企业官网建设流程全解析

ThinkRail 可视化扩展实战：AI 直接在聊天里画 Mermaid 架构图与方案对比

【免费下载链接】thinkrailVibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need项目地址: https://gitcode.com/GitHub_Trending/th/thinkrail

如果你用过 AI 编程助手，多半见过这样的场面：AI 解释架构时甩出一堆 ASCII 字符画，对比方案时丢下一张挤在一起的 Markdown 表格。ThinkRail 的可视化扩展（visualize工具）正是为解决这个问题而生——它让 AI 在聊天流里直接渲染 Mermaid 架构图、方案对比卡片和文件预览，让“看图说话”成为日常。这篇文章带你快速上手这套能力：它能做什么、怎么触发、背后如何校验与渲染。

1️⃣ 为什么 AI 编程需要"可视化"

在 ThinkRail 里，AI（pi引擎）不是只会在终端里打字，它内置了一组"超越 shell"的工具。其中visualize是面向沟通的工具：当它要解释架构、梳理流程、比较技术选型或提议 UI 改动时，会主动"掏出一张图"，而不是画字符画。好处很直接：

• 架构图：SVG 矢量渲染，可缩放、可全屏，随主题换色；
• 方案对比：每个选项一张卡片，优点 / 缺点列表化，推荐项高亮；
• 文件预览：HTML 原型图、Markdown、SVG 等直接在聊天里渲染，还能做"前后对比"。

官方说明见 pi-extensions/visualize/README.md。

2️⃣ visualize 工具一览：三种可视化一次看懂

visualize只有三种type，参数定义在 pi-extensions/visualize/src/schema.ts：

你不需要手写这些调用——只要在聊天里问"帮我画一下这个模块的架构图"或"REST 和 GraphQL 怎么选"，AI 会自己选择正确的type。

3️⃣ Mermaid 架构图：全屏、缩放与主题同步

这是新手最容易上头的功能。type: "diagram"的结果会渲染成一张精致的 SVG 卡片（thinkrail-extensions/visualize/web/DiagramCard.tsx），核心渲染器是 thinkrail-extensions/visualize/web/MermaidView.tsx，它带来几个实用细节：

• 懒加载：mermaid库只在真正画图时载入，不拖慢启动；
• 全屏 + 缩放：点"Full screen"打开全屏查看，支持滚轮 / 触控板缩放、拖拽平移、一键重置（100% 指示器）；
• 主题同步：切换深色 / 浅色主题后，节点配色自动跟随应用 CSS 变量重绘，聊天消息里的 mermaid 代码块同样生效；
• 失败兜底：渲染失败时显示错误和纯文本源码，绝不会白屏。

💡 小提示：聊天中 AI 直接写的 ```mermaid 代码块和visualize工具产出的图共用同一套渲染器，观感完全一致。

4️⃣ 方案对比卡片：优缺点一目了然

技术选型时，一句"我推荐 REST"远不如一张对比卡直观。type: "comparison"会把每个选项渲染成独立卡片（thinkrail-extensions/visualize/web/ComparisonCard.tsx）：

• 名称 + 一两句描述；
• ✅ 优点列表 / ❌ 缺点列表，逐条对照；
• 被 AI 认可的唯一选项打上高亮的Recommended徽章；
• 每个选项还可内嵌一张 mermaid 小图（比如两种方案的调用链路图）。

端到端测试里就有一个经典例子：REST vs GraphQL，REST 带缓存、客户端简单但多次往返，GraphQL 字段精确但 Resolver 复杂，最终 REST 被标记为推荐——完整断言见 e2e/visualize.spec.ts。

5️⃣ 文件预览：HTML 原型图 + 前后对比

type: "file"是"提案 UI 改动"的利器。它不内嵌内容，而是引用工作区真实文件，交给与 diff 评审相同的渲染器绘制：

• 工具指引 AI 把 UI 原型写成自包含 HTML（内联 CSS、data:图片），放在被 gitignore 的.thinkrail/context/mockups/目录，不会污染你的项目；
• 卡片显示文件当前内容：AI 继续改 mockup 时，聊天里所有引用它的卡片实时刷新；想保留旧版，就把它复制一份作为before，得到 before/after 双栏对比；
• 卡片工具栏支持Open in tab（在编辑器标签页打开，before/after 则打开对比标签页）和Full screen；HTML 预览还能切换手机 / 桌面视口；
• 更妙的是：你可以在预览上圈选、写评审意见，一键发到当前聊天，AI 按你的批注继续改——评审意见锚定在真实文件上，后续编辑全程可追溯。

相关设计决策见 thinkrail-extensions/visualize/SPEC.md。

6️⃣ 严格校验：语法写错，AI 自己会改

新手常担心：AI 写错 Mermaid 语法怎么办？ThinkRail 在这条链路上做了双重保障：

• 服务端严格校验：ThinkRail 通过validateMermaid注入缝，用与网页渲染器同一版本的mermaid.parse做语法检查（实现见 thinkrail-extensions/visualize/server/mermaid.ts），并借助linkedom提供解析所需的 DOM 环境；
• 错误即指引：校验失败的工具结果会指明出错字段（如mermaid或options[N].mermaid），并要求模型"改正后重试"，AI 通常下一轮就输出修正版；
• 渲染端兜底：即使历史消息里的图渲染失败，也优雅降级为纯源码展示。

而在纯终端场景（vanilla pi），同一工具退化为用lovely-mermaid引擎直接画 Unicode 框线图，语法宽校验 + Markdown 兜底，保证"处处可读"。

7️⃣ 如何开启与关闭：Settings → Extensions

可视化扩展随 ThinkRail 默认启用，无需安装。如果你暂时用不上，路径很短：

1. 打开Settings（右上角齿轮）；
2. 进入Extensions，这里列出 AI 获得的所有 ThinkRail 扩展，逐项开关；
3. 关闭visualize后，AI 将不再在聊天里画图，其余能力不受影响。

8️⃣ 关键源码位置（供进阶阅读）

写在最后

ThinkRail 的visualize扩展把"AI 解释复杂事物"从文本升级成了图像：Mermaid 架构图负责讲清结构，对比卡片负责讲清取舍，文件预览负责讲清"改完之后长这样"。下次当 AI 开始长篇大论时，不妨直接回一句"画出来给我看"——它会自己掏出工具，把图送到你的聊天里。

【免费下载链接】thinkrailVibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need项目地址: https://gitcode.com/GitHub_Trending/th/thinkrail