📌 项目地址：ranxianglei/billion-context | ⭐ 877 颗星 | 🔧 TypeScript | 📜 未标注
先看一组数字
一个编码 agent 会话，跑了 8,584 到 12,049 次模型调用，持续数月，累计输入 token 达到十亿量级。而模型窗口只有 204,800 token，全程零次窗口超限。
这是 billion-context 论文（仓库 paper/ 目录，v0.2）里记录的生产环境数据：4.5 个月，三台主机，174,327 次模型调用，累计输入 18.76B token（三台主机加起来约 24.7B）。
数字先放这，信不信往下看原理。
问题在哪
长编码会话有两个死法。一是上下文超窗口，会话直接挂掉；二是宿主（比如 Claude Code）的内置摘要器出手，把历史粗暴压缩。内置方案的问题在于整段重写，会把 prefix cache 的前缀打断，缓存全部失效，钱白花。
billion-context 的思路不同：压缩必须是增量的、可逆的、前缀缓存友好的。摘要按小范围写入，缓存前缀保持完整，摘要还能按需解压回原文。
还有一个关键设计：由模型自己决定何时压缩、压缩什么，靠注入的 compress 工具和压缩提示词完成。它不是设一个硬阈值然后截断。
它在哪一层
billion-context 是个本地代理，坐在 agent 和模型 API 中间：
Agent (Claude Code / Codex / Cursor / Aider ...)
│ 你把 agent 的 base URL 指向代理
▼
┌─────────────────┐
│ billion-context│ 1. 解析请求（Anthropic 或 OpenAI 格式）
│ proxy │ 2. 对对话执行 acp-kernel 压缩
│ │ 3. 注入 compress 工具 + 压缩哲学提示
│ │ 4. 转发给真实模型 API
│ │ 5. 改写流式响应
└─────────────────┘
▼
真实模型 API (Anthropic / OpenAI / 兼容接口)
压缩核心是 acp-kernel。对 Anthropic 和 OpenAI 两种请求格式都能处理，Claude Code、Codex、Cursor、Aider 这些主流 agent 理论上都能接。
安装：
npm install -g billion-context --prefix=~/.local
装好后把 agent 的 base URL 指过来就行。README 目前没给出代理的完整启动参数，这部分需要去仓库确认。
怎么判断它有没有用
这个项目给了一个很具体的健康指标：正常会话的 prefix cache 命中率应该维持在 95–97%，压缩本身的开销不超过 2%。
如果命中率持续低于这个区间，用 /acp 或 /acp-cache 排查。可能原因按概率排序：上游缓存 TTL 过期，切换了模型，项目 bug（可以上报），其他未知原因。
我见过不少项目只承诺“节省 token”，从不告诉你怎么验证。给一个可测量的指标，再给排查命令，这种做法值得肯定。
论文也开源，还是活文档
论文《Model-Driven Incremental Hierarchical Compression: Training-Free Multi-Generational Context Management for Long-Lived Coding Agents》放在仓库 paper/ 目录，MIT 协议，作者明确说这是活文档，任何人都可以提 PR 改进它。
要注意数据来源是作者自己的纵向研究，样本就是他自己的生产环境，不是独立第三方验证。数字详细（精确到 174,327 次调用这种粒度），但解读时心里有这层即可。
上手前想清楚几件事
第一，架构前提是所有流量都过这层代理。你得能改 agent 的 base URL，改不了的场景直接排除。
第二，方案是 training-free 的，压缩质量全靠模型自己。弱模型产出的摘要可能丢关键信息，用强模型才对得起这套设计。
第三，成熟度一般。877 star，论文还在 v0.2，README 自己都把 bug 列为缓存命中率下降的可能原因之一。作者坦诚，但也说明生产使用前应该先拿小会话跑一跑。
社区方面有 QQ 群：1056130197（已满）和 1108730198（开放）。
我的判断
如果你天天用 CLI agent 跑持续数天的任务，被窗口和账单两头挤压，billion-context 解决的正是这个具体痛点，而且给出了可验证的数字和排查工具，值得一试。
如果你的会话几小时就收工，token 消耗本来就不大，加一层代理纯属给自己找麻烦。