easyeda-draw-sop

name	easyeda-draw-sop
description	Standard operating procedure for drawing schematics in EasyEDA Pro. Invoke when starting a new schematic drawing task to follow a structured workflow from main components to peripherals.

标准绘制步骤 (SOP)

从主控到外围的标准原理图绘制流程。

原则说明：本文档包含绘制时的操作规范（原则一~十）。绘制后的优化策略见 strategies/。 多 Agent 编排模式见 orchestration/ —— 完整流程模式必读。

---

核心绘制原则 （MUST FOLLOW）

📖 技能快速参考见 SKILL.md

原则零：任务规划先行（新增）

⚠️ 在开始任何放置操作前，必须完成任务规划。

1. 阅读设计文档，划分电路模块
2. 为每个模块写《模块任务卡》（范围边界 / 器件清单 / 布局方案 / 连线方案 / 验收条件）
3. 制定整张原理图的《Zone Plan》（每个模块的 BBox + 模块间最小安全间距）
4. 用 find-space 验证每个模块 BBox 可用
5. 给用户评审计划，得到确认后才开始画

详见 orchestration/ Phase A。

原则一：必须使用 CLI，禁止直接调用 API

⚠️ 禁止使用 curl 直接调用 /execute 端点来进行绘制操作！

所有放置器件、连线、验证操作必须通过 CLI 脚本完成：

./scripts/draw_cli.py <command>

唯一例外：查询/调试操作可以使用 exec 命令。

原则二：逐模块绘制，禁止一次性摆完全部器件

⚠️ 禁止「先摆完全部器件，再统一连线」！

正确方式：每个模块按 子流程 逐步骤完成：搜索 → 放置 → 对齐 → 验证摆放 → 连线 → 验证连线 → 策略检查 → 人工确认

✅ 模块A: 搜索器件 → 摆放 → 对齐 → verify-placement → 连线 → verify-wiring → 策略检查 → 人工确认
✅ 模块B: 搜索器件 → 摆放 → 对齐 → verify-placement → 连线 → verify-wiring → 策略检查 → 人工确认

原则二点五：每个模块由独立子 Agent 绘制（新增）

⚠️ 完整流程模式下，每个模块必须召唤独立子 Agent 完成。

• 主 Agent 只做规划、协调、整改意见整理
• 绘制子 Agent 按《模块任务卡》严格守约（不超出范围边界）
• 检查子 Agent 独立验收，不通过则整改闭环
• 详见 orchestration/ Phase B

原则三：连线遇到困难时，先调整器件位置/方向

如果发现导线需要多段折线（>2段）才能连接，先移动器件使引脚对齐，再画直线。

原则四：每个模块完成后必须人工确认

每完成一个模块的摆放+连线+策略检查，必须停下来让用户确认。用户说"继续"才能进入下一个模块。

原则五：验证必须通过才能继续

摆放后 verify-placement、连线后 verify-wiring，FAIL 须修复后重新验证。

原则六：批量操作粒度由 AI 自主判断

简单重复操作（如放多个相同开关）可批量进行；复杂或高风险操作应分批并逐步确认。防止 API 超时。

原则七：导线必须显式设置网络名

每创建一条导线必须指定网络名，不要让导线网络名留空。

原则八：禁止 NetPort，信号仅用延伸导线

信号引脚：延伸导线-only（导线网络名 = 信号名）。电源/地：延伸导线 + NetFlag。详见 wiring §3。

原则九：绘制完成后必须执行策略集优化

所有模块绘制完毕、check-all 通过后，必须应用 strategies/ 进行系统性优化：

1. 同名电源/地合并
2. NetFlag 终点对齐检查
3. 冗余导线合并
4. NC 未用引脚标注

优化后再次运行 check-all + drc --show-ui。

原则十：放置前必须规划布局（新增）

⚠️ 禁止凭感觉直接 place 一个器件！

每个模块放置前必须：

1. 明确模块的 BBox（来自 Zone Plan）
2. 用 find-space 验证该区域可用：

   ./scripts/draw_cli.py find-space <width> <height> [minX] [minY] [maxX] [maxY]
   

3. 模块间最小间距 ≥ 100 单位；与 U1 主控间距 ≥ 150 单位；同模块内 ≥ 40 单位
4. 放置后立即 check-overlap 确认无重叠

---

逐模块绘制工作流

每个模块的完整流程详见 模块子流程。

验证命令速查

# 摆放一个模块后
./scripts/draw_cli.py verify-placement

# 连线一个模块后
./scripts/draw_cli.py verify-wiring

# 检查引脚覆盖（连线或 NC）
./scripts/draw_cli.py check-nc-coverage

# 全部完成后 一键全量检查
./scripts/draw_cli.py check-all

