---
name: draw-diagram
description: docs/ 文档技术配图绘制流程（精确布局图用 SVG 生成器 / 拓扑图用 Mermaid）：挑脚本 → 改顶部数据 → 重跑生成 → 目检 → md 相对路径引用 → 脚本+产物一并提交，产物统一放 docs/images/。Use when 需要新增/修改 docs/ 文档的技术配图（协议帧、分层架构、依赖/就绪屏障、流程图、时序、状态机），或用户要求"画个图 / 生成图 / 更新架构图 / 帧格式图"。
---

# 文档配图绘制（SVG / Mermaid）

`docs/` 文档技术配图的统一流程；完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**（专门配图目录，`.svg` 入库；PNG 预览属本地派生物、不入库）。

## 工具选型

| 图形类型 | 工具 |
|---|---|
| 协议帧 / 字节布局（字段宽 ∝ 字节数、偏移标尺） | SVG：`tools/arch_diagram/gen_frame_svg.py` |
| 分层架构 / 模块依赖 | SVG：`tools/arch_diagram/gen_arch_svg.py` |
| 就绪屏障 / 生产者-消费者 | SVG：`tools/arch_diagram/gen_barrier_svg.py` |
| 其他精确布局图 | **复制**最接近的生成器改顶部数据（`build()` 与数据解耦，通用） |
| 流程 / 时序 / 状态机 / ER（只表达拓扑关系） | Markdown 内嵌 ` ```mermaid ` 代码块（`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`），无需生成图片 |

> Mermaid 盒子按文本自适应宽、自动加有向边，**只适合"关系"类图**；凡需精确像素 / 比例的布局图一律走 SVG 生成器。

## SVG 生成流程（仓库根目录执行）

1. **挑 / 复制脚本**：新类型图复制最接近的生成器，只改顶部数据区。
2. **改顶部数据**：字段 / 节点 / 标题 / 配色。沿用既有调色板（主色 / 底色）：

   | 语义 | 主色 | 底色 |
   |---|---|---|
   | 蓝 | `#2563eb` | `#eff6ff` |
   | 青 | `#0d9488` | `#f0fdfa` |
   | 绿 | `#16a34a` | `#f0fdf4` |
   | 琥珀 | `#d97706` | `#fffbeb` |
   | 紫 | `#7c3aed` | `#f5f3ff` |
   | 灰 | `#475569` | `#f1f5f9` |
   | 玫红 | `#e11d48` | `#fff1f2` |

3. **重跑**（脚本内置 `ElementTree` 自检，XML 不合法直接抛错）：

   ```powershell
   & '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py
   # 成功输出：OK <字节> bytes, canvas <W>x<H> -> <路径>
   ```

4. **目检**：浏览器打开 `docs/images/*.svg`——文字不溢出盒外、框 / 线 / 标签对齐、配色符合调色板。
5. **md 引用**（相对路径）：`docs/` 根的 md 写 `![标题](images/xxx.svg)`；`docs/UI设计/` 等子目录 md 写 `![…](../images/xxx.svg)`。
6. **提交**：生成器脚本（源）+ 生成的 `.svg`（产物）**一并**提交。

## SVG 约定（手写 / 新增生成器必须遵循）

- **纯标准库**拼 SVG（只用 `html` / `os`（+ `math`）），不引第三方库（SVG 由浏览器用系统字体渲染）
- 所有文本经 `html.escape(s, quote=True)`，防止破坏 XML
- 字体栈：`Microsoft YaHei, Segoe UI, PingFang SC, sans-serif`
- 文本宽估算（自适应盒宽）：CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`，其余 ≈ `0.58em`（**宁大勿小**防溢出）
- 落盘：`open(OUT, "w", encoding="utf-8", newline="\n")`（UTF-8 无 BOM + LF）
- 写盘后 `xml.etree.ElementTree.fromstring(svg)` 自检
- 产物放 `docs/images/`，命名 `<主题>.svg`（可与同名 `.md` 对应）

## SVG → PNG（可选，本地派生物不入库）

- 最简单：浏览器打开 `.svg` → 另存为图片
- 脚本化：`& '.venv\Scripts\python.exe' -m pip install cairosvg` 后
  `& '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/xxx.svg', write_to='x.png', scale=2)"`
- `.gitignore` 已含 `docs/images/*.png`

## 提交前检查清单

- [ ] 生成器输出 `OK … bytes`（无异常 = XML 合法）
- [ ] 浏览器目检：文字不溢出、框 / 线 / 标签对齐、配色符合调色板
- [ ] 引用它的 `.md` 里图片**相对路径**正确（能显示）
- [ ] 脚本 + 产物 `.svg` **一并**暂存
- [ ] `pre-commit run --files <脚本> <svg> <md>` 全过（无乱码 / 行尾空白 / 编码 OK）