AI画的怎么证明是对的?easyeda-agent画电路板的写前守卫、回读验证与保存重载完整机制
AI画的怎么证明是对的?easyeda-agent画电路板的写前守卫、回读验证与保存重载完整机制
easyeda-agent 是 EasyEDA Pro(嘉立创 EDA 专业版)的 AI 自动化层,让 AI 直接放置器件、连线、布局布线并完成检查。它不靠"截图看着像"来判断结果,而是用写前守卫、回读验证、保存重载三层机制证明 AI 画的每一笔都是真实落盘、可复查的。
为什么"截图看着对"不可信 🧐
让 AI 操作 EDA 编辑器时,有 3 个容易被忽略的坑:
| 坑 | 后果 |
|---|---|
| 截图会 stale | 图片是旧帧,画布已经变了,截图与真实对象脱节 |
| 部分成功 | 批量操作 161/163 步成功,第 162 步悄悄失败,整体看起来"做完了" |
| 内存态 ≠ 落盘 | 编辑只发生在内存,没保存前一切都可能丢 |
easyeda-agent 的解法是把"证明"拆成三道独立关卡:写入前守住入口,写入后立刻回读,保存重载后做最终对账。
第一关:写前守卫,身份没核对就不动文档
写前守卫(preflight guard)的目标很简单:在调用任何写入 API 之前,先把"我要改谁"这件事确认清楚。
- 核对目标工程、页面、器件身份和源数据。命令用
--project路由到工程,--doc钉住目标页,防止落子到错页;多窗口下目标不明确会直接返回AMBIGUOUS_WINDOW而不是"猜一个"(见 docs/protocol.md)。 - 负例在写前拒绝。错误
--doc、过期对象 ID、无效参数、缺失连接器,都会被拒绝执行——"每个负例在写前拒绝或明确标状态未知"是它的基础测试放行条件之一(见 docs/cli-live-test.md)。 - 批量写入先 dry-run。
easyeda sch apply steps.json --dry-run只做本地预检并打印步骤,不写 EDA;队列里的每一步还可以带assert断言和confirm确认门控,删除/清除类动作默认需要--yes放行(格式见 docs/design-apply-playbook.md)。 - 状态漂移即拒绝。写入前记录的对象状态与目标不符(比如器件已被移动、引脚状态变了)时拒绝继续,而不是带着旧快照硬写。
第二关:回读验证,判对错看数据不看截图
写入"成功"只是第一半。easyeda-agent 要求写后立刻从官方 API fresh 回读,逐项核对:
| 核对项 | 说明 |
|---|---|
| 引脚与网络 | 每个 pin 的实际网络名、noConnected 状态与目标一致 |
| 几何 | 器件/导线坐标、旋转、镜像与计划值逐项比较 |
| 对象绑定 | 器件身份(uniqueId)、位号、父子关系未被破坏 |
| 范围外不变 | 不该改的对象,一条记录都不能变 |
回读有严格语义:expectSchematic 要求按位号和引脚编号匹配、列齐全部引脚,与数组返回顺序无关;部分成功的写入返回 partial:true 和 notApplied[] 明细,失败不自动重试,而是先读真实状态再重新规划(见 docs/design-apply-playbook.md)。项目 CLI 约定也写明:"判对错看数据不看截图:list / check / drc / layout-lint 是判据;截图会 stale"(见 docs/cli/README.md)。
第三关:保存与重载,落盘的最终证据 💾
前两关证明的是"内存里的画面对了",保存重载证明"它真的写在磁盘上了":
- 显式保存并要求真实确认。成功保存必须返回布尔
saved:true;外层调用返回 ok 不等于落盘(见 docs/concepts.md)。 - 真实 reload 后 fresh 读取。权威批次以
save → reload → readback收尾,刷新失败时结果保持incomplete,不能拿 reload 前的缓存或旧记录当完成证据(见 docs/architecture.md)。 - 保存身份认证。连接器在操作前后采集 project/document/type 身份,只有两边一致才给出
mutationContextAvailable:true;身份漂移会明确报告原因。两次采样也不能排除 ABA 切页,所以显式保存重载仍是必需检查点(见 docs/protocol.md)。 - autosave 只是安全网。daemon 有防抖后台保存兜底,但它不能替代关键检查点的显式
save+ 重载回读。 - 全程留审计。每次 typed action 都进操作日志,可用
easyeda audit查看(实现见 internal/app/cmd_audit.go),复核时按原始回包独立判定,不靠执行员自述。
真实案例:会自己叫停的写入队列
这套机制不是纸面设计。在一轮三页原理图恢复的现场实测中,重新生成的 88 步队列前 20 步成功后,第 21 步导线写后校验失败:SDK 已返回对象 ID,但即时回读库存为空。系统的反应是——停止队列、保存、完整回读、导出证据,不重放旧队列,把失败登记为已知问题并用有界只读回查修复,最终独立复核通过。完整过程见 docs/reviews/2026-09-27-cli-schematic-gate.md。
对比一下:没有这套机制时,同一时刻的合理做法很可能是"稍后再读一次,应该就好了"——而这正是部分成功被掩盖的起点。
三步启用这套验证机制 🚀
不用读源码,日常使用只需记住三步:
- 开始前做健康检查:
easyeda health核对版本与连接; - 稳定检查点显式保存:每完成一个功能区就
save,确认saved:true后doc reload再 fresh 读取; - 收尾看数据:
sch check/sch drc/pcb check分项报告事实,导出审计与证据,截图只作辅助审阅。
完整验收分层(基础动作先行、高级验收随后)见 docs/cli-live-test.md 与 docs/cli-advanced-test.md;已知问题与证据边界见 docs/cli-known-bugs.md。
验证边界速查表
| 关卡 | 证明了什么 | 不能证明什么 |
|---|---|---|
| 写前守卫 | 目标身份正确、输入合法、状态未漂移 | 写入本身会成功 |
| 回读验证 | 内存中对象与目标一致 | 数据已持久化 |
| 保存重载 | 落盘且重载后仍一致 | 全部制造/电气验收 |
| 审计日志 | 每一步可追溯、可独立复核 | 不能替代上述三项证据 |
一句话总结:easyeda-agent 对"AI 画的"给出的证明链条是——写前核对身份与数据、写后 fresh 回读逐项对账、保存重载后重新读取,全程审计留痕。三层都过,才算"画对了"。


