kidoc

kidoc — 工程文档技能

根据 KiCad 项目文件生成专业工程文档。

快速开始

执行一条命令，即可生成完整脚手架——分析、图表、渲染文件和 Markdown 都会自动生成：

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

此命令会自动检测 .kicad_sch 和 .kicad_pcb 文件，运行原理图、PCB、EMC 和热分析，生成框图和原理图 SVG 渲染文件，并生成结构化的 Markdown 脚手架，其中包含预填数据的表格和叙述内容占位符。

生成 PDF：

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

首次运行时会自动创建 reports/.venv/（仅用于 PDF/DOCX/ODT——HTML 无需额外依赖）。

工作流

1. 生成脚手架 — kidoc_scaffold.py 会自动运行所有可用的分析、渲染原理图、生成图表，并写入 Markdown 脚手架。
2. 填写叙述内容 — Agent 读取脚手架，并为每个 `` 占位符编写工程说明。工程师负责审核和编辑。
3. 重新生成 — 再次运行时，`` 标记之间的数据部分会根据最新分析结果更新；用户编写的叙述内容会保留。
4. 渲染输出 — kidoc_generate.py 可生成 PDF、HTML、DOCX 或 ODT。

文档类型

类型	名称	主要章节
hdd	硬件设计说明	系统概述、电源、信号、模拟、热、EMC、PCB、机械、BOM、测试、合规性
ce_technical_file	CE 技术文件	产品 ID、基本要求、协调标准、风险评估、符合性声明
design_review	设计审查包	审查摘要（交叉分析器评分）、发现项、行动项
icd	接口控制文档	接口列表、各连接器引脚排列详情、电气特性
manufacturing	制造移交包	装配概述、PCB 制造说明、装配说明、测试流程
schematic_review	原理图审查报告	系统概述、电源、信号、模拟、BOM、原理图附录
power_analysis	电源分析报告	电源设计、热、EMC、BOM
emc_report	EMC 预符合性报告	EMC 分析、合规性、原理图附录

自定义报告

使用 --spec 以任意章节顺序生成报告：

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir . --spec my-report.json --output reports/custom.md

Spec 格式（JSON）：

{
  "type": "custom",
  "title": "USB Interface Analysis",
  "sections": [
    {"id": "front_matter", "type": "front_matter"},
    {"id": "signal_interfaces", "type": "signal_interfaces"},
    {"id": "bom", "type": "bom_summary"}
  ]
}

每个章节的 type 必须与已知章节类型匹配（名称与上方文档类型表中的相同）。id 字段是该章节实例的唯一键。

查看任意内置类型的完整默认 spec：

python3 skills/kidoc/scripts/kidoc_spec.py --expand hdd
python3 skills/kidoc/scripts/kidoc_spec.py --list

--spec 标志也适用于 kidoc_generate.py（使用 spec 标题作为备用项目名称）。

原理图和 PCB 渲染

渲染功能已集成到图表生成引擎中。编排器和脚手架会在生成文档时自动渲染原理图和 PCB 视图：

# Generate all figures (diagrams + schematic/PCB renders) from analysis JSON
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --output reports/figures/

# Full orchestration with spec, analysis, and project files
python3 skills/kidoc/scripts/kidoc_orchestrator.py --analysis schematic.json \
    --project-dir . --output reports/figures/

图表生成器支持：整页渲染（根页 + 所有子页）、子系统裁剪（规范章节中的 focus_refs）、网络高亮、引脚级网络标注，以及所有 PCB 图层预设。这些选项可在文档规范中配置，也可通过分析字典传入。

通过生成器框架提供的渲染功能：

• 裁剪：聚焦于特定元件参考标号周围的子系统边界框
• 聚焦/淡化：以完全不透明度显示聚焦的元件，将其余部分淡化至 15%
• 高亮网络：通过 BFS 对特定网络进行颜色追踪
• 引脚网络：在引脚末端标注引脚级网络名称

如需直接以编程方式访问，请使用 figures.renderers：

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')

图层预设：

预设	显示内容
assembly-front	正面丝印、制造层、焊盘、外形
assembly-back	背面丝印、制造层、焊盘、外形（镜像）
routing-front	正面铜层、焊盘、过孔、外形
routing-back	背面铜层、焊盘、过孔、外形
routing-all	所有铜层、焊盘、过孔、覆铜区
power	电源平面、过孔、覆铜区轮廓

