mcpField
S
session-handoff

session-handoff

github.com/softaworksAgent 工作流2.6k4.2k 次安装34 周前更新
代码仓库

关于 session-handoff

session-handoff 是用于创建和恢复交接文档的 Agent 技能，适合跨长会话工作的 Agent。它结合文档脚手架、完整性验证和过时状态检查。

主要功能

  1. 01生成带时间戳的交接文档
  2. 02记录项目与 Git 上下文
  3. 03验证完整性并检查密钥
  4. 04检查交接内容是否过时
  5. 05串联相关交接文档

适用场景

  1. 01在会话结束前保存上下文
  2. 02根据旧交接文档恢复工作
  3. 03检查已保存的上下文是否仍适用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/softaworks/agent-toolkit --skill session-handoff

安装后在 Claude Code 中输入/session-handoff确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
evals/
model-expectations.md
results-opus-baseline.md
setup_test_env.py
test-scenarios.md
references/
handoff-template.md
resume-checklist.md
scripts/
check_staleness.py
create_handoff.py
list_handoffs.py
validate_handoff.py

详细介绍

工作交接

创建全面的交接文档，让新的 AI Agent 能够毫无歧义地无缝接续工作。解决 Agent 长时间运行导致上下文耗尽的问题。

模式选择

确定适用的模式：

创建交接文档？ 用户想要保存当前状态、暂停工作，或上下文即将占满。

  • 遵循下方的 CREATE 工作流

从交接文档恢复工作？ 用户想要继续之前的工作、加载上下文，或提到了现有的交接文档。

  • 遵循下方的 RESUME 工作流

主动建议？ 完成大量工作后（编辑 5 个或更多文件、复杂调试、重大决策），建议：

“我们已经取得了显著进展。可以考虑创建交接文档，为后续会话保留这些上下文。准备好时，请说‘创建交接文档’。”

CREATE 工作流

第 1 步：生成脚手架

运行智能脚手架脚本，创建预填充的交接文档：

python scripts/create_handoff.py [task-slug]

示例：python scripts/create_handoff.py implementing-user-auth

对于后续交接文档（链接到之前的工作）：

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

脚本将：

  • 根据需要创建 .claude/handoffs/ 目录
  • 生成带时间戳的文件名
  • 预填充：时间戳、项目路径、Git 分支、近期提交、修改过的文件
  • 如果接续之前的工作，则添加交接链链接
  • 输出供编辑的文件路径
第 2 步：完成交接文档

打开生成的文件，填写所有 [TODO: ...] 部分。优先填写以下部分：

  1. 当前状态摘要 - 当前进展
  2. 重要上下文 - 下一位 Agent 必须了解的关键信息
  3. 接下来的具体步骤 - 清晰、可执行的第一步
  4. 已做出的决策 - 附带理由的选择（不只是结果）

请参考 references/handoff-template.md 中的模板结构。

第 3 步：验证交接文档

运行验证脚本，检查完整性和安全性：

python scripts/validate_handoff.py <handoff-file>

验证器会检查：

  • 不存在遗留的 [TODO: ...] 占位符
  • 必要的章节均已包含并填写
  • 未检测到潜在机密（API 密钥、密码、令牌）
  • 引用的文件均存在
  • 质量评分（0-100）

如果检测到机密或评分低于 70，请勿完成交接。

第 4 步：确认交接

向用户报告：

  • 交接文件位置
  • 验证评分和任何警告
  • 已记录上下文的摘要
  • 下一次会话的第一项行动

RESUME 工作流

第 1 步：查找可用的交接文档

列出当前项目中的交接文档：

python scripts/list_handoffs.py

这会显示所有交接文档的日期、标题和完成状态。

第 2 步：检查时效性

加载之前，检查交接文档的时效性：

python scripts/check_staleness.py <handoff-file>

时效等级：

  • FRESH：可以安全恢复——交接后只有少量更改
  • SLIGHTLY_STALE：检查更改后再恢复
  • STALE：恢复前仔细核实上下文
  • VERY_STALE：考虑创建新的交接文档

脚本会检查：

  • 交接文档创建以来经过的时间
  • 交接后新增的 Git 提交
  • 交接后更改的文件
  • 分支差异
  • 缺失的引用文件
第 3 步：加载交接文档

采取任何行动前，完整阅读相关交接文档。

如果交接文档属于交接链（包含“接续自”链接），也要阅读链接指向的上一份交接文档，以获取完整上下文。

第 4 步：核实上下文

按照 references/resume-checklist.md 中的清单操作：

  1. 确认项目目录和 Git 分支一致
  2. 检查阻塞因素是否已解决
  3. 验证假设是否仍然成立
  4. 检查修改过的文件是否存在冲突
  5. 检查环境状态
第 5 步：开始工作

从交接文档“接下来的具体步骤”中的第 1 项开始。

工作时请参考以下章节：

  • “关键文件”中的重要位置
  • “发现的关键模式”中的待遵循约定
  • “潜在陷阱”中的已知问题，避免踩坑
第 6 步：更新或串联交接记录

工作过程中：

  • 在“待处理工作”中标记已完成的事项
  • 在相关部分添加新发现
  • 对于长时间的会话：使用 --continues-from 创建新的交接记录，将它们串联起来

交接记录串联

对于长期项目，将交接记录串联起来，以保留上下文脉络：

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

串联中的每份交接记录：

  • 链接到其前一份记录
  • 可以将较早的交接记录标记为已被取代
  • 为新的 Agent 提供上下文线索

从一系列交接记录中恢复工作时，先阅读最新的一份，再根据需要参考前序记录。

存储位置

交接记录存储于：.claude/handoffs/

命名约定：YYYY-MM-DD-HHMMSS-[slug].md

示例：2024-01-15-143022-implementing-auth.md

资源

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

评论

支持 Markdown