billion-context 完整实操指南：上下文压缩代理在 100K 窗口装下 5 倍工作量-优快云博客

billion-context 完整实操指南：上下文压缩代理在 100K 窗口装下 5 倍工作量

【免费下载链接】billion-context A context-compression plugin for month-long single sessions (billions of tokens) ,small context windows (a 100K context is enough) and token savings (5x fewer tokens) .上下文压缩插件，月级长会话会话，兼顾小窗口(100k上下文足矣)省token(省5倍token) . billion-context is all you need 项目地址: https://gitcode.com/GitHub_Trending/bil/billion-context

billion-context 是一个插在编码代理与模型 API 之间的上下文压缩代理。它向对话注入 compress / decompress / search_context / acp_status 四件工具，由模型自行决定何时压缩、压哪一段，已压历史可以按需展开，长会话不再坍缩成不可逆的黑盒摘要。本文先拆开机制与证据，再给出安装、调参与验证的完整路径。

先看机制：压缩后为什么丢不了细节

宿主自带压缩的常见死法：上下文逼近窗口时，整段历史被总结成一块不透明摘要，原文从此丢失。billion-context 换了一条路——它以代理形式运行在模型 API 前面，每次请求解析、改写、转发，并注入四件上下文管理工具：

compress：把一段消息区间折叠成摘要块；
decompress：需要精确细节时展开某个已压区间；
search_context：在摘要与可见消息中做关键词检索；
acp_status：上下文用量概览 + 哪些区间仍可压。

压缩时机与范围由模型按"当前任务还需要这份内容吗"判断，不由固定阈值决定；每段内容一生只被折一次，折完以摘要块形态常驻窗口，块本身还能再被折成 tier-2 / tier-3，形成逐层缩小的摘要金字塔。

布局的另一个承重设计是：历史只追加，压缩只停用已折叠的尾段区间，已建立的 KV 前缀缓存永远不会被一次压缩作废。这就是它和"改写式"压缩的本质差异——后者每压一次就击穿整个前缀。

关键数字从哪里来

指标	数值	口径
单次压缩输出体量	中位 185 token，97.5% 不超过 2K	17,783 个生产压缩块（08-20 快照）
折叠比	整体中位约 7.9×；工具输出主导块中位 24×、p75 45×	同上
重负载会话常驻摘要	原始历史约 90 万 token 最终只剩约 13K token，宏折叠约 70×	242 个被压缩量超 10 万 token 的会话
前缀缓存读占比	活跃节奏（调用间隔 <2 分钟，占 89% 流量）94.2%；两个带缓存宿主混合值 88.3–90.7%	四个半月生产遥测
窗口违规	204,800 窗口下 42,986 次调用，峰值 198,628，零违规	主宿主生产日志
受控对照	计费 token 较全量保留基线 −31–54%，重读调用 −63%，召回探针得分持平	单模型本地实验（窗口 65,536，小样本）

上述全部出自仓库 paper/ 目录中随代码开源的预印本（v0.2）：四个半月、三宿主、174,327 次模型调用、187.6 亿累计输入 token 的单用户观察性纵向研究。受控实验则是单模型（qwen3.8-27b、温度 0）n=1–3 种子的小样本初测。

标题里"5 倍"的口径：按上表的折叠比，窗口内常驻的摘要按 8–24 倍的比例置换了被折叠的原始历史，100K 窗口按 5 倍口径可承载约 500K token 的累计工作。项目自有的 1,500 题第三方盲测（见 benchmarks/third-party-1500/）给出了独立旁证：ContextBench 端到端 F1 以 0.3097 全场第一，比全量保留臂省 58.3% 成本。

安装与首次接入

一条命令安装：用户级 prefix

前置条件只有一个：Node ≥ 20（package.json 的 engines 字段）。Linux / macOS 推荐用户级 prefix：

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

发生了什么：bili 命令落入 ~/.local/bin（bili-proxy 是保留别名）。什么不会被改：npm 全局配置与系统目录，全程不需要 sudo，bili 自更新也不会再撞权限错误。用 nvm / Homebrew Node 或 Windows 的用户直接 npm install -g billion-context 即可——默认 prefix 本来就用户可写。若 ~/.local/bin 不在 PATH，把 export PATH="$HOME/.local/bin:$PATH" 写进 ~/.bashrc 或 ~/.zshrc。

三种接入方式，选最省事的一条

