省 Token：用 SmartCompact 在「提交/测试绿」时压缩 Claude Code 会话

省 Token：用 SmartCompact 在「提交/测试绿」时压缩 Claude Code 会话

长会话写代码时，真正烧钱的往往不是「模型想得久」，而是每一步都要把整段历史再读一遍。上下文越长，下一步越贵。

Claude Code、Codex、Pi 都有原生自动压缩，但它们大多等到窗口快满才动手——Claude Code 接近约 100 万 token，Codex 可配到约 80 万——而且不挑时机，常常卡在你改到一半、测试还红的时候。压完之后模型要重新摸清现场，既费钱又容易丢细节。

开源插件 SmartCompact（MIT）换了一个思路：上下文过线之后，只在「做完一件事」的停顿处压缩——比如刚提交、测试刚绿、任务刚收口。据作者测试报告，在 18～60 个连续开发任务上，成本约降 7%～44%，隐藏验收基本不掉；最长一组（60 任务）自称约 −44%。下面按官方 README 把安装、参数和避坑写清楚。

数字均为仓库 README / TEST-REPORT 自述，小样本、单一代码库，请标「据作者测试」，勿当普适财报。

它和「压输出 / 压检索」不是同一刀

如果你已经在用 RTK、squeeze、Headroom 一类工具，可以把省 token 拆成几层：

749《Headroom 实战》 讲的是「上下文怎么压得更短」；本文讲的是「什么时候压」。两件事叠在一起，长会话账单才会明显下来。

核心规则（三分钟看懂）

据官方中英文 README，SmartCompact 支持 Claude Code（CLI + 桌面）、Pi、Codex CLI：

1. 允许压缩线（默认 20 万 token）
   没过这条线：插件不起作用，也没有额外开销。
   过了之后：只要「上次压缩以来做过完一件事」，就在本轮结束时压。

2. 什么叫「做完一件事」
   识别 agent 跑过的命令：真实成功的 git commit、测试通过、任务完成等都算。
   一轮结束本身就是停顿点——不必非等到「下一轮再提交」才压，否则多半只是多花钱。

3. 绝不在做到一半时压
   只在一轮结束时判断；测试失败、构建红、连续报错、后台任务还在跑时先等着。

4. 宽限线（允许线 × 1.3，默认约 26 万）
   一直等不到合适时机、上下文过了宽限线，就在一轮结束时兜底压缩。

5. 进度笔记接上
   改过的文件、最近提交与测试结果、模型用 checkpoint 记下的决定，压缩后补回给模型，减少「压完两眼一抹黑」。

6. 预计腾不出足够空间就不压（默认最少腾出约 6 万 token），避免刚压完又立刻再压。

安装（按你用的 Agent 选）

Claude Code（需 2.1.295 及以上）

在 Claude Code 里执行：

/plugin marketplace add coffeecoproject/SmartCompact
/plugin install smartcompact@smartcompact

装好后新开会话生效。插件会把原生自动压缩线调到宽限线附近；当前会话若要暂时退回原生行为，用：

/smartcompact pause

恢复：

/smartcompact resume

看三条线、识别到的阶段节点和成本估算：

/smartcompact

或 /smartcompact report。

卸载：

/plugin uninstall smartcompact@smartcompact

Pi

pi install npm:smartcompact

默认在一轮结束（agent_settled）时，挑「刚做完一件事」的时机压缩。若你把 reserveTokens 调大、让 Pi 原生压缩提前，插件会在那个点按工作状态决定是否推迟。

卸载：pi remove npm:smartcompact。

Codex CLI（需 0.162+，以及 Node.js 22.18+）

codex plugin marketplace add coffeecoproject/SmartCompact
codex plugin add smartcompact@smartcompact

下次启动 Codex 时，按提示信任插件的 4 个 hook。hook 会自己找 Node.js 22.18+（PATH / nvm / Homebrew，也可用环境变量 SMARTCOMPACT_NODE）；找不到就什么都不做。

