# kicad-flow 逐节点执行指引

`action` 字段对应下面的小节。括号里的数字是 `Notes\PR00.drawio` 的 cell id。
回填命令一律省略前缀，完整形式是：

```powershell
& $PY $KF resume --prj-dir "<工程目录>" --set <下面写的>
```

---

## 阶段一：框图与资料

### `n02_intake_requirement`（2）— 读需求

需求 md 在 `<工程>\Notes\` 根目录下，由用户手写。payload 的 `candidates` 已经把
该目录下的 md 列好了；多于一份就问用户哪份是需求。

读完把要点摘成一段 —— 这段会一路带到 `d22`，作为「是否符合原始需求」的判据，
所以要**摘需求本身，不要摘你打算怎么做**。

回填：`--set requirement_md="<绝对路径>" --set requirement_summary="<摘要>"`

### `n03_draw_block_diagram`（3）— 画电路框图

用 drawio MCP（`new_diagram` → `add_nodes` → `link_nodes`）画功能框图，存
`<工程>\Notes\`。payload 的 `suggested_path` 给了建议落点。

框图的用途是**划分出可独立验证的功能模块**，不是画电路图。每个模块块里写清：
模块名、关键器件与型号、关键参数、可独立验证的判据。连线上标信号名与电平。

返工时（`retry > 0`）payload 里有上一轮用户的意见，照着改，别重画一版一样的。

> 文件名用 payload 的 `suggested_path`（`.drawio`），**不要**听 `new_diagram`
> 参数说明里的「should end with `.drawio.svg`」—— 那会让后面 `n18`/`d21` 对不上路径。
> 写出来的文件是 SVG 外壳 + 压缩的 mxfile（哪怕扩展名是 `.drawio`），直接 `Read`
> 看不了。要核对内容用 `drawio_read.py --summary`。

回填：`--set drawio_path="<绝对路径>"`

### `d07_confirm_partition`（7）— 用户确认划分

**必须问用户本人。** 把每个模块讲一遍（模块名 + 它负责什么 + 怎么独立验证），
请他确认划分是否正确。

用户说不对就 `--set partition_ok=false`，图回到 `n03` 重画（最多 3 次）。
把他的具体意见也带上：`--set partition_ok=false --set feedback="电源划分太粗"`。

回填：`--set partition_ok=true`

### `n08_collect_references`（8）— 参考资料整理

逐模块登记五类资料：① 开发板资料 ② 参考设计（KiCad/Altium 工程）③ 器件 datasheet
④ 子电路设计描述 md ⑤ 原理仿真结果。前四类是用户给的，第五类多半来自本流程 `n09`
自己跑出来的结论（payload 的 `sim_results` 里）。

嵌套结构用 `--json`：

```powershell
& $PY $KF resume --prj-dir "<工程>" --json '{"references":[{"module":"PWR","kind":"refdesign","path":"E:\\ref\\foo","note":"LDO 部分可整段照抄"}]}'
```

`kind` 取 `board` / `refdesign` / `datasheet` / `spec` / `sim`。

这是回环节点：`n09`（仿真完）和 `n13`（用户补料完）都会回到这里再整理一轮，
payload 的 `retry` 和 `sim_results` 告诉你上一轮发生了什么，**把新增的并进来**，
不要只报新的。

### `d04_have_reference_or_sim`（4）— 每个模块都有依据吗

逐个比对框图模块与已登记资料：每个模块是否都能找到**可直接照抄的参考设计**，
或**已有可参考的仿真结果**？只要有一个模块两者皆无就判 false。

判 true 直接进 `n10` 开画。判 false 进 `d05` 决定走仿真还是要料。

回填：`--set have_reference_or_sim=true`
（判 false 时把缺依据的模块带上：`--json '{"have_reference_or_sim":false,"uncovered":["LPF","ANT"]}'`）

### `d05_need_simulation`（5）— 用户要求过仿真吗

> **判据是「用户有没有明确要求」，不是你觉得该不该仿。** 原图节点上写着
> 「一般是用户明确要求仿真」。

翻需求 md 和此前的对话，找用户是否点名要对某个模块做仿真（「这级滤波器仿一下」、
「环路补偿要仿真确认」之类）：

- 找得到 → `--set need_simulation=true`，走 `n09` 跑仿真
- **找不到 → `--set need_simulation=false`**，走 `n13` 去要材料

**不要因为你自己觉得仿一下更稳妥就判 true。** 真心认为该仿的，到 `n13` 里
向用户提议，由他决定；他同意了，下一轮 `d05` 自然就是 true。

### `n09_run_spice_sim`（9）— 原理仿真

用 simetrix MCP：`open_schematic`/`add_component` 建电路 → `set_analysis_lines`
设分析 → `run_simulation` → `measure_waveform` 量指标 → `export_waveform_csv` 存证。

**仿真结论要能直接支撑取值**（「R=10k 时纹波 12mV，满足 <20mV」），
不是「仿了，看着还行」。

回填：`--json '{"sim_results":[{"module":"LPF","conclusion":"fc=1.2kHz，阻带 -42dB","evidence":"<csv 路径>"}]}'`

做完自动回 `n08`（`material_retry` +1，上限 5）。

### `n13_prompt_more_material`（13）— 要用户补料

**必须问用户本人。** 走到这里是因为：有模块缺设计依据，而用户并没有要求对它们做仿真。

说清缺依据的是哪些模块、需要他补哪一类材料（开发板资料 / 参考工程 / datasheet /
子电路设计描述 md）。**要具体到模块和材料类型**，别只说「资料不够」。

**这里也是提议仿真的出口**：你要是判断某个模块用原理仿真就能定下来，在这里提给用户，
由他拍板。他同意，下一轮 `d05` 就判 true 去跑仿真。

用户答复后：`--set supplied=true --set note="补了 NTC 的 datasheet；同意对 LPF 做仿真"`

做完自动回 `n08`（`material_retry` +1，上限 5）。

---

## 阶段二：原理图与平台校验

### `n10_draw_schematic`（10）— 画 KiCad 原理图

用 kicad MCP 按框图逐模块画。能照抄的照抄，仿真定的取值照搬。
**drawio 框图作为插图放在原理图第一页** —— 这是流程的硬要求，`d21` 会查。

> **分立器件必须归入子电路，不许单独归堆**（bmem 全局规则 G-0037）。
> 阻容等分立器件要和它服务的芯片电路画在一起组成子电路：去耦电容画在对应电源引脚旁、
> 上下拉电阻画在对应信号引脚旁、分压/RC 网络与它所属的采样或接口电路画在一起 ——
> **不要**把所有 R/C 归堆丢在图纸角落。子电路的摆放布局尽量与该芯片 datasheet 的
> 典型应用电路或参考设计保持一致，便于逐项比对、便于照抄取值，也便于后面 `n101`
> 导入 PCB 后直接沿用这层就近关系。

首选 `scripts\schgen` 脚本库生成（见 schgen/README.md，示例 `E:\Kicad_design\DVBS2_dmod\carrier\gen\gen_sch.py`）：
自带重叠/越界、子电路、ERC、网表器件数检查，封面框图由 `schgen.diagram` 渲染、`schgen.root` 嵌入。
零星修改才用 MCP 的 `batch_add_and_connect` / `batch_add_components` / `batch_connect`。

这是三条回环的汇合点，payload 会告诉你这轮为什么回来：
- `fix_plan` 非空 → `d22` 判了不符合需求，**逐条按方案返工**
- `layout_retry` 涨了 → `d11` 判了排版有问题
- `mcu_retry` 涨了 → `d17` 判了 MCU IO 不对，管脚要改

回填：`--set schematic_path="<.kicad_sch 绝对路径>"`

### `d11_layout_issue`（11）— 排版检查

三条判据：① 信号标签与线段/字体/器件重叠 ② 字体与器件、线段重叠 ③ 电路落在图框外。

工具：`find_overlapping_elements`、`find_wires_crossing_symbols`、
`find_orphaned_wires`、`get_schematic_view` 逐页看、`get_board_extents` 对框。

> **这里 true = 有问题**（回 `n10` 重排，上限 5 次）。与 `d20` 同极性。

回填：`--set layout_issue=false`

### `d12_has_fpga`（12）/ `d16_has_mcu`（16）— 板上有没有

看框图和原理图。有就走对应的平台校验支路，没有就跳过。
`--set has_fpga=true --set part="xc7a200t"`

### `n14_build_vivado_probe`（14）— 建验证性 Vivado 工程

用 vivado-mcp 建一个**简单但接口完整**的工程，目的是验证原理图上的管脚约定站得住，
不是实现功能。必须覆盖：

1. 管脚分配
2. 管脚所在**供电 bank**（IO 电平与 bank 电压是否自洽）
3. 时钟输入/输出，以及内部 PLL 的使用要求（时钟必须进时钟专用脚）
4. 差分对走线要求

Zynq 系列另须核对：MIO/EMIO 分配是否合规、QSPI/eMMC/JTAG 配置是否正确。

`xdc_lint` 和 `verify_io_placement_tool` 先跑一遍，能省一轮实现。

回填：`--set vivado_prj_dir="<工程目录>"`

### `d15_bitstream_ok`（15）— 出得来 bitstream 吗

`run_synthesis` → `run_implementation` → `generate_bitstream`，再看
`get_io_report` 和 `get_critical_warnings`。bitstream 出来**且** IO 摆放合法才算过。

失败回 `n14` 改约束或改管脚（上限 3 次）。把失败原因带上：
`--json '{"bitstream_ok":false,"errors":["Bank 34 电平冲突"]}'`

### `d17_mcu_io_correct`（17）— MCU IO 核对

对着 datasheet 逐脚核原理图上的 IO：SPI/I2C/PWM 等**专用引脚**是否用在支持该复用的
脚上、上拉/开漏要求、电平域、启动引脚（BOOT/NRST）有没有被占用。
STM32 可用 cubemx MCP 的 `get_pin_functions` / `get_pinout` 交叉验证。

> ⚠️ **判 false 会一路退回 `n10` 重画原理图**，FPGA/MCU 校验整段重跑（上限 3 次）。
> 这是原图 edge 88 的明确画法，不是 bug。所以判之前把问题一次找全，
> 别分两轮触发两次长回环。

回填：`--set mcu_io_ok=true`

---

## 阶段三：封装

### `n23_assign_footprints`（23）— 加封装

**动手前先查 bmem 全局记忆里关于封装描述格式的条目** —— 那里记着踩过的坑，
格式写错封装挂不上。

来源优先级（payload 的 `priority` 里也有）：
1. 从参考设计（KiCad/Altium 工程）直接拷贝
2. 按型号或 datasheet 从网上下载并安装
3. 按型号或 datasheet 自己画（`create_footprint`）

脚本化做法：`schgen.fplib.FpLib`（KiCad 自带 python 跑）按位号从参考 `.kicad_pcb` 提取封装，
自画件直接写 `.kicad_mod`；原理图生成脚本里用 `fp_resolver` 按数值查表。
验收：`python -m schgen.check <根图>` 的"封装"一行必须是"全部 N 个器件有封装且引脚/焊盘一一对应"。

`search_footprints` / `list_library_footprints` 找库内现成的，
`search_jlcpcb_parts` 可顺带确认可采购性。

返工轮（`retry > 0`）payload 的 `missing` 就是这轮要处理的器件，别全部重来。

回填：`--set assigned=12 --set note="9 个从参考工程拷，3 个用标准库"`

### `d24_all_footprints`（24）— 派 agent 查封装是否齐

**派一个单独的 agent**，让它独立核查每个器件的 Footprint 字段：是否都已填、
指向的库里是否真的存在该封装、引脚数是否与符号对得上。

独立 agent 是为了不被主线的既有判断带偏 —— 别自己顺手查了就填。

回填：`--json '{"footprints_complete":false,"missing":[{"ref":"U3","part":"XYZ-123"}]}'`

### `d26_ref_has_footprint`（26）— 参考资料里还有吗

针对 `missing` 里的器件再翻一遍参考资料：参考工程的封装库、datasheet 的推荐焊盘图、
开发板资料。找得到就 true（回 `n23` 继续加），找不到就 false（去要用户补）。

每进一次这里 `footprint_retry` +1，上限 5。

### `n25_prompt_footprint`（25）— 要用户补封装

**必须问用户本人。** 说清哪些器件既拷不到也按 datasheet 定不了，请他给厂商封装库、
推荐焊盘图，或明确指定用哪个标准封装。

回填：`--set supplied=true --set note="给了 TI 的 QFN-24 封装库"`

---

## 阶段四：回写与三道复核

### `n18_sync_drawio_back`（18）— 按原理图回写 drawio

原理图画完后，实现常与最初框图有出入。用 drawio MCP 按**当前原理图**更新框图
（补上实际用到的器件/接口/信号名，删掉没实现的），然后把更新后的框图
**重新贴回原理图第一页**的插图位置。

先用 `drawio_read.py --summary` 看现有框图内容，再决定改哪里。

回填：`--set drawio_path="<路径>" --set synced=true`

### `d21_sch_matches_drawio`（21）— 派 agent 比对一致性

**派一个单独的 agent**，只给它两份文件（drawio 与原理图），让它判断：
框图里每个模块在原理图里都有对应实现？模块间连接关系与信号名对得上？
第一页插图是不是最新那版 drawio？

告诉它用 `drawio_read.py --summary` 读框图，否则它会对着 base64 发呆。

不一致回 `n18` 重写（上限 3 次）：
`--json '{"sch_matches_drawio":false,"diffs":["框图有 EEPROM，原理图里没画"]}'`

### `n19_recheck_layout`（19）— 再修一遍排版

回写 drawio、贴插图之后排版会再次被打乱。按同样三条判据再过一遍并**动手修**：
挪标签、挪文字、把越界电路收回图框，必要时 `autoplace_schematic_fields`。

回填：`--set fixed=3 --set note="挪了 3 处标签"`

### `d20_layout_issue`（20）— 派 agent 复核排版

**派一个单独的 agent** 独立复核原理图是否还有 criteria 所列的排版问题。

> 极性与 `d11` **一致**：**true = 有问题 → 回 `n19` 继续修**（上限 3 次），
> **false = 没问题 → 前进 `d22`**。两个节点的回填键都是 `layout_issue`。

回填：`--set layout_issue=false`
（仍有问题：`--json '{"layout_issue":true,"issues":["插图压住 J1"]}'`）

### `d22_meets_requirement`（22）— 派 agent 比对原始需求

**派一个单独的 agent**，只给它**用户最初的需求 md** 和当前原理图 ——
**不要给它中间过程的结论**，避免被带偏。让它逐模块判断：

- 需求里要的功能是否都实现了？
- 实现方式是否满足需求写明的指标/接口/电平/电源约束？
- 有没有需求里没要、却擅自加进来的东西？

不符合会走 `n98` 整理修改方案再回 `n10` 重做（上限 3 次）：
`--json '{"meets_requirement":false,"gaps":["PWR:需求要过流保护，原理图没做"]}'`

### `n98_collect_fixes`（98）— 整理修改方案

把差距整理成**可执行**的方案，每条写清：改哪个模块、改什么、改成什么样、
依据是需求里的哪一句。这份方案会带回 `n10` 指导返工。

回填：`--json '{"fix_plan":[{"module":"PWR","change":"加 PTC + 过流比较器","basis":"需求 §2.3 短路保护"}]}'`

### `n93_schematic_done`（93）— 无 interrupt

图自己写完成报告到 `<工程>\.kicad-flow\runs\<thread>\`，直接进 `n101`。

### `n101_import_to_pcb`（101）— 导入 PCB

**用 `schgen.pcbimport`，不要用 MCP 的 `sync_schematic_to_board`**（G-0039）：后者自报 success，
实测 ipots 载板 338/327 封装、191/426 网；DVBS2_dmod 26/60 网（`Net-(...)` 无名网全丢、
多出一个 PWR_FLAG 网、U4 一串焊盘没网）。

```powershell
cd $env:USERPROFILE\.claude\skills\kicad-flow\scripts
& <KICAD_PYTHON> -m schgen.pcbimport <根图.kicad_sch> <工程>\<prj>.kicad_pcb [--layers 4]
```

它从 kicad-cli 网表建一块新板（封装按页排在停车场、挂网），再重新载入**逐焊盘**比对网表，
末行"验收：… 问题 0"才算成功。每次都是重建整块板，布局开始后别再跑。

导入成功后直接进入阶段五（PCB）。

回填：`--set pcb_path="<.kicad_pcb 路径>" --set imported=true`

---

## 阶段五：PCB —— 布局要求 → 布局 → 为布线调整原理图 → 关键线布线

PCB 段在 PR00.drawio 右侧，cell id 形如 `T50IymjQljGLdgGnkx4X-109`，下面只写末尾数字。

**原理图调整是「先试后落」的**：`d140` 只提方案、不动原理图；方案依次过 FPGA
（`d116`→`n118`→`d123`）和 MCU（`d128`→`d132`）两道校验，全过才算通过
（`adjust_status=accepted`），**由 `n183` 真正改原理图并更新到 PCB**。任一道不过即
「调整被拒绝」→ `d148` 想新方案；总尝试次数由 `d144` 卡在 `max_adjust_retry`（默认 3），
超了或想不出新方案都是「放弃调整」（`adjust_status=abandoned`），**按原原理图继续布线，
不是 safety_end**。

### `n109_prompt_pcb_rules`（109）— **要用户**给布局要求 md

**必须拿到用户本人的回答**，不能替他编要求。md 放 `<工程>\Notes\` 根目录（用户手写），
至少覆盖：① 板层设置（层数/叠层/各层用途）；② 阻抗线、差分线、等长线的要求；
③ 线宽、过孔的要求。回到这里时 payload 的 `missing` 是上轮查出的缺项，照着问。

回填：`--set pcb_rules_md="<md 绝对路径>"`

### `d176_pcb_rules_complete`（176）— 布局要求完整吗

逐项核对，而且每项都要是**能直接落成设计规则的数值**（目标阻抗 + 按叠层算出的线宽/间距、
差分对与等长组成员及容差、最小线宽/过孔孔径与焊环）。「按常规」「尽量短」不算。

> false 回 `n109` 再问用户，上限 `max_pcb_rules_retry`（默认 3），超限 safety_end。

回填：`--set pcb_rules_complete=true` 或 `--set pcb_rules_complete=false --json '{"missing":["等长容差"]}'`

### `n110_place_components`（110）— 评估难度并布局

先把板框、叠层、网络类设进 PCB，再评估布局布线难度（BGA/细间距扇出与层数、关键信号走向
与长度、大电流路径、接口器件的板边约束），然后在满足用户要求的前提下**以最有利于布线**
的方式摆件。用 `schgen.pcbplace`（KiCad 自带 python），`check()` 到 0 重叠/出板，
`render()` 出正反面 PNG 目视。难度评估与布局理由写成一份 md。

回填：`--set placement_report="<md 路径>" --set placed=true`

### `d140_need_sch_adjust`（140）— 要不要为布线调整原理图连线

看飞线：FPGA 同 bank 内换脚、MCU 功能换到另一组可复用引脚、连接器/排阻换序、差分对 P/N 对调
这类**只改连接、不改功能**就能明显省层/省过孔/解交叉的地方。**此时先别动原理图**。

回填：`--set need_sch_adjust=false`，或
`--set need_sch_adjust=true --json '{"adjust_plan":[{"ref":"U1","change":"LED0: A5→B6","why":"省两个过孔"}]}'`

### `d144_adjust_over_limit`（144）— 无 interrupt

图自己计数：放行一次 `adjust_retry` +1；已达 `max_adjust_retry` 就判「已超过三次，放弃修改」
直接去 `n159`。

### `d116_need_fpga_pin_change`（116）/ `d128_need_mcu_pin_change`（128）— 方案动没动管脚

只看当前 `adjust_plan`。板上没有 FPGA / MCU 直接回 false。
**`d128` 回 false 就等于本轮方案通过**（FPGA 那道要么没涉及、要么已经过了），下一步 `n183` 落地。

回填：`--set need_fpga_pin_change=true` / `--set need_mcu_pin_change=false`

### `n118_rebuild_vivado_probe`（118）— 按新管脚重建验证工程

优先在 `n14` 建的工程上改 XDC。检查项与 `n14` 相同：管脚分配、供电 bank、时钟与 PLL
（时钟仍在 CC 脚）、差分对；Zynq 另查 MIO/EMIO、QSPI/eMMC/JTAG。

回填：`--set vivado_prj_dir="<工程目录>"`

### `d123_swap_bitstream_ok`（123）— 新管脚下出得来 bitstream 吗

> **false 不回 `n118` 重试**，而是本轮方案被拒 → `d148`。别在这里反复改 Vivado。

回填：`--set bitstream_ok=true` 或 `--set bitstream_ok=false --json '{"errors":["时钟不在 CC 脚"]}'`

### `d132_swap_mcu_io_ok`（132）— 调整后的 MCU IO 对吗

判据同 `d17`（专用脚复用、上拉/开漏、电平域、启动引脚），STM32 可用 cubemx 交叉验证。
**与 `d17` 不同：false 不退回 `n10`**，只是本轮方案被拒 → `d148`。

回填：`--set mcu_io_ok=true` 或 `--set mcu_io_ok=false --json '{"violations":["PB3:JTDO 被占"]}'`

### `d148_have_new_adjust`（148）— 被拒了，还有新方案吗

payload 的 `rejections` 最后一条是被拒原因。避开它能给新方案就回 true 并带新 `adjust_plan`；
想不出就 false —— 放弃调整。

回填：`--set have_new_adjust=false`，或 `--set have_new_adjust=true --json '{"adjust_plan":[...]}'`

### `n183_apply_sch_adjust`（183）— 修改原理图并更新到 PCB 中

只有方案通过（`d128` 否 / `d132` 正确）才会到这里。

1. 按 `adjust_plan` 改原理图连线。schgen 生成的原理图就**改生成脚本重出图**，别手改
   `.kicad_sch` 之后又被脚本覆盖。
2. 更新到 PCB：PCB 已经布局，**绝对不要重跑 `schgen.pcbimport`**（它重建空板，布局全丢），
   只改受影响焊盘的网络并保持器件位置。
3. FPGA 的 XDC 以 `n118` 通过的那版为准。
4. kicad-cli 导出网表与 PCB 逐焊盘核一遍，改过的网络全部一致才回 true。

回填：`--set applied=true --set note="<改了哪些网络>"`（路径变了再加 `schematic_path` / `pcb_path`）

### `n159_collect_critical_nets`（159）— 统计阻抗/差分/等长需求

payload 的 `adjust_status`：

- `accepted` → 方案已由 `n183` 落地，以更新后的网络为准。
- `abandoned` → 原理图不动；若为验证改过 Vivado 工程的 XDC，退回 `n14` 那版。
- `none` → 没调整，直接统计。

然后对照原理图、datasheet 与布局要求 md 统计**所有**阻抗线、差分线、等长线，并在 PCB
里建好对应网络类/差分对规则。

回填：`--json '{"critical_nets":[{"group":"USB","kind":"diff","nets":["USB_DP","USB_DN"],"rule":"90R 5/5mil"}]}'`

### `n167_route_critical_nets`（167）— 关键线布线（流程终点）

按用户布线原则把 `critical_nets` 全部布完（kicad MCP 的 `route_differential_pair` /
`route_trace` 等）：差分对全程耦合、换层配回流过孔、等长组绕到容差内。布完跑 DRC，
关键线相关违规清零，逐组记录实测长度/偏差写进布线报告。普通信号不在本步范围。
图随后写最终报告并结束。

回填：`--set routed=true --set route_report="<md 路径>"`