session-handoff

Session Handoff 是一套专为解决 AI 助手上下文窗口限制而设计的会话管理解决方案。该技能通过标准化的文档模板和自动化脚本，实现了工作状态在多个 AI 会话间的无缝传递，确保长时间复杂任务能够跨会话持续推进而不丢失关键上下文。

核心用法围绕 CREATE 和 RESUME 两个工作流展开。CREATE 工作流通过 create_handoff.py 脚本生成结构化的交接文档，自动捕获项目元数据（时间戳、Git 分支、最近提交、修改文件等），并要求填写当前状态摘要、重要上下文、即时下一步行动和决策依据等关键信息。RESUME 工作流则通过 list_handoffs.py 和 check_staleness.py 工具管理文档时效性（FRESH 到 VERY_STALE 四级评估），帮助新会话快速恢复工作状态。此外，该技能支持交接链（Handoff Chaining）功能，允许将多个交接文档串联，形成完整的项目历史 lineage。

显著优点包括：彻底解决长时任务中的上下文耗尽问题；通过强制结构化模板确保信息传递的完整性；完全基于 Python 标准库开发，零外部依赖，本地运行保障数据隐私；内置 validate_handoff.py 质量验证机制，自动检测残留占位符和潜在敏感信息泄露，确保交接文档达到 70 分以上的质量标准。

潜在缺点与局限性不容忽视。首先，作为 T3 来源（个人开发者）项目，长期维护稳定性不如企业级方案。其次，工具深度依赖 Git 环境，非 Git 管理的项目无法自动捕获版本信息。此外，尽管有验证脚本，文档质量仍高度依赖用户手动填写的内容质量，存在信息遗漏或主观描述不清的风险。交接文档的时效性管理（Staleness）虽有帮助，但仍需人工判断过时信息的有效性。

适合的目标群体主要包括：长期进行复杂编程任务的开发者，特别是使用 Claude 等 AI 助手进行多轮深度调试的工程师；需要跨时段、跨会话延续工作的远程协作团队；以及处理需要数小时甚至数天才能完成的分析、重构或研究任务的知识工作者。

使用该技能可能存在的常规风险包括：虽然 subprocess.run 调用 Git 命令的参数受控，但在不可信目录中运行仍存在潜在命令注入边界风险；用户可能误将 API 密钥或密码写入交接文档（尽管有扫描检测）；长期积累的交接文档可能造成信息冗余；以及文档与代码实际状态不同步（Stale）导致的决策失误风险。建议定期清理过时交接文档，并在恢复工作时严格执行验证清单。