wandering1
a6cdebde62
- D-6 目录规范化：docs 根目录散落文档归入 UI设计/子系统设计/架构设计/审查记录/ 环境与部署/网络 等子目录，去掉目录名空格，重命名 嵌入式C语言代码规范_V1.0.md - D-7 三档一致性门禁：新增 scripts/check_doc_links.py（链接存在性）、 scripts/gen_task_table.py（FreeRTOS 任务表数值）、scripts/check_mem_numbers.py （内存/Flash 体积），均支持 --check/--write/--diff，pre-commit 钩子同步注册 - D-5 文档索引：新建 docs/README.md，新建 docs/文档规范.md 约束目录命名与链接写法 - D-1 芯片手册瘦身：删除 1069 张无引用孤儿图片（77.06 MB）， docs/芯片手册 120 MB → 41 MB，已引用图片零断链 - 同步 C 源码注释中的文档路径引用（D-6 重组后），构建 0 错误 0 警告
72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
---
|
||
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）
|