| name | feature-design-doc |
| description | 阅读某个性能/优化特性的源码,产出一份图文并茂、可交付的设计文档(Markdown + Word/docx),支持中文、英文或中英双语。适用场景:用户说"读一下 XX 特性/优化的代码并写一份设计文档""为这个 PR/commit 写设计文档""生成含框架图、原理图、时序图、用例图的设计说明""把这个特性整理成 docx 设计文档""再出一份对应英文版的文档和图片""做成中英双语"等。无论用户是否点名"设计文档",只要意图是"理解一段特性代码并系统化产出含架构图/原理图/验证数据/用例的说明文档",都应使用本技能;要英文/双语版时同样用它(图内文字也会译成英文)。它固化了章节骨架、结构图用 SVG 矢量、行为图用 PlantUML 的图示策略、严格的 docx 排版(中文宋体五号/英文 Times New Roman 五号/全黑无斜体/单倍行距段后6磅)、英文版正文全 Times New Roman、以及"图片与文档同级归档、同次提交"的工程规范。 |
特性设计文档生成
把"读懂一个特性的源码 → 产出规范、图文并茂、可交付的设计文档"这件事标准化。产物是一份中文 Markdown 设计文档,外加一份排版规范的 Word(.docx),其中所有图都以图片内嵌。
何时用本技能
当用户要求"阅读某特性/优化的代码并写设计文档""为某 PR/commit 出设计说明""生成含框架图/原理图/时序图/用例图的文档""把特性整理成 docx"时。核心信号是:需要先理解一段特性代码,再系统化地把它的需求、方案、详细设计、验证、用法讲清楚。
工作流总览
- 环境准备:
bash scripts/setup_env.sh(装 cairosvg/python-docx/pillow、下载 plantuml.jar 与中英文字体)。
- 精读源码:把特性涉及的所有文件读全——构建开关、生成的表/常量、运行时主体、汇编、测试。弄清"改之前 vs 改之后"。
- 写 Markdown:按
references/doc-structure.md 的骨架写,牢记黄金原则:每图每代码前有引入、后有解读。
- 作图:按
references/diagram-guide.md 选型——结构/分层/组件/内存布局图用 SVG(scripts/svglib.py + assets/svg_example.py),时序/状态/用例/活动图用 PlantUML。源文件(.svg/.puml)写进文档同级的 images/。
- 渲染:
python scripts/render_diagrams.py <doc>/images,把所有 .puml/.svg 渲成 .png。
- 生成 docx:
python scripts/md_to_docx.py <doc>.md,严格遵守 references/docx-format.md 的排版。
- 归档与提交:md、images/.png、images/.{svg,puml} 同级、同次 commit;按目标仓库流程提交并(如需)发 PR。
关键规范(必须遵守)
文档质量
- 有图、有代码就必有文字:禁止光秃秃的图或不解释的代码块。详细设计以文字讲原理、讲设计思路为主,图与代码为佐证。详见
references/doc-structure.md。
- 详细设计要讲"变换过程":重点画清楚数据/内存/状态"从 A 到 B 怎么变"(如 span 怎样被切分、填充、回收、放大),多画原理图,而不是只贴代码。
- 验证要归因:不能只贴 benchstat 数字,要逐项解释为什么、哪项受益最大/回退,并给总结;基线选择要诚实(对照只差被测特性本身)。
- 与源码交叉验证:文中常量名/函数名/文件名必须与代码一致,不臆造数据。
图示策略(见 references/diagram-guide.md)
- 结构类 → SVG(分层架构、组件/泳道、内存布局、数据流、维度分层):用
svglib.py 精确排布,网格对齐、配色统一(参考 sizeclasses_span 风格)。
- 行为类 → PlantUML(时序、状态、用例、活动、波形):自动布局更合适。
- 自检:SVG 子框不得超出父框/画布,文字不压盖;渲染后用图片查看核对。
docx 排版(见 references/docx-format.md,已固化在 md_to_docx.py)
- 中文宋体五号、英文 Times New Roman 五号;嵌入正文的代码词与正文同字体,仅整块代码用 Consolas。
- 字体一律自动黑色、不用斜体;单倍行距、段后 6 磅。
归档规范
- 图片文件夹与文档同级(
docs/images/ 紧挨 docs/xxx.md),md 用相对引用 images/figNN.png。
- md + 渲染 png + 图源(svg/puml)三者同一次提交,缺图会导致仓库无法显示图片。
英文 / 双语版本(见 references/bilingual.md)
当用户要"英文版""对应英文文档""双语"时,产出与中文版同结构、同图序的英文版本——图内文字也要译成英文(不是只翻正文):
- 布局:中文在
docs/<feature>-design.md + docs/images/;英文放 docs/en/<feature>-design.md + docs/en/images/,两套图各自独立(英文图在 en/images)。
- 图片:结构图复制 svg 生成器、把标注换成英文重渲染;行为图复制 puml、把文字换成英文重渲染(
render_diagrams.py 对 en/images 再跑一次)。图序 figNN 与中文版一一对应,正文引用同名。
- docx:英文版正文全
Times New Roman 五号(无中文则宋体不生效),其余排版约束不变;md_to_docx.py 直接可用。
- 中英文档互相加一行交叉链接(
> 中文版见 … / > English: …)。
目录与脚本
feature-design-doc/
├── SKILL.md
├── scripts/
│ ├── setup_env.sh # 一键装依赖(cairosvg/python-docx/plantuml.jar/CJK 字体)
│ ├── svglib.py # SVG 原语库(Canvas/rect/cells/arrow/调色板)
│ ├── render_diagrams.py # images 目录里 *.puml→png(plantuml)、*.svg→png(cairosvg)
│ └── md_to_docx.py # Markdown→docx,内嵌图片,固化排版规范
├── references/
│ ├── doc-structure.md # 章节骨架 + 写作黄金原则(先读这个)
│ ├── diagram-guide.md # SVG vs PlantUML 选型、风格、引用与归档
│ ├── docx-format.md # docx 字体/颜色/段落/校验细则
│ └── bilingual.md # 英文/双语版本:图内文字也译英、en/ 布局、交叉链接
└── assets/
└── svg_example.py # 用 svglib 画分层架构 / 默认vs优化对比 的起手示例
按需读取:动笔前先读 references/doc-structure.md;作图时读 references/diagram-guide.md;生成 docx 前读 references/docx-format.md;做英文/双语版本时读 references/bilingual.md。
