diff --git a/CONFIGURATION.md b/CONFIGURATION.md index dcb30034a9..a5d36e73a6 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -79,6 +79,13 @@ Top-level keys that control how the proxy listens and behaves globally. - **Status:** ACTIVE - **Description:** Network interface the proxy binds to. `127.0.0.1` (default) listens only on localhost — safe for a local sidecar. Use `::` for IPv4 + IPv6 dual-stack. Use `0.0.0.0` (or a LAN IP) to expose the proxy to other machines — typically inside a container or on a trusted LAN: remote agents then point their model `baseURL` at `http://:/bili/…`, and MITM-mode `CONNECT` accepts remote clients for whitelisted model hosts only (blind tunnels stay loopback-only, and `/__bili/` management endpoints remain loopback-only). There is no authentication — ensure the surrounding network is trusted. Overridden by `ACP_HOST` / `--host`. +### `upstream` + +- **Type:** `string` (base URL) +- **Default:** `https://api.anthropic.com` +- **Status:** ACTIVE +- **Description:** Fallback base URL for path-only model requests: a client that POSTs to `/v1/messages` without a host is forwarded to `${upstream}/v1/messages`. Trailing slashes are stripped. Overridden by `ACP_UPSTREAM`. Also reported as `upstream` in `GET /__bili/health`. + ### `sessionHeader` - **Type:** `string` @@ -93,6 +100,13 @@ Top-level keys that control how the proxy listens and behaves globally. - **Status:** ACTIVE - **Description:** Enable per-request logging. Set `false` (or `ACP_LOG=0`) to silence the standard request log. +### `logFile` + +- **Type:** `string` +- **Default:** XDG state path (`~/.local/state/billion-context/bili.log`) +- **Status:** ACTIVE +- **Description:** Location of the proxy's tee log (file + stderr). Set `"off"` to disable file logging entirely (stderr only). Auto-rotates at 10 MB into `bili.log.old`. Overridden by `ACP_LOG_FILE` when set (an empty value resolves back to the default path, not off). + ### `debug` - **Type:** `boolean` @@ -166,6 +180,20 @@ Top-level keys that control how the proxy listens and behaves globally. } ``` +### `upstreamProxy` + +- **Type:** `string` (proxy URL) +- **Default:** *(none)* +- **Status:** ACTIVE +- **Description:** The config-file carrier of the Web UI manual proxy control — the UI writes this key (it survives restarts; `BILI_UPSTREAM_PROXY` is the env tier above it in the ladder). When set without an explicit `upstreamProxyMode`, the effective mode becomes `"manual"` so this value is what gets used. It takes its place in the [`proxy`](#proxy) resolution order between `BILI_UPSTREAM_PROXY` and the top-level `proxy`. An empty string is treated as unset. + +### `upstreamProxyMode` + +- **Type:** `"auto" | "manual" | "direct"` (anything else parses as `"direct"`) +- **Default:** *(unset — resolves to `"manual"` when `upstreamProxy` is set, else `"direct"`)* +- **Status:** ACTIVE +- **Description:** Selection mode for the proxy's own outbound connections (see the [`proxy`](#proxy) resolution order for the full ladder): `"manual"` uses the Web UI manual proxy (`upstreamProxy`), falling back to the top-level `proxy` when it is empty; `"auto"` and `"direct"` use the top-level `proxy`; an EXPLICITLY set `"direct"` additionally opts the auxiliary egress (MITM blind tunnels) out of proxy fallbacks. `BILI_UPSTREAM_PROXY` always wins as an explicit proxy regardless of mode. Overridden by `BILI_UPSTREAM_PROXY_MODE`. + ### `imageBilling` - **Type:** `"auto" | "pixels" | "bytes"` @@ -226,6 +254,139 @@ Top-level keys that control how the proxy listens and behaves globally. - `providers..resign[""]` (level 2) — `{ enabled?, passthrough?, credentialRef? }` under the same scheme key, per-field over the global block. - The host-side intercept (dsh native lane) runs before routing exists and always uses the global block — that's the wire-necessity trigger (signed body must tunnel or be refused), not policy. Scheme lookup itself is case-insensitive (wire tokens arrive as `SDK-HMAC-SHA256 Access=…`, keys are lowercase). +### `modelContextLimit` + +- **Type:** `number` +- **Default:** `200000` +- **Status:** ACTIVE +- **Description:** Process-wide absolute context limit (tokens) — the fallback tier when neither a provider entry nor a model entry declares its own limit. Overridden by `ACP_MODEL_CONTEXT_LIMIT`. Distinct from the `compress.modelContextLimit` merge key under [Compression Tuning](#compression-tuning), which participates in the per-provider/per-model three-level cascade. + +### `providersPath` + +- **Type:** `string` +- **Default:** *(none — providers come from the inline `providers` block in this file)* +- **Status:** ACTIVE +- **Description:** Path to an external `providers.json` (legacy / shared-file form of the inline [`providers`](#providers) table). Overridden by `ACP_PROVIDERS`. + +### `promptCache` + +- **Type:** `{ routing?: "auto" | "enabled" | "disabled" }` +- **Default:** `{ routing: "auto" }` (anything unrecognized parses as `"auto"`) +- **Status:** ACTIVE +- **Description:** Routing for Responses-wire `prompt_cache_key` stamping. An explicit client-supplied `prompt_cache_key` always wins untouched; otherwise bili stamps its own stable conversation-derived key subject to the mode: `"enabled"` = always stamp, `"disabled"` = never stamp, `"auto"` (default) = stamp only when the upstream host is exactly `api.openai.com`. Overridden by `ACP_PROMPT_CACHE_ROUTING`. + +### `autoUpdate` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Periodic npm-registry version check (every `update.checkIntervalMs`, default 3 min; the first check per process ignores throttle). Detects newer builds on the configured `updateTag` channel; whether the running process actually swaps depends on `autoRestartOnUpdate` (self-restart) or the advisory lane (forced install). Disabled by `ACP_AUTO_UPDATE=0`. Independent of `advisoryCheck`: installs with auto-update off still escape known-broken version ranges via the advisory watcher. + +### `autoRestartOnUpdate` + +- **Type:** `boolean` +- **Default:** `false` +- **Status:** ACTIVE +- **Description:** Opt-in self-restart after an auto-update install (#811): requires zero in-flight requests, passes an install sanity check, and honors a 10-minute cooldown marker; on failure the original listener resumes. Enabled by `ACP_AUTO_RESTART_ON_UPDATE=1` (any non-`0` value). + +### `updateTag` + +- **Type:** `string` (npm dist-tag) +- **Default:** `"latest"` +- **Status:** ACTIVE +- **Description:** Dist-tag channel the auto-updater follows (e.g. `dev`). The rolling `pr` tag tracks the newest PR test build across all PRs; legacy per-PR `pr-N` tags are frozen at that PR's last build and are only followed when explicitly configured. Overridden by `ACP_UPDATE_TAG`. + +### `advisoryCheck` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Critical-defect advisory watcher (#1481): polls the companion package `billion-context-advisories` (CI-published from `advisories/`) and force-installs the pinned `target` version — which may be a ROLLBACK — when the running version falls inside a declared broken range. Runs independently of `autoUpdate`, so installs with auto-update off still get force-updated out of known-broken versions. Fail-open: an unreachable or malformed source only warns and never blocks model traffic. Disabled by `BILI_ADVISORY_CHECK=0`. + +### `advisoryUrl` + +- **Type:** `string` (URL) +- **Default:** *(companion package `billion-context-advisories` on the configured registry — `update.registry` aware)* +- **Status:** ACTIVE +- **Description:** Override for the advisory document URL. Overridden by `BILI_ADVISORY_URL`. + +### `releaseNotesCheck` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Release-notes visibility watcher (#1870): fetches the companion `billion-context-release-notes` document and surfaces "CRITICAL update ready — restart to finish" or "critical update available" on `acp_status` and the `/acp` panel ONLY when the pending span contains a `critical`-tier entry — routine releases never surface (silent by design, #1977). Never installs, never restarts; fail-open. Disabled by `BILI_RELEASE_NOTES_CHECK=0`. + +### `releaseNotesUrl` + +- **Type:** `string` (URL) +- **Default:** *(companion package `billion-context-release-notes` on the configured registry — `update.registry` aware)* +- **Status:** ACTIVE +- **Description:** Override for the release-notes document URL. Overridden by `BILI_RELEASE_NOTES_URL`. + +### `maskHosts` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Host masking in proxy logs (#897/#255): non-public target hosts (private relays, internal domains) are logged as `` instead of verbatim, because logs routinely get pasted into public issues. Credential-header masking is independent and always on. Real target hosts remain available without touching this flag via `GET /__bili/stats` → `blindTunnels` and `GET /__bili/health` (both loopback-only). Disabled by `BILI_LOG_MASK_HOSTS=0`. + +### `subagentSplit` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Claude Code background-subagent session splitting (#970): anthropic-wire requests carrying the `x-claude-code-agent-id` + `x-claude-code-parent-agent-id` pair get their own `\|sub:` session — own lock chain and compression state — instead of queueing behind the main session's lock. Disabled by `BILI_SUBAGENT_SPLIT=0`. + +### `forkAdoption` + +- **Type:** `boolean` +- **Default:** `false` +- **Status:** ACTIVE +- **Description:** Fork block-adoption for ANONYMOUS (prefix-affinity) clients (#629): when such a client forks its history mid-conversation (edit-and-resend / regenerate an earlier turn), the new session inherits the parent's compression blocks whose source content is fully present in the forked request, instead of restarting with zero compression state and re-folding the shared prefix from scratch. Identified resume-forks are NOT governed by this switch — they adopt blocks together with `resumeInheritance` (#1834). The adoptable inventory is logged on every anonymous fork even while disabled, so you can size the win before enabling. Enabled by `BILI_FORK_ADOPTION=1`. + +### `resumeInheritance` + +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Resume inheritance for identified clients (#1486/#1834): when a client sending its own session id (e.g. Claude Code's `x-claude-code-session-id`) resumes a conversation under a NEW session id while replaying the full transcript (`cc --resume` forks a fresh UUID), bili matches the incoming history byte-exactly against that client's tracked chains (≥8 messages, append-only tracking) and, on the resumed session's first request, inherits the parent's ref assignments — stale model citations resolve to their ORIGINAL messages instead of mis-hitting renumbered ones — adopts the fully-present compression blocks, and records the `derivedFrom` lineage. The parent is never modified and fresh messages number above the parent's ref space. A resume must strictly EXTEND the parent's history — an equal-depth byte-exact replay under another id is a duplicate, not a resume. Anonymous sessions keep their own pfa-* world (#309). Disabled by `BILI_RESUME_INHERITANCE=0`. + +### `stableSystemAnchor` + +- **Type:** `boolean` +- **Default:** `false` +- **Status:** ACTIVE +- **Description:** Stable-system anchoring (#1085) — a best-effort wire-layer fallback for prefix caching; the root fix belongs client-side (the client owns its history and decides how to present instruction changes). Plain-proxy mode only: plugin-mode agents (`x-bili-plugin`) own their context management and are never anchored. When enabled, bili remembers each session's first-seen head system/instructions block and keeps re-sending those exact bytes when the client's system prompt later changes: a LOCALIZED change (a file-style edit sharing ≥70% of lines with the version in effect so far) appends a trailing `[System context update] …` user note carrying a compact line diff (`-` removed / `+` added); a NON-LOCALIZED change (structural reshuffle, tool-def churn, timestamped banners, heads over 400 lines) is adopted outright — one deliberate cache miss beats appending noise that would mislead the model; more than 8 accumulated notes likewise replace the anchor with the newest text. The anchor and note log persist with the session metadata and survive compression/compaction. Excluded from anchoring: title-gen micro-requests (OpenAI/Google), Responses compaction-trigger requests, auto-mode classifier requests. Enabled by `BILI_STABLE_SYSTEM_ANCHOR=1`. + +### `chainContentDetection` + +- **Type:** `boolean` +- **Default:** `false` +- **Status:** ACTIVE +- **Description:** Body-content detection of bili→bili chain awareness (#1086/#1421/#1683 follow-up): when an inbound request carries compression artifacts (render tags / historical `acp_status`+`search_context` tool calls) or a digest-bearing `` checkpoint in its BODY but neither the `x-bili-hop` header nor local compression state for its session, bili records an advisory observation and/or applies first-processor-wins passthrough. Default OFF because scanning the request BODY can false-positive on CCR/file-introduced text and model-echoed tags that look like real markers — enable only for the narrow multi-bili relay case where an intermediate box strips `x-bili-hop` and you accept that false-positive risk. The `x-bili-hop` signal itself is unaffected either way. Enabled by `BILI_CHAIN_CONTENT=1`. + +### `chainEgressStamp` + +- **Type:** `boolean` +- **Default:** `false` +- **Status:** ACTIVE +- **Description:** Egress emission of the model-visible `` chain-integrity checkpoint carrier (#1683): when enabled, every request THIS instance actually processes leaves with a digest-bearing stamp so a downstream bili applies first-processor-wins even when the `x-bili-hop` header was stripped in transit (#1421). The carrier lands in a slot the terminal model also reads (a trailing `user` message on OpenAI/Responses, a trailing text part on Anthropic/Google), so models treat it as phantom user input and burn tokens commenting on it — which is why it is off by default. Independent of `chainContentDetection` (inbound body-detection) and of the `x-bili-hop` passthrough, which works either way. Enable only for the narrow multi-bili relay case above. Enabled by `BILI_CHAIN_STAMP=1`. + +### `claude` + +- **Type:** `{ nativePort?: number }` +- **Default:** `{}` (lane rides the self-managed port zone) +- **Status:** ACTIVE +- **Description:** claude native-lane settings. `nativePort` pins an EXACT port for the hook-spawned proxy (#964/#1660): strict-port semantics — a squatter on the port is refused loudly instead of hopping — and the baked managed `ANTHROPIC_BASE_URL` points at it. Without it the lane rides the self-managed zone (`BILI_ZONE_PORT` base + per-lane sticky) and re-pins the managed URL to the live origin each session, so port drift self-heals. Overridden by `BILI_CLAUDE_NATIVE_PORT`. + +### `native` + +- **Type:** `{ attachExternal?: boolean }` +- **Default:** `{}` (attach gate closed for lane'd instances) +- **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). + ### 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. @@ -246,7 +407,8 @@ Since #2030 every pure-behavior knob has a config-file key alongside its env var "streamKeepAliveMs": 15000, // SSE keepalive during upstream silence; 0 disables "preflightHoldMs": 30000, // grace before a long preflight hold starts "preflightDeadEndCooldownMs": 300000, // cooldown after a dead-end preflight verdict - "proxyKeepAliveMaxMs": 55000 // upstream-proxy connection reuse cap; 0 uncapped + "proxyKeepAliveMaxMs": 55000, // upstream-proxy connection reuse cap; 0 uncapped + "postResponseLingerMs": 5000 // post-response close linger budget (#1982) }, // Session persistence @@ -302,10 +464,10 @@ Since #2030 every pure-behavior knob has a config-file key alongside its env var ### `network` -- **Type:** `{ upstreamTimeoutMs?: number; requestWatchdogMs?: number; replayRetryMax?: number; replayRetryBaseMs?: number; maxShrinkPerCompress?: number; keepAliveTimeoutMs?: number; clientErrorBackstopMs?: number; exposureLogIntervalMs?: number; streamKeepAliveMs?: number; preflightHoldMs?: number; preflightDeadEndCooldownMs?: number; proxyKeepAliveMaxMs?: number }` -- **Default:** `{}` (built-ins: `720000`, `2× upstream timeout`, `3`, `1500`, unset, `5000`, `30000`, `3600000`, `15000`, `30000`, `300000`, `55000`) +- **Type:** `{ upstreamTimeoutMs?: number; requestWatchdogMs?: number; replayRetryMax?: number; replayRetryBaseMs?: number; maxShrinkPerCompress?: number; keepAliveTimeoutMs?: number; clientErrorBackstopMs?: number; exposureLogIntervalMs?: number; streamKeepAliveMs?: number; preflightHoldMs?: number; preflightDeadEndCooldownMs?: number; proxyKeepAliveMaxMs?: number; postResponseLingerMs?: number }` +- **Default:** `{}` (built-ins: `720000`, `2× upstream timeout`, `3`, `1500`, unset, `5000`, `30000`, `3600000`, `15000`, `30000`, `300000`, `55000`, `5000`) - **Status:** ACTIVE -- **Description:** Process-wide transport and retry timing (ms). Each key resolves env > file > default via its twin (`BILI_UPSTREAM_TIMEOUT_MS`, `BILI_REQUEST_WATCHDOG_MS`, `BILI_REPLAY_RETRY_MAX`, `BILI_REPLAY_RETRY_BASE_MS`, `BILI_MAX_SHRINK_PER_COMPRESS`, `BILI_KEEP_ALIVE_TIMEOUT_MS`, `BILI_CLIENT_ERROR_BACKSTOP_MS`, `BILI_EXPOSURE_LOG_INTERVAL_MS`, `BILI_STREAM_KEEPALIVE_MS`, `BILI_PREFLIGHT_HOLD_MS`, `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS`, `BILI_PROXY_KEEPALIVE_MAX_MS`). Semantics: `upstreamTimeoutMs` bounds time-to-first-byte and inter-chunk silence end-to-end (#551); `requestWatchdogMs` is the total-request budget (a negative value opts out); `replayRetryMax` counts attempts after transient upstream rejections (#189/#1688); `maxShrinkPerCompress` caps how much one compress may shrink the request before bili steers toward smaller ranges (#189); `streamKeepAliveMs` emits an SSE comment when the response has written zero bytes for that long (#1647); `proxyKeepAliveMaxMs` caps connection reuse through an upstream proxy below its recycle cadence (#1263), `0` uncaps. Full details in the [env table](#config-file-keys-for-environment-knobs-2030). +- **Description:** Process-wide transport and retry timing (ms). Each key resolves env > file > default via its twin (`BILI_UPSTREAM_TIMEOUT_MS`, `BILI_REQUEST_WATCHDOG_MS`, `BILI_REPLAY_RETRY_MAX`, `BILI_REPLAY_RETRY_BASE_MS`, `BILI_MAX_SHRINK_PER_COMPRESS`, `BILI_KEEP_ALIVE_TIMEOUT_MS`, `BILI_CLIENT_ERROR_BACKSTOP_MS`, `BILI_EXPOSURE_LOG_INTERVAL_MS`, `BILI_STREAM_KEEPALIVE_MS`, `BILI_PREFLIGHT_HOLD_MS`, `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS`, `BILI_PROXY_KEEPALIVE_MAX_MS`, `BILI_POST_RESPONSE_LINGER_MS`). Semantics: `upstreamTimeoutMs` bounds time-to-first-byte and inter-chunk silence end-to-end (#551); `requestWatchdogMs` is the total-request budget (a negative value opts out); `replayRetryMax` counts attempts after transient upstream rejections (#189/#1688); `maxShrinkPerCompress` caps how much one compress may shrink the request before bili steers toward smaller ranges (#189); `streamKeepAliveMs` emits an SSE comment when the response has written zero bytes for that long (#1647); `proxyKeepAliveMaxMs` caps connection reuse through an upstream proxy below its recycle cadence (#1263), `0` uncaps; `postResponseLingerMs` is the graceful-close budget after a proxy-initiated post-response close — the socket is held waiting for the peer's FIN/TLS close_notify and destroyed at the deadline (`reason=linger-backstop`) (#1982). Full details in the [env table](#config-file-keys-for-environment-knobs-2030). ### `persist` @@ -951,6 +1113,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_PREFLIGHT_HOLD_MS` | `network.preflightHoldMs` | `30000` | | `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS` | `network.preflightDeadEndCooldownMs` | `300000` | | `BILI_PROXY_KEEPALIVE_MAX_MS` | `network.proxyKeepAliveMaxMs` | `55000` | +| `BILI_POST_RESPONSE_LINGER_MS` | `network.postResponseLingerMs` | `5000` | | `BILI_MITM_HANDSHAKE_TIMEOUT_MS` | `mitm.handshakeTimeoutMs` | `10000` | | `BILI_PERSIST` | `persist.enabled` | `true` | | `BILI_PERSIST_ZSTD` | `persist.zstd` | `false` | @@ -1004,7 +1167,8 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `ACP_HOST` | Override the listen host. | | `ACP_UPSTREAM` | Override the default upstream base URL. | | `ACP_LOG` | Set to `0` to disable request logging. | -| `ACP_AUTO_UPDATE` | Set to `0` to disable auto-update checks. | +| `ACP_AUTO_UPDATE` | Set to `0` to disable auto-update checks. File-config key: `autoUpdate`. | +| `ACP_AUTO_RESTART_ON_UPDATE` | Set to `1` (any non-`0` value) to enable self-restart after an auto-update install (#811): the restart requires zero in-flight requests, passes an install sanity check, honors a 10-minute cooldown marker, and resumes the original listener on failure. File-config key: `autoRestartOnUpdate`. | | `ACP_UPDATE_TAG` | Dist-tag channel the auto-updater follows (default `latest`, e.g. `dev`). File-config key: `updateTag`. The rolling `pr` tag tracks the newest PR test build across all PRs; legacy per-PR `pr-N` tags are frozen at that PR's last build and are only followed when explicitly configured. The rolling `master` tag tracks the newest build merged to master — every non-release merge publishes one (#2049); set it to follow merged-but-unreleased state. | | `BILI_UPDATE_REGISTRY` | Base URL override for the npm registry used by the auto-updater and `bili update` (default `https://registry.npmjs.org`). Intended for hermetic testing against a loopback registry (the verdaccio instance in the `ACP_TEST_REGISTRY` e2e suite); leave unset in production (#1153). | | `BILI_UPDATE_CHECK_INTERVAL_MS` | Auto-update check period in milliseconds (default `180000`, i.e. 3 minutes; values ≤ 0 are ignored and the default applies). Shortened by the hermetic e2e suite so it never waits a full cycle (#1153). | @@ -1066,7 +1230,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_LAUNCHER_LANE` | Internal: the launcher hands its client's lane name (pi / codex / claude / …) to the spawned proxy, which records it in the instance file (#1225). Reuse is identity-based: two instances with *different declared* lanes never attach to each other; an instance without a declared lane is a manually-started user-zone daemon — attachable by default (#1660). Only the launcher sets it — no user configuration. | | `BILI_LAUNCHER_PLUGIN` | Set `0` to disable the launcher's bili MCP server injection for claude/codex (pure wire mode); `1` forces plugin mode. Default: injected — except codex with a local/private upstream (sglang/vllm/ollama cannot parse codex's namespace tool type, so bili auto-falls back to wire tools there). See [Launcher Reference](#launcher-reference). | | `BILI_LAUNCHER_DIRECT` | Set `1` for direct-URL routing in the launcher (drop MITM/CA trust). See [Launcher Reference](#launcher-reference). | - | `BILI_NATIVE_ATTACH_EXTERNAL` | Attach-gate escape hatch (#1335). Lane'd native hooks attach to a running proxy only when it reports an armed session-lifecycle watchdog (`watchdog.armed == true` in `/__bili/health`) — an unarmed *lane'd* proxy (a crashed session's orphan, or an instance whose lifecycle state cannot be verified) is refused loudly instead of being silently ridden. #1660: a **manually started `bili start` daemon** (no lane, no launch token) is user-zone by definition — native hooks attach to it by default, so a deliberate resident daemon “just works” without this env; you then own its lifetime and version. Set `1`/`true` to also attach to *lane'd* unarmed listeners anyway: any code/lane-compatible listener becomes attachable regardless of watchdog state (including pre-#1330 builds that report no `watchdog` field at all). `"native": { "attachExternal": true }` in the config file does the same; the env var wins (`0`/`false` closes the gate even over a permissive file — including for user-zone daemons, forcing fresh lane spawns). Default is closed (for lane'd instances). Full mechanics (reuse rules, listener table, escape hatch): [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md#proxy-reuse-and-the-attach-gate-1225-1335-1232). | + | `BILI_NATIVE_ATTACH_EXTERNAL` | Attach-gate escape hatch (#1335). Lane'd native hooks attach to a running proxy only when it reports an armed session-lifecycle watchdog (`watchdog.armed == true` in `/__bili/health`) — an unarmed *lane'd* proxy (a crashed session's orphan, or an instance whose lifecycle state cannot be verified) is refused loudly instead of being silently ridden. #1660: a **manually started `bili start` daemon** (no lane, no launch token) is user-zone by definition — native hooks attach to it by default, so a deliberate resident daemon “just works” without this env; you then own its lifetime and version. Set `1`/`true` to also attach to *lane'd* unarmed listeners anyway: any code/lane-compatible listener becomes attachable regardless of watchdog state (including pre-#1330 builds that report no `watchdog` field at all). `"native": { "attachExternal": true }` in the config file does the same; the env var wins (`0`/`false` closes the gate even over a permissive file — including for user-zone daemons, forcing fresh lane spawns). Default is closed (for lane'd instances). Full mechanics (reuse rules, listener table, escape hatch): [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md#proxy-reuse-and-the-attach-gate-1225-1335-1232-1660). | | `BILI_ZCODE_ROUTE` | zcode native-plugin routing scope (#1622): `all` (default — every provider entry with a usable http(s) baseURL rides compression, pi/dsh parity), `plans` (pre-#1622 bigmodel coding-plan whitelist), `none` (opt out; the bootstrap leaves the store direct). Compat escape hatch — there is **no** file equivalent; routing is on by default. | | `BILI_ZONE_PORT` | Base of the self-managed port zone (#1660, default `18787`): every *lane-spawned* proxy (claude/zcode native hooks, launcher lanes riding port 0) tries the lane's sticky record first, else this base; port collisions resolve via the child's +1 ladder — except when the holder is a same-lane predecessor running a different build (an upgrade-restart overlap), which the child waits out (up to 5s) and then rebinds the SAME port instead of drifting (#1723) — and the settled port is recorded sticky under `/port-zone.json` so later launches follow drift automatically. Manual `bili start` keeps its own default (`8787`) — the user zone is never touched by lanes. | | `BILI_ZCODE_PORT` | Pin an **exact** port for the zcode native lane's proxy (#1660): the launch becomes strict-port — a squatter is refused loudly instead of hopping — and wrappers written into the shared store survive session restarts even without handoff. Without it the lane rides the self-managed zone (`BILI_ZONE_PORT` base + sticky drift following). | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index e66cf4b20b..0f405399dd 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -79,6 +79,13 @@ - **状态:** ACTIVE - **说明:** 代理绑定的网络接口。`127.0.0.1`(默认)仅监听本机 —— 适合本地 sidecar。使用 `::` 可同时监听 IPv4 + IPv6 双栈。使用 `0.0.0.0`(或局域网 IP)可将代理暴露给其他机器 —— 常见于容器或可信局域网: 远程 agent 把模型 `baseURL` 指向 `http://<本机>:<端口>/bili/…`,MITM 模式的 `CONNECT` 仅对白名单内的模型域名接受远程客户端(盲隧道仍仅限本机,`/__bili/` 管理端点也仍仅限本机)。没有任何鉴权 —— 请确保所在网络可信。可由 `ACP_HOST` / `--host` 覆盖。 +### `upstream` + +- **类型:** `string`(base URL) +- **默认值:** `https://api.anthropic.com` +- **状态:** ACTIVE +- **说明:** 仅路径模型请求的回退 base URL:客户端不带 host POST 到 `/v1/messages` 时转发到 `${upstream}/v1/messages`。尾部斜杠会被剥掉。可由 `ACP_UPSTREAM` 覆盖。同时作为 `GET /__bili/health` 的 `upstream` 字段报告。 + ### `sessionHeader` - **类型:** `string` @@ -93,6 +100,13 @@ - **状态:** ACTIVE - **说明:** 启用逐请求日志。设为 `false`(或 `ACP_LOG=0`)可关闭标准请求日志。 +### `logFile` + +- **类型:** `string` +- **默认值:** XDG state 路径(`~/.local/state/billion-context/bili.log`) +- **状态:** ACTIVE +- **说明:** 代理 tee 日志(文件 + stderr)的位置。设为 `"off"` 完全禁用文件日志(仅 stderr)。10 MB 自动轮转为 `bili.log.old`。设置时由 `ACP_LOG_FILE` 覆盖(空值解析回默认路径,而非 off)。 + ### `debug` - **类型:** `boolean` @@ -166,6 +180,20 @@ } ``` +### `upstreamProxy` + +- **类型:** `string`(代理 URL) +- **默认值:** *(无)* +- **状态:** ACTIVE +- **说明:** Web UI 手动代理控件的配置文件载体 —— UI 写入这个键(重启后保留;`BILI_UPSTREAM_PROXY` 是阶梯上它之上的 env 层)。设置后若未显式指定 `upstreamProxyMode`,生效模式变为 `"manual"`,用的就是这个值。它在 [`proxy`](#proxy) 解析顺序中位于 `BILI_UPSTREAM_PROXY` 与顶层 `proxy` 之间。空字符串按未设置处理。 + +### `upstreamProxyMode` + +- **类型:** `"auto" | "manual" | "direct"`(其他值一律解析为 `"direct"`) +- **默认值:** *(未设置 —— `upstreamProxy` 有值时解析为 `"manual"`,否则 `"direct"`)* +- **状态:** ACTIVE +- **说明:** 代理自身出站连接的选择模式(完整阶梯见 [`proxy`](#proxy) 解析顺序):`"manual"` 用 Web UI 手动代理(`upstreamProxy`),其为空时回落顶层 `proxy`;`"auto"` 与 `"direct"` 用顶层 `proxy`;**显式设置**为 `"direct"` 还会让辅助出网(MITM 盲隧道)退出代理回退。`BILI_UPSTREAM_PROXY` 无论何种模式都作为显式代理优先。可由 `BILI_UPSTREAM_PROXY_MODE` 覆盖。 + ### `imageBilling` - **类型:** `"auto" | "pixels" | "bytes"` @@ -226,6 +254,139 @@ - `providers..resign["<方案>"]`(二级)—— 同样的方案键下 `{ enabled?, passthrough?, credentialRef? }`,逐字段压过全局块。 - 宿主侧拦截(dsh native lane)运行在路由存在之前,始终用全局块 —— 那是传输必要性判定(签名 body 只能隧道或拒收),不是策略。方案键匹配不区分大小写(电线 token 形如 `SDK-HMAC-SHA256 Access=…`,键一律小写)。 +### `modelContextLimit` + +- **类型:** `number` +- **默认值:** `200000` +- **状态:** ACTIVE +- **说明:** 进程级绝对上下文上限(token)—— provider 条目与模型条目都未声明各自上限时的兜底层。可由 `ACP_MODEL_CONTEXT_LIMIT` 覆盖。区别于[压缩调优](#压缩调优)下参与三级合并的 `compress.modelContextLimit` 合并键。 + +### `providersPath` + +- **类型:** `string` +- **默认值:** *(无 —— providers 来自本文件的内联 `providers` 块)* +- **状态:** ACTIVE +- **说明:** 外部 `providers.json` 的路径(内联 [`providers`](#providers) 表的遗留 / 共享文件形态)。可由 `ACP_PROVIDERS` 覆盖。 + +### `promptCache` + +- **类型:** `{ routing?: "auto" | "enabled" | "disabled" }` +- **默认值:** `{ routing: "auto" }`(无法识别的值一律解析为 `"auto"`) +- **状态:** ACTIVE +- **说明:** Responses wire `prompt_cache_key` 盖章的路由策略。客户端显式提供的 `prompt_cache_key` 永远原样优先;否则 bili 按模式决定是否加盖自己从会话身份派生的稳定 key:`"enabled"` = 总是盖,`"disabled"` = 从不盖,`"auto"`(默认)= 仅当上游 host 恰好是 `api.openai.com` 时盖。可由 `ACP_PROMPT_CACHE_ROUTING` 覆盖。 + +### `autoUpdate` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** 周期性 npm registry 版本检查(每 `update.checkIntervalMs`,默认 3 分钟;每进程首次检查忽略节流)。检测所配 `updateTag` 通道上的新版本构建;运行进程是否真正换装取决于 `autoRestartOnUpdate`(自我重启)或公告通道(强制安装)。`ACP_AUTO_UPDATE=0` 关闭。独立于 `advisoryCheck`:关闭自动更新的安装仍会经公告监视器被强制移出已知缺陷版本范围。 + +### `autoRestartOnUpdate` + +- **类型:** `boolean` +- **默认值:** `false` +- **状态:** ACTIVE +- **说明:** 自动更新安装后的 opt-in 自我重启(#811):要求零在途请求、通过安装自检、遵守 10 分钟冷却标记;失败时恢复原监听器。`ACP_AUTO_RESTART_ON_UPDATE=1`(任意非 `0` 值)开启。 + +### `updateTag` + +- **类型:** `string`(npm dist-tag) +- **默认值:** `"latest"` +- **状态:** ACTIVE +- **说明:** 自动更新器跟随的 dist-tag 通道(如 `dev`)。滚动的 `pr` tag 跟踪所有 PR 中最新的测试构建;旧式按 PR 的 `pr-N` tag 冻结在该 PR 最后一次构建,仅在显式配置时跟随。可由 `ACP_UPDATE_TAG` 覆盖。 + +### `advisoryCheck` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** 严重缺陷公告监视器(#1481):轮询伴生包 `billion-context-advisories`(CI 从 `advisories/` 发布),运行版本落入声明的缺陷范围时强制安装钉死的 `target` 版本 —— 可能是**回滚**。独立于 `autoUpdate` 运行,所以关闭自动更新的安装也能被强制移出已知缺陷版本。fail-open:公告源不可达/格式错误只告警,绝不阻断模型流量。`BILI_ADVISORY_CHECK=0` 关闭。 + +### `advisoryUrl` + +- **类型:** `string`(URL) +- **默认值:** *(所配 registry 上的伴生包 `billion-context-advisories` —— 感知 `update.registry`)* +- **状态:** ACTIVE +- **说明:** 公告文档 URL 覆盖。可由 `BILI_ADVISORY_URL` 覆盖。 + +### `releaseNotesCheck` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** release notes 可见性监视器(#1870):拉取伴生文档 `billion-context-release-notes`,且仅当待更新区间含 `critical` 级条目时,才在 `acp_status` 与 `/acp` 面板显示 "CRITICAL update ready — restart to finish" 或 "critical update available" —— 常规版本从不显示(设计上即静默,#1977)。不安装、不重启;fail-open。`BILI_RELEASE_NOTES_CHECK=0` 关闭。 + +### `releaseNotesUrl` + +- **类型:** `string`(URL) +- **默认值:** *(所配 registry 上的伴生包 `billion-context-release-notes` —— 感知 `update.registry`)* +- **状态:** ACTIVE +- **说明:** release notes 文档 URL 覆盖。可由 `BILI_RELEASE_NOTES_URL` 覆盖。 + +### `maskHosts` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** 代理日志中的 host 掩码(#897/#255):非公开的目标 host(私有中继、内网域名)记为 `` 而非原文 —— 因为日志常被原样贴进公开 issue。凭据头掩码独立且始终开启。不动这个开关也能通过 `GET /__bili/stats` → `blindTunnels` 与 `GET /__bili/health`(均仅限 loopback)查看真实目标 host。`BILI_LOG_MASK_HOSTS=0` 关闭。 + +### `subagentSplit` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** Claude Code 后台子代理会话拆分(#970):携带 `x-claude-code-agent-id` + `x-claude-code-parent-agent-id` 对的 anthropic-wire 请求获得自己的 `\|sub:` 会话 —— 独立的锁链与压缩状态 —— 而不是排在主会话锁后面。`BILI_SUBAGENT_SPLIT=0` 关闭。 + +### `forkAdoption` + +- **类型:** `boolean` +- **默认值:** `false` +- **状态:** ACTIVE +- **说明:** 匿名(前缀亲和)客户端的 fork 块继承(#629):此类客户端在会话中途 fork 自己的历史(编辑重发 / 重新生成更早的回合)时,新会话继承父会话中源内容完整存在于 fork 请求里的压缩块,而不是从零压缩状态起步、把共享前缀从头重新折叠。已识别的 resume-fork 不受此开关管辖 —— 它们随 `resumeInheritance` 一起继承块(#1834)。即使开关关闭,每次匿名 fork 也会记录可继承清单,便于启用前评估收益。`BILI_FORK_ADOPTION=1` 开启。 + +### `resumeInheritance` + +- **类型:** `boolean` +- **默认值:** `true` +- **状态:** ACTIVE +- **说明:** 已识别客户端的 resume 继承(#1486/#1834):发送自有 session id 的客户端(如 Claude Code 的 `x-claude-code-session-id`)在全量回放转录(`cc --resume` fork 出新 UUID)的同时以**新的** session id 恢复会话时,bili 把入站历史与该客户端跟踪的链做逐字节匹配(≥8 条消息、追加式跟踪),并在恢复会话的首个请求上继承父会话的 ref 分配 —— 模型的陈旧引用解析到**原始**消息而不是错命中重新编号的消息 —— 同时继承完整存在的压缩块并记录 `derivedFrom` 谱系。父会话永不被修改,新消息编号高于父会话 ref 空间。resume 必须严格**扩展**父会话历史 —— 另一 id 下同深度逐字节回放是重复而非 resume。匿名会话保持自己的 pfa-* 世界(#309)。`BILI_RESUME_INHERITANCE=0` 关闭。 + +### `stableSystemAnchor` + +- **类型:** `boolean` +- **默认值:** `false` +- **状态:** ACTIVE +- **说明:** 稳定 system 锚定(#1085)—— 面向 prefix cache 的最佳努力 wire 层兜底;根因修复属于客户端侧(客户端拥有自己的历史并决定如何呈现指令变更)。仅纯代理模式:插件模式 agent(`x-bili-plugin`)自管上下文,永不被锚定。开启后,bili 记住每个会话首次见到的头部 system/instructions 块,并在客户端 system prompt 之后变化时继续重发那些确切字节:局部变更(与当前生效版本共享 ≥70% 行的文件式编辑)追加一条尾部 `[System context update] …` user note,携带紧凑行级 diff(`-` 删除 / `+` 新增);非局部变更(结构性重排、工具定义抖动、带时间戳横幅、超过 400 行的头部)直接采纳 —— 一次故意的 cache miss 好过追加会误导模型的噪音;累计超过 8 条 note 同样以最新文本替换锚点。锚点与 note 日志随会话元数据持久化,穿越压缩/compaction。排除在锚定之外:标题生成微请求(OpenAI/Google)、Responses compaction-trigger 请求、auto-mode 分类器请求。`BILI_STABLE_SYSTEM_ANCHOR=1` 开启。 + +### `chainContentDetection` + +- **类型:** `boolean` +- **默认值:** `false` +- **状态:** ACTIVE +- **说明:** bili→bili 链感知的 body 内容检测(#1086/#1421/#1683 后续):入站请求 body 里携带压缩产物(渲染标签 / 历史性 `acp_status`+`search_context` 工具调用)或带摘要的 `` checkpoint,但既无 `x-bili-hop` 头也无该会话的本地压缩状态时,bili 记录告警观测和/或应用 first-processor-wins 直通。默认关,因为扫描请求 BODY 会对 CCR/文件引入的文本与形似真实标记的模型回声标签误报 —— 只在中间盒子剥掉 `x-bili-hop` 的多 bili 中继窄场景、且你接受该误报风险时启用。`x-bili-hop` 信号本身两种情况都不受影响。`BILI_CHAIN_CONTENT=1` 开启。 + +### `chainEgressStamp` + +- **类型:** `boolean` +- **默认值:** `false` +- **状态:** ACTIVE +- **说明:** 模型可见 `` 链完整性 checkpoint 载体的出站发射(#1683):开启后,本实例实际处理的每个请求离开时都带上带摘要的戳,使下游 bili 即使在 `x-bili-hop` 头被中途剥离(#1421)时也应用 first-processor-wins。载体落在终端模型也会读的位置(OpenAI/Responses 的尾部 `user` 消息,Anthropic/Google 的尾部 text part),模型会把它当作幽灵用户输入并烧 token 评论它 —— 这就是默认关的原因。独立于 `chainContentDetection`(入站 body 检测)与始终有效的 `x-bili-hop` 直通。仅在上述多 bili 中继窄场景启用。`BILI_CHAIN_STAMP=1` 开启。 + +### `claude` + +- **类型:** `{ nativePort?: number }` +- **默认值:** `{}`(lane 走自管端口区) +- **状态:** ACTIVE +- **说明:** claude native lane 设置。`nativePort` 为 hook 拉起的代理钉死一个**精确**端口(#964/#1660):严格端口语义 —— 端口上有占位者就大声拒收而不是跳口 —— 且烘焙的受管 `ANTHROPIC_BASE_URL` 指向它。不设时 lane 走自管区(`BILI_ZONE_PORT` 基址 + per-lane sticky),并在每个会话把受管 URL 重新钉到活 origin,端口漂移自愈。可由 `BILI_CLAUDE_NATIVE_PORT` 覆盖。 + +### `native` + +- **类型:** `{ attachExternal?: boolean }` +- **默认值:** `{}`(lane'd 实例的 attach 门关闭) +- **状态:** 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)。 + ### 进程级配置块(#2030) 自 #2030 起,每个纯行为开关在环境变量之外都有配置文件键。解析顺序为**环境变量 > 配置文件 > 内置默认值**:已设置的环境变量值即使内容非法也独占其开关(解析方式与 #2030 之前完全一致 —— 回落到默认值),既不泄漏进文件层、也不被文件层遮蔽。这些块的作用域是**代理进程本身**(传输时序、持久化、会话生命周期、自更新、诊断)。它们有意**不参与**压缩配置的三级合并([全局 → provider → 模型](#三层合并示例)):这些开关都不存在按 provider / 按模型的语义 —— 它们的环境变量形态本来就是进程级的,顶层键恰好保持作用域不变。所有键均可选;省略整个块不会改变任何行为。每个开关的完整语义见下文[环境变量对照表](#环境变量的配置键对照-2030)。 @@ -246,7 +407,8 @@ "streamKeepAliveMs": 15000, // 上游静默期的 SSE 保活;0 禁用 "preflightHoldMs": 30000, // 长 preflight 开始 hold 前的宽限 "preflightDeadEndCooldownMs": 300000, // preflight 死路判定后的冷却 - "proxyKeepAliveMaxMs": 55000 // 经上游代理的连接复用上限;0 不限 + "proxyKeepAliveMaxMs": 55000, // 经上游代理的连接复用上限;0 不限 + "postResponseLingerMs": 5000 // 响应后关闭的优雅关闭预算(#1982) }, // 会话持久化 @@ -302,10 +464,10 @@ ### `network` -- **类型:** `{ upstreamTimeoutMs?: number; requestWatchdogMs?: number; replayRetryMax?: number; replayRetryBaseMs?: number; maxShrinkPerCompress?: number; keepAliveTimeoutMs?: number; clientErrorBackstopMs?: number; exposureLogIntervalMs?: number; streamKeepAliveMs?: number; preflightHoldMs?: number; preflightDeadEndCooldownMs?: number; proxyKeepAliveMaxMs?: number }` -- **默认:** `{}`(内置值依次为:`720000`、`2× 上游超时`、`3`、`1500`、未设置、`5000`、`30000`、`3600000`、`15000`、`30000`、`300000`、`55000`) +- **类型:** `{ upstreamTimeoutMs?: number; requestWatchdogMs?: number; replayRetryMax?: number; replayRetryBaseMs?: number; maxShrinkPerCompress?: number; keepAliveTimeoutMs?: number; clientErrorBackstopMs?: number; exposureLogIntervalMs?: number; streamKeepAliveMs?: number; preflightHoldMs?: number; preflightDeadEndCooldownMs?: number; proxyKeepAliveMaxMs?: number; postResponseLingerMs?: number }` +- **默认:** `{}`(内置值依次为:`720000`、`2× 上游超时`、`3`、`1500`、未设置、`5000`、`30000`、`3600000`、`15000`、`30000`、`300000`、`55000`、`5000`) - **状态:** ACTIVE -- **说明:** 进程级传输与重试时序(毫秒)。每个键按 env > file > default 解析,对应环境变量分别为 `BILI_UPSTREAM_TIMEOUT_MS`、`BILI_REQUEST_WATCHDOG_MS`、`BILI_REPLAY_RETRY_MAX`、`BILI_REPLAY_RETRY_BASE_MS`、`BILI_MAX_SHRINK_PER_COMPRESS`、`BILI_KEEP_ALIVE_TIMEOUT_MS`、`BILI_CLIENT_ERROR_BACKSTOP_MS`、`BILI_EXPOSURE_LOG_INTERVAL_MS`、`BILI_STREAM_KEEPALIVE_MS`、`BILI_PREFLIGHT_HOLD_MS`、`BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS`、`BILI_PROXY_KEEPALIVE_MAX_MS`。要点:`upstreamTimeoutMs` 端到端约束首字节时间与 chunk 间静默(#551);`requestWatchdogMs` 是单请求总预算(负值 = 退出该约束);`replayRetryMax` 统计瞬态上游拒绝后的尝试次数(#189/#1688);`maxShrinkPerCompress` 限制单次压缩对请求的最大缩减比例,超限则引导模型选择更小的范围(#189);`streamKeepAliveMs` 在响应零字节写出超过该时长时发一条 SSE 注释行(#1647);`proxyKeepAliveMaxMs` 把经上游代理的连接复用窗口压在上游回收周期之下(#1263),`0` 取消上限。完整细节见[环境变量表](#环境变量的配置键对照-2030)。 +- **说明:** 进程级传输与重试时序(毫秒)。每个键按 env > file > default 解析,对应环境变量分别为 `BILI_UPSTREAM_TIMEOUT_MS`、`BILI_REQUEST_WATCHDOG_MS`、`BILI_REPLAY_RETRY_MAX`、`BILI_REPLAY_RETRY_BASE_MS`、`BILI_MAX_SHRINK_PER_COMPRESS`、`BILI_KEEP_ALIVE_TIMEOUT_MS`、`BILI_CLIENT_ERROR_BACKSTOP_MS`、`BILI_EXPOSURE_LOG_INTERVAL_MS`、`BILI_STREAM_KEEPALIVE_MS`、`BILI_PREFLIGHT_HOLD_MS`、`BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS`、`BILI_PROXY_KEEPALIVE_MAX_MS`、`BILI_POST_RESPONSE_LINGER_MS`。要点:`upstreamTimeoutMs` 端到端约束首字节时间与 chunk 间静默(#551);`requestWatchdogMs` 是单请求总预算(负值 = 退出该约束);`replayRetryMax` 统计瞬态上游拒绝后的尝试次数(#189/#1688);`maxShrinkPerCompress` 限制单次压缩对请求的最大缩减比例,超限则引导模型选择更小的范围(#189);`streamKeepAliveMs` 在响应零字节写出超过该时长时发一条 SSE 注释行(#1647);`proxyKeepAliveMaxMs` 把经上游代理的连接复用窗口压在上游回收周期之下(#1263),`0` 取消上限;`postResponseLingerMs` 是代理主动发起的响应后关闭的优雅关闭预算 —— socket 被挂起等待对端 FIN/TLS close_notify,到点销毁(`reason=linger-backstop`)(#1982)。完整细节见[环境变量表](#环境变量的配置键对照-2030)。 ### `persist` @@ -956,6 +1118,7 @@ | `BILI_PREFLIGHT_HOLD_MS` | `network.preflightHoldMs` | `30000` | | `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS` | `network.preflightDeadEndCooldownMs` | `300000` | | `BILI_PROXY_KEEPALIVE_MAX_MS` | `network.proxyKeepAliveMaxMs` | `55000` | +| `BILI_POST_RESPONSE_LINGER_MS` | `network.postResponseLingerMs` | `5000` | | `BILI_MITM_HANDSHAKE_TIMEOUT_MS` | `mitm.handshakeTimeoutMs` | `10000` | | `BILI_PERSIST` | `persist.enabled` | `true` | | `BILI_PERSIST_ZSTD` | `persist.zstd` | `false` | @@ -1008,7 +1171,8 @@ | `ACP_HOST` | 覆盖监听主机。 | | `ACP_UPSTREAM` | 覆盖默认上游 base URL。 | | `ACP_LOG` | 设为 `0` 关闭请求日志。 | -| `ACP_AUTO_UPDATE` | 设为 `0` 禁用自动更新检查。 | +| `ACP_AUTO_UPDATE` | 设为 `0` 禁用自动更新检查。文件配置键:`autoUpdate`。 | +| `ACP_AUTO_RESTART_ON_UPDATE` | 设为 `1`(任意非 `0` 值)启用自动更新安装后的自我重启(#811):重启要求零在途请求、通过安装自检、遵守 10 分钟冷却标记,失败时恢复原监听器。文件配置键:`autoRestartOnUpdate`。 | | `ACP_UPDATE_TAG` | 自动更新跟随的 dist-tag 通道(默认 `latest`,如 `dev`)。文件配置键:`updateTag`。滚动 `pr` tag 指向所有 PR 中最新的测试构建;旧版按 PR 划分的 `pr-N` tag 已冻结在该 PR 的最后一个构建,仅在显式配置时才会被跟随。滚动 `master` tag 指向最新合入 master 的构建——每次非 release 合并都会发布一个(#2049);设置它即可跟随已合并但未正式发布的状态。 | | `BILI_UPDATE_REGISTRY` | 自动更新与 `bili update` 使用的 npm registry base URL 覆盖(默认 `https://registry.npmjs.org`)。仅供 hermetic 测试指向回环 registry(`ACP_TEST_REGISTRY` e2e 套件自带的 verdaccio 实例);生产环境请勿设置(#1153)。 | | `BILI_UPDATE_CHECK_INTERVAL_MS` | 自动更新检查周期(毫秒,默认 `180000` 即 3 分钟;≤ 0 的值被忽略,回退默认)。hermetic e2e 套件用它缩短周期,避免等待完整间隔(#1153)。 | diff --git a/src/config.ts b/src/config.ts index bca7b81452..935759ac45 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1363,6 +1363,8 @@ type FileConfig = { maxShrinkPerCompress?: number; /** Outbound proxy keep-alive ceiling, 0 for one-shot (was BILI_PROXY_KEEPALIVE_MAX_MS; default 55000). */ proxyKeepAliveMaxMs?: number; + /** Post-response close linger budget (#1982; was env-only BILI_POST_RESPONSE_LINGER_MS; default 5000). */ + postResponseLingerMs?: number; }; /** Session persistence knobs (#2030) — was BILI_PERSIST_* env-only. */ persist?: { @@ -1445,13 +1447,14 @@ const KNOWN_TOP_LEVEL_KEYS = new Set([ "port", "host", "upstream", "providersPath", "providers", "proxy", "modelContextLimit", "sessionHeader", "log", "debug", "dumpSse", "passthrough", "autoUpdate", "autoRestartOnUpdate", "updateTag", - "advisoryCheck", "advisoryUrl", "upstreamProxy", "upstreamProxyMode", + "advisoryCheck", "advisoryUrl", "releaseNotesCheck", "releaseNotesUrl", + "upstreamProxy", "upstreamProxyMode", "logFile", "compress", "promptCache", "mitm", "maskHosts", "subagentSplit", "forkAdoption", "resumeInheritance", "chainContentDetection", "chainEgressStamp", "stableSystemAnchor", - "compat", "imageBilling", "claude", "native", "resign", + "compat", "imageBilling", "imageTokenCap", "claude", "native", "resign", // #2030 subsystem blocks: - "network", "persist", "sessions", "update", "diagnostics", + "network", "persist", "sessions", "plugin", "update", "diagnostics", "fakeCompletion", "codexCompact", "ccrRetrievalTtlMs", "decompressTmpCap", ]); diff --git a/src/knobs.ts b/src/knobs.ts index b6033395d4..55720b244e 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -136,6 +136,18 @@ export function proxyKeepAliveMaxMs(): number { : Number.isFinite(v) && v > 0 ? Math.floor(v) : PROXY_KEEPALIVE_MAX_MS; } +export const POST_RESPONSE_LINGER_MS_DEFAULT = 5_000; + +/** BILI_POST_RESPONSE_LINGER_MS > network.postResponseLingerMs > 5000 (#1982 + * post-response close linger budget; mirrors nginx lingering_time). Env tier + * preserves the historical parseInt parsing byte-exact: set (even empty/ + * garbage) wins and non-numeric or non-positive values fall back to the + * default without consulting the file tier. */ +export function postResponseLingerMs(): number { + const v = tInt("BILI_POST_RESPONSE_LINGER_MS", fileNetwork().postResponseLingerMs); + return Number.isFinite(v) && v > 0 ? v : POST_RESPONSE_LINGER_MS_DEFAULT; +} + export const MITM_HANDSHAKE_TIMEOUT_MS_DEFAULT = 10_000; /** BILI_MITM_HANDSHAKE_TIMEOUT_MS > mitm.handshakeTimeoutMs > 10000. */ diff --git a/src/server.ts b/src/server.ts index 34ac891a3a..ae69f231e5 100644 --- a/src/server.ts +++ b/src/server.ts @@ -139,6 +139,7 @@ import { keepResponseId as knobKeepResponseId, noCompressPrompt as knobNoCompressPrompt, noInjectTool as knobNoInjectTool, + postResponseLingerMs as knobPostResponseLingerMs, preflightDeadEndCooldownMs as knobPreflightDeadEndCooldownMs, preflightHoldGraceMs as knobPreflightHoldGraceMs, rawDumpDir as knobRawDumpDir, @@ -386,17 +387,6 @@ export function googleModelFromPath(urlPath: string): string | undefined { } -// #1982: budget for the post-response close linger (see installPostResponseLinger). -// Default 5s mirrors nginx's lingering_time: a peer that FINs promptly costs one -// RTT of extra hold; a silent peer costs at most this window per fd. -// Env-overridable like BILI_MITM_HANDSHAKE_TIMEOUT_MS (tests + operator tuning); -// non-numeric or non-positive values fall back to the default. -const POST_RESPONSE_LINGER_MS_DEFAULT = 5_000; -function postResponseLingerMs(): number { - const v = Number.parseInt(process.env.BILI_POST_RESPONSE_LINGER_MS ?? "", 10); - return Number.isFinite(v) && v > 0 ? v : POST_RESPONSE_LINGER_MS_DEFAULT; -} - export async function startServer(opts: ProxyOptions): Promise { // Configure the tee logger (file + stderr) BEFORE any logging so the very // first line (persist status) lands in the file too. @@ -601,7 +591,7 @@ export async function startServer(opts: ProxyOptions): Promise { if (socket.destroyed) return; if (why === "backstop") { rec.lingerBackstopAt = performance.now(); - log("warn", `[conn#${rec.id}] ${rec.kind} linger backstop: no peer close signal ${postResponseLingerMs()}ms after post-response close — destroying (peer may see RST/ECONNRESET)`); + log("warn", `[conn#${rec.id}] ${rec.kind} linger backstop: no peer close signal ${knobPostResponseLingerMs()}ms after post-response close — destroying (peer may see RST/ECONNRESET)`); } else if (why === "peer-fin") { log("debug", `[conn#${rec.id}] ${rec.kind} linger complete: peer close signal received — closing cleanly`); } @@ -619,7 +609,7 @@ export async function startServer(opts: ProxyOptions): Promise { return origDestroy(); } armed = true; - log("info", `[conn#${rec.id}] ${rec.kind} post-response close: lingering for peer close signal (budget ${postResponseLingerMs()}ms)`); + log("info", `[conn#${rec.id}] ${rec.kind} post-response close: lingering for peer close signal (budget ${knobPostResponseLingerMs()}ms)`); // http leaves the socket paused between requests; without resume() // the peer's EOF would never reach us and every linger would run // out on the backstop. Draining also removes unread recv residual @@ -627,7 +617,7 @@ export async function startServer(opts: ProxyOptions): Promise { socket.resume(); socket.once("end", () => finishLinger("peer-fin")); socket.once("error", () => finishLinger("error")); - backstopTimer = setTimeout(() => finishLinger("backstop"), postResponseLingerMs()); + backstopTimer = setTimeout(() => finishLinger("backstop"), knobPostResponseLingerMs()); backstopTimer.unref?.(); return socket; }; diff --git a/tests/issue1815-unknown-top-level-keys.test.ts b/tests/issue1815-unknown-top-level-keys.test.ts index 83e0377ef3..8073b7095d 100644 --- a/tests/issue1815-unknown-top-level-keys.test.ts +++ b/tests/issue1815-unknown-top-level-keys.test.ts @@ -103,7 +103,7 @@ test("#1815: multiple unknown keys list together; fixing some re-warns about the } }); -test("#1815: the full documented top-level surface produces no warning", () => { +test("#1815: the full documented top-level surface produces no warning (#2062)", () => { const { captured, stop } = captureLogs(); try { withConfigFile( @@ -112,12 +112,18 @@ test("#1815: the full documented top-level surface produces no warning", () => { providersPath: "./providers.json", providers: {}, proxy: "http://127.0.0.1:7890", modelContextLimit: 200000, sessionHeader: true, log: true, debug: true, dumpSse: false, passthrough: {}, autoUpdate: true, autoRestartOnUpdate: true, updateTag: "latest", - advisoryCheck: false, advisoryUrl: "", upstreamProxy: "", upstreamProxyMode: "direct", + advisoryCheck: false, advisoryUrl: "", releaseNotesCheck: false, releaseNotesUrl: "", + upstreamProxy: "", upstreamProxyMode: "direct", logFile: "", compress: { promptPack: "lean" }, promptCache: {}, mitm: {}, maskHosts: true, subagentSplit: true, forkAdoption: false, resumeInheritance: true, chainContentDetection: true, chainEgressStamp: false, stableSystemAnchor: false, - compat: {}, imageBilling: "auto", - claude: { nativePort: 8901 }, native: { attachExternal: false }, + compat: {}, imageBilling: "auto", imageTokenCap: 4096, + resign: {}, claude: { nativePort: 8901 }, native: { attachExternal: false }, + network: { upstreamTimeoutMs: 60000 }, persist: { enabled: true }, + sessions: { max: 64 }, plugin: { snapshotCapBytes: 1048576 }, + update: { checkIntervalMs: 180000 }, diagnostics: { dumpBody: false }, + fakeCompletion: { retries: 0 }, codexCompact: "intercept", + ccrRetrievalTtlMs: 600000, decompressTmpCap: 50, }), () => { loadRoutes(); diff --git a/tests/knobs-config-precedence.test.ts b/tests/knobs-config-precedence.test.ts index d2ea0f0973..fbd101c10e 100644 --- a/tests/knobs-config-precedence.test.ts +++ b/tests/knobs-config-precedence.test.ts @@ -55,6 +55,7 @@ test("defaults: no env, no file", () => { assert.equal(knobs.preflightHoldGraceMs(), 30_000); assert.equal(knobs.preflightDeadEndCooldownMs(), 5 * 60_000); assert.equal(knobs.proxyKeepAliveMaxMs(), PROXY_KEEPALIVE_MAX_MS); + assert.equal(knobs.postResponseLingerMs(), 5_000); assert.equal(knobs.mitmHandshakeTimeoutMs(), 10_000); assert.equal(knobs.persistEnabled(), true); assert.equal(knobs.persistZstdEnabled(), false); @@ -97,6 +98,7 @@ test("file tier: every migrated block resolves from the config file", () => { clientErrorBackstopMs: 45000, exposureLogIntervalMs: 0, streamKeepAliveMs: 20000, preflightHoldMs: 40000, preflightDeadEndCooldownMs: 60000, replayRetryMax: 5, replayRetryBaseMs: 250, maxShrinkPerCompress: 0.4, proxyKeepAliveMaxMs: 60000, + postResponseLingerMs: 12345, }, persist: { enabled: false, zstd: true, debounceMs: 900, tailTokens: 4096, epermAlertThreshold: 9, epermAlertRepeatMs: 1200 }, sessions: { max: 64, gc: { enabled: true, maxAgeDays: 3, maxTokens: 2000000, intervalMs: 60000 } }, @@ -127,6 +129,7 @@ test("file tier: every migrated block resolves from the config file", () => { assert.equal(knobs.replayBaseDelayMs(), 250); assert.equal(knobs.maxShrinkPerCompress(), 0.4); assert.equal(knobs.proxyKeepAliveMaxMs(), 60000); + assert.equal(knobs.postResponseLingerMs(), 12345); assert.equal(knobs.mitmHandshakeTimeoutMs(), 1234); assert.equal(knobs.persistEnabled(), false); assert.equal(knobs.persistZstdEnabled(), true); @@ -162,16 +165,18 @@ test("file tier: every migrated block resolves from the config file", () => { }); test("env tier always wins over the file (live test seams)", () => { - setConfig({ network: { upstreamTimeoutMs: 60000, replayRetryMax: 5 }, persist: { enabled: false }, diagnostics: { renderNone: true, compressProtocol: "text" } }); + setConfig({ network: { upstreamTimeoutMs: 60000, replayRetryMax: 5, postResponseLingerMs: 12345 }, persist: { enabled: false }, diagnostics: { renderNone: true, compressProtocol: "text" } }); withEnv({ BILI_UPSTREAM_TIMEOUT_MS: "999", BILI_REPLAY_RETRY_MAX: "2", + BILI_POST_RESPONSE_LINGER_MS: "777", BILI_PERSIST: "1", ACP_RENDER_NONE: "", ACP_COMPRESS_PROTOCOL: "tools", }, () => { assert.equal(knobs.upstreamTimeoutMs(), 999); assert.equal(knobs.replayMaxAttempts(), 2); + assert.equal(knobs.postResponseLingerMs(), 777); // persistEnabled env tier: only "0"/"false" disable; "1" forces on over file false assert.equal(knobs.persistEnabled(), true); // a SET (even empty) env var owns the knob: historical truthy check @@ -216,6 +221,18 @@ test("set env owns the knob: garbage env resolves exactly as pre-migration", () }); }); +test("post-response linger: strict parseInt tier — set-but-empty/garbage env never consults the file (#1982)", () => { + setConfig({ network: { postResponseLingerMs: 12345 } }); + withEnv({ BILI_POST_RESPONSE_LINGER_MS: "junk" }, () => { + assert.equal(knobs.postResponseLingerMs(), 5_000); + }); + // pre-migration parser was Number.parseInt(env ?? ""): an EMPTY export parsed + // to NaN → default, unlike the tIntLoose family where empty means unset + withEnv({ BILI_POST_RESPONSE_LINGER_MS: "" }, () => { + assert.equal(knobs.postResponseLingerMs(), 5_000); + }); +}); + test("garbage file values fall back to defaults, never throw", () => { setConfig({ network: { upstreamTimeoutMs: "fast", replayRetryMax: -3 }, persist: { tailTokens: null }, ccrRetrievalTtlMs: "whenever", plugin: { snapshotCapBytes: "huge" } }); assert.equal(knobs.upstreamTimeoutMs(), UPSTREAM_TIMEOUT_MS);