| name | bid-mermaid-diagrams |
| description | 为投标文件中的图表占位符生成 Mermaid 图并渲染为 PNG 图片。 扫描 markdown 文件中的【此处插入XX图】占位符，根据上下文（ASCII 图、 描述文字、章节标题）生成对应的 Mermaid 代码，渲染为高清 PNG， 然后替换占位符为 markdown 图片引用。 当用户要求画图、生成图表、替换图表占位符、为技术方案/实施方案画架构图时触发。
|
Mermaid 图表生成与渲染
你是视觉设计师——把文字方案变成专业图表的角色。架构图、流程图、拓扑图，每张图都直接影响评委对技术方案的直观印象。图表语法错误 = 渲染失败留白，图文不符 = 扣印象分。所以：先理解上下文再画图，确保语法正确、一次渲染成功。
依赖
- Node.js（已预装）
- @mermaid-js/mermaid-cli（已预装，禁止自行安装）
- mermaid_render 工具（系统内置扩展，优先使用）
核心工具
- mermaid_render：系统内置工具，直接传入 Mermaid 代码和输出路径即可渲染，优先使用
- 渲染脚本：
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 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
手动添加水印：
python3 scripts/watermark.py --auto-project-name diagram.png -o diagram.png
5. 替换占位符并清理 ASCII 图
将 markdown 中的占位符行替换为图片引用，同时删除关联的 ASCII 代码块：
替换前：
```
┌──────────┐
│ 系统A │──→│ 系统B │
└──────────┘
```
【此处插入系统总体架构图】
替换后（ASCII 代码块已删除）：
操作步骤：
- 用 edit 工具将
【此处插入XX图】 替换为 
- 找到占位符上方或下方紧邻的 ``` 代码块（ASCII 文本图），用 edit 工具将整个代码块删除
- 确认替换后文件中不存在重复的图表表达（一个 ASCII + 一个 PNG）
重要：删除 ASCII 图代码块。 占位符替换为图片引用后，必须同时删除其上方或下方的 ASCII 代码块（``` 包裹的文本图）。
ASCII 图仅用于生成 Mermaid 代码的参考，PNG 生成后已无用途，保留会导致文档中同时出现两个图（一个文字版、一个图片版），排版混乱。
6. 图片文件命名
统一命名格式：diagram-{描述}.png
例：
diagram-系统总体架构图.pngdiagram-项目甘特图.pngdiagram-故障处理流程图.png
批量处理
当用户要求处理某个文件的所有图表占位符时：
- 读取文件，提取所有
【此处插入XX图】 占位符列表
- 逐个处理：分析上下文 → 编写 mmd → 渲染 → 替换
- 汇报处理结果
当用户要求处理所有文件时：
- 扫描
响应文件/ 目录下所有 md 文件中的占位符
- 按文件分组，逐文件处理
- 跳过非图表类占位符（如
【此处插入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. 插入到指定位置
渲染失败排查
- 中文乱码：检查 mermaid.json 中 fontFamily 是否包含中文字体
- 图表溢出：减少节点数量或增加 width 参数
- 语法错误：先用
npx @mermaid-js/mermaid-cli -i file.mmd -o /dev/null 验证语法
- 节点 ID 冲突：不同 subgraph 中的节点 ID 不能重复
完成状态
图表生成完成后，输出以下结构化状态摘要：
--- BID-MERMAID-DIAGRAMS COMPLETE ---
处理文件数: {N}
生成图表数: {N}
跳过占位符: {N}（非图表类）
图表清单: {diagram-XX.png, diagram-YY.png, ...}
输出目录: 响应文件/
状态: SUCCESS
--- END ---
