Skip to content

ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648

Closed

Description

@chenshuangci

ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面)

现象

ZCode 以普通代理模式接 bili(anthropic 协议,base-url 指向代理,无插件头)。旧版本(≤0.1.80)里,bili 压缩(折叠)发生后,ZCode UI 的上下文用量会立刻降为实际上下文;某个版本后变成了"累加值"——显示的是未压缩基线(真实折叠值 + 历次压缩节省的回填),只会持续上涨,不再是模型实际收到的量。

  • 用户无法从 UI 判断真实上下文压力(bili 自己的账本显示 9-11%,UI 显示 ~16%+);
  • 数字还会在没有任何压缩的纯追加轮小幅回落(估算漂移),看起来像坏了;
  • 只有翻 bili.log 的 [acp-usage] input= 才能看到真实值。

版本时间线

与 #645(Codex 面)完全一致:0.1.70–0.1.80 正常,v0.1.88 的 PR #425(#408 host usage backfill)起出现;0.1.95 实测仍存在(证据见下)。

现场证据(0.1.95,2026-09-08 晚,长会话实时抓取)

2026-09-08T11:35:38.077Z [info] [3c6c…] [acp-usage] round 1 input=90023 cached=89792 (cache hit 100%)
2026-09-08T11:35:38.512Z [info] [3c6c…] host usage backfill armed: +63812 tok (forwarded view is folded); host usage will report the uncompressed baseline
2026-09-08T11:45:41.745Z [info] [3c6c…] [acp-usage] round 1 input=101592 cached=99712 (cache hit 98%)
2026-09-08T11:45:44.510Z [info] [3c6c…] host usage backfill armed: +63761 tok (forwarded view is folded); host usage will report the uncompressed baseline

根因(0.1.95 dist/index.js:59340-59347)

function armHostUsageCredit(session, originalMessages, processedMessages, log2) {
  session.hostCreditTokens = 0;
  if (session.metadata.pluginAgent === "pi" || session.metadata.pluginAgent === "omp") return;
  session.hostCreditTokens = ... Math.max(0, estimateCoreMessages(originalMessages) - estimateCoreMessages(processedMessages)) ...;
  // log: host usage backfill armed: +N tok ... host usage will report the uncompressed baseline
}

