Handoff

Handoff 把当前工作交给接手者。不提交就还是临时包。

Memory 保存以后仍要知道的项目知识。Handoff 处理正在进行的工作。它要说清目标是什么、已经验证了什么、哪里卡住、接手者下一步做什么。

一条 Memory 往往很短。一个可用的 Handoff 必须让接手者检查证据，并判断自己是否真的有能力和权限继续。

​

先选 Memory 还是 Handoff

先看谁需要这些信息。Memory 保存可复用知识。Handoff 保存另一位执行者继续当前任务所需的状态。

你要保存的内容	选择
“运行契约测试前先重新生成客户端”	Memory
“客户端已生成，但测试尚未运行，下一步执行命令 X”	Handoff
“项目只支持 Python 3.11+”	Memory
“这个会话已修改文件 A/B，文件 C 仍待检查”	Handoff

长期有效的结论可以进入 Memory。一次任务当前的完整状态用 Handoff，不要把整份交接包硬塞进 Memory。

​

两层 API

选对对象之后，再看调用走哪一层。PowerContext 有低层 Handoff 生命周期，也有高层工作连续性循环。

​

低层生命周期

PrepareHandoff
→ HandoffDraft
→ finalize
→ PreparedHandoff
→ continue from prepared
→ optional commit
→ committed Handoff Revision

​

高层工作循环

Work Contract
→ handoff_current_work
→ Prepared Handoff
→ optional commit
→ continue
→ acknowledge
→ Task Outcome
→ Work continuity projection

高层操作把工作契约（Work Contract）、边界、回执和 Task Outcome 保存为 Source 记录，并复用低层 Handoff 模型。

​

已准备 Handoff 先于提交

finalize 把 draft 变成 PreparedHandoff。它会验证内容和直接证据，并读取当前 Handoff 头版本，再设置 base。当前没有头版本时，base=None。已经有已提交头版本时，base 是当前精确 Handoff 版本引用。

这一步不写 Handoff Artifact。

已准备 Handoff 可以序列化并交给另一个进程或会话。接手者可以直接从它继续。只要调用方保留这个值，Server 重启并不会使它失效。但没有提交，它不会成为 latest。

handoff_current_work 也不会自动提交。不过它会采集一条 Handoff 边界 Source，所以它不是零写入的预览 API。

​

提交保存里程碑

只有用户明确需要持久里程碑时才提交。

提交会检查三件事。已准备 Handoff 的 Scope 必须与请求一致。base 必须仍然等于当前头版本。内容和证据链必须合法。

第一次提交创建 Revision 1。以后同一生命周期的里程碑创建下一 Revision。

对同一已准备 Handoff 重试相同内容是幂等的，会返回当前 Revision，而不是重复新增。

​

过期基础

两个工作进程可以从同一个基础准备不同 Handoff。第一个提交后，第二个的基础已经过期，应返回 Revision 冲突。调用者需要读取新头版本，检查变化，再重新准备。

不要把冲突处理成把 Revision 加一再试。

​

继续有三种选择

接手者拿到包以后，可以用三种方式继续。

选择方式	读取什么	已选择 Revision
prepared	调用方携带的已准备 Handoff	无已提交 Revision
exact	指定历史 Revision	指定 Revision，同时返回当前
latest	当前已提交头版本	已选择等于当前

所有 Handoff 解析结果都是 untrusted_history。它会列出状态、next 动作、Citation 和无法读取的证据，但不会证明这些内容仍然新鲜。

接手者还应检查引用式文件和 Source 是否仍可读，实时工作区是否符合描述，自己是否具备所需能力，以及当前用户是否授权它继续。

​

确认绑定精确目标

接手者从 latest 发现 Handoff 后，应取返回的精确已选择 Revision，再用精确选择方式确认。

接受确认要求证据都可用，实时状态已确认，能力已确认，授权信息已确认，并且选择方式是 prepared 或 exact，不是 latest。

