[PR] refactor(server): name the window-reservation block in handleRequest by yanhuojiyusheng · Pull Request #4902 · ranxianglei/billion-context

yanhuojiyusheng · 2026-10-27T02:28:11Z

现象

src/server/handle.ts 的 handleRequest() 是一个 2545 行的单函数（全文件 2801 行，纯注释 47.6%、空行 8 个）。它内部有 8 个语义阶段，边界只存在于横幅注释里，代码里没有任何东西给它们命名。读到 2100 行时必须记住 1000 行算出的 sideRequestLike、1373 行才拿到的 session、1916 行被就地改写的 parsed。

其中最贵的是窗口预算那段：它在 6 层 native window 解析之上再叠 5 条相互牵制的规则（#896 预留上限、#282 fallback 地板、#4205 anthropic 豁免、#3450/#3973 实测 share 夹紧、#2096 clamp 口径），正确性全靠代码顺序维持，且此前只能通过 server fixture 间接覆盖。

方案

把该段原样搬进同文件的 reserveJudgingWindow()：15 个横切值从闭包捕获变成具名入参，返回收紧后的 Config，调用点 167 行 → 19 行。另补 30 个空行恢复段落结构（原文件 0.3%，同仓库 server.ts 2.7% / crush.ts 5.6%）。新增 tests/reserve-judging-window.test.ts 直接钉分支矩阵。

handleRequest() 2545 → 2462 行。

不采用

其余 7 段不做同样抽取。 实测：E 段（车道判决）内部有 return 并改写 parsed；A/B 段产物是一串 let 且 6 个出口各自 return；F 段本身是可重入闭包。都不是干净边界，硬抽会动控制流。
不引入 per-request ctx。 那才是真解耦方向（本段 141 行依赖 17 个外层局部值，说明耦合是真的、不是排版问题），但等于重写这个文件，与本次目的不符。代码注释里已写明：本次抽取不解耦，只把耦合面显性化 + 可测。
零行为变更：不新增 config 字段 / env var，无 wire 报文变化，无持久化格式变化，不碰 kernel/。

范围

文件	变化
`src/server/handle.ts`	+250 / −166（30 行空行；139 行搬移块；15 行具名入参；19 行调用点）
`tests/reserve-judging-window.test.ts`	新增 12 条

审阅提示：416 行 diff 里 139 行是原样搬移，去缩进后可逐行对照 master；真正需要看的是 15 个入参的型别（protocol: WireProtocol 非空、headroomOrigin: string | undefined）。

已验证（本地，rebase 后 head）

139 行搬移块 vs master，去缩进逐行比对   完全一致
tsc --noEmit                            exit 0
npm run build                           exit 0（dist-import-annotations OK / dist-external OK）
新单测                                    12/12  (1.9s)
既有 headroom 端到端回归（5 文件）         18/18
check-unused-exports.mjs                clean (6 waived)
check-test-import-graph.mjs             ok

负控制：把 headroomCap 换成 1 → 3 条精确变红；把 if (nativeFromFallback && reserved < FLOOR) 改成 if (nativeFromFallback) → 首次未红，暴露测试缺口，补第 12 条后仅它变红。两者均已回滚并复检。

未跑：全量 CI（按 §7.2 以远端 CI 为准）；未做「改动前后各 build 一次对比警告集」的对照实验。

风险

热文件冲突：416 行落在 handle.ts，按 §7.5 这是二次返工第一驱动，且不在代码层面可控。
新单测未覆盖四个 fallback 层级（runtime-info / launcher / configured / registry）的正向路径——本次安全性由逐行搬移保证，但这四条路径将来只靠 e2e 兜底。
reserveJudgingWindow 成为模块导出，扩大了可 import 面（为让单测直接钉住矩阵而付的代价）。

ranxianglei · 2026-10-27T03:08:17Z

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Merge-guard sync attempted and verified, but blocked at push.

Merged current master (e4cc68575) into the PR head (e3b361388) → clean auto-merge, no conflicts. The only shared file (src/server/handle.ts) had non-overlapping changes (master's compressionProxy demotion vs. this PR's window-reservation block naming); both survive intact.
Verified locally on the merged tree: typecheck ✅, build ✅, tests/reserve-judging-window.test.ts 12/12 ✅.

Blocker: the resulting merge commit could not be pushed. The automation account has pull-only access to the source fork (permissions.push = false), so git push to the PR branch was rejected with permission denied. There is no GitHub-side path to push a fork branch from outside the fork.

Net effect: the PR still shows as behind. To clear it, either the author rebases this branch onto latest master, or the fork grants the maintainer push access so the already-prepared sync can land. No code was changed beyond the clean merge of master.

