session-handoff（会话交接技能）Skill 是什么？如何解决 AI 代理上下文耗尽？

会话交接技能：让 AI 代理在上下文耗尽前优雅"换班"

• 核心定位：为长时间运行的 AI 代理会话提供"交接班"能力，把当前工作状态写成一份结构化、可验证、可续接的交接文档。
• 双工作流：既支持"创建交接"（保存状态），也支持"从交接恢复"（继续之前的工作），并带有一套检查和恢复清单。
• 四个配套脚本：脚手架生成、列表查看、完整性/安全性校验、陈旧性评估，把"写笔记"变成有质量门槛的工程动作。
• 交接链机制：通过 --continues-from 把多次会话链接成上下文谱系，适合跨天、跨周的长期项目。
• 触发自然：说一句"保存状态"“上下文快满了”"继续之前的工作"即可启动，无需记复杂参数。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：会话交接技能；技能英文名：session-handoff；技能 ID：12057。

这个技能要解决的问题非常具体：AI 代理在长时间工作中会遇到上下文窗口耗尽——聊着聊着就"失忆"，前面做过的决策、改过的文件、踩过的坑全部丢失，新会话只能从头再来。session-handoff 的做法是：在上下文还够用的时候，把"现在做到哪了、为什么这么定、下一步做什么"写成一份结构化的交接文档，让下一个代理（或下一个会话的自己）能够无歧义地接手。

一键安装的思路与步骤：

1. 确认前提：需要一个支持 Skill 机制的 AI 代理客户端，并且该技能包内的脚本（Python 脚本）能在本地运行；同时项目目录可写，因为交接文档会写入 .claude/handoffs/。具体的客户端版本与运行环境要求，以官方说明为准。
2. 获取技能：在客户端的技能市场/技能管理中，用技能 ID 12057 或英文名 session-handoff 检索并安装；若采用手动导入方式，则将技能包（包含 SKILL.md、scripts/、references/）放入技能目录。安装入口与路径以官方说明为准。
3. 验证是否生效：安装后在会话中输入"创建交接"，观察代理是否转为交接创建工作流、是否调用 scripts/create_handoff.py 生成文件；再输入"加载交接"或"从…恢复"，看是否进入恢复工作流。两者都能正确切换，说明技能已生效。
4. 顺手确认依赖：技能依赖 scripts/ 下的四个脚本正常执行，可先跑一次 python scripts/list_handoffs.py，能正常输出（哪怕是"暂无交接"）即说明脚本路径与环境没问题。

"一键安装"真正提升效率的地方在于：它把一个原本靠个人自觉、格式随意、容易漏项的"写备注"动作，变成了带脚手架、带校验、带评分的标准流程——安装一次，之后每个长任务都能复用。

2. 该技能的主要功能和特点

• 两种模式自动分流：技能会先判断意图——用户想保存状态/暂停/上下文快满 → 走创建流程；用户想继续之前的工作/加载上下文 → 走恢复流程。不需要用户自己记命令。
• 智能脚手架：create_handoff.py 自动创建 .claude/handoffs/ 目录、生成带时间戳的文件名，并预先填好时间戳、项目路径、git 分支、最近提交、修改过的文件，省去手工翻 git log 的时间。
• 强制补全关键章节：文档中所有 [TODO: ...] 都必须填完，且优先处理"当前状态摘要"“重要上下文”“立即下一步”“已做决策（含理由）”——尤其强调记录决策的理由而不只是结果，这正是跨会话最容易丢失的信息。
• 完整性 + 安全性双重校验：validate_handoff.py 检查是否有未填占位符、必需章节是否齐全、引用的文件是否存在，并扫描潜在的密钥/密码/令牌；同时给出 0–100 的质量分数。分数低于 70 或检出秘密的交接不允许定稿，这条硬规则避免把敏感信息或半成品交出去。
• 陈旧性分级：check_staleness.py 依据时间间隔、期间产生的 git 提交、变更文件、分支分歧、缺失的引用文件，把交接分为新鲜 / 略微陈旧 / 陈旧 / 非常陈旧，指导"能不能直接恢复"。
• 交接链：用 --continues-from 让新交接链接到上一份，形成 handoff-1 → handoff-2 → handoff-3 的谱系，恢复时先读最新一份再回溯前驱，长期项目不再"断代"。
• 主动建议：在 5 次以上文件编辑、复杂调试或重大决策之后，技能会主动提醒"考虑创建交接文档"，把保存时机前置到上下文还健康的时候。
• 规范化存储：统一放在 .claude/handoffs/，命名规则为 YYYY-MM-DD-HHMMSS-[缩写].md，示例 2024-01-15-143022-implementing-auth.md，多人多任务也不容易混。