豁免集目前只有 pluginAgent === "pi"(#591)与 "omp"(#623);#645 在飞的修复按 Codex User-Agent 豁免。ZCode 走普通代理(base-url 直指),pluginAgent 为空、UA 也不是 Codex → 三个豁免都吃不到,hostCreditTokens = est(原始全量) − est(折叠视图) 全额累加进回报宿主的 usage。

与现有 issue 的关系

同一机制的宿主面第四例:#408/#425(起源)→ #590/#591(pi 豁免)→ #623(omp)→ #645(Codex,UA 豁免在飞)→ 本票(ZCode/普通 anthropic 代理客户端)。#645 里已论证"回填值是虚数且有漂移,宿主显示 used/window 只有 used=模型实收才自洽"——对 ZCode 同样成立,不重复展开。

修复方向建议

ZCode 与 pi 的论证同构:压缩调度主要由 bili 的 nudge/preflight 负责(读折叠口径),宿主侧的未压缩基线对 ZCode 的价值存疑。两个方向任一均可:

  1. 豁免扩展:普通代理模式提供配置开关(如 hostUsageCredit: "auto"|"off",auto=仅对已知需要未压缩口径的宿主武装),让普通 anthropic 代理客户端默认回报实收值;
  2. UA 识别:若 [Question] Previously, Codex displayed the context window size after compression, but it now appears to show an unexpected/incorrect value. #645 的 Codex UA 豁免落地,把豁免机制做成可扩展宿主集(ZCode 有稳定 UA 的话可加入;普通代理模式下 UA 可能不可靠,建议以配置开关为主)。

若最终裁决 ZCode 需要保留回填(驱动其原生压缩),也请在文档/面板明确「UI 数字=未压缩基线」,并在 /acp 面板或响应头暴露实收值,避免只能翻日志。

验收

Activity

  1. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 已修复,PR: #649

    审核结论(动手前验证)

    Bug 属实,根因与你的分析一致。 我在代码里核实了 armHostUsageCredit(src/server.ts):豁免集只有 pluginAgent === "pi"(#591)/"omp"(#623),#647 在飞的是按 Codex UA 豁免。ZCode 走普通代理(anthropic 协议、base-url 直指、无 x-bili-plugin 头)→ pluginAgent 为空、UA 非 Codex → 三个豁免全吃不到,hostCreditTokens = est(原始全量) − est(折叠视图) 全额累加进回报宿主的 usage。层次判断:这是 #408 回填机制在"普通代理客户端"这一宿主面的第四例(继 pi/omp/codex 之后),根因是回填对这类客户端是虚数且有漂移,不是 ZCode 自身的问题。

    修复方案(采纳你的方向 1:配置开关为主)

    新增 hostUsageCredit 配置项("auto" | "off",默认 auto = 现状):

    配置方式二选一:

    • 配置文件:"hostUsageCredit": "off"
    • 环境变量:BILI_HOST_USAGE_CREDIT=off

    已在 CONFIGURATION.md 记录。

    为什么做成开关而不是硬豁免

    #408 回填的初衷是让宿主的原生 auto-compact 看到未压缩基线从而保持存活。它对某宿主是有益还是有害,取决于该宿主的原生压缩:pi/omp 被 bili 扩展取消(已豁免)、codex 按 total_tokens 触发(回填碰不到,已豁免)。对普通代理客户端如 ZCode,这个价值是宿主相关、代理侧无法预判的——所以用显式开关(你建议的主机制)比猜测更稳。auto 保留现状,off 给 ZCode 这类客户端一条干净的退出路径。

    验收对照

    预检

    一个待你拍板的点

    我保留了默认 auto(现状) 以向后兼容。你的方向 1 里提到"让普通 anthropic 代理客户端默认回报实收值"——如果希望普通代理客户端默认就是 off(即回到 0.1.88 之前的行为),这是一行改动,但会改变所有普通代理客户端的行为(不只 ZCode),所以想先跟你确认:是保持 auto 默认 + ZCode 用户显式 off,还是直接把普通代理默认翻成 off?我倾向前者(更安全),但你定。

  2. added a commit that references this issue on Sep 8, 2026
  3. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    继续,按照你的建议实现

  4. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 收到,按建议(auto 默认 + 普通代理客户端显式 off)实现——PR #649 当前代码已是这个方案,无需再改:

    分支上已看到补的 CHANGELOG 条目(1fd8806,docs-only,放在 [Unreleased] → Fixes,描述准确),现在 PR 共两个提交:

    1. e6a24d5 fix ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648: 代码 + 回归测试 + CONFIGURATION.md
    2. 1fd8806 docs: CHANGELOG 条目

    预检(typecheck / test / build)在上条已列:全绿(唯一 launcher.test.ts 失败是本环境预存问题,基线同样失败,与本改动无关)。

    PR 已就绪,等你 review 后人工合并(我按规不能 merge):#649

  5. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    徽章验证:请回复一个 ok

  6. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    挂了?继续

  7. ranxianglei commented on Sep 8, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 没挂,开发已经完成,卡在人工合并这一步(我按规不能 merge):

    • PR fix #648: add hostUsageCredit switch to opt out of #408 host-usage backfill #649 已就绪:open + mergeable: true,两个提交(代码+测试+文档 / CHANGELOG),预检全绿(typecheck / test / build)。
    • 下一步需要人工操作:review 后合并 PR → CI 自动发布新版本到 npm(打 tag + GitHub Release)。
    • 合并发布后,ZCode 用户装新版并设 "hostUsageCredit": "off"(或 BILI_HOST_USAGE_CREDIT=off),UI 用量就会回落到实际转发值。

    PR 链接:#649

    如果你希望我继续做别的(比如调整默认值、补文档、或处理 PR review 里的意见),告诉我具体要改什么即可。

  8. Xiaomaogod666 commented on Sep 10, 2026

    @Xiaomaogod666

    @ranxianglei 补一份 #648 的完整现场记录。我们刚开始以为是 ZCode 或中转站的 bug,排查了两天才定位到这是 #408 backfill 的预期行为,过程中积累了一套双端对账数据,整理如下,供参考。

    环境与现象

    • Windows 11,ZCode 桌面版经 MITM 接入 bili(httpProxy 127.0.0.1:8787 + root-ca.pem),上游为 OpenAI /responses 协议中转站,模型 glm-5.3-flash。
    • 配置:compress.modelContextLimit: 328000、preserveRecentMessages: 5,实测 0.1.91 / 0.1.92 / 0.1.98 三个版本行为一致。
    • 现象:bili 面板显示真实上下文 ~10 万(占比 9–11%),但 ZCode UI 显示 80 万上下文,两者差近 10 倍,且随会话变长持续增长。

    根因定位(代码级)

    • armHostUsageCredit(0.1.91 dist:58711):hostCreditTokens = estimateCoreMessages(originalMessages) − estimateCoreMessages(processedMessages),豁免仅 pluginAgent === 'pi'(0.1.95 起加了 'omp')。ZCode 普通代理模式(pluginAgent 为空、UA 非 Codex)不在豁免之列,拿到全额 credit。
    • backfillHostUsage(0.1.91 dist:52454):直接改写回传宿主的 usage——responses/anthropic 协议加在 input_tokens,openai 协议加在 prompt_tokens + total_tokens;cache_read 字段不动。
    • estimateCoreMessages(0.1.91 dist:51234):= Σ defaultCountTokens(m.text),纯文本估算,不含工具参数与结构开销。
    • ZCode 侧:UI 的 contextUsed 直接取最后一次 response.usage.inputTokens,没有过滤逻辑,所以显示的就是 backfill 后的基线值。

    量化对账(同一时刻抓取,算术闭合)

    会话 sess_2dc0ce93(长会话,2145 条消息):

    来源 值
    bili [acp-usage] input=(实际转发) 69,849
    bili host usage backfill armed +634,699
    bili 面板 contextTokens ~99,937
    ZCode 收到的 usage.inputTokens 678,622

    69,849 + 634,699 ≈ 678,622,逐轮核对都闭合(显示值 670,269 → 679,667 单调爬升,每轮 +200~900,对应新增历史的文本估算)。另一图片会话同样闭合:实际 ~80k + credit 823,498 → UI 显示 903,852。

    排查中发现的三个附加问题

    1. credit 是文本估算,与真实 wire 有系统性偏差,UI 因此不单调。
    纯追加轮的 credit 会逐轮漂移(实测 81166 → 81155 → 81144,每轮 −11),也就是说没有发生任何压缩时,UI 显示值也会小幅回落。另外 sess_2dc0ce93 的未折叠 wire 实测约 1.72M chars(≈570k tok),而回填基线约 679k,两者偏差约 19%。

    2. cacheRead 不回填,UI 内部自相矛盾。
    backfill 只加 input/total,cache_read 保持真实值(约 92k),于是 ZCode UI 上出现"总上下文 678k、缓存命中只有 92k"的组合,两个数字对不上,用户会怀疑是缓存坏了而不是口径不同。

    3. 使用者无法从 UI 区分"真 800k"与"基线 800k"。
    这是我们排查成本最高的点:面板 9–11%、UI 80 多万,中间没有任何提示说明两者口径不同。并且基线随本地历史单调增长,长会话最终会顶到宿主自己的自动压缩阈值(ZCode 在 1M 窗口下是 966k),触发一次完全不必要的全量本地压缩——而真实上下文其实只有 ~10%。

    一个连带事故:基线混淆放大了图片问题的排查难度

    期间还遇到:图片会话每轮携带约 307k 图片 token(当时 stripImages 未开),modelContextLimit 328000 经 output 预算 clamp 后窗口不足,preflight fail-fast 502("Images alone account for ~307078 tokens (≥ window 271351)")。ZCode 收到这个错误后触发 reactive compact,把约 92 万 token 的全量本地历史拿去做压缩。当时因为 UI 显示 80 万上下文,第一直觉是"上下文真的满了",绕了不少弯路才定位到真正原因是图片。如果 UI 显示的是折叠后的真实值,这个问题应该一眼就能排除。

    对 #151 的量化注脚

    代理模式下 bili 不修改客户端本地历史,ZCode 每轮全量重发(实测 messageCount 2104 → 2145,请求体约 1.8M chars/turn),bili 折叠后实际转发约 10 万。所以 UI 的 ~679k 实际上是客户端本地未压缩存量的文本估算影子,不等于模型所见。这个口径差目前没有任何文档或 UI 提示,我们最初也因此把 backfill 值误读成了真实占用。

    数据采集方式

    以上所有数字都来自 bili 的 [acp-usage]、backfill armed 日志与面板 contextTokens,加上 ZCode rollout 文件里记录的原始 response.usage,可以对账复核。这套日志体系对排障帮助很大,谢谢。

  9. ranxianglei commented on Sep 10, 2026

    @ranxianglei
    Owner

    ework 看最新消息

  10. ranxianglei commented on Sep 10, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 @Xiaomaogod666 这份现场对账非常扎实——我逐条对照了 src/(不是 dist),你的三个观察全部成立,而且它们正好落在一个已经打开的重设计 issue 上,不用另开新票(避免重复)。

    代码核对(src/,非 dist)

    • 观察 2(cacheRead 不回填):backfillHostUsage(src/util.ts:120-140)只改 input_tokens(anthropic/responses)或 prompt_tokens+total_tokens(openai),完全不碰任何缓存字段(cache_read_input_tokens / cached_tokens)。→ UI 上「总量 678k、缓存仅 92k」的自相矛盾是结构必然。✅
    • 观察 1(credit 是文本估算):estimateCoreMessages(src/preflight.ts:113-117)= Σ defaultCountTokens(m.text),只数消息正文,不含工具参数/结构开销。→ 你测到的逐轮漂移(−11/轮)和与真实 wire 的 ~19% 系统偏差是结构必然。✅
    • 观察 3(基线推过宿主阈值 → 无谓压缩):最实际的危害路径——基线随本地历史单调增长,长会话迟早顶穿宿主 auto-compact 阈值(1M 窗口下 ZCode 966k),触发一次真实上下文其实只有 ~10% 的全量本地压缩。✅ 也是本次误判成本最高的点。

    你的两条期待各对应什么

    期待 1(#649 合并发版,你们设 off):PR #649 已就绪(open+mergeable),等 @ranxianglei review 后人工合并 → CI 自动发版。发版后设 "hostUsageCredit": "off",off 路径下三个观察同时消失(不回填 → 无漂移、缓存与总量一致、基线不会推过阈值)。这是最快止血。

    期待 2(auto 模式若保留回填:缓存同口径 / credit 用真实 wire 差值 / 面板口径说明):这正是已打开的 #660(《Redesign #408 host-usage backfill: post-fold by default, baseline opt-in》)的范围。#660 的方向是默认就报折叠实收值,你列的三个问题对所有普通代理客户端都从根上消失,而不是逐个宿主打补丁(pi #590 / omp #623 / codex #647 / ZCode #648 这套 whack-a-mole 就是 #660 要终结的)。#648 的 off 开关在 #660 里被明确定位成「通往终态的一步」。所以与其给 auto 模式打三个补丁,不如推进 #660 翻默认。

    当前状态与下一步

    好话收到,谢谢——[acp-usage] / backfill armed / nudge 三套日志能完整对账是有意设计的,这次所有数字全靠它们拼出来。

  11. added 3 commits that reference this issue on Sep 10, 2026
    2858db0
    6fba944
    175beb2
  12. added 4 commits that reference this issue on Sep 11, 2026
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

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions