Skip to content

feat: resolve behavior knobs as env > config file > default via src/knobs.ts (#2030) - #2037

Merged
ranxianglei merged 5 commits into
masterfrom
2026-10-04_env-knob-config-migration
Oct 4, 2026
Merged

ranxianglei merged 5 commits into
masterfrom
2026-10-04_env-knob-config-migration

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2030

彻底整治环境变量滥用:每个纯行为开关现在都有配置文件键,环境变量仅保留为覆盖层。

What this does

New src/knobs.ts — the single resolver module. Precedence: env var > config file > built-in default. The env tier preserves each variable's historical parsing quirks byte-exact (backward compat); the file tier takes strict typed values. A set-but-garbage env value resolves exactly as it did pre-migration (falls back to the default) and neither leaks into nor is shadowed by the file tier. Leaf modules keep their exported function names/signatures and delegate to the resolver.

Config surface (mandatory section)

New optional top-level blocks in billion-context.json (existing configs need no migration):

Block Keys (defaults) Former env-only knobs
network upstreamTimeoutMs (720000), requestWatchdogMs (2× upstream timeout), replayRetryMax (3), replayRetryBaseMs (1500), maxShrinkPerCompress (unset), keepAliveTimeoutMs (5000), clientErrorBackstopMs (30000), exposureLogIntervalMs (3600000), streamKeepAliveMs (15000), preflightHoldMs (30000), preflightDeadEndCooldownMs (300000), proxyKeepAliveMaxMs (55000) BILI_UPSTREAM_TIMEOUT_MS, BILI_REQUEST_WATCHDOG_MS, BILI_REPLAY_RETRY_*, 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
persist enabled (true), zstd (false), debounceMs (500), tailTokens (16384), epermAlertThreshold (5), epermAlertRepeatMs (0) BILI_PERSIST*
sessions max (256), gc.enabled (false), gc.maxAgeDays (7), gc.maxTokens (1000000), gc.intervalMs (3600000) BILI_MAX_SESSIONS, BILI_SESSION_GC*
update registry (npm public), checkIntervalMs (180000) BILI_UPDATE_REGISTRY, BILI_UPDATE_CHECK_INTERVAL_MS
diagnostics dumpBody, dumpReq (true), rawDumpDir (<state>/raw), dump4xx, dump4xxMaxBytes (2MiB), renderNone, noInjectTool, noCompressPrompt, countTokensPassthrough, compressProtocol ("tools") ACP_DUMP_BODY, ACP_DUMP_REQ, ACP_RAW_DUMP_DIR, BILI_DUMP_4XX*, ACP_RENDER_NONE, ACP_NO_INJECT_TOOL, ACP_NO_COMPRESS_PROMPT, ACP_COUNT_TOKENS_PASSTHROUGH, ACP_COMPRESS_PROTOCOL
fakeCompletion retries (0), bufCapBytes (16MiB) BILI_FAKE_COMPLETION_RETRIES, BILI_FAKE_BUF_CAP
scalars codexCompact ("intercept"), ccrRetrievalTtlMs (600000), decompressTmpCap (50) BILI_CODEX_COMPACT, BILI_CCR_RETRIEVAL_TTL_MS, BILI_DECOMPRESS_TMP_CAP
existing blocks extended mitm.handshakeTimeoutMs (10000), compat.noCacheControl (false), compat.keepResponseId (false) BILI_MITM_HANDSHAKE_TIMEOUT_MS, BILI_NO_CACHE_CONTROL, ACP_KEEP_RESPONSE_ID

Why the existing surface cannot express these: ~30 knobs were env-only with no config representation at all. The providers table is per-provider scoped (wrong for process-wide timing/diagnostics); the three-level compress hierarchy is compression-feature-specific; a pile of 30 flat top-level keys would pollute the config root — hence grouping by subsystem. Where a fitting block existed it was extended instead of duplicated (compat, mitm).

Compat/migration: fully additive. Every default is unchanged; every env var keeps working with identical parsing. No persistence-format or wire change. Env-only variables remain reserved for what cannot live in the file (secrets, spawn-time channels, host-side posture, path relocation, third-party conventions) — now codified in AGENTS.md.

Behavior changes (disclosed, old → new)

  1. ACP_DEBUG unification: the three inline process.env.ACP_DEBUG reads in server.ts (responses input items, forwarded-tools log, client-headers dump) now resolve through opts.debug (flag > env > config file). Old: "debug": true in the config file had NO effect on those paths (only flag/env worked). New: it does. Flag/env behavior unchanged; verified no test relied on the old bypass.
  2. Everything else: defaults byte-identical — each accessor was checked against its pre-migration parse quirk one by one (incl. BILI_NO_CACHE_CONTROL's truthy-string quirk, negative watchdog opt-out, proxyKeepAliveMax 0/negative handling, gc enable words, dump4xx 1KiB floor).

Sensitivity notes

Verification

  • npm run typecheck clean, npm run build clean
  • Targeted local runs (full suite is CI's job): 282 tests across every touched module green — persist*, session-gc, codex-compact, fake-completion, error-dump, anthropic-cache-control, count-tokens, issue1881×2, fix-decompress-reaper, mitm, upstream-fail, loop-core, fix-551, fix-806×2, issue1452-socket-hardening, preflight-hold, stream-keepalive, wire-exit×2, issue1815 (unknown-top-level-keys)
  • New tests/knobs-config-precedence.test.ts (8 tests) pins the precedence contract incl. garbage-env byte-exactness and hot-reload
  • AGENTS.md: new "Environment Variable Discipline" section (categories + hard rules); CONFIGURATION.md en+zh: precedence model paragraph + full env→config-key mapping table (also first documentation of the previously undocumented debug knobs)

ework-agent added 2 commits October 4, 2026 13:51
…nobs.ts (#2030)

Every pure-behavior env var (BILI_*_MS timeouts, persist/session-gc,
diagnostics/dump flags, fake-completion, codex-compact, ccr ttl, update
registry/interval, mitm handshake, proxy keepalive, replay retry, ...)
gains a config-file key under new network/persist/sessions/update/
diagnostics/fakeCompletion blocks (+mitm.handshakeTimeoutMs,
compat.noCacheControl, compat.keepResponseId). Env stays the override
tier with byte-exact historical parsing; a set-but-garbage env value
resolves exactly as pre-migration and never leaks into the file tier.

Also unifies the three inline ACP_DEBUG reads in server.ts through
opts.debug so config-file debug reaches those log paths (previously
only flag/env worked there). Adds AGENTS.md Environment Variable
Discipline section and documents all keys in CONFIGURATION.md en/zh.
@ranxianglei
ranxianglei force-pushed the 2026-10-04_env-knob-config-migration branch from f6bc492 to be4ecc3 Compare October 4, 2026 05:55
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-04_env-knob-config-migration (45d822e)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2088-pr.2037.e3e781f

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-pr2037.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 #2037 review 完成 — 结论:方向正确、实现忠实,修掉两处真实问题后已 rebase 到最新 master,可合(等 CI 绿)。

按结构化七问作答:

1. 是什么问题:#2030 要求彻底整治环境变量滥用——把行为可调的 BILI_*/ACP_* 全部迁入配置文件,并在 AGENTS.md 立规范防止 env 继续膨胀。本 PR 即该需求的实现。

2. 什么原因导致的:历史上没有统一解析层,各模块直接读 process.env 且各自散落解析 quirk(env 值怎么解析、空串算不算设置、garbage 怎么处理都不统一);行为旋钮只存在于 env,配置文件无对应项,导致 env 面无限增长。

3. 怎么修复的:新增 src/knobs.ts 单一解析层(tiered raw resolvers:tNum/tNumLoose/tInt/tIntLoose),优先级 env > 配置文件 > 默认值;env 层逐字节保留历史解析行为(garbage env 解析结果与迁移前完全一致,绝不泄漏进/被文件层遮蔽);文件层取严格类型值;叶子模块保持函数名与签名不变、纯委托。配套:config.ts 加 typed 块并扩展 KNOWN_TOP_LEVEL_KEYS(防 unknown-key 告警刷屏)、新测试套件钉住优先级、AGENTS.md 立「Environment Variable Discipline」节、CONFIGURATION.md en/zh 映射表。

4. 是否有回归问题:我把 40+ 个 accessor 逐个对照 master 历史实现核验,语义全部一致,包括所有 quirk:NO_CACHE_CONTROL 任意非空(含 "0")生效、KEEP_RESPONSE_ID/dump 类严格 "1"、watchdog 负数 opt-out 直通、proxyKeepAliveMaxMs 0→0/负→默认、gc enable 词表 ["1","true","on"]、dump4xx 1KiB floor、maxShrinkPerCompress (0,1] 校验等。发现并修复两处真实问题(均已在推送分支上):

披露的行为变更(PR 正文已声明,我复核确认 + 补一个未明说的边缘):ACP_DEBUG 统一——server.ts 三处日志(responses input items、forwarded-tools、client-headers dump)从直读 process.env.ACP_DEBUG 改走 opts.debug(flag > env > 配置文件)。旧:配置文件 "debug": true 对这三处无效;新:有效。补充边缘:旧代码是 truthy 判断,ACP_DEBUG=<非"1"的非空值>(如 "0"、"yes")以前会点亮这三处日志,新严格 === "1" 后不再点亮——与 bili 标准 debug 语义对齐,--debug flag 用户不受影响。其余所有默认值与迁移前逐字节相同。触碰路径上的既有行为(#1933 F1 计费估算块、#1954 chain-warning、WS forward 日志)在冲突解决中全部按 union-of-intent 保留。

5. 是否破坏缓存:不涉及。prefix-cache/retry/去重键策略零改动;FORCE_TEXT_PROTOCOL 仍是 import 时冻结(冻结点与之前相同);MAX_SESSIONS 同样 import 时冻结;CHECK_INTERVAL_MS 保持 import-time const(update e2e 子进程 env 契约完好)。

6. 是否改了设计方向:是,且正是 owner 在 #2030 里点名的方向——引入配置单一解析层 + 立开发规范。边界纪律清晰:secrets / per-process channels / host-side posture / path relocation / 第三方约定仍保持 env-only(AGENTS.md 分类表);config surface 新增全部为可选附加块,现有配置零迁移。符合 Configuration Surface Discipline(owner-gated,issue 中已明确授权)。

7. 是否引入了新的配置:是——新增可选块 network/persist/sessions/update/diagnostics/fakeCompletion + 标量 codexCompact/ccrRetrievalTtlMs/decompressTmpCap + 扩展 mitm.handshakeTimeoutMs/compat.noCacheControl/compat.keepResponseId;默认值与既有默认完全一致,key 名与对应 env 的映射见 CONFIGURATION.md(en/zh 同步)。另立新规范:新 env var = 新讨论、每个旋钮一个 resolver(env wins over file always)、document or don't ship。


Rebase 披露(分支已改写,请知悉):原 head f6bc4925 基于 f2b18022,落后 master 108 commits,merge conflict(dirty)。我已 rebase 到当前 master tip 6edfc6f7(含 #2014/#1996 修复)并 force-push 到 PR 分支(feature 分支,非 master):新 head be4ecc37,2 个 commit(rebased feat + JSDoc nit)。4 处冲突按 union-of-intent 解决:#1933 F1 块保留 + knobRenderNone()、#1954 warning 保留并挂到 !knobKeepResponseId() 门下、WS-aware forward 日志保留 + opts.debug、adapter 同构。PR 状态已从 dirty 翻回 mergeable=True(现仅 blocked=等 CI)。

验证:本地 typecheck clean + 定向测试 362/362 绿(含新 tests/knobs-config-precedence.test.ts 8 例——真断言有牙,gate ④ 通过;覆盖默认值、文件层、env-wins、garbage-env 字节等价、quirk 钉死、热重载)。全量回归交给远程 CI。

CI 现状(刚触发):E2E(real codex)✅ success、PR Build Artifact ✅ success,其余 lane(CI 主门禁、e2e-native-*/fake-codex/local-registry/ci-image/windows overlay)排队/运行中。CI 红了我会立即跟进排查;全绿后此 PR 即可由人工合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 全绿 ✅ — 10/10 workflow 全部 completed/success:CI 主门禁、CI Windows codex overlay、E2E(real codex)、PR Build Artifact、ci-image、e2e-fake-codex、e2e-local-registry、e2e-native-dsh、e2e-native-opencode、e2e-native-pi。

PR #2037(head be4ecc37,基于当前 master tip 6edfc6f7)已具备合并条件,请人工合并:https://github.com/ranxianglei/billion-context/pull/2037(合并后自动 close #2030)。

ework-agent and others added 3 commits October 4, 2026 14:16
…ess-level blocks

Owner review of PR #2037: the new blocks were only listed in the env-var mapping table, with no proper Parameter-Reference sections and no JSON example. Adds per-block sections (network/persist/sessions/update/diagnostics/fakeCompletion/scalars) under Server Settings with a full annotated jsonc example, compat.noCacheControl/keepResponseId bullets + type line, and fixes the stale 'env-only' note on BILI_NO_CACHE_CONTROL. En + zh mirrored.
@ranxianglei

Copy link
Copy Markdown
Owner Author

重新review

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 重新 review 完成(第二轮,针对首审后的新提交)— 结论:通过,无新问题,CI 10/10 绿,可合。

本轮范围:分支在首审后新增 3 个提交——fcd7d0a0(CONFIGURATION en/zh 补 per-block Parameter-Reference 节 + 完整 jsonc 示例)、bfbd9330(env discipline 细则移入 reference/env-vars.md、README 配置节、architecture.md 重生成、AGENTS.md 陈旧修正)、45d822eb(merge 当前 master 4fd4cfea,PR 已最新)。源码文件与首审时逐字节一致,本轮全部是文档与合并。

按七问作答:

1. 是什么问题:owner 首审反馈——新增配置块只出现在 env 映射表里,没有正式的参数参考节和 JSON 示例;同时 AGENTS.md 积累了若干陈旧描述。这 3 个提交即对该反馈的落实。

2. 什么原因导致的:首版文档把 #2030 的新块当"映射表附录"处理,未给 Parameter-Reference 级待遇;AGENTS.md 陈旧项(acp-kernel pin、配置文件名、release carve-out、hermetic lanes)是历史漂移。

3. 怎么修复的:CONFIGURATION.md en/zh 各 +131 行(每块独立 section:Type/Default/Status/Description + 带注释 jsonc 全量示例 + compat.noCacheControl/keepResponseId 补进 compat 类型行与条目,并修正 BILI_NO_CACHE_CONTROL 的过期 "Env-only" 注记);env discipline 的类别表+4 条硬规则+rationale 移入 reference/env-vars.md,operative 决策规则保留在自动加载的 AGENTS.md(3 行摘要 + 指针,符合本仓 AGENTS.md/reference 分层哲学);AGENTS.md 修 4 处陈旧;architecture.md 按"源文件变动必须重生成模块图"规则更新(knobs.ts 入图)。

4. 是否有回归问题:无。逐项事实核查(不是照单全收):

5. 是否破坏缓存:不涉及(纯文档轮次,零 wire/缓存改动)。

6. 是否改了设计方向:无变化。文档重组遵循仓库既有的"规则留加载区、枚举进 reference/"原则,边界未动。

7. 是否引入了新的配置:本轮无(配置面在首审轮已完整评审并确认 additive、零迁移)。

CI:head 45d822eb 全部 10 个 workflow completed/success(CI 主门禁、Windows codex overlay、E2E real codex、Build Artifact、ci-image、fake-codex、local-registry、native-dsh/opencode/pi)。PR 状态 mergeable=True(blocked=仅等 CI,现已满足)。

判定:重新 review 通过,未发现新问题,建议人工合并:#2037

@ranxianglei
ranxianglei merged commit 30e64f0 into master Oct 4, 2026
16 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 4, 2026
antclt pushed a commit to antclt/billion-context that referenced this pull request Oct 4, 2026
…onseLingerMs (ranxianglei#2062)

ranxianglei#1982's post-response close linger budget landed after the ranxianglei#2037 knob
migration and stayed env-only (server.ts read process.env directly),
violating the ranxianglei#2030 discipline that pure-behavior knobs get a config-file
key. The issue names the target shape network.postResponseLingerMs
(owner sign-off). Now resolved env > file > default through knobs.ts with
the historical parseInt parsing preserved byte-exact (set-but-empty/
garbage env falls back to the default without consulting the file).
Default stays 5000; env semantics unchanged — additive file tier only.
@ranxianglei
ranxianglei deleted the 2026-10-04_env-knob-config-migration branch October 15, 2026 05:32
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.

彻底整治环境变了滥用,除非必要都走配置文件

1 participant