Skip to content

feat: compat.dropFields — per-provider deletion of client-fixed fields (SenseNova strict-schema 400) - #1858

Merged
ranxianglei merged 2 commits into
masterfrom
wt-1757-ework-daemon
Oct 1, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
wt-1757-ework-daemon

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Adds compat.dropFields: string[] (global + per-provider) — opt-in deletion of client-sent fields from the final forwarded body, for strict-schema upstreams that reject a field the client always sends but the upstream does not accept (#1757).

Repro anchor: SenseNova's OpenAI-Responses-compatible gateway (https://token.sensenova.cn/v1/responses) returns 400 json: unknown field "summary" on pi-ai's fixed reasoning: { effort, summary: "auto" }; every other pi-ai outbound field measured 200 in the issue's per-field curl matrix.

Design (owner-decided shape A, sign-off in issue)

  • Dot-path plain-object paths only (reasoning.summary); no wildcards, no array indices; malformed entries dropped at parse time.
  • Merge = global ∪ per-provider additive union (provider can add paths, never retract a global one) — unlike compat.roles' per-key override.
  • Structural key deletion on parsed JSON only — string values are never inspected or altered, so tool-call arguments / message content stay byte-exact (§7.3 wire fidelity).
  • Byte-for-byte when unconfigured or nothing matches (original string identity preserved, no re-stringify); ≥1 actual drop ⇒ re-serialize + info log listing dropped paths.
  • No learn-on-failure auto-drop in v1 (field deletion is not a bounded value domain like role mapping).

Application points — drops sit at the outbound forward boundary, so both compression modes are covered:

New module src/compat-drop.ts (parse/resolve/drop helpers); config plumbing in src/config.ts mirrors compat.roles (FileConfig → resolved ProxyOptions + ProviderRoute).

Config surface (AGENTS.md discipline)

Behavior change flag

None. Inert unless configured; the unconfigured path preserves original string identity (no re-stringify), protecting the #661 byte-fingerprint contract. No thresholds/timing/output-format drift anywhere else in the diff.

Wire-contract ledger (#1304)

WC-011 added to WIRE_RULES (provenance: #1757, 2026-09-30 per-field measurement): responses wire must not carry reasoning.summary; the validation-parity fake enforces it with its native 400 envelope. Gate tests pin both sides: unconfigured bili forwards untouched (fake 400s, WC-011 violation recorded, field byte-for-byte on the wire) and configured bili strips before forward (200, zero violations, sibling reasoning.effort survives).

Docs

CONFIGURATION.md + CONFIGURATION.zh-CN.md: global and per-provider compat sections document dropFields (semantics, merge rule, string-leaf safety, canonical SenseNova example from the issue).

Pre-flight

  • npm run typecheck — clean
  • tests/compat-drop.test.ts — 11/11 (units for all four exports + e2e A–E through a real proxy instance: processed responses path, verbatim fallback, default transparency, additive merge, string-leaf fidelity)
  • tests/wire-contract.test.ts — 13/13 incl. new WC-011 negative/positive gates + ledger self-check
  • npm run build — clean (acp-kernel inlined)
  • Full regression + e2e-codex left to CI (local-testing discipline); this diff touches src/server.ts, so the e2e workflow auto-triggers.

Fixes #1757

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始审查 PR #1858(commit 771e7ead,单提交)。按 PR Review 规范走:原 issue 方向核对 → 回归审查 → 代码审查 → 测试有效性 → diff 整洁度 + CI 状态。结论稍后按结构化七问给出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1858 审查完成。结论先行:代码质量 PASS,但现状不可合并——分支落后 live master 237 个提交,与当前 master 存在 3 处文本冲突 + 1 处语义碰撞(wire-rule 编号撞号),需 rebase 后才能合并。细节如下。

结构化七问

1. 是什么问题:SenseNova 的 Responses 网关(token.sensenova.cn/v1/responses)做严格 schema 校验,对 pi-ai 固定发送的 reasoning: { effort, summary: "auto" } 返回 400 json: unknown field "summary";逐字段实测其余 pi-ai outbound 字段全部 200(#1757)。本 PR 增加 opt-in compat.dropFields,允许按 provider 在转发前删除这类客户端固定字段。

2. 什么原因导致的:客户端 wire 形态与严格上游不匹配——pi-ai 发送的 reasoning.summary 不属于 OpenAI Responses API(仅 reasoning.effort 有文档)。不是 bili 的 bug;bili 的职责是提供透明的逃生口且不打扰默认行为。

3. 怎么修复的:新增 src/compat-drop.ts——dot-path(仅 plain-object 段,无通配符/数组下标,畸形条目解析期逐个丢弃)的结构化删除:

4. 是否有回归问题:默认行为不变,由测试钉死(e2e C「未配置 ⇒ 字段原样到达上游」+ WC 负控「未配置 ⇒ byte-for-byte 转发、上游 400 原样 relay」)。但热文件竞争导致必须 rebase,这是本次审查的核心发现:

  • 分支基点 8d3d1bfc 落后 live master bcef839d 237 个提交。本地 merge-tree 实测:3 个文件冲突
  • 边界缺口(披露,非阻断):codex compaction_trigger 非拦截直通(server.ts:2627)返回 Buffer,既不走预 scrub 也不走 string-body 边界 → 该路径 dropFields 不生效。这与 compat.roles / output-steering 的既有行为完全一致(同一 string-body 门),非本 PR 引入;属边界中的边界(codex UA + compaction item + 非拦截模式 + 严格网关四条件叠加)。
  • 小测试缺口:retry 路径(wireTransform 带删除)仅经代码审查确认,无专门 e2e(需要触发 compression+retry)。
  • 已逐项核过的既有行为:forward() 全部 6 个调用点(主处理路径 + 5 条 verbatim 分支)各自只应用一次删除,无双重应用(nop 幂等);buildForwardTarget 抽取为 forwardUpstreamUrl 逻辑等价;config 解析对未配置用户零变化(空对象不赋值,行为保持);master 侧 route.compat 形状未变,与本 PR 扩展无语义冲突。

5. 是否破坏缓存:否。prompt-cache stamp 在删除之后执行,digest 基于删后字节计算——同一 provider 配置下确定性输出;未配置会话字节级不变(prefix cache 不受影响);缓存/重试/增量游标/去重键策略均未触碰。

6. 是否改了设计方向:否。沿用现有 compat 块设计(镜像 compat.roles 的管道),#1757 线程中 owner 拍板的 shape A;v1 明确排除 learn-on-failure 自动删除;无架构/边界/数据流转向。

7. 是否引入了新的配置:是——compat.dropFields?: string[](全局块 + per-provider providers.<url>.compat.dropFields)。纯增量、默认关闭/缺省、无迁移;CONFIGURATION.md en/zh 已同步;PR 正文含 config-surface 章节(理由 + 为何现有面无法表达 + 置于 compat 块内,规避 #1437 式旁路)。

Wire-contract ledger(#1304 纪律)

合规:WC 条目含 provenance(#1757 逐字段实测日期/网关)、fake 强制器注册(responses: validateResponsesBody)、自检语料新 probe(反恒真)、负控+正控双闸。唯一问题是上面的编号撞号 → 改名 WC-013 即可(共 9 处引用:fakes.ts 4 处[WIRE_RULES 条目、doc 注释、子句注释、违规消息],test.ts 5 行[区段注释、2 个测试名、断言])。

CI 状态

  • 该 head sha 771e7ead 从未有任何 workflow 运行(head 与 branch 维度均查过,0 runs)——同日兄弟分支(2026-10-02_dsh-autoreview-side)全套绿。即此 PR 目前没有任何 CI 证据。
  • GitHub mergeable_state: unknown(与冲突一致)。

判定

代码:PASS。可合并性:blocked,需 rebase。rebase 要求:① 三个 union 解法(见上);② WC-011 → WC-013 全量改名;③ push 后等新 CI(diff 触及 src/server.ts,e2e 会自动触发)。

按协议我未动分支。owner 回复「继续」我就执行 rebase(union 解法 + WC-013 改名)并推送,然后回报 CI 结果。

@ranxianglei

Copy link
Copy Markdown
Owner Author

解决冲突后重新审核

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。开始执行:rebase 到 live master(815027fc,审查期间又前进了几个提交)+ 三处 union 解法 + WC-011→WC-013 改名(改名范围以实际 rebase 结果为准——master 新进的提交若再占编号会继续顺延)。完成后推分支、等 CI、再按七问重新审核并回报。

…s for strict-schema upstreams (#1757)

Opt-in dot-path field deletion on the final forwarded body: global and per-provider lists merge additively, structural key deletion only (string values untouched), byte-for-byte when nothing matches. Applied after roles/steering before the prompt-cache stamp, wired into wireTransform for compress retries, and chained after scrubAnthropicPck on all verbatim passthrough branches. WC-011 added to the wire-contract ledger with negative/positive gate tests. CONFIGURATION.md en/zh document the key with the canonical SenseNova example.
@ranxianglei
ranxianglei force-pushed the wt-1757-ework-daemon branch from 771e7ea to aedd29c Compare October 1, 2026 12:33
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: wt-1757-ework-daemon (41958d5)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1856-pr.1858.da94d23

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-pr1858.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] 🏷 已按指示完成 rebase(解决冲突)并重新审核。结论:代码 PASS,可合并 —— 仅剩主 CI 的全量测试矩阵还在跑(详见下方 CI 节),收尾后补一条确认。

Rebase 与冲突处置

  • 分支已 rebase 到当时最新 master(815027fc)并 force-push:head 771e7ead → aedd29ce,单一线性提交,8 文件 +596/-29,改动范围不变。
  • 三处冲突全部按并集解决,无内容丢弃:
    1. src/server.ts(标题生成等侧请求污染主会话状态:prepareAnthropic 缺 isTitleGen 守卫、快照无条件覆盖、survivedCount 每请求空转 #388 side-request 区):保留 master 新增的 requestAgent 日志 + replaceBiliCompactionItems 归一化,scrubCompatDrop 追加在归一化之后——顺序关键:归一化可能重新 stringify,drop 必须在其后执行才不会被冲掉。
    2. tests/wire-contract-fakes.ts:语义级冲突——master 已通过 Responses 历史压缩后产生连续 configuration_update,导致上游返回 HTTP 400 #1733 占用 WC-011(configuration_update 相邻禁令)与 WC-012(compaction id 前缀),自动合并会静默产生重复 id。本 PR 的新规则改号为 WC-013(reasoning.summary 非 OpenAI Responses 字段),仍置于 tools 早退之前(无 tools 的 body 也要被校验)。
    3. tests/wire-contract.test.ts:ledger 自检语料两条探针并存;本文件内 WC-011 引用全部改号 WC-013(master 侧引用不受影响)。
  • 顺带说明:原 head(771e7ead)自 PR 创建起从未触发任何 workflow run(同期其他分支均正常);rebase 推送后 9 个 workflow 全部立即触发。第一轮 review 因此没有 CI 数据可引。

本地定向验证(全量回归交给 CI)

  • npm run typecheck clean
  • 定向测试 31/31 通过:tests/compat-drop.test.ts(11)、tests/wire-contract.test.ts(含 WC-013 正/负向门 + ledger 自检)、tests/issue1733-config-update.test.ts(master 侧 WC-011 回归,确认改号无误伤)

CI(新 head aedd29ce)

七问(本轮复审)

  1. 是什么问题:SenseNova OpenAI-Responses 网关严格 schema,对 pi-ai 固定外发的 reasoning.summary 返回 400 json: unknown field "summary"(compat.dropFields:按 provider 删除客户端固定发送的字段(SenseNova Responses 严格 schema 400) #1757)。
  2. 什么原因导致的:客户端固定字段与上游 schema 不匹配——不是 bili 的 bug,是 wire 兼容缺口,缺一个按 provider 显式删字段的逃生口。
  3. 怎么修复的:compat.dropFields(全局 ∪ per-provider 加性合并);dot-path 结构化删除只作用于解析后 JSON 的普通对象路径,字符串叶子永不触碰(tool-call args / 消息内容逐字节保真);forward() 字符串 body 边界应用(roles/output-steering 之后、[design] chain checkpoint step 3: carrier stamp shape on role-alternation-strict wires (anthropic/google) #1421 prompt-cache stamp 之前),5 条 verbatim 分支在既有 scrubAnthropicPck 之后预 scrub,wireTransform 使压缩重试同样携带删除;未配置/零命中时保持原始字符串同一性(不重新 stringify),字节级透明。
  4. 是否有回归:默认关闭,未配置路径字节不变(e2e C + WC-013 负向控制钉住);改号 WC-011→WC-013 不动 master 已有条款(issue1733 回归通过)。上轮披露的边缘缺口维持不变:codex compaction_trigger 非拦截直通路径(src/server.ts:2627 Buffer 返回)不经过 drop——与 roles/steering 的既有行为完全一致(同在 string-body gate 之外),edge-of-edge,不构成阻塞。
  5. 是否破坏缓存:否——stamp 在 drop 之后计算,digest 覆盖删后字节且确定性不变。
  6. 是否改了设计方向:否——沿用 owner 拍板的 shape A,落在既有 compat 块内(feat: opt-in for non-http(s) baseUrl providers to ride bili (#1392) #1437 教训案例合规,config surface 章节齐备)。
  7. 是否引入新配置:compat.dropFields?: string[](全局 compat 块 + providers.<url>.compat),opt-in、默认空、无迁移;CONFIGURATION.md 中英同步。

判定

可合并。mergeable=True,state=behind:复审期间 master 又并入 #1863(loop 修复,与本 PR 零文件重叠,merge-tree 干净),落后一个提交不阻塞合并按钮。等主 CI 全量矩阵转绿即收工。

Every server constructed without a compat block (all hand-built test opts,
any embedder passing minimal options) crashed per request with
'TypeError: Cannot read properties of undefined (reading dropFields)'
at server.ts:1495/:5528, hanging the full test matrix in CI for 40+ min.
Matches the existing optional-chaining style of the roles call site (:5491
opts.compat?.roles). resolveCompatDropFields already tolerates undefined.
@ranxianglei

Copy link
Copy Markdown
Owner Author

修了 test-matrix 挂起:两处 opts.compat.dropFields(server.ts:1495 handle / :5528 forward)在 server opts 不带 compat 块时每请求抛 TypeError: Cannot read properties of undefined (reading 'dropFields'),348 个用例连带失败/长超时,CI 卡 40+ 分钟。改为可选链 opts.compat?.dropFields(与既有 :5491 opts.compat?.roles 同风格;resolveCompatDropFields 本身容忍 undefined),提交 41958d5。本地全量 3555 tests / 3536 pass / 0 fail / 19 skipped,CI 13/13 绿。旧的卡死 run 已取消。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已独立验证 41958d52(可选链修复),全部通过。PR 收工判定:可合并。

对修复的独立核验

  • diff 审阅:两处调用点(src/server.ts:1495 handle / :5528 forward)均改为 opts.compat?.dropFields,与既有 :5491 的 opts.compat?.roles 同风格;resolveCompatDropFields 本身容忍 undefined,语义闭合。
  • 完整性审计:全仓 grep 确认本 PR 引入的 dropFields 访问点只有这两处,无遗漏;其他文件无同类裸访问。
  • 本地定向验证(新 head):typecheck clean;tests/compat-drop.test.ts 全过;merge-tree vs 当前 master 干净(mergeable=True,behind 不阻塞)。
  • CI(经 API 逐条核对,非转述):新 head 41958d52aa 上 9/9 workflow 全绿,含主 CI 全量矩阵——与你的「13/13」一致。

根因分层确认(与你的诊断一致)

  • 直接原因:server opts 不经 loadOptions 构造(测试 harness / 手工 opts)时缺 compat 块 → 每请求 TypeError → 348 个用例级联失败/长超时 → 主 CI 挂起 40+ 分钟。
  • 类型层为何没拦住:ProxyOptions.compat 声明为可选(config.ts:60),但 loadOptions 总赋值(config.ts:1052),TS 控制流窄化让裸访问通过了 typecheck——类型「看起来有」≠ 运行时一定有。可选链是正确且最小的修法。

诚实复盘(我的 review 缺口)

这个缺陷是我前两轮 review 漏掉的:我的定向 e2e 走真实 config 文件 → loadOptions → compat 恒在,崩溃路径从未被我的用例触达;而主 CI 挂起的异常时长正是该 bug 的症状,我当时归因于 runner 波动、没有深挖日志(logs 端点当时还 404)。教训:定向测试通过 ≠ 构造路径全覆盖;CI 异常时长本身就是信号。全量套件最终兜住了它——这正是门禁顺序(定向→CI 全局把关)的价值。

七问(终态)

  1. 是什么问题:SenseNova OpenAI-Responses 网关严格 schema 拒绝 pi-ai 固定外发的 reasoning.summary(compat.dropFields:按 provider 删除客户端固定发送的字段(SenseNova Responses 严格 schema 400) #1757)→ 需要按 provider 删字段的逃生口。
  2. 什么原因导致的:客户端固定字段与上游 schema 不匹配(wire 兼容缺口,非 bili bug);复审中暴露的次生缺陷为 opts 构造路径未覆盖 compat 缺席情形。
  3. 怎么修复的:compat.dropFields(全局 ∪ per-provider 加性合并)、dot-path 结构化删除只动解析后 JSON 普通对象路径、字符串叶子逐字节保真;forward() 边界 + 5 条 verbatim 分支 + wireTransform 重试路径统一应用;未配置时原始字符串同一性保持。次生缺陷以可选链修复(与 roles 既有模式一致)。
  4. 是否有回归:默认关闭、未配置路径字节不变(e2e C + WC-013 负向控制钉住);WC-011→WC-013 改号不动 master 已有条款;全量 3555 tests 0 fail(你跑)+ 我侧定向复验一致。
  5. 是否破坏缓存:否——[design] chain checkpoint step 3: carrier stamp shape on role-alternation-strict wires (anthropic/google) #1421 stamp 在 drop 之后计算,digest 覆盖删后字节且确定性不变。
  6. 是否改了设计方向:否——沿用拍板的 shape A,落在既有 compat 块内。
  7. 是否引入新配置:compat.dropFields?: string[](全局 + per-provider),opt-in 默认空无迁移;CONFIGURATION.md 中英同步。

判定

可合并,等人按按钮。代码两轮 review PASS + 冲突并集解决 + 可选链修复 + 9/9 CI 绿(独立核验)。无需另立 issue(修复在 #1757/#1858 范围内,已落 PR 分支)。

@ranxianglei
ranxianglei merged commit fe92be6 into master Oct 1, 2026
13 checks passed
@ranxianglei
ranxianglei deleted the wt-1757-ework-daemon branch October 15, 2026 05:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

compat.dropFields:按 provider 删除客户端固定发送的字段(SenseNova Responses 严格 schema 400)

1 participant