更新：

codex plugin marketplace upgrade smartcompact
codex plugin add smartcompact@smartcompact

若以前用过仓库里的 node scripts/codex.ts install，先在那份克隆里跑一次 node scripts/codex.ts uninstall，避免 hook 跑两遍。

卸载：codex plugin remove smartcompact@smartcompact。

Codex 注意： hook 不能推迟「一轮中间」的压缩。插件在一轮结束时判断，需要压时通过 Codex 共享后台服务在会话空闲时发起。codex exec 默认不走共享后台；Codex App（ChatGPT.app）目前也走不了——这两种情况下插件主要补进度笔记，压缩仍跟原生规则。想加兜底，可在 config.toml 顶部配置 Codex 自带的 model_post_turn_compact_threshold_percent（例如可用窗口约 87.2 万时设 31，约 26 万；详见官方测试报告）。

可调参数

配置入口：

• Claude Code：插件选项 allowLineTokens、graceFactor、minFreedTokens（留空用默认）
• Pi：--smartcompact-allow-line、--smartcompact-grace、--smartcompact-min-freed
• Codex：环境变量 SMARTCOMPACT_ALLOW_LINE、SMARTCOMPACT_GRACE、SMARTCOMPACT_MIN_FREED

日常长会话先用默认即可；若你的项目动不动就过 30 万上下文，再考虑略抬允许线，避免压得太勤、模型反复「重新熟悉代码」（这部分开销官方已计入成本对比）。

作者测试怎么读（别只盯 −44%）

据仓库结果表（同一代码库、连续开发任务，装与不装各跑多次；验收靠模型看不到的隐藏测试）：

读法建议：

• 会话越长、原生压得越晚，省得越多；短会话过不了 20 万，插件等于没开。
• 隐藏验收在报告里整体稳住；最长一组记忆题少对了 6 道（180 题里），说明随口交代的细节仍可能丢——重要约束请写进文件或让模型 checkpoint。
• 成本按各家价格折成「缓存读取 token 当量」，且已包含「压完后重新熟悉代码」的请求。

实战建议：接到工具站 / 计算器长会话里

我自己日常用 Claude Code / Codex 改工具站，常见套路是：规格 → 改代码 → 跑测 → 提交 → 下一刀。正好对应 SmartCompact 的「完成信号」。

可执行 checklist：

1. 装插件，新开一条长会话（旧会话不会自动带上 Claude Code 插件）。
2. 让 agent 养成「小步提交」：功能可跑就 git commit，而不是攒一大包再压——完成信号越清晰，压缩时机越好。
3. 测试命令别乱接管道：接了 | tail 又没开 pipefail 时，退出码不可信，不算测试结果（官方 FAQ）。
4. 关键决定写进 checkpoint / 仓库文档：进度笔记只记文件、提交、测试和模型主动记下的决定；用户随口说的「别动支付回调」一类，压完可能淡。
5. Claude Code 子进程注意环境变量：插件通过 CLAUDE_CODE_AUTO_COMPACT_WINDOW 调原生压缩点，从该会话拉起的 claude -p / 脚本会继承；若子进程不该提前压，启动前去掉该变量。
6. 用 /smartcompact report 对照账单：看识别到了哪些阶段节点、估算省了多少，再决定要不要改允许线。

避坑速查

总结

SmartCompact 不教你「怎么把上下文挤得更短」，它教你别在手术做到一半时关灯。允许线以下零打扰，过线后等提交 / 测试绿 / 任务收口再压，宽限线兜底，再用进度笔记把现场接上。

若你已经在用 Headroom、RTK 压内容和输出，再叠这一层「压时机」，长会话的账单和体验通常会一起好转。安装以官方仓库为准：coffeecoproject/SmartCompact；效果数字请始终标注「据作者测试报告」。

项目地址：coffeecoproject/SmartCompact（MIT）