DSH 中的 pi 组件把 API 错误误判成「上下文超长」，导致不会触发自动重试

[TheEudaemonia]

问题是怎么发现的

在开发项目过程中，用 DeepSeek Harness 接入第三方 API 跑长对话任务时（第三方 API 自身是否稳定由对方控制，且各家返回的错误格式各不相同），发现一个反复出现的怪现象：

1. 界面上弹出「上下文已压缩」的提示（比如"已压缩 120 条历史记录，约 61767 tokens"）；
2. 紧接着下一轮就报「本轮运行失败 400 status code (no body) CONTEXT_WINDOW_EXCEEDED」。

第一反应都会是：压缩了 → 内容还是超长 → 失败。听起来很合理，但冷静下来就觉得不对——压缩的目的就是把上下文变小，压缩完反而更超长？ 于是一步步排查。

把现象拆开看，真正的痛点是：DSH 中的 pi 组件（pi-ai）把上游的 API 错误误判成了"上下文超长"（CONTEXT_WINDOW_EXCEEDED），导致该错误不会触发自动重试，模型调用失败后 Harness 直接停止本轮——无论失败发生在压缩前后，只要被定性为不可重试的错误码，任务就会中断，长对话无法继续。

---

第一步：先看数据 —— 压缩和失败其实没啥关系

把 6 天的会话日志全部扒出来分析（日志是一堆 zstd 压缩包，解开后是逐条 JSONL 事件）：

• 一共跑了 12,238 个 step，失败约 530 次（失败率约 4.3%）；
• 这 6 天里真正发生的压缩只有 81 次；
• 结果：压缩后 8 个事件之内接着失败的，只有 12 次，占全部失败的 2.3%。

也就是说 97.7% 的失败和压缩没有任何关系。"压缩后必失败"其实是错觉——压缩提示很醒目，之后的失败容易让人误以为是压缩引起的。

---

第二步：这个报错真的是"上下文超长"吗？

报错自带错误码 CONTEXT_WINDOW_EXCEEDED（上下文窗口超了），但前面的描述是 "400 status code (no body)"——意思是：服务器返回了 400 错误，而且错误详情（body）是空的。

把 6 天所有失败翻出来看：

• 91%（486 次）都是这种"空 body 4xx"；
• 关键：没有任何一次失败带着 "context length"、"token count" 这类真实的"超长"提示文本。

结论：6 天里上下文从未真正超长过，这个错误码与实际不符。

---

第三步：失败那一刻，请求到底有多大？

以出问题最典型的那个会话为例：压缩 banner 出现后仅过了 5 个事件就失败了。把那一刻发给模型的请求内容重建出来数了数：约 4 万多个字符，折算成真实 token 只有几万。

而模型的上下文窗口是默认的 256K（约 26 万 token）。请求量只有窗口的几十分之一，却被标记为超长，说明问题不在请求体大小。

再补一个数据：历史上最大的一次成功请求是 16.5 万 token，照样成功了。所以更不可能是超长。

---

第四步：看源码

结合会话轨迹和源码，把完整的调用链梳理出来。从请求发出到本轮失败，实际按以下顺序流转：

1. 请求发往网关：模型请求走代理网关（部署在 AWS 反向代理 ALB 后面）。网关在部分请求上返回 HTTP 400，且响应体为空——没有错误码，也没有任何错误说明；
2. 空响应被翻译成一条错误消息：库会把这类空响应转成一条错误消息，文本为 400 status code (no body)；
3. 命中"上下文超长"识别规则：这一步是 pi-ai（@earendil-works/pi-ai）的错误分类逻辑。pi-ai 维护了一套用于识别上下文超长的模式库，其中有一条是专门为 Cerebras 模型加的——「返回 400/413 且响应体为空，判定为上下文超长」（Cerebras 确实用这种方式报告超长）。这条规则原本只适用于 Cerebras，但也同样命中了通用网关的 400 空响应；
4. 错误码被定为 CONTEXT_WINDOW_EXCEEDED：由于第 3 步判定为超长，这条错误被标记上该错误码；
5. 按重试白名单判定：Harness 的重试机制根据错误码白名单决定是否重试。默认白名单包含：EMPTY_RESPONSE（空响应）、RATE_LIMIT(限流)、SERVER（服务器错误）、TIMEOUT（超时）、TRANSPORT（传输错误）。CONTEXT_WINDOW_EXCEEDED 不在其中；
6. 本轮直接失败：不在白名单 = 不重试，错误直接抛给上层，本轮运行到此结束。

补充两点：

