十亿级上下文

项目简介

billion-context 是一个上下文压缩代理插件。它位于任意编码 Agent 与模型 API 之间，使用 acp-kernel 对 Anthropic 或 OpenAI 协议的流式请求进行重写。模型自行决定何时、对哪些内容生成高保真摘要，而不是依赖硬性截断。

解决的问题

长时编码会话会让上下文急剧膨胀：每 token 都在计费，一旦超出窗口会话就会降级或中断。billion-context 将已消费的对话压缩为分层摘要，使单个会话可以持续运行数天、通过单一上下文窗口处理数十亿 token。与宿主自带的摘要器相比，这里的压缩是增量、可逆且对前缀缓存友好的：摘要按小段写入、可按需解压、前缀缓存保持完整。

技术架构

代理位于客户端与模型 API 之间：

Agent (Claude Code / Codex / Cursor / Aider ...)
        │  将客户端的 base URL 指向代理
        ▼
┌─────────────────┐
│  billion-context│   1. 解析请求（Anthropic 或 OpenAI 形态）
│     proxy       │   2. 对会话执行 acp-kernel 压缩
│                 │   3. 注入 compress 工具与压缩策略
│                 │   4. 转发到真实模型 API
│                 │   5. 重写流式响应
└─────────────────┘
        │
        ▼
   真实模型 API（Anthropic / OpenAI / 兼容协议）

上下文管理工具

代理向会话注入四个工具，模型在上下文增长时自行调用，compress 由代理在服务端执行，已折叠的区间在历史中保持摘要状态直至恢复：

• compress：将一段消息折叠为详细摘要。
• decompress：需要原始细节时还原已压缩区间。
• search_context：在压缩摘要与可见消息上做关键词检索。
• acp_status：查看上下文占用与可压缩区间。

安装

Linux / macOS 推荐使用用户级前缀（避免 sudo 与权限问题）：

npm install -g billion-context --prefix=~/.local

bili 命令会安装到 ~/.local/bin（多数发行版已位于 PATH）。若不存在，可将 export PATH="$HOME/.local/bin:$PATH" 加入 ~/.bashrc 或 ~/.zshrc。在 nvm 或 Homebrew 安装的 Node 环境下，默认前缀已属于当前用户，直接 npm install -g billion-context 即可。Windows 的默认前缀（%APPDATA%\npm）同样可写。

bili-proxy 保留为别名。若旧版根用户拥有的前缀触发 EACCES，重装时仍需传入 --prefix=~/.local，这是永久修复方式。

三种使用方式

方式一：原生插件（bili plugin install <client>）

代理内置于客户端：安装一次后正常启动客户端即可，无需启动器、环境变量、固定端口或修改 URL。目前支持 pi、omp、opencode（1.x / 2.x）、dsh、kimi、hermes、zcode、claude、codex：

bili plugin install pi          # 在 pi 的 settings 中注册 billion-context 条目
bili plugin install omp         # 在 ~/.omp/agent/config.yml 写入扩展条目
bili plugin install opencode    # 注册插件并禁用原生自动压缩
bili plugin install dsh         # 对每个 profile 执行 dsh plugin --profile <name> add billion-context
bili plugin install kimi        # 写入 $KIMI_CODE_HOME/plugins/managed/billion-context/kimi.plugin.json
bili plugin install hermes      # 复制 Python 插件至 ~/.hermes/plugins/billion-context/
bili plugin install zcode       # 写入 hooks.enabled 与 mcp.servers.bili 配置
bili plugin remove <client>     # 撤销（dsh 走相同通道；配置快照保存为 .bili-bak）

bili plugin install codex 仅写入 [mcp_servers.bili] 块，因此 codex 用户需要先启动 bili（bili start 或其他客户端的 lane 代理）。

原生模式与独立扩展（billion-context-pi、opencode-acp）互斥——安装器会替换旧条目并将原配置快照到 .bili-bak。

方式二：启动器（bili <client>）

一条命令同时拉起代理与客户端：代理在独立端口运行（始终新开实例、永不复用端口），客户端通过证书 MITM 或 /bili/ 配置重写指向代理，真实配置文件始终不被修改。宿主配置仅用于读取其所用的 HTTPS 上游主机，并将这些主机加入 MITM 白名单。

示例：

bili pi                               # 代理 + 启动 pi（无文件改动）
bili codex                            # 代理 + 启动 codex
bili claude                           # 代理 + 启动 claude
bili opencode                         # 完整指南见 CLIENTS.md
bili kimi                             # Kimi Code CLI
bili gemini                           # Gemini CLI
bili iflow                            # iFlow CLI
bili qwen                             # Qwen Code
bili antigravity                      # Antigravity CLI（agy，Google）
bili aider                            # Aider
bili copilot                          # Copilot CLI
bili amp                              # Amp CLI
bili goose                            # Goose（Block，Rust/reqwest）
bili pi --mitm-domain api.foo.com     # 向 MITM 白名单追加域名

方式三：URL 修改（/bili/ 前缀）

先启动代理：

bili

然后在客户端的 baseURL 前加上 http://localhost:8787/bili/，完整的上游 URL 编码在路径中：

客户端 baseURL 修改前：  https://api.openai.com/v1
客户端 baseURL 修改后：  http://localhost:8787/bili/https://api.openai.com/v1

端口分配

bili start（手动模式）占用 8787。各 lane 自动分配的实例从 18787 起独立管理，端口冲突时 +1 漂移且每条 lane 记录漂移量；升级重启时会等待旧构建释放端口（最长 5 秒）以避免漂移。

验证

代理运行后执行健康检查与实时统计：

curl -s http://localhost:8787/__bili/health
# → {"ok":true,"upstream":"https://api.anthropic.com"}

curl -s http://localhost:8787/__bili/stats    # 实际请求后的会话统计

随后从客户端发送一条消息，观察日志（~/.local/state/billion-context/）中的压缩活动。