Files

T

wandering1 511fd30cc6 docs: 清理全仓变更记录流水（43 篇整节删 / 23 篇留一行 / 5 篇保留）

用户裁定：文档只写现状，历史流水一律删掉，过程查 git log。

- 43 篇「变更记录 / 修订记录」整节删除：继电保护规划 12.6 KB、产品
  需求 11.8 KB、项目部署环境 5.5 KB、BSD Socket 指南 5.3 KB、架构
  总览 5.0 KB、实机测试实施指南 3.8 KB 等
- 23 篇别处仍有指向：只留节名 + 一行「本文件不再记流水账，过程查
  git log」，节号与锚点不位移（doc-links 不因此断链）
- 5 篇整表保留（被当唯一证据 / 活台账引用）：看门狗设计说明、配置
  文件设计说明、RAM预算台账、内容页架构、本地工具路径环境变量方案
- 规范同步：文档规范 §5.1 改新裁定；测试文档模板规范删示例节与
  登记句；测试开发标准流程 / UI 两篇 / 实机测试实施指南 / 四篇单测
  说明 / 并行任务工作树方案 / 编号规范 的「登记变更记录」改「写进
  正文」
- 技能同步：stale-doc-count-sweep / ui-verify / id-family 三个 SKILL
  正文不再要求追加流水行（顺带消掉 SKILL.md:121「产品需求 §12」
  失效引用）
- 修 5 处悬空指针：采样有效性校验目录锚点、BSD 指南「文末变更
  记录」、docs/README 过期描述、网络自愈架构两处指向面

72 篇文档净减 600 余行；check_doc_links --all --sections-strict 可判
定比例 61% → 78%、失效引用 0；静态门禁 passed=50 failed=0；gitlint
10 条历史提交信息 0 failed。