…anxianglei#4901) Extract the output-headroom reservation out of handleRequest() verbatim: the 15 cross-cutting values it captured from the closure become named inputs, the call site drops from 167 lines to 19, and the block returns a tightened Config. No logic changed. The moved block is identical to master's apart from indentation: 139 non-blank lines compare equal line by line. The two values it used to compute inline (nativeWindow, headroomOrigin) are now arguments; the only other edit is 30 blank lines, which restore the paragraph structure of a 2801-line file that had 8 blank lines in it. tests/reserve-judging-window.test.ts pins the branch matrix directly - ranxianglei#896 cap vs max_tokens, ranxianglei#282 floor up and not-down, ranxianglei#4205 exemption both ways, ranxianglei#3450/ranxianglei#3973 proven share both ways, ranxianglei#2283 stamp both ways - in 1.9s where the same paths previously needed six server fixtures. Closes ranxianglei#4901

ranxianglei · 2026-10-27T03:48:53Z

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重：不重复。 本 PR 实现自己的 #4901（可读性抽取提案），无其他在途条目做同一抽取。热文件核查：本地拉取全部 2644 个 refs/pull 头，与抽取区间（master src/server/handle.ts L2174–2341）逐 hunk 比对——#3973、#4510 有重叠 hunk 但均已 closed/merged（内容已在 master，陈旧分支）；唯一开放且重叠的是 #4138（见「协调提示」）。

标签判定： scope/wiring + p3（纯可读性重构、请求管道域、零行为变更、无用户影响）。镜像的 label API 返回 "endpoint not implemented in ework shim"，无法经 API 写标签，在此报备判定。

审核结论先行：建议合并。 独立复核了全部关键声明，零行为变更成立，远端 CI 在推送头全绿。一条协调提示：开放 PR #4138 在同一抽取区间内加一行展示性元数据写入，建议明确合入顺序。

结构化八问

是什么问题：handleRequest() 是 2545 行单函数，窗口预算段在 6 层窗口解析之上叠 5 条相互牵制的规则（output headroom 目前仍按 max_tokens 全额预留，是否应改为最大输出的 1/4 / 支持配置比例？ #896 预留上限、bili出现连续压缩情况 #282 fallback 地板、"Output reservation extended to all wires" (#4184) landed without test coverage: widespread red on master is blocking th | 「输出预留扩到所有 wire」(#4184) 落地没带测试面: master 大面积红卡住 v0.1.204 发版 (已 revert, 重做要求见内) #4205 anthropic 豁免、[Bug][dsh native] preflight fold target sits ABOVE the engine's own denominator (1048576 vs 1000000) and the upstream-stated window from a 400 never feeds it — 'deficit 0' forwards an over-window payload → context_length_exceeded kills the turn #3450/[PR] fix(headroom): remember the proven completion share so the anthropic lane stops re-overflowing #3973 实测 share 夹紧、clampOutgoingOutput sizes max_tokens against the raw native window while preflight enforces the reserve-adjusted one — up to 25% of slack the clamp never sees #2096 clamp 口径），边界只存在于横幅注释里，正确性全靠代码顺序维持，此前只能经 server fixture 间接覆盖。本 PR 给该段命名并可直接单测。
什么原因导致的：历史累积——每条规则都是过去某次缺陷修复的补丁，无人做过结构整理。是维护性债务，不是缺陷。
影响范围与严重程度：零行为变更（已验证：文件清单仅 src/server/handle.ts + 新测试文件；config-surface-guard / kernel-guard / version-guard 全绿；无 config/env/wire/持久化变化）。用户面完全不受影响，收益为可维护性与可测性。
怎么修复的：将该段原样抽成模块级 reserveJudgingWindow()，15 个闭包捕获值变具名入参，返回收紧后的 Config。明确不做的事同样正确：其余 7 段控制流边界不干净不硬抽；不引入 per-request ctx（等于重写文件）。注释如实写明「不解耦，只把耦合面显性化」。
是否有回归问题（既有行为逐项清点）：
- 机械验证：difflib 对 master 实际 git blob 去空白逐行比对——搬移块除两处已披露的变量来源变更（nativeWindow/headroomOrigin 上提到调用点，表达式未变、normalizeUpstreamOrigin 为纯函数）外逐字节一致，另加 28 行脚手架（签名/解构/let）。作者「去缩进逐行比对完全一致」声明成立。
- 类型收窄：本地独立跑 tsc --noEmit exit 0——protocol: WireProtocol 非空型在调用点成立；日志里残留的 protocol ?? "unknown" 是 master 原样搬运，类型上不可达但无害，保留它正是「原样搬移」可审计性的代价，不计为缺陷。
- 定向测试：新 12/12 + 既有 headroom 回归 5 文件 18/18 = 本地 30/30 通过。
- 远端 CI（推送头 e3b3613）：test 全 lane（ubuntu/windows × node 22/24 分片）全绿 + static-gates / kernel-guard / unused-exports / test-import-graph / version-guard / config-surface-guard / docs-sync / gate / build-artifact 全绿；e2e lane 按设计 gated skip。
- 触碰路径的既有行为清单：output headroom 目前仍按 max_tokens 全额预留，是否应改为最大输出的 1/4 / 支持配置比例？ #896 预留上限、bili出现连续压缩情况 #282 fallback 地板（只抬不压）、"Output reservation extended to all wires" (#4184) landed without test coverage: widespread red on master is blocking th | 「输出预留扩到所有 wire」(#4184) 落地没带测试面: master 大面积红卡住 v0.1.204 发版 (已 revert, 重做要求见内) #4205 anthropic 豁免、[Bug][dsh native] preflight fold target sits ABOVE the engine's own denominator (1048576 vs 1000000) and the upstream-stated window from a 400 never feeds it — 'deficit 0' forwards an over-window payload → context_length_exceeded kills the turn #3450+[PR] fix(headroom): remember the proven completion share so the anthropic lane stops re-overflowing #3973 实测 share 夹紧与优先级、clampOutgoingOutput sizes max_tokens against the raw native window while preflight enforces the reserve-adjusted one — up to 25% of slack the clamp never sees #2096 clamp 口径、[可观测性] 计量/窗口/对账决策的可审计性缺口：窗口翻转时间序列、逐请求 usage-vs-est 成对记录、回滚 token 体量（#2274） #2283 lastWindowResolution 元数据戳、fallback 层级顺序——全部保持（字节级搬移 + 分支矩阵被新测试钉住）。
- base 之后 master 侧唯一触碰 handle.ts 的提交 d572657（[hermes] After tool_search defers plugin tools, the entire plugin identity/budget package is lost: /acp always reports " | [hermes] tool_search 延迟插件工具后，插件身份/预算整包丢失：/acp 永远报 "No model request yet"，窗口回落 200K #4855 hermes pluginMode）在不同区域，无语义交互；GitHub auto-merge 干净。
是否破坏缓存：不涉及（不动缓存/重试/增量游标/去重键；窗口取值计算结果逐位相同）。
是否改了设计方向：没有。刻意不引入 ctx 对象（真解耦方向已留注释给后续）。唯一方向性后果：reserveJudgingWindow 成为模块导出、import 面扩大——作者已披露，是为单测直接钉矩阵付的成本。
是否引入了新的配置：无（无新 env/config/默认值）。

