[ranxianglei]

What

Issue #6220 asks for a way to force the x-bili-plugin-bypass decision from the outside. Today that decision is made per-request, purely from the header the opencode-acp host plugin stamps for legacy sessions — an operator on a machine where opencode auto-disabled bili had no lever to force either side.

This PR adds the env-only knob BILI_PLUGIN_BYPASS at the proxy decision site (src/server/handle.ts):

Value	Effect
unset / auto	Per-request header decides — zero behavior change (today's default)
1 / on	Force bypass for ALL inbound model traffic: raw passthrough, no compression, no session state. Escape valve when an in-process compressor is loaded but bili still manages those sessions. First hit logs a loud warn: if nothing in-process (e.g. opencode acp) is actually compressing, traffic reaches the model uncompressed.
0 / off	Ignore any inbound bypass header, including opencode legacy ones: bili takes over those sessions. First hit logs a loud warn: their pre-existing ref space lives in the in-process acp store, so their history degrades to a read-only archive.
anything else	Treated as unset (auto) + one warning about the typo

Each forced state emits exactly one warn-once log line (per state); later requests stay at debug level.

Why env-only, no config-file key

Owner ruling in the #6220 thread (plan A, "继续"): this is an explicit escape valve, not a per-machine tunable — env-only by design, per reference/env-vars.md hard rule 1 with owner sign-off in-thread. Generic name (not opencode-specific): the header is a generic wire contract, and the same auto-disable conflict can arise from other in-process compressors too.

Changes

• src/knobs.ts — pure resolvePluginBypass() resolver (env: NodeJS.ProcessEnv injectable, returns "on" | "off" | "auto" | "invalid"), placed with the other resolvers per knob-placement discipline.
• src/server/handle.ts — decision site consumes the resolver: force-on overrides the header; force-off silences it; invalid behaves as auto. Warn-once set pluginBypassForceWarned + test seam _resetPluginBypassForceWarnForTest (same pattern as _resetNoOutputCeilingWarningsForTest).
• tests/plugin-bypass.test.ts — new BILI_PLUGIN_BYPASS force switch (#6220) suite: resolver unit test (tri-state + case/trim + invalid classification) and 4 end-to-end proxy cases against the existing harness (force-on with NO header, force-off WITH header, auto/invalid keep header semantics, warn-once loud lines incl. the exact risk wording). Harness switched to log: true, logFile: "off" (established pattern, e.g. tests/codex-responses-ws.test.ts) so the engine log — a no-op under log: false — is observable via setLogCapture. 7/7 pass.
• Docs: website/config-reference/env-only.yaml entry (generated into docs/configuration.md + zh-CN), docs/lifecycle.md §2.9 line. tools/gen-config-docs.mjs generate + check-coverage clean.

Verification

• node --import tsx --test tests/plugin-bypass.test.ts → 7/7
• tests/knobs-config-precedence.test.ts → 16/16
• scripts/check-test-import-graph.mjs, scripts/lifecycle-ledger-guard.mjs, scripts/config-surface-guard.mjs → all OK
• npm run typecheck → clean

[github-actions]

📦 Built Package Artifact

Branch: 2026-11-12_bili-plugin-bypass-env (1418e30)

Latest build — install this exact version

npm install -g billion-context@0.0.9289-pr.6359.2e57a45

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit	version	build
1418e30	billion-context@0.0.9289-pr.6359.2e57a45	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr6359.tgz
npm install -g package

---

Install instructions are refreshed on each push.