Mermaid Chart 的 VS Code 扩展如何通过 AI Chat Participant 生成图表？

Mermaid Chart 官方 VS Code 扩展可以在 GitHub Copilot Chat 中注册 @mermaid-chart 参与者，让开发者用自然语言或选定的源码生成 Mermaid 图表。完整流程是安装扩展与 GitHub Copilot、登录 Mermaid 账户、在聊天中调用参与者、审查所选上下文、生成 Mermaid 代码并在本地预览，最后把结果保存为 .mmd 或 .mermaid 文件。AI 生成只是初稿，源码范围、图表语义和数据外发都需要主动核对。

使用前需要满足哪些条件

• 安装较新的 Visual Studio Code。
• 安装发布者为 Mermaid Chart 的官方 Mermaid 扩展。
• 安装并可使用 GitHub Copilot Chat。
• 准备 Mermaid 账户并在扩展中登录。
• 打开有写入权限的工作区。
• 对发送给语言模型的源码和需求文本拥有授权。

Marketplace 当前说明，从扩展 2.7.7 起，创建、预览、AI 制图、云同步、Improve Diagram 和 Sync 审查都受登录限制。如果只需要不登录的本地预览，应安装其另行提供的 Mermaid Preview 扩展；两者不是同一个产品入口。

安装并登录扩展

1. 在 VS Code 扩展面板搜索 Mermaid。
2. 核对发布者和扩展标识，安装官方扩展。
3. 同时确认 GitHub Copilot 扩展已安装且 Chat 可用。
4. 点击活动栏中的 Mermaid 图标。
5. 选择登录，通过浏览器完成 OAuth。
6. 远程开发或 OAuth 回调不可用时，可在 Mermaid 账户设置中生成手动令牌并粘贴到扩展。
7. 返回 VS Code，确认侧边栏能够读取账户中的项目和图表。

手动令牌相当于账户凭据，不应写入项目文件、聊天消息、终端历史或截图。怀疑泄露时应立即吊销并重新生成。

AI Chat Participant 是什么

Chat Participant 是 Copilot Chat 中的专用参与者。输入 @mermaid-chart 后，后续请求由 Mermaid 扩展提供的能力处理。它可以结合自然语言和显式附加的文件，生成 Mermaid 语法并展示预览，而不是简单返回一张不可编辑图片。

基础调用可以写成：

@mermaid-chart 生成一个用户登录流程图，包含密码错误、账户锁定、双因素验证和登录成功分支。

如果目标是从代码生成图表，应使用专门命令：

@mermaid-chart /generate_diagram_from_code

该处理器会让用户选择要分析的代码文件，再选择合适的图表类型，例如流程图、类图、时序图、状态图、ER 图、架构图或思维导图。不要默认整个仓库都会被准确理解，也不要一次选择与问题无关的大量文件。

怎样用自然语言生成第一张图

1. 打开 Copilot Chat。
2. 输入 @mermaid-chart。
3. 写明图表类型和目标。
4. 列出参与者、组件或状态。
5. 说明连接、调用顺序、分支和异常。
6. 提交后检查生成的 Mermaid 代码和预览。
7. 把代码保存到工作区文件。

例如，生成部署时序图时可以使用下面的提示：

@mermaid-chart 生成 Mermaid 时序图。
参与者包括开发者、GitHub Actions、镜像仓库、Kubernetes API 和应用 Pod。
开发者推送标签后触发工作流，工作流构建并推送镜像，然后更新 Deployment。
Kubernetes 创建新 Pod 并执行健康检查。
使用 alt 分支表示健康检查成功与失败，失败时回滚到旧版本。

明确参与者和消息顺序，通常比“画一个部署架构图”更容易得到可验证结果。

如何从当前代码文件生成图表

扩展默认会在受支持的代码文件底部显示 CodeLens，包括 Generate Mermaid Diagram 和 Open Chat 两个入口。受支持的示例语言包括 TypeScript、JavaScript、Python、Java、Go、Rust 和 C#。