与普通笔记工具的差别：普通 Markdown 笔记只能记，不能校验、不能判断是否过期、不能保证下一个代理读得懂；这个技能把"写交接"变成了有模板、有检查项、有质量分数的可执行流程。

3. 如何使用该技能？

A. 创建交接（保存现场）

1. 触发：说"创建交接"“保存状态”“我需要暂停"或"上下文快满了”。
2. 生成脚手架：技能会运行

   python scripts/create_handoff.py [任务缩写]
   

   例如 python scripts/create_handoff.py implementing-user-auth；若是延续上一段工作：

   python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
   

   脚本会输出生成的文件路径。
3. 填写 TODO：打开文件，按 references/handoff-template.md 的结构补全内容，优先写清四块：当前状态摘要、重要上下文、立即下一步、已做决策及理由。
4. 校验：运行

   python scripts/validate_handoff.py <交接文件>
   

   确认无残留 [TODO: ...]、必需章节齐全、无潜在秘密、引用文件存在，且质量分数 ≥ 70。
5. 确认：技能会向你汇报交接文件位置、验证分数与警告、捕获的上下文摘要，以及下次会话的第一个行动项。

B. 从交接恢复（接手工作）

1. 找文件：python scripts/list_handoffs.py，查看所有交接的日期、标题与完成状态。
2. 查陈旧性：python scripts/check_staleness.py <交接文件>，根据新鲜 / 略微陈旧 / 陈旧 / 非常陈旧决定是直接恢复、审查后恢复，还是重建一份新交接。
3. 完整阅读：在采取任何动作前读完整份交接；若它属于交接链，还要读它链接的前驱交接。
4. 验证上下文：按 references/resume-checklist.md 逐项核对——项目目录与 git 分支是否一致、阻塞问题是否已解决、假设是否仍成立、改动过的文件是否有冲突、环境状态是否正常。
5. 开始干活：从"立即下一步"的第 1 项做起，过程中参考"关键文件"“发现的关键模式”"潜在陷阱"三节。
6. 边做边更新：在"待处理工作"里勾掉已完成项，把新发现补进对应章节；会话拉得很长时，用 --continues-from 再链一份新交接。

输入示例：

“上下文快满了，帮我创建一份交接，任务缩写用 payment-refactor。”

预期输出：.claude/handoffs/2024-01-15-143022-payment-refactor.md 生成 → 你补齐 TODO → 校验脚本返回分数（如 88 分、无秘密告警）→ 技能汇总"下次第一件事：把 refund 分支的幂等校验补上"。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
session-handoff（会话交接技能）	结构化会话交接与续接	脚手架生成、四脚本配套、完整性/秘密校验、0–100 质量分、陈旧性分级、交接链	需支持 Skill 的客户端 + 可运行 Python 脚本；说出触发语即可	长周期重构、复杂调试、跨天需求、上下文即将耗尽	优势：有校验门槛、可判断过期、可链式追溯；不足：依赖脚本环境，初次配置需确认路径
手写 Markdown 备忘	自由记录	想到什么写什么	零门槛	临时记几个待办	优势：最快；不足：格式随意、易漏关键决策、无校验、下一个代理常读不懂
项目常驻说明文件（如各类 Agent 约定文件）	长期项目约定	存放编码规范、目录说明、长期偏好	低，随手编辑	团队通用规范、长期不变的约定	优势：每次会话自动生效；不足：不记录"当下做到哪一步"，无法承担单次任务的现场快照，越长越乱
通用 Agent 记忆/记忆库类插件	隐式记忆沉淀	自动抽取偏好与事实并存储	通常较低，多为自动触发	记住用户习惯、常用信息	优势：无需手动操作；不足：偏"长期偏好"而非"任务现场"，缺少显式下一步与决策理由，恢复时不易确认状态

怎么选：任务短、只需记两行 → 手写备忘；团队长期规范 → 常驻说明文件；个人偏好记忆 → 记忆类插件；任务跨会话、跨天、需要另一个代理准确接手 → session-handoff。三者并不互斥，常驻说明放"不变的事"，交接文档放"这一刻的事"。

5. 该技能的典型应用场景与实际体验情况

