billion-context 的4大上下文管理工具详解:compress、decompress、search_context 与 acp_status 实战教程

原创2026-10-15 06:32:071,837 阅读
文章标签:人工智能大模型LLM 网关API网关CLI开发工具AI 插件dsh-plugin

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%。

billion-context 上下文窗口布局:digest 摘要块分层收纳,recent zone 保留原文,decompress 按需还原到文件

二、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 条)。于是推荐工作流是:

  1. search_context("auth token") → 定位到 b12;
  2. 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 的顺序排查。

billion-context 长会话实战:两个生产马拉松会话(12049/8584次调用)的单次上下文始终压在204,800窗口红线以内

billion-context 前缀缓存命中率分层:两次调用间隔<2分钟时缓存读取占比达94.2%,占全部流量89%

论文数据同样能说明这套上下文管理工具的实际效果:4.5 个月、174,327 次模型调用、累计输入 18.76B token,在 204,800 token 窗口的模型上零窗口违规,最长会话达 12,049 次调用 —— 详见 paper 目录下的论文全文。

八、延伸阅读:相关源码与文档

💡 小结:billion-context 的巧妙之处在于把"上下文管理"变成了模型自己的决策 —— acp_status 看全景、compress 折叠过去、search_context 找回来、decompress 拿细节,四件套配合前缀缓存友好设计,让小窗口也能跑马拉松。

登录后查看全文
billion-context