embedded-project-loop

嵌入式项目循环

对于跨越文件与实体硬件边界的工作，采用一个小型、持久的循环。Agent 可以准备并验证主机端产物，但不得虚构焊接、刷写、测量或现场证据。

推荐入口

如果请求涉及实体硬件、多个会话、待完成的测量、现场测试或恢复工作，请先加载此技能，再加载 arduino-workflow-router。此技能负责持久化目标、下一项待办、证据边界、回滚路径和实体操作关卡。随后，路由器会选择电路板、接线、代码、工具链、测试和部署方面的专家，但不会代替此技能结束该循环。

状态

在项目中使用 .arduino/，或使用用户指定的外部证据目录：

.arduino/goal.md
.arduino/next-todo.md
.arduino/board-profile.md
.arduino/evidence/{build,upload,hardware,system,deployment}/
.arduino/experiment-log.jsonl
.arduino/resume-token.md

请勿在这些产物中放入密钥、令牌、私有网络凭据和未脱敏的个人数据。goal.md 记录准确目标、成功标准、非目标、安全约束、停止条件和回滚路径。下一项待办文件包含一项操作、负责人、前置条件、预期证据、关卡和状态。

有界迭代

1. 阅读目标、下一项待办、电路板配置文件和最近的日志条目。
2. 选择一项会产生因果影响的固件、接线、电源、测量或诊断变更。
3. 运行可用的、范围最小且安全的主机端／构建检查。
4. 如果下一步需要用户操作，则在实体操作关卡处停止。
5. 将用户提供的观察结果与预期结果及独立安全关卡进行比较。
6. 追加记录操作、证据路径、决策、回滚和下一项待办。
7. 只保留经过验证的候选方案；否则记录阻碍因素，或恢复当前实验状态。

一次迭代不得组合多项接线变更、多个固件映像、多种电源或多次测量。一次只做一项变更，才能将故障归因于具体原因。

实体操作关卡

提出具体问题，并等待观察结果：

Physical gate: On <exact board/revision>, perform <one action> with power
<state>. Capture <measurement/log/photo> at <location>. Expected:
<observable result>. Reply with the observation or `blocked: <reason>`; do not
reply with an unverified yes.

如果上传失败，请索取准确的端口／设备标识、映像／哈希值和已脱敏的上传器日志。如果涉及电源问题，请索取仪表测量位置、单位以及观察到的最小值／最大值。如果涉及接线，请在启用负载前索取通断／极性检查结果或带标注的照片。

证据边界

• 构建证据只能证明源代码／配置以及依赖项编译情况。
• 上传证据只能证明映像已被指定目标路径接受。
• 硬件证据必须包含目标标识，以及测量数据、串口输出、通断检查、示波器数据或附有上下文的照片。
• 系统证据必须包含集成场景和有代表性的负载。
• 部署证据必须包含健康检查、分阶段更新、回滚、恢复和维护记录。

如果缺少证据，请标记为 unverified 或 blocked，并保持下一项待办未完成。在擦除、修复引导加载程序或重新刷写之前，请先阅读路由器的恢复参考资料。

防止自我合理化

捷径	应对方式
“复选框已经勾选了。”	要求提供产物，并明确证据阶段。
“编译通过了。”	不要将其提升为上传、硬件或系统证明。
“用户大概已经接好线了。”	提出具体的关卡问题并等待答复。
“同时试三个修复方案。”	将它们拆分为每次只做一项变更的迭代。
“先擦除再说。”	确认目标、最近一次已知正常映像、恢复路径以及数据丢失影响。
“没有新输出就表示成功。”	记录无操作观察结果；这不会关闭目标。

验证

• 状态文件存在，且下一项待办指定了一项确定的操作。
• 每个已完成的实体步骤都关联到带有证据阶段标签的证据。
• 日志以只追加的方式记录决策、回滚和下一个候选方案。
• 停止条件和修复上限均有明确说明。
• 在此代码仓库中，运行 python3 scripts/run_arduino_evals.py；loop-engine-evidence-contract 用例会检查有效和无效的持久循环产物，并在缺少必要状态或日志字段时安全失败。

共享输出约定

使用共享的 Arduino 技能约定： 说明假设、所需工具及版本、实现步骤、 各证明阶段的测试/证据、已知限制，以及恢复/安全说明。