# DRC 不通过时，打开 EDA 面板查看逐项详细错误
./scripts/draw_cli.py drc --show-ui

DRC 详细错误查看（重要）

⚠️ EasyEDA API 限制：eda.sch_Drc.check() 只返回聚合统计 {type: "fatalError", count: N}， 不返回每个错误的具体信息（器件名、引脚号等）。

查看逐项详细错误的唯一方式：

./scripts/draw_cli.py drc --show-ui

这会呼出 EasyEDA 底部的 DRC 面板，面板中可看到每个错误的器件、引脚、具体描述。

---

参考绘制风格

以本项目的 POWER 页为最佳实践参考：

• 所有导线都有明确的网络名（VBUS、BAT-、VCC_5V、VCC_3V3、VCC_1V8、GND 等）
• 电源/地使用 createNetFlag（Power/Ground），不用 NetPort
• 同一网络的多段导线共享网络名，确保电气连接正确
• 去耦电容靠近对应 IC 放置，连接清晰
• 电源树流向清晰：USB → VBUS → Charge → VBAT → Boost → VCC_5V → LDO → VCC_3V3 / VCC_1V8

---

Step 0: 准备阶段

0.1 确认环境

# 确认当前文档为原理图页面
./scripts/draw_cli.py exec "return await eda.dmt_SelectControl.getCurrentDocumentInfo();"
# 检查 documentType == 1

0.2 清理页面（如需要）

# 清理所有内容（保留标题块）
./scripts/draw_cli.py clear

0.3 任务规划（新增 · 必做）

⚠️ 在开始任何放置前，必须先完成本步，并得到用户确认。

按 orchestration/ Phase A 完成：

1. 划分模块：从设计文档拆出功能模块（矩阵 / 编码器 / OLED / UART / 电源去耦等）
2. 写《模块任务卡》：每个模块一份（范围边界 / 器件清单 / 布局方案 / 连线方案 / 验收条件）
3. 画《Zone Plan》：ASCII 图展示每个模块的 BBox 和模块间安全间距（≥100，与 U1 ≥150）
4. 验证可行性：每个模块 BBox 用 find-space 跑一遍
5. 用户评审：把计划发给用户确认，得到"开始"再进入 Step 1

0.4 规划布局

在图纸上划分功能区域（参考 Zone Plan）：

• MCU 靠右，给外围留空间
• 矩阵/开关在左
• 编码器/按钮在左下
• 接口（OLED/UART）在右下
• 电源去耦在右下角靠近 VCC 引脚

---

Step 1: 放置并连接主控器件

逐模块，每步 CLI。

1.1 搜索主控符号

./scripts/draw_cli.py search "<主控关键词>"

1.2 放置主控

./scripts/draw_cli.py place <libUuid> <deviceUuid> <x> <y> U1 0

1.3 验证摆放

./scripts/draw_cli.py verify-placement

1.4 获取主控引脚

./scripts/draw_cli.py get-pins --designator U1

1.5 为主控引脚添加网络标签

按功能分组，左/右侧分开。按以下策略操作：

策略 A — 信号引脚：从引脚坐标向外延伸导线，导线网络名即信号名。

• 左侧引脚：wire "pinX,pinY,pinX-100,pinY" SIGNAL_NAME
• 右侧引脚：wire "pinX,pinY,pinX+100,pinY" SIGNAL_NAME

策略 B — 电源/地引脚：延伸导线 + NetFlag，NetFlag 坐标 = 导线终点。

• 先 wire "pinX,pinY,endX,endY" VCC，再 netflag Power VCC endX endY

策略 C — 同侧同名电源/地合并：连续的同名引脚（如 GND/GND），先画竖线段短接，再引出一根导线 + 1 个 NetFlag。

• wire "pin1X,pin1Y,pin1X,pin2Y" GND（竖线短接）
• wire "pin1X,pin2Y,pin1X-100,pin2Y" GND（水平引出）
• netflag Ground GND pin1X-100 pin2Y（NetFlag 在终点）

1.6 验证连线

./scripts/draw_cli.py verify-wiring

⚠️ 连线检查必须包含：模块到模块也使用网络标签，禁止连接导线。 如果发现导线两端分别在两个不同功能模块的器件上，必须改用网络标签（NetFlag/NetPort）。

1.7 收集网络标签（供下一个子 Agent 使用）

./scripts/draw_cli.py net-summary

模块完成后必须执行此步骤，将网络标签快照传递给下一个子 Agent。

输出示例：

=== Net Summary (5 nets, 12 points) ===
COL0: 2 wire pts (620,80) (820,80)
ROW0: 1 netport (700,300) + 1 wire pt (620,320)
VCC:  1 netflag (300,100)
GND:  1 netflag (500,400)

