绘图流程沉淀为 draw-diagram skill，SVG 收拢到 docs/images/
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
---
|
||||
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 写 ``；`docs/UI 设计/` 等子目录 md 写 ``。
|
||||
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）
|
||||
Reference in New Issue
Block a user