1. 打开要分析的源码文件。
2. 点击文件底部的 Generate Mermaid Diagram。
3. 或从命令面板运行 Mermaid: Generate Diagram from Code。
4. 在选择器中只勾选与目标流程相关的文件。
5. 选择流程图、类图、时序图或其他类型。
6. 等待 AI 分析并生成 Mermaid 语法。
7. 逐项核对类、函数、调用和异常路径。

如果不希望在源文件中看到 CodeLens，可以在设置中关闭 Mermaid 的 Show Generate Diagram Code Lens 选项。关闭只影响入口显示，不会删除已有图表。

不同代码场景对应哪些命令

扩展提供多种专用命令。命令名是工作流入口，不代表输出一定正确：

• /generate_diagram_from_code：从所选源码生成多种 Mermaid 图。
• /generate_er_diagram：从模型、Schema 或相关代码生成实体关系图。
• /generate_docker_diagram：分析 Dockerfile、Compose 或 Stack 文件。
• /generate_cloud_architecture_diagram：分析选定的云配置文件。
• /generate_execution_sequence：从模块化代码生成执行时序图。
• /generate_c4_topdown_architecture：生成自顶向下的 C4 架构视图。
• /generate_dependency_diagram：分析依赖清单及其状态。
• /analyze_code_ownership：结合 Git 历史生成代码归属图。

专用命令可能读取不同类型的信息。例如代码归属依赖 Git 历史，依赖图可能涉及版本和漏洞信息，Docker 图会读取容器配置。调用前应先明确允许访问的数据范围。

怎样选择图表类型

• 要说明控制流和判断条件，选择流程图。
• 要说明对象之间按时间发生的调用，选择时序图。
• 要说明类型、属性、方法与继承，选择类图。
• 要说明数据库实体与基数，选择 ER 图。
• 要说明服务边界与层级，选择 Architecture 或 C4 图。
• 要说明生命周期事件和迁移，选择状态图。
• 要说明任务日期和依赖，选择甘特图。

同一批源码可以生成不同图表。不要把时序、部署、类关系和业务状态全部塞进一张图；按阅读目的拆分，评审成本更低。

如何预览和保存生成结果

扩展支持 .mmd 与 .mermaid 文件的本地编辑和并排实时预览，也能识别 Markdown 中的 Mermaid 代码块。文本变化会反映到预览，语法错误会标出可能出错的行。

建议把 Mermaid 源码作为真源提交到版本控制：

docs/
  architecture/
    checkout-sequence.mmd
    deployment-flow.mmd
  generated/
    checkout-sequence.svg

源码便于审查变更，SVG 或 PNG 作为交付产物。扩展支持平移、缩放、主题切换以及 SVG、PNG 导出，还可以选择自动、浅色、深色或自定义背景。

生成后的代码应该怎样检查

预览成功只证明 Mermaid 语法可以渲染，不代表 AI 理解了真实代码。至少检查以下内容：

1. 生成图引用的文件确实属于目标功能。
2. 函数调用方向与源码一致。
3. 同步、异步和事件驱动关系没有混淆。
4. 异常、超时、重试和回滚路径没有遗漏。
5. 类的继承、组合和依赖关系没有颠倒。
6. 数据库基数和可空性符合 Schema。
7. 图中没有不存在的组件或模型推测。

可以在图旁记录源文件和提交版本，让读者知道图表对应哪个代码状态。重要架构图还应由模块负责人审核。

AI 修复和 Improve Diagram 有什么区别

Repair Diagram 面向语法错误。扩展检测到 Mermaid 无法渲染时，可以调用 AI 提出修复，并在应用前显示差异；该功能使用 Mermaid 账户中的 AI 积分。

Improve Diagram 面向已经可渲染的图，生成两种建议：一种偏布局和分组，另一种偏样式。侧边栏会提供模型选择、刷新、取消和差异预览。该能力通过 VS Code Language Model API 使用受支持的聊天扩展，并会请求语言模型访问权限。

两类操作都不应盲目接受。语法修复可能改变标签或连接，布局优化也可能重组子图。应用前先看代码差异和双图预览。

智能重新生成如何工作

从源文件创建图表后，扩展可以记录关联。当源码变化时，Regenerate Diagram 会建议重新生成并展示差异。预提交功能还会检查已暂存文件是否与图表关联，并在提交前提示更新。