启动器（首选）：bili pi / bili claude / bili codex / bili opencode 等，一条命令拉起"代理 + 客户端"，不碰任何真实配置文件。客户端自己的配置只被读取——bili 用它发现实际连接的 HTTPS 上游主机，只把这些主机加进 MITM 白名单，其余流量盲透传。

原生插件：bili plugin install <client>，支持 pi / omp / opencode / dsh / kimi / hermes / zcode，装完照常启动客户端。两条注意项：

原生插件与独立进程内扩展（billion-context-pi、opencode-acp）互斥。后果：两者同时生效 = 双重压缩，同一份历史被两套压缩器各折一遍。安装器会自动替换旧条目并把原配置快照到 .bili-bak，但项目级安装不会被动，需手动移除。
OpenCode 走原生姿势时必须同时设 "compaction": { "auto": false }。后果：宿主原生自动压缩与 bili 抢同一份历史，两个压缩器互相污染对方的输出。

改 URL（最通用）：客户端 baseURL 前加 http://localhost:8787/bili/，完整上游地址内嵌在路径里，代理端无需任何配置。没有插件接缝的客户端（aider、copilot、zed 等）只有启动器或这条路，完整客户端矩阵见 CLIENTS.zh-CN.md。

发出第一条消息

bili pi

启动后在客户端发一条真实消息，另开终端验证转发：

curl -s http://localhost:8787/__bili/health
curl -s http://localhost:8787/__bili/stats

