billion-context — 面向 AI 编程 Agent 的上下文压缩代理

技能简介

billion-context 是一款面向 AI 编程 Agent（如 Claude Code、Codex、OpenCode、Cursor、Aider 等）的上下文压缩代理/插件，通过 npm 全局安装后作为本地代理挂在 Agent 与模型 API 之间。它把已消费的多轮对话折叠为分层、可解压、可检索的摘要，让单次会话可以从数小时延伸到数天乃至数月，累积数十亿 token 也不超出模型窗口。billion-context 与配套的 acp-kernel 算法在 4.5 个月、3 台主机、17.4 万次模型调用、187.6 亿 token 的实测中实现零窗口违规，且前缀缓存命中率稳定在 95–97%、压缩自身开销 ≤2%，适合任何"需要长会话"但"模型上下文窗口有限"的真实场景。

核心能力

1. 增量式分层压缩：acp-kernel 算法将对话按小段写入、逐层折叠为高保真摘要，而非简单截断，关键细节不丢失。
2. 可逆解压：decompress 工具按需把已压缩范围还原成原文，模型随时拿回细节，调试、长会话检索都方便。
3. 跨摘要检索：search_context 在已压缩摘要和可见消息上做关键词搜索，等价于给超长会话装上"记忆索引"。
4. 用量与可压缩性观测：acp_status 实时返回上下文用量、可压缩范围与命中率，便于排障与调优。
5. 前缀缓存友好：摘要按段写入，缓存前缀保持不变，对 Anthropic / OpenAI 等厂商的 prompt cache 命中率影响最小（实测 95–97%）。
6. 20+ 主流 Agent 客户端兼容：一套 bili 命令同时支持 Claude Code、Codex、OpenCode、pi、omp、dsh、kimi、hermes、zcode、Cursor、Aider、Cline、Gemini CLI、Qwen Code、Copilot CLI、Amp、Goose、Crush、Zed、Antigravity、MiniMax Code 等。
7. 三种部署模式：原生插件（bili plugin install）、启动器（bili）、URL 前缀覆盖（/bili/），任选其一即可生效。

安装配置

1. 全局安装 bili CLI：npm install -g billion-context --prefix=~/.local（用户级 prefix，免 sudo，Windows 用默认 npm prefix 即可）。
2. 把 PATH 加进 shell：export PATH="$HOME/.local/bin:$PATH"（写入 .bashrc / .zshrc），bili 命令即就绪。
3. 以 Claude Code 为例注册原生插件：/plugin marketplace add ranxianglei/billion-context → /plugin install billion-context@billion-context → /billion-context:bili-setup，重启 Claude Code 即可。

使用步骤

1. 选择你常用的 Agent（Claude Code / Codex / OpenCode 等），按官方渠道安装并完成账号登录。
2. 启动代理：以 Claude Code 为例运行 bili claude，或 Codex 走 bili codex 启动器；也可以只跑 bili 守护进程再手动改 baseURL。
3. 在 Agent 内正常对话，billion-context 自动注入 compress / decompress / search_context / acp_status 四个工具。
4. 当上下文增长接近窗口阈值时，模型会自动调用 compress 把旧对话折叠为分层摘要。
5. 需要回查细节时调用 decompress，或用 search_context 关键词检索；随时 /acp-cache 查看缓存命中率和压缩开销。

适用场景

1. 月级编程会话：让 Claude Code / Codex 连续几天重构大型代码库，不被上下文窗口截断。
2. AI Agent 产品研发：研究类 Agent 在长程任务里需要反复回看历史决策，避免因截断丢细节。
3. 高 token 成本对话：对外计费或对内消耗大的场景，省 5x token 直接折算为成本。
4. 小窗口模型部署：本地 32K / 100K 模型上跑出几百万 token 的"伪超长会话"体验。
5. 多 Agent 编排：subagent 之间共享压缩上下文，避免重复传全量历史。

适用人群

• 全栈 / 后端 / 系统工程师（长任务重构、跨文件改动）
• AI Agent 应用开发者（自家 Agent 想接入上下文压缩）
• AI 编程重度用户（Claude Code / Codex / Cursor 长期高强度使用）
• 个人 AI 助理自部署玩家（需要"长记忆 + 可控成本"）

工作原理

billion-context 作为本地 HTTP/HTTPS 反向代理，拦截 Anthropic / OpenAI 兼容协议的请求流。先用 acp-kernel 把对话按"小段、可解压、可前缀缓存命中"的方式压缩成层级摘要；再把四个上下文管理工具（compress / decompress / search_context / acp_status）注入到 system prompt；最后把压缩后的对话和工具表一起转发给真实模型 API，并把流式响应回写给客户端。摘要以小段写入意味着厂商 prompt cache 的前缀命中稳定，压缩本身只占总体 token 流的 2% 以内。

官方链接

• GitHub 仓库（含论文）：https://github.com/ranxianglei/billion-context
• npm 包：npm install -g billion-context（package name: billion-context）
• 配套算法库：https://github.com/ranxianglei/acp-kernel
• 客户端文档：仓库内 CLIENTS.md、TECHNICAL-NOTES.md
• 论文：仓库内 paper/model-driven-incremental-hierarchical-compression-training-free-multi-generational-context-management-for-long-lived-coding-agents.md（MIT 开源，可编辑）