Skip to content

[Gap] Core type surface stricter than actual usage: AbsorbConfig requires all five fields vs consumers applying per-field fallback (incl. prompt_cache_key wire type facet) | [Gap] 内核类型表面严于实际使用:AbsorbConfig 五字段全必填 vs 消费者逐字段 fallback(附 prompt_cache_key wire 类型 facet) #502

Open

Description

@ranxianglei

来源: #1991 (ranxianglei/billion-context#1991) 分析测试 fixture 人体工学 vs src 类型表面时发现

背景

清理 billion-context tests/ 的 1028 个既有类型错误(#1970/#1990)时发现,错误的大多数源于同一个机制族:类型表面与消费者实际用法不一致——恒有默认值的字段被声明为必填、常用类型未导出。bili 侧的 facet 已在 PR ranxianglei/billion-context#1992(Closes #1991)修复;以下两个 facet 位于 acp-kernel 自身,只能在内核侧修。

Checklist(同一机制的全部 facet,在本单内统一管理)

1. AbsorbConfig 五字段全部必填,声明与实际使用不符(主 facet)

  • 现状:acp-kernel@0.0.100 dist/types.d.ts:116-125 —— interface AbsorbConfig { enabled: boolean; toolName: string; minToolTokens: number; contextThresholdPct: number; excludeTools?: ... } 全部五个字段必填(enabled / toolName / minToolTokens / contextThresholdPct / excludeTools);仅容器层 Config.absorb?(types.d.ts:367)可选。
  • 消费者证据(内核自己与 bili 两侧都按「字段可缺席」处理):
    • billion-context src/absorb.ts:52:absorb.toolName ?? ABSORB_TOOL_NAME
    • billion-context src/compress-settings.ts:262-272 resolveAbsorbSettings(s):逐字段合并 DEFAULT_ABSORB_CONFIG(enabled: s.enabled===true、toolName/minToolTokens/excludeTools ?? 默认、contextThresholdPct parsePercent-or-default)
    • absorbEnabled 判定只看一个字段:config.absorb?.enabled === true
  • 影响:任何构造 partial AbsorbConfig 的场景(测试 fixture、配置解析中间态)都必须把内核内部本就容忍缺席的字段逐个填齐,否则 TS 可比性失败被迫 cast;与 bili 侧已修的 ProxyOptions 七字段问题(#1991 item 1)同构。
  • 建议:非激活开关字段改可选(toolName / minToolTokens / contextThresholdPct / excludeTools → 可选,enabled 可保留必填作为激活开关或一并可选),并在内核导出与 resolveAbsorbSettings 语义一致的默认合并函数,消费方不再各自维护一份默认值。

2. ResponsesRequestBody.prompt_cache_key 类型为 string,wire 上实际可能出现非 string(次 facet,评估为低价值)

  • 现状:dist/wire/responses.d.ts:52:prompt_cache_key?: string(跟随 OpenAI 规范)。
  • 消费者证据:billion-context src/session-id.ts:214-222 preferPromptCacheKeyIdentity(identity, body: { prompt_cache_key?: unknown }) 显式做 typeof === "string" 防御——说明非 string 值在真实客户端流量中出现过,否则无需防御。
  • 影响:类型表面比真实 wire 行为更窄;目前边界防御已在正确位置(bili 消费端),无功能缺陷。
  • 建议(二选一,owner 拍板):①保持现状(string 跟随规范,非 string 属客户端异常行为,消费端防御即可)——推荐;②wire 类型放宽为 unknown,把 string 假设下推到各消费方(成本:所有读该字段的站点类型降级)。记录在此仅为机制账本完整。

影响

非 bug,当前行为正确;成本是可维护性——类型门禁收紧后(#1990 起),这类摩擦会在新代码编写时持续复现,并稀释类型系统的价值。

Activity

  1. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    #502 已完成,PR: #503 (Closes #502,待 CI + 人工合并)

    结构化结论

    1. 是什么问题:AbsorbConfig 类型声明五字段全必填,但内核与消费方运行时都逐字段容忍缺席(spread 合入默认值)——类型表面比实际契约严,任何 partial 构造场景(fixture、配置解析中间态)被迫填齐全部字段或 cast。
    2. 什么原因导致的:声明与实现漂移。实际消费路径一直是 resolveAbsorbConfig / defaultConfig 的 {...DEFAULT_ABSORB_CONFIG, ...(config.absorb ?? {})} 合并(src/absorb.ts:42-44、src/config.ts:70-72),字段缺席本就合法;类型却按「完整对象」声明。这是声明-实现不一致,不是行为 bug——运行时行为一直正确。已在 v0.0.100 master 复现:defaultConfig(200000, { absorb: { enabled: true } }) → TS2739(missing toolName, minToolTokens, contextThresholdPct, excludeTools)。
    3. 怎么修复的:把声明放宽到与实现一致——toolName/minToolTokens/contextThresholdPct/excludeTools 改可选(字段文档标注默认值),enabled 保留必填作为激活开关(与仓内 ImageCompressionConfig 先例一致,issue 也允许此选项);新增 ResolvedAbsorbConfig = Required<AbsorbConfig>,DEFAULT_ABSORB_CONFIG、resolveAbsorbConfig 返回值、EvaluateCrushInput.absorb 及内部 isAcpOrConfiguredTool 改用它,保证放宽后「消费已解析配置」的入口不会静默接受 partial(否则会对 undefined 做比较)。issue 要求的「导出默认合并函数」内核自身已满足(resolveAbsorbConfig + DEFAULT_ABSORB_CONFIG 在 current master 已导出),无需新增函数。Facet 2(prompt_cache_key)按你推荐的选项①:保持 string 不动,记录在案。
    4. 是否有回归问题:逐项清点过既有行为——defaultConfig 合并、resolveAbsorbConfig、absorb/crush 各管道节点代码路径字节级未变(仅类型标注变化);validateConfig 对旧类型下所有合法输入的行为逐位相同。一处有意变更(披露):validateConfig 对 enabled 但缺 toolName 的 absorb 块,旧代码会报 "absorb.toolName must be a non-empty string when enabled"(该输入在旧类型下只能经 JS/cast 到达),现在通过——缺席即默认 "absorb" 生效,原判定是假阳性;显式空串 "" 仍报错,语义不变。EvaluateCrushInput.absorb 收紧为 resolved 形态:现有调用方(含 bili)均传完整配置,不受影响。新增 3 个回归测试钉住 resolve 语义与 validation 边界。
    5. 是否破坏缓存:不涉及——prompt 文本、wire 字节、token 计数、渲染快照均未变。
    6. 是否改了设计方向:不涉及——纯类型表面修复,架构/数据流不变;新 alias 为纯增量导出。
    7. 是否引入新配置:无——无新 env/config key,默认值不变(minToolTokens 4000、toolName "absorb"、contextThresholdPct 0、excludeTools [])。

    验证证据:修复前 probe 报 TS2739,修复后干净通过;npm run typecheck / format:check / build 全绿,build 出的 dist/types.d.ts(即 issue 引用的 116-125 行区域)显示四可选字段 + ResolvedAbsorbConfig;定向测试 absorb/crush/sync-config 三个文件 80/80 通过,全量套件交 CI。

    判定:可合并(待 CI 绿 + 人工 merge)。

  2. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    补充:PR #503 CI 已全部通过(build-artifact / test Node22 / test Node24 / pr-validation 均绿),全量测试套件无回归。可以合并了(按仓库规则由人工操作):#503

  3. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 来源: #503 (#503) review AbsorbConfig 类型表面修复时发现

    #503 review 中发现 CcrConfig 存在与本单主 facet 同机制族的缺陷(类型表面严于实际使用),PR #503 未覆盖:

    • src/types.ts:236-245:CcrConfig 的 toolName / minToolTokens / excludeTools / maxHeadChars 全部声明必填(容器层 types.ts:415 ccr?: CcrConfig 可选);
    • src/ccr.ts:59-60:resolveCcrConfig = { ...DEFAULT_CCR_CONFIG, ...config.ccr },运行时逐字段合入默认值,缺席本就合法;
    • src/config.ts:235-249:validateConfig 对这三个数值/字符串字段做无条件检查——partial { enabled: true } ccr 块在 current master 会报 3 条假阳性错误("ccr.toolName must be a non-empty string when enabled" / "ccr.minToolTokens must be >= 0" / "ccr.maxHeadChars must be >= 0"),与 AbsorbConfig 旧行为同构。

    本单明确「同一机制的全部 facet 在本单内统一管理」,故在此留账而非另立 issue。请 owner 决定处置:① reopen 本单、checklist 补 CCR facet(修法与 #503 同模式:内层值字段放宽 + ResolvedCcrConfig + validateConfig undefined 容忍),或 ② 另行安排。#503 本身范围正确、CI 全绿,可先合并。

  4. ranxianglei commented on Oct 9, 2026

    @ranxianglei
    OwnerAuthor

    跨仓同步:迁移镜像 ranxianglei/billion-context#2510 继续跟踪——内核代码已并入 billion-context(kernel/),修复已按 acp-kernel#513 指示移植为 ranxianglei/billion-context#2518 #2510,AbsorbConfig/CcrConfig 类型表面对齐 + #503 review 发现的 CCR facet 一并覆盖,CI 绿,待人工合并)。本 issue 与 PR #503 暂留 open,是否关闭由 owner 决定。

  5. changed the title [-][Gap] 内核类型表面严于实际使用:AbsorbConfig 五字段全必填 vs 消费者逐字段 fallback(附 prompt_cache_key wire 类型 facet)[/-] [+][Gap] Core type surface stricter than actual usage: AbsorbConfig requires all five fields vs consumers applying per-field fallback (incl. prompt_cache_key wire type facet) | [Gap] 内核类型表面严于实际使用:AbsorbConfig 五字段全必填 vs 消费者逐字段 fallback(附 prompt_cache_key wire 类型 facet)[/+] on Oct 16, 2026
  6. ranxianglei commented on Oct 23, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    收到跨仓同步。已逐项核实(GitHub API):

    • acp-kernel PR fix(types): AbsorbConfig type surface — optional value fields + ResolvedAbsorbConfig #503:仍 open 未合并,head 54cbab6 未变,CI 四项全绿(build-artifact / test Node22 / test Node24 / pr-validation)
    • billion-context#2510:open(本 issue 的迁移副本)
    • billion-context#2518:open 未合并,标题确认覆盖 AbsorbConfig + CcrConfig 两个 facet,head 2026-10-09_kernel-type-surface,CI 全绿(含 kernel-guard / lane-guard / 双 Node 版本测试 / e2e)

    我在 floor 5 留账的 CCR facet(CcrConfig 值字段声明必填 vs 运行时逐字段合默认,validateConfig 对 partial 块误报)按你的指示已由 bili#2518 一并覆盖,该问题闭环。

    剩一个待你拍板:acp-kernel 侧的收尾方式。#513 说「版本保持独立」,我理解 acp-kernel 仍作为独立 npm 包发布——若如此,这两个 facet 在修复进入 acp-kernel master 之前,独立包里仍然存在。

    结构化八问(选项 A/B/C 见后):

    1. 是什么问题:内核类型表面严于实际使用(AbsorbConfig 已在 fix(types): AbsorbConfig type surface — optional value fields + ResolvedAbsorbConfig #503 修好待合并;CcrConfig 同族未修),跨仓迁移后需定原仓库是否继续接直接修复。
    2. 什么原因导致的:声明-实现漂移(类型按「完整对象」声明,运行时一直 spread 合默认值);迁移本身不是缺陷,是本次决策的背景。
    3. 影响范围与严重程度(按选项):
      • A:acp-kernel master 一次补齐两 facet;不做则独立包保留严类型摩擦 + ccr partial 块 validation 假阳性(旧类型下只能经 JS/cast 到达,属可维护性瑕疵/p3)。
      • B:只修 AbsorbConfig;CcrConfig facet 留在独立包(除非将来 sync-back)。
      • C:acp-kernel 完全跟随 bili;独立包若仍在用则两 facet 都不修。
    4. 怎么修复的(推荐 A):在 PR fix(types): AbsorbConfig type surface — optional value fields + ResolvedAbsorbConfig #503 上追加一个 CCR commit——与 fix(types): AbsorbConfig type surface — optional value fields + ResolvedAbsorbConfig #503 同模式(CcrConfig 值字段改可选 + ResolvedCcrConfig 别名 + validateConfig undefined 容忍 + 回归测试),内容对齐 bili#2518 便于日后 diff/sync。一个 issue、一个 PR、一个闭环,不拆两个 PR;你点头我立即推。
    5. 回归风险(按选项):
    6. 是否破坏缓存:不涉及(三选项均无 prompt 文本/wire 字节/token 计数变化)。
    7. 是否改了设计方向:无——纯类型表面对齐;选项 C 相当于宣布本仓库「开发重心转移」,属你的决策范畴。
    8. 是否引入新配置:无。

    选项对比:

    A(推荐) B C
    PR #503 追加 CCR commit 后合并 原样合并 不合并,关闭
    CCR facet(acp-kernel 侧) 同 PR 修掉 留 bili 侧/sync-back 不修
    本 issue 关闭时机 #503 合并后(我先发说明评论再关) #503 合并后,注明 CCR 移交 bili#2518 现在关,注明已迁移 bili#2510
    成本 ~1 小时(模式复用) 零 零

    选 A 我立即推 CCR commit;选 B/C 告诉我即可,其余收尾动作(关 issue 留痕等)我来做。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions