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

[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

• wire 真实输入 90k–110k;ZCode 侧看到的 ≈ input + 63.7k ≈ 154k–174k(nudge 自己的口径同窗口是 usage=9% (89852/1000000))。
• 连续纯追加轮的回填量:63812 → 63792 → 63782 → 63772 → 63761 → 63750——逐轮漂移,宿主显示值因此可在无压缩时不单调(与 [Question] Previously, Codex displayed the context window size after compression, but it now appears to show an unexpected/incorrect value. #645 报告者观察到的 1315→1313.2 同源)。
• 2026-09-07 另一会话的完整对账:UI 260k→200k→276k,同期 acp-usage input 实际 137932→70134;UI 值 = 折叠真实值 + 历次回填累计(两轮压缩各 ~65k),算术完全闭合。

根因(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 面板或响应头暴露实收值,避免只能翻日志。

验收

• ZCode(普通代理模式)会话在压缩发生后,UI 用量回落到与 [acp-usage] input= 一致的实收值;或提供官方开关可达成此效果
• 纯追加轮宿主显示不再因 est 漂移出现无压缩回落(豁免路径下自然满足)
• pi/omp/codex 既有行为不变(代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408 现有测试全绿)

[ranxianglei]

🤖 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 = 现状):

• off:彻底关闭 代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408 未压缩基线回填——回报宿主的 usage 就是实际转发(折叠后)请求的用量,与 [acp-usage] input= 一致。
• auto(默认):保持现状(普通代理客户端仍回填,pi/omp/codex 豁免不变)——向后兼容,不改变任何既有宿主行为。

配置方式二选一:

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

已在 CONFIGURATION.md 记录。

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

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

验收对照

• ZCode(普通代理)压缩后 UI 用量回落到实收值 → hostUsageCredit: "off" 达成(回归测试:anthropic 线真实折叠后,off 回报 input=1000 而非回填值)
• 纯追加轮不再因 est 漂移无压缩回落 → 关闭回填后自然满足
• pi/omp/codex 既有行为不变 → 默认 auto = 现状;现有 代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408/pi plugin 模式宿主 usage 回填未压缩基线:footer 显示 302.7%/1M 与实际请求(折叠后 ~57K)不符 #590/omp 插件会话原生压缩被扩展全部取消后仍收 #408 usage 回填: omp footer 只增不减 (205%/1M) #623 测试全绿

预检

• npm run typecheck 干净
• npm test:1241/1242 通过;唯一失败 launcher.test.ts 的 resolveClientCommand: codex/claude resolve to themselves 是本环境预存问题(此机 codex 装在 /usr/bin/codex),在基线 5836f78 上同样失败,与本改动无关。host-usage-backfill 全部 23 条(含 2 条新增 + pi plugin 模式宿主 usage 回填未压缩基线:footer 显示 302.7%/1M 与实际请求(折叠后 ~57K)不符 #590/omp 插件会话原生压缩被扩展全部取消后仍收 #408 usage 回填: omp footer 只增不减 (205%/1M) #623)通过
• npm run build 成功

一个待你拍板的点

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

[ranxianglei]

继续,按照你的建议实现

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

• 默认 auto = 现状(普通代理客户端仍回填,pi/omp/codex 豁免不变),向后兼容。
• off = 彻底关闭 代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408 回填,回报宿主的 usage 就是实际转发(折叠后)请求的用量,与 [acp-usage] input= 一致。ZCode 用户设 "hostUsageCredit": "off"(或 BILI_HOST_USAGE_CREDIT=off)即可。

分支上已看到补的 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

[ranxianglei]

徽章验证:请回复一个 ok

[ranxianglei]

挂了？继续

[ranxianglei]

🤖 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 里的意见),告诉我具体要改什么即可。

[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，可以对账复核。这套日志体系对排障帮助很大，谢谢。

[ranxianglei]

ework 看最新消息

[ranxianglei]

🤖 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 翻默认。

当前状态与下一步

• fix #648: add hostUsageCredit switch to opt out of #408 host-usage backfill #649(off 开关,止血):等人工合并发版 → 你们先设 off。
• Redesign #408 host-usage backfill: post-fold by default, baseline opt-in (opencode gap + whack-a-mole exemptions) #660(默认折叠值 + 基线 opt-in,治本):open,卡在等 @ranxianglei 确认方向(是否对所有客户端翻默认 + 机制范围)。你这份量化对账 + 三点观察是 Redesign #408 host-usage backfill: post-fold by default, baseline opt-in (opencode gap + whack-a-mole exemptions) #660 目前最强的现场证据——尤其 ~19% 偏差、缓存自相矛盾、reactive compact 危害路径这三条,Redesign #408 host-usage backfill: post-fold by default, baseline opt-in (opencode gap + whack-a-mole exemptions) #660 正文还没具体到这个程度。要不要我直接把这三条整理成一条评论补进 Redesign #408 host-usage backfill: post-fold by default, baseline opt-in (opencode gap + whack-a-mole exemptions) #660?(避免那边讨论缺了实测数据)

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