Handoff

Handoff 是什么

Handoff 用于把一个代理会话的工作状态交给下一个代理、同事或不同工具。它不会简单复制聊天记录，而是提炼目标、已完成工作、当前状态、关键决定、未解决问题和下一步，并尽量引用仓库中已经存在的规格、计划、ADR、提交或差异，降低重复和过期信息。

适用场景与不适用场景

适合更换代理工具、切换仓库或目录、把任务交给同事、从主任务分叉一个支线时使用。若只是同一环境中的上下文压缩，直接使用原生 compact 更合适。它也不应被当成最终项目文档、审计记录或唯一事实源，因为交接摘要可能遗漏细节并带有生成时的判断。

核心能力与工作机制

Skill 会生成一份结构化 Markdown，写入操作系统临时目录；可接收一个可选参数，说明下一会话的目标。摘要优先引用已有文件而非重写内容，并可推荐下一位执行者需要加载的 Skill。生成过程中要求删除令牌、密钥、个人身份信息和其他不应传播的内容。

实际工作流与产物

它先识别当前目标与范围，再收集已验证事实、文件位置、变更、决定和阻塞项；随后压缩成独立可读的交接文档，并返回文件路径。下一位执行者应直接读取该路径，同时回到被引用的原始规格和代码核验。若不是立即接手，应把文件复制到持久目录，因为系统临时文件可能被清理。

安装、依赖与权限

只需要读取当前会话可见的项目状态，并能在系统临时目录写文件，不依赖外部 API。由于文档可能包含路径、命令和代码标记，传递给命令行时应使用安全的文件路径参数，不要把整段摘要插入 shell 字符串，以免反引号或变量表达式被解释。

限制、风险与使用建议

交接文档是二手来源，可能把推测写得过于确定，或遗漏刚发生但尚未完成的动作。任何接手者都应核对仓库状态、测试结果和引用文件。临时目录不是可靠存档位置；敏感内容过滤也不能替代人工检查。对于合规或事故场景，应使用正式记录系统。

上手建议

调用前说明接手对象和下一阶段目标，例如“交给另一代理继续修复支付回归”。生成后快速检查五项：目标是否准确、未完成项是否清楚、命令是否安全、路径是否存在、是否有秘密或个人信息。真正重要的结论应回填到项目文档，而不是长期依赖交接摘要。

来源、版本与许可

本条目依据固定提交中的完整 Skill 与详细使用说明整理，仓库声明 MIT 许可证。说明保留了上游关于临时文件寿命、敏感信息过滤和摘要可信度的边界。

常见问题

1. 交接文件会写到项目仓库吗？

默认不会，而是写到操作系统临时目录，避免无意污染仓库。需要长期保存时，应在人工检查后复制到明确的持久位置，并决定是否纳入版本控制；不要假设临时路径会一直存在。

2. 它与上下文压缩有什么区别？

上下文压缩服务于同一工具和工作目录中的继续对话；Handoff 面向跨工具、跨目录、跨人员或任务分叉，需要形成外部可读文件并显式说明恢复步骤。只为节省当前窗口上下文时无需额外交接。

3. 会把完整聊天记录复制进去吗？

不会。它选择对接手者有行动价值的信息，并引用已经存在的规格、计划、ADR、提交与差异，避免制造冗长且很快过期的副本。若某段原始讨论是唯一证据，应先转成正式文档。

4. 如何处理密钥和个人信息？

规则要求主动删去令牌、密码、密钥和个人身份信息，但自动过滤并非绝对可靠。发送给他人或上传到工单前仍要人工审阅，并检查日志片段、环境变量、URL 查询参数和截图描述中的隐性泄漏。

5. 下一位执行者可以直接相信摘要吗？

不应无条件相信。摘要是从会话提炼出的二手资料，可能遗漏失败尝试或把假设写成事实。接手者应先查看当前文件状态、版本控制差异、测试结果和被引用的原始文档，再继续写操作。

6. 可选参数有什么用途？

它用于说明下一会话的具体目标，例如继续调试、准备评审或迁移到另一个仓库。这个提示能帮助摘要调整重点，但不会改变权限边界，也不能替代对目标文件和外部操作的重新确认。

7. 为什么不要把摘要直接拼进 shell 命令？

摘要可能包含反引号、美元符号、括号和代码片段，字符串插值可能触发命令替换或变量展开。安全做法是把文档保存在文件中，让下一工具按路径读取，而不是把全文当作命令参数。

8. 什么信息应回写到正式项目文档？

长期有效的术语、决策理由、外部契约、复现步骤和验收标准应进入 CONTEXT、ADR、规格或问题追踪系统。交接文件只保存恢复任务所需的短期导航，不应成为新的永久真相源。