会话交接
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/softaworks-agent-toolkit-session-handoff。
技能介绍
它解决什么问题
长时间运行的 AI Agent 会撞上上下文耗尽:对话越长,早期的决策、踩过的坑、临时约定就越快被挤出窗口。一旦会话中断——无论是上下文满了、换台机器还是重启客户端——新会话里的 Agent 只能看到一句“我们刚才在做鉴权”,然后重头猜。Handoff 技能针对的就是这个状态丢失问题:把当前会话的关键上下文固化成一份文档,让下一个 Agent 零歧义接手。
工作原理
技能围绕两个工作流组织:创建和恢复,另有一个主动触发机制。
创建工作流分四步:
- 运行脚手架脚本
create_handoff.py,自动建好.claude/handoffs/目录、生成带时间戳的文件名,并预填项目路径、git 分支、最近 commit、改动文件等元信息; - 打开生成的文档补齐
[TODO: ...]占位,优先写四部分:当前状态、代理人必须知道的关键上下文、明确的下一步动作、已做决策及其理由; - 跑
validate_handoff.py校验:残留占位符、必备章节、潜在密钥、引用文件是否存在,并给出 0–100 的质量分,低于 70 分或检出密钥就不允许定稿; - 向用户汇报文件位置、校验分数和首个待办动作。
恢复工作流同样有明确步骤:先用 list_handoffs.py 列出可用交接文档,再跑 check_staleness.py 判断时效——FRESH、SLIGHTLYSTALE、STALE、VERYSTALE 四级,依据是距离创建时间的 git commit、文件变化和分支分叉情况;确认可用后完整读取文档(若是链路交接,还要回读前序文档),按 resume-checklist.md 逐项核对目录、分支、假设与环境,然后从“Immediate Next Steps”第 1 条直接开工,工作过程中勾选进度、追加发现,必要时用 --continues-from 串联新交接。
适用边界
- 交接文档的质量取决于填写质量:占位符没清干净、决策只写结果不写理由,恢复方照样会猜错;
- 安全边界靠校验器兜底,但它不是万能的密钥扫描器,敏感内容仍应先自行清理;
- 对频繁变动的项目,交接文档的时效衰减很快,每次恢复前都必须做 staleness 检查,别假设内容仍然适用;
- 适合长任务、跨会话场景,短平快的单次问答不必套这套流程。
使用场景
- 模型上下文快满需要暂停当前任务时,把进展和待办写成交接文档供新会话续作
- 隔天回来继续开发前,先用 check_staleness.py 判断昨夜的交接文档是否已过期
- 连续排查多个棘手 bug 之后,按模板生成 handoff 记录已走过的死胡同和遗留问题
- 长任务要跨多次会话推进时,用 --continues-from 把多份交接文档串成完整链路
适合人员
- 独立开发者:功能开发跨多天多轮会话,希望隔天回来时不必重头摸底进度
- Agent 应用工程师:给长任务智能体接入中断恢复能力,保证流水线可断点续跑
- 小团队技术负责人:多人轮值维护同一个长周期模块,靠文档传递决策理由与坑点
- 驻场顾问:在客户环境连续多天开发后离场,要让接手同事快速还原现场状态