kidoc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kidoc — Engineering Documentation Skill

kidoc — 工程文档生成Skill

Generate professional engineering documentation from KiCad project files.

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

Quick Start

快速开始

One command generates the full scaffold — analyses, diagrams, renders, and markdown are all produced automatically:

bash

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

This auto-detects

.kicad_sch

and

.kicad_pcb

files, runs schematic/PCB/EMC/thermal analyses, generates block diagrams and schematic SVG renders, and produces a structured markdown scaffold with pre-filled data tables and narrative placeholders.

To produce a PDF:

bash

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

Creates

reports/.venv/

automatically on first run (PDF/DOCX/ODT only — HTML is zero-dep).

只需一条命令即可生成完整框架——分析内容、图表、渲染图和Markdown文件均自动生成：

bash

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文档：

bash

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格式无依赖）。

Workflow

工作流程

Generate scaffold —
```
kidoc_scaffold.py
```
auto-runs all available analyses, renders schematics, generates diagrams, and writes the markdown scaffold.
Fill narratives — The agent reads the scaffold and writes engineering prose for each
```

```
placeholder. The engineer reviews and edits.
Regenerate — On re-run, data sections between
```

```
markers update from fresh analysis; user-written narrative content is preserved.
Render output —
```
kidoc_generate.py
```
produces PDF, HTML, DOCX, or ODT.

生成框架 —
```
kidoc_scaffold.py
```
会自动运行所有可用分析、渲染原理图、生成图表，并写入Markdown框架。
填充叙述内容 — Agent会读取框架并为每个
```

```
占位符编写工程文案。工程师可进行审核和编辑。
重新生成 — 再次运行时，
```

```
标记之间的数据部分会根据最新分析结果更新；用户编写的叙述内容将被保留。
渲染输出 —
```
kidoc_generate.py
```
可生成PDF、HTML、DOCX或ODT格式文件。

Document Types

文档类型

Type	Name	Key Sections
`hdd`	Hardware Design Description	System overview, power, signals, analog, thermal, EMC, PCB, mechanical, BOM, test, compliance
`ce_technical_file`	CE Technical File	Product ID, essential requirements, harmonized standards, risk assessment, Declaration of Conformity
`design_review`	Design Review Package	Review summary (cross-analyzer scores), findings, action items
`icd`	Interface Control Document	Interface list, per-connector pinout details, electrical characteristics
`manufacturing`	Manufacturing Transfer Package	Assembly overview, PCB fab notes, assembly instructions, test procedures
`schematic_review`	Schematic Review Report	System overview, power, signals, analog, BOM, schematic appendix
`power_analysis`	Power Analysis Report	Power design, thermal, EMC, BOM
`emc_report`	EMC Pre-Compliance Report	EMC analysis, compliance, schematic appendix

类型	名称	核心章节
`hdd`	硬件设计说明（HDD）	系统概述、电源、信号、模拟电路、热设计、EMC、PCB、机械结构、物料清单（BOM）、测试、合规性
`ce_technical_file`	CE技术文件	产品ID、基本要求、协调标准、风险评估、符合性声明
`design_review`	设计评审包	评审总结（跨分析器评分）、发现问题、行动项
`icd`	接口控制文档（ICD）	接口列表、每个连接器的引脚细节、电气特性
`manufacturing`	制造转移包	装配概述、PCB制造说明、装配指导、测试流程
`schematic_review`	原理图评审报告	系统概述、电源、信号、模拟电路、BOM、原理图附录
`power_analysis`	电源分析报告	电源设计、热设计、EMC、BOM
`emc_report`	EMC预合规报告	EMC分析、合规性、原理图附录

Custom Reports

自定义报告

Use

--spec

to generate reports with arbitrary section ordering:

bash

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

Spec format (JSON):

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"}
  ]
}

Each section's

type

must match a known section type (same names used in the document types table above). The

id

field is a unique key for that section instance.

To see the full default spec for any built-in type:

bash

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

The

--spec

flag also works with

kidoc_generate.py

(uses the spec title as fallback project name).

使用

--spec

参数可生成任意章节顺序的报告：

bash

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

配置文件格式（JSON）：

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

字段是该章节实例的唯一标识。

要查看任何内置类型的完整默认配置：

bash

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

--spec

参数同样适用于

kidoc_generate.py

（使用配置文件中的标题作为项目名称的备选）。

Schematic and PCB Rendering

原理图与PCB渲染

Rendering is integrated into the figure generation engine. The orchestrator and scaffold automatically render schematics and PCB views as part of document generation:

bash

undefined

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

bash

undefined

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/


The figure generators support: full-sheet rendering (root + all sub-sheets), subsystem cropping (`focus_refs` in spec sections), net highlighting, pin-level net annotation, and all PCB layer presets. These options are configured in the document spec or passed through the analysis dict.

Rendering features available through the generator framework:
- **Crop**: Focus on a subsystem bounding box around specific component refs
- **Focus/dim**: Show focused components at full opacity, dim the rest to 15%
- **Highlight nets**: Color-trace specific nets via BFS
- **Pin nets**: Annotate pin-level net names at pin tips

For direct programmatic access, use `figures.renderers`:
```python
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')

Layer presets:

Preset	Shows
`assembly-front`	Front silk, fab, pads, outline
`assembly-back`	Back silk, fab, pads, outline (mirrored)
`routing-front`	Front copper, pads, vias, outline
`routing-back`	Back copper, pads, vias, outline
`routing-all`	All copper layers, pads, vias, zones
`power`	Power planes, vias, zone outlines

Additional options:

--highlight-nets

--crop-refs

--crop x,y,w,h

--mirror

--overlay annotations.json

(callout boxes with leader lines).

python3 skills/kidoc/scripts/kidoc_orchestrator.py --analysis schematic.json
--project-dir . --output reports/figures/


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

通过生成器框架可使用以下渲染特性：
- **裁剪**：聚焦于特定组件参考编号周围的子系统边界框
- **焦点/调暗**：以完全不透明度显示聚焦组件，其余组件调暗至15%
- **网络高亮**：通过广度优先搜索（BFS）为特定网络添加颜色追踪
- **引脚网络**：在引脚末端标注引脚级网络名称

如需直接通过编程访问，可使用`figures.renderers`：
```python
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')

Block Diagrams

层预设

bash

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/

Generated from schematic analysis JSON. Power trees show regulator topology with inductor values, capacitor summaries, and output voltages.

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

附加选项：

--highlight-nets

、

--crop-refs

、

--crop x,y,w,h

、

--mirror

、

--overlay annotations.json

（带引线的标注框）。

Output Formats

框图

Format	SVG Handling	Dependencies
Markdown	Image references	Zero-dep
HTML	Inlined as vector	Zero-dep
PDF	Vector via svglib, custom converter fallback, raster fallback	Venv ( `reports/.venv/` )
DOCX	Rasterized to 300 DPI PNG	Venv
ODT	Rasterized to 300 DPI PNG	Venv

PDF output includes a styled cover page, table of contents, formatted tables with alternating rows, and vector SVG diagrams.

bash

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生成。电源树显示稳压器拓扑结构，包含电感值、电容汇总和输出电压。

Configuration

输出格式

Report settings live in

.kicad-happy.json

under the

"reports"

key. Config files cascade:

~/.kicad-happy.json

(user-level defaults, e.g. company branding) merges with project-level config.

jsonc

{
  "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}"
    }
  }
}

格式	SVG处理方式	依赖项
Markdown	图片引用	无依赖
HTML	内联为矢量	无依赖
PDF	通过svglib实现矢量嵌入，自定义转换器备选，光栅化备选	虚拟环境（ `reports/.venv/` ）
DOCX	光栅化为300 DPI PNG	虚拟环境
ODT	光栅化为300 DPI PNG	虚拟环境

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

Writing Narratives

配置

After generating a scaffold, fill the narrative placeholder sections with engineering prose.

报告设置存储在

.kicad-happy.json

文件的

"reports"

键下。配置文件会级联合并：

~/.kicad-happy.json

（用户级默认配置，如公司品牌）会与项目级配置合并。

jsonc

{
  "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}"
    }
  }
}

Workflow

编写叙述内容

Run the context builder to get focused data for each section:

bash

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

Or build contexts for all narrative sections at once:

bash

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

For each section, read the context and write prose that:
- Explains why, not just what — engineering rationale, tradeoffs
- References specific component values and part numbers
- Uses quantitative language ("2.3ms hold-up time" not "adequate capacitance")
- Flags deviations from datasheet recommendations
- References SPICE validation results when available
Replace the italic placeholder
```
*[...]*
```
in the markdown with real prose.
On regeneration, data tables update automatically. Review narratives for consistency with any changed data.

