From eab4bbcd37e8b196bd4a21dc66f67d7b2a742bf0 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sat, 19 Sep 2026 19:53:02 +0800 Subject: [PATCH 1/2] docs: move mechanism details out of Quickstart into TECHNICAL-NOTES (#985) --- CONFIGURATION.md | 2 +- CONFIGURATION.zh-CN.md | 2 +- README.md | 100 +++++++++------------------------------ README.zh-CN.md | 25 ++-------- TECHNICAL-NOTES.md | 89 ++++++++++++++++++++++++++++++++++ TECHNICAL-NOTES.zh-CN.md | 30 ++++++++++++ 6 files changed, 149 insertions(+), 99 deletions(-) create mode 100644 TECHNICAL-NOTES.md create mode 100644 TECHNICAL-NOTES.zh-CN.md diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 04d25dceae..90515bbf9e 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -712,7 +712,7 @@ Where upstreams are discovered from (read-only): ### Generated files (what gets written — last resort only, #535) -The launcher prefers file-free injection (env vars > CLI flags/extension APIs > generated files; see README, “Injection priority” section). Where a file is unavoidable it is a **copy** — the real config is never edited: +The launcher prefers file-free injection (env vars > CLI flags/extension APIs > generated files; see TECHNICAL-NOTES.md, “Injection priority” section). Where a file is unavoidable it is a **copy** — the real config is never edited: - **pi / omp** — nothing is written (#535): provider baseUrls ride the `BILI_PROVIDER_REWRITES` env manifest consumed by the bili extension at load (`registerProvider`), and auto native compaction is cancelled in-extension (`session_before_compact`; omp distinguishes auto vs manual via the `auto_compaction_start` announcement, #851) — manual `/compact` stays user-owned. The real `~/.pi` / `~/.omp` homes are untouched. - **opencode** — a temp `opencode.json` pointed at by `OPENCODE_CONFIG` (removed when the client exits), with `/bili/`-rewritten plaintext baseURLs **plus the thin `/acp` plugin appended**. On OpenCode 1.x the `opencode-acp` entries are stripped from the clone (the host must not load it armed) and the thin plugin imports that same package as a library instead, gated on legacy sessions; the first stripped spec rides along via `BILI_OPENCODE_ACP_SPEC` so the bridge imports the exact copy the host would have loaded (#920). Relative local plugin specs (`./x`, `../x`) are re-anchored to absolute paths in the clone — opencode resolves them against the declaring config file's dir, which the clone no longer is (#826). diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index e06892cffb..4bbb128023 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -708,7 +708,7 @@ Claude Code 的 undici fetch 忽略 `HTTPS_PROXY`,所以证书 MITM 拦不到 ### 生成文件(写了什么 —— 最后手段,#535) -启动器优先零文件注入(env > CLI 参数/扩展 API > 生成文件;见 [README —— 注入优先级](README.zh-CN.md))。确实绕不开文件时写的都是**副本** —— 真实配置绝不编辑: +启动器优先零文件注入(env > CLI 参数/扩展 API > 生成文件;见 [TECHNICAL-NOTES.zh-CN.md —— 注入优先级](TECHNICAL-NOTES.zh-CN.md))。确实绕不开文件时写的都是**副本** —— 真实配置绝不编辑: - **pi / omp** —— 不写任何文件(#535):provider baseUrl 走 `BILI_PROVIDER_REWRITES` env 清单,由 bili 扩展加载时消费(`registerProvider`);自动原生压缩改由扩展内取消(`session_before_compact`,omp 按 `auto_compaction_start` 预告区分自动/手动,#851),手动 `/compact` 保持用户所有。真实 `~/.pi` / `~/.omp` 主目录原样不动。 - **opencode** —— 临时 `opencode.json`(由 `OPENCODE_CONFIG` 指向,客户端退出时删除),明文 `baseURL` 重写为 `/bili/` 形式,**并追加了薄 `/acp` 插件**。OpenCode 1.x 下 `opencode-acp` 条目会从副本中移除(主机不得以激活状态加载它),改由薄插件把同一个包作为库导入、仅对 legacy 会话生效;首个被移除的 spec 经 `BILI_OPENCODE_ACP_SPEC` 传递,保证 bridge 导入的正是主机本会加载的那份拷贝(#920)。 diff --git a/README.md b/README.md index 2bb88add2b..5f328a157c 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,9 @@ Three ways to use it — pick one: - **URL change (persistent):** prefix your client's baseURL with the proxy origin + `/bili/`. +Mechanism details behind these three options (plugin lifecycle, runtime-info +protocol, injection priority) live in [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md). + ### Option 1 — Native plugin (`bili plugin install pi` / `omp` / `opencode` / `dsh` / `kimi`) The proxy lives inside the client: install once, then start the client @@ -241,52 +244,22 @@ mixing *writers* is what the guard forbids. `bili plugin update [client]` is the one command that drives every lane through its own owner and prints the per-lane update path (`bili plugin list` shows the same per-lane channel). -At load the plugin **spawns its own proxy** (or attaches to a healthy -running one — a parent-pid watchdog tears it down when the client exits), +At load the plugin **spawns its own proxy** (attaches to a healthy running +one if present; a parent-pid watchdog tears it down when the client exits), rewrites model traffic to `/bili/`, registers `compress` / `decompress` / `acp_status` as native client tools (plugin -mode), and binds the `/acp` panel to the current session. It also reports -the client's **own model config** to the proxy (runtime-info protocol, -#955) so compression budgets use the real window instead of a registry -guess. Opt-out envs: `BILI_NATIVE_PI=0`, `BILI_NATIVE_OMP=0`, -`BILI_NATIVE_OPENCODE=0`, `BILI_NATIVE_DSH=0`, `BILI_NATIVE_KIMI=0`. - -#### Runtime-info protocol (#955) - -A native plugin lives inside the client process, so it can read the model -config the client itself will use. It pushes that truth to the proxy on two -channels, and the proxy prefers it over the models.dev registry / built-in -table in the context-window chain: - -| Channel | When | Fields | -|---|---|---| -| Per-request headers (gated on `x-bili-plugin`) | every model request | `x-bili-plugin-context-window`, `x-bili-plugin-max-output`, `x-bili-plugin-model` | -| `POST /__bili/plugin/runtime-info` (loopback) | plugin bootstrap + model switch | `{agent, model, contextWindow?, maxOutput?, baseURL?, source}` | - -Resolution order for the window: `anthropic-beta` negotiation > per-request -plugin header > runtime-info table (agent+model must match) > launcher -env > route config > models.dev registry > built-in table. A reported -`maxOutput` only stands in when the request body carries no output budget -of its own. Implementations: `src/agent/pi.ts` (covers pi and omp), -`src/agent/opencode-native.ts` (v1), `src/agent/opencode-v2.ts`, -`src/agent/dsh-native.ts`, `src/kimi/native-mcp.ts` (bootstrap-time report -only — kimi's provider `custom_headers` are static, so per-request headers -would go stale on model switch) — other client integrations should follow -the same protocol. - -The launcher env tier covers pure-proxy clients (no in-process plugin): -`bili ` reads the client's own model config at launch -(`model_context_window` / `model_max_output_tokens` for codex, -`contextWindow` / `maxTokens` for pi / omp, `limit.context` / `limit.output` -for opencode, `maxInputTokens` / `maxOutputTokens` for codebuddy) and hands -it to the proxy via `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` -(#971). A plugin report — when present — always outranks it. - -Before the first model request there is no session yet, so the `/acp` panel -probes `GET /__bili/plugin/status?conversationId=&fallback=latest`, -which answers from the runtime table (`phase: "pre-first-request"`) instead -of 404ing — the reported config is visible immediately, and the real session -takes over once traffic lands. +mode), and reports the client's **own model config** to the proxy so +compression budgets use the real window instead of a registry guess. +Opt-out envs: `BILI_NATIVE_PI=0`, `BILI_NATIVE_OMP=0`, +`BILI_NATIVE_OPENCODE=0`, `BILI_NATIVE_DSH=0`, `BILI_NATIVE_KIMI=0`. Full +mechanics: [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md). + +**Runtime-info protocol (#955).** A native plugin reads the model config +the client itself will use and pushes it to the proxy (per-request headers ++ bootstrap report); the proxy prefers that truth over the models.dev +registry / built-in table when resolving the context window. Protocol +details, resolution order, and implementations: +[TECHNICAL-NOTES.md](TECHNICAL-NOTES.md). Notes: @@ -302,39 +275,12 @@ Notes: mechanics in the "Kimi Code" section below. - `codex` has a companion install too (an MCP shell), but it needs a running proxy — it is not native mode. -- `claude` also has a **native posture** (#964, hybrid): Claude Code has no - in-process extension point, so `bili plugin install claude` writes a - managed block into `~/.claude/settings.json` (env - `ANTHROPIC_BASE_URL=http://127.0.0.1:48787/bili/`, - `DISABLE_AUTO_COMPACT=1`, and a `SessionStart` hook) plus the same - user-scope MCP shell as before, now pinned to that stable port. The hook - (fired before claude's first model request) attaches to a healthy proxy - on the port or spawns one whose pid watchdog tracks claude itself, so the - proxy lives and dies with the session. Port override: - `BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort` > 48787; upstream - override: `BILI_CLAUDE_UPSTREAM` (or the existing `claude.anthropicBaseUrl` - config). Opt out with `BILI_NATIVE_CLAUDE=0` — the hook then brings up a - **passthrough** proxy on the same port (verbatim forward, compression - off) so claude keeps working. The block is pure JSON merge/strip: foreign - keys are never touched, `bili plugin remove claude` restores exactly. - `bili claude` still works on a machine with the native block installed — - it overrides the static URL with its own ephemeral proxy and the hook - stays dormant. - -### Injection priority — no files unless unavoidable (#535) - -bili never owns user data: every launched client runs on its **real home**, so -runtime writes land where the user expects them. When pointing a client at the -proxy, the launcher picks by priority — **env vars first** (proxy/CA envs for -hermes/dsh/codex; the `BILI_PROVIDER_REWRITES` URL manifest for pi/omp, -consumed by their extension's `registerProvider` at load), then **CLI flags or -extension APIs** (codex `-c key=value`, opencode plugin), and **generated files -last** — today only opencode's temp `opencode.json` (deleted on exit) and dsh's -loopback exception: dsh's fetch stack bypasses proxy envs for loopback targets -unconditionally, so local upstreams keep the persistent `~/.dsh-bili` overlay -rewrite until dsh gains a settings-path env or an upstream loopback opt-out. -Overlay dirs created by older versions are left in place and never merged back -into the real home. +- `claude` also has a **native posture** (#964): `bili plugin install + claude` writes a managed settings block (static `/bili/` URL + + `SessionStart` hook) plus an MCP shell pinned to a stable port — the + proxy lives and dies with the session. Opt out with + `BILI_NATIVE_CLAUDE=0` (passthrough). Mechanics: + [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md). ### Option 2 — Launcher (`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi`) diff --git a/README.zh-CN.md b/README.zh-CN.md index 13affb7454..f97f7096c9 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -104,6 +104,8 @@ npm install -g billion-context - **启动器(最省事):** `bili ` 一条命令拉起代理 + 客户端,不碰任何真实配置文件. - **改url(持久化):** 在客户端 baseURL 前面加上代理地址 + `/bili/`。 +三种方式背后的机制细节(插件生命周期、runtime-info 协议、注入优先级)见 [TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。 + ### 方式 1 —— 原生插件(native,`bili plugin install pi` / `omp` / `opencode` / `dsh` / `kimi`) @@ -126,35 +128,18 @@ bili plugin remove # 卸载(dsh 经同一通道移除;配置快照 pi / omp / kimi / claude 没有客户端侧通道 —— 它们的配置条目由 `bili plugin install ` 代写(kimi 的声明式 `kimi.plugin.json` + 注册记录、claude 的受管 settings 块等)。 -插件加载时**自拉起自己的代理**(已有健康实例则直接复用 —— 父进程 pid 看门狗在客户端退出时收掉它),把模型流量改写到 `/bili/<上游URL>`,并把 `compress` / `decompress` / `acp_status` 注册为客户端原生工具(plugin 模式),`/acp` 面板绑定当前会话。插件还会把客户端**自己的模型配置**上报给代理(runtime-info 协议,#955),压缩预算用真实窗口而不是注册表猜测。退出开关:`BILI_NATIVE_PI=0`、`BILI_NATIVE_OMP=0`、`BILI_NATIVE_OPENCODE=0`、`BILI_NATIVE_DSH=0`、`BILI_NATIVE_KIMI=0`。 - -#### Runtime-info 协议(#955) - -原生插件就在客户端进程里,因此能读到客户端自己将要使用的模型配置。它通过两个通道把真相推给代理,代理在上下文窗口解析链里优先采用它而不是 models.dev 注册表/内置表: - -| 通道 | 时机 | 字段 | -|---|---|---| -| 逐请求头(门控在 `x-bili-plugin`) | 每次模型请求 | `x-bili-plugin-context-window`、`x-bili-plugin-max-output`、`x-bili-plugin-model` | -| `POST /__bili/plugin/runtime-info`(回环地址) | 插件自举 + 模型切换 | `{agent, model, contextWindow?, maxOutput?, baseURL?, source}` | +插件加载时**自拉起自己的代理**(已有健康实例则直接复用;父进程 pid 看门狗在客户端退出时收掉它),把模型流量改写到 `/bili/<上游URL>`,注册 `compress` / `decompress` / `acp_status` 为客户端原生工具(plugin 模式),并把客户端**自己的模型配置**上报给代理让压缩预算用真实窗口而不是注册表猜测。退出开关:`BILI_NATIVE_PI=0`、`BILI_NATIVE_OMP=0`、`BILI_NATIVE_OPENCODE=0`、`BILI_NATIVE_DSH=0`、`BILI_NATIVE_KIMI=0`。完整机制:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。 -窗口解析顺序:`anthropic-beta` 协商 > 逐请求 plugin 头 > runtime-info 表(agent+model 必须匹配) > launcher 环境变量 > 路由配置 > models.dev 注册表 > 内置表。上报的 `maxOutput` 仅在请求体自带输出预算缺席时兜底。现有实现:`src/agent/pi.ts`(覆盖 pi 与 omp)、`src/agent/opencode-native.ts`(v1)、`src/agent/opencode-v2.ts`、`src/agent/dsh-native.ts`、`src/kimi/native-mcp.ts`(仅自举时上报 —— kimi 的 provider `custom_headers` 是静态的,逐请求头会在模型切换后过期)—— 其他客户端接入请遵循同一协议。 - -launcher 环境变量这档覆盖纯代理客户端(无进程内插件):`bili ` 启动时读客户端自己的模型配置(codex 的 `model_context_window` / `model_max_output_tokens`,pi / omp 的 `contextWindow` / `maxTokens`,opencode 的 `limit.context` / `limit.output`,codebuddy 的 `maxInputTokens` / `maxOutputTokens`),经 `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` 交给代理(#971)。插件上报 —— 若存在 —— 永远优先于它。 - -首次模型请求之前会话尚不存在,`/acp` 面板会探测 `GET /__bili/plugin/status?conversationId=&fallback=latest`,代理从 runtime-info 表应答(`phase: "pre-first-request"`)而不是返回 404 —— 上报的配置立即可见,流量落地后由真实会话接管。 +**Runtime-info 协议(#955)。** 原生插件读取客户端自己将要使用的模型配置并推给代理(逐请求头 + 自举上报);代理解析上下文窗口时优先采用这份真相,而不是 models.dev 注册表/内置表。协议细节、解析顺序与现有实现:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。 注意: - 原生模式与独立进程内扩展(`billion-context-pi`、`opencode-acp`)**互斥** —— 安装器负责换条目并把原配置快照(`.bili-bak`);迁移细节见上方客户端表(pi 需 `billion-context-pi` 0.1.72+ 才能干净退让)。 - OpenCode:legacy `opencode-acp` 会话、V1/V2 插件形态与全部注意事项已并入 [OpenCode](#opencode) 一节。 - `kimi` 仅在自举时上报 runtime-info(静态 `custom_headers` 无法承载逐请求的窗口/模型头,否则会在模型切换后过期),子代理会话按每次调用的 `conversation_id` 绑定 —— 完整机制见下文「Kimi Code」小节。 -- `claude` 有**原生姿态**(hybrid,#964):Claude Code 没有进程内扩展点,所以 `bili plugin install claude` 往 `~/.claude/settings.json` 写一个受管块(env `ANTHROPIC_BASE_URL=http://127.0.0.1:48787/bili/`、`DISABLE_AUTO_COMPACT=1`、`SessionStart` hook),外加同样指向该稳定端口的用户级 MCP shell。hook 在首个模型请求前触发:附着到端口上健康的代理,或拉起一个 pid 看门狗追踪 claude 本身的代理 —— 代理随会话生灭。端口覆盖:`BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort` > 48787;上游覆盖:`BILI_CLAUDE_UPSTREAM`(或既有 `claude.anthropicBaseUrl`)。`BILI_NATIVE_CLAUDE=0` 退出 —— hook 改为拉起同端口的 **passthrough** 代理(原样转发、关闭压缩)。块是纯 JSON merge/strip:外部键从不触碰,`bili plugin remove claude` 精确还原。装有原生块的机器上 `bili claude` 仍可用 —— 它用自身临时代理覆盖静态 URL,hook 保持休眠。 +- `claude` 有**原生姿态**(#964):`bili plugin install claude` 写入受管 settings 块(静态 `/bili/` URL + `SessionStart` hook)+ 指向稳定端口的 MCP shell —— 代理随会话生灭。`BILI_NATIVE_CLAUDE=0` 退出(passthrough)。机制细节:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。 - `codex` / `omp` 也有配套安装(MCP shell 与轻量扩展),但它们需要一个在跑的代理 —— 不属于原生模式。 -### 注入优先级 —— 能不写文件就不写(#535) - -bili 永不拥有用户数据:每个被启动的客户端都跑在**真实 home** 上,运行期写入落在用户预期的位置。把客户端指向代理时,启动器按优先级选择——**优先 env 变量**(hermes/dsh/codex 的代理/CA env;pi/omp 的 `BILI_PROVIDER_REWRITES` URL 清单,由扩展加载时经 `registerProvider` 消费),其次 **CLI 参数或扩展 API**(codex `-c key=value`、opencode 插件),最后才是**生成文件**——目前仅剩 opencode 的临时 `opencode.json`(退出即删)和 dsh 的回环例外:dsh 的 fetch 栈对回环目标无条件绕过代理 env,所以本地上游保留持久 `~/.dsh-bili` overlay 改写,直到 dsh 提供 settings-path env 或上游支持回环 opt-out。旧版本创建的 overlay 目录原地保留,绝不合并回真实 home。 - ### 方式 2 —— 启动器(`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi`) 启动器把客户端包进一条命令:在独立端口拉起一个代理(总是全新实例,绝不复用端口),再按客户端支持的机制把它指向代理 —— 能吃代理/CA 环境变量的走**证书 MITM**,不吃的走隔离的**`/bili/` 配置重写**。真实配置文件从不被修改;客户端自己的配置只被**读取**,用来发现它实际连接的 HTTPS 上游主机,把这些主机加入 MITM 白名单 —— 代理只 TLS 终结它们,其余流量盲透传。 diff --git a/TECHNICAL-NOTES.md b/TECHNICAL-NOTES.md new file mode 100644 index 0000000000..ac74126b98 --- /dev/null +++ b/TECHNICAL-NOTES.md @@ -0,0 +1,89 @@ +# Technical notes + +Mechanism-level details behind the three usage options in the README. The +README keeps each option concise; the "how it actually works" material lives +here instead of between the options. + +## Native plugin lifecycle (Option 1) + +At load the plugin **spawns its own proxy** (or attaches to a healthy +running one — a parent-pid watchdog tears it down when the client exits), +rewrites model traffic to `/bili/`, registers +`compress` / `decompress` / `acp_status` as native client tools (plugin +mode), and binds the `/acp` panel to the current session. It also reports +the client's **own model config** to the proxy (runtime-info protocol, +#955) so compression budgets use the real window instead of a registry +guess. Opt-out envs: `BILI_NATIVE_PI=0`, `BILI_NATIVE_OMP=0`, +`BILI_NATIVE_OPENCODE=0`, `BILI_NATIVE_DSH=0`, `BILI_NATIVE_KIMI=0`. + +## Runtime-info protocol (#955) + +A native plugin lives inside the client process, so it can read the model +config the client itself will use. It pushes that truth to the proxy on two +channels, and the proxy prefers it over the models.dev registry / built-in +table in the context-window chain: + +| Channel | When | Fields | +|---|---|---| +| Per-request headers (gated on `x-bili-plugin`) | every model request | `x-bili-plugin-context-window`, `x-bili-plugin-max-output`, `x-bili-plugin-model` | +| `POST /__bili/plugin/runtime-info` (loopback) | plugin bootstrap + model switch | `{agent, model, contextWindow?, maxOutput?, baseURL?, source}` | + +Resolution order for the window: `anthropic-beta` negotiation > per-request +plugin header > runtime-info table (agent+model must match) > launcher +env > route config > models.dev registry > built-in table. A reported +`maxOutput` only stands in when the request body carries no output budget +of its own. Implementations: `src/agent/pi.ts` (covers pi and omp), +`src/agent/opencode-native.ts` (v1), `src/agent/opencode-v2.ts`, +`src/agent/dsh-native.ts`, `src/kimi/native-mcp.ts` (bootstrap-time report +only — kimi's provider `custom_headers` are static, so per-request headers +would go stale on model switch) — other client integrations should follow +the same protocol. + +The launcher env tier covers pure-proxy clients (no in-process plugin): +`bili ` reads the client's own model config at launch +(`model_context_window` / `model_max_output_tokens` for codex, +`contextWindow` / `maxTokens` for pi / omp, `limit.context` / `limit.output` +for opencode, `maxInputTokens` / `maxOutputTokens` for codebuddy) and hands +it to the proxy via `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` +(#971). A plugin report — when present — always outranks it. + +Before the first model request there is no session yet, so the `/acp` panel +probes `GET /__bili/plugin/status?conversationId=&fallback=latest`, +which answers from the runtime table (`phase: "pre-first-request"`) instead +of 404ing — the reported config is visible immediately, and the real session +takes over once traffic lands. + +## Claude native posture (#964) + +Claude Code has no in-process extension point, so `bili plugin install +claude` writes a managed block into `~/.claude/settings.json` (env +`ANTHROPIC_BASE_URL=http://127.0.0.1:48787/bili/`, +`DISABLE_AUTO_COMPACT=1`, and a `SessionStart` hook) plus the same +user-scope MCP shell as before, now pinned to that stable port. The hook +(fired before claude's first model request) attaches to a healthy proxy on +the port or spawns one whose pid watchdog tracks claude itself, so the +proxy lives and dies with the session. Port override: +`BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort` > 48787; upstream +override: `BILI_CLAUDE_UPSTREAM` (or the existing `claude.anthropicBaseUrl` +config). Opt out with `BILI_NATIVE_CLAUDE=0` — the hook then brings up a +**passthrough** proxy on the same port (verbatim forward, compression off) +so claude keeps working. The block is pure JSON merge/strip: foreign keys +are never touched, `bili plugin remove claude` restores exactly. `bili +claude` still works on a machine with the native block installed — it +overrides the static URL with its own ephemeral proxy and the hook stays +dormant. + +## Injection priority — no files unless unavoidable (#535) + +bili never owns user data: every launched client runs on its **real home**, so +runtime writes land where the user expects them. When pointing a client at the +proxy, the launcher picks by priority — **env vars first** (proxy/CA envs for +hermes/dsh/codex; the `BILI_PROVIDER_REWRITES` URL manifest for pi/omp, +consumed by their extension's `registerProvider` at load), then **CLI flags or +extension APIs** (codex `-c key=value`, opencode plugin), and **generated files +last** — today only opencode's temp `opencode.json` (deleted on exit) and dsh's +loopback exception: dsh's fetch stack bypasses proxy envs for loopback targets +unconditionally, so local upstreams keep the persistent `~/.dsh-bili` overlay +rewrite until dsh gains a settings-path env or an upstream loopback opt-out. +Overlay dirs created by older versions are left in place and never merged back +into the real home. diff --git a/TECHNICAL-NOTES.zh-CN.md b/TECHNICAL-NOTES.zh-CN.md new file mode 100644 index 0000000000..ec10cbacce --- /dev/null +++ b/TECHNICAL-NOTES.zh-CN.md @@ -0,0 +1,30 @@ +# 技术细节 + +README 三种使用方式背后的机制级说明。README 里每种方式只保留简洁的用法;「它到底怎么工作」的内容都放在这里,而不是夹在三种方式中间。 + +## 原生插件生命周期(方式 1) + +插件加载时**自拉起自己的代理**(已有健康实例则直接复用 —— 父进程 pid 看门狗在客户端退出时收掉它),把模型流量改写到 `/bili/<上游URL>`,把 `compress` / `decompress` / `acp_status` 注册为客户端原生工具(plugin 模式),并把 `/acp` 面板绑定到当前会话。插件还会把客户端**自己的模型配置**上报给代理(runtime-info 协议,#955),压缩预算用真实窗口而不是注册表猜测。退出开关:`BILI_NATIVE_PI=0`、`BILI_NATIVE_OMP=0`、`BILI_NATIVE_OPENCODE=0`、`BILI_NATIVE_DSH=0`、`BILI_NATIVE_KIMI=0`。 + +## Runtime-info 协议(#955) + +原生插件就在客户端进程里,因此能读到客户端自己将要使用的模型配置。它通过两个通道把真相推给代理,代理在上下文窗口解析链里优先采用它而不是 models.dev 注册表/内置表: + +| 通道 | 时机 | 字段 | +|---|---|---| +| 逐请求头(门控在 `x-bili-plugin`) | 每次模型请求 | `x-bili-plugin-context-window`、`x-bili-plugin-max-output`、`x-bili-plugin-model` | +| `POST /__bili/plugin/runtime-info`(回环地址) | 插件自举 + 模型切换 | `{agent, model, contextWindow?, maxOutput?, baseURL?, source}` | + +窗口解析顺序:`anthropic-beta` 协商 > 逐请求 plugin 头 > runtime-info 表(agent+model 必须匹配) > launcher 环境变量 > 路由配置 > models.dev 注册表 > 内置表。上报的 `maxOutput` 仅在请求体自带输出预算缺席时兜底。现有实现:`src/agent/pi.ts`(覆盖 pi 与 omp)、`src/agent/opencode-native.ts`(v1)、`src/agent/opencode-v2.ts`、`src/agent/dsh-native.ts`、`src/kimi/native-mcp.ts`(仅自举时上报 —— kimi 的 provider `custom_headers` 是静态的,逐请求头会在模型切换后过期)—— 其他客户端接入请遵循同一协议。 + +launcher 环境变量这档覆盖纯代理客户端(无进程内插件):`bili ` 启动时读客户端自己的模型配置(codex 的 `model_context_window` / `model_max_output_tokens`,pi / omp 的 `contextWindow` / `maxTokens`,opencode 的 `limit.context` / `limit.output`,codebuddy 的 `maxInputTokens` / `maxOutputTokens`),经 `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` 交给代理(#971)。插件上报 —— 若存在 —— 永远优先于它。 + +首次模型请求之前会话尚不存在,`/acp` 面板会探测 `GET /__bili/plugin/status?conversationId=&fallback=latest`,代理从 runtime-info 表应答(`phase: "pre-first-request"`)而不是返回 404 —— 上报的配置立即可见,流量落地后由真实会话接管。 + +## Claude 原生姿态(#964) + +Claude Code 没有进程内扩展点,所以 `bili plugin install claude` 往 `~/.claude/settings.json` 写一个受管块(env `ANTHROPIC_BASE_URL=http://127.0.0.1:48787/bili/`、`DISABLE_AUTO_COMPACT=1`、`SessionStart` hook),外加同样指向该稳定端口的用户级 MCP shell。hook 在首个模型请求前触发:附着到端口上健康的代理,或拉起一个 pid 看门狗追踪 claude 本身的代理 —— 代理随会话生灭。端口覆盖:`BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort` > 48787;上游覆盖:`BILI_CLAUDE_UPSTREAM`(或既有 `claude.anthropicBaseUrl`)。`BILI_NATIVE_CLAUDE=0` 退出 —— hook 改为拉起同端口的 **passthrough** 代理(原样转发、关闭压缩)。块是纯 JSON merge/strip:外部键从不触碰,`bili plugin remove claude` 精确还原。装有原生块的机器上 `bili claude` 仍可用 —— 它用自身临时代理覆盖静态 URL,hook 保持休眠。 + +## 注入优先级 —— 能不写文件就不写(#535) + +bili 永不拥有用户数据:每个被启动的客户端都跑在**真实 home** 上,运行期写入落在用户预期的位置。把客户端指向代理时,启动器按优先级选择——**优先 env 变量**(hermes/dsh/codex 的代理/CA env;pi/omp 的 `BILI_PROVIDER_REWRITES` URL 清单,由扩展加载时经 `registerProvider` 消费),其次 **CLI 参数或扩展 API**(codex `-c key=value`、opencode 插件),最后才是**生成文件**——目前仅剩 opencode 的临时 `opencode.json`(退出即删)和 dsh 的回环例外:dsh 的 fetch 栈对回环目标无条件绕过代理 env,所以本地上游保留持久 `~/.dsh-bili` overlay 改写,直到 dsh 提供 settings-path env 或上游支持回环 opt-out。旧版本创建的 overlay 目录原地保留,绝不合并回真实 home。 From bbb78ffb6fbad450cdea3b0e47e2f90ff67a81b4 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sat, 19 Sep 2026 21:05:18 +0800 Subject: [PATCH 2/2] docs: move Verify step into Option 3 (URL change) where its precondition belongs (#985) --- README.md | 36 +++++++++++++++++------------------- README.zh-CN.md | 30 +++++++++++++----------------- 2 files changed, 30 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 5f328a157c..35f59c8072 100644 --- a/README.md +++ b/README.md @@ -334,6 +334,23 @@ automatically. For per-client configuration examples (OpenCode, Codex, Pi, login-client MITM, …) see the web UI guide at [http://localhost:8787](http://localhost:8787). +**Verify.** With the proxy running and your config saved, check it answers +and that your first real request shows compression activity in the log: + +```bash +# Health check (proxy up + where it forwards) +curl -s http://localhost:8787/__bili/health +# → {"ok":true,"upstream":"https://api.anthropic.com"} + +# Live session stats (after a real request) +curl -s http://localhost:8787/__bili/stats +``` + +Then send one message from your client and watch the log +(`~/.local/state/billion-context/bili.log`, also printed to stderr). You +should see a `processTurn` line per request, and once the conversation grows, +`[acp-usage] round N input=X cached=Y (cache hit Z%)` + a `compress` event. + ### dsh (deepseek-harness) Two lanes, same plugin (#941): @@ -432,25 +449,6 @@ small node scripts that do the work around the client: NOT pushed out — ACP compression simply fires first, as in launcher mode. Opt-out: `BILI_NATIVE_KIMI=0`. -### Verify - -With the proxy running and your config saved, check it answers and that your -first real request shows compression activity in the log: - -```bash -# Health check (proxy up + where it forwards) -curl -s http://localhost:8787/__bili/health -# → {"ok":true,"upstream":"https://api.anthropic.com"} - -# Live session stats (after a real request) -curl -s http://localhost:8787/__bili/stats -``` - -Then send one message from your client and watch the log -(`~/.local/state/billion-context/bili.log`, also printed to stderr). You -should see a `processTurn` line per request, and once the conversation grows, -`[acp-usage] round N input=X cached=Y (cache hit Z%)` + a `compress` event. - ### Client uses `http.proxy` (CONNECT) but nothing compresses Some clients (VS Code-based IDEs: CodeBuddy, Cursor, Windsurf, …) only offer an HTTP **proxy** setting (`http.proxy`, `codingcopilot.httpProxyURL`, …) — no model base-URL to rewrite. Such clients send `CONNECT :443` through the proxy instead of plain `/bili/…` requests. That path is only decrypted when the model host is on bili's **MITM whitelist**; otherwise bili blind-tunnels the TLS bytes (opaque relay) and can never see — or compress — the model requests (#897). diff --git a/README.zh-CN.md b/README.zh-CN.md index f97f7096c9..6d845e24fe 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -178,6 +178,19 @@ bili 更多客户端配置参考网页引导: [http://localhost:8787](http://localhost:8787) . +**验证。** 代理跑着、配置保存了之后,确认它能应答,并且第一个真实请求在日志里显示压缩活动: + +```bash +# 健康检查(代理是否在跑 + 转发到哪) +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/bili.log`,同时也打到 stderr)。每个请求应该看到一行 `processTurn`,等对话变长后会出现 `[acp-usage] round N input=X cached=Y (cache hit Z%)` + `compress` 事件。 + ### dsh(deepseek-harness) 两条通道,同一个插件(#941): @@ -198,23 +211,6 @@ bili - **看门狗与生命周期:** MCP 子进程每 30 s 探测一次代理。attach 模式下永远等待(绝不碰用户自己的代理);spawn 模式下代理死亡则重新拉起并把路由改写到新 origin。恢复失败时移除受管块,让流量退回直连上游而不是打到死端口。会话结束时 kimi 杀掉 MCP 子进程,父进程 pid 看门狗随之收掉拉起的代理。多个并发 TUI 共享第一个拉起的代理;它消失后其余会话自动重新拉起并改路。 - **已知局限:** 子代理会话各自得到独立的派生代理会话(kimi 不暴露稳定的会话 id;工具调用经每次调用的 `conversation_id` 参数绑定);kimi 的原生自动压缩**没有**被推后 —— ACP 压缩只是先触发,与启动器模式一致。退出开关:`BILI_NATIVE_KIMI=0`。 -### 验证 - -代理跑着、配置保存了之后,确认它能应答,并且第一个真实请求在日志里显示压缩活动: - -```bash -# 健康检查(代理是否在跑 + 转发到哪) -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/bili.log`, -同时也打到 stderr)。每个请求应该看到一行 `processTurn`,等对话变长后 -会出现 `[acp-usage] round N input=X cached=Y (cache hit Z%)` + `compress` 事件。 - ### 客户端用 `http.proxy`(CONNECT)接入但从不压缩 部分客户端(VS Code 系 IDE:CodeBuddy、Cursor、Windsurf……)只提供一个 HTTP **代理**设置(`http.proxy`、`codingcopilot.httpProxyURL` 等),没有可改写的模型 base-URL。这类客户端不走普通的 `/bili/…` 请求,而是把 `CONNECT <模型域名>:443` 发给代理。只有当模型域名在 bili 的 **MITM 白名单**里时这条路径才会被解密;否则 bili 只做盲隧道(不透明转发),永远看不到——也就无法压缩——模型请求(#897)。