> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 生命周期，也有高层工作连续性循环。

### 低层生命周期

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
PrepareHandoff
→ HandoffDraft
→ finalize
→ PreparedHandoff
→ continue from prepared
→ optional commit
→ committed Handoff Revision
```

### 高层工作循环

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`。

> [!NOTE]
>
> `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. 工作契约

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Objective: complete the OpenAPI client update
In scope: regenerate the checked-in client
Acceptance: contract tests pass
```

### 2. 当前工作

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
State: client generation completed
Disposition: continuable
Next action: run contract tests
```

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

### 3. 临时交接

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

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

### 4. 持久里程碑

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
handoff/HANDOFF_ID@1
```

### 5. 接手与确认

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

### 6. 结果

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

## 失败不会总是原子回滚

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

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

## 常见误解

> [accordion] 为什么 Handoff Report 里没有刚才的 Prepared Handoff？
>
> 报告面向已提交历史内容。已准备 Handoff 没有提交，不是持久里程碑。

> [accordion] 我从最新版本读取了 Handoff，为什么不能直接 acknowledge 最新版本？
>
> 最新版本会随头版本变化。先读取它选中的精确 Revision，再把确认绑定到那个不可变目标。

> [accordion] 证据都能读取，为什么还不能 accepted？
>
> 可读不等于当前仍正确，也不证明接手者有能力或授权。接受还需要实时状态、能力和授权信息检查。

> [accordion] 提交冲突后可以复用旧 Prepared Handoff 吗？
>
> 先读取新头版本。旧基础已失效，直接重试会继续冲突。

## 怎么知道分清了

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

对象已经清楚时，去跑 [Handoff 闭环](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md)。工作完成后，还可以从精确证据提炼可复用判断，但仍要经过 Review。

## 下一步

> [card] [再看先审再留](https://powercontext.mintlify.site/zh/mental-model/experience-and-skill.md)
>
> 工作完成后，可以从精确证据提炼判断或做法。生成成功不等于批准。

> [card] [跑一次真正的交接](https://powercontext.mintlify.site/zh/basic-usage/handoff-loop.md)
>
> 先准备临时交接包，再决定要不要提交成持久里程碑。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.