Skip to main content
读再多规则,不如看一次真实需求跑完全程。这一篇用”为用户资料页增加头像上传”这个需求,走完 Native 的四个阶段——包括一次验证失败、一次会话中断,让你看清 Loop 怎么收敛、证据怎么绑定、断了怎么恢复。

需求起点

你在 Agent 中输入:
/comet 读配置,转发到 /comet-native。Skill 重新读磁盘状态,确认当前没有匹配的 active change,于是创建一个新的。

Shape:把”想加个头像”变成可验证的契约

Agent 先调查仓库事实:现有资料页结构、有没有文件上传基础设施、鉴权怎么做、存储用什么。这些能查清的事实,Agent 自己搞定,不来问你。 然后它发现几个真正影响产品行为、没法从现有代码推断的决定,按 Sequential 模式逐个问你: 第一轮(最上游的决定):
  • 问题:头像上传失败时,保留用户原头像,还是清空?
  • 推荐:保留原头像,失败不造成数据损失。
  • 影响:选”清空”会让上传中途的网络抖动直接删掉用户已有头像。
你选了”保留原头像”。Agent 立即写入 brief.md,并据此判断下一个问题。 第二轮
  • 问题:是否允许用户删除已有头像,恢复默认?
  • 推荐:允许,提供删除入口。
  • 影响:需要额外的前端按钮和后端清理逻辑。
你选了”允许删除”。两轮结束,Agent 认为没有更多需要你决定的行为,生成一份共享理解摘要:
  • 上传失败保留原头像,不报错给用户造成困惑;
  • 支持删除头像、恢复默认;
  • 最大 2MB,支持 JPG/PNG,服务端压缩;
  • 压缩后仍超 500KB 则拒绝。
你确认这份摘要后,Shape 写入 brief.md 和每个 capability 的 target spec,把验收条件也定下来(例如”上传 2MB JPG 后应产出压缩后的头像""删除头像后资料页显示默认图”)。--confirmed 推进到 Build。 关键点:实现方式——用哪个 HTTP 库、裁剪放前端还是后端、临时文件存哪——Agent 一个都没问你,这些是模型自主选择。

Build:Agent 自主实现

进入 Build,Agent 自己决定怎么干:它选了用现有的表单组件、在后端用 sharp 做压缩、把临时文件放系统 tmp 目录。Native 不要求它写设计文档或按 TDD 走,只要实现满足 brief 和 target spec。 Agent 实现了一批相关改动后,对照完整 spec 和全部验收条件自检,然后提交真实的项目产物。Runtime 把这些产物和项目快照一起算出一份 implementation scope——这不是 Agent 嘴上说的”我改了这些”,而是 Runtime 从内容哈希算出来的事实。

Verify:第一次失败,Loop 开始收敛

Agent 提交了 Build 产物,Runtime 推进到 Verify。Agent 对照验收条件跑真实验证,其中一项没过:
  • 验收项:删除头像后,资料页显示默认图。
  • 失败原因:删除逻辑清了数据库记录,但前端没刷新,还显示旧头像。
Runtime 把这个未满足的验收项和失败检查结构化地交回 Build,而不是让 Agent 自己在对话里回忆还差什么。这就是 Native Loop 的第一轮收敛。 Agent 回到 Build,补上前端刷新逻辑,再提交。这次 Runtime 重新验证——删除后刷新生效,该项转绿。但 Verify 还在继续检查其他验收……

会话中断:从磁盘接着干

验证跑到一半,你的会话断了——可能是切了设备,可能是上下文被压缩。第二天你回到项目,输入:
环境感知恢复读磁盘状态,确认目标 change 唯一,自动进入。Agent 重新读 comet-state.yaml、brief、target spec 和当前验收进度——它精确知道:还差两项验收没跑,上一次中断在 Verify 阶段。不依赖昨天的聊天记录。 Agent 接着跑完剩余验证。全部验收通过,证据绑定到当前的 brief、spec、scope 和 revision。

Archive:提交前两步检查

进入 Archive。Runtime 先生成一个内容绑定的 preflightHash,然后才执行真正的归档提交——提交时会重新检查证据、路径和 canonical spec hash。如果中间有人改了同一个 capability,归档会停下而不是覆盖。 这次没有并发冲突,归档成功:
  • target spec 成为新的 canonical spec;
  • active change 移入带日期的 archive 目录;
  • trajectory 只保存阶段摘要和证据引用,不记录隐藏推理。

走完一遍,你看到了什么

  • Agent 自主选择方法:整个过程中,Agent 没被强制走 TDD、写计划或 review,它自己判断怎么实现最合适。
  • 完成判定权在 Runtime:验证失败不是 Agent 说”修好了”就算,而是 Runtime 用证据确认缺口真的减少了。
  • 可恢复:会话中断后从磁盘精确恢复,不靠聊天记忆。
  • 证据可信:每条验收都有对应的真实证据,没跑的检查写不成通过。
想了解 Loop 收敛背后的工程原理,见 Native Loop 工程原理。想看 Native 和 Classic 的深度对比,见 Native 与 Classic 如何选择。从自己的需求开始,见 Native 快速开始
最后修改于 2026年8月2日