其他选项：--highlight-nets、--crop-refs、--crop x,y,w,h、--mirror、--overlay annotations.json（带引线的标注框）。

框图

python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --all --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --power-tree --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --bus-topology --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --architecture --output diagrams/

根据原理图分析 JSON 生成。电源树展示稳压器拓扑、电感值、电容摘要和输出电压。

输出格式

格式	SVG 处理方式	依赖项
Markdown	图像引用	零依赖
HTML	内嵌为矢量图	零依赖
PDF	通过 svglib 输出矢量图、自定义转换器回退方案、栅格回退方案	Venv (reports/.venv/)
DOCX	栅格化为 300 DPI PNG	Venv
ODT	栅格化为 300 DPI PNG	Venv

PDF 输出包含经过样式设计的封面页、目录、带交替行底色的格式化表格，以及矢量 SVG 图表。

配置

报告设置位于 .kicad-happy.json 的 "reports" 键下。配置文件会逐级合并：~/.kicad-happy.json（用户级默认设置，例如公司品牌信息）会与项目级配置合并。

{
  "project": {
    "name": "Widget Board",
    "number": "HW-2024-042",
    "revision": "1.2",
    "company": "Acme Electronics",
    "author": "Jane Smith",
    "market": "eu"
  },
  "reports": {
    "classification": "Company Confidential",
    "documents": [
      {"type": "hdd", "output": "HDD-{project}-{rev}", "formats": ["pdf", "docx"]}
    ],
    "branding": {
      "logo": "templates/logo.png",
      "header_left": "{company}",
      "header_right": "{number} Rev {rev}"
    }
  }
}

撰写说明性文字

生成脚手架后，使用工程说明文字填写说明性文字占位章节。

工作流

1. 运行上下文构建器，获取每个章节的聚焦数据：

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

   或一次性为所有说明性文字章节构建上下文：

   python3 skills/kidoc/scripts/kidoc_narrative.py \
     --analysis analysis/schematic.json \
     --report reports/HDD.md
   

2. 针对每个章节，阅读上下文并撰写说明文字，要求：

   • 解释为什么，而不只是是什么——说明工程依据和权衡
   • 引用具体的元件值和零件编号
   • 使用定量描述（例如“2.3ms 的保持时间”，而非“电容足够”）
   • 指出与数据手册建议不符之处
   • 如有 SPICE 验证结果，请加以引用

3. 将 Markdown 中的斜体占位符 *[...]* 替换为实际说明文字。

4. 重新生成时，数据表会自动更新。请检查说明文字，确保其与任何已更改的数据保持一致。

风格指南

以资深 EE 向同行说明的口吻撰写：

• 先陈述关键发现或决策
• 用分析中的具体数字作为依据
• 指出风险或偏差
• 每段控制在 3-5 句
• 不要重复表格中已有的数据

要求

• Python 3.9+ 和 python3-venv（用于生成 PDF/DOCX/ODT）
• KiCad 原理图文件（.kicad_sch，KiCad 6+）——用于 SVG 渲染
• **可选：**分析 JSON 会从 .kicad_sch/.kicad_pcb 自动生成；如果 analysis/ 中（或 .kicad-happy.json 中配置的路径下）存在预生成的 JSON，则会使用它们。生成的图表（框图、原理图 SVG）会放在 reports/figures/ 中，以便通过 Git 进行跟踪

限制

• 原理图和 PCB 渲染器仅支持 KiCad 6+ 格式（.kicad_sch、.kicad_pcb）
• 叙述性章节需要由 Agent 编写或手动撰写 — 脚手架提供结构和数据，而非正文
• SPICE 仿真结果需要手动设置仿真（脚手架不会自动运行仿真）
• PDF 中的矢量 SVG 嵌入功能在可用时使用 svglib；如果 svglib 无法解析特定 SVG，则回退为栅格图像

相关技能

技能	关联
kicad	生成脚手架使用的原理图/PCB/热分析 JSON
emc	为 EMC 章节生成 EMC 分析 JSON
spice	SPICE 仿真结果会出现在模拟设计章节中
bom	BOM 数据会出现在 BOM 摘要章节中

先运行 kicad 技能的分析器，然后在可用时运行 emc 和 spice。源文件存在时，脚手架会自动运行 kicad 和 emc 分析，因此只有 SPICE 需要手动预分析。