[Bug] anthropic-messages：网关把缓存读折叠进 input_tokens，导致误判上下文溢出、整轮失败并丢弃完整回答

[haozhongh]

摘要

使用 dsh-llm-pi-ai 的 api: anthropic-messages 连接第三方 Anthropic 兼容网关时，该网关返回的 input_tokens 已经包含 cache_read_input_tokens（非标准行为；Anthropic 的约定是只报未缓存部分）。

这个折叠在 DSH 中造成 4 个后果，其中第一个会直接杀掉整个 turn 并丢弃已经完整生成的模型回答。后果 1、2、3 同源，修一处即可全消；后果 4 是独立的既有缺陷，只是被这里放大暴露。

环境：DSH 0.2.1-rc.2，@deepseek-ai/dsh-llm-pi-ai，api: anthropic-messages。

---

后果 1（最严重）：误判上下文溢出，整轮失败并丢弃完整回答

机制

packages/llm/llm-pi-ai/src/stream.ts:81 把 pi-ai 的原始 usage 交给上游的静默溢出检测：

const piAiOverflow = isContextOverflow(message, contextWindow)

isContextOverflow 的 case 2 按"互不重叠"假设求和：

// @earendil-works/pi-ai dist/utils/overflow.js
if (contextWindow && message.stopReason === "stop") {
    const inputTokens = message.usage.input + message.usage.cacheRead;
    if (inputTokens > contextWindow) return true;
}

折叠后这个和接近真实 prompt 的 2 倍。真实 60 万的 prompt 被按 120 万判超 100 万窗口，mapStopReason 返回 CONTEXT_WINDOW_EXCEEDED，agent loop 结束本轮。

实测证据（本地会话日志）

会话	input	cacheRead	判定	真实 prompt	结论
0114fc3e	754,575	754,304	1,508,879 > 1,000,000	754,575	误判
2b4d209e	600,240	599,936	1,200,176 > 1,000,000	600,240	误判
cd3a3292	945,078	627,712	provider 400，报 1,048,568	≈1.05M	真超

前两例的 input 与 cacheRead 比值都是 99.9x%，正是本文开头复现的折叠特征，而且这两例的 totalTokens 字段也正好等于 input + output + cacheRead（1,509,709 与 1,200,391），可直接验证 pi-ai 的求和口径。

真实 prompt 分别为 75 万和 60 万，都低于网关实际接受的 1,048,568——这些请求本来能成功。

被丢弃的回答

判定发生时模型已经正常生成完毕（stopReason: "stop"），内容仍被整段丢弃：

会话	位置	stopReason	被丢弃内容
0114fc3e	turn 2 / step 15	stop	text 1,411 字符
0114fc3e	turn 3 / step 2	stop	text 769 字符
2b4d209e	turn 3 / step 25	stop	reasoning 1,369 + text 1,318 字符
2b4d209e	turn 4 / step 2	stop	text 1,036 字符
2b4d209e	turn 5 / step 47	stop	text 1,592 字符

用户侧看到的是「本轮运行失败 / CONTEXT_WINDOW_EXCEEDED」，且重试无法脱困——下一轮请求会被同样判超。这会形成稳定的死锁，而不是偶发失败。

另外，stopReason: "stop" 且内容非空时判为溢出本身即自相矛盾：真正溢出的请求不会收到完整回答。这一条可以独立作为兜底。

---

后果 2：缓存命中率显示约 50%，实际约 99.8%

packages/client/ui-chat/src/client/chat/StatsPills.tsx:118 把三个桶相加作分母：

export function billedInputTokens(usage: TokenUsageProjection): number {
  return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
}

而 uncachedInputTokens 直接来自 usage.inputTokens（packages/llm/token-meter/src/usage-projection.ts:22），折叠时它并不减少。

复现（向网关发送三次完全相同的请求，大且稳定的 system prompt）：

#1 input=2433 cacheRead=2432 cacheWrite=0
#2 input=2433 cacheRead=2432 cacheWrite=0
#3 input=2433 cacheRead=2432 cacheWrite=0

缓存命中时 input_tokens 不减少，说明它是总量而非未命中量。DSH 按 2432 / (2433 + 2432) ≈ 50% 显示，真实值 2432 / 2433 ≈ 99.96%。

长会话逐步数据完全一致：

input	cacheRead	显示	实际
312,035	311,680	49.9%	99.9%
312,637	311,936	49.9%	99.8%
313,171	312,576	50.0%	99.8%
313,804	313,088	49.9%	99.8%

---

后果 3：上下文占用接近翻倍，压缩阈值被提前触发

packages/llm/token-meter/src/usage-projection.ts:78 与 packages/llm/token-meter/src/index.ts:71 同样按互不重叠求和：

const pressureFrom = (usage: TokenUsage): number =>
  usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)

function usageTokens(usage: TokenUsage): number {
  return usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0) + usage.outputTokens
}

