Communitygithub.com

会话交接

在上下文使用量接近容量(>60%)、执行 /clear 或 /compact 之前、切换任务或结束编码会话时使用此技能。它会生成结构化的交接产物,将执行状态转移到新的代理会话中,避免上下文丢失或产生漂移。

会话交接 是什么?

Session Handoff(会话交接)技能专为 Claude Code、Cursor、Codex 等 AI 编码代理平台设计,旨在解决长会话导致的高上下文窗口问题,例如指令遵循能力下降、推理精度降低和工具准确性偏差。其核心功能是标准化代理如何快照当前工作状态,将临时的、易失的工作记忆转化为结构化的、可验证的交接文档,从而在开启新会话时实现无缝状态转移,避免因盲目清空上下文而造成的状态丢失、幻觉进度或重复错误。该技能通过六个关键步骤(审计 Git 与工作区状态、捕获目标与实际实现差异、记录决策与废弃路径、整理触及的文件与符号、隔离未完成任务并指定负责人与验证方法、明确下一步行动)确保交接文档的准确性和可操作性。它强调事实与推测分离,禁止模糊指示,要求所有未完成任务必须指定负责方(人工或代理)及明确的验证标准,并提供了完整的交接文档示例和反模式指南(如禁止转储聊天记录或标记未测试模块为完成)。注意,该技能仅负责书面交接,无法保留运行中的进程、未提交的终端输出或内存调试上下文,需用户主动记录关键信息。

兼容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/alapha888/session-handoff-kit/tree/master

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

会话交接技能

目的

长时间运行的会话中,随着 Token 数量累积,上下文窗口会逐渐退化,导致指令遵循能力、推理精度以及工具准确性下降。长会话中充斥着已被取代的计划、废弃的草稿以及重复的错误追踪。重置到新会话可以恢复性能,但盲目丢弃上下文会引入状态丢失、产生幻觉性的进展以及重复犯错。

session-handoff 技能标准化了代理如何快照活动状态。它将短暂的、易失的工作记忆转化为可为下一会话提供可操作、可验证的桥梁文档。


工作流:结束会话(6 个步骤)

当代理会话达到操作限制或终止工作时,按以下序列执行:

  1. 审计 Git 和工作区状态 运行 git status -s 和 git diff --stat 以建立基于实际状态的基准。切勿依赖聊天记忆来判断哪些内容已被修改。识别出发生更改、未跟踪以及暂存的文件。

  2. 捕获目标状态与实际实现之间的差异 用一句话定义原始目标。明确记录哪些部分已经通过测试命令或运行时检查被验证为有效,以及哪些部分仍然是不完整或未经验证的。

  3. 记录已做出的决策和已舍弃的路径 列出在该会话中做出的架构和设计选择,并附上具体理由。明确记录负向决策(已经尝试过但放弃的方法),以防止下一个代理重新尝试失败的解决方案。

  4. 整理触及的文件和相关符号 列出已修改或引用的关键文件路径、函数、类和模式定义。如适用,请注明行号引用。

  5. 隔离未解决的问题(附带负责人和验证方法) 列出所有未处理的边界情况、失败的测试、延迟的任务以及环境约束。每个未解决的问题都必须指定谁来解决(人类还是代理),以及如何验证完成状态。

  6. 指定下一步即时操作 起草一条简单、原子、不含歧义的指令,供下一个代理在第一个回合执行。不要提供宽泛的清单;要明确指出首先要运行的命令或编辑的文件。


操作规则

  • 区分事实与推测:测试通过是事实;认为代码可运行因为编译通过是推测。将未经测试的假设明确标记为 [UNVERIFIED]。
  • 为未解决的问题强制指定负责人和验证方法:每个未解决的问题必须声明负责人(Human 或 Agent)以及确定性的验证标准(例如,pytest tests/auth/test_token.py::test_refresh_rotation passes)。
  • 禁止模糊的延续描述:绝不要写“继续在 auth 上工作”或“完成前端组件”。要指明具体的符号、文件和失败模式。
  • 引用真实工作区标识符:所有对代码的引用都必须使用确切的文件路径和符号名。不要使用泛化的伪代码描述。

工作示例:会话交接笔记

# 会话交接:JWT 轮换实现

### 目标和当前状态
- **目标**:在 FastAPI 认证服务中实现刷新令牌轮换和撤销功能。
- **当前状态**:刷新令牌数据库迁移已应用,轮换端点已创建。令牌生成和数据库持久化工作正常。撤销黑名单缓存尚未接入依赖验证器。
- **验证**:`pytest tests/test_auth_tokens.py` 通过(4/4 测试)。

### 已做出的决策(附原因)
- **使用 Redis 保存令牌撤销列表**:选择 Redis 而不是 Postgres 查找已撤销的 JTI 令牌,以将受保护路由上的延迟保持在 5 毫秒以下。
- **舍弃无状态刷新令牌**:我们最初评估了在 JWT 声明中实现滑动过期而不持久化,但由于在自然过期前无法撤销泄露的令牌,因此放弃。
- **令牌格式**:选择 UUIDv4 作为 `jti` 声明的值,以保持与现有会话存储模式的兼容性。

### 文件变更
- `src/services/auth.py`:添加了 `rotate_refresh_token(old_token: str)` 函数和 Redis 失效调用。
- `src/models/tokens.py`:添加了 `RefreshTokenRecord` SQLModel 表用于追踪令牌家族。
- `alembic/versions/20261005_add_token_families.py`:创建 `token_records` 表的迁移文件。
- `tests/test_auth_tokens.py`:添加了令牌家族生成和轮换的单元测试。

### 未解决的问题
- [代理] 将 `verify_token_not_revoked` 接入 `src/api/deps.py` -> 通过检查 `tests/test_auth_deps.py` 在黑名单令牌下失败来验证。
- [代理] 处理轮换过程中 Redis 不可用时的数据库回滚 -> 通过在单元测试中模拟 Redis 连接失败来验证。
- [人工] 在 CI 执行的 `.env.test` 中设置 `REDIS_AUTH_URL` 密钥。

### 下一步操作
打开 `src/api/deps.py`,从 `src.services.auth` 导入 `is_token_blacklisted`。在 JWT 解码验证之后,立即在 `get_current_user` 中插入该检查。

### 注意事项
- 不要修改 `src/core/config.py` 中现有的 `access_token` 过期时间(当前为 15 分钟)。
- 在本地启动 API 服务器之前,必须运行 Alembic 迁移 `20261005_add_token_families.py`(`alembic upgrade head`)。

反模式

  • 聊天记录转储:将原始对话日志粘贴到交接笔记中。这样会污染新会话的上下文窗口,而正是你原本希望避免的对话噪声。
  • 幻影通过:某个模块仅仅被编写过,但从未执行或测试过,就将其标记为“已完成”。
  • 隐藏死胡同:省略掉失败的解决方案。下一个代理读到代码库,会看到同样的显式路径,从而再次实现那个失败的方法。
  • 抽象的下一步:以“下一步:实现剩余的测试”结尾。新的代理需要经过 3-5 个不必要的回合来发现哪些内容需要测试。

局限性

  • 此技能仅生成书面交接文档;它无法保留运行中的进程、未提交的终端输出或内存中的调试上下文——请主动将任何重要的内容记录在笔记中。
  • 交接文档的质量受限于前一个会话记录的内容:未记录下来的决策、死胡同或文件更改,无法被下一个会话恢复。
  • 它不能替代版本控制或问题跟踪系统;先提交工作,然后在笔记中引用提交或工单,而不是重复它们。

相关技能