该提示是非阻塞的，不会阻止 Git 提交。重新生成后的结果应在 Review Mermaid Sync 中接受或拒绝。关闭审查界面不等于回滚，文件变化仍可能留在工作区，因此最终要以 git diff 和暂存区内容为准。

账户、Copilot 和 AI 积分的关系

Mermaid 扩展登录用于账户、云同步和部分 AI 能力；GitHub Copilot 提供 Chat Participant 的聊天环境；Repair Diagram 等功能还会消耗 Mermaid AI 积分。Improve Diagram 则使用 VS Code Language Model API 中可用的聊天模型。它们是不同的授权和计费边界。

遇到功能不可用时，不要只检查一个登录状态。应分别确认 Mermaid 账户、Copilot 订阅或授权、可用聊天模型、语言模型权限和 Mermaid AI 积分。

源码和分析数据会发送到哪里

Marketplace 的隐私说明称，扩展会把 VS Code 机器标识、激活与登录事件、AI 功能使用事件、错误报告和图表类型等分析信息发送到 Mermaid 服务，且当前不能在扩展设置中关闭分析。说明同时称该分析通道不发送个人文件、图表内容或源码。

这不等于所有 AI 操作都完全本地。Chat Participant、从代码生成图表和 Improve Diagram 必须让语言模型处理用户明确提供或选择的上下文；扩展文档也说明 AI 功能使用时会产生网络请求。分析遥测与 AI 推理是两个不同数据通道，评估隐私时必须分别审查。

• 只选择生成图表所需的最少文件。
• 不要提交密钥、证书、生产配置和真实客户数据。
• 检查 Copilot 与 Mermaid 服务的组织策略。
• 注意生成的图表本身可能暴露内部架构。
• 受监管代码应先取得安全或法务批准。

常见问题如何排查

输入参与者后没有响应

确认 GitHub Copilot Chat 已安装并登录，Mermaid 扩展已启用，参与者拼写为 @mermaid-chart。重新加载 VS Code 窗口后再次检查。

扩展提示必须登录

这是当前官方扩展的预期行为。通过活动栏完成 OAuth，远程环境可改用手动令牌。只需离线预览时，考虑使用官方说明中的独立 Mermaid Preview 扩展。

代码文件底部没有生成入口

确认语言属于支持范围，文件已保存，Show Generate Diagram Code Lens 设置没有关闭。也可以从命令面板直接运行生成命令。

AI 选择了错误的图表类型

在提示中明确类型，或使用从代码生成处理器提供的类型选择。复杂需求拆成多张目标单一的图。

生成图遗漏跨文件调用

重新运行并补选入口、接口、实现和配置文件。不要让 AI 猜测未提供的模块；仍有遗漏时手工补充 Mermaid 代码。

预览正常但导出背景不合适

打开导出设置，选择浅色、深色或自定义背景。用于文档时同时检查透明背景和目标主题的对比度。

AI 修复按钮不可用

检查 Mermaid 账户是否有效、是否还有 AI 积分，以及网络和登录令牌是否正常。Improve Diagram 还需要可用聊天扩展和语言模型权限。

团队落地建议

1. 把图表源码放在固定文档目录。
2. 在文件头或邻近文档记录关联源码。
3. 生成时采用最小文件选择原则。
4. 把 Mermaid 变更纳入代码审查。
5. 由业务或模块负责人核对语义。
6. 统一 Mermaid 版本、主题和导出规范。
7. 定期检查 AI 权限、积分和数据策略。

总结

Mermaid Chart VS Code 扩展通过 @mermaid-chart 接入 GitHub Copilot Chat，可以从自然语言或显式选择的源码生成可编辑 Mermaid 图表。使用前需要 Mermaid 账户和 Copilot，生成后应保存源码、检查关系并审查网络数据边界。专用命令适合 ER、Docker、云架构、时序、C4、依赖和代码归属等场景，但命令输出仍是需要评审的 AI 草稿。把文件选择、差异审查和版本控制纳入流程，才能让图表长期跟得上代码。