health 返回真实上游地址（如 {"ok":true,"upstream":"https://api.anthropic.com"}），证明流量去向正确；stats 在有真实请求穿过之后才有内容。所有 /__bili/* 管理端点都是纯 JSON，可脚本化。日志同时写入 ~/.local/state/billion-context/bili.log 与 stderr，接下来一节就是看日志该找哪些行。

按场景调三个参数组

配置文件：~/.config/billion-context/billion-context.json，首次运行自动落一个空模板，从不覆盖已有文件。同一开关多来源时的优先级：CLI 参数 > 环境变量 > 配置文件 > 内置默认值；compress 块支持全局 → provider → 模型三级合并，Web UI 可热改。完整参数表见 CONFIGURATION.zh-CN.md。

场景 A：日常小上下文，但允许单个任务爆发

诉求：平时上下文保持小，遇到大文件读取、大构建时不想中途被"压死"。

"compress": {
  "modelContextLimit": 200000,   // 钉在原生窗口：硬墙只在真实边缘
  "maxContextLimit": "35%"       // ≈70K 起进入强制 nudge 区（目标 = % × 原生窗口）
}

为什么不能直接把 modelContextLimit 压低：该字段同时扮演使用率分母与 preflight 硬墙，压得比原生窗口低时，任何超限载荷会在任务中途被折叠或直接快速失败。正确分工是 modelContextLimit 管硬墙、maxContextLimit 管软目标（配置文档"软目标与弹性余量"一节即为此设计）。

场景 B：首次压缩要到 ~200K 才出现

原因：触发不是按绝对窗口位置，而是按增长区间——首次软压缩在开机内容之上增长 50K（compress.nudgeGrowthTokens，恒定步长、与窗口大小无关）后才发。系统提示词很重（开机 ~100K）时，首压自然被推到 ~200K。

修复按官方推荐顺序：

删减系统提示词、关掉不用的工具、精简 skills——开机尺寸直接决定首次压缩的绝对位置；
确认 nudgeGrowthTokens 没被抬到 100k，调回 ~50k；
开启 "promptPack": "lean"——更短的压缩哲学提示，固定开销更低；
仍嫌晚，把 maxContextLimit 降到 "40%" 左右，压力带在使用率到该比例时就开始要求压缩，不再等增长节奏。

场景 C：大工具输出多，又不想丢细节

CCR（Content-Cache-and-Retrieve）在代理模式下默认开启：单次工具结果超过约 4000 token 时，原文一次性存入会话内容库，上下文只留一个占位符（类型、大小、命令预览、ref），模型用 acp_retrieve 把原文取回——取回内容走工具结果通道，不扰动已缓存前缀。相关旋钮：compress.ccr.minToolTokens、compress.ccr.excludeTools。

若某些工具的结果在任何情况下都不许折叠，写入 compress.protectedTools（全历史硬排除）。

最小完整配置

// ~/.config/billion-context/billion-context.json
{
  "port": 8787,
  "providers": {
    "https://api.anthropic.com": {
      "models": {
        "claude-sonnet-4-5": { "context": 200000, "output": 8192 }
      }
    }
  },
  "compress": {
    "modelContextLimit": 200000,
    "maxContextLimit": "75%",
    "emergencyThresholdPercent": "95%",
    "nudgeGrowthTokens": 50000,
    "promptPack": "lean"
  },
  "network": { "upstreamTimeoutMs": 900000 }
}

显式声明模型窗口，使用率分母才准；其余字段缺省即回退内置默认。

跑通后看什么：日志、报告与曲线

日志心跳

~/.local/state/billion-context/bili.log（镜像到 stderr）里找三行：

每请求一行 processTurn——请求确实穿过了代理；
[acp-usage] round N input=X cached=Y (cache hit Z%)——Z 的健康区间是 95–97%，压缩自身的代价 ≤2%（README 给出的经验值）；
对话变长后出现的 compress 事件——应当"沿途"出现，而不是等窗口快爆才动手。

想看每次 nudge 决策细节（growth / usage / pendingT1 / shouldInject），用 bili --debug 启动。

缓存报告与排查顺序

/acp-cache（原生插件宿主内的会话命令）或 GET /__bili/cache-report。报告四块：GRAND LEDGER 给出总账与 HEALTHY 或异常判定；FOLD ECONOMICS 逐折叠列出净省 token 与是否回本；LINE ITEMS 只列异常行（hit<85% 或 miss≥5000）。命中率持续偏低时按概率排序排查：

上游缓存 TTL 到期——报告里表现为 stable-prefix miss，top spikes 会点出闲置时长；
切换了模型——前缀键变化，整个前缀作废；
bili 的 bug——带报告页提 issue；
其他 / 未知。

上下文曲线与状态面板

打开 http://localhost:8787：总览、会话列表、实时日志、配置编辑器、上游连通性测试。逐会话的每请求上下文曲线，健康形态是有界区间的锯齿，而不是单调爬升：

论文中两个最长的生产会话（12,049 次与 8,584 次调用，累计 15.2 亿与 10.1 亿输入 token）轨迹即为此形态。原生插件宿主（opencode、dsh）里 /acp 直接在会话内渲染 ACP 状态面板——会话、摘要块、可压缩区间、用量三块；其余客户端看 Web UI：

它不解决什么：边界与取舍

逐字历史类任务不覆盖。 论文"我们不宣称的"一节明确：审计、合规、取证、多约束逐字重构在有损折叠的支持范围之外。第三方评测里 19.7 万字单句针尖检索子任务上，其精确匹配率（27.00% EM）明显低于 RAG 管线（59.00%–66.33%），有损折叠会抹平局部字面细节。任务核心是"从长历史里逐字引用某一行"的，别用。
模型不会自发解压。 受控实验中该模型规模下自发恢复工具采用为零——decompress / search_context 在被明确指示时才有效。"可恢复"是能力，不是习惯。
不缩小客户端自己的对话文件。 压缩缩的是发给模型的内容；客户端侧历史文件是用户数据，bili 从不改写。dsh 宿主上宿主自带自动压缩会被一并关闭（两个压缩器不能抢同一份历史），宿主侧文件随轮次增长，超长会话的收敛路径是重开新会话。
数字的口径。 "187.6 亿 token""94.2% 读占比"是单用户观察性生产数据，非随机对照；"31–54% 降幅"是小样本受控初测。它们不是对任意工作负载的承诺，调参前先看自己日志的读数。
Windows 部署点： 把 %USERPROFILE%\.local\share\billion-context\ 加入杀软排除项——长会话每轮重写状态文件，Defender 锁目录会导致 EPERM。会话文件清理是 opt-in 的（BILI_SESSION_GC=1），被压缩过的会话永不删除。
全链路透明、随时可退。 未识别端点原样转发；bili plugin remove <client>、停掉启动器或去掉 /bili/ 前缀后，流量立刻恢复直连。

先跑起来，再看数字

billion-context 的一句话价值：不是把窗口做大，而是让同一个窗口装下更多月的工作量——压缩判断交给模型，细节保持可恢复。最小下一步：按安装一节跑通第一条消息后，先不动任何旋钮，用默认配置观察一两个真实长任务，用 /acp-cache 确认总账判定稳定在 HEALTHY、命中率落在上文给出的健康区间，再按场景篇顺序动旋钮。你日志里那行 cache hit，才是唯一算数的结论。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考