fable-handoff

Fable 交接

留下足够且经过核实的上下文，让其他 Agent 无需重放整段对话或重新摸索代码库，就能继续工作。

使命

交接不是摘要，而是一份续接契约。

接手的 Agent 应清楚了解用户提出了什么要求、实际做了哪些更改、哪些说法有证据支持、哪些证据已过时或缺失、当前有哪些阻碍，以及接下来最安全的第一步是什么。

适用场景

• 暂停一项耗时较长的任务；
• 将工作移交给另一个 Agent、人员或会话；
• 上下文过多，需要进行持久化压缩；
• 发布或 PR 尚未完成，但必须停止执行；
• 自动化或协作循环需要持久化检查点。

不适用场景

• 除了一个简单且已完成的轮次，没有值得持久化保留的信息；
• 由于规划或诊断尚未完成，下一步行动本身仍不明确；
• 交接会被用来掩盖缺少验证或尚未解决的失败。

连续性分类

状态	交接重点
已干净完成的卡片	具体证据 + 下一张卡片
工作区有未提交更改	已负责的更改与无关更改 + 安全的续接点
尝试失败	复现步骤、已尝试的方案、修订后及尚存的假设
等待评审	差异/基线、发现的问题、验证状态
等待发布	候选 SHA/版本、各渠道状态、外部阻碍
等待研究/探索	实测事实、尚未解决且影响决策的问题
等待委派工作	工作人员责任归属、已返回/缺失的数据包

协议

阶段 1 — 重建持久化任务

用一句简洁的话记录用户最初/当前希望达成的结果。将其与之后发现的实现策略分开。

阶段 2 — 精确记录代码库/工作状态快照

在可获取时，记录：

• 分支/工作区和候选提交 SHA；
• 当前卡片/阶段；
• 有意修改的文件/界面；
• 必须保留的无关用户更改；
• 有意不提交的生成产物/状态文件；
• 未关闭的 PR、问题、发布版本或标签标识符。

阶段 3 — 区分事实、决策与猜测

分别记录：

• 实测事实：观察到的代码库/运行时/提供方证据；
• 决策：选定的架构/契约及其原因；
• 推断：合理但尚未证实的判断；
• 已否决的假设：避免重复无效推理；
• 未解决的问题：仅记录会影响下一步行动的问题。

阶段 4 — 记录证据及其时效性

为每条重要说法记录：

• 命令/探测/来源；
• 结果；
• 相关变更/提交/产物；
• 状态为最新、过时或未检查。

绝不要把 NOT_CHECKED 写成听起来像是已通过的描述。

阶段 5 — 记录失败和已尝试的修复

仅记录能让接手者有所收获的尝试。说明尝试了什么、结果如何，以及这如何改变或未能改变原有假设。

阶段 6 — 明确说明阻碍

阻碍必须说明缺少哪项外部事实/权限/环境，以及解决后能开展什么工作。

错误示例：CI 问题

正确示例：GitHub 依赖项审查失败，因为仓库已禁用依赖关系图；代码/安全扫描本身并未报告依赖项漏洞。

阶段 7 — 给出一个安全的下一步行动

第一步行动应可直接执行，并有当前证据作为依据。如果有多个独立行动，请先指出主要行动，再列出其他行动。

阶段 8 — 清理敏感信息

不要复制机密、令牌、私钥、原始凭据、不必要的个人数据或冗长日志。应说明使用安全凭据机制，而不是记录凭据值。

决策规则

• 优先使用精确标识符（分支、SHA、PR、文件路径、命令），而不是叙述性描述。
• 保留否定性结论：已被证伪的理论可以避免重复浪费。
• 证据的新鲜度必须在上下文压缩后仍然明确；不能把旧的通过测试概括为当前测试通过。
• 如果工作区有未提交更改，请区分本任务的更改与无关更改／用户自己的更改。
• 如果下一步取决于尚未解决的决策，应先转交规划／恢复流程，而不是臆造交接操作。
• 对话历史只是可选上下文；交接内容必须能够独立理解。
• 如果错误特征、命令和关键行已足够，就不要复制完整日志。

不变原则

• 交接内容如实说明已证实和未证实的事项。
• 接手的 Agent 无需猜测名称、分支或文件，就能定位确切工作。
• 绝不在交接内容中保存机密。
• 明确保护与任务无关的用户更改。
• 下一步操作不能暗中依赖交接内容中未提供的上下文。

失败类型

叙述倾倒

聊天过程太多，可执行状态太少。应围绕任务／状态／证据／下一步操作重新组织。

新鲜度失实

将旧证据概括为当前证据。附上变更／SHA／制品上下文，并降低过期证据的可信度。

上下文匮乏

接手者必须重新发现架构，或弄清某项决策的原因。补充最精简但关键的证据／决策理由。

机密泄露

凭据出现在摘要／日志中。删除凭据值，只引用安全来源。

归属不明

列出有未提交更改的文件，却未说明哪些属于任务／用户／其他工作。交接前应先明确归属。

虚假结项

外部门禁／评审／提供方证据缺失时，交接内容却声称“已完成”。应明确标记待处理／阻塞状态。

反模式

• 复制整个对话；
• 倾倒终端输出却不作解读；
• 省略失败尝试，导致下一位 Agent 重复尝试；
• 不说明提交／变更的新鲜度就声称“测试通过”；
• 因为“下一位 Agent 会需要”而保存令牌；
• 使用“继续修复”之类含糊的下一步；
• 丢失会实质影响实现的用户约束／偏好；
• 仅凭已准备好的制品就声称已发布／已公开。

交接包

Goal:
Current branch/worktree/SHA:
Active phase/card:
Intentional changes:
Protected unrelated changes:
Measured facts:
Decisions + rationale:
Rejected hypotheses / failed attempts:
Evidence:
- claim → command/source → result → fresh/stale/not checked
Open findings/blockers:
External states (PR/CI/release/registry):
Primary next safe action:
Secondary independent actions:
Do not repeat / do not change:

完成标准

当零上下文的接手 Agent 能够：

• 确认具体任务和仓库状态；
• 区分事实／决策／推断；
• 知道哪些证据是最新的；
• 避免重复已被证伪的尝试；
• 安全地保护无关工作和凭据；
• 无需询问缺失的基本上下文即可执行下一步操作；

则交接即为完整。

进阶资源

• 深入指南：references/resumability-and-context-compaction.md
• 现有架构：references/continuity-schema.md
• 模板：templates/handoff-state.template.md
• 示例：examples/cross-session-handoff.md