前者驱动 ContextMeter 占用显示与 projectedTokens，后者是 token-meter 的用量锚点（baseline）。折叠时两者都接近翻倍。

compaction-basic 用 measurement.totalTokens < spec.thresholdTokens 判断是否压缩（packages/compaction/compaction-basic/src/index.ts:319、:327、:340），所以压缩会在真实占用约一半时触发，白白截断仍然可用的上下文。

实测（contextWindow = 1,000,000）：

量	值
inputTokens	345,581
cacheReadTokens	345,216
当前 pressureTokens	690,797（69.1%）
真实 prompt 大小	345,581（34.6%）

注意后果 1 与后果 3 方向相反：与 contextWindow 直接比较的一侧会误判溢出，与阈值比较的一侧会提前压缩。两者必须一起修，否则只修一边会让另一边继续保持错误。

---

后果 4：真溢出时恢复路径本身不可能成功（既有缺陷，被此折叠放大）

即使溢出是真的，compaction-basic 的恢复也救不回来。

packages/compaction/compaction-basic/src/index.ts:190 的 agent/request-error 收到 CONTEXT_WINDOW_EXCEEDED 后调用 compactIfNeeded(agent, 'context-overflow', …)。摘要请求由 buildSummarizationInput()（packages/compaction/compaction-basic/src/region.ts:544）构造：system + tools + 被压缩区域的完整消息，设计上刻意复用 KV cache（packages/compaction/compaction-basic/src/summarizer.ts:28-30）。

当被压缩区域接近整段历史（正是溢出的情形），这个辅助请求与原请求几乎等大，于是摘要本身再次溢出，compaction/end 记录的错误与 turn/end 完全相同：

compaction/start {"compactionId":"e4f33c52-…","turn":1}
compaction/end   {"compactionId":"e4f33c52-…","turn":1,"error":"…context overflow…"}
turn/end         {"turn":1,"reason":{"kind":"error","error":{"code":"CONTEXT_WINDOW_EXCEEDED"}}}

maxOverflowRetries 默认 1（packages/compaction/compaction-basic/src/config.ts:106），用完即 next() 并保留原始错误。而 summarizationProvider/summarizationModel 默认回落到被路由模型本身——也就是刚刚溢出的同一个窗口。

本地会话里连续多个 turn 都停在这一步：2b4d209e 的 turn 3 / 4 / 5 各自产生一次 compaction/start + 同错 compaction/end，期间没有任何一次成功的 pre-step 压缩。

---

根因归属

packages/llm/llm/src/types.ts:170-173 已声明该契约：

Counts are DISJOINT: inputTokens is uncached input only; cached input is reported separately as cacheReadTokens/cacheWriteTokens (billed input = sum of the three). Adapters whose providers fold cache hits into a total prompt count subtract them out.

两点澄清：

1. llm-deepseek 并没有做减法，也不需要——它走 Anthropic 风格的 input_tokens，本就只报未缓存部分（packages/llm/llm-deepseek/src/translate.ts:36 直接映射）。该文档句子里提到的 prompt_tokens 折叠属于 openai-completions 协议，pi-ai 自己的该实现确实做了减法（dist/api/openai-completions.js:1177：Math.max(0, promptTokens - cacheReadTokens - cacheWriteTokens)）。
2. anthropic-messages 不能假定折叠，因为标准 Anthropic 不折叠；折叠只出现在部分兼容网关上。

因此归一化应发生在适配器摄入点（mapUsage），而不是各个消费方分别求和；且必须是 opt-in 的兼容开关，不能改变标准网关的行为。

---

建议修复

A. pi-ai 路由在摄入时归一化 usage（修后果 1、2、3）

在 packages/llm/llm-pi-ai/src/stream.ts:24 的 mapUsage() 增加兼容参数：

export function mapUsage(usage: PiUsage, inputIncludesCacheRead = false): TokenUsage {
  const cacheRead = Math.max(0, usage.cacheRead)
  const cacheWrite = Math.max(0, usage.cacheWrite)
  const input = inputIncludesCacheRead
    ? Math.max(0, usage.input - cacheRead - cacheWrite)
    : usage.input
  return {
    inputTokens: input,
    outputTokens: usage.output,
    // pi-ai 的合计口径是 input + output + cacheRead + cacheWrite，
    // 折叠时这个和也重复计数，必须一并重算，否则 usageTokens() 仍会翻倍。
    totalTokens: input + usage.output + cacheRead + cacheWrite,
    ...cacheRead > 0 ? { cacheReadTokens: cacheRead } : {},
    ...cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {},
  }
}

调用点两处（stream.ts:209、:219）透传开关。

开关位置：不能放进 PiAiCompatProfile——那个接口由 EveryProfileFieldIsOffered / EveryProfileFieldMatchesUpstream 编译期钉死在 pi-ai 上游的 compat 类型上，加非上游字段无法编译。应作为普通的配置字段加入：

