Mermaid 图表生成与渲染
依赖
- •Node.js（已安装）
- •@mermaid-js/mermaid-cli（通过 npx 自动安装）
核心工具
- •渲染脚本：
scripts/render.sh - •主题配置：
scripts/mermaid.json（蓝色专业主题，支持中文）
工作流程
1. 扫描占位符
在目标 markdown 文件中查找 【此处插入XX图】 格式的占位符。
每个占位符对应一张需要生成的图表。
2. 分析上下文
对每个占位符，分析其周围内容以确定图表内容：
- •占位符后的 ASCII 图：最重要的参考。如果占位符下方有 ``` 代码块中的 ASCII art， 应将其内容忠实转换为 Mermaid 语法。ASCII 图定义了图表的结构和层次关系。
- •章节标题：确定图表主题
- •前后文字描述：补充图表细节
3. 编写 Mermaid 代码
根据上下文编写 .mmd 文件。Mermaid 代码要求：
- •忠实于 ASCII 图内容：不添加 ASCII 图中没有的元素，不遗漏已有的元素
- •中文标签：所有节点文字使用中文
- •层次清晰：用 subgraph 表达分层/分组关系
- •配色通过主题控制：不在 mmd 文件中硬编码颜色（除非特别需要区分）
图表类型对照
| 占位符内容 | Mermaid 图类型 | 说明 |
|---|---|---|
| XX架构图 | graph TD | 分层架构，用 subgraph 表达层 |
| XX拓扑图 | graph TD | 网络拓扑，用 subgraph 表达区域 |
| XX流程图 | graph TD | 流程图，用菱形表达判断 |
| ER图 | erDiagram | 实体关系图 |
| 甘特图 | gantt | 项目进度甘特图 |
| 组织架构图 | graph TD | 树形组织结构 |
| 对接/集成架构图 | graph LR | 左右布局，表达系统间关系 |
| 方法论/示意图 | graph LR | 流程或阶段示意 |
Mermaid 编写注意事项
- •节点 ID 用英文，显示标签用中文括号包裹：
A[系统总体架构] - •subgraph 标题用中文：
subgraph 基础设施层 - •避免特殊字符：标签中避免
(){}[]等 mermaid 语法字符，用全角替代 - •连接线标签简短：
A -->|数据同步| B - •gantt 图日期格式：
YYYY-MM-DD或相对周数 - •erDiagram 关系：
PATIENT ||--o{ NURSING_RECORD : has - •节点文字过长时换行：在引号标签中换行无效，应缩短文字或拆分节点
4. 渲染为 PNG
将 .mmd 文件渲染为 PNG：
bash
# 单个文件 bash scripts/render.sh input.mmd output.png # 自定义宽度和缩放 bash scripts/render.sh input.mmd output.png 1400 2
参数说明：
- •
width：图片宽度像素（默认 1200，复杂图可设 1400-1800） - •
scale：缩放因子（默认 2，适合打印；屏幕查看可设 1）
渲染输出的 PNG 保存到目标 markdown 文件的同目录。
5. 替换占位符
将 markdown 中的占位符行替换为图片引用：
替换前：
code
【此处插入系统总体架构图】
替换后：
code
重要：保留 ASCII 图代码块。 占位符替换后，其下方的 ASCII 代码块不删除—— 在 Word 排版时可以选择保留或删除，但在 markdown 阶段保留作为参考。
6. 图片文件命名
统一命名格式：diagram-{描述}.png
例：
- •
diagram-系统总体架构图.png - •
diagram-项目甘特图.png - •
diagram-故障处理流程图.png
批量处理
当用户要求处理某个文件的所有图表占位符时：
- •读取文件，提取所有
【此处插入XX图】占位符列表 - •逐个处理：分析上下文 → 编写 mmd → 渲染 → 替换
- •汇报处理结果
当用户要求处理所有文件时：
- •扫描
响应文件/目录下所有 md 文件中的占位符 - •按文件分组，逐文件处理
- •跳过非图表类占位符（如
【此处插入XX扫描件】、【此处插入XX功能截图】）
跳过规则
以下占位符不处理（需要真实截图/扫描件，不是可生成的图表）：
- •
【此处插入XX扫描件】— 证书/合同扫描件 - •
【此处插入XX功能截图】— 系统功能截图（需真实系统） - •
【此处插入XX查询截图】— 网站查询截图 - •
【此处插入XX效果示意图】— 需要 UI mockup（可另行处理）
典型调用示例
code
用户：把技术方案里的图画出来 操作： 1. 读取 07-技术方案.md 2. 找到 8 个图表占位符 3. 逐个生成 mermaid → 渲染 PNG → 替换占位符 4. 汇报：8 张图已生成 用户：画一个项目甘特图 操作： 1. 读取上下文中的进度信息 2. 编写 gantt 类型 mermaid 3. 渲染 PNG 4. 插入到指定位置
渲染失败排查
- •中文乱码：检查 mermaid.json 中 fontFamily 是否包含中文字体
- •图表溢出：减少节点数量或增加 width 参数
- •语法错误：先用
npx @mermaid-js/mermaid-cli -i file.mmd -o /dev/null验证语法 - •节点 ID 冲突：不同 subgraph 中的节点 ID 不能重复
完成状态
图表生成完成后，输出以下结构化状态摘要：
code
--- BID-MERMAID-DIAGRAMS COMPLETE ---
处理文件数: {N}
生成图表数: {N}
跳过占位符: {N}（非图表类）
图表清单: {diagram-XX.png, diagram-YY.png, ...}
输出目录: 响应文件/
状态: SUCCESS
--- END ---