skills-win/kicad-flow/references/nodes.md

kicad-flow 逐节点执行指引

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

& $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。

嵌套结构用 --json：

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

kind 取 board / refdesign / datasheet / spec。

这是回环节点：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）— 靠仿真还是靠补料

缺依据的模块里，哪些是仿真能定下来的（滤波器、环路补偿、阻抗匹配、 分压与容差），哪些是只有用户才知道的（选型偏好、接口协议、机械约束）？

前者 --set need_simulation=true 走 n09，后者 false 走 n13。

两类都有就先走仿真（能自己解决的先解决），下一轮回到 d04 时再判 false 去要料。

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）— 要用户补料

必须问用户本人。 明确说清：哪些模块既没有可照抄的参考设计、也不适合靠仿真定， 需要他补哪一类材料。要具体到模块和材料类型，别只说「资料不够」。

用户补完：--set supplied=true --set note="补了 NTC 的 datasheet 和选型表"

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

---

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

n10_draw_schematic（10）— 画 KiCad 原理图

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

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_wires_crossing_symbols、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）

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_clean（20）— 派 agent 复核排版

派一个单独的 agent 独立复核排版。

这里 true = 干净、往前走（和 d11 正好相反）。 原图节点文字写的是「是否有排版问题」，但边标签是「是→前进」， 二者矛盾，已由用户裁定以边标签为准。填之前想一秒。

仍有问题回 n19 继续修（上限 3 次）。

回填：--set layout_clean=true

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

sync_schematic_to_board 把原理图导入 PCB（器件带封装落板）。导入后确认器件数与 网表数与原理图一致（get_component_list、get_nets_list）。

PCB 的布局/布线/DRC 不属于本流程，导入成功即收工。

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