DIY Primitives｜让 Agent 真正推进制作的轻量原语
设计提案 v0.1（2026-11-07）。源于 Writing Primitives 的“事实与表达分离、少量原语、planned / observed 区分、最小有效改动”原则。它不是已被实验证明的制造标准，也不是要求每个 DIY 都填写一套复杂表格。
核心不是“描述步骤”，而是“交付可验证的状态变化”
传统教程：打开网页 → 看零件 → 打印 → 组装。问题是读者不知道谁负责判断、什么算完成、条件不满足应该怎么办。
一个可执行的制作步骤应该可以被问五个问题：做成什么？依赖什么？谁动手？留下什么结果？失败怎么办？
五个最小对象（DOAVR）
| 对象 | 核心问题 | 举例 |
|---|---|---|
| D · Direction / Outcome | 想完成什么？成功条件、预算、受众、约束是什么？ | “完成可显示 Agent 状态的桌面设备，预算尚未锁定；不能假设读者有打印机” |
| O · Object / Resource | 材料、工具、文件、设备和环境是什么？哪些是必要的、哪些可替代？ | ESP32-P4 实际芯片版次、屏幕与 FFC、打印机或代打印服务 |
| A · Action | 谁使用什么输入做一件具体的事？产物是什么？ | Agent 查最新 Release 并与芯片版次配对，输出来源表；人只负责插线和最后授权 |
| V · Verification / Evidence | 什么证据支持怎样的结论？能否通过？ | 官网规格证实接口 ≠ 收到的实物可正常运行；切片成功 ≠ 外壳能装好 |
| R · Relation / Route | 哪些动作有先后、兼容、互斥、可替代或失败回退关系？ | 屏幕与固件不匹配 → HOLD；没有打印机 → 代打印分支；烧录失败 → 停止写入 |
刻意不增加十几种“采购原语”“焊接原语”“视频原语”。采购、切片、拍摄属于 A 的 action kind；BOM 属于 O 的视图；证据和验收属于 V；设备替代和门禁属于 R。像 Writing IR 的 Move/Reader Evidence 一样，页面、清单、流程图是按需生成的视图，而不是必须持久化的新本体。
把 Writing IR 的三层思路迁移到 DIY
第一层，工程结构是否成立：物料是否完整，依赖/接口是否正确，制作与验证能不能闭环（D/O/A/R/V）。第二层，新手表达是否可执行：人的那一版有没有一句一个动作、具体操作界面、成功时的可见反馈、失败分支，是否把专业查证正确委托给 Agent（A 的人类视图）。第三层，新手最终是否真的获得成果：是否减少误购和返工、能否成功完成一次实物测试、是否能不用重新求助就推进到下一关（V 的实际观察与用户反馈）。
这三层不强制按固定顺序推进，更不应为“第三层”新增一套庞大原语。当前只是根据实践提出的判据；没有真实外部新手试做记录，就不能声称第三层已经得到验证。
让原语有工程意义的三条区分
- 计划 / 观察分离：所谓“应当看到屏幕亮起”是 planned；只有真实测试记录才是 observed。Agent 读取 README、切片、模拟，最多证明与其证据等级相称的内容。
- 研究 / 实物分离：Agent 能查官方工程、读源代码、对比参数、生成 CAD 检查报告；没有硬件就不能假装量到了孔位或烧录成功。模型做的安全评估不等于实物的安全认证。
- 执行 / 授权分离：Agent 可以生成精确 SKU 清单、购物车候选、商家问询稿；付款与风险动作必须取得相应授权。任何依赖未解决不应被“下一步”掩盖。
四种执行者，不要写“用户自行核实”
agent：联网检索、源码阅读、文件分析、CAD/切片自动化、生成 BOM、交叉验证和记录。前提是工具权限、素材与数据确实可用。human：告知目标/预算、选择替代路线、付款、上手操作、拍照测量和最终实物观察。shared：Agent 生成精确操作和验收要求，人完成物理动作并提供照片/日志，Agent 再解释结果。vendor：出具非公开规格/报价，打 PCB、代打印或代焊；Agent 跟踪证据但不能替供应商作出保证。
两种读法，数据只维护一处
source-data/hachimodock/workflow.json 是第一个结构化示例，source-data/robot-lab-draw-tree/workflow.json 是第二个实际应用。每个 A 标识参与者、依赖、输入、输出、验收与遇阻分支。
- 人类制作版：从该 JSON 自动生成，新手只需按自己的资源路径完成必要物理动作。
- Agent 执行版：从同一 JSON 自动生成，要求 Agent 自主查证、报告证据、说明当前授权边界。
- 深入教程：原有的 13 个章节是详细解释，不应复制维护机器工作流的状态；若二者冲突，应提出更新来源数据的补丁。
- AI Robot Lab 人类制作版 · Agent 执行版：从 SO-101 画树这个单任务验证 DOAVR，先离线笔画、兼容查证和安全适配，再进入实物组装、标定、三次画树验收。当前全部任务仍为计划状态，不能把网站回归测试当作机械臂实测。
运行 python3 scripts/render_diy_ir.py 可重建两个版本；python3 scripts/render_diy_ir.py --check 检查是否出现版本漂移，已纳入 CI 内容检查。原始结构及测试可在 GitHub 仓库中查看。
一件事如何从头到尾跑？
D 目标：HachimoDock 能显示真实的 Agent 状态
↓
O 资源：电脑系统 ? / 打印资源 ? / 关键物料 ? / 官方 STEP + PCB ?
↓
A1 Agent 验证上游资料和兼容 → V1 源码/型号证据
↓
A2 Agent 做结构模拟与询价 → V2 数字验证、报价
↓
R 采购门禁：不满足 → HOLD/询问；满足 → 人批准付款
↓
A3 人打印/代打印、焊接、接线、烧录 → V3 实物照片/日志
↓
A4 Agent 汇总记录，人确认真实结果 → V4 实机验收
重要：A1/A2 成功不意味着 A3/A4 已完成。任何新项目都可以从 D、已有的 O 和下一项 A 开始；只有发现高影响的缺失时才补 V/R，不要为填表本身增加工作量。
给 Agent 的作业准则
Agent 在同一回合能完成的检查就应自行完成，不把“去 GitHub 查看”“检查 BOM”转述给新手；若工具不可用，说明确切缺口并索取最少的材料。每次汇报只要：已查证 / 仍未知 / 需人执行 / 下一关 / 证据。每项判断都有来源时间、版本、条件、影响、置信边界；虚拟模拟不能推定实物成功。
这套表示的效果还需要通过真实项目验证。最重要的外部指标是：新手是否少买错料、少返工、少被要求做专业调研，并能在没有指定品牌机器时完成制作。