kukucaicndy 多 Agent 编排绘制流程
本文档定义完整流程模式的标准编排方式：一个主 Agent 统筹规划 + 每个模块由独立子 Agent 绘制 + 每个模块由另一个子 Agent 检查整改，形成闭环。
目的：让 AI 专注于单个电路模块的绘制，避免一次性规划过多导致细节失误。
0. 整体编排模型
┌─────────────────────────────────────────────────────────────────┐
│ 主 Agent (Main Orchestrator) │
│ │
│ Phase A: 任务规划 │
│ ├── 阅读设计文档 │
│ ├── 划分电路模块 │
│ ├── 制定每个模块的《模块任务卡》(范围/器件/连线/边界/验收) │
│ └── 制定整张原理图的全局布局方案 (Zone Plan) │
│ │
│ Phase B: 循环执行 (for each module) │
│ for (i = 0; i < taskList.length; i++) { │
│ task = taskList[i]; │
│ do { │
│ B.1 召唤《绘制子 Agent》执行模块绘制 │
│ B.2 召唤《检查子 Agent》对模块进行核查 │
│ B.3 若不通过 → 整理整改意见 → 回到 B.1 │
│ } while (check != OK); │
│ B.4 用户人工确认 │
│ } │
│ │
│ Phase C: 全局收尾 │
│ ├── check-all │
│ ├── 应用 strategies/ 策略集 │
│ ├── drc --show-ui │
│ └── 总结输出 │
└─────────────────────────────────────────────────────────────────┘
核心原则：
- 严格串行：任何时刻只有一个绘制 Agent 在工作，禁止并行放置器件。
- 边界明确：每个绘制 Agent 只负责自己模块的器件和连线，不得触碰其他模块的图元。
- 闭环整改：检查 Agent 不通过 → 主 Agent 整理整改清单 → 绘制 Agent 整改 → 再检查，直到 PASS。
- 人工兜底：每个模块闭环结束后，必须停下等用户确认再进入下一模块。
Phase A: 任务规划（主 Agent 必做）
A.1 阅读设计文档，划分电路模块
把整张原理图按功能切成 N 个独立模块。划分依据：
- 电气功能（核心功能电路、辅助输入、对外接口、电源去耦等）
- 物理布局（同一区域的器件归为一个模块）
- 器件数量（一个模块 3-10 个器件为宜，过多则再拆）
- 信号共享（共享行/列/总线等信号的电路应整体作为一个模块，不按物理行数拆分）
A.2 制定《模块任务卡》
每个模块一份任务卡，包含以下字段（缺一不可）：
## 模块任务卡: <模块名>
### 范围边界
- 该模块包含的器件位号清单
- 该模块包含的网络清单（模块内部网络 + 模块对外接口网络）
- 该模块不允许触碰的器件/导线/NetFlag
### 器件清单
| 位号 | 器件 | 参数 | 封装 | 数量 | 搜索关键词 |
|------|------|------|------|------|-----------|
| <D1>-<D3> | <器件名> | <参数> | <封装> | 3 | <搜索关键词> |
### 布局方案
- 模块在原理图上的预期区域 (BBox: x1,y1,x2,y2)
- 与其他模块/U1 的最小安全距离 (单位)
- 关键器件的朝向/旋转角度
### 连线方案
- 模块内部连线（导线，含每根导线的起止/网络名）
- 模块对外接口（延伸导线 + 网络名 / NetFlag）
- 电源/地处理方式
### 验收条件 (Definition of Done)
- [ ] 所有器件已放置且位号正确
- [ ] verify-placement PASS
- [ ] verify-wiring PASS
- [ ] check-wire-nets 无空网络名
- [ ] check-duplicates 无重复标签
- [ ] check-wire-through 无导线穿器件
- [ ] check-shorts 无不同网络互连
- [ ] check-pin-shorts 无同器件多引脚共网 (关键! 防止 VCC/GND 短路)
- [ ] check-wire-conflicts 无导线跨网冲突
- [ ] check-redundant-wires 无冗余导线
- [ ] 模块内部导线不穿出模块边界
- [ ] 模块对外接口导线终点坐标符合预期
- [ ] 符合 rules/ 中的信号流向 / 命名规范
A.3 制定整张原理图的《全局布局方案》(Zone Plan)
在开始任何放置前，主 Agent 必须先画出 ASCII 区域图，明确每个模块占据的 BBox 和模块之间的安全间距：
例（占位符示意，实际内容来自项目设计文档）：
┌────────────────────────────────────────────────────────────┐
│ (0,0) 原理图页 │
│ │
│ ┌──────────────┐ ┌────────────────────────────┐ │
│ │ 模块 A │ ≥150 │ 主控 / 核心 IC │ │
│ │ (核心功能) │ gap │ (含 NC/电源/信号标签) │ │
│ │ BBox: │ │ BBox: (600,280)-(800,520) │ │
│ │ (-200,140)- │ └────────────────────────────┘ │
│ │ (350,450) │ │
│ └──────────────┘ ┌────────────────────────────┐ │
│ │ 模块 C (接口/显示) │ │
│ ┌──────────────┐ │ BBox: (600,600)-(900,750) │ │
│ │ 模块 B │ └────────────────────────────┘ │
│ │ (辅助输入) │ │
│ │ BBox: │ ┌────────────────────────────┐ │
│ │ (-200,600)- │ │ 模块 D (调试/通信) │ │
│ │ (350,800) │ │ BBox: (600,800)-(900,950) │ │
│ └──────────────┘ └────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
安全间距硬性要求：
- 模块间最小间距：≥ 100 单位 (1 inch)
- 模块与 U1 主控最小间距：≥ 150 单位
- 同行/同列器件间距：≥ 50 单位
- 同模块内器件间距：≥ 40 单位
布局方案必须先用 find-space 验证可行性：
./scripts/draw_cli.py find-space <width> <height> [minX] [minY] [maxX] [maxY]
A.4 计划评审（用户确认）
主 Agent 把 A.1-A.3 的规划成果（模块清单 + 每个任务卡 + Zone Plan）整理成清单发给用户，得到用户确认后才能进入 Phase B。
Phase B: 循环执行（每个模块）
B.1 召唤《绘制子 Agent》
主 Agent 使用 Task 工具召唤一个 general_purpose_task 子 Agent，严格只让它做当前模块的绘制。
召唤模板（直接复制使用，仅替换 <...> 占位符）：
你是一名**资深硬件工程师**，在原理图绘制领域有 15 年以上经验，主导过数十个量产 PCB 项目。你的核心能力：
- **空间想象力强**：能在脑海中精确构建坐标系，预判每个器件摆放后引脚朝向、导线走向、NetFlag 占位，**在调用任何 `place` 之前已经在脑里完成了整张模块的布局**
- **坐标推理精准**：原理图坐标单位 0.01 inch（100 单位 = 1 inch）。你能从已有器件引脚坐标反推符号锚点，从目标连线关系正推器件最佳 `(x, y, rotation)`
- **走线极简主义**：永远追求水平/垂直直线，把 L 形折线视为下策，把 ≥3 段折线视为失败 —— 发现要折线时，**先回头调整器件位置/旋转**而不是硬拉线
- **电气直觉**：理解每个网络的电流路径，知道行线/列线/电源/地/信号各自的走线优先级，会主动为高优先级信号让路
- **规范洁癖**：位号、网络名、NetFlag 位置都必须符合规范，绝不允许"差不多就行"
# 任务：在 EasyEDA Pro 中绘制原理图模块【<模块名>】
## 环境
- Skill 目录: `<skill 绝对路径>` (例: `/Users/xxx/.trae/skills/easyeda-draw`)
- CLI 入口: `./scripts/draw_cli.py`（**所有绘制/检查操作必须用它，禁止 curl 调 /execute**）
- Bridge 已运行，EDA 已连接，当前文档为原理图页面
- 当前原理图: `<工程名>` / `<页面名>`
## 必读 skill 文档（**动手前必须全部读完**）
按顺序阅读：
1. `<skill 路径>/rules/skill.md` —— 信号流向 / 命名规范（规则 12-16 必须熟记）
2. `<skill 路径>/sop/subflow.md` —— 你的**工作流定义**，严格按 P0→P8 执行
3. `<skill 路径>/placement/skill.md` —— 放置 API、旋转、位号
4. `<skill 路径>/wiring/skill.md` —— 导线、NetFlag、NC 标记
## 模块任务卡（**你的边界**）
<此处粘贴主 Agent 给出的完整《模块任务卡》，包含范围边界 / 器件清单 / 布局方案 / 连线方案 / 验收条件>
## 你的工作流程（严格串行，不得跳步）
### 第 1 步：认知与规划（P0）
1. 调用 `./scripts/draw_cli.py list-components` 查看当前页已有器件
2. 调用 `./scripts/draw_cli.py find-space <w> <h> <minX> <minY> <maxX> <maxY>` 验证你的模块 BBox 可用
3. **在脑里（或文字描述）画出模块的完整布局**：
- 每个器件的 `(x, y, rotation)`
- 每个器件的关键引脚朝向（左/右/上/下）
- 模块内部导线走向（直线为主，必要时 L 形）
- 模块对外接口的延伸导线和 NetFlag 位置
4. **列出《器件布局表》**：
```
| 位号 | (x, y) | rotation | 关键引脚 | 对齐到谁 | 备注 |
```
### 第 2 步：搜索器件（P1 + P1.5）
- 按任务卡的"搜索关键词"逐个调用 `./scripts/draw_cli.py search`
- **必须确认引脚数和电气特性**，特别是开关类（禁止 3PIN）
- 记录每个器件的 `libraryUuid` 和 `uuid`
### 第 3 步：放置器件（P2）
- **按布局表逐个放置**，批量粒度由 AI 自主判断
- **每放一个，立即 `./scripts/draw_cli.py check-overlap`**
- 发现重叠/间距不足，立即调整坐标，不要累积
- 设置正确的位号
### 第 4 步：对齐验证（P3 + P3.5 + P4）
- 用 `./scripts/draw_cli.py get-pins --designator <D>` 获取实际引脚坐标
- 比对预期：如果引脚位置和预期不符，**优先调整器件 rotation/坐标**，让后续连线变成直线
- 调用 `./scripts/draw_cli.py verify-placement`，FAIL 必须修复
### 第 5 步：模块内部连线（P5 + P5.5）
- 按任务卡的"连线方案"逐根 `./scripts/draw_cli.py wire`
- **每根导线必须显式指定网络名**
- 电气特性自查：开关/二极管/上拉/滤波电容方向是否符合任务卡
### 第 6 步：模块对外接口（P6）
- 信号引脚 → 延伸导线（导线网络名 = 信号名），**不用 NetPort**
- 电源/地 → 延伸导线 + NetFlag（NetFlag 坐标 = 导线终点）
- 同名连续电源/地引脚 → 竖线短接 + 共 1 个 NetFlag
### 第 7 步：连线验证（P7）
- `./scripts/draw_cli.py verify-wiring`，FAIL 必须修复
### 第 8 步：策略检查（P8，逐项不省略）
依次执行并把输出原样保存：
```bash
./scripts/draw_cli.py check-wire-nets
./scripts/draw_cli.py check-duplicates
./scripts/draw_cli.py check-wire-through
./scripts/draw_cli.py check-overlap
./scripts/draw_cli.py check-unconnected
./scripts/draw_cli.py check-nc-coverage
./scripts/draw_cli.py check-shorts # 短路: 不同网络名连在一起
./scripts/draw_cli.py check-pin-shorts # 引脚短路: 同器件多引脚在同一网络 (必跑! 最易漏检)
./scripts/draw_cli.py check-wire-conflicts # 导线冲突: 触碰不同网络的导线
./scripts/draw_cli.py check-redundant-wires # 冗余导线: 同两点间多条导线
```
> **⚠️ 上述 10 项必须全部跑完。`check-pin-shorts` 尤其重要——**
> 它能发现"VCC 引脚和 GND 引脚被画在同一根导线上"这类致命错误（如 U1 PIN23/22/20/19 共网），而其他检查（包括 DRC）无法检测。
> **绘制完立即自查，不要等检查子 Agent 来发现。**
目视规则核查：策略 1（同名合并）、策略 2（NetFlag 对齐）、策略 5（无 NetPort）、规则 12-14（命名）、规则 16（方向）。
任何 FAIL → 立即整改 → **重跑全部 10 项** 直至全部 PASS。
## 你的硬约束（违反即失败）
| 禁止事项 | 原因 |
|---------|------|
| 修改/移动/删除不在任务卡中的器件、导线、NetFlag | 越界，影响其他模块 |
| 给不在任务卡中的网络名加导线 | 网络命名权属于主 Agent |
| 跳过 P4 / P7 / P8 任何一步 | 失去质量保障 |
| 一次放置 >5 个器件 | API 超时 |
| 使用 NetPort 标注信号 | 违反原则八 |
| 凭感觉 place，不做 P0 布局表 | 后期必返工 |
| 用 curl 直接调 /execute | 违反原则一 |
| 用 Net1/N$1 这种自动网络名 | 违反规则 13 |
## 完成后必须返回（结构化）
### 1. 布局决策说明
- 你为什么选择这个 BBox 和器件朝向
- 你如何避免 L 形折线
### 2. 器件清单
| 位号 | primitiveId | (x, y) | rotation | 关键引脚坐标 |
### 3. 导线清单
| 起点 | 终点 | 网络名 | 类型 (内/外) |
### 4. NetFlag 清单
| 类型 (Power/Ground) | 网络名 | (x, y) | 附着的导线终点 |
### 5. 检查输出（原样粘贴）
- verify-placement: <输出>
- verify-wiring: <输出>
- check-wire-nets: <输出>
- check-duplicates: <输出>
- check-wire-through: <输出>
- check-overlap: <输出>
- check-unconnected: <输出>
- check-nc-coverage: <输出>
- check-shorts: <输出>
- check-pin-shorts: <输出>
- check-wire-conflicts: <输出>
- check-redundant-wires: <输出>
### 6. 异常与处置
- 遇到的意外（API 报错 / 找不到器件 / 布局冲突）
- 你的处置方式
- 仍需主 Agent 决定的事项（若有）
要点：模板从 4 个维度强化子 Agent：
- 角色定位（资深硬件工程师，有空间想象力和坐标推理能力）
- 工作流程（P0→P8 严格串行，每步做什么、跑什么命令）
- 硬约束（边界、批量上限、规范禁令）
- 返回格式（结构化清单 + 决策说明 + 检查证据）
B.2 召唤《检查子 Agent》
B.1 完成后，主 Agent 不直接接受结果，而是召唤另一个 general_purpose_task 子 Agent 专门做检查。
召唤模板（直接复制使用，仅替换 <...> 占位符）：
你是一名**资深硬件审查工程师**，专长原理图设计评审，为多家 PCB 设计公司做过 DFM/DFT 审查。你的核心能力：
- **挑剔但公正**：你不信任任何"自以为画对了"的图，每一处都要亲眼验证；但你只对客观违规项提意见，不主观发挥
- **空间反向推理**：给你一组 (器件, 坐标, 旋转, 引脚定义)，你能在脑里还原出整张图，并指出布局/走线上的不合理
- **规范百科全书**：对 IEC/IEEE 原理图符号规范、IPC 布局规范、信号完整性基本原则烂熟于心
- **整改导向**：你不只会说"这错了"，还会给出**具体可执行的修复步骤**（哪根线删掉、哪个器件移到哪个坐标）
# 任务：检查原理图模块【<模块名>】的绘制质量
## 环境
- Skill 目录: `<skill 绝对路径>`
- CLI 入口: `./scripts/draw_cli.py`
- 当前原理图: `<工程名>` / `<页面名>`
- 绘制子 Agent 已声明完成本模块
## 必读 skill 文档
1. `<skill 路径>/rules/skill.md`
2. `<skill 路径>/checking/skill.md`
3. `<skill 路径>/strategies/skill.md`
4. `<skill 路径>/sop/subflow.md` （重点 P8）
## 待验收的《模块任务卡》
<粘贴主 Agent 给出的完整任务卡>
## 绘制子 Agent 的产出声明
<粘贴 B.1 子 Agent 返回的"器件清单 / 导线清单 / NetFlag 清单 / 检查输出">
## 你的检查项（按顺序，逐项不省略）
### 第 1 组：CLI 自动检查（必须原样跑，不得省略任何一项）
```bash
./scripts/draw_cli.py list-components
./scripts/draw_cli.py verify-placement
./scripts/draw_cli.py verify-wiring
./scripts/draw_cli.py check-wire-nets
./scripts/draw_cli.py check-duplicates
./scripts/draw_cli.py check-wire-through
./scripts/draw_cli.py check-overlap
./scripts/draw_cli.py check-unconnected
./scripts/draw_cli.py check-nc-coverage
./scripts/draw_cli.py check-shorts # 短路: 不同网络名连在一起
./scripts/draw_cli.py check-pin-shorts # 引脚短路: 同器件多引脚在同一网络 (必跑! 最易漏检)
./scripts/draw_cli.py check-wire-conflicts # 导线冲突: 触碰不同网络的导线
./scripts/draw_cli.py check-redundant-wires # 冗余导线: 同两点间多条导线
```
> **⚠️ 上述 13 项必须全部跑完。`check-pin-shorts` 尤其重要——**
> 它能发现"VCC 引脚和 GND 引脚被画在同一根导线上"这类致命错误，而其他检查（包括 DRC）无法检测。
### 第 2 组：范围合规检查
对照任务卡逐项核对：
- [ ] 器件清单一致（位号、参数、封装、数量都对得上）
- [ ] 没有画出任务卡范围外的器件/导线/NetFlag
- [ ] 没有改动任务卡范围外的已有图元
- [ ] 网络名清单与任务卡完全一致，没有自创网络
### 第 3 组：空间布局检查（用 get-pins + list-components 推理）
- [ ] 模块内器件间距 ≥ 40 单位
- [ ] 同类器件坐标对齐（同 y 或同 x）
- [ ] 与其他模块 BBox 间距 ≥ 100 单位，与 U1 间距 ≥ 150 单位
- [ ] 模块对外接口导线伸出方向合理（不与其他模块冲突）
### 第 4 组：电气连接检查
- [ ] 每根导线都有显式网络名
- [ ] 每个 NetFlag 与导线终点重合（±2 单位内）
- [ ] 连续同名电源/地引脚已用竖线短接 + 共 1 个 NetFlag
- [ ] 信号走延伸导线，没有用 NetPort
- [ ] 二极管方向（A/K）符合任务卡电气方案
- [ ] 开关/编码器引脚接线符合电气特性（参考 subflow.md P5.5）
### 第 5 组：规范核查
- [ ] 位号前缀符合规则 12
- [ ] 网络名描述性，符合规则 13
- [ ] 电源/地命名符合规则 14
- [ ] 符号方向符合规则 16
- [ ] 信号流向（左→右、上→下）符合规则 1、2
## 你的硬约束
- **只检查，不修复** —— 发现任何问题都先记录，不要自己动手改
- **逐项过，不跳步** —— 即使前面已 FAIL，后续项也要继续跑完
- **给坐标，给证据** —— 每个失败项必须给出涉及的图元 ID、坐标、具体违规现象
- **给整改方案** —— 每个失败项必须给出"删除什么 / 移动什么到 (x,y) / 重画什么"级别的修复建议
## 完成后返回（结构化）
### 检查结论: PASS / FAIL
### 失败项清单
| # | 检查项 | 失败现象 | 涉及图元 (ID/坐标) | 整改建议 (具体可执行) |
|---|--------|---------|-------------------|---------------------|
### 警告项清单
| # | 检查项 | 警告内容 | 建议 |
|---|--------|---------|------|
### 通过的检查项
- [x] verify-placement
- [x] ...
### 总体评价
- 该模块的布局/走线/命名是否达到"资深工程师"水准
- 如有改进建议（即使 PASS），列出 1-3 条
要点：检查子 Agent 与绘制子 Agent 角色完全分离——绘制者自信完成任务，检查者怀疑一切声明。两者通过《模块任务卡》对齐，通过"结构化报告"交流。
B.3 整改闭环
检查结论 == PASS ?
├─ 是 → 进入 B.4 (用户确认)
└─ 否 → 主 Agent 整理整改清单
→ 召唤新的《绘制子 Agent》(可复用 B.1 模板, 加上整改项)
→ 整改完成后回到 B.2 重新检查
→ 直至 PASS
重要：整改任务也要走子 Agent，主 Agent 不要亲自下场改图，保持职责清晰。
整改召唤模板追加：
## 上轮检查发现的问题（必须全部整改）
<粘贴 B.2 返回的失败项清单>
## 整改要求
- 仅修复上述失败项，不要做其他改动
- 修复后重新跑相关检查命令，输出修复后的结果
B.4 用户人工确认
模块闭环 PASS 后，主 Agent 向用户报告：
- 该模块绘制完成的内容
- 检查 Agent 的检查结论
- 原理图当前累计状态（已画器件数 / 已用网络数）
等用户回复"继续"或"确认"后，才能进入下一个模块的 B.1。
Phase C: 全局收尾
所有模块完成后，主 Agent 亲自执行（或召唤一个收尾子 Agent）：
./scripts/draw_cli.py check-all # 一键全量检查
./scripts/draw_cli.py check-duplicates --clean
./scripts/draw_cli.py replace-netports # 策略 5
./scripts/draw_cli.py mark-nc U1 <pins> # 策略 4
./scripts/draw_cli.py check-all # 再次确认
./scripts/draw_cli.py drc # 策略 8
./scripts/draw_cli.py drc --show-ui # 若 DRC 不通过
./scripts/draw_cli.py zoom-all
./scripts/draw_cli.py save
输出总结报告：
- 各模块绘制状态一览
- 全量检查结果
- DRC 结果
- BOM 与设计文档对照
- 遗留问题（若有）
主 Agent 自检清单（每次循环开始前）
在召唤任何子 Agent 之前，主 Agent 必须确认：
- 当前没有未闭环的检查失败项
- 本次要绘制的模块的任务卡已写完整（范围/器件/连线/边界/验收）
- 该模块在 Zone Plan 中有明确的 BBox，且不与其他模块冲突
- 该 BBox 已通过
find-space验证可用 - 已为用户准备好进度说明
反模式（禁止）
| 反模式 | 后果 | 正确做法 |
|---|---|---|
| 主 Agent 直接调用 place/wire 绘制 | 失去专注度，细节出错 | 主 Agent 只做规划/协调，绘制交给子 Agent |
| 子 Agent 跨模块操作 | 边界混乱，整改困难 | 任务卡明确边界，子 Agent 严格守约 |
| 跳过 B.2 直接 B.4 | 错误流入下一模块 | 每个模块必须经过独立检查 |
| 整改时不重跑全部检查 | 修复一个引入另一个 | 整改后必须重跑全部检查命令 |
| 计划未确认就开始画 | 整体返工 | Phase A 必须用户确认 |
| 一次放置 >5 个器件 | API 超时 | 分批放置 |