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
10 changes: 10 additions & 0 deletions CLIENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,16 @@ option 1); this section covers what the one-line table can't — **which model
transports the native intercept actually covers**. Pi is the only host that
brings WebSocket model traffic into the loop.

**Sub-agent config (#2230).** The built-in `acp_delegate` surface (three
dele gate tools, roles, fleet inspector — wired by `bili pi` through the
embedded extension) is configured in bili's own config file, the `pi.subagents`
section of `~/.config/billion-context/billion-context.json` (boolean shorthand
`"pi": {"subagents": false}` disables it). The four `~/.pi/acp.json` keys
(`delegate` / `delegatePrompt` / `displayUsage` / `debug`) are a deprecated
fallback — read only while the section is absent, ignored once it exists.
Full field table and the `PI_ACP_DELEGATE_*` env overrides:
CONFIGURATION.md → [`pi`](CONFIGURATION.md#pi).

**How routing works.** The pi extension bootstraps (or attaches to) its own
proxy and patches `globalThis.fetch` in-process: every model-API HTTP request
is rewritten to `<proxy>/bili/<upstream-url>`, and the extension stamps the
Expand Down
2 changes: 2 additions & 0 deletions CLIENTS.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,8 @@ Windows 上默认 npm 安装把 `codex.cmd` shim 放上 PATH,它的 `%*` 转发

Pi 有完整原生模式(`bili plugin install pi`,README 快速上手方案 1);这一节只讲一行表格装不下的内容——**原生拦截实际覆盖哪些模型传输**。pi 是唯一把 WebSocket 模型流量带进环路的宿主。

**子代理配置(#2230)。** 内置 `acp_delegate` 面(三个 delegate 工具、角色、fleet 检查器——由 `bili pi` 经内嵌扩展接线)配置在 bili 自己的配置文件:`~/.config/billion-context/billion-context.json` 的 `pi.subagents` 段(布尔简写 `"pi": {"subagents": false}` 可整体关闭)。`~/.pi/acp.json` 的四键(`delegate` / `delegatePrompt` / `displayUsage` / `debug`)是已废弃的回退源——仅当段缺失时读取,段存在后完全忽略。完整字段表与 `PI_ACP_DELEGATE_*` 环境变量见 CONFIGURATION.zh-CN.md 的 [`pi`](CONFIGURATION.zh-CN.md#pi) 段。

**路由机制。** pi 扩展自行拉起(或附着)代理并进程内 patch `globalThis.fetch`:所有模型 API 的 HTTP 请求被改写到 `<proxy>/bili/<upstream-url>`,扩展经 pi 的 `before_provider_headers` 事件盖 `x-bili-plugin*` 头。所有 HTTP 系 provider(Anthropic、OpenAI chat/completions/responses、Gemini、Mistral、OpenRouter、Azure、自定义中转……)走这条路,得到具名 plugin-mode 会话。

**WebSocket 覆盖(#2073,#2111 实现)。** WebSocket 连接从不经过 `globalThis.fetch`,所以原生扩展在加载时(首个模型连接之前)同时包装 `globalThis.WebSocket`(pi 的 Node 分支每次调用都读全局,Bun 分支首次调用时缓存子类——两个运行时的安装时序都因此安全)。只重写受支持的 Codex Responses 模型连接——其余 WebSocket(devtools、第三方库、已路由 URL)原样通过:
Expand Down
50 changes: 50 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed
| `promptCache.routing` | "auto" \| "enabled" \| "disabled" | auto | ACP_PROMPT_CACHE_ROUTING | Prompt-cache routing posture for cache-aware lane selection. |
| `native.attachExternal` | boolean | false | BILI_NATIVE_ATTACH_EXTERNAL | Let launcher-less native plugins attach to an external (lane'd, unarmed) daemon instead of spawning their own. |
| `claude.nativePort` | number | unset (lane sticky zone port) | BILI_CLAUDE_NATIVE_PORT | Exact port pin for the claude native lane's hook-spawned proxy (strict-port: squatters are refused loudly). |
| `pi.subagents` | { subagents?: object \| boolean } | {} (acp_delegate enabled with package defaults) | PI_ACP_DELEGATE_FORCE_ENABLE, PI_ACP_DELEGATE_MAX_DEPTH, PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES, PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES, PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES, PI_ACP_DELEGATE_MAX_CONCURRENT | Built-in pi-lane sub-agents (acp_delegate) surface, #2230 config-home. The pi.subagents section of billion-context.json owns the delegate config; the four acp.json keys (delegate/delegatePrompt/displayUsage/debug) are a deprecated fallback read only while the section is absent. prompt replaces delegatePrompt; debug is scoped to the sub-agent subsystem. Boolean shorthand subagents: false disables the whole surface. Full field table: the pi section in CONFIGURATION.md. |

**MITM lane**

Expand Down Expand Up @@ -677,6 +678,49 @@ Top-level keys that control how the proxy listens and behaves globally.
- **Status:** ACTIVE
- **Description:** Native-hook attach policy (#1335). Lane'd native hooks attach to a running proxy only when it reports an armed session-lifecycle watchdog; an unarmed lane'd listener (a crashed session's orphan) is refused loudly instead of being silently ridden — a manually started `bili start` daemon (no lane) is user-zone and attachable by default (#1660). Set `attachExternal: true` to attach to *lane'd* unarmed listeners anyway (any code/lane-compatible listener becomes attachable regardless of watchdog state, including pre-#1330 builds). Overridden by `BILI_NATIVE_ATTACH_EXTERNAL` (`1` opens the gate even over a closed file; `0` closes it even over a permissive file). Full mechanics: [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md#proxy-reuse-and-the-attach-gate-1225-1335-1232-1660).

### `pi`

- **Type:** `{ subagents?: PiSubagentsFileConfig | boolean }`
- **Default:** `{}` (acp_delegate surface enabled with package defaults)
- **Status:** ACTIVE (#2230 config-home)
- **Description:** Settings for the built-in **pi-lane sub-agents** (`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`, registered when `bili pi` wires the embedded extension). The `pi.subagents` section is the config home for this surface; the standalone `billion-context-pi-subagents` package reads the same section through its own loader (the file format is the contract, not shared code). Previously these knobs lived in pi's `~/.pi/acp.json` under `delegate` / `delegatePrompt` / `displayUsage` / `debug` — those four keys are a **deprecated fallback**: still read while the section is absent (one-time warning in the bili log and `~/.pi/acp.log`), **ignored once the section exists**, slated for removal in a future release. Renames: `delegatePrompt` → `prompt`; `debug` is scoped to the sub-agent subsystem and does **not** collide with the top-level proxy `debug`.

```jsonc
"pi": {
"subagents": {
"enabled": true, // master switch; false (or "subagents": false) removes tools+prompt+shortcut (new session)
"forceEnable": false, // keep acp_delegate even when a project-scope pi-subagents install is detected (#415)
"displayUsage": "separate", // "separate" (own footer block) | "merged" (folded into tool-result usage)
"maxDepth": 2, // nesting depth cap, propagated to children
"syncTimeoutMinutes": 5, // hard timeout for sync delegates; 0/null disables
"idleTimeoutMinutes": 5, // idle watchdog for async delegates; 0/null disables (warns)
"asyncTimeoutMinutes": 30, // hard limit for async delegates; 0/null disables
"maxConcurrent": 4, // cap on concurrent background delegates (default unlimited; extras queue)
"thinkingLevel": "medium", // off|minimal|low|medium|high|xhigh|max; priority per-call > role > this > pi default
"agents": { // per-role defaults: { model: "provider/id", thinkingLevel: "…" }
"reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" }
},
"notifyIfRead": "skip", // "skip" — no completion nudge if the model already read the result file
"fleetShortcut": "ctrl+alt+d", // "" disables the keyboard shortcut (/acp-fleet still works)
"prompt": null, // replace (string) or remove (null) the ACP_DELEGATE NOTIFICATIONS appendix
"debug": false // debug events in ~/.pi/acp.log, scoped to sub-agents
}
}
```

**Env overrides** (per-process spawn channels, propagate to delegate children; `PI_ACP_DELEGATE_*` > `pi.subagents` > deprecated acp.json > default):

| Env var | Overrides | Notes |
|---|---|---|
| `PI_ACP_DELEGATE_FORCE_ENABLE` | `pi.subagents.forceEnable` | `true`/`false`; unparseable values warn and fall back to the file value. |
| `PI_ACP_DELEGATE_MAX_DEPTH` | `pi.subagents.maxDepth` | Integer ≥ 1; invalid warns and falls back. |
| `PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES` | `pi.subagents.syncTimeoutMinutes` | `0` disables; negative/non-numeric warns and falls back. |
| `PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES` | `pi.subagents.idleTimeoutMinutes` | `0` disables (warns — hung children then need `acp_delegate_cancel`). |
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents.asyncTimeoutMinutes` | `0` disables. |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents.maxConcurrent` | Integer ≥ 1; invalid falls through to the file value, then unlimited. |

Changes take effect on a **new session** (tools register at session start). Full delegate surface docs (roles, execution model, fleet inspector): [billion-context-pi-subagents README](https://github.com/ranxianglei/billion-context-pi-subagents#readme).

### Process-level blocks (#2030)

Since #2030 every pure-behavior knob has a config-file key alongside its env var. Resolution is **env var > config file > built-in default**: a *set* env value owns its knob even when garbage (it parses exactly as pre-#2030 — falling back to the default) and neither leaks into nor gets shadowed by the file tier. These blocks scope the **proxy process** (transport timing, persistence, session lifecycle, self-update, diagnostics). They deliberately do **not** participate in the three-level compress merge ([global → provider → model](#three-level-merge-example)): none of these knobs has per-provider or per-model semantics — their env-var form was process-global, so a top-level key preserves scope exactly. All keys are optional; omitting a block changes nothing. Exhaustive per-knob semantics live in the [env mapping table](#config-file-keys-for-environment-knobs-2030) below.
Expand Down Expand Up @@ -1481,6 +1525,12 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
| `BILI_UPSTREAM_PROXY` | `proxy` | unset (direct) |
| `BILI_UPSTREAM_PROXY_MODE` | `upstreamProxyMode` | auto (unset behaves as direct) |
| `BILI_UPSTREAM_TIMEOUT_MS` | `network.upstreamTimeoutMs` | 720000 |
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_FORCE_ENABLE` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_MAX_DEPTH` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PORT` | `port` | 8787 |
<!-- /bili:gen -->

Expand Down
50 changes: 50 additions & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@
| `promptCache.routing` | "auto" \| "enabled" \| "disabled" | auto | ACP_PROMPT_CACHE_ROUTING | 面向缓存感知路由选择的提示词缓存路由姿态。 |
| `native.attachExternal` | boolean | false | BILI_NATIVE_ATTACH_EXTERNAL | 允许无启动器的原生插件挂到外部(车道化、未武装看门狗)守护进程,而不是自行派生。 |
| `claude.nativePort` | number | unset (lane sticky zone port) | BILI_CLAUDE_NATIVE_PORT | claude 原生车道钩子派生代理的精确端口钉死(严格端口:被占用时响亮拒绝而非跳端口)。 |
| `pi.subagents` | { subagents?: object \| boolean } | {} (acp_delegate enabled with package defaults) | PI_ACP_DELEGATE_FORCE_ENABLE, PI_ACP_DELEGATE_MAX_DEPTH, PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES, PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES, PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES, PI_ACP_DELEGATE_MAX_CONCURRENT | 内置 pi lane 子代理(acp_delegate)面(#2230 配置搬家)。billion-context.json 的 pi.subagents 段拥有 delegate 配置;acp.json 四键(delegate/delegatePrompt/displayUsage/debug)为已废弃回退源,仅段缺失时读取。prompt 取代 delegatePrompt;debug 限定子代理子系统。布尔简写 subagents: false 整体关闭。完整字段表见 CONFIGURATION.md 的 pi 段。 |

**MITM 通道**

Expand Down Expand Up @@ -677,6 +678,49 @@
- **状态:** ACTIVE
- **说明:** native hook attach 策略(#1335)。lane'd native hook 仅在运行中的代理报告了已武装的会话生命周期看门狗时才 attach;未武装的 lane'd listener(崩溃会话的孤儿)被大声拒收而不是被静默搭车 —— 手动启动的 `bili start` 守护(无 lane)属用户区,默认可 attach(#1660)。设 `attachExternal: true` 仍可 attach 到 *lane'd* 未武装 listener(任何代码/lane 兼容的 listener 均可 attach,不论看门狗状态,包括 pre-#1330 构建)。可由 `BILI_NATIVE_ATTACH_EXTERNAL` 覆盖(`1` 即使文件关闭也开门;`0` 即使文件宽松也关门)。完整机制见 [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md#proxy-reuse-and-the-attach-gate-1225-1335-1232-1660)。

### `pi`

- **类型:** `{ subagents?: PiSubagentsFileConfig | boolean }`
- **默认值:** `{}`(acp_delegate 面按包默认值启用)
- **状态:** ACTIVE(#2230 配置搬家)
- **说明:** 内置 **pi lane 子代理**(`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`,`bili pi` 装入内嵌扩展时注册)的配置。`pi.subagents` 段是该功能的配置家;独立包 `billion-context-pi-subagents` 用自己的 loader 读同一段(契约是文件格式,不是共享代码)。此前这些旋钮在 pi 的 `~/.pi/acp.json`(`delegate` / `delegatePrompt` / `displayUsage` / `debug` 四键)——这四键是**已废弃的回退源**:段缺失时仍读取(在 bili 日志与 `~/.pi/acp.log` 各警告一次),**段存在后完全忽略**,未来版本移除。改名:`delegatePrompt` → `prompt`;`debug` 限定子代理子系统,**不**与顶层代理 `debug` 冲突。

```jsonc
"pi": {
"subagents": {
"enabled": true, // 总开关;false(或 "subagents": false)移除工具+提示词+快捷键(新会话生效)
"forceEnable": false, // 检测到项目级 pi-subagents 安装时仍保留 acp_delegate(#415)
"displayUsage": "separate", // "separate"(独立 footer 块)| "merged"(并入工具结果用量)
"maxDepth": 2, // 嵌套深度上限,向子进程传播
"syncTimeoutMinutes": 5, // 同步 delegate 硬超时;0/null 关闭
"idleTimeoutMinutes": 5, // 异步 delegate 空闲看门狗;0/null 关闭(告警)
"asyncTimeoutMinutes": 30, // 异步 delegate 硬时限;0/null 关闭
"maxConcurrent": 4, // 后台并发上限(默认无限;超出排队)
"thinkingLevel": "medium", // off|minimal|low|medium|high|xhigh|max;优先级 每次调用 > 角色 > 此处 > pi 默认
"agents": { // 角色默认:{ model: "provider/id", thinkingLevel: "…" }
"reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" }
},
"notifyIfRead": "skip", // "skip" —— 模型已读结果文件则不再补发完成通知
"fleetShortcut": "ctrl+alt+d", // "" 关闭快捷键(/acp-fleet 仍可用)
"prompt": null, // 替换(字符串)或移除(null)ACP_DELEGATE NOTIFICATIONS 附录
"debug": false // ~/.pi/acp.log 调试事件,仅限子代理子系统
}
}
```

**环境变量覆盖**(进程级 spawn 通道,随子代理子进程传播;`PI_ACP_DELEGATE_*` > `pi.subagents` > 已废弃 acp.json > 默认):

| 环境变量 | 覆盖 | 说明 |
|---|---|---|
| `PI_ACP_DELEGATE_FORCE_ENABLE` | `pi.subagents.forceEnable` | `true`/`false`;非法值告警并回退到文件值。 |
| `PI_ACP_DELEGATE_MAX_DEPTH` | `pi.subagents.maxDepth` | ≥1 整数;非法值告警并回退。 |
| `PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES` | `pi.subagents.syncTimeoutMinutes` | `0` 关闭;负数/非数字告警并回退。 |
| `PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES` | `pi.subagents.idleTimeoutMinutes` | `0` 关闭(告警 —— 挂死子进程需 `acp_delegate_cancel`)。 |
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents.asyncTimeoutMinutes` | `0` 关闭。 |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents.maxConcurrent` | ≥1 整数;非法值回落到文件值,再回落到无限。 |

修改在**新会话**生效(工具在会话启动时注册)。完整 delegate 面文档(角色、执行模型、fleet 检查器)见 [billion-context-pi-subagents README](https://github.com/ranxianglei/billion-context-pi-subagents#readme)。

### 进程级配置块(#2030)

自 #2030 起,每个纯行为开关在环境变量之外都有配置文件键。解析顺序为**环境变量 > 配置文件 > 内置默认值**:已设置的环境变量值即使内容非法也独占其开关(解析方式与 #2030 之前完全一致 —— 回落到默认值),既不泄漏进文件层、也不被文件层遮蔽。这些块的作用域是**代理进程本身**(传输时序、持久化、会话生命周期、自更新、诊断)。它们有意**不参与**压缩配置的三级合并([全局 → provider → 模型](#三层合并示例)):这些开关都不存在按 provider / 按模型的语义 —— 它们的环境变量形态本来就是进程级的,顶层键恰好保持作用域不变。所有键均可选;省略整个块不会改变任何行为。每个开关的完整语义见下文[环境变量对照表](#环境变量的配置键对照-2030)。
Expand Down Expand Up @@ -1486,6 +1530,12 @@
| `BILI_UPSTREAM_PROXY` | `proxy` | unset (direct) |
| `BILI_UPSTREAM_PROXY_MODE` | `upstreamProxyMode` | auto (unset behaves as direct) |
| `BILI_UPSTREAM_TIMEOUT_MS` | `network.upstreamTimeoutMs` | 720000 |
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_FORCE_ENABLE` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_MAX_DEPTH` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES` | `pi.subagents` | {} (acp_delegate enabled with package defaults) |
| `PORT` | `port` | 8787 |
<!-- /bili:gen -->

Expand Down
2 changes: 1 addition & 1 deletion reference/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ precisely so knobs don't bloat the environment. Precedence everywhere:
|----------|------|----------|
| Behavior tunables (timeouts, caps, modes, diagnostics) | config-file key resolved through `src/knobs.ts`; env stays the override tier | `network.*`, `persist.*`, `sessions.*`, `update.*`, `diagnostics.*`, `fakeCompletion.*`, `plugin.*` |
| Secrets / credentials | env only (never written to disk) | `BILI_LAUNCH_TOKEN`, `BILI_ENCRYPTION_KEY` |
| Per-process channels (written by another bili component at spawn) | env only + comment at the read site naming the writer | `BILI_MCP_PROXY`, `BILI_PARENT_PID`, `BILI_STRICT_PORT`, `BILI_OPENCODE_ACP_SPEC`, `BILI_LAUNCHER_MODEL_*` |
| Per-process channels (written by another bili component at spawn) | env only + comment at the read site naming the writer | `BILI_MCP_PROXY`, `BILI_PARENT_PID`, `BILI_STRICT_PORT`, `BILI_OPENCODE_ACP_SPEC`, `BILI_LAUNCHER_MODEL_*`, `PI_ACP_DELEGATE_*` (child-delegate propagation, #2230; file tier = `pi.subagents`) |
| Host-side posture (read inside a third-party host process at bootstrap) | env only + comment at the read site | `BILLION_CONTEXT_PLUGIN*`, `BILI_NATIVE_*`, `BILI_RECLAIM_FETCH_PATCH` |
| Path relocation (test/container isolation) | env only via `src/paths.ts` | `BILI_CONFIG_FILE`, `BILI_SESSIONS_DIR`, `ACP_DUMP_DIR`, `XDG_*` |
| Third-party conventions (not ours to rename) | as-is | `CLAUDE_CODE_SESSION_ID`, `CODEX_HOME`, `https_proxy` |
Expand Down
Loading
Loading