billion-context —— Codex 桌面版插件
把 billion-context 的上下文压缩 能力装进 Codex 桌面版:小上下文窗口(100K 就够)也能连跑数天、累计数十亿 token。
安装
从仓库根目录执行:
.\plugins\codex\scripts\install.ps1
或者手动执行等价的三步:
codex plugin marketplace add ranxianglei/billion-context
codex plugin add billion-context@billion-context
装完重启 Codex。
marketplace 必须是 Git 源。这是更新检测的前提:只有 Git marketplace 才有 版本推进语义,Codex 会把它识别成
sourceType=git并在后台自动拉取上游更新。local和npm源的版本号恒为null,插件页面永远看不到「有更新」。
它做了什么
插件注入一个 MCP server(bili),提供四个上下文管理工具:
| 工具 | 作用 |
|---|---|
compress |
把一段对话折叠成详细摘要 |
decompress |
需要精确细节时把压缩掉的区段还原回来 |
search_context |
在压缩摘要和可见消息里按关键词搜索 |
acp_status |
上下文占用概览,以及还有哪些区段可以压缩 |
压缩由模型自己决定何时触发、压缩什么;被折叠的区段保持摘要、随时可解压还原, 前缀缓存不失效。
关于压缩代理
插件负责工具面(让 Codex 的模型能调用压缩),压缩的执行面在 bili 代理里。 两者分工:
-
只装插件、不跑代理 → 四个工具会出现在 Codex 里,但
tools/list会报bili proxy unreachable …,因为没有会话被代理。 -
想让压缩真正生效,需要代理在跑:
bili start # 后台代理,监听 8787或者用
bili codex启动 Codex —— 它会同时拉起代理并把 Codex 的流量 指向代理,压缩与工具一起生效(零配置路线)。
更新
Codex 桌面版会自己拉取上游 Git marketplace 的新提交(内置的
plugins-marketplace-auto-upgrade 任务)。上游发新版本后:
- 插件页面的版本号会前进;
- 点更新(或执行
codex plugin remove+codex plugin add)即可装上新版本。
版本号以仓库的 package.json 为唯一真相源,
scripts/sync-codex-plugin-version.mjs 负责把它同步到所有插件清单,
发布流程里已经接了这个校验。
排障
工具列表是空的 / 报 proxy unreachable
说明 MCP server 起来了但代理没跑。先 bili start,再重启 Codex。
MCP server 起不来
插件里的 mcp-server.mjs 会依次找 dist/mcp.js:BILI_MCP_ENTRY 环境变量 →
仓库源码布局(<插件目录>/../../dist/mcp.js)→ 插件目录自身(<插件目录>/dist/mcp.js)
→ 全局 npm 安装目录。全都找不到时它会把已尝试的路径打到 stderr。
这时装一下 CLI 即可:npm install -g billion-context。
插件页面不显示图标
Codex 从插件目录读 interface 字段(显示名、简介、品牌色)。本插件的
interface 写在 .codex-plugin/plugin.json 里。