name: handoff description: "将当前对话压缩为交接文档，供另一个 Agent 接续。" argument-hint: "下一次会话将用于什么？" disable-model-invocation: true
第 22 课 / handoff
保存可接续的线索，而不是复制整场聊天
交接文档为下一位 Agent 提供当前重点与权威材料位置，避免重新从聊天猜测状态。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
一 / 读这一课之前
先把必要的概念讲清楚
交接的目的是让下一位 Agent 在正确状态继续。压缩聊天只是手段，重点是保留已经确认的目标、进度、证据位置和仍未解决的问题。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
context｜Agent 当前可用的上下文
模型这一轮实际能使用的请求、对话、指令和已读文件内容。它不是电脑上所有资料，也不是永久记忆。文件存在但没被读到，就不一定参与推理。交接文档应指明当前目标、进度、关键证据位置和下一步，让新会话能够恢复必要背景。
context pointer｜上下文资料指引
告诉 Agent 在什么条件下去读哪份材料的短指引。例如“新增或修改数据写入时，先读权限规则文档”。它同时承担地址与触发条件两项作用。只有“见文档”太模糊，可能找不到或不知道何时需要；一股脑放入所有内容又会占用上下文。
spec / specification｜规格说明
把要解决的问题、预期行为、约束和验收依据写明确的文档。它比“做个好用的学习网站”具体：例如登录用户能收藏课程，刷新后仍保留，重复收藏不会多出记录。它不必规定每个内部函数怎么写，但应让实现者和验收者对同一结果达成一致。
ADR｜架构决策记录
Architecture Decision Record 的缩写，记录一个重要技术决定、当时为什么选择它，以及接受了什么代价。例如规定所有写入经过后端权限检查。遵循相关 ADR，是在适用范围内延续已确认决定；新需求与之冲突时，应说明冲突和修改理由，而不是默默绕过。
二 / 中英全文对照与精讲
读原文，理解每一步为什么这样做
左右内容按小节对应；窄屏先中文、后英文。两种语言均完整展示，对应讲解紧接在小节之后。译文传达原文要求；老师讲解补充概念、原因、例子与适用边界。
中文译文English · 英文原文
name: handoff description: Compact the current conversation into a handoff document for another agent to pick up. argument-hint: "What will the next session be used for?" disable-model-invocation: true
编写一份当前对话的交接文档，让没有参加过这段讨论的新 Agent 能够继续工作。保存到用户操作系统的临时目录，不要放在当前工作区。
文档中加入“建议使用的技能”部分，列出下一位 Agent 应通过 Skill 工具加载哪些技能。
已经记录在规格、计划、ADR、工单、提交或代码差异里的内容，不要整段复制；提供对应路径或网址，让新执行者找到原始材料。
隐去 API 密钥、密码和可识别个人身份的信息等敏感内容。
用户若提供了额外参数，将它理解为下一次会话的重点，并据此安排交接内容。
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
老师讲解 · 对应上方原文 · 含教学举例
交接文件应该保留什么，省略什么
假设我们已经完成中英展示，正在重写教学内容。下一位必须知道：目标是初学者看得懂；旧版过于精简；已修哪些课；尚未发布哪些改动。只写“继续优化网站”无法恢复真实状态。
规格、ADR、提交和差异已有稳定记录时，用路径或链接引用，避免复制出另一份可能过期的副本。但对接续至关重要、别处没保存的决定，仍需在摘要明确写出。
**教师建议的核对法：**让一个没看过旧聊天的人只读交接，回答现在要做什么、什么不能重做、哪项还未验证。如果答不出，交接过度压缩。
临时目录与跨环境交接不是同一回事
原文把文件存到操作系统临时目录，避免把会话摘要当成项目长期规格。临时路径能被下一会话读取，是这个安排的前提。
换电脑或换工具时，本机路径可能不存在。因此教师补充建议是确认接收环境能访问文件或引用产物，而不是只把路径发过去。这里没有保证临时文件永远保留。
脱敏同样重要：交接写“凭据位于已配置的秘密管理处”通常比复制密钥更合适。可引用的位置、实际权限和秘密本身是三件事。
交接要说明从哪里继续，不只是总结聊过什么
假设收藏保存已完成，取消收藏还没做。交接应说明目标规格在哪里、已完成哪个提交、哪些测试通过、下一张工单是什么，以及仍有哪些未解决问题。
“我们讨论了收藏和测试”不是足够的交接。 新 Agent 不知道讨论结果，也不知道工作停在哪一步。已经有规格时可以准确引用；重要决定尚未写入其他文件时，必须在交接中写清楚，不能只说“参考前文”。
自包含不等于复制所有资料，而是能从交接入口找到所需材料。引用还必须在新环境中可访问。清空聊天不会自动删除代码；但临时目录也可能被系统清理，不能让它成为永久项目知识的唯一保存位置。
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
交接写“部署成功”，但没有实际结果，下一会话该怎么办？
我已思考，查看参考思路
把它当待核验的摘要陈述，读取部署记录或访问证据。不能用旧总结替代当前真实状态。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 22 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：“读完前四课，grilling 的依赖顺序仍不清楚”比“已掌握需求技能”更适合教学交接。工程交接则还需准确版本、未知操作结果和下一步检查。
边界与容易误读的地方
handoff 写文件并不代表旧执行已停止，也不代表新 Agent 已启动；若要转移写入责任，必须另有真实状态核验。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。