Skip to content

refactor(#1714): retire all BILI_*/ACP_* behavior env vars to config.json - #1747

Closed
ranxianglei wants to merge 4 commits into
masterfrom
2026-09-30_env-surface-retirement-p1
Closed

ranxianglei wants to merge 4 commits into
masterfrom
2026-09-30_env-surface-retirement-p1

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1714

Full-scope delivery of the config-surface convergence: every behavior-class BILI_*/ACP_* environment variable is retired — config.json is now the single input channel for proxy behavior. One PR per owner instruction (thread 2026-09-30).

What changed

Retirement (69 names, canonical registry in src/retired-env.ts)

  • Class A (~25 names, had file+env dual support): env layer deleted, file field kept — pure subtraction.
  • Class B (~34 names, env-only): new top-level config.json fields added + env read removed (src/config.ts, knobs across fetch-util.ts, persist.ts, server.ts, mitm.ts, tunnel-guard.ts, error-dump.ts, decompress-shared.ts, fake-completion.ts, image-tokens.ts, upstream-proxy.ts, store.ts, session-gc.ts).
  • BILI_MITM_DOMAINS user knob retired: the launcher→child pipe is renamed to internal BILI_LAUNCHER_MITM_DOMAINS so no user-facing name re-opens the pollution vector (Opencode failed to send message with error: upstream stream ended before a completion event; this turn may be incomplete #1706 failure mode: stale shell export silently changing behavior).
  • CLI flags (--debug/--no-auto-update/--auto-restart-on-update/--passthrough) now set ProxyOptions directly instead of routing through process.env.
  • Web passthrough state source converged to "file"|null; dead env-source 409 branch removed; clear button always enabled (en/zh copy synced).

P4 — RETIRED startup scan

P5 — docs

Base moved to v0.1.174. My earlier P1 commit (file-only streamStallMs + 5s floor) was superseded by owner-merged #1715, which removed the stall guard entirely — this branch drops P1 and follows master's design. To avoid double-warning, BILI_STREAM_STALL_MS is therefore NOT in the RETIRED map (master's own boot warning covers it).

Behavior change disclosure (old → new)

Per reporting rule 4, every semantic shift:

  1. Input channel: env → config.json for ~69 behavior knobs. Old: export BILI_X=... took effect on next start (and some live-reloaded). New: env values are IGNORED; the config.json field is authoritative. Stale exports are inert and produce a one-time boot warning naming the replacement field. Migration = move value from env to file.
  2. ~24 config.json fields that were previously DEAD CODE now take effect. Before this PR, several file fields existed in FileConfig but nothing forwarded them into the runtime (only tests called the setters) — users who set them got silently ignored values. startServer() + both hot-reload paths in src/server.ts now apply all of them (persist enabled/zstd/tailTokens/debounce/epermAlert×2, maxSessions, imageTokenCap, fakeCompletionRetries/fakeBufCap, dump4xx/maxBytes, decompressTmpCap, ccrRetrievalTtlMs, tunnel allowedHosts, mitm handshakeTimeoutMs, sessionGc{enabled,maxAgeDays,maxTokens,intervalMs}, upstreamTimeoutMs, replayRetryMax/baseMs, maxShrinkPerCompress, proxyKeepAliveMaxMs, streamKeepaliveMs, requestWatchdog, preflightHoldMs, preflightDeadEndCooldownMs, sessionsDir). Old behavior: file value ignored, default used. New: file value honored. This is intended (the whole point of file-only), flagged because it changes what existing config files do.
  3. sessionsDir wiring added (startup + reloads); previously the env var was the only channel and the file field was unwired.
  4. -F/--forward-proxy fix: the flag previously wrote overrides.BILI_UPSTREAM_PROXY; after env retirement that became a silent no-op. Now it sets a local marker applied directly after loadOptions() in all three paths (doctor/update/start). Old: broken (post-retirement); new: works again.
  5. GC sub-knobs (maxAgeDays/maxTokens/intervalMs) now honored from file (part of item 2).
  6. Attach/chain code knobs (attachEvidenceGraceMs, attachHealthDeadlineMs, chain maxFutureSkewMs/recentWindowMs): env fallbacks removed; programmatic module setters remain (tests/internal callers); no new config fields added — these post-date the issue inventory and are not user-facing product knobs; if you want them file-configurable, say so and I'll add them deliberately.
  7. Defaults unchanged everywhere: every knob's unset/default value is identical to before; only the input channel moved.

Kept seams (documented, not retired)

  • Class C/D kept: transport/system-proxy conventions, inter-process pipes (BILI_LAUNCHER_MITM_DOMAINS), secret inputs, test seams (ACP_TEST_*, BILI_FAKE_HOOK_CMD, BILI_EPIPE_LOG_FILE, BILI_TEST_MARKER), ACP_RENDER_NONE D-seam, ACP_PORT/HOST, BILI_CONFIG_FILE.
  • Class E gray zone untouched pending owner decision: BILI_ENCRYPTION_KEY, ACP_UPSTREAM, ACP_PROVIDERS, ACP_DUMP_* (listed here for the ruling, not migrated).

Findings while working

  • ACP_REASONING_KEEP is owned by acp-kernel (behavioral probe: unset→reasoning preserved, none→dropped; bili passes it through). Out of scope — cross-repo; deferred, noted here rather than filed per loop-guard.
  • tests/fix-437-idle-timeout.test.ts "healthy stream longer than timeout" failed 1× in local full-suite runs; solo A/B: fails 1/10 on pristine master too → pre-existing event-loop timing race (>500ms between 100ms chunks under load), not this PR (the diff touches none of its timer logic). CI is arbiter.

Pre-flight

  • npm run typecheck ✅ · npm run build ✅
  • Full suite: 3326 pass / 1 fail (the pre-existing fix-437 flake above) / 17 gated skips
  • E2E zero-token preflight (E2E_CHECK=1) ✅; full local codex e2e fails identically on pristine master in this sandbox (environment limitation, verified A/B) → relying on ci-e2e.yml, which auto-runs (touches pipeline hot files).
  • Diff vs origin/master: 100 files, +1804/−1148 — src/, tests/, CONFIGURATION.md (+zh) only. No version bump, no lockfile churn.

Replaces #1716 (closed): after rebasing onto v0.1.174, the force-push orphaned #1716's recorded head commit and GitHub refuses to reopen it (POST /pulls/1716/reopen → 404 despite the PR existing). Same branch, full scope.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-30_env-surface-retirement-p1 (ebb01fd)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1728-pr.1747.7c3a66e

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1747.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是已交付的 PR(#1747,对应 #1714 全量范围),我不重做工作,按 PR 审查规范走完整 review:① 原 issue 方向核对(已读 #1714 全线程,owner 指示「一个 PR 搞定、别应付了事」→ 本 PR 全范围交付,方向一致)② 回归审查 ③ 代码审查 ④ 测试有效性 ⑤ diff 整洁度。拉分支核对中,结论稍后回贴(含中文一句话摘要)。

ework-agent and others added 2 commits September 30, 2026 14:42
Every behavior-class BILI_*/ACP_* env var (~70 names) is removed from bili's
read surface and now lives only in config.json (canonical mapping + one-time
boot warning in src/retired-env.ts). Transport/identity overrides, launcher IPC
channels, secret material, and default-invariant test seams stay env-based by
design.

Also fixed on the way (disclosed per #1714 rule 4):
- 24+ config.json fields were dead code in production (configure* setters never
  called): startServer + both live-reload paths now forward every knob from
  ProxyOptions, so file values actually take effect.
- sessionsDir config field wired at startup + reloads (was env-only before).
- -F flag: overrides.cliUpstreamProxy applied post-loadOptions instead of the
  retired BILI_UPSTREAM_PROXY env name (old path silently no-op'd).
- attach evidence-grace / health-deadline and chain skew/recent-window knobs:
  env fallbacks replaced by programmatic opts/configure* setters (no new
  config fields — code knobs, not user surface).
- BILI_STREAM_STALL_MS left out of RETIRED_ENV: master's #1715 dedicated boot
  warning already names it (avoid double warn).
…ICT_PORT pipe

Review finding on the env-surface retirement: #1714's Class B inventory
lists BILI_STRICT_PORT, but it was left readable from process.env in every
proxy (server.ts port-retry opt-out, #964). It is a claude SessionStart
hook -> launcher -> child pipeline var, so like BILI_MITM_DOMAINS it moves
to the internal BILI_LAUNCHER_* namespace and joins the RETIRED boot-scan
map — a stale 'export BILI_STRICT_PORT=1' now warns instead of silently
disabling port retry on all instances (#1706 failure class). Also rebased
onto current master (no file overlap with #1741).
@ranxianglei
ranxianglei force-pushed the 2026-09-30_env-surface-retirement-p1 branch from 3296c8b to 87eaff4 Compare September 30, 2026 06:44
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 — 可以直接合并(需人工 merge)。按规范逐项过了一遍,过程中发现并直接修掉了一处真实缺口(BILI_STRICT_PORT 漏退役),已补在分支上。

① 原 issue(#1714)方向关:对齐。owner 指令是全量收敛,PR 打到了决策点(loadOptions/configure* 单一来源),不是症状层过滤。我核对了 master 上全部 114 个 BILI_*/ACP_* 读取点 vs PR head 保留的 53 个:退役的 62 个全部在 RETIRED boot-scan 映射里(stale export 会 warn + 迁移提示,没有静默死亡);保留的 53 个全部是合法 seam(管道 BILI_LAUNCHER_*/BILI_INHERITED_*/BILI_PARENT_PID/BILI_CONFIG_FILE 等、测试 seam ACP_NO_*/ACP_DUMP_*/ACP_PORT 等、updater seam BILI_UPDATE_REGISTRY/BILI_UPDATE_CHECK_INTERVAL_MS 默认不变)+ Class E 灰区(BILI_ENCRYPTION_KEY/ACP_UPSTREAM/ACP_PROVIDERS)——灰区等你拍板,body 里已列明。

② 回归审查(既有行为清单):

  • ~69 个行为开关:通道从 env→file-only,默认值逐一核对全部不变(fetch-util 30min/1500ms、persist debounce 500/enabled true/zstd false/tailTokens 16384、tunnel-guard trim+lowercase 归一化与旧 CSV parser 等价、session-gc off/7d/1M/hourly、MAX_SESSIONS 256、zonePortBase 18787 校验一致……)。旧行为(env 覆盖 file)→ 新行为(file 唯一权威源 + 少数 CLI flag):这是 配置面收敛:移除全部 BILI_*/ACP_* 行为类环境变量,统一迁入 config.json #1714 的有意变更,逐 knob 披露在 issue body;shell 里残留的旧 export 从此失效并由 boot warn 提示——正是 Opencode failed to send message with error: upstream stream ended before a completion event; this turn may be incomplete #1706 失败类的根治。
  • ~24 个此前 dead 的 file 字段现在生效(GC 子字段、sessionGcMaxAgeDays 等)——有意,已披露。
  • CLI:-F 修复(原来 env 在 loadOptions 之后被清掉,flag 实际失效 → 现直接设 opts.proxy,doctor/start/update 三条路径都覆盖);--debug/--no-auto-update/--auto-restart-on-update/--passthrough 改走 ProxyOptions,用户可见语义不变;cli* marker key 有 /^[A-Z][A-Z0-9_]*$/ 守卫,不会泄漏进子进程 env。
  • web passthrough source "bili-env"→"file"(纯展示)、clear 按钮恒可用、i18n en/zh 同步;logFile:"off" 仍工作(src/logger.ts:219)。
  • BILI_MITM_DOMAINS→内部管道 BILI_LAUNCHER_MITM_DOMAINS:child 不再继承用户 shell 里的同名变量——有意,已披露。
  • 无阈值/时序/输出格式漂移(除上述有意通道切换)。

③ 代码审查主关 + 我的直接修复:通读 100 文件 diff。发现:#1714 Class B 列了 BILI_STRICT_PORT,但 PR 没处理它——它仍是 claude SessionStart hook→launcher→child 管道变量(src/launcher.ts:2990 写入),而每个 proxy 都从 process.env 读它做端口重试豁免(src/server.ts:692,#964)。stale export BILI_STRICT_PORT=1 会让所有实例静默关掉 port retry = 本 PR 要消灭的那类故障。已直接在分支修掉(commit 87eaff41):writer/reader 重命名为 BILI_LAUNCHER_STRICT_PORT(同 MITM_DOMAINS 模式),并加入 RETIRED 映射(stale export 会 warn,提示"claude launcher 自动设置")。非阻塞小记:opts 里的 zonePort/zcodeNativePort 字段被填充但从未消费(consumer 直接读 config file)——冗余无害,不拦;attach×2/chain×2 code knob 不加 config 字段是有意(body item 6,setter 保留)。
另外:master 期间合入了 #1741,我已 rebase 到当前 master(c8b62af)——零文件重叠,干净 rebase,非 force-push 到受保护分支。

④ 测试有效性:330+ 断言迁移到 file-based surface,module-state knob 都有 reset 函数;本地定向跑 292/292 全过(retired-env/port-zone/cli-parseargs/launcher/fix-config-session/zero-config-routing)+ typecheck clean + 功能冒烟(stale env 全部 warn 且 file 值胜出)。新 head CI:全部 e2e lane 绿(real pi/opencode/dsh/codex zero-token、hermetic registry verdaccio)+ build-artifact + version-guard 绿;unit test 矩阵(ubuntu/windows × 22/24)在我写这条时还在跑,结果出来我再补一条确认。已知 flake fix-437-idle-timeout 在纯 master 上也 ~1/10 失败(event-loop race,diff 未触碰其时序),以 CI 为准。

⑤ diff 整洁度:仅 src/tests/docs,无 package.json/lockfile/version 变更,单一逻辑提交 + 我一条有标注的 fix 提交。

自动合并门:不适用(config schema 变更 + refactor,必须人工 merge)。遗留:Class E 灰区 4 个名字等你拍板;ACP_REASONING_KEEP 是 kernel 侧读取,cross-repo,body 已注明。

中文摘要:审查了 #1714 环境面收敛 PR——方向对齐、约 70 个行为开关全部转为 file-only 且默认值不变、发现并直接修掉 BILI_STRICT_PORT 漏退役(重命名内部管道名并纳入退役扫描)、rebase 到最新 master 后 e2e 全绿,可以合并。

@ranxianglei
ranxianglei force-pushed the 2026-09-30_env-surface-retirement-p1 branch from 87eaff4 to 918e905 Compare September 30, 2026 07:27
The env->file migration pointed claude.nativePort at $XDG_CONFIG_HOME/
billion-context.json, but the app reads $XDG_CONFIG_HOME/billion-context/
billion-context.json (src/paths.ts configDir()). Unresolved nativePort made
every pinned-port hook e2e launch fall back to the shared zone base 18787:
the strict-port test saw "proxy started at http://127.0.0.1:18787" instead
of a loud bring-up failure, four more hook e2e tests timed out on their
pinned ports, and the leaked 18787 daemons collided with the unchanged
tests/port-zone-live.test.ts suite under concurrent node --test.
@ranxianglei
ranxianglei force-pushed the 2026-09-30_env-surface-retirement-p1 branch from 918e905 to 72b62c8 Compare September 30, 2026 07:33
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补一条:unit test 矩阵红了——根因已定位并修好,新 head 72b62c88 在跑 CI。 上一条说"可以合并"时 unit job 还在跑,现在结果出来了,先纠正结论。

① 红在哪:ubuntu/windows × node 22/24 四个 unit job 全挂(旧 head 3296c8b 和新 head 87eaff41 同样挂,master 四个全绿)——是 PR 自身引入的回归,不是我的 strict-port fix、也不是环境抖动。8 个失败:

  • tests/claude-native.test.ts 5 个 hook e2e(其中 "occupied stable port" 的 actual 是 proxy started at http://127.0.0.1:18787 —— zone base,不是它 pin 的端口);
  • tests/port-zone-live.test.ts 3 个(该文件本 PR 一行没改,EADDRINUSE 18787 / attach 错配)。

② 根因(单个 bug):env→file 迁移把 live hook-e2e 沙箱配置写错了目录——4 处(runHook + watchdog + manual-start + shared-proxy 测试)写到 $XDG_CONFIG_HOME/billion-context.json,而 app 读的是 $XDG_CONFIG_HOME/billion-context/billion-context.json(src/paths.ts 的 configDir() 带 billion-context/ 子目录)。后果链:claude.nativePort 解析不到 → planClaudeNativeBootstrap 返回 port=undefined → 非 strict 的 zone-riding 启动落到共享 base 18787(正好解释那个 started at ...:18787)→ 其余 4 个 hook e2e 在自己 pin 的端口上等满 60s 超时 → 泄漏在 18787 上的 daemon 又和并发跑的 port-zone-live 套件(node --test 跨文件并行)撞端口。同文件里迁移过的 unit 测试(190/215/237/265 行)路径是对的,所以只有 live e2e 挂。

③ 修复 + 验证:已在分支直接修掉(commit 72b62c88,仅 tests/claude-native.test.ts,4 处 × mkdir+write 共 8 行)。本地 ACP_TEST_CLAUDE_NATIVE=1 实跑 claude-native.test.ts + port-zone-live.test.ts:55/55 全绿(含全部 5 个 hook e2e、ps-walk、4 个 zone live);typecheck/build clean。(本地验证有个小插曲:本沙箱 /tmp 只读、TMPDIR 指到工作区 .tmp,而 fake-claude 无扩展名脚本会向上找到 workspace 的 "type":"module" package.json 被当 ESM 解释而崩——纯本地环境伪影,CI 的 tmpdir 是 /tmp 不受影响,与 PR 代码无关。)

④ 分支协调说明(重要):我审查期间(15:27)分支被重写为 918e9050(基于 #1741 之前的旧 master 27c8774a,单提交)。逐行比对后确认:它独立修了同一个 test path bug(cfgDir 变量写法,与我语义等价),但不含我前面修的 BILI_STRICT_PORT 退役(server.ts:692 仍从 process.env 读、launcher.ts:2990 仍写旧名),且没 rebase 到当前 master。我已把完整栈 force-push 回 feature 分支(非保护分支):c8b62af6(当前 master,含 #1741)← refactor ← 87eaff41(strict-port 退役)← 72b62c88(test path 修复)。推送前已验证我的栈是其严格超集(diff 只剩 strict-port 4 文件 + #1741 的 tag-echo 两文件 + 测试写法差异),没有任何内容丢失。如果那侧还有活跃会话在推这个分支,请知会它别再覆盖。

⑤ 当前状态:新 head 72b62c88 CI 运行中(e2e lanes 此前全绿,盯 unit 矩阵)。unit 四格转绿后即可人工合并(自动合并门不适用:config schema 变更 + refactor)。Class E 灰区 4 个名字仍等你拍板。

中文摘要:unit 矩阵红是 PR 自己的 test harness bug(沙箱配置写高一层目录导致 pinned-port 启动全落到共享 18787 并级联打挂未改动的 port-zone-live 套件),已直接在分支修好并本地 55/55 复验,同时恢复了被并行重写丢掉的 BILI_STRICT_PORT 退役修复,rebase 到最新 master 后等新 head CI 转绿即可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 全绿,可以合并。 新 head 72b62c88 全部 check run 通过:

  • unit 矩阵 4/4 绿:test (ubuntu-latest, 22/24) + test (windows-latest, 22/24)——之前红的就是这四格,现在全过;
  • e2e lanes 全绿:real pi / opencode / dsh / codex zero-token、hermetic registry (verdaccio)、e2e、codex CODEX_HOME overlay;
  • build-artifact + version-guard 绿。

分支最终栈:c8b62af6(当前 master,含 #1741)← refactor(#1714)← 87eaff41(BILI_STRICT_PORT 退役)← 72b62c88(live hook-e2e 沙箱配置路径修复)。剩余事项:① 人工合并(自动合并门不适用);② Class E 灰区 4 个名字(BILI_ENCRYPTION_KEY/ACP_UPSTREAM/ACP_PROVIDERS/ACP_DUMP_*)等你拍板。

中文摘要:修复后新 head CI 全绿(unit 四格转绿 + e2e 全 lane),PR 已具备合并条件,请人工合并。

…g zonePort); preserve master's #1723 drift-warn; re-add configureMaxSessions/configureSessionsDir imports
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

配置面收敛:移除全部 BILI_*/ACP_* 行为类环境变量,统一迁入 config.json

2 participants