• 为什么超长不在白名单：上下文超长重试没有意义——内容没变，重发结果相同，正确做法是先压缩会话再继续。白名单不放它是合理的默认值。问题不在"白名单没放它"，而在第 3 步 pi-ai 把它误判成了超长；
• 对照组：同样是空 body，如果状态码是 429，会被归为 RATE_LIMIT（在白名单内），退避重试最多 10 次；5xx 同理归为 SERVER。只有 400/413 空 body 这一种，同时触发了超长判定且错误码不在白名单，第一发就直接结束——这就是"调用失败后停止不重试"的直接成因。

---

原因详细说明：上游的问题 × pi-ai 的过度拦截

这个问题的根源来自两头：对方上游的调用流程有问题，而 pi-ai 的错误分类与重试策略设置过于严格，把本可以自愈的问题直接拦截了。

1. 接入第三方 API：自身不稳定，且错误返回设置不统一

问题发生在接入第三方 API 的场景下。我们接入的模型走代理网关（部署在 AWS 反向代理 ALB 后面），调用的正是第三方 API。它有两点直接放大了问题的可能性：

• 自身不稳定：第三方 API 间歇性出现异常。多数是瞬时故障——网关恢复后，同一个请求大概率能成功（数据印证：相同上下文大小，相邻两步经常一个失败、一个成功）；但也存在持续性问题（429 限流久重试不退）。
• 错误返回设置不统一：第三方 API 对不同错误返回的格式并不一致——有的附带了完整的错误说明，有的只有状态码，有的响应体完全为空。空 body 的错误让客户端无法获知真实原因，只能靠规则库去推测。

从 6 天的失败数据看：

• 间歇性空 body 400/413：最常见，486 次（91%）。正常的错误响应应附带说明（如"参数错误"或"超长"），空 body 意味着网关在生成错误响应时出了问题，错误原因无法获知；
• 429 限流频发：291 次，且每次重试 10 次后仍失败——限流不是瞬时抖动，而是持续一段时间无法缓解；
• ALB 层 502/504、连接中断、"Stream ended" 等传输层问题还有几十次。

2. pi-ai 的识别规则与重试策略设置过于严格，把问题直接拦截

让"瞬时异常"升级为"本轮直接失败"的，是 pi-ai 这边的两道设置：

• 第一道：识别规则过宽。上下文超长识别规则库中，有一条本是为 Cerebras 模型定制的——"返回 400/413 且无响应体，判定为上下文超长"。放在通用 API 网关前，这条规则过宽：网关的 400 可能只是瞬时异常，也会被按"超长"处理；
• 第二道：重试白名单未覆盖。即使被误判，"上下文超长"这个错误码也不在默认的可重试白名单中（设计上认为超长重试无意义）。于是错误在第一次请求时就被判定为不可重试，直接抛给上层，本轮结束。

对比：同样是空 body，429（限流）和 5xx（服务器错误）都在白名单内，可退避重试最多 10 次；唯独空 body 的 400/413 没有任何重试机会。对瞬时异常而言，这确实过于严格。

3. 两者叠加的效果：任务卡顿

• 上游异常是诱因（问题确实存在）；
• pi-ai 的拦截是放大器（把可自愈的瞬时问题变成一轮失败）；
• 在长任务中表现为：任务中途突然失败一轮，有时需手动重试或重开，推进停滞。

修复的本质是把这道设置放松一点：让"上下文超长"（误判出来的）错误码也能进入重试流程（退避重试最多 10 次），让上游异常在重试中自行恢复，而不是第一次请求就直接失败、停止本轮。

---

补充：DeepSeek Harness 内部流程，为什么会导致这一步出问题

在厘清"上游异常 + 误判 + 白名单拦截"后，再看 Harness 每走一步的完整流程，可以解释为什么这个错误会在这一轮暴露。

Harness 每走一步的内部流水线

每推进一个 step，Harness 按固定顺序执行：

1. 组装请求：将当前会话全部内容（系统提示、可用工具、之前所有消息）打包，发送给模型网关；
2. 等待响应：模型以流式（SSE）返回，Harness 边接收边解析；
3. 解析终态：流结束或出错时，得到一条终态消息——成功，或一条错误消息（如 400 status code (no body)）；
4. 错误定性：若终态为错误，先经过 pi-ai 的"上下文超长识别器"——只要命中规则库中任意一条正则，即判定为上下文超长，错误码固定为 CONTEXT_WINDOW_EXCEEDED；
5. 重试判定：再走"重试钩子"查白名单——错误码在名单内则退避重试；不在则放行给上层；
6. 决断：无重试决定时抛错终止，本轮失败。

为什么偏偏是这一步出问题

关键在第 4、5 步只做规则匹配、不做实际校验：

