billion-context 的4大上下文管理工具详解:compress、decompress、search_context 与 acp_status 实战教程
billion-context 的4大上下文管理工具详解:compress、decompress、search_context 与 acp_status 实战教程
billion-context 是一款面向 AI 编程代理的上下文压缩插件:它把"已消费"的对话增量折叠成摘要,让 100K 的小上下文窗口也能撑住数月级、几十亿 token 的超长单会话,同时节省约 5 倍 token 开销。这篇教程带你吃透它注入给模型的 4 大上下文管理工具 —— compress、decompress、search_context 与 acp_status,理解"由模型自己决定何时压缩"的机制,并学会监控压缩效果与前缀缓存命中。
一、为什么长会话总被上下文窗口"卡死"?
AI 编程代理每发起一次模型调用,都要把完整历史重新发送一遍。会话越长,token 账单越高;一旦撞穿上下文窗口,会话质量骤降甚至直接中断。
billion-context 的解法:在任意代理(Claude Code、Codex、OpenCode、pi 等)与模型 API 之间架一个压缩代理,对请求流做增量、可逆、前缀缓存友好的压缩:
- 模型驱动 —— 不是硬性截断,而是由模型自己判断"何时压、压什么",把用掉的内容写成高保真摘要;
- 可逆 —— 折叠后的内容可以随时按需还原,甚至写回文件;
- 省钱 —— 健康会话能保持 95–97% 的前缀缓存命中率,压缩本身开销 ≤2%。
二、30 秒安装启动:三步跑起上下文压缩代理
Linux / macOS 推荐用户级前缀安装(免 sudo):
npm install -g billion-context --prefix=~/.local
然后二选一启动:
bili # 仅启动代理,把客户端 baseURL 前缀改成 http://localhost:8787/bili/
bili claude # 启动器:一条命令同时拉起代理 + 客户端(也支持 bili codex / bili pi / bili opencode 等)
验证代理已就绪:
curl -s http://localhost:8787/__bili/health
# → {"ok":true,"upstream":"https://api.anthropic.com"}
装好后无需任何手工操作:上下文增长时,模型会自己调用下面 4 个工具,代理在服务端代为执行。四大工具一览:
| 工具 | 一句话职责 | 典型时机 |
|---|---|---|
compress |
把一段对话折叠成详细摘要 | 上下文持续膨胀时 |
decompress |
还原被压缩的内容 | 需要精确细节时 |
search_context |
关键字搜索压缩块摘要 | 还原前先定位 |
acp_status |
上下文用量 + 可压缩区间总览 | 想知道"还能压什么"时 |
三、工具一:compress —— 把消费完的对话折叠成摘要
compress 是整个体系的核心:模型指定起止消息引用(mNNNNN 形式的 startId/endId)并附上自己写好的 summary,代理把这段消息从历史中替换成摘要块。四种参数形态(批量字符串、对象数组、扁平单区间)都接受,且多个区间建议合并进一次调用,避免反复改写请求前缀拖累缓存。
关键设计点:
- 增长提醒(nudge):默认每增长约 50K token 就温和提醒模型考虑压缩(
compress.nudgeGrowthTokens可调),同时 preflight 在"单条输入已超窗口"时作为硬兜底强制触发; - 摘要长度预算:每个摘要有字符上限,过大的区间应拆成多个小区间分别摘要、一次提交;
- 保护机制:首/末消息、进行中的工作等受保护内容不会被折叠。
工具 schema 与参数契约定义在 kernel/src/compress-tools.ts,代理侧的参数解析与容错(引号抢救、部分区间保留)在 src/compress-tool.ts。
四、工具二:decompress —— 需要精确细节时按需还原
压缩是有损的,但 billion-context 的压缩是可逆的。decompress 接收一个块 ID(如 b5):
- 默认向上还原一层(摘要 → 上一层细节);
full: true一路还原到原始消息;toFile不撑大上下文,而是把内容写入文件返回路径,模型再用读文件工具取用;- 可选
imageRef还能把被剥离/折叠的图片原始像素恢复成文件,传"list"可枚举当前可还原的图片。
子会话(subagent / fork)也受照顾:子会话出生时上报血缘,decompress 会沿父链回退,取回"自己从未见过"的内容(带环检测、深度上限 8)。内核侧对应 core.decompress("b3", state),见 kernel/README.md。
工具参数定义见 kernel/src/compress-tools.ts,代理侧的区间扩展与图片恢复参数注入在 src/compress-tool.ts。
五、工具三:search_context —— 先搜索,再还原
面对几十个压缩块,直接 decompress 容易"盲开"。search_context 对压缩块摘要与可见消息做关键字搜索,按相关度排序返回,官方描述写得很直白:
Search through compressed block summaries by keyword. Use BEFORE decompressing to find the right block.
参数很简单:query(必填,搜索词)与 limit(可选,默认 5 条)。于是推荐工作流是:
search_context("auth token")→ 定位到 b12;decompress("b12")→ 只还原真正需要的那一块。
这样既拿到了精确细节,又不会把整个会话塞回上下文。schema 见 kernel/src/compress-tools.ts。
六、工具四:acp_status —— 上下文用量与可压缩区间总览
acp_status 不带参数即输出上下文用量总览:窗口占用多少、已有哪些摘要块、哪些区间仍可继续压缩 —— 专门帮模型回答"下一步该压什么"。
一个容易被忽视的细节:报告里的可压缩区间是每次调用时从实时会话状态重新计算的,而不是读压缩前的快照,所以刚压完的引用不会立刻又出现在待压列表里。核心实现在 src/acp-status.ts。
在支持原生插件的客户端里,输入 /acp 可直接渲染当前会话的 ACP 状态面板;在 OpenAI Codex 等不能共存工具字段的客户端里,模型则通过 <acp_status> 文本触发器发起调用。工具 schema 见 kernel/src/compress-tools.ts。
七、实战验证:压缩生效了吗?缓存健康吗?
看日志:每次请求都会记录 processTurn 行;会话变长后会出现:
[acp-usage] round N input=X cached=Y (cache hit Z%)
加上 compress 事件行,即可确认压缩正在发生。
看 Web UI:浏览器打开 http://localhost:8787,会话详情页有缓存命中率折线图与折叠明细(每次折叠的压缩量、摘要量、折叠后命中率);客户端内输入 /acp-cache 可输出文字版报告:总账(HEALTHY 判定)、折叠经济学、异常明细,还有模型/密钥切换导致的缓存失效归因。经验法则:压缩本身成本 ≤2%,健康会话稳定在 95–97% 命中率;若持续偏低,按 ① 上游缓存 TTL 过期 → ② 切换模型 → ③ 代理 bug 的顺序排查。
论文数据同样能说明这套上下文管理工具的实际效果:4.5 个月、174,327 次模型调用、累计输入 18.76B token,在 204,800 token 窗口的模型上零窗口违规,最长会话达 12,049 次调用 —— 详见 paper 目录下的论文全文。
八、延伸阅读:相关源码与文档
- 四大工具官方速览:README.md
- 工具 schema 与系统提示词构建:kernel/src/compress-tools.ts
- 代理侧参数解析/归一化:src/compress-tool.ts
- 状态报告实现:src/acp-status.ts
- 压缩引擎设计说明(
processTurn/applyCompression心智模型):kernel/README.md - 各客户端接入方式(launcher / 原生插件 / URL 前缀):CLIENTS.md
- 压缩调优参数(
compress三级配置、nudge 节奏、窗口设置):CONFIGURATION.md
💡 小结:billion-context 的巧妙之处在于把"上下文管理"变成了模型自己的决策 —— acp_status 看全景、compress 折叠过去、search_context 找回来、decompress 拿细节,四件套配合前缀缓存友好设计,让小窗口也能跑马拉松。