场景一：大型重构的中途暂停 后端工程师小李在把单体服务的支付模块拆成独立服务，改到第 12 个文件时被拉去开会。他一句"创建交接"，脚本自动填好 git 分支、最近提交、已改文件清单；他补上"已做决策：保留旧的退款回调入口，理由是线上仍有存量订单"，校验得分 90，安全下播。第二天新会话说"继续之前的工作"，从"立即下一步"直接续上。 实际体验：上手难度低，最难的不是操作而是"把理由写清楚"；效果最明显的是决策上下文不丢，避免二次返工。

场景二：复杂 Bug 的跨天调试 排查一个偶发的并发超时问题，第一天排除了三个假设。用交接记录"已排除项 + 未验证假设 + 潜在陷阱"，第二天恢复时用 check_staleness.py 发现期间分支有两次新提交，判定为"略微陈旧"，于是先审查变更再继续，避免基于旧结论空跑。 实际体验：陈旧性检查很实用，尤其在有他人协作的仓库里；建议交接时把"当前假设"写得可证伪。

场景三：上下文即将耗尽的被动急救 长会话已经跑了几十轮，代理开始"忘记"前面的约定。此时触发创建交接，脚手架把已有上下文快速固化，验证器顺手扫出文件里不该出现的令牌，拦下了原本会被写进文档的敏感串。 实际体验：秘密扫描是意外惊喜；但要注意这是"最后一道防线"，最佳实践仍是主动在里程碑处创建，而不是等窗口见底（信息已开始丢失）。

场景四：多人/多代理接力 一个需求由不同时段、不同代理接力完成，用 --continues-from 把三份交接串成链。接手者先读最新一份，再按需回溯前驱，形成清晰的上下文谱系。 实际体验：链式结构让"考古"变简单；注意及时把被取代的旧交接标记为过时，否则文件多了会挑花眼。

6. 该技能能为用户带来的价值

• 效率上：把"重新讲一遍项目背景"的冷启动时间压缩成"读一份文档 + 跑一次校验"。脚手架自动抓取 git 分支、提交记录和改动文件，手工整理时间大幅减少。
• 门槛上：不需要懂什么"上下文工程"，只要会说"创建交接"“继续之前的工作”，模板与检查清单会推着你把关键信息补全，新手也能写出合格的交接文档。
• 质量上：0–100 的质量分数和"低于 70 不定稿"的硬门槛，让交接从"看心情"变成"看标准"；秘密扫描降低把 API 密钥、令牌写进仓库文档的风险。
• 可量化的口径：验证分数、陈旧性等级（新鲜/略微陈旧/陈旧/非常陈旧）、待处理项完成数、交接链长度——这些都是可以直接观察的指标，用来判断交接质量是否在改善。
• 长期价值：交接链沉淀下来的是项目的决策史与踩坑史，新成员或新代理接手时的学习成本持续下降；对团队而言，这相当于给 AI 协作补上了"交班制度"。

7. 常见问题 FAQ

Q1：怎么安装？装完怎么确认能用？ 在支持 Skill 的客户端里用技能 ID 12057 或英文名 session-handoff 检索安装，也可手动导入包含 SKILL.md、scripts/、references/ 的技能包，具体入口以官方说明为准。验证方式：说"创建交接"看是否生成文件，说"加载交接"看是否进入恢复流程。

Q2：收费吗？ 技能本身不涉及计费说明，成本主要来自你所使用的 AI 客户端本身的额度消耗。是否收费、如何计费请以官方说明为准。

Q3：适合谁用？ 适合需要 AI 代理连续工作较久的开发者：做长周期重构、跨天调试、架构决策记录的人；也适合多代理/多人接力同一任务的团队。只是问一两个短问题的话，用不上它。

Q4：和直接写 Markdown 备忘、或用记忆类插件有什么区别？ 备忘只管记录，不校验、不判断过期；记忆类插件偏长期偏好沉淀，不记录"当下做到哪一步、为什么这么做"。session-handoff 提供模板、校验、质量分、陈旧性分级和链式追溯，面向的是"任务现场的精确交接"。

Q5：质量分数不到 70 怎么办？ 说明必需章节缺失、仍有 [TODO: ...] 占位符，或引用的文件/秘密检测有问题。按校验输出逐项补齐：把"已做决策"的理由写清、确认引用的文件路径存在、移除任何密钥或令牌后再复验，达到 70 分以上再定稿。

Q6：交接文档存在哪里？会不会泄露敏感信息？ 统一存放在项目的 .claude/handoffs/ 目录，命名形如 2024-01-15-143022-implementing-auth.md。校验脚本会扫描潜在秘密，检出即不建议定稿；但请务必确认该目录未被提交到公开仓库。