| name | context-reset |
| description | 产出结构化 handoff 工件，让新 session 无痕接续当前任务。ctx-guard 阻断或主动切换 session 时使用。触发关键词：context reset、上下文重置、新开 session、切换 session、handoff。 |
| model | sonnet |
Context Reset — 结构化交接协议
把当前 session 的关键状态固化成 handoff 工件，让新 session 仅凭工件 + AGENTS.md 即可无痕接力。
触发
| 场景 | 说明 |
|---|
ctx-guard 阻断 | stderr 出现 "Context 占用超过硬阈值" |
| sprint 收尾 | 完成一个 sprint 需要开新 session |
| context 混乱 | 任务跑偏、想"白板" |
与 /compact 的区别：compact 压缩保留；reset 是清空 + 交接工件。
边界
- ✅ 读 transcript + 文件系统采集状态
- ✅ 按模板填 handoff 工件并落盘
- ✅ 校验工件完整性,写指标到
handoffs.jsonl
- ✅ 提示用户退出当前 session
- ❌ 不在旧 session 继续推进实质工作
- ❌ 不凭"记忆"重建状态
- ❌ 不省略模板必填字段
- ❌ 不退化为单纯压缩
Gotchas
- 误把
/compact 当 reset：compact 是压缩保留,reset 是清空 + 交接工件,二者不能互换
- 凭对话记忆重建状态(应该读 task.json + transcript + 文件系统)
- handoff 工件必填字段省略 → 下游 session 接不上,必须跑
fitness/handoff-lint.py 校验
- 忘记追加
handoffs.jsonl 指标 → 后续 review 无数据
流程
flowchart LR
A[采集状态] --> B[填 handoff 模板]
B --> C[校验工件]
C --> D[记录指标]
D --> E[提示用户退出]
步骤（脚本两阶段 + 主 Claude 补全）
- gen — 脚本采集文件系统状态（task.json snapshot + git status + 最近 commits）生成 draft:
python .claude/skills/context-reset/scripts/gen_handoff.py gen \
[--story-id <id>] --reason "<ctx-guard阻断|sprint收尾|context混乱>"
输出 draft 路径,含"自动采集"段(已填) + "待补全"段(标 TBD)
- 补全 — 主 Claude 读 draft,基于 transcript 补全 7 个 TBD 段:任务声明 / 已完成 / 下一步 / 关键约束 / 活跃工件 / 未决问题 / 禁止事项
- finalize — 校验 + 追加指标:
python .claude/skills/context-reset/scripts/gen_handoff.py finalize <draft_path>
任一 TBD 未补全 → 失败并列出 missing_fields
- 提示 — 输出建议新 session 用
/context-resume <path> 接力
关联
- 脚本:
.claude/skills/context-reset/scripts/gen_handoff.py
- 指标日志:
docs/reports/handoffs.jsonl
- 产出目录:
docs/reports/handoffs/YYYY-MM-DD-HHMM.md