测试有效性

12 条断言全部是精确值断言（不是「不崩」），且每条规则正负双向（#3617 纪律）：#896 cap 绑定 vs max_tokens 低于 cap；#282 地板抬升 vs 权威窗口不抬 vs 只抬不压；#4205 豁免 vs anthropic wire 无独立墙证据时仍预留；#3450 实测 share 压过豁免 vs 模型不符不压过；#2283 有戳 vs 豁免路径无戳。issue 记录了两个负控制（headroomCap→1 恰好 3 条红；放宽地板条件首次未红 → 暴露缺口 → 补第 12 条后仅它红），方法可信。已知缺口（作者已披露）：四个 fallback 层级（runtime-info/launcher/configured/registry）的正向路径未被单测覆盖，本次安全性由逐行搬移保证，长期靠 e2e 兜底。

Diff 整洁度

handle.ts 416 行 = 139 原样搬移 + 30 空行（已披露，段落结构对齐仓库惯例 0.3%→约 1%）+ 15 参数声明 + 19 调用点 + 注释，每一行都与目的相关。30 空行属披露过的 cosmetic 变更，可接受。

协调提示（§7.5 热文件）

开放 PR #4138（#4130「annotate the output-headroom effective window on every denominator surface」）在 master L2194–2199——本抽取区间之内——加 session.metadata.outputHeadroomBase = nativeWindow（展示性元数据）。两种顺序都不冲突语义（展示写入 vs 纯搬移）：#4902 先合 → #4138 的单 hunk rebase 时挪进新函数即可（nativeWindow/reqConfig 在新函数内均在作用域，适配成本极低）；#4138 先合 → #4902 的「原样搬移」基线移动，需重做一次逐行比对。建议二选一协调，不必阻塞本 PR。

收工判定

可合入（人工合并）。纯 refactor 按 §7.4 第 5 条（须 pure fix:）不走 auto-merge，需人拍板；CI 在当前头已全绿，behind(5) 由 merge-guard 系统流程收敛。

ranxianglei · 2026-10-27T04:55:17Z

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Update — no sync needed from me: the author already rebased the branch onto latest master, so head 5a94be18d now sits directly on e4cc68575 (the current master tip) and the behind flag has cleared on its own. All 51 CI checks on the new head are green (37 pass / 14 skip, none failing or pending). The mergeable_state badge currently reads blocked solely from GitHub's transient post-force-push re-evaluation — nothing is actually failing. This supersedes my previous note.

ranxianglei · 2026-10-30T17:32:59Z

(ai: vllm-qwen/qwen3.8-27b)

Hi @yanhuojiyusheng, thanks for the readability refactor! One heads-up: this PR is currently ~353 commits behind master (master has moved on since Oct 27). We verified that merging the latest master into your branch is completely clean (zero conflicts), so a rebase/pull of master should be straightforward. Our automation account does not have push access to your fork, so we cannot sync it from our side — could you pull master into your branch yourself? Once CI is green we'll merge it right away. Thanks!

ranxianglei · 2026-10-31T04:43:05Z

🤖 Powered by ework · qwen3.8-27b