• 路由级：packages/llm/llm-pi-ai/src/config.ts 的 route profile（紧邻 defaultContextWindow），schemastery 声明 inputTokensIncludeCacheRead: z.boolean()
• 模型级：PiAiModelProfile（catalog.ts:603）+ config.ts 的 modelFields，覆盖路由默认
• 解析：沿用 configuredMaxTokens 的既有做法——在 catalog.ts 的 resolveEntry 旁记入一个 Map<string, boolean>，由 adapter.ts 的 modelInfo() / generate() 读取后传给 toStreamChunks

默认关闭，标准 Anthropic 端点与 llm-deepseek 完全不受影响。

B. 不要用未归一化的 usage 判溢出（同源，需一并修）

仅靠 A 还不够：mapStopReason 目前把 pi-ai 的原始 Usage 交给 isContextOverflow。归一化后仍应让 DSH 自己掌握这条判定，而不是依赖 pi-ai 的 usage.input + usage.cacheRead。

建议改 toStreamChunks 的签名（packages/llm/llm-pi-ai/src/stream.ts:142，调用点 adapter.ts:426），把 contextWindow 换成 { contextWindow, inputIncludesCacheRead }，然后：

• case 1（错误文本模式）继续用 isContextOverflow(message, undefined) —— 显式 provider 错误仍然可信；
• case 2 / 3（静默溢出）在 DSH 侧用归一化后的 prompt 量重算，而不是交给上游；
• 额外兜底：stopReason === 'stop' 且 content.length > 0 时永不判为溢出。

C. 摘要请求加大小上限（修后果 4，独立改动）

buildSummarizationInput() 应受一个按 token 计价的预算约束（可复用 tokenMeter 的 node 价格）。超出时改为分段摘要，或退回更小的区域。同时，summarizationProvider/summarizationModel 默认不该回落到刚刚溢出的同一路由；若确实回落，至少应在日志中明确提示「摘要使用了与溢出相同的窗口」。

D. 文档修正

packages/llm/llm/src/types.ts:173 提到 "DeepSeek's prompt_tokens"，但 llm-deepseek 走 Anthropic 协议、从不接收 prompt_tokens。这句应改为指名 openai-completions 协议（pi-ai 实现），否则读者会以为减法已经发生在错误的包里。

---

影响面

• 计费不受影响：提供商按自己的 input_tokens 计费，DSH 只是读数与阈值错了。
• 受影响：缓存命中率显示、ContextMeter 占用、compaction-basic 的触发时机，以及后果 1 的整轮失败与回答丢弃。
• 默认不受影响：llm-deepseek 与标准 Anthropic 端点；受影响的只有把缓存读折叠进 input_tokens 的兼容网关。

---

附：复现用最小配置

- id: llm-pi-ai
  name: "@deepseek-ai/dsh-llm-pi-ai"
  config:
    providers:
      compat-gateway:
        displayName: compat gateway
        apiKeyEnv: GATEWAY_API_KEY
        api: anthropic-messages
        baseURL: https://<gateway>/v1
        defaultContextWindow: 1000000
        inputTokensIncludeCacheRead: true   # 修复后新增
        models:
          - id: <model-id>

判定网关是否折叠：连发两次相同请求，若 input_tokens 不随命中下降、且 input ≈ cacheRead，即属于本 issue。

[PerryLink]

你的后果 1 能落到一条已经写明的约定上，不只是「算术可疑」。

packages/llm/llm/src/types.ts:177-180 在 TokenUsage 上写得很硬：计数是 DISJOINT 的，inputTokens 只含未缓存输入，缓存单独报，并且「Adapters whose providers fold cache hits into a total prompt count (DeepSeek's prompt_tokens) subtract them out」—— 网关折叠了，适配器就要减回来。

llm-pi-ai 没做这一步。stream.ts:24-32 的 mapUsage 只处理了 pi-ai 把 reasoning 折进 output 这一种情况（注释就写着这个），inputTokens 直接取 usage.input，cacheRead 原样搬进 cacheReadTokens，整个包里没有减法。于是 isContextOverflow 拿到的 input + cacheRead 就是折叠后的两倍。判定点在 :81，在 switch 之前；:70-78 的注释也明说 stop + 超窗要映射成 CONTEXT_WINDOW_EXCEEDED —— 「完整回答被判溢出」是当前代码明确承认的组合。

所以这更像适配器没执行 DSH 自己的不变量，而不是 pi-ai 算错。修在 mapUsage 这一处（检测到折叠时把 cacheRead 从 input 扣掉）符合既有约定；在 mapStopReason 里加「stop + 内容非空不判超」的兜底是另一件事，两者不冲突。

版本：master = ce7073d5，这个文件与 dsh-v0.2.2-alpha.2 是同一个 blob；rc.5（b830ec95）上是另一份，报的时候标清楚分支。