Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
1ed16fc
feat: codex native install/remove with self-starting silent proxy ser…
El1mir Oct 14, 2026
8cb3bf0
feat: codex lane wiring (cli/plugin-install/admin/docs/tests) alongsi…
El1mir Oct 14, 2026
3695094
Merge fork (El1mir/billion-context) 7f96abe into master
El1mir Oct 14, 2026
044c316
Merge remote-tracking branch 'origin/master' into pr3176-align
Oct 14, 2026
51f3dfa
fix: restore 22 files the branch had silently pinned to pre-fork state
Oct 14, 2026
1ad7971
refactor: converge PR diff to repo style and purpose
Oct 14, 2026
6db3d97
fix: make the codex service suite pass on POSIX CI lanes
Oct 14, 2026
d5abc52
Merge origin/master (bd2aa6e15) into pr3176-align
Oct 14, 2026
8ad0f34
Merge remote-tracking branch 'origin/master' into pr3176-strict-refactor
Oct 14, 2026
7075031
refactor: re-land codex install feature without formatting churn
Oct 14, 2026
2b18131
fix: proxy service strict-review defects
Oct 14, 2026
8e392de
refactor: remove dead code from codex/proxy-service modules
Oct 14, 2026
58ea967
test: re-target proxy-service tests off removed flag-form planner
Oct 14, 2026
2215592
docs: document bili service command and new codex install semantics
Oct 14, 2026
1af27f1
fix: remove dead exports flagged by the unused-exports gate
Oct 14, 2026
71af23d
docs: document BILI_CODEX_HOOK_ORIGIN in the config reference
Oct 14, 2026
8d73192
test: make codex install-faces test hermetic without a bundle
Oct 14, 2026
4e03643
Merge remote-tracking branch 'origin/master' into pr3176-strict-refactor
Oct 16, 2026
0160cf2
merge: sync master into codex one-click install branch (#3176)
Oct 24, 2026
382e666
fix(ci): register BILI_CODEX_HOOK_ORIGIN in LIFECYCLE.md ledger
Oct 24, 2026
932f6e2
fix(ci): drop leading export from ClientBuildCheck (INTERNAL_ONLY)
Oct 24, 2026
c297b3c
Merge remote-tracking branch 'upstream/master' into sync/2026-11-09-m…
El1mir Nov 9, 2026
7f4ca48
feat: warn when dsh's iot-thinking plugin is installed
El1mir Nov 9, 2026
223bd27
fix(ci): register issue5955 takeover test in LIVE_FILES + tolerate do…
Nov 9, 2026
effbe63
fix: warn about iot-thinking only while it is enabled
El1mir Nov 9, 2026
80eba19
Merge remote-tracking branch 'upstream/master'
El1mir Nov 9, 2026
5ba1474
Merge branch '2026-11-09_iot-incompat-notice'
El1mir Nov 9, 2026
bab610e
fix(web): show built-in notice banners (missing .show class)
El1mir Nov 9, 2026
c2172ab
fix(web-i18n): move iot-thinking probe helpers out of src/notices.ts
Nov 9, 2026
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
106 changes: 82 additions & 24 deletions docs/clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -479,32 +479,90 @@ the client's window through the existing launcher/runtime reporting mechanism
or set the existing `compress.modelContextLimit`; the proxy's local cache is not
evidence of another machine's configuration. Output headroom still applies.

Codex is the one client a plugin install cannot make self-sufficient. The seam
matrix explains why: claude has a `SessionStart` hook + managed settings block,
zcode has a provider store whose `baseURL` can be rewritten — codex has neither.
Its model traffic routes via environment variables only (`HTTPS_PROXY` /
`SSL_CERT_FILE` — this is how `bili codex` works); the default
ChatGPT-login provider has no config-file routing seam, and a managed
`model_providers` block would force `env_key` API-key auth and **drop the
subscription login**. An MCP server cannot inject env into its parent process,
so the plugin can never route codex's own traffic. Three postures:
Codex now has four distinct integration faces. `bili plugin install codex` writes
the `[mcp_servers.bili]` block for ACP tools, adds a bili-owned Codex model route
through `<loopback>/bili/<upstream>`, installs a `[[hooks.SessionStart]]` entry
running `dist/codex/bootstrap-hook.js`, and writes the ACP skill to
`~/.codex/skills/bili/SKILL.md`. For ordinary Codex configuration the route is
the top-level `openai_base_url`. When the current
Codex config is positively detected as CC Switch Direct, bili instead routes
the active `[model_providers.<name>].base_url`, which Codex actually uses. It
preserves the native Codex account and provider selection and never writes the
CC Switch database. The route's target, previous value and exact written value
are recorded in a bili sidecar; removal restores only the value that still
exactly matches bili's record, and leaves later user edits intact. A foreign
route or a provider field changed by CC Switch is reported as a conflict and
left untouched. CC Switch may rewrite the field during provider/mode changes;
bili does not run a watcher to compete with those writes.

| Posture | What you get |
|---|---|
| `bili codex` (launcher) | Full zero-config: a self-managed lane proxy (#1660 zone, sticky port) + cert-MITM env injected into codex — tools *and* compression |
| `bili plugin install codex` + a running bili + self-exported `HTTPS_PROXY` | Tools + compression for power users who manage their own env |
| `bili plugin install codex` alone | The four tools appear in codex but no conversation is proxied, so there is nothing for them to act on; `tools/list` fails with -32003 (`bili proxy unreachable … — start bili or set BILI_MCP_PROXY`) when nothing is reachable |

**Concurrent sessions (#3203).** Several `bili codex` launches may run at once in the same project directory with the same `CODEX_HOME`: each launch takes its own per-session overlay slot (`<CODEX_HOME>-bili-s<N>`, pool of 16) and its own lane proxy, so routing, MCP conversation binding, and compression state never cross between sessions. With the shared-state default (codex ≥ 0.147.0) both sessions' history lands in the ONE live state db in the real home and survives any exit order — see `BILI_CODEX_STATE_MODE` in configuration.md. Older binaries, or `BILI_CODEX_STATE_MODE=legacy`, keep one exclusive overlay per home: the second concurrent launch is refused with `BILI_OVERLAY_BUSY`.

The install writes a single `[mcp_servers.bili]` block into `~/.codex/config.toml`
(command = node, args = dist/mcp.js). #1660 removed the install-time origin bake
(#403: a baked URL went stale after drift/reboot and left the tools pointing at
a dead port); the shell resolves the proxy at session start — env
`BILI_MCP_PROXY` > the live-instance record (any lane's proxy, or a
`bili start` daemon) > the 8787 user-zone default — so a drifted or rebooted
proxy never strands a dead URL, and the shell simply attaches to whatever is
alive. Session binding is headless: the launcher passes
| --- | --- |
| `bili codex` (launcher) | Managed lane proxy and cert-MITM; tools + compression |
| `bili plugin install codex` | Native Codex model route + ACP tools + SessionStart hook + ACP skill |

**Concurrent sessions (#3203).** Several `bili codex` launches may run at once in the same project directory with the same `CODEX_HOME`: each launch takes its own per-session overlay slot (`<CODEX_HOME>-bili-s<N>`, pool of 16) and its own lane proxy, so routing, MCP conversation binding, and compression state never cross between sessions. With the shared-state default (codex ≥ 0.147.0) both sessions' history lands in the ONE live state db in the real home and survives any exit order — see `BILI_CODEX_STATE_MODE` in CONFIGURATION.md. Older binaries, or `BILI_CODEX_STATE_MODE=legacy`, keep one exclusive overlay per home: the second concurrent launch is refused with `BILI_OVERLAY_BUSY`.


**Each face proves only itself.** The MCP block proves TOOLS, never that model
traffic reaches bili. The hook is attach-only (it never spawns a proxy, and
fails open) and reports this session's runtime to an already-running proxy. The
skill only tells the model which ACP tools exist. Only the route face — plus an
observed real request — says anything about compression. `bili plugin status`
and `bili doctor` report all four separately, so a lane missing one of them can
never read as a complete install.

**Ownership of the hook and skill faces.** `[[hooks.SessionStart]]` is an ARRAY
of tables, so a foreign entry (lean-ctx and friends live there) is a sibling,
not a competitor: bili APPENDS its own entry, keeps every existing one, and
refreshes/removes only the entry whose command names its own script. The same
rule covers the skill: a same-named `SKILL.md` bili does not own is left alone.

**The shape of bili's entry is load-bearing in two separate ways**, and each
failure mode is different:

- Codex deserializes `hooks` as a SEQUENCE, so the `[hooks.SessionStart]` +
`hooks = [{…}]` map form makes the whole config unloadable — and an unloadable
config takes the host down (observed on Codex Desktop, surfacing only an
unrelated-looking `AbsolutePathBuf deserialized without a base path in
model_catalog json`). This one is LOUD.
- Each entry is a `MatcherGroup` — `{ matcher?, hooks = [ { type = "command",
command, timeout } ] }`. Handler fields written DIRECTLY on the entry are
unknown keys, so Codex drops them **silently**: the config loads, `codex mcp
list` succeeds, and the hook simply never registers. This one is SILENT, and a
load probe can never detect it — only Codex's own `hooks/list` app-server RPC
can.

The installer refuses to write any shape known to fail either way, and upgrades
an older flat entry it finds in place. `[features] hooks = true` is Codex's
master switch for hook execution — when it is off, bili writes its entry and
says so rather than editing a switch value the user set. Uninstall deletes only
bili's own entry and file, and keeps the skill directory when the user has other
files in it.

`bili service install` registers a persistent per-user proxy service — a Task
Scheduler logon task on Windows, a systemd user unit on Linux; other platforms
report that the service is unsupported and the manual postures still work.
`bili service status|restart|enable|disable|remove` manage it; failed
registration is reported explicitly.
When the proxy is down, Codex's configured URL remains loopback and requests
fail at the local endpoint; there is no direct-upstream fallback. `bili doctor`
reports `proxy-ready`, `configured`, `verified`, `bypassed`, or `unknown`.
`verified` requires an observed Codex model request, while a healthy proxy or a
written config alone cannot claim verification.

CC Switch Direct is supported only at the current Codex config route layer:
when Direct is positively detected, bili can wrap the active provider's
`base_url` with reversible ownership. This is not integration with CC Switch's
provider database or synchronization mechanism. Routing and Aggregation remain
detection-only; discovery does not prove API-level compatibility. No CC Switch
files are modified and bili does not install a competing watcher. ChatGPT subscription/Desktop integration stays
`待完成/可实现`: the implementation does not read, copy, persist, or inject
`auth.json`, cookies, or session tokens; Desktop MCP is separate from model
routing, and official login channels remain intact.

The MCP shell still resolves its proxy at session start — env `BILI_MCP_PROXY`
> the live-instance record (any lane's proxy, or a `bili start` daemon) > the
8787 user-zone default. Session binding is headless: the launcher passes
`BILI_CONVERSATION_ID` at spawn time, and the plugin shell binds the next NEW
session otherwise; per-call `conversation_id` overrides work as everywhere
(#760). Codex ≥0.160 additionally stamps the real thread id on every
Expand Down
29 changes: 21 additions & 8 deletions docs/clients.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,18 +117,31 @@ fork 继承同一面;Antigravity 自带用户插件系统 —— `plugins/<name>

**窗口对齐。** 客户端 plugin/runtime 上报及启动器传递的窗口优先于发布时的 Codex 模型表。没有上报时,本机代理只读其 `CODEX_HOME`(默认 `~/.codex`)下的 `models_cache.json` 和基础 `config.toml`,将 `model_context_window` 限制在匹配模型的 `max_context_window` 内,再应用 `effective_context_window_percent`(Codex 默认 95);后续请求会跟随缓存更新。元数据缺失、不可读或无效时,保留内置表及未知模型 272K 的既有回退。远程代理或其他客户端 profile 应通过现有启动器/runtime 机制传递实际窗口,或设置既有的 `compress.modelContextLimit`;代理本机缓存不能证明另一台机器的配置。输出预留仍正常生效。

Codex 是唯一一个插件安装无法自给自足的客户端。接缝矩阵可以解释:claude 有 SessionStart hook + 受管 settings 块,zcode 有可改写 `baseURL` 的 provider store —— codex 两者都没有。它的模型流量只能经环境变量路由(`HTTPS_PROXY` / `SSL_CERT_FILE` —— `bili codex` 正是这么做的);默认 ChatGPT-登录 provider 没有可改写的配置缝,managed `model_providers` 块会强制 `env_key` API-key 认证、**废掉订阅登录**;而 MCP 子进程无法向父进程注入 env,所以插件永远路由不了 codex 本体流量。三种姿势:
Codex 现在有四个彼此独立的集成面。`bili plugin install codex` 会写入 `[mcp_servers.bili]` 块以提供 ACP 工具,默认添加由 bili 所有的模型路由(经 `<loopback>/bili/<upstream>` 转发原生 Codex CLI 请求),写入一个 `[[hooks.SessionStart]]` 条目运行 `dist/codex/bootstrap-hook.js`,并把 ACP 技能写到 `~/.codex/skills/bili/SKILL.md`。普通 Codex 配置使用顶层 `openai_base_url`;若明确检测到 CC Switch Direct,则改写当前生效的 `[model_providers.<name>].base_url`,保留原生账号与 provider 选择,且不写 CC Switch 数据库。路由目标、原值和 bili 写入的精确值记录在 sidecar;卸载时只还原仍与记录完全一致的字段,后续用户编辑会保留。外部路由冲突或 CC Switch 已重写该字段时会报告冲突并保留现值。CC Switch 切换 provider/模式或同步配置时可能重写路由;bili 不运行 watcher 与之抢写。

| 姿势 | 你能得到什么 |
|---|---|
| `bili codex`(启动器) | 全功能零配置:自管 lane 代理(#1660 端口区,粘性口)+ 注入 codex 的证书 MITM env —— 工具与压缩兼得 |
| `bili plugin install codex` + 在跑的 bili + 自行导出 `HTTPS_PROXY` | 自己管 env 的 power user:工具 + 压缩 |
| 只装 `bili plugin install codex` | codex 里出现四个工具但没有对话被代理、无话可操作;全不可达时 `tools/list` 报 -32003(`bili proxy unreachable … — start bili or set BILI_MCP_PROXY`) |
| 方式 | 能力 |
| --- | --- |
| `bili codex`(启动器) | 受管 lane 代理与证书 MITM;工具 + 压缩 |
| `bili plugin install codex` | 原生 Codex 模型路由 + ACP 工具 + SessionStart hook + ACP 技能 |

**并发会话(#3203)。** 同一项目目录、同一 `CODEX_HOME` 下可以同时跑多个 `bili codex`:每次启动各取一个独立的每会话 overlay 槽位(`<CODEX_HOME>-bili-s<N>`,池上限 16)和各自的 lane 代理,路由、MCP 会话绑定、压缩状态互不串线。共享状态默认(codex ≥ 0.147.0)下,两个会话的历史都落在真实 home 的同一个活库上,退出顺序不影响保留 —— 见 CONFIGURATION.md 的 `BILI_CODEX_STATE_MODE`。旧版二进制或 `BILI_CODEX_STATE_MODE=legacy` 保持每 home 一个独占 overlay:第二个并发启动会被 `BILI_OVERLAY_BUSY` 拒绝。

**四个面各证各的。** MCP 块只证明工具可用,绝不证明模型流量经过 bili;hook 只做 attach(从不 spawn 代理,失败即放行)并把本会话 runtime 上报给已在运行的代理;技能只是告诉模型有哪些 ACP 工具及其用法;只有路由面(外加观测到的真实请求)才与压缩有关。`bili plugin status` 与 `bili doctor` 分别报告这四项,缺哪一项都不会被读成完整安装。

**Hook 与技能的所有权。** `[[hooks.SessionStart]]` 是**数组表**,所以别人写的条目(lean-ctx 之类就住在这里)是**兄弟条目**而不是竞争者:bili **追加**自己的一条、保留全部已有条目,只刷新/删除命令指向自己脚本的那一条。技能同理:同名但非 bili 所有的 `SKILL.md` 完全不碰。

**条目形状有两处硬要求,两种失败模式完全不同:**

- Codex 把 `hooks` 反序列化为**序列**,写成 `[hooks.SessionStart]` + `hooks = [{…}]` 的 map 形式会让整份配置无法加载,进而拖垮宿主(实测 Codex 桌面端只报一个看似无关的 `AbsolutePathBuf deserialized without a base path in model_catalog json`)。这一种是**响的**。
- 每个条目是 `MatcherGroup`——`{ matcher?, hooks = [ { type = "command", command, timeout } ] }`。把 `type`/`command`/`timeout` 直接写在条目上,这些键在 `MatcherGroup` 上是未知字段,会被 Codex **静默丢弃**:配置照常加载、`codex mcp list` 照常成功,hook 却根本不会注册。这一种是**哑的**,任何"能不能加载"的探测都发现不了——只有 Codex 自己的 `hooks/list` app-server RPC 能看见。

安装器拒绝写入任何一种已知会失败的形状,并会把发现的旧扁平条目**就地升级**。`[features] hooks = true` 是 Codex 的 hook 总开关:没有开启时 bili 会写入 hook 条目并明确提示需要打开,不会替你改写既有的开关值。卸载时 bili 只删自己的条目/文件;技能目录里另有用户文件时目录保留。

**并发会话(#3203)。** 同一项目目录、同一 `CODEX_HOME` 下可以同时跑多个 `bili codex`:每次启动各取一个独立的每会话 overlay 槽位(`<CODEX_HOME>-bili-s<N>`,池上限 16)和各自的 lane 代理,路由、MCP 会话绑定、压缩状态互不串线。共享状态默认(codex ≥ 0.147.0)下,两个会话的历史都落在真实 home 的同一个活库上,退出顺序不影响保留 —— 见 configuration.md 的 `BILI_CODEX_STATE_MODE`。旧版二进制或 `BILI_CODEX_STATE_MODE=legacy` 保持每 home 一个独占 overlay:第二个并发启动会被 `BILI_OVERLAY_BUSY` 拒绝。
`bili service install` 会注册当前用户级的常驻代理服务——Windows 上是 Task Scheduler 登录任务,Linux 上是 systemd 用户单元;其他平台会明确报告服务不受支持,手动方式仍然可用。可用 `bili service status|restart|enable|disable|remove` 管理;注册失败会明确报告。代理关闭时,Codex 配置的 URL 仍是 loopback,请求会在本地端点失败,不会静默回退到上游直连。`bili doctor` 会报告 `proxy-ready`、`configured`、`verified`、`bypassed` 或 `unknown`;只有观测到真实 Codex 模型请求才会标记 `verified`,健康代理或已写配置本身都不能证明已验证。

CC Switch Direct 仅在当前 Codex provider 的 `config.toml` 路由层受支持:这是可撤销的配置写入,不代表 bili 与 CC Switch 的 provider 数据库或同步机制已集成。Routing/Aggregation 仍只检测并报告,不自动改写;发现模式不代表 API 级兼容。bili 不修改 CC Switch 数据库,也不会安装 watcher。ChatGPT 订阅/Desktop 集成仍标为 `待完成/可实现`:实现不会读取、复制、持久化或注入 `auth.json`、cookies 或 session token;Desktop MCP 与模型路由分开,官方登录渠道保持不变。

安装写入 `~/.codex/config.toml` 单个 `[mcp_servers.bili]` 块(command = node,args = dist/mcp.js)。#1660 去掉了安装时烘焙 origin(#403:烘焙的 URL 在漂移/重启后变成死端口,工具永远指向它);shell 在会话启动时解析代理 —— env `BILI_MCP_PROXY` > 活实例登记(任一 lane 的代理,或 `bili start` 守护)> 8787 用户区默认 —— 漂移或重启后绝不残留死 URL,shell 直接附着到活着的那个。会话绑定是 headless 的:启动器在 spawn 时传 `BILI_CONVERSATION_ID`,插件 shell 否则绑定下一个新会话;逐调用的 `conversation_id` 覆盖与其他客户端一致(#760)。Codex ≥0.160 还在每次 `tools/call` 的 `_meta.threadId` 里盖上真实 thread id;shell 按调用消费(严格校验、绝不写回 spawn 时的全局绑定),优先级高于过期的 `BILI_CONVERSATION_ID` 残留与模型抄写的 `conversation_id`(#2024)。
MCP shell 仍在会话启动时解析代理 —— env `BILI_MCP_PROXY` > 活实例登记(任一 lane 的代理,或 `bili start` 守护)> 8787 用户区默认。会话绑定是 headless 的:启动器在 spawn 时传 `BILI_CONVERSATION_ID`,插件 shell 否则绑定下一个新会话;逐调用的 `conversation_id` 覆盖与其他客户端一致(#760)。Codex ≥0.160 还在每次 `tools/call` 的 `_meta.threadId` 里盖上真实 thread id;shell 按调用消费(严格校验、绝不写回 spawn 时的全局绑定),优先级高于过期的 `BILI_CONVERSATION_ID` 残留与模型抄写的 `conversation_id`(#2024)。

**Responses 原生链式(一个坑)。** bili 靠重放完整 `input` 来压缩,因此无法跟随 OpenAI 原生的 `previous_response_id` 链式续传:只带增量的续传请求会在上游丢失之前的轮次,却仍返回 200。对 codex 而言今天这不是问题 —— 观察到的构建都发 `store:false` 且从不设置 `previous_response_id`(是观察不是证明;E2E 未覆盖该形态)。若你把走原生链式的 Responses 客户端指向 bili,要么重发完整 input/output 历史,要么设 `ACP_KEEP_RESPONSE_ID=1`;bili 剥掉非空 `previous_response_id` 时现在会记一条 `warn`(#1954)。完整链式支持跟踪在 #1973。见[官方迁移指南](https://developers.openai.com/api/docs/guides/migrate-to-responses)。

Expand Down
Loading
Loading