生成框架后，为叙述占位符章节填充工程文案。

Style Guide

工作流程

Write as a senior EE explaining to a peer:

Lead with the key finding or decision
Support with specific numbers from the analysis
Note any risks or deviations
Keep paragraphs to 3-5 sentences
Don't repeat data that's already in tables

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

bash

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

或者一次性为所有叙述章节构建上下文：

bash

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

针对每个章节，阅读上下文并编写文案，需：
- 解释原因，而非仅说明内容——包括工程原理、权衡取舍
- 引用特定组件值和零件编号
- 使用量化表述（如“2.3ms保持时间”而非“足够的电容”）
- 标记与 datasheet 推荐的偏差
- 如有可用，引用SPICE验证结果
将Markdown中的斜体占位符
```
*[...]*
```
替换为真实文案。
重新生成时，数据表会自动更新。需检查叙述内容与更新后数据的一致性。

Requirements

风格指南

Python 3.9+ with
```
python3-venv
```
(for PDF/DOCX/ODT generation)
KiCad schematic file (
```
.kicad_sch
```
, KiCad 6+) — for SVG rendering
Optional: Analysis JSONs are auto-generated from
```
.kicad_sch
```
/
```
.kicad_pcb
```
; pre-generated JSONs in
```
analysis/
```
(or the path configured in
```
.kicad-happy.json
```
) are used if present. Generated figures (diagrams, schematic SVGs) are placed in
```
reports/figures/
```
for git tracking

以资深电子工程师向同行讲解的口吻撰写：

开篇点明核心结论或决策
用分析得出的具体数据支撑内容
标注任何风险或偏差
段落控制在3-5句话
不要重复表格中已有的数据

Limitations

要求

Schematic and PCB renderers support KiCad 6+ formats only (
```
.kicad_sch
```
,
```
.kicad_pcb
```
)
Narrative sections require the agent or manual authoring — the scaffold provides structure and data, not prose
SPICE simulation results require manual simulation setup (not auto-run by scaffold)
PDF vector SVG embedding uses svglib when available; falls back to raster if svglib cannot parse a particular SVG

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版本跟踪

Related Skills

局限性

Skill	Relationship
`kicad`	Produces schematic/PCB/thermal analysis JSON consumed by scaffolds
`emc`	Produces EMC analysis JSON for EMC sections
`spice`	SPICE simulation results appear in analog design sections
`bom`	BOM data appears in BOM summary sections

Run the

kicad

skill's analyzers first, then

emc

and

spice

if available. The scaffold auto-runs

kicad

and

emc

analyses when source files are present, so manual pre-analysis is only needed for SPICE.

原理图和PCB渲染器仅支持KiCad 6及以上版本格式（
```
.kicad_sch
```
、
```
.kicad_pcb
```
）
叙述章节需要Agent或人工编写——框架仅提供结构和数据，不生成文案
SPICE仿真结果需要手动设置仿真（框架不会自动运行）
PDF矢量SVG嵌入在svglib可用时使用；如果svglib无法解析特定SVG，则会回退到光栅化

—

Skill	关联关系
`kicad`	生成框架所使用的原理图/PCB/热分析JSON
`emc`	生成EMC章节所用的EMC分析JSON
`spice`	SPICE仿真结果会出现在模拟设计章节中
`bom`	BOM数据会出现在BOM汇总章节中

kidoc

Original

Translation

kidoc — Engineering Documentation Skill

kidoc — 工程文档生成Skill

Quick Start

快速开始

Workflow

工作流程

Document Types

文档类型

Custom Reports

自定义报告

Schematic and PCB Rendering

原理图与PCB渲染

Generate all figures (diagrams + schematic/PCB renders) from analysis JSON

Generate all figures (diagrams + schematic/PCB renders) from analysis JSON

Full orchestration with spec, analysis, and project files

Full orchestration with spec, analysis, and project files

Block Diagrams

层预设

Output Formats

框图

Configuration

输出格式

Writing Narratives

配置

Workflow

编写叙述内容

Style Guide

工作流程

Requirements

风格指南

Limitations

要求

Related Skills

局限性

相关Skill