AI编码代理与Mermaid图渲染规范：CLI、AGENTS.md与CI自动化实践

先解释一下背景。最近在开源圈有个讨论挺有意思某些带着“open code”气质的自主 OSS 创作集体代码没提交多少PR 描述和文档里反而先铺满了 Mermaid 图。Dex Horthy 对这件事的调侃落点不是“AI 能不能写代码”而是“AI 生成的图渲染风格是不是已经变成另一种噪音”。这种调侃并不是无意义的段子它背后对应一个真实工程问题当 opencode 这类终端编码代理被用在 autonomous OSS 协作中大模型非常容易把“梳理架构”直接转化成“生成一张 Mermaid 图”。问题是普通同学在网页里看到图会觉得很直观一旦要维护、批处理、做人机 Code Review就会发现图没有源文件、渲染版本不一致、CI 根本没法验证。所以这篇文章不打算停留在吐槽而是给一套可复制的技术实践用 Mermaid CLI 来规范图的编译和渲染用 AGENTS.md 约束 AI 代理的制图行为再用 GitHub Actions 把“Mermaid 图能不能渲染”变成自动检查项。文中会讲清安装方式、核心命令、批量渲染方法、常见踩坑点并在最后给出适合开源协作的 Mermaid 文档规范建议。1. 调侃背后的真实问题AI 编码代理为什么偏爱 Mermaid 图先明确一下opencode 并不是某一个固定产品的专属名词而是目前 AI 编码代理这一类工具的代称。它可以是开源社区里的 opencode、Codex CLI也可以是其他具备“读懂仓库、改代码、跑命令、提 PR”能力的终端 Agent。这类工具接入 OSS 项目后理想状态是自动完成小任务让维护者只做 Review。但在实际使用中大模型分析完一个仓库后最爱输出的内容往往不是严格的测试代码而是“解释性产物”。解释性产物里Mermaid 又是优先级最高的一种因为它的表达成本和理解成本都低大模型不需要关系真实画布坐标只要生成flowchart LR这类语义化文本。Mermaid 代码可以直接嵌在 Markdown 里GitHub 默认就能渲染。描述模块依赖关系时图比大段文字更紧凑。对模型来说让“节点 A 到节点 B”比写一段准确的进程通信代码更容易。如果是单个开发者自己玩多画几张图问题不大。当 collaborative 变成 autonomous OSS 集体行为时问题就会放大多个 Agent 同时改仓库每次提交都生成一张结构图却没有规定源文件放哪里没有渲染命令也没有版本更新的校验。最后仓库里的 Mermaid 图会像没有单元测试的代码一样无法被自动化保护。因此真正值得讨论的不是“Mermaid 图该不该用”而是“AI 生成的 Mermaid 图应该用什么风格渲染、如何批量验证、如何避免图文档失控”。2. 核心能力速览与适用边界下面把“AI 编码代理 Mermaid 渲染”当成一套工作流来评估核心能力如下。能力项说明项目类型opencode 类 AI 编码代理 Mermaid CLI 文档渲染工作流主要功能自动分析代码、生成 Mermaid 源文件、渲染为 SVG/PNG、PR 阶段自动校验硬件需求不依赖 GPU也不需要特定显卡占用的是 CPU、内存和模型 API Token操作系统Linux、macOS、Windows 的 WSL 环境均可跑 CLI启动方式命令行启动、GitHub Actions 自动触发、Mermaid Live Editor 在线调试是否支持 APIMermaid 本身不是 HTTP REST 服务但可以通过脚本包装成内部调用接口是否支持批量支持最常见的做法是对docs/diagrams/*.mmd目录做循环渲染适合场景OSS 协作中的架构文档、AI Agent 任务拆解、PR 描述自动配图、代码评审辅助适用边界要单独说清楚。这套工作流适合小到中型开源项目尤其是团队已经接收 AI Agent 提交的场景。它能解决文档图“无法维护、无法验证”的问题但它不能替代“需求判断”也无法阻止 Agent 画出一张“看起来合理、实际已过期”的架构图。安全方面也要提醒如果你的 Agent 准备在公开仓库里生成 Mermaid 图图中所有节点和标签都要避免出现内网地址、密钥、未公开业务细节。涉及第三方开源组件时复制架构拓扑不代表复制代码但采用别人的图源文件时仍需确认许可证是否允许再分发。涉及人脸、用户数据、敏感系统拓扑图的场景必须经过授权并脱敏。3. 环境准备与前置条件这一套流程不需要 GPU对显卡没有要求重点是把 Node.js 和渲染依赖装好。建议先准备以下环境Linux / macOS / Windows WSLWindows 原生环境也可以但路径和字体问题会多一些。Node.js 18 或更高版本。建议直接用 20 LTS兼容性更好。最低版本以mermaid-js/mermaid-cli官方要求为准。npm一般随 Node.js 一起安装。Git用来管理源文件和执行 Agent 提交。Docker可选。如果你不想在宿主机里装 Chromium可以用容器跑 Mermaid CLI。GitHub CLI可选。如果要做 open code review 流程中的 PR 操作会比较方便。一个可用的 Mermaid 调试入口。可以是 Mermaid Live Editor 网页也可以是本地 CLI。磁盘空间不用太担心。Mermaid CLI 本身不大但它会调用 Puppeteer 下载 ChromiumChromium 相关文件可能占用几百 MB。如果你在服务器或 CI 容器里跑至少预留 1GB 磁盘空间比较稳妥。内存方面Mermaid CLI 单次渲染通常不需要很大的机器常见 2C4G 的云服务器足够跑单条渲染。重点是不要同时开很多个 Mermaid 进程否则 Chromium 并发会把内存吃满。具体内存需求要看图节点数量和字体加载情况建议第一次跑的时候看下ps或任务管理器而不是凭经验直接并发。4. 安装 Mermaid CLI 与第一次渲染Mermaid 的常用渲染路径有三种网页在线编辑器、Markdown 原生渲染、命令行渲染。网页调试适合验证语法但开源协作更看重的批量能力来自 CLI。全局安装 Mermaid CLI 的命令如下npm install -g mermaid-js/mermaid-cli安装完成后先确认命令是否可用mmdc --version如果你不想全局安装也可以借助npx临时调用npx -y mermaid-js/mermaid-cli mmdc --version第一次在 Linux 容器或 CI 环境里运行时很常见的问题是 Puppeteer 找不到 Chrome。这种情况需要先安装 Chrome 浏览器或者生成一个 Puppeteer 配置文件。推荐在项目根目录放一份.puppeteer.json{ args: [--no-sandbox, --disable-dev-shm-usage] }--no-sandbox主要用于容器和 CI 环境本地开发机不建议随便关沙箱。--disable-dev-shm-usage可以避免共享内存不足导致 Chromium 崩溃。现在创建一个测试目录和 Mermaid 源文件mkdir -p docs/diagrams把下面的内容保存为docs/diagrams/architecture.mmd。这是一个简化版架构图演示的是常见 Web 服务依赖关系flowchart LR User[用户] -- GW[API Gateway] GW -- Auth[Auth Service] GW -- Biz[Biz Service] Biz -- DB[(PostgreSQL)] Biz -- Cache[(Redis)]然后执行渲染mmdc -i docs/diagrams/architecture.mmd -o docs/diagrams/architecture.svg -p .puppeteer.json如果命令没有报错docs/diagrams/architecture.svg就会生成。用浏览器打开 SVG能看到节点和箭头。第一次渲染建议多做一步把节点标题改成中文确认系统字体能正确显示避免后续文档出现中文乱码。如果在 Ubuntu/Debian 上渲染中文出现方块字先安装中文字体sudo apt update sudo apt install -y fonts-noto-cjk安装后重新执行mmdc基本能解决中文乱码。5. 约束 AI 生成风格AGENTS.md 示例Mermaid CLI 能解决“图能不能渲染”的问题但解决不了“Agent 是否该画这么多图”的问题。要想让 opencode 类工具输出稳定风格不应该靠每次对话临时叮嘱而应该把规则放进项目根目录的AGENTS.md。下面是一个可以直接复制到仓库里的规则示例。不同 AI Agent 对AGENTS.md的读取方式略有差异但绝大多数支持项目级上下文的编码代理都会主动读取这个文件。## Mermaid 图规范 1. 只有在需要表达模块间关系时才建议生成 Mermaid 图。 2. 新图源文件统一放在 docs/diagrams/ 目录文件名必须能表示内容例如 architecture.mmd、workflow.mmd。 3. 默认使用 flowchart LR 或 flowchart TD不随意使用复杂图形类型。 4. 单张图节点数量建议控制在 12 个以内。超过 12 个节点时先考虑拆分图。 5. 节点命名使用英文变量标签可以使用中文。例如 User[用户]。 6. 在提交 PR 时必须同时提交 .mmd 源文件和渲染后的 SVG/PNG 文件。 7. 修改 Mermaid 源文件后必须执行以下命令验证渲染 mmdc -i 文件 -o 输出文件 -p .puppeteer.json 8. 禁止把内网地址、密钥、未公开基础设施信息写入节点标签。除了静态规则也可以在 prompt 里要求 Agent 在生成图之前先说明绘图目的。比如请分析仓库中支付模块的代码路径如果模块依赖数超过 3 个就在 docs/diagrams/payment-flow.mmd 中生成一张 flowchart 图。先不要直接在 PR 描述里贴长图先确认 .mmd 源文件已经放好并完成渲染验证。这套规则能够缓解“Mermaid 图无限膨胀”的问题。因为原图源文件和渲染输出被当作代码一样管理任何人看到图时都能找到对应源文件也能重新跑一次渲染。6. 批量渲染与 API 集成思路当目录里的.mmd文件逐步增多一条条命令行渲染会很低效。常见的做法是写一个脚本批量渲染整个目录。在项目根目录创建scripts/render-mermaid.sh#!/usr/bin/env bash set -euo pipefail diagram_dir${1:-docs/diagrams} puppeteer_config${2:-.puppeteer.json} for f in $diagram_dir/*.mmd; do [ -e $f ] || continue out${f%.mmd}.svg echo Rendering $f - $out mmdc -i $f -o $out -p $puppeteer_config done echo All mermaid diagrams rendered successfully.然后给脚本执行权限chmod x scripts/render-mermaid.sh运行./scripts/render-mermaid.sh如果你没有全局安装 Mermaid CLI只是通过项目本地安装可以把脚本里的mmdc改成npx -y mermaid-js/mermaid-cli mmdc。Mermaid CLI 本身不是标准 HTTP API但你可以把批量脚本封装成内部的“图渲染服务”。最简单的做法是用 Python 的subprocess调用同一套 CLIimport pathlib import subprocess diagram_dir pathlib.Path(docs/diagrams) puppeteer_config pathlib.Path(.puppeteer.json) for mmd_file in diagram_dir.glob(*.mmd): svg_file mmd_file.with_suffix(.svg) print(fRendering {mmd_file} - {svg_file}) subprocess.run( [ mmdc, -i, str(mmd_file), -o, str(svg_file), -p, str(puppeteer_config), ], checkTrue, )如果你要接入现有业务可以用 FastAPI 或 Express 把这个 Python 脚本包成/render接口。请求体包含待渲染文件的路径或 Mermaid 源码后端调用 CLI 后返回渲染产物。这里的接口参数需要根据项目