STM32F4-Base/.opencode/skills/draw-diagram/SKILL.md

name, description

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

1. 挑 / 复制脚本：新类型图复制最接近的生成器，只改顶部数据区。

2. 改顶部数据：字段 / 节点 / 标题 / 配色。沿用既有调色板（主色 / 底色）：

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

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

   & '.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）