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
32 changes: 25 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,13 +201,31 @@ skipping bili commands entirely:
without `dist/` and the bundle never loads) — same end state either way
(pnpm into the profile, bundled patch layer mounted by dsh itself); remove
through the same channel. See the dsh section below.
- **opencode:** add the bare npm name to your real config's plugin list —
`"plugin": ["billion-context"]` (npm form only; a git checkout has no
published entry). The package publishes `exports["./server"]` →
`dist/agent/opencode-native.js`, so opencode loads it through its own
Npm.add machinery and the plugin self-spawns exactly like the
bili-installed form. Do the two things the bili installer would have done
for you too: set `"compaction": { "auto": false }` in the same config
- **opencode:** easiest is `bili plugin install opencode` (it picks the
right entry form for your host version). Hand-install without bili (npm
form only; a git checkout has no published entry):
- **OpenCode 1.x** — add the bare npm name to your real config's plugin
list: `"plugin": ["billion-context"]`. The package publishes
`exports["./server"]` → `dist/agent/opencode-native.js`, so opencode
loads it through its own Npm.add machinery and the plugin self-spawns
exactly like the bili-installed form.
- **OpenCode 2.x** — the bare name does NOT work: 2.x resolves it through
the package `main` field (`dist/index.js`, the CLI — no plugin
definition), so the module load fails (#3976). Instead, put a one-line
re-export in a directory and point the config's `plugins` list at that
directory:

```js
// <shim dir>/index.js
export { default } from "<abs path to the global install>/dist/agent/opencode-native.js";
```

```json
{ "plugins": ["<shim dir>"] }
```

Either generation: do the two things the bili installer would have done
for you too — set `"compaction": { "auto": false }` in the same config
(otherwise OpenCode's native auto-compaction double-compresses) and keep a
manual backup of the file first.
- **claude:** this repository doubles as a Claude Code plugin marketplace —
Expand Down
15 changes: 14 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,20 @@ bili plugin remove <client> # 卸载(dsh 经同一通道移除;配置快照
客户端有自己的插件通道时,也可以原生安装、完全不用 bili 命令:

- **dsh:** `dsh plugin --profile <name> add billion-context` 正是 `bili plugin install dsh` 按 profile 驱动的那条命令(仅 npm 形态;git checkout 没有已发布入口 —— 直接填 GitHub 地址装到的是没有 `dist/` 的源码,bundle 永远加载不出来)—— 两种走法终态一致(pnpm 装进 profile、patch 层由 dsh 自己挂载);经同一通道卸载。见下文 dsh 段。
- **opencode:** 把裸 npm 包名直接写进你真实配置的插件列表 —— `"plugin": ["billion-context"]`(仅 npm 形态;git checkout 没有已发布入口)。包通过 `exports["./server"]` → `dist/agent/opencode-native.js` 暴露插件入口,opencode 用自己的 Npm.add 机制加载,插件自拉起的行为与 bili 安装的形态完全一致。另外要做两件 bili 安装器会替你做的事:在同一份配置里设 `"compaction": { "auto": false }`(否则 OpenCode 的原生自动压缩会双重压缩),并先手工备份该配置文件。
- **opencode:** 最省事是 `bili plugin install opencode`(它会按宿主版本选对入口形态)。不用 bili 手工安装(仅 npm 形态;git checkout 没有已发布入口):
- **OpenCode 1.x** —— 把裸 npm 包名直接写进你真实配置的插件列表:`"plugin": ["billion-context"]`。包通过 `exports["./server"]` → `dist/agent/opencode-native.js` 暴露插件入口,opencode 用自己的 Npm.add 机制加载,插件自拉起的行为与 bili 安装的形态完全一致。
- **OpenCode 2.x** —— 裸包名**不行**:2.x 走包的 `main` 字段(`dist/index.js`,是 CLI、没有插件定义)解析,模块加载失败(#3976)。正确写法是在一个目录里放一行重导出,再把配置的 `plugins` 列表指向这个目录:

```js
// <shim 目录>/index.js
export { default } from "<全局安装的绝对路径>/dist/agent/opencode-native.js";
```

```json
{ "plugins": ["<shim 目录>"] }
```

两个版本都要做两件 bili 安装器会替你做的事:在同一份配置里设 `"compaction": { "auto": false }`(否则 OpenCode 的原生自动压缩会双重压缩),并先手工备份该配置文件。
- **claude:** 本仓库同时是一个 Claude Code 插件市场 —— `/plugin marketplace add ranxianglei/billion-context`,再 `/plugin install billion-context@billion-context`,然后运行 `/billion-context:bili-setup`(它会替你驱动 `bili plugin install claude` 并提示重启)。终态与 bili 安装器一致;插件自身不携带 hooks 或 MCP 条目,不会双重注册。

pi / omp / kimi / claude 没有客户端侧通道 —— 它们的配置条目由 `bili plugin install <client>` 代写(kimi 的声明式 `kimi.plugin.json` + 注册记录、claude 的受管 settings 块等)。
Expand Down
23 changes: 15 additions & 8 deletions docs/clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -882,7 +882,7 @@ the V1 shape and 2.x hosts load the V2 `setup()`. The standalone
[`opencode-acp`](https://github.com/ranxianglei/opencode-acp) extension is
V1-only and does **not** load under 2.x — for OpenCode 2.x, billion-context
is the recommended context manager. Everything below is verified end-to-end
on `@opencode/cli` 2.0.3 (V1 lane: 1.14.46 and 1.18.31).
on `@opencode/cli` 2.1.0 (V1 lane: 1.14.46 and 1.18.31).

| Path | Command | When |
|---|---|---|
Expand Down Expand Up @@ -935,13 +935,20 @@ Registers a self-spawning plugin in your real opencode config and sets
face is added by default (the native plugin already provides the bili tools,
session-bound); pass `--with-mcp` to add one — the entry then carries no
origin pin, so it survives the plugin's ephemeral-port proxy restarts (#926).
Entry form depends on how THIS bili was installed: an **npm install** writes
the bare package name (`"plugin": ["billion-context"]`) — the package
publishes `exports["./server"]` → `dist/agent/opencode-native.js`, so
opencode loads it through its own Npm.add machinery; zero absolute paths, portable. (That exact bare-name entry doubles as a hand-install without bili — see README Quickstart Option 1.) A **git checkout / dev build** falls back to a local shim dir
(`<configDir>/plugins/billion-context/index.js` → this checkout's
`dist/agent/opencode-native.js`) — machine-local by construction; re-running
install from an npm install migrates the entry back to the bare name.
Entry form depends on the host generation AND how THIS bili was installed.
An **OpenCode 1.x npm install** writes the bare package name
(`"plugin": ["billion-context"]`) — the package publishes
`exports["./server"]` → `dist/agent/opencode-native.js`, so opencode loads
it through its own Npm.add machinery; zero absolute paths, portable. (That
exact bare-name entry doubles as a hand-install without bili — see README
Quickstart Option 1.) On an **OpenCode 2.x host** — and for any **git
checkout / dev build** — the installer writes a local shim dir instead
(`<configDir>/plugins/billion-context/index.js` → this install's
`dist/agent/opencode-native.js`): 2.x resolves a bare package name through
the package `main` field (`dist/index.js`, the CLI — no plugin definition),
so the bare name never loads there (#3976); re-running install (or a reinstall
to a new path) regenerates the shim to point at the current root, and a
legacy bare-name entry in a 2.x config is migrated to the shim automatically.

At load the plugin bootstraps its own proxy (attaches to a healthy instance
instead of doubling; parent-pid watchdog kills it when opencode exits),
Expand Down
4 changes: 2 additions & 2 deletions docs/clients.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ bili 只压缩路径匹配已知 wire 协议(`/chat/completions`、`/llm_raw_cha

## OpenCode

同一个内置插件同时服务两代 OpenCode:agent 文件同时保留 V1 `server()` 与 V2 `setup()` 导出 —— ≥ 1.18.29 的 1.x 宿主加载 V1 形状,2.x 宿主加载 V2 `setup()`。独立扩展 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 仅支持 V1,在 2.x 下**不加载** —— 对 OpenCode 2.x,**billion-context 是推荐的上下文管理方案**。以下均在 `@opencode/cli` 2.0.3 上端到端验证过(V1 泳道:1.14.46 与 1.18.31)。
同一个内置插件同时服务两代 OpenCode:agent 文件同时保留 V1 `server()` 与 V2 `setup()` 导出 —— ≥ 1.18.29 的 1.x 宿主加载 V1 形状,2.x 宿主加载 V2 `setup()`。独立扩展 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 仅支持 V1,在 2.x 下**不加载** —— 对 OpenCode 2.x,**billion-context 是推荐的上下文管理方案**。以下均在 `@opencode/cli` 2.1.0 上端到端验证过(V1 泳道:1.14.46 与 1.18.31)。

| 路径 | 命令 | 适用 |
|---|---|---|
Expand All @@ -304,7 +304,7 @@ HTTPS 走证书 MITM,HTTP 走临时 `opencode.json` 副本(`/bili/` 改写;JSONC

### 原生(免启动器)—— `bili plugin install opencode`

在真实 opencode 配置里注册一个自拉起插件并设 `compaction.auto: false`,之后直接跑 `opencode` 即可。默认不加 MCP 面(原生插件已提供会话绑定的 bili 工具);需要就传 `--with-mcp` —— 该条目不带 origin 钉扎,能扛过插件临时端口的代理重启(#926)。条目形态取决于**本 bili 自身的安装来源**:**npm 安装**写裸包名(`"plugin": ["billion-context"]`)—— 包经 `exports["./server"]` → `dist/agent/opencode-native.js` 暴露插件入口,opencode 用自己的 Npm.add 机制加载、自行管理安装与升级;零绝对路径、可跨机。(这个裸包名条目也可以不经 bili 直接手写进配置 —— 见 README 快速上手 方式 1。)**git checkout / 开发构建**回退到本机 shim 目录(`<configDir>/plugins/billion-context/index.js` → 该 checkout 的 `dist/agent/opencode-native.js`)—— 按构造即机器本地;之后改用 npm 安装再跑一次 install 会把条目迁回裸包名。
在真实 opencode 配置里注册一个自拉起插件并设 `compaction.auto: false`,之后直接跑 `opencode` 即可。默认不加 MCP 面(原生插件已提供会话绑定的 bili 工具);需要就传 `--with-mcp` —— 该条目不带 origin 钉扎,能扛过插件临时端口的代理重启(#926)。条目形态取决于**宿主代次**和**本 bili 自身的安装来源**。**OpenCode 1.x + npm 安装**写裸包名(`"plugin": ["billion-context"]`)—— 包经 `exports["./server"]` → `dist/agent/opencode-native.js` 暴露插件入口,opencode 用自己的 Npm.add 机制加载、自行管理安装与升级;零绝对路径、可跨机。(这个裸包名条目也可以不经 bili 直接手写进配置 —— 见 README 快速上手 方式 1。)在 **OpenCode 2.x 宿主**上 —— 以及任何 **git checkout / 开发构建** —— 改写本机 shim 目录(`<configDir>/plugins/billion-context/index.js` → 本次安装的 `dist/agent/opencode-native.js`):2.x 按包的 `main` 字段(`dist/index.js`,是 CLI、没有插件定义)解析裸包名,所以裸包名在那里永远加载不出来(#3976);重跑 install(或重装到新路径)会重新生成指向当前根的 shim,2.x 配置里遗留的裸包名条目也会被自动迁移为 shim。

加载时插件自拉起自己的代理(健康的已有实例直接复用不重复起;父进程 pid 看门狗在 opencode 退出时收掉它),把模型流量路由到 `<proxy>/bili/<upstream-url>`,暴露与启动器模式相同的原生 bili 工具 —— 无固定端口、无环境变量、免启动器。退出:`BILI_NATIVE_OPENCODE=0`。若没有任何代理能拉到健康状态,请求直连(不压缩)并给一次性告警,之后自动恢复。在 `bili opencode` 启动下该条目整体跳过(代理归启动器管)。

Expand Down
7 changes: 7 additions & 0 deletions scripts/live-files.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,13 @@ export const LIVE_FILES = [
// network I/O and binds no port, so no zone band is needed — the entry is for
// the tripwire alone, like #3890/#5114
"tests/cache-keepalive.test.ts",
// #5955: the only real child is ONE bare `node -e ""` spawned purely to
// hand back an already-reaped pid (win32 taskkill-then-SIGKILL silence);
// the takeover ladder itself runs on INJECTED deps — no proxy is started,
// no port is bound, no shutdown/kill signal ever reaches the OS. Fixed
// fake origins only, so no zone band is needed — the entry is for the
// tripwire alone, like #3890/#5114/#5666
"tests/issue5955-wedged-same-lane-takeover.test.ts",
];

/** Band width per live file: the zone ladder drifts +1 per EADDRINUSE retry;
Expand Down
Loading
Loading