sync: WIN10-I9-64G 2026-09-19

kicad-flow/references/nodes.md

@@ -0,0 +1,296 @@
+# 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。
+
+嵌套结构用 `--json`：
+
+```powershell
+& $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`