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 编写注意事项

1. 节点 ID 用英文，显示标签用中文括号包裹：A[系统总体架构]
2. subgraph 标题用中文：subgraph 基础设施层
3. 避免特殊字符：标签中避免 () {} [] 等 mermaid 语法字符，用全角替代
4. 连接线标签简短：A -->|数据同步| B
5. gantt 图日期格式：YYYY-MM-DD 或相对周数
6. erDiagram 关系：PATIENT ||--o{ NURSING_RECORD : has
7. 节点文字过长时换行：在引号标签中换行无效，应缩短文字或拆分节点

4. 渲染为 PNG

将 .mmd 文件渲染为 PNG：

# 单个文件
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 文件的同目录。

⭐ 自动水印功能：
render.sh 脚本在渲染完成后会自动尝试添加项目名称水印：

• 从当前目录的 分析报告.md 中自动提取项目名称
• 在图片右下角添加半透明灰色水印
• 如果未找到项目名称，跳过水印功能（不影响渲染）

水印参数：

• 位置：右下角
• 透明度：50%
• 字体大小：20px
• 边距：15px

手动添加水印：

# 使用 watermark.py 手动添加水印
python3 scripts/watermark.py --auto-project-name diagram.png -o diagram.png

5. 替换占位符

将 markdown 中的占位符行替换为图片引用：

替换前：

【此处插入系统总体架构图】

替换后：

![系统总体架构图](diagram-系统总体架构图.png)

重要：保留 ASCII 图代码块。 占位符替换后，其下方的 ASCII 代码块不删除——
在 Word 排版时可以选择保留或删除，但在 markdown 阶段保留作为参考。

6. 图片文件命名

统一命名格式：diagram-{描述}.png

例：

• diagram-系统总体架构图.png
• diagram-项目甘特图.png
• diagram-故障处理流程图.png

批量处理

当用户要求处理某个文件的所有图表占位符时：

1. 读取文件，提取所有 【此处插入XX图】 占位符列表
2. 逐个处理：分析上下文 → 编写 mmd → 渲染 → 替换
3. 汇报处理结果

当用户要求处理所有文件时：

1. 扫描 响应文件/ 目录下所有 md 文件中的占位符
2. 按文件分组，逐文件处理
3. 跳过非图表类占位符（如 【此处插入XX扫描件】、【此处插入XX功能截图】）

跳过规则

以下占位符不处理（需要真实截图/扫描件，不是可生成的图表）：

• 【此处插入XX扫描件】 — 证书/合同扫描件
• 【此处插入XX功能截图】 — 系统功能截图（需真实系统）
• 【此处插入XX查询截图】 — 网站查询截图
• 【此处插入XX效果示意图】 — 需要 UI mockup（可另行处理）

典型调用示例

用户：把技术方案里的图画出来
操作：
1. 读取 07-技术方案.md
2. 找到 8 个图表占位符
3. 逐个生成 mermaid → 渲染 PNG → 替换占位符
4. 汇报：8 张图已生成

用户：画一个项目甘特图
操作：
1. 读取上下文中的进度信息
2. 编写 gantt 类型 mermaid
3. 渲染 PNG
4. 插入到指定位置

渲染失败排查

1. 中文乱码：检查 mermaid.json 中 fontFamily 是否包含中文字体
2. 图表溢出：减少节点数量或增加 width 参数
3. 语法错误：先用 npx @mermaid-js/mermaid-cli -i file.mmd -o /dev/null 验证语法
4. 节点 ID 冲突：不同 subgraph 中的节点 ID 不能重复

完成状态

图表生成完成后，输出以下结构化状态摘要：

--- BID-MERMAID-DIAGRAMS COMPLETE ---
处理文件数: {N}
生成图表数: {N}
跳过占位符: {N}（非图表类）
图表清单: {diagram-XX.png, diagram-YY.png, ...}
输出目录: 响应文件/
状态: SUCCESS
--- END ---