• 第 4 步只看正则，不核对实际情况：不会因"请求仅几万 token、远小于 256K 窗口"而放行，也不会因错误消息是空 body（未提及"超长"）而放过——命中即判定为超长。Cerebras 正则见到 400 status code (no body) 即无条件命中；
• 第 5 步只看错误码，不区分错误来源：CONTEXT_WINDOW_EXCEEDED 不在默认白名单，错误在 0 次重试下直接成为终止原因。若同一异常以"网络/连接错误"或"429"形式出现，则会在白名单内、进入退避重试并大概率恢复；
• 结论：同一上游异常，因被识别为不同错误码而结局不同——网络/限流类自动重试自愈，超长类直接终止。最终是哪一种，取决于网关当时返回的状态码，与当前 step 是否复杂、是否刚压缩过无关。

为什么看起来压缩后这一轮更容易出问题

• 压缩后 Harness 会基于压缩得到的 checkpoint 重新组装完整请求（banner 只提示压缩量，请求照常构建），这一步发生频繁，但请求反而更小，不增加失败概率（数据：81 次压缩后 8 条事件内失败仅 12 次，2.3%）；
• 压缩提示醒目，之后的失败容易被归因于压缩；真正触发失败的是网关当刻的异常；
• 数据上最显著的风险是网关整体不稳定（6 天 12,238 步失败约 530 次、91% 为空 body 4xx），而非"压缩后"这个时间点。

这次的失败恰好发生在压缩之后，属于偶合，但撞上时确实无法自愈：压缩后重建请求刚好碰到网关异常，且该异常被识别为不可重试的超长错误；而同样的异常如果出现在其他步骤，只要以可重试的错误码返回（如 429 限流、5xx 服务器错误），重试机制会自动恢复，无需人工介入。

小结

Harness 流程设计本身合理——真实超长确实不应盲目重试。问题出在 pi-ai 的判定源头过宽（Cerebras 规则误伤）以及超长判定先于网络类判定执行，导致上游瞬时异常被定性为终结性失败，调用失败后停止、不重试。修复即放宽拦截：将 CONTEXT_WINDOW_EXCEEDED 加入可重试白名单，使误判的超长也能先重试再决定是否终止。

---

修复：改一行配置就行，不用动代码

既然问题出在"错误码没进重试白名单"，那就把它加进白名单——纯配置就能解决。

settings.yaml 里模型的重试配置，原来是：

retryPolicy: { mode: normal, maxRetries: 10 },

改成（把 CONTEXT_WINDOW_EXCEEDED 加进白名单，同时必须保留原来的 5 个码，否则限流/5xx 的重试会被一起弄丢）：

retryPolicy:
  {
    mode: normal,
    maxRetries: 10,
    retryableCodes:
      [ EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, CONTEXT_WINDOW_EXCEEDED ]
  },

涉及三个走同一个网关的模型配置（具体模型名略去）。

验证：用 Harness 自己的配置解析器跑了三关——YAML 语法、配置校验、重试逻辑模拟全部通过（新码能重试、原来的 5 个码没丢、真实的参数错误仍然不会拿去重试）。

---

改完之后的效果（预期）

• 重启 Harness 后生效（配置文件是启动时读取的）；
• 以后再遇到网关空 body 400：会退避重试最多 10 次（总等待约 1 分钟以内），网关缓过来往往就成功了，不再像以前那样第一发就"本轮运行失败"；
• 万一哪天真遇上"上下文超长"（6 天里从没发生过），会多花约 1 分钟重试然后照旧失败——代价可接受；
• 回滚很容易：把配置里的 retryableCodes 删掉就回到原样。

[weijiafu14]

这是我在这个社区见过取证最扎实的一份报告之一——12,238 个 step / 530 次失败 / 81 次压缩 / 压缩后 8 事件内失败只有 12 次（2.3%），这三个数字直接把"压缩导致失败"这个最自然的假设证伪了，而绝大多数报告在第一步就会停在那里。

补三件：一个现在就能用的止血办法、这条属于哪个更大的类、以及修复该落在哪一层。

一、止血：在网关前放一个把"空 body 400"改写成 5xx 的透传代理

你已经定位到整条链的转折点是第 3 步——pi-ai 那条为 Cerebras 加的规则（400/413 + 空 body ⇒ 判为上下文超长）。而你自己给出的对照组正好指出了出路：

同样是空 body，如果状态码是 429 会被归为 RATE_LIMIT（在白名单内），5xx 同理归为 SERVER。

也就是说：只要那个响应不是 400/413，整条误判链就不成立。

所以在 DSH 和你的网关之间放一个本地透传器，只做一件事——把"状态码 400/413 且 body 为空"的响应改写成 503，其余原样转发。DSH 那边把 baseURL 指到这个本地端口即可。

