> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Native 实战演练

> 用一个真实的头像上传需求，完整走完 Shape → Build → Verify → Archive，展示 Native Loop 如何收敛、证据如何绑定、中断如何恢复。

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

## 需求起点

你在 Agent 中输入：

```text theme={null}
/comet 为用户资料页增加头像上传能力
```

`/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 还在继续检查其他验收……

## 会话中断：从磁盘接着干

验证跑到一半，你的会话断了——可能是切了设备，可能是上下文被压缩。第二天你回到项目，输入：

```text theme={null}
/comet 继续
```

环境感知恢复读磁盘状态，确认目标 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 工程原理](/zh/native/native-loop)。想看 Native 和 Classic 的深度对比，见 [Native 与 Classic 如何选择](/zh/native/native-vs-classic)。从自己的需求开始，见 [Native 快速开始](/zh/native/quickstart)。