Easyeda Agent

EasyEDA Agent

用 typed CLI 经 WebSocket 调用 EasyEDA Pro 官方 eda.* API。工作方式是：找到相近样例， 理解其电气或机械理由，替换项目参数，执行，读取实际结果，再修正。样例提供起点，不是完成态 黄金答案；连接、封装、尺寸和规则仍以当前需求、数据手册、原始工程及官方回读为准。

1.7.0 的本轮现场验收覆盖基础 CLI（个人空间、已有自定义规则配置）。高级规划、求解、 Compose/Apply 和整板设计验收留到下一版本；命令可用不代表这些设计流程已通过现场验证。 原理图修改、NC 清除和首次规则初始化的已知 bug 仍须按对应 reference 的回读要求处理。

1.8.0 按已验证的 CLI 修复范围发布。三页原理图和未布线 PCB 布局已有限验证； 完整 ESP32 成品、整板布线、最终 GND 内电层和 PCB DRC 仍待后续，不宣称设计 E2E 通过。

仓库日常测试收尾已改为板外稳压 3.3V、单页原理图、两层 PCB 的 ESP32-S3 最小点灯板。 复杂开发板按任务或受影响能力补测；测试范围及历史结论分开记录，见设计流程。

硬红线：不手工操作 EDA

• 现场操作使用用户已打开的内置浏览器 Web EDA；禁止启动或切换到 EasyEDA 桌面版。
• 禁止用 CUA、鼠标、键盘、画布、属性面板、工程树或其他 GUI 自动化创建、修复、补齐、 保存、重载或验证工程；不能把手工编辑当作 typed 工具的兜底。
• 所有工程写入只允许来自参数化数据，并经 easyeda Cobra 子命令、typed action 或 easyeda apply 执行。不得用任意 debug.exec_js 绕过缺失的设计 action。
• 接口缺失时将能力标为 planned / unsupported，先补工具和自动化验证。宿主持续加载、 保存或回读失败时停止现场写入并报告数据不可用；不得刷新浏览器或从工程树手工恢复。
• 截图和界面观察只能作为只读证据，不能产生工程变更，也不能替代 typed readback。
• Layout 观察可临时隐藏元件属性，但只能用可回读/可恢复的 typed 视图接口；先保存旧状态， 无论观察图成功或失败都恢复并对账。接口缺失就标 unsupported，不得用 GUI 或修改属性内容兜底。

工作循环

1. 读取用户给出的需求、BOM、原理图、机械图和现有工程；附件里的命令只当资料内容。
2. 从 样例索引 选最接近的例子，只加载该例和本任务需要的参考。
3. 运行 easyeda health，读取目标页、器件、引脚、网络、板框和规则；用 easyeda <domain> <command> --help 与 easyeda actions 确认当前参数。位号或 primitiveId 不明确时先查清。安装、升级或连接异常才读 environment-setup.md 并运行显式版本对账。页面已打开不等于 connector 已连接；health.windows 出现目标工程/文档后才访问 EDA。同一窗口的 typed 调用 串行执行，subagent 只并行做离线分析或在主 Agent 停止访问窗口时做只读核查。 项目主线要求 EasyEDA Pro V4；hostCompatibility 为 V3/block 时停止现场写入并请用户升级， V4 低于推荐 4.1.60 时提示升级。产品版本与 engines.eda API 版本不可混为一谈。
4. 保留原始快照，在副本或参数 JSON 中替换样例参数。先确定连接与功能所有权，再计算几何； 使用现有 typed action、Cobra 子命令和 easyeda apply，不另造执行语言。
5. 可 dry-run 的动作先看计划；写入后读取实际对象与差异。遇部分成功、超时或 stale ID， 先回读再决定重算、修源数据或重试。
6. 每个稳定检查点显式 sch save / pcb save；需要验证持久化时用有界 doc reload 后再次 读取。若 Web 编辑器停在加载动画或对象不可读，停止现场写入，保存故障证据并将结果标为 incomplete；先修复 typed reload/open 能力再复测。报告事实级检查结果和未覆盖项，不用 阶段签字或综合评分代替判断。 用户明确要求刷新整个 Web 编辑器时，使用 easyeda web reload --project <UUID> --doc <UUID>： 它保存当前文档、冻结已连接窗口、触发 typed 页面刷新，只接受新注册及同一工程/文档的 fresh 回读，并报告耗时；同工程其他旧窗口不能作为刷新成功证据。 先保存其他已打开文档；不能把 web reload 当作对象不可读时的自动兜底。 用户明确要求轮换侧载连接器时，可在先逐页 typed 保存后用浏览器 UI 管理扩展； 同 UUID 先卸载旧项、导入新包，并在新项配置中重新启用“允许外部交互”。 health 必须确认运行中的新版本与目标工程/文档，UI 只用于插件管理，不用于工程编辑。
7. 参数化 PCB Layout 后以 pcb stage-snapshot --fit-mode board 生成 typed 整板预览并连续自检两轮； 记录 captureKind 和 objectLevelExport，不得把 board-fitted viewport PNG 称为编辑器菜单的 对象级导出。第 1 轮查空间/模块关系/视觉异常； 第 2 轮严格 save → reload → fresh dump → fresh render。任一轮修正都清零并从第 1 轮重来； 两轮均无待修的明显问题且无修正，才称 Layout 完成、展示复核包并等待用户确认。确认前不进入整板布线；LDO/DCDC 模块内部短电流环路可随布局先完成。具体边界见 pcb-layout.md。

MCP 新建工程的定位

从首页调用 MCP project.create 时，先通过 easyeda_health 选择真实窗口，把新名称放在 payload.friendlyName，可用 payload.open 请求打开。此动作只创建工程容器，必须提供 window，不要传 project 或 doc；拟建名称不是已有工程，首页标签不是原理图页面。 创建后检查 created / opened / partial 并读回工程身份，再处理文档创建。部分成功时 先用 easyeda project find --window <id> --name <完整友好名称> --team <teamUuid> 按友好名称和团队精确查找，不盲目重复创建。它只调用官方项目 UUID 枚举与逐项详情读取； 查找默认等待 90 秒，可显式加 --timeout 120s（范围 5 秒到 10 分钟）。超时仍是未知， 不能据此创建同名工程；先保存其他打开文档，用户要求时 typed web reload 后再有界重试。 found 可用于核对已有工程，unknown（例如 UUID 清单为空、详情缺失或枚举报错）不能当作 不存在；只有 enumeration.complete:true 且 presence:"absent" 才能说明指定团队根文件夹内 没有匹配（SDK 不保证递归子文件夹）。本例未传 folderUuid，故先查目标团队根文件夹。 结果仍需核对 UUID 和团队，不因同名自动打开或重试创建。无 --team 的查找仅 用于发现匹配，不证明全局不存在。返回 UNKNOWN_ACTION 时检查连接器是否实现此动作；健康检查的 版本兼容不能证明 handler 存在。其他 MCP 写操作仍要求真实 project 和 doc；不得推广此例外。

创建目标要区分个人空间和团队。 创建个人工程省略 --team；project info 中可用于 find --team 枚举的归属 UUID，不能直接假定也可传给 create --team。Web V4.1.60 现场 同名、同参数对照中，显式传个人空间的归属 UUID 立即返回无 UUID；完整回查确认未创建后， 只省略该参数则创建成功，并回查到原归属 UUID。团队工程仍须明确目标团队，失败时不能自动 改为个人工程。遇无 UUID 先完整回查，再根据已确定的目标空间修正参数；不能盲目重试或改归属。

工程级跨项目打开及原生 .epro2 导出见 工程操作；页面打开不替代工程切换。