Files

T

wandering1 a6cdebde62 文档体系重组与 D-7 一致性门禁落地，清理芯片手册孤儿图片

- 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 警告

2026-09-26 00:51:53 +08:00

4.1 KiB

Raw Blame History

name, description

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

name

description

draw-diagram

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 生成流程（仓库根目录执行）

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

语义主色底色

蓝 #2563eb #eff6ff

青 #0d9488 #f0fdfa

绿 #16a34a #f0fdf4

琥珀 #d97706 #fffbeb

紫 #7c3aed #f5f3ff

灰 #475569 #f1f5f9

玫红 #e11d48 #fff1f2

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

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

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

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

4.1 KiB Raw Blame History Unescape Escape