会话交接技能
目的
长时间运行的会话中,随着 Token 数量累积,上下文窗口会逐渐退化,导致指令遵循能力、推理精度以及工具准确性下降。长会话中充斥着已被取代的计划、废弃的草稿以及重复的错误追踪。重置到新会话可以恢复性能,但盲目丢弃上下文会引入状态丢失、产生幻觉性的进展以及重复犯错。
session-handoff 技能标准化了代理如何快照活动状态。它将短暂的、易失的工作记忆转化为可为下一会话提供可操作、可验证的桥梁文档。
工作流:结束会话(6 个步骤)
当代理会话达到操作限制或终止工作时,按以下序列执行:
-
审计 Git 和工作区状态 运行
git status -s和git diff --stat以建立基于实际状态的基准。切勿依赖聊天记忆来判断哪些内容已被修改。识别出发生更改、未跟踪以及暂存的文件。 -
捕获目标状态与实际实现之间的差异 用一句话定义原始目标。明确记录哪些部分已经通过测试命令或运行时检查被验证为有效,以及哪些部分仍然是不完整或未经验证的。
-
记录已做出的决策和已舍弃的路径 列出在该会话中做出的架构和设计选择,并附上具体理由。明确记录负向决策(已经尝试过但放弃的方法),以防止下一个代理重新尝试失败的解决方案。
-
整理触及的文件和相关符号 列出已修改或引用的关键文件路径、函数、类和模式定义。如适用,请注明行号引用。
-
隔离未解决的问题(附带负责人和验证方法) 列出所有未处理的边界情况、失败的测试、延迟的任务以及环境约束。每个未解决的问题都必须指定谁来解决(人类还是代理),以及如何验证完成状态。
-
指定下一步即时操作 起草一条简单、原子、不含歧义的指令,供下一个代理在第一个回合执行。不要提供宽泛的清单;要明确指出首先要运行的命令或编辑的文件。
操作规则
- 区分事实与推测:测试通过是事实;认为代码可运行因为编译通过是推测。将未经测试的假设明确标记为
[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 个不必要的回合来发现哪些内容需要测试。
局限性
- 此技能仅生成书面交接文档;它无法保留运行中的进程、未提交的终端输出或内存中的调试上下文——请主动将任何重要的内容记录在笔记中。
- 交接文档的质量受限于前一个会话记录的内容:未记录下来的决策、死胡同或文件更改,无法被下一个会话恢复。
- 它不能替代版本控制或问题跟踪系统;先提交工作,然后在笔记中引用提交或工单,而不是重复它们。