我们仓库里有个可以直接拿来改的透传器（recording-proxy.mjs，独立单文件，拷走 node 直接跑，不需要装任何东西）。它本来是用来把请求体录下来的：请求真发给上游、真实响应原样流回，中间只多存一份 body。改成"顺手改写一个状态码"就是转发前多几行。

这条的性质要说清楚：它是绕过，不是修复。 而且它有一个真实代价——如果哪天真的发生了上下文超长，你也会把它改写成可重试的 5xx，于是变成无意义的退避重试。不过按你的数据（6 天内没有任何一次失败带真实的 "context length" 文本、最大成功请求 16.5 万 token 对 256K 窗口），在你的部署里这个代价接近零。加上一行日志记下被改写的次数，如果哪天这个数字异常上涨，就该回头看了。

（好处是它还顺带给你一个东西：你能直接看到那些空 body 400 到底长什么样、来自哪一跳——你原文说网关部署在 AWS ALB 后面，那么"400 是 ALB 返的还是上游返的"这个问题，录一份就有答案了。ALB 在某些情况下会自己返回空 body 的 4xx。）

二、这属于一个反复出现的类：结构化错误信息在中间层被弄坏

你这条和另外两帖是同一个形状的三种变体：

帖	中间层做了什么	后果
本帖 #4657	用一条厂商专用启发式，给一个空 body 400 打上了错误的结构化错误码	该重试的不重试，长任务直接中断
#1215	pi-ai 的 Responses 路径把 HTTP status 和 server_error 之类的 code 压扁成一句英文 errorMessage	下游拿不到机器码，配置好的有界重试被跳过
#2884	429 配额错误被分类为终态（QUOTA 不在 retryableCodes）	整轮直接失败

三条合起来说的是同一件事：重试决策的质量，完全取决于错误分类的质量；而分类这一步现在既会丢信息（#1215），也会造假信息（你这条）。

造假比丢失更危险，这一点值得你在原帖里点明：

• 丢失（[Feedback] Windows Codex CLI integration: fork patch and remaining upstream seams #1215）的表现是"退化到保守行为"——拿不到 code 就不重试，用户至少能看出是没重试；
• 造假（你这条）的表现是"系统自信地做了错误的事"——它不是不知道，它是"知道"这是上下文超长，并据此正确地决定不重试。用户看到的错误码在积极地误导他（你自己第一反应也是"压缩了还超长？"）。

建议在标题或摘要里把这层写出来，比如"pi-ai 的上下文超长启发式会给通用网关的空 body 400 打上 CONTEXT_WINDOW_EXCEEDED，使其绕过重试"——"错误码与事实不符"比"不会自动重试"更容易被当成必须修的东西。

三、修复该落在哪一层：这里有个归属问题值得先说清

你已经指出第 3 步在 pi-ai（@earendil-works/pi-ai） 里，那是一个上游第三方库，不是 DSH 自己的代码。这意味着修复有两个可能的家，而它们的时间尺度差很远：

1. 上游 pi-ai：把那条 Cerebras 规则收窄（例如要求 provider/baseURL 匹配 Cerebras，而不是对所有端点生效）。这是根治，但要走上游；
2. DSH 这一侧：在采纳 pi-ai 的分类结果之前加一层校验——"判为 CONTEXT_WINDOW_EXCEEDED 但请求实际 token 数远低于窗口"时，不采信这个分类。你手上正好有做这个判断所需的全部数据（token meter 知道这次请求多大，模型声明知道窗口多大）。

第 2 条我觉得特别值得提，因为它不依赖上游，而且它是一条通用的防线：任何"由启发式推断出来的结构化错误码"，都应该在有更硬的证据时被推翻。 你这个案例里，"请求只有几万 token 而窗口是 256K"就是那个更硬的证据，而它当时就在手边、没人去看。

（顺带一个相关的版本信息：我们这边把 @earendil-works/pi-ai 精确钉在 0.84.1，与 dsh-llm-pi-ai 装在同一棵树里跑回归。我没有专门去读那条 Cerebras 规则在 0.84.1 上是否还在——如果你要提上游，值得先确认它在最新版里的形态，免得提一个已经改过的东西。另外 #2849 指出 dsh-llm-pi-ai 目前钉的是 ^0.82.1，而 0.x 的 caret 到不了 0.84——所以你现在跑的很可能是 0.82.x，和 npm 上的最新版差了两个小版本。）

边界与利益相关

我们不修 DSH 自家组件，也不修 pi-ai——错误分类、重试白名单、压缩都在它们各自的仓库里。第一节给的是绕过不是修复；我没有复现过你的场景，也没有读过那条 Cerebras 规则的源码，全部建立在你的取证上。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销：第一节那个脚本是独立单文件，拷走就能跑；而且换一套运行时不会改变 pi-ai 的分类逻辑——那条规则在库里，谁调用它都一样。