Hardware doc generator

何时使用

当你有一个 KiCad 6+ 工程（.kicad_sch / .kicad_pcb），需要产出专业硬件工程文档时使用：

• HDD（硬件设计说明）、CE 技术文件、ICD（接口控制文档）、设计评审包、制造移交包，以及原理图评审报告、电源分析报告、EMC 预兼容报告。
• 需要渲染原理图/PCB 的 SVG（含子系统裁剪、聚焦淡化、网络高亮、引脚级网络标注）。
• 需要生成电源树、总线拓扑、架构框图。
• 需要把 Markdown 文档源导出为带封面、目录、矢量图的 PDF（或 HTML/DOCX/ODT）。

不该用的边界：

• 渲染器仅支持 KiCad 6+ 格式（.kicad_sch / .kicad_pcb），更早版本不支持。
• 不负责跑 SPICE 仿真本身——仿真需手动搭建，本工具只在结果可用时引用。
• 叙述性工程正文（每个 <!-- NARRATIVE --> 占位）需 Agent 或人工撰写，脚手架只给结构和数据，不代写文字。

步骤

1. 生成脚手架：kidoc_scaffold.py 自动探测源文件、跑全部可用分析、渲染原理图、生成框图，写出带预填数据表和叙述占位符的 Markdown。
2. 填写叙述：Agent 读取脚手架，为每个 <!-- NARRATIVE: 段名 --> 占位写工程正文；工程师复核修订。
3. 重新生成：再次运行时，<!-- GENERATED: 段id --> 之间的数据段会用最新分析刷新，用户写的叙述内容被保留。
4. 导出：kidoc_generate.py 产出 PDF / HTML / DOCX / ODT。

指令

一条命令生成完整脚手架（分析、框图、渲染、Markdown 全自动）：

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir /path/to/kicad/project \
  --type hdd \
  --output reports/HDD.md

导出 PDF（首次运行自动创建 reports/.venv/，仅 PDF/DOCX/ODT 需要 venv，HTML 零依赖）：

python3 skills/kidoc/scripts/kidoc_generate.py \
  --project-dir /path/to/kicad/project \
  --doc reports/HDD.md \
  --format pdf

自定义报告——用 --spec 指定任意段顺序（JSON 中 type 必须匹配已知段类型，id 为该段实例唯一键）：

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir . --spec my-report.json --output reports/custom.md
# 查看内置类型的默认 spec / 列出全部类型
python3 skills/kidoc/scripts/kidoc_spec.py --expand hdd
python3 skills/kidoc/scripts/kidoc_spec.py --list

框图与渲染（集成在图形引擎里，脚手架会自动调用）：

# 从分析 JSON 生成全部图（框图 + 原理图/PCB 渲染）
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --output reports/figures/
# 仅电源树 / 总线拓扑 / 架构图
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --power-tree --output diagrams/

PCB 层预设：assembly-front/back、routing-front/back/all、power。附加选项：--highlight-nets、--crop-refs、--crop x,y,w,h、--mirror、--overlay annotations.json。

直接编程访问：

from figures.renderers import render_schematic, render_pcb
render_schematic('design.kicad_sch', 'output/', crop_refs=['R1', 'R2'], highlight_nets=['VCC'])
render_pcb('board.kicad_pcb', 'output/', preset_name='assembly-front')

示例

为一块电源板生成 HDD 并导出 PDF + DOCX：

1. 配置 .kicad-happy.json（reports 键下声明文档与品牌信息，用户级 ~/.kicad-happy.json 与项目级级联合并）：

{
  "project": {"name": "Widget Board", "number": "HW-2024-042", "revision": "1.2", "company": "Acme Electronics", "market": "eu"},
  "reports": {
    "classification": "Company Confidential",
    "documents": [{"type": "hdd", "output": "HDD-{project}-{rev}", "formats": ["pdf", "docx"]}]
  }
}

2. 跑脚手架 → 读 reports/HDD.md，为每个 *[...]* 占位写正文（用上下文构建器取分段数据）：

python3 skills/kidoc/scripts/kidoc_narrative.py --analysis analysis/schematic.json --section power_design

3. 导出：kidoc_generate.py --format pdf，得到带封面、目录、矢量 SVG 的 PDF。

注意事项

• 环境：Python 3.9+ 且需 python3-venv（PDF/DOCX/ODT）。原理图 SVG 渲染需 .kicad_sch（KiCad 6+）。
• 分析 JSON 从源文件自动生成；若 analysis/（或配置路径）下已有预生成 JSON 则优先使用。生成的图放在 reports/figures/ 便于 git 跟踪。
• 写叙述要讲“为什么”而非“是什么”：交代工程权衡，引用具体元件值/料号，用定量语言（如“2.3ms 维持时间”而非“电容足够”），标注偏离 datasheet 之处，有 SPICE 结果时引用。文风按资深 EE 对同行讲解：先抛关键结论，再用分析数据支撑，段落 3-5 句，不重复表里已有数据。
• SVG 嵌入 PDF：优先用 svglib 矢量嵌入；个别 SVG 解析失败时回退到栅格。DOCX/ODT 一律栅格化到 300 DPI PNG。
• 先跑上游分析：先运行 kicad 分析器，再视情况跑 emc/spice。脚手架在源文件存在时自动跑 kicad 和 emc，故通常只需手动预跑 SPICE。

互见

• 上游 kicad 分析产出原理图/PCB/热分析 JSON，被本技能脚手架消费；emc 产出 EMC 段 JSON；spice 仿真结果进入模拟设计段；bom 数据进入 BOM 汇总段。

---

本条采编自 aklofas/kicad-happy（MIT）。