session-handoff

用途

session-handoff 用于在 AI 智能体会话之间创建完整的交接文档，使新的智能体能够无缝继续之前的工作，避免歧义。它主要解决长时间运行的智能体上下文耗尽的问题。

该技能提供两种工作流：

此外，在完成大量工作后（例如 5 次以上文件编辑、复杂调试、重大决策），技能会主动建议创建交接文档以保留上下文。

cd /path/to/spectrum-web-components
python .cursor/skills/session-handoff/scripts/create_handoff.py [task-slug]

例如：python .cursor/skills/session-handoff/scripts/create_handoff.py implementing-user-auth

对于延续型交接（链接到之前的工作）：

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

脚本会：在项目根目录创建 .cursor/handoffs/（如需要）、生成带时间戳的文件名、预填时间戳、项目路径、git 分支、最近提交、修改的文件，并在延续时添加交接链链接，最后输出文件路径供编辑。

完成交接文档：打开生成的文件，填写所有 [TODO: ...] 部分。优先处理以下部分：当前状态摘要、重要上下文、立即下一步、已做决策（含理由）。可参考 references/handoff-template.md 中的模板结构。
校验交接：从项目根目录运行校验脚本：

python .cursor/skills/session-handoff/scripts/validate_handoff.py .cursor/handoffs/<handoff-file>

校验器会检查：是否还有 [TODO: ...] 占位符、必需部分是否存在且已填写、是否检测到潜在机密（API 密钥、密码、令牌）、引用的文件是否存在，并给出质量评分（0-100）。检测到机密或评分低于 70 时不应定稿。

当 Python 或脚本不可用时：(a) 使用 references/handoff-template.md 手动创建交接文档，和/或 (b) 在聊天中输出结构化交接内容供用户保存。

cd /path/to/spectrum-web-components
python .cursor/skills/session-handoff/scripts/list_handoffs.py

这会显示所有交接文档的日期、标题和完成状态。当 Python 或脚本不可用时，可手动从项目根目录的 .cursor/handoffs/ 列出（命名格式：YYYY-MM-DD-HHMMSS-[slug].md），然后加载并使用恢复清单验证上下文。

python .cursor/skills/session-handoff/scripts/check_staleness.py .cursor/handoffs/<handoff-file>

过期等级：FRESH（可安全恢复）、SLIGHTLY_STALE（查看变更后恢复）、STALE（恢复前仔细验证上下文）、VERY_STALE（考虑创建新的交接文档）。脚本会检查：交接创建后的时间、git 提交、变更的文件、分支分歧、缺失的引用文件。

加载交接：在采取任何行动前完整阅读相关交接文档。如果交接属于链的一部分（有“Continues from”链接），也要阅读链接的前一个交接文档以获取完整上下文。
验证上下文：遵循 references/resume-checklist.md 中的清单：验证项目目录和 git 分支是否匹配、检查阻塞项是否已解决、验证假设是否仍然成立、审查修改的文件是否有冲突、检查环境状态。
开始工作：从交接文档中的“立即下一步”第 1 项开始。工作时参考“关键文件”“发现的关键模式”“潜在陷阱”等部分。
更新或链接交接：工作时在“待办工作”中标记已完成项、将新发现添加到相关部分。对于长会话，使用 --continues-from 创建新交接文档以形成链。

对于长期项目，可将交接文档链接在一起以维护上下文谱系：

handoff-1.md (初始工作)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

链中的每个交接文档：链接到其前驱、可将较旧的交接标记为已取代、为新智能体提供上下文线索。从链中恢复时，先阅读最新的交接文档，再按需参考前驱。

交接文档存储在项目根目录的 .cursor/handoffs/ 目录中。从项目根目录运行创建脚本以确保新交接文档存放于此。命名约定：YYYY-MM-DD-HHMMSS-[slug].md，例如 2024-01-15-143022-implementing-auth.md。

脚本	用途
`create_handoff.py [slug] [--continues-from <file>]`	生成带智能脚手架的新交接文档
`list_handoffs.py [path]`	列出项目中可用的交接文档
`validate_handoff.py <file>`	检查完整性、质量和安全性
`check_staleness.py <file>`	评估交接上下文是否仍然有效