Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"name": "billion-context",
"interface": {
"displayName": "billion-context"
},
"plugins": [
{
"name": "billion-context",
"version": "0.1.205",
"source": {
"source": "local",
"path": "./plugins/codex"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Developer Tools"
}
]
}
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"name": "billion-context",
"source": "./",
"description": "Context-compression plugin for Claude Code · month-long single sessions (billions of tokens) · high compression quality even in small context windows (100K is enough) · 5× fewer tokens",
"version": "0.1.188",
"version": "0.1.205",
"author": {
"name": "ranxianglei"
},
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "billion-context",
"version": "0.1.188",
"version": "0.1.205",
"description": "Context-compression plugin for Claude Code · month-long single sessions (billions of tokens) · high compression quality even in small context windows (100K is enough) · 5× fewer tokens",
"author": {
"name": "ranxianglei"
Expand Down
8 changes: 8 additions & 0 deletions .github/workflows/release-bugfix.yml
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,14 @@ jobs:
[ -z "$SHA" ] && SHA="$(git rev-parse HEAD)"
echo "::notice::Publishing carve-out from '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)"

- name: Check plugin manifest versions (#4449)
# Same gate as release.yml: the carve-out PR head is a frozen tree
# (last tag + fix + bump), so it must ALREADY carry the synced plugin
# manifests — drift fails fast here instead of shipping a release whose
# marketplace update detection never fires. See reference/release.md.
if: steps.resolve.outputs.proceed == 'true'
run: node scripts/sync-codex-plugin-version.mjs --check

- name: Publish guard (monotonic + not-already-live)
if: steps.resolve.outputs.proceed == 'true'
run: |
Expand Down
14 changes: 9 additions & 5 deletions .github/workflows/release-manual.yml
Original file line number Diff line number Diff line change
Expand Up @@ -148,15 +148,19 @@ jobs:
console.log(`${f}: replaced ${n} occurrence(s)`);
}
' "$(node -p "require('./package.json').version")" "${{ steps.version.outputs.version }}"
# #4449: plugin manifests (.agents/.claude-plugin/plugins/codex) carry
# their version from package.json — sync them into the same release
# commit or marketplace update detection sees a stale version.
node scripts/sync-codex-plugin-version.mjs

- name: Verify bump diff
run: |
git add package.json package-lock.json
git add package.json package-lock.json .agents .claude-plugin plugins/codex
CHANGED="$(git diff --cached --name-only)"
EXPECT="package-lock.json
package.json"
if [ "$CHANGED" != "$EXPECT" ]; then
echo "::error::bump touched unexpected files: $CHANGED"
[ -n "$CHANGED" ] || { echo "::error::bump produced no changes"; exit 1; }
BAD="$(printf '%s\n' "$CHANGED" | grep -vE '^(package\.json|package-lock\.json|\.agents/plugins/marketplace\.json|\.claude-plugin/marketplace\.json|\.claude-plugin/plugin\.json|plugins/codex/\.codex-plugin/plugin\.json)$' || true)"
if [ -n "$BAD" ]; then
echo "::error::bump touched unexpected files: $BAD"
exit 1
fi

Expand Down
11 changes: 11 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,17 @@ jobs:
echo "is_release=false" >> $GITHUB_OUTPUT
fi

- name: Check plugin manifest versions (#4449)
# Codex/Claude plugin marketplaces detect updates by the declared
# manifest version vs the installed cache version, so the four
# manifests (.agents/plugins, .claude-plugin x2, plugins/codex) must
# match package.json. The release branch carries the synced manifests
# as their own commit (reference/release.md step 3.5); drift here
# means the branch was prepared without that step — fail fast, before
# any CI dispatch, tag, or publish.
if: steps.check.outputs.is_release == 'true'
run: node scripts/sync-codex-plugin-version.mjs --check

- name: Full CI dispatch (missing lanes, publish sha)
# Policy (2026-10-10, after the v0.1.192 carve-out): every release
# channel must run the COMPLETE CI set at the exact publish sha before
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,8 @@ Split extra findings into their own issues/PRs rather than expanding this one's
Releases are fully automated via CI (`.github/workflows/release.yml`): the Agent prepares a release PR; merging it builds, tests, publishes to npm, tags, and creates a GitHub Release. Kernel releases (`acp-kernel`) use the parallel flow in `.github/workflows/release-kernel.yml` (below). There's also a one-click fast path for routine patches. Hard rules (exact steps + internals in [reference/release.md](reference/release.md)):

- **Owner-approved start (owner rule 2026-10-12, #2910):** an Agent runs the release flow (steps 1–6 below) ONLY after the owner explicitly approves the release in the trigger thread (「发版 vX」). Triage that ends at "fix stranded on master, users blocked" PROPOSES the release in the issue thread and stops — what ships and when belongs to the owner. Origin: #2906 → a bot autonomously cut v0.1.196 (#2910) mid-triage; every mechanical rule held (no publish, no merge, branch naming, version-only-on-release-branch) yet the decision to ship was never the bot's to make.
- **Branch** `YYYY-MM-DD_release-v{VERSION}`; commit `release v{VERSION}` changing ONLY `version`. The Agent does steps 1–6 (sync master → branch → bump → **release-notes entry if severe (#1870)** → pre-flight typecheck+test+build → commit/push/open PR); HUMAN merges step 7; CI publishes step 8.
- **Branch** `YYYY-MM-DD_release-v{VERSION}`; commit `release v{VERSION}` changing ONLY `version`. The Agent does steps 1–6 (sync master → branch → bump → **sync plugin manifest versions (#4449)** → **release-notes entry if severe (#1870)** → pre-flight typecheck+test+build → commit/push/open PR); HUMAN merges step 7; CI publishes step 8.
- **Plugin manifest versions sync on every release (#4449).** The four plugin manifests (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json`, `plugins/codex/.codex-plugin/plugin.json`) carry their own `version` fields, which the Codex/Claude marketplaces use for UPDATE DETECTION — they must equal `package.json`. After the version-bump commit, run `node scripts/sync-codex-plugin-version.mjs` and commit the result as its own `chore:` commit on the release branch (the one-click lane runs it inside CI automatically). ALL THREE publish workflows (`release.yml`, `release-manual.yml`, `release-bugfix.yml`) run `--check` BEFORE tag/publish: drift = red release, nothing shipped. Consequence: a bugfix carve-out PR head (last tag + fix + bump) MUST also carry the synced manifests or its gate fails.
- **Release-notes entry (#1870, OPT-IN since 2026-10-04):** only SEVERE releases need an entry in `release-notes/package.json`; ordinary releases ship with NO entry (the gates log a notice and pass when absent, validate when present). Add a severe entry as its own commit in the SAME release PR; the one-click fast path needs it already merged to master before dispatching. Full rules: [reference/release.md](reference/release.md) + `release-notes/README.md`.
- **Bugfix carve-out channel (#2011, PR-gated since #2851):** emergency hotfixes ship as a normal-looking release PR whose head branch keeps the `bugfix-release/v{VERSION}-{slug}` marker (cut from the last released TAG, containing ONLY the fix + version bump); merging it publishes the PRE-MERGE PR-head tree — strictly excluding master's other unreleased work. Pushing such a branch triggers nothing anymore; a manual `workflow_dispatch` on an explicitly chosen ref remains the emergency fallback. Mechanics and constraints: [reference/release.md](reference/release.md). Batch form: a standing patch train (same `bugfix-release/**` branches + the `backport` label bot routing merged fixes onto it via cherry-pick, 2026-10-24) — see "Dual-lane releases" in the same doc.
- **NEVER run `npm publish` manually** — CI does it (§4).
Expand Down
34 changes: 34 additions & 0 deletions plugins/codex/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{
"name": "billion-context",
"version": "0.1.205",
"description": "Context-compression plugin for Codex — small context windows (100K is enough), 5x fewer tokens, month-long single sessions (billions of tokens), and high compression quality.",
"author": {
"name": "ranxianglei"
},
"homepage": "https://github.com/ranxianglei/billion-context",
"license": "MIT",
"keywords": [
"context",
"compression",
"long-context",
"token-saving",
"acp"
],
"mcpServers": "./.mcp.json",
"interface": {
"displayName": "billion-context",
"shortDescription": "上下文压缩:100K 窗口跑出十亿 token 的长会话",
"longDescription": "把 Codex 的对话历史做增量分层压缩:模型自己决定何时压缩、压缩什么,被折叠的区段保持摘要、可随时解压还原,前缀缓存不失效。一个上下文窗口连跑数天、累计数十亿 token 而不爆窗。插件注入四个上下文管理工具(compress / decompress / search_context / acp_status),模型会在上下文变长时自行调用。",
"developerName": "ranxianglei",
"category": "Developer Tools",
"capabilities": [
"Read",
"Write"
],
"defaultPrompt": [
"查看当前会话的上下文压缩状态",
"把最近的一段对话压缩掉"
],
"brandColor": "#10a37f"
}
}
24 changes: 24 additions & 0 deletions plugins/codex/.mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"mcpServers": {
"bili": {
"command": "node",
"args": [
"./mcp-server.mjs"
],
"env_vars": [
"BILI_MCP_PROXY",
"BILI_CONVERSATION_ID",
"PATH",
"APPDATA",
"LOCALAPPDATA",
"USERPROFILE",
"HOME",
"XDG_CONFIG_HOME",
"XDG_DATA_HOME",
"XDG_STATE_HOME",
"TMPDIR"
],
"startup_timeout_sec": 30
}
}
}
85 changes: 85 additions & 0 deletions plugins/codex/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# billion-context —— Codex 桌面版插件

把 [billion-context](https://github.com/ranxianglei/billion-context) 的上下文压缩
能力装进 Codex 桌面版:小上下文窗口(100K 就够)也能连跑数天、累计数十亿 token。

## 安装

从仓库根目录执行:

```powershell
.\plugins\codex\scripts\install.ps1
```

或者手动执行等价的三步:

```powershell
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 …`,因为没有会话被代理。
- 想让压缩真正生效,需要代理在跑:

```powershell
bili start # 后台代理,监听 8787
```

或者用 `bili codex` 启动 Codex —— 它会同时拉起代理并把 Codex 的流量
指向代理,压缩与工具一起生效(零配置路线)。

## 更新

Codex 桌面版会自己拉取上游 Git marketplace 的新提交(内置的
`plugins-marketplace-auto-upgrade` 任务)。上游发新版本后:

1. 插件页面的版本号会前进;
2. 点更新(或执行 `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` 里。
135 changes: 135 additions & 0 deletions plugins/codex/mcp-server.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
#!/usr/bin/env node
// Codex 插件的 MCP server 启动器。
//
// Codex 把插件装到 ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/,
// 这个目录里只有插件自身的文件。billion-context 的 MCP 外壳(dist/mcp.js)
// 来自 npm 包或者仓库源码,两者都不在这个目录里,所以这里按优先级探测:
//
// 1) BILI_MCP_ENTRY —— 显式指定 dist/mcp.js 的绝对路径(最高优先级)
// 2) 仓库源码布局:<插件目录>/../../dist/mcp.js(开发检出时优先用本仓库
// 自己的构建,而不是可能过期的全局安装)
// 3) 插件目录自身(dist/mcp.js 就在插件目录里的布局)
// 4) 全局 npm 安装的 billion-context(npm root -g 下的包目录;npm 不在
// PATH 上时兜底 AppData\npm\node_modules)
//
// 找到之后以 child_process 的 stdio 管道原样转发:Codex 说 JSON-RPC,
// dist/mcp.js 说 JSON-RPC,中间不做任何解析,避免协议漂移。
//
// 必须用 spawn 而不是 import():dist/mcp.js 里的 stdio 循环只在它
// "作为脚本被直接执行"时启动(见 src/mcp.ts 末尾的 invokedAsScript 守卫),
// 被 import() 加载时它只会导出 runMcpStdio,不会接管 stdin。

import { spawn, spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const HERE = path.dirname(fileURLToPath(import.meta.url));

function isFile(p) {
try {
return fs.statSync(p).isFile();
} catch {
return false;
}
}

/** 全局 npm root(可能不止一个:nvm / pnpm / yarn 各自一处)。 */
function globalNpmRoots() {
const roots = [];
const probe = (cmd, args) => {
try {
const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 8000 });
const out = (r.stdout || "").trim();
if (r.status === 0 && out) roots.push(out);
} catch {
/* npm 不在 PATH 上是常态,忽略即可 */
}
};
probe("npm", ["root", "-g"]);
// Windows 上 npm 不在 PATH 时的常见全局安装位置(npm root -g 探针失效的兜底)
const appData = process.env.APPDATA;
if (appData) roots.push(path.join(appData, "npm", "node_modules"));
return roots;
}

function candidates() {
const out = [];

const explicit = process.env.BILI_MCP_ENTRY?.trim();
if (explicit) out.push(explicit);

// 仓库源码布局:插件目录的上两级是仓库根,dist/mcp.js 在那里
out.push(path.resolve(HERE, "..", "..", "dist", "mcp.js"));
// 插件目录自己就是包根(npm 源安装时 dist/mcp.js 在插件目录里)
out.push(path.join(HERE, "dist", "mcp.js"));

for (const root of globalNpmRoots()) {
out.push(path.join(root, "billion-context", "dist", "mcp.js"));
}

return out;
}

function resolveEntry() {
for (const c of candidates()) {
if (isFile(c)) return c;
}
return null;
}

// Codex 启动 MCP server 时给的 cwd 可能是插件目录,也可能不是(不同版本的
// 行为不一样)。mcp-server.mjs 用 import.meta.url 定位自己的位置,所以
// cwd 无关;但 dist/mcp.js 内部会按 cwd 找配置(~/.config/billion-context 等),
// 那里是绝对路径,所以也不受影响。这里只做一件事:把 cwd 钉到插件目录,
// 让相对路径的引用(比如 README、scripts/)在任何宿主下都指向插件自己的文件。
process.chdir(HERE);

const entry = resolveEntry();

if (!entry) {
// 不能静默退出:Codex 会看到一个"启动了但立刻消失"的 MCP server,
// 报错信息还指向一个不存在的端口。把缺失说清楚。
process.stderr.write(
"[bili-codex] 找不到 billion-context 的 MCP 入口(dist/mcp.js)。\n" +
"[bili-codex] 已尝试:\n" +
candidates()
.map((c) => ` - ${c}`)
.join("\n") +
"\n" +
"[bili-codex] 请安装 CLI:npm install -g billion-context\n" +
"[bili-codex] 或设置 BILI_MCP_ENTRY 指向 dist/mcp.js 的绝对路径。\n",
);
process.exit(1);
}

const child = spawn(process.execPath, [entry], {
stdio: ["pipe", "pipe", "pipe"],
env: process.env,
});

child.on("error", (err) => {
// spawn 本身失败(极少见)时给一个可定位的报错,而不是裸的未处理事件。
process.stderr.write(`[bili-codex] 无法启动 MCP 入口 ${entry}: ${err.message}\n`);
process.exit(1);
});

// stdio 三路直接对接,中间不加任何缓冲或解析。
process.stdin.pipe(child.stdin);
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

child.on("exit", (code, signal) => {
if (signal) process.kill(process.pid, signal);
else process.exit(code ?? 0);
});

for (const sig of ["SIGINT", "SIGTERM"]) {
process.on(sig, () => {
try {
child.kill(sig);
} catch {
/* 子进程已经退出 */
}
});
}
Loading
Loading