Mermaid CLI：把 Agent 流程图源文件放进可重复的构建流程

在线编辑器适合讨论流程，仓库里的构建则需要相同源文件和固定依赖。Mermaid CLI 提供 mmdc 命令，可以将 .mmd 文本导出为图像。本文介绍如何安装、导出和检查失败，不再次把 Mermaid Live Editor 当作新资源收录，也不声称已经生成或验收图片。

为什么需要 CLI，而不是只保存截图？

截图只能显示结果，无法清楚解释审批边何时被删除、重试出口怎样改变。文本图可以与代码一起 diff，让评审者关注流程变更。CLI 则把人工点击导出变成可记录的命令，方便在修改 Agent 编排后更新文档。

先在 aiKit 的 Mermaid Live Editor讨论流程，再把源文本纳入仓库即可。这里的差异是本地构建和版本管理，不是编辑器的第二篇基础介绍；权限语义仍需要人和代码测试共同检查。

从哪里下载，安装前需要准备什么？

官方下载与使用说明见 mermaid-js/mermaid-cli，npm 包名是 @mermaid-js/mermaid-cli，命令名为 mmdc。仓库采用 MIT 许可；打包分发时还要处理浏览器、字体与其他依赖各自的许可，不能只看顶层许可证。

准备 Node.js/npm 和能运行无头 Chromium 的环境。macOS、Windows、Linux 的浏览器依赖不同，受限容器尤其需要查官方故障说明。本文以 Node.js 24 环境作为练习选择；执行前读取目标包的 engines，不把该选择误称为唯一最低版本。

怎样进行项目内安装并记录依赖？

在独立练习目录逐行执行以下命令。先查看引擎要求，再安装，避免全局命令与项目依赖版本不一致。安装阶段可能下载浏览器，网络代理、企业证书或沙箱限制可能导致失败；应保留错误日志，而非跳过浏览器校验。

mkdir mermaid-cli-lab
cd mermaid-cli-lab
node --version
npm view @mermaid-js/mermaid-cli engines --json
npm init -y
npm install --save-dev --save-exact @mermaid-js/mermaid-cli
npx --no-install mmdc --version

macOS/Linux 可用常见终端，Windows 可用 PowerShell 逐行运行。提交经过验证的锁文件，后续环境用 npm ci 复装；固定版本只是复现基础，字体和浏览器差异仍会影响最终布局。

如何完成第一次导出并判断结果？

在该目录创建 agent.mmd，内容如下。图只表达“读取、检查、审核”的简化路径，不代表实际系统具有审批能力。

flowchart LR
  Read["读取输入"] --> Check{"字段有效？"}
  Check -->|是| Review["人工审核"]
  Check -->|否| Reject["拒绝并记录"]

按 CLI 官方用法执行：

npx --no-install mmdc -i agent.mmd -o agent.svg

检查退出状态、文件是否存在，再用浏览器查看文字、箭头和标签是否完整。存在非空 SVG 不代表视觉验收通过；中文缺字、文字溢出或边交叉，都需要人工确认。对外展示前还应按目标站点的 SVG 安全策略处理，不直接内联陌生人提供的 SVG。

常见失败应该如何排查？

找不到 mmdc 时，先在当前目录确认依赖安装完整，不混用另一个目录的全局包。Chromium 无法启动时，区分浏览器下载失败与操作系统依赖不足；不要把 --no-sandbox 当作通用修复。生产 CI 应保留隔离措施，并使用受控输入。

中文显示异常时检查字体安装与 CI 字体环境；图能导出但布局变化，检查依赖、浏览器和字体版本。将这些环境信息与团队 AI 配置一起纳入运行说明，比只记录一条 npm 命令更有复现价值。

何时放进 CI，什么时候保持人工导出？

先在本地证明一个正例能导出、一个语法错误能阻止构建，再接到文档流水线。CI 只处理仓库内经审查的图，限制文件大小、渲染时间和权限。用固定文件名覆盖产物前，应确认不会误写原始材料；不要通过构建自动发布到线上。

偶尔画一张图，在线编辑器已足够；文档频繁随代码变化时，CLI 才值得维护。生产级 Agent 工程原则可帮助决定哪些状态必须画出，但图像构建测试不替代 Agent 行为测试。本篇没有安装 CLI 或渲染图像，以上均为可执行步骤和预期验收项。

FAQ

问：Mermaid CLI 就是在线编辑器吗？ 答：不是，它是将源文本转换为图像的命令行资源。

问：锁定 npm 版本就能保证像素完全一致吗？ 答：不能，浏览器、字体和系统环境也会影响结果。

问：Chromium 失败时应直接禁用沙箱吗？ 答：不应，先排查依赖并保留合适的隔离边界。

参考来源

核查日期：2026-10-06。导出未执行，未生成任何图片。

• Mermaid CLI 安装、命令与许可
• CLI 包配置与运行时声明
• Mermaid 流程图语法