未提交他人在飞改动：.dsh/skills/keil-build/*（%SystemDrive% 守卫）。

2026-10-28 22:00:34 +08:00

8.3 KiB

Raw Blame History

图形绘制流程（SVG / Mermaid）

范围：本仓库文档（docs/）里的技术配图——协议帧 / 字节布局、分层架构、依赖 / 就绪屏障、流程 / 时序 / 状态机等。目标：统一绘图方法与工具链，保证图形精确、可复现、可 diff、可过 pre-commit，并与既有 tools/arch_diagram/ 生成器一致。沉淀：本流程已沉淀为 draw-diagram skill（.dsh/skills/draw-diagram/SKILL.md）——画图时直接加载该 skill 即可。 产物目录：生成的 .svg 统一放 docs/images/（专门配图目录，产物入库）。

一、选型：什么图用什么工具

图形类型	工具	说明
协议帧 / 字节布局（精确比例）	SVG（`gen_frame_svg.py`）	字段宽须严格 ∝ 字节数 + 逐字段标注 + 偏移标尺
闪存 / 内存分区布局（精确比例）	SVG（`gen_partition_svg.py`）	帧图生成器的 MB 计量副本（分区宽 ∝ MB 数 + 偏移标尺）
分层架构 / 模块依赖	SVG（`gen_arch_svg.py`）	多节点跨层依赖，Mermaid 会画成"意大利面"，手工排布更清晰；单层单职责的栈图用其副本 `gen_storage_stack_svg.py`
就绪屏障 / 生产者-消费者	SVG（`gen_barrier_svg.py`）	三栏对齐 + 正交连线，避免交叉
流程图 / 时序 / 状态机 / ER	Mermaid（Markdown 内嵌）	拓扑关系类图，节点少、强调连接；渲染器原生支持
UI 界面 / 像素级样机	`simulator/` 截图	非本流程范围

为什么"精确布局图"用 SVG，不用 Mermaid / HTML：

维度	SVG	Mermaid	HTML
字段宽 ∝ 字节数	✅ 像素精确定位	❌ 盒子按文本自适应	⚠️ 可但繁琐
连续字节流（无假箭头）	✅ 分段矩形	❌ 自动加有向边	✅
纯文本（可 diff / lint / pre-commit）	✅	✅（代码块）	⚠️
直接是图片（免截图）	✅	⚠️ 需渲染器	❌ 需截图
矢量无损（任意 DPI）	✅	✅（渲染后）	⚠️
依赖	无（浏览器用系统字体渲染）	渲染器	浏览器

结论：要精确像素 / 比例的布局图 → SVG 生成器；只表达拓扑关系的图 → Mermaid。

二、既有工具（`tools/arch_diagram/`）

以下生成器共享同一套约定（§3.2），均为纯标准库拼 SVG：

脚本	产物（入库）	顶部数据区（改这里 → 重跑）
`gen_arch_svg.py`	`docs/images/项目架构总览.svg`	`LAYERS` / `ROWS` / `FOOT`
`gen_barrier_svg.py`	`docs/images/就绪屏障.svg`	`BITS` / `PRODUCERS` / `CONSUMERS`
`gen_frame_svg.py`	`docs/images/RemoDispBus帧格式.svg`	`FIELDS` / `TITLE` / `SUB` / `FOOT`
`gen_storage_stack_svg.py`	`docs/images/存储栈分层.svg`	`L_*` / `ROWS` / `TITLE` / `SUB` / `FOOT`
`gen_partition_svg.py`	`docs/images/物理分区布局.svg`	`FIELDS` / `TITLE` / `SUB` / `FOOT`（MB 计量）
`gen_net_pending_svg.py`	`docs/images/Net层阻塞模型.svg`	`CALLER_STEPS` / `LOOP_STEPS` / `PHASES`
`gen_cfg_arch_svg.py`	`docs/images/配置文件分层架构.svg`	配置引擎分层
`gen_net_stack_svg.py`	`docs/images/BSD网络栈分层.svg`	BSD 网络栈分层
`gen_memory_svg.py`	`docs/images/内存布局_*.svg`	RAM / FLASH 布局
`gen_watchdog_svg.py`	`docs/images/看门狗心跳模型.svg`	`TASKS` / `REQ_BITS` / `POLL_STEPS` / `TIMELINE`
`gen_adc_frontend_svg.py`	`docs/images/ADC前端电路.svg`	`SUB1` / `NOTE_*` 等文案常量 + 面板坐标（电路拓扑固定，网表变了才重画）
`gen_adc_code_scale_svg.py`	`docs/images/ADC码值刻度.svg`	`PANELS` 列表（码范围 / LSB / 实测码标记位置）+ `FOOT`（换芯片才重画）

三、绘制流程

3.1 精确布局图（协议帧 / 架构 / 依赖）——用生成器

挑脚本：协议帧 → gen_frame_svg.py；分层架构 → gen_arch_svg.py；就绪屏障 → gen_barrier_svg.py。
改数据：编辑脚本顶部数据区。配色沿用既有调色板：

语义主色底色

蓝 #2563eb #eff6ff

青 #0d9488 #f0fdfa

绿 #16a34a #f0fdf4

琥珀 #d97706 #fffbeb

紫 #7c3aed #f5f3ff

灰 #475569 #f1f5f9

玫红 #e11d48 #fff1f2
重跑（仓库根目录；纯标准库，任意 python3，统一用 .venv 亦可）：
```
& '.venv\Scripts\python.exe' tools/arch_diagram/gen_frame_svg.py
```
成功输出 OK <字节> bytes, canvas <W>x<H> -> <路径>。脚本内置 ElementTree.fromstring 自检——XML 不合法会直接抛错，不会产出坏图。
目检：浏览器打开 docs/images/*.svg，确认文字不溢出盒外、框 / 线 / 标签对齐、配色正确。
引用：在对应 .md 里用相对路径：根目录下的 md 指向 docs/images/ 下的图（形如 ![帧格式](images/RemoDispBus帧格式.svg)）；docs/UI设计/ 等子目录的 md 则写 ../images/ 前缀的等价写法。
提交：脚本（源）+ 生成的 .svg（产物）一起提交（产物入库，类比生成物 ui_menu_tab.c）。

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

3.2 SVG 约定（手写 / 新增生成器时遵循）

纯标准库：只用 html / os（+ 需要时 math）拼 SVG 字符串；不引第三方库（SVG 由浏览器用系统字体渲染，无需 Pillow / 字体文件）。
文本转义：所有文本经 html.escape(s, quote=True)（& < > " ' → 实体），防止破坏 XML。
字体：根 <svg font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">（系统字体栈，Win / mac 通用）。
文本宽估算（自适应盒宽时）：text_w(s, fs)——CJK / 全角 / 圈码 / 箭头 ≈ 1.0em，其余 ≈ 0.58em（宁大勿小，防溢出）。
落盘：open(OUT, "w", encoding="utf-8", newline="\n")（UTF-8 无 BOM + LF，符合仓库编码铁律）。
自检：写盘后 xml.etree.ElementTree.fromstring(svg)。
产物位置：docs/images/（专门配图目录；引用它的 .md 用相对路径指向）。
命名：docs/images/<主题>.svg（可与同名 .md 对应，如 images/RemoDispBus帧格式.svg ↔ RemoDispBus协议与接收设计说明.md §1.2）。

3.3 拓扑类图（流程 / 时序 / 状态机）——用 Mermaid

在 Markdown 里直接写 ```mermaid 代码块（GitHub 与多数渲染器原生渲染，无需生成图片）：

```mermaid
sequenceDiagram
    participant C as 客户端
    participant S as 服务端
    C->>S: LCDMEM 取帧
    S-->>C: 1bpp 位图（3200 B）
```

常用：flowchart（流程 / 框图）、sequenceDiagram（时序）、stateDiagram-v2（状态机）、erDiagram（实体关系）。

⚠️ Mermaid 盒子宽度自适应、会自动连线，只适合"关系"类图；凡需精确像素 / 比例的布局图（协议帧、分层框）一律走 §3.1 的 SVG 生成器。

四、SVG → PNG（可选）

默认交付 SVG（矢量、可缩放、可 diff、可过门禁）。仅当某个不渲染 SVG 的查看器需要位图时再转 PNG：

最简单：浏览器打开 .svg → 截图 / 另存为图片。

脚本化：给 .venv 装 cairosvg 后转（scale=2 提高清晰度）：

& '.venv\Scripts\python.exe' -m pip install cairosvg
& '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/RemoDispBus帧格式.svg', write_to='remo.png', scale=2)"

PNG 属本地派生物、不入库（与 simulator/tests/ref/*.png 目检图一致，.gitignore 已含 *.png；注意该目录下作为像素黄金参考的 .bin 是入库的，别顺手一起忽略掉）。

五、检查清单（提交前）

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

8.3 KiB Raw Blame History Unescape Escape