Repository navigation
feat: resolve behavior knobs as env > config file > default via src/knobs.ts (#2030) - #2037
Conversation
…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.
f6bc492 to
be4ecc3
Compare
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.2088-pr.2037.e3e781fThis exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr2037.tgz
npm install -g packageInstall instructions are refreshed on each push. |
[bot] 🏷 PR #2037 review 完成 — 结论:方向正确、实现忠实,修掉两处真实问题后已 rebase 到最新 master,可合(等 CI 绿)。 按结构化七问作答: 1. 是什么问题:#2030 要求彻底整治环境变量滥用——把行为可调的 2. 什么原因导致的:历史上没有统一解析层,各模块直接读 3. 怎么修复的:新增 4. 是否有回归问题:我把 40+ 个 accessor 逐个对照 master 历史实现核验,语义全部一致,包括所有 quirk:
披露的行为变更(PR 正文已声明,我复核确认 + 补一个未明说的边缘):ACP_DEBUG 统一——server.ts 三处日志(responses input items、forwarded-tools、client-headers dump)从直读 5. 是否破坏缓存:不涉及。prefix-cache/retry/去重键策略零改动; 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. 是否引入了新的配置:是——新增可选块 Rebase 披露(分支已改写,请知悉):原 head 验证:本地 typecheck clean + 定向测试 362/362 绿(含新 CI 现状(刚触发):E2E(real codex)✅ success、PR Build Artifact ✅ success,其余 lane(CI 主门禁、e2e-native-*/fake-codex/local-registry/ci-image/windows overlay)排队/运行中。CI 红了我会立即跟进排查;全绿后此 PR 即可由人工合并。 |
[bot] 🏷 CI 全绿 ✅ — 10/10 workflow 全部 PR #2037(head |
…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.
…env-vars.md, AGENTS.md staleness fixes (#2037)
|
重新review |
[bot] 🏷 重新 review 完成(第二轮,针对首审后的新提交)— 结论:通过,无新问题,CI 10/10 绿,可合。 本轮范围:分支在首审后新增 3 个提交—— 按七问作答: 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 全量示例 + 4. 是否有回归问题:无。逐项事实核查(不是照单全收):
5. 是否破坏缓存:不涉及(纯文档轮次,零 wire/缓存改动)。 6. 是否改了设计方向:无变化。文档重组遵循仓库既有的"规则留加载区、枚举进 reference/"原则,边界未动。 7. 是否引入了新的配置:本轮无(配置面在首审轮已完整评审并确认 additive、零迁移)。 CI:head 判定:重新 review 通过,未发现新问题,建议人工合并:#2037 |
…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.
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):networkBILI_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_MSpersistBILI_PERSIST*sessionsBILI_MAX_SESSIONS,BILI_SESSION_GC*updateBILI_UPDATE_REGISTRY,BILI_UPDATE_CHECK_INTERVAL_MSdiagnostics<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_PROTOCOLfakeCompletionBILI_FAKE_COMPLETION_RETRIES,BILI_FAKE_BUF_CAPBILI_CODEX_COMPACT,BILI_CCR_RETRIEVAL_TTL_MS,BILI_DECOMPRESS_TMP_CAPmitm.handshakeTimeoutMs(10000),compat.noCacheControl(false),compat.keepResponseId(false)BILI_MITM_HANDSHAKE_TIMEOUT_MS,BILI_NO_CACHE_CONTROL,ACP_KEEP_RESPONSE_IDWhy 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
compresshierarchy 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)
process.env.ACP_DEBUGreads inserver.ts(responses input items, forwarded-tools log, client-headers dump) now resolve throughopts.debug(flag > env > config file). Old:"debug": truein 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.BILI_NO_CACHE_CONTROL's truthy-string quirk, negative watchdog opt-out,proxyKeepAliveMax0/negative handling, gc enable words, dump4xx 1KiB floor).Sensitivity notes
src/update.ts— import-time value source ONLY (REGISTRY_BASE,CHECK_INTERVAL_MSresolve via the resolver: env > file > same defaults). Updater mechanism, locking, and the e2e child-process env contract (test: 自带本地 npm registry 的 hermetic 测试基建——解锁自更新/钉版本/解析全链路 e2e #1153) are untouched. Per §5 a NO-OP validation release precedes any updater-MECHANISM change; this is not one.Verification
npm run typecheckclean,npm run buildcleantests/knobs-config-precedence.test.ts(8 tests) pins the precedence contract incl. garbage-env byte-exactness and hot-reload