下一个子 Agent 收到后，知道哪些网络已存在、在什么坐标，可以正确对接。

🤚 人工确认点 1

用户确认：主控位置是否合适？标签布局是否清晰？确认后在 EasyEDA 中检查。

---

Step 2-N: 绘制外围模块（逐个）

每模块重复以下流程：

# 2.1 搜索此模块的器件
./scripts/draw_cli.py search "关键词"

# 2.2 放置器件
./scripts/draw_cli.py place ...

# 2.3 验证摆放
./scripts/draw_cli.py verify-placement

# 2.4 如果验证失败，调整位置
# ./scripts/draw_cli.py exec "..."  # 移动器件

# 2.5 连线
./scripts/draw_cli.py wire ...
./scripts/draw_cli.py netflag ...

# 2.6 验证连线
./scripts/draw_cli.py verify-wiring

# 2.7 如果连线不理想，调整方向/位置再连线

# 2.8 收集网络标签 (供下一个子 Agent 使用)
./scripts/draw_cli.py net-summary

🤚 每一模块完成后人工确认

在 EDA 中检查，确认后回复"继续"进入下一模块。

推荐绘制顺序

⚠️ 具体顺序由项目设计文档决定，下表是通用原则，不要照抄位号。

顺序	模块类型	说明
1	主控/核心 IC	先放主控，引出引脚标签
2	核心功能模块	项目主体功能电路（如矩阵/传感/驱动等）
3	辅助功能模块	编码器/按钮/指示等辅助输入
4	接口模块	OLED/UART/USB 等对外接口
5	电源去耦	靠近 IC 电源引脚放置
6	NC 标记 + 功能标注	最后添加

模块划分原则：行/列共享的电路（如键盘矩阵）应整体作为一个模块处理，不要按物理行数拆分——拆分会让共享信号（行线/列线）的连线变复杂。是否拆分以"信号是否共享"为准，不以"器件数量"为准。

---

Step N+1: 最终检查

# 全量检查
./scripts/draw_cli.py check-all

# 修复发现的问题
./scripts/draw_cli.py check-duplicates --clean

# 必须执行策略集优化（见原则九）
# 优化后再次 check-all
./scripts/draw_cli.py check-all

# DRC，不通过则打开面板查看详情
./scripts/draw_cli.py drc --show-ui

# 缩放到全局
./scripts/draw_cli.py zoom-all

---

CLI 命令完整参考

搜索/查询

# 搜索器件
./scripts/draw_cli.py search "关键词" 5

# 查询当前页信息
./scripts/draw_cli.py page-info
./scripts/draw_cli.py project-info
./scripts/draw_cli.py list-components
./scripts/draw_cli.py get-pins --designator U1
./scripts/draw_cli.py zoom-all

放置/绘制

# 放置器件
./scripts/draw_cli.py place <libUuid> <uuid> <x> <y> <des> [rotation]

# 添加网络标签（电源/地专用）
./scripts/draw_cli.py netflag Power VCC x y
./scripts/draw_cli.py netflag Ground GND x y

# 标记 NC（未使用引脚，使用原生 API 而非文本）
./scripts/draw_cli.py mark-nc U1 14
./scripts/draw_cli.py mark-nc U1 14,16

# 绘制导线
./scripts/draw_cli.py wire "x1,y1,x2,y2" NET_NAME

# 清理
./scripts/draw_cli.py clear

验证/检查

./scripts/draw_cli.py verify-placement
./scripts/draw_cli.py verify-wiring
./scripts/draw_cli.py check-overlap
./scripts/draw_cli.py check-duplicates
./scripts/draw_cli.py check-duplicates --clean
./scripts/draw_cli.py check-wire-nets
./scripts/draw_cli.py check-unconnected
./scripts/draw_cli.py check-all
./scripts/draw_cli.py drc
./scripts/draw_cli.py drc --show-ui

---

常见问题与修复

问题	现象	修复方式	CLI 命令
导线无网络名	check-wire-nets 检出无 net 导线	删除重画，指定网络名	delete-wires + wire
标签重复	同一坐标 2 个标签叠加	自动清理	check-duplicates --clean
器件重叠	verify-placement FAIL	移动器件	exec 移动代码
DRC fatal error	未连接引脚无 NC	使用原生 NC API	mark-nc U1 14
引脚未连未NC	check-nc-coverage WARN	连线或打 NC	mark-nc / wire
文本重复	同一标注出现多次	手动删除	exec 删除代码
API 超时	一次操作太多器件	分开操作，减少单次批量	—
导线创建失败	端点碰触其他图元	绕开图元，使用 L 形路径	—