如果任何检查没通过，结果应该是 needs clarification、declined 或其他真实状态，不能为了闭环好看就写接受。

确认也不授予权限。它只是记录接手者检查了什么，以及是否愿意继续。

​

Task Outcome 关闭工作循环

工作做完以后，用 Task Outcome 记录整体结果。合法状态包括 succeeded、partial、blocked、failed、cancelled 和 unknown。单项检查的 skipped 或 timed_out 属于 TaskCheck，不是 Task Outcome 状态。两层都应原样保存真实状态。

要让一个已提交 Handoff 显示为 covered，结果必须链接一个接受确认回执，回执必须绑定精确已提交 Handoff Revision，结果必须在回执之后出现，并且位于同一 Scope。

同 Scope 下随便一条结果不会自动覆盖 Handoff。

​

Handoff 报告是投影

工作连续性和 Handoff 报告从 Source 日志与已提交 Handoff 历史内容生成视图。它们不会改写底层 Source、Handoff 或结果。

投影读取格式错误的工作 Source 时会软失败。无效记录计入 invalid_record_count，其余有效历史仍可展示。

当前工作连续性最多投影最近 64 个有效事件，同时保留总数和 truncated 信息。这是展示上限，不是日志数据删除。

​

用 OpenAPI 案例走一遍

​

1. 工作契约

Objective: complete the OpenAPI client update
In scope: regenerate the checked-in client
Acceptance: contract tests pass

​

2. 当前工作

State: client generation completed
Disposition: continuable
Next action: run contract tests

每条状态和 next 动作都引用精确 Source 或 Artifact 证据。

​

3. 临时交接

handoff_current_work 返回已准备 Handoff。先把它交给接手者继续，不提交。

检查 latest 仍然为空。这是预期行为。

​

4. 持久里程碑

用户要求保留后，提交已准备 Handoff。

handoff/HANDOFF_ID@1

​

5. 接手与确认

接手者 continue latest，检查返回的精确 @1，再确认精确 @1。

​

6. 结果

契约测试运行后记录 Task Outcome，并引用确认回执 SourceRef。工作连续性应显示 transfer 接受、outcome covered。

​

失败不会总是原子回滚

高层工作循环跨越多个持久操作。handoff_current_work 先采集边界 Source，再返回已准备 Handoff。后续提交失败时，边界 Source 仍存在，没有新的已提交 Handoff Revision。连续性可以看到边界事件，但不能把它当成持久里程碑。

文档和调用方都要报告这个实际状态。

​

常见误解

为什么 Handoff Report 里没有刚才的 Prepared Handoff？

报告面向已提交历史内容。已准备 Handoff 没有提交，不是持久里程碑。

我从最新版本读取了 Handoff，为什么不能直接 acknowledge 最新版本？

最新版本会随头版本变化。先读取它选中的精确 Revision，再把确认绑定到那个不可变目标。

证据都能读取，为什么还不能 accepted？

可读不等于当前仍正确，也不证明接手者有能力或授权。接受还需要实时状态、能力和授权信息检查。

提交冲突后可以复用旧 Prepared Handoff 吗？

先读取新头版本。旧基础已失效，直接重试会继续冲突。

​

怎么知道分清了

1. Memory 保存长期知识，Handoff 保存当前任务状态。
2. 已准备 Handoff 和已提交 Handoff 是两步。
3. handoff_current_work 会写入一条边界 Source。
4. 从最新版本发现之后，确认要绑到精确 Revision。
5. 接手者要检查证据、实时状态、能力和授权信息。
6. 结果要链接接受回执。
7. 报告仍然只是投影。

对象已经清楚时，去跑 Handoff 闭环。工作完成后，还可以从精确证据提炼可复用判断，但仍要经过 Review。

​

下一步

再看先审再留

工作完成后，可以从精确证据提炼判断或做法。生成成功不等于批准。

阅读 Experience 与 Skill

跑一次真正的交接

先准备临时交接包，再决定要不要提交成持久里程碑。

开始 Handoff 闭环