会话交接系统:长上下文预警 + compact/clear 前后的归档与接续。
| 文件 | 角色 |
|---|---|
context_meter.py |
Stop hook。每回合读 transcript 尾部最后一条 assistant 记录的 message.usage(真实 token,非估算),systemMessage 报一行上下文大小;越过双档阈值(软 200k 预警留意收尾点 / 硬 350k 尽快 wrap)时给模型塞 additionalContext 提醒。 |
precompact_snapshot.sh |
PreCompact hook。压缩前抓 git log/status/diff 机械快照到 <project>/.claude/handoff/auto-precompact-<ts>.md,兜底"忘了 /wrap 被 auto-compact 突袭"。不阻塞压缩。 |
session_start_inject.py |
SessionStart hook。compact/clear/resume 后把 NEXT.md 的 goal/now 注回上下文;startup 只给一行提示。 |
skill_gate_override.py |
可选 PostToolUse hook(matcher: Skill,默认不装)。brainstorming skill 载入时注入提醒:用户已永久豁免其 "User Review Gate"(spec 写完不停等用户审,双 review 干净后直接进 writing-plans)。绑定作者个人 CLAUDE.md 工作流,别人装了只会看到不相干的提醒——如果你有同款"某 skill 步骤想永久覆盖"的需求,可参考它改造。 |
install_settings.py |
幂等 installer:三个核心 hook + cleanupPeriodDays:3650 装进 ~/.claude/settings.json,并把 skills/wrap/SKILL.md 拷到 ~/.claude/skills/wrap/。可重跑(重跑即同步 skill 更新);--with-skill-gate 额外装上面的可选 hook。 |
skills/wrap/SKILL.md |
/wrap skill(installer 拷到 ~/.claude/skills/wrap/):先确保 .git/info/exclude 忽略 handoff → 重写 NEXT.md(push)→ commit 本段工作(只 add 相关文件、handoff 永不入库、不 push)→ 追加 devlog.md(pull)→ 建议 compact/clear。 |
<project>/.claude/handoff/NEXT.md— 下一步行动清单(push,每次覆盖,SessionStart 注回)。<project>/.claude/handoff/devlog.md— 追加式开发日志(pull,按需读)。.claude/handoff/由/wrap写进.git/info/exclude本地忽略,不进版本历史。
| 变量 | 默认 | 说明 |
|---|---|---|
WRAP_CONTEXT_THRESHOLD_SOFT |
200000 |
软档:提前预警"留意下一个自然收尾点,到点建议 /wrap"(= 硬档减一节工作量的余量) |
WRAP_CONTEXT_THRESHOLD |
350000 |
硬档:"别再展开新的大块工作,尽快 wrap"(主力模型 1M 窗口,350k 仅 35%,不撞 auto-compact;实测 clear 后重建工作状态基线 ~50k,旧 250k 工作空间太挤) |
WRAP_CONTEXT_LIMIT |
1000000 |
上下文上限(仅用于报数百分比显示) |
WRAP_REMIND_DELTA |
30000 |
同档内去抖:上次提醒后须再涨这么多 token 才重复提醒 |
在 ~/.claude/settings.json 的 env 块设置即可覆盖。
为什么双档:上下文按大块增长(一节工作 + 一轮反馈可涨 100k+),单一阈值越线后才首提,往往已冲到 146k+、错过了之前的收尾点。软档留出"约一节工作量"的余量,让模型提前规划在下一个停顿点 wrap;硬档兜底。
报数 vs 提醒(去抖):每回合都会通过 systemMessage 给你报一行上下文大小(过软档带 additionalContext 提醒则去抖——每档首次越线必提醒(soft→hard 升档不受去抖压制),之后同档内每再涨 WRAP_REMIND_DELTA 才重复(状态按 session 存在 ~/.claude/.wrap-state/),compact 后跌回软档下会重置。这样避免每回合重复灌提醒污染上下文。
git clone https://github.com/TheGreatCBH/wrap-context-handoff.git
cd wrap-context-handoff
python3 install_settings.py # 装三个核心 hook + /wrap skill(幂等,可重跑)
python3 -m json.tool ~/.claude/settings.json >/dev/null && echo VALID
python3 tests/run_tests.py # 跑测试装完重启 Claude Code(或新开会话)生效。要求:macOS/Linux、python3、jq 非必需。已有 ~/.claude/settings.json 时 installer 只做增量合并,不动你现有配置;没有则新建。
/wrap 归档时会自动做一次本地 git commit(不 push、只 add 任务相关文件、交接文档永不入库、pre-commit 被拒不绕过)。不想要此行为,装前删掉 skills/wrap/SKILL.md 的 3b 步即可。
- 关某个 hook:编辑
~/.claude/settings.json,删掉对应 command 项。 - 调阈值:在
settings.json的env设WRAP_CONTEXT_THRESHOLD_SOFT(软)/WRAP_CONTEXT_THRESHOLD(硬)。 auto-precompact-*.md快照只增不清,可定期手动清理 handoff 目录。
- 上下文大小 = 最后一条 assistant
usage的input_tokens + cache_read_input_tokens + cache_creation_input_tokens + output_tokens,是 API 真实计数;compact 后自动反映压缩后的小上下文。 - 大 transcript(可达数百 MB)从文件尾部往前读,不整文件加载。
/compact无法被程序触发(hook/skill 都不行),故本系统只做"预警 + 归档 + 接续",压缩仍由用户手敲。