Skip to content

docs(configuration): Server Settings parity with src/config.ts surface (#2062) - #2064

Merged
ranxianglei merged 4 commits into
masterfrom
2026-10-04_config-docs-server-settings
Oct 4, 2026
Merged

ranxianglei merged 4 commits into
masterfrom
2026-10-04_config-docs-server-settings

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2062

改动

CONFIGURATION.md(en + zh-CN)§Server Settings 补齐相对 src/config.ts 配置面的全部缺失条目:23 个新键条目 + network 小节扩展。

issue 清单内(18 项,全部覆盖)
upstream、logFile、maskHosts、subagentSplit、forkAdoption、resumeInheritance、chainContentDetection、chainEgressStamp、stableSystemAnchor、autoUpdate、autoRestartOnUpdate、updateTag、advisoryCheck、advisoryUrl、releaseNotesCheck、releaseNotesUrl、upstreamProxy、network.postResponseLingerMs

同机制补差(6 项,实现时系统性 diff FileConfig vs 文档标题发现)
upstreamProxyMode(upstreamProxy 的配套模式键)、providersPath、顶层 modelContextLimit、promptCache、claude、native

另有:#2030 env 映射表补 BILI_POST_RESPONSE_LINGER_MS 行;主 env 表补 ACP_AUTO_RESTART_ON_UPDATE 行(此前 README 有文档但两版手册 env 表均无)。

顺手小修(独立标注):CONFIGURATION.md 既有 BILI_NATIVE_ATTACH_EXTERNAL env 行的 TECHNICAL-NOTES 锚点缺 -1660(死链),修正为实际标题 slug。

config surface(AGENTS.md 强制节)

新增字段:network.postResponseLingerMs(number,默认 5000,env twin BILI_POST_RESPONSE_LINGER_MS)。

行为变更披露(旧 → 新)

  1. linger 预算获得文件层:此前仅 BILI_POST_RESPONSE_LINGER_MS env;现按 env > file(network.postResponseLingerMs) > 5000 解析。默认值与 env 语义完全不变,纯增量。
  2. unknown-key 告警输出变化(fix commit):releaseNotesCheck / releaseNotesUrl / imageTokenCap / plugin 四个本来就生效的键此前误报 [acp-config] ignoring unknown top-level config key(s)(KNOWN_TOP_LEVEL_KEYS 白名单落后于 FileConfig 接口)。修复后不再告警、照常生效。仅告警输出变化,功能行为不变。
  3. 其余为纯文档增量,无行为影响。

测试

本地定向(全量回归交 CI):typecheck 干净;tests/knobs-config-precedence.test.ts 13/13(含新键 default / file-tier / env-wins / junk-parse 4 例);tests/issue1815-unknown-top-level-keys.test.ts 4/4(已扩展为钉住 FileConfig 全字段面,A/B 验证:撤掉 fix commit 即挂于 ignoring unknown top-level config key(s): releaseNotesCheck, releaseNotesUrl, imageTokenCap, plugin);tests/graceful-close.test.ts 1/1(其子进程 env pin 在迁移后仍优先生效)。

ework-agent added 3 commits October 4, 2026 17:12
…#2062)

releaseNotesCheck/releaseNotesUrl/imageTokenCap/plugin were read by
loadOptions/knobs but absent from the known-key set, so users setting
them got a spurious 'ignoring unknown top-level config key(s)' warning
although the keys work. Add them to the set and extend the issue1815
full-surface test to pin every FileConfig field (A/B-verified: the
extended test fails on the pre-fix set).
…onseLingerMs (#2062)

#1982's post-response close linger budget landed after the #2037 knob
migration and stayed env-only (server.ts read process.env directly),
violating the #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.
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-04_config-docs-server-settings (6af149f)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2142-pr.2064.2bc71b2

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-pr2064.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] 🏷 已独立 review PR #2064(拉分支核对代码 + 本地定向验证 + A/B 回归钉住 + CI 状态),非复述作者自报,以下结论均附证据。

① 方向关(原 issue #2062):方向正确、打到根因。手册 §Server Settings 落后于 src/config.ts 配置面是真实缺陷(我独立 diff FileConfig 顶层字段 vs KNOWN_TOP_LEVEL_KEYS 确认漂移属实);同一失败域里三个独立漂移源(增量落地未回填 / linger 漏迁 knobs / 白名单落后)分层清晰,合并为一个 checklist 处理合理,未把症状当病因。

② 回归审查(逐项既有行为):

  • linger env 语义(最高危,逐字节核验):读 src/knobs.ts:41 tInt 源码——门控是 envRaw !== undefined(不是 !== ""),故 set-but-empty/garbage env 仍走 parseInt→NaN→default,不查文件层,与旧 Number.parseInt(env ?? "") 十种取值情形逐一比对全部一致。唯一 delta = 预期内的 file 层增量(env 未设 + file 有值 → 现读 file)。默认 5000 不变。无回归。作者正确选了严格 tInt 而非松散 tIntLoose,这点是关键且做对了。
  • graceful-close 子进程 env pin:迁移后 env 仍优先,测试 1/1 绿。
  • unknown-key 告警:4 个本就生效的键不再误报(披露行为变更fix: address all code review findings (condense, routing, session-id, dead code) #2,功能行为不变)。已验证这 4 键确实被消费(config.ts:1156/1158/1139、knobs.ts:262)。
  • 其余纯文档增量,无阈值/时序/输出格式漂移。无回归。

③ 代码审查:两个 code commit 小而收敛。KNOWN_TOP_LEVEL_KEYS 补 4 键——我独立 AST 抽取确认修复后 FileConfig 48 字段 == KNOWN 48 项,零缺失零多余(非仅靠测试字段列表)。postResponseLingerMs 迁入 network 块走 knobs,3 处调用点干净替换为 knobPostResponseLingerMs(),无残留直读 process.env。

④ 测试有效性(真测试,有牙):本地实跑 knobs 9/9、issue1815 4/4、graceful-close 1/1;typecheck exit 0。A/B 钉住:临时撤掉 fix commit 的 4 键,issue1815 full-surface 用例即挂于 ignoring unknown ... : releaseNotesCheck, releaseNotesUrl, imageTokenCap, plugin——证明该回归测试真能抓住再漂移,非恒真断言。

⑤ diff 整洁度:7 文件 +389/-33,base = 当前 master(3a7308ab,fresh 无 stale-base)。每行都与本 PR 目的相关;顺手小修(死链锚点 -1660)独立标注,非噪音。文档默认值抽查(maskHosts/subagentSplit/resumeInheritance 默认开,forkAdoption/chainContentDetection/chainEgressStamp/stableSystemAnchor 默认关,linger 5000)与 loadOptions 解析逻辑逐项一致,无误述。

结构化七问

  1. 是什么问题:手册 Server Settings 落后于代码配置面,一批可读可写顶层键无条目,下游文档系统性漏键、用户无从知晓存在与默认值。
  2. 什么原因导致:三个同源漂移叠加——(a) 各功能 PR 只更 README/env 表未回填手册;(b) 建议:客户端侧连接请优雅关闭(close_notify+FIN),避免向下游客户端发出 RST #1982 linger 落在 feat: resolve behavior knobs as env > config file > default via src/knobs.ts (#2030) #2037 knobs 迁移之后漏迁,一直 env-only,违反 彻底整治环境变了滥用,除非必要都走配置文件 #2030「每个开关有文件键」纪律;(c) KNOWN_TOP_LEVEL_KEYS 白名单落后 FileConfig 接口。
  3. 怎么修复:文档 en+zh 补齐全部缺条目(语义按 loadOptions 取证);linger 按 issue 点名形状迁入 network 块走 knobs(env>file>default,严格 tInt 字节级保留旧解析);白名单补 4 键并扩展测试钉住全字段面防再漂移。
  4. 是否回归:无。见②逐项——linger env 语义经十情形比对字节级不变,仅新增 file 层;告警输出变化属披露的有意变更;无其他语义/阈值/时序/格式漂移。
  5. 是否破坏缓存:不涉及(未触碰会话状态/压缩/去重键)。
  6. 是否改设计方向:不涉及。仅一处面增量,沿用既有进程级块模式。
  7. 是否引入新配置:是——network.postResponseLingerMs(number,默认 5000,env BILI_POST_RESPONSE_LINGER_MS 优先)。纯增量、无迁移;PR 含 config surface 强制节。

CI 与判定

CI 5/6 绿(PR Build Artifact / E2E real codex / e2e-fake-codex / ci-image / e2e-native-pi 均 success),主 CI 全量套件 in_progress。本地 typecheck+定向测试已过。

判定:主 CI 套件转绿后即可合。 两个 code commit 小、收敛、有牙测试钉住且 A/B 证明必要且充分;docs commit 纯增量、默认值准确。注:本 PR 触及配置面(新增 config 字段)且含 feat: commit,按 §7.4 auto-merge gate 不满足自动合并条件,需人工合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

冲突

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 冲突已解决并推送到分支(45a3fdd9..6af149f2),PR 恢复可合并状态,新 head 的 CI 全部在跑。

七问

  1. 是什么问题:PR 分支与最新 master 冲突(mergeable_state: dirty),无法合并。
  2. 什么原因导致的:PR 基线 3a7308ab 之后 master 推进到 d8d1f8a0(支持分支合并到master后发布tag master的npm包,参考pr 的tag #2049 master tag 发布、[site] /docs/ 配置文档不全:以 CONFIGURATION.md 为基准做完整核对与补齐 #2052 website docs 等 16 个提交)。其中只有 支持分支合并到master后发布tag master的npm包,参考pr 的tag #2049 的文档改动与本 PR 重叠:master 给两版手册 env 表的 ACP_UPDATE_TAG 行追加了滚动 master tag 一句(支持分支合并到master后发布tag master的npm包,参考pr 的tag #2049),而本 PR 恰好在同一表格区域插入新行(ACP_AUTO_RESTART_ON_UPDATE 等)——纯文本位置重叠。源码/测试文件在 master 侧零改动,无代码冲突;全仓仅两个文件各一个 hunk 冲突。
  3. 怎么修复的:按仓库惯例把 master 合入分支(merge commit,非 rebase、非 force-push)。唯一冲突 hunk 用 union 解法——两侧互为超集:保留 PR 的 ACP_AUTO_RESTART_ON_UPDATE 新行与 ACP_AUTO_UPDATE 行的 "File-config key: autoUpdate" 标注,同时保留 master 的 支持分支合并到master后发布tag master的npm包,参考pr 的tag #2049 master tag 句子。零语义取舍,无任何代码改动。
  4. 是否有回归问题:无。零丢失已双向验证:merged tree vs origin/master 的 diff = 原 PR 的 7 文件 +389/-33(逐字节一致);vs PR head 的 diff = 恰好只有 master 那 2 行文档变更。无残留冲突标记。typecheck 干净;定向测试 14/14(knobs-config-precedence 9、issue1815-unknown-top-level-keys 4、graceful-close 1)本地通过,全量回归交 CI。
  5. 是否破坏缓存:不涉及(纯文档冲突解决,无运行时路径变化)。
  6. 是否改了设计方向:不涉及。
  7. 是否引入了新的配置:无新增——PR 已披露的 network.postResponseLingerMs(默认 5000,env twin BILI_POST_RESPONSE_LINGER_MS)保持不变。

判定:冲突已消除,PR diff 对 master 仍保持原 7 文件范围(GitHub 按 merge-base 计算,diff 整洁度不受 merge commit 影响)。新 head 6af149f2 上 8 个 CI job 已启动(in_progress/queued);CI 转绿后即可人工合并(§7.4 自动合并不适用:触碰 config surface + 含 feat 提交)。我稍后跟进 CI 结果。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 全绿,PR 已就绪可合并。

新 head 6af149f2 上 10/10 job 全部 success:CI(typecheck + 全量测试 + build)、E2E real codex、e2e-fake-codex、ci-image、e2e-local-registry、e2e-native-{dsh,pi,opencode}、PR Build Artifact、Windows codex overlay。

PR 状态:mergeable: True,mergeStateStatus: clean。

收工判定:冲突解决后的分支与原 PR 内容逐字节等价(union 解法零语义取舍,双向 diff 已验证),加上此前 review 的全部结论(tInt 严格语义保留、KNOWN_TOP_LEVEL_KEYS 48/48 完整面、A/B 测试咬合)在新基线上依然成立——可以合并。按 §7.4 需人工合并(触碰 config surface + 含 feat 提交,自动合并不适用):#2064

@ranxianglei
ranxianglei merged commit dda1689 into master Oct 4, 2026
16 checks passed
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.9-master.dda1689 (rolling master tag).

npm install -g billion-context@0.0.9-master.dda1689  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

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.

[docs] CONFIGURATION.md §Server Settings 落后于 src/config.ts 配置面(autoUpdate 族等 16 键无条目)

1 participant