DeepSeek Harness PI_AI_ERROR：瞬时中断不重试、限流误判与 400 锁死会话

如果你在 DeepSeek Harness（DSH）里用 pi-ai 类路由（Codex、OpenRouter、opencode-go、自建网关等），很可能会遇到一种「什么都没坏但就是不重试」的失败：一轮对话突然结束，报一个笼统的 PI_AI_ERROR，日志里连一条 llm/retry 都没有。 原因不在网络，而在错误分类器：classifyPiAiError 是一串按顺序匹配的无锚文本正则，首个命中即返回，认不出就落到末尾兜底 PI_AI_ERROR；而重试轮只处理 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT 五类。于是本批讨论里反复出现的四类上游瞬时故障全部落进兜底：HTTP/2 流中断（upstream_http2_stream_error）、Codex 服务端过载与缓冲限制（server_error / exceeded request buffer limit）、限流被鉴权正则抢走（同一句里出现 401 与 429 时被判成 AUTH），以及无 body 的 400 被判 INVALID_REQUEST 之后长会话进入不可自愈的吸收态（#9589、#9397、#9502、#9564、#9636、#9352）。

DeepSeek Harness 机制：一个纯文本正则分类器 + 五类白名单

一句话结论：分类靠「文本长什么样」而不是「上游给的码是什么」，所以只要上游措辞不在正则表里，就会被归成兜底码 PI_AI_ERROR，而兜底码没有重试资格——这就是「瞬时故障不重试」的全部原因。 两处实现细节决定了所有症状（#9589）：

1. 分类器：classifyPiAiError() 是一串无锚（不带 ^/$）的文本正则，按顺序匹配、首个命中即返回；末尾是 catch-all 兜底 PI_AI_ERROR；
2. 重试轮：只重试 EMPTY_RESPONSE / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT 这五类，PI_AI_ERROR 不在其中。

DeepSeek Harness 本批被报告的具体缺口

讨论里给过一个很有说服力的量化：约有一半 pi-ai 可重试措辞对 harness 是不可见的——也就是说「上游认为可重试」与「DSH 认为可重试」两张表在漂移（#9397）。

DeepSeek Harness 判据：怎么确认你踩的是这一族

看两件事就够：turn/end 有没有带 assistant/message，以及有没有 llm/retry 事件。

1. 一轮被 PI_AI_ERROR 打断，日志里 turn/end 显示错误结束、没有 assistant 产出；
2. 全程没有任何 llm/retry 事件（说明这一次根本没进重试轮）；
3. 换成 TRANSPORT 类故障时，能看到重试 5/5 之类的记录——这个对照最能说明问题不在网络而在分类（#9564）。

DeepSeek Harness 处置一：把缺失的码补进重试白名单（配置层）

一句话结论：retryableCodes 是整体替换语义，所以补的时候必须把默认五类一起写全。 配置写在与当前会话模式一致的 profile patch 文件（cordis.patch.yml）里，不是过时的 settings.yaml（#9694）。

1. 先确认要补哪个码。看日志里 turn/end 的 reason.error.code，确认是 PI_AI_ERROR 还是 INVALID_REQUEST（#9694）。
2. 在 profile patch 里写全列表（把默认五类一起列出，避免整体替换把它们挤掉）：

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- patch:
    id: llm-pi-ai
    config:
      retryPolicy:
        retryableCodes:
          - EMPTY_RESPONSE
          - RATE_LIMIT
          - SERVER
          - TIMEOUT
          - TRANSPORT
          - PI_AI_ERROR        # 本次要补的兜底码

3. 重启 DSH 让配置生效，然后重跑之前失败的那条请求。
4. 验证：日志里这次应当出现 llm/retry 事件；若仍没有，说明这个码在更早的地方就被拦下（见下一节的 400 情形）（#9694）。
5. 知道代价：PI_AI_ERROR 是兜底码，把它加进白名单等于「重试所有未识别的错误」，包括那些本来就不该重试的。所以这是临时缓解，不是长期方案（#9694）。

一个容易困惑的点：为什么在设置界面里找不到这个选项？因为 pi-ai 适配器的 retryPolicy 没有标记为可在设置界面编辑（deepseek 适配器才显示），所以只能手写 patch（#9694）。

DeepSeek Harness 处置二：无 body 的 400 为什么是「吸收态」

一句话结论：INVALID_REQUEST 不在默认可重试集合，而压缩溢出的自动恢复只认 CONTEXT_WINDOW_EXCEEDED，两者对不上——所以这个状态既不会被重试、也不会被自动恢复，长会话就此锁死。 症状是「突然每条请求都报 400 status code (no body)」，此后连 /compact 也救不回来（#9352）。

还有一条相关的量级问题值得一起看：某些网关的错误体只有 31 字节，即「有状态码、没有有效消息」，于是 DSH 只能按「裸状态码」处理；opencode-go 上的真实触发条件是 prompt_tokens + max_tokens > 2^20——请求的 max_tokens 取自目录声明的输出上限（例如 384000），而声明的 1M 窗口大于上游实际的 2^20 限制（#9434）。

DeepSeek Harness 三步处置

1. 先把请求体量降下来：给该 provider/model 显式压 maxTokens（讨论中给出的一个可行值是 65536），或手动 /compact 缩短历史（#9434）：

providers:
  <provider>:
    modelOverrides:
      <model>:
        maxTokens: 65536

2. 把 INVALID_REQUEST 加进 retryableCodes（写法同上一节，注意整体替换语义），让这类 400 有机会重试成功（#9352）。
3. 或使用把无 body 4xx 改判为可重试错误的社区插件（讨论中提到有同类插件把「无 body 4xx」改判为 EMPTY_RESPONSE，从而让默认策略接手）（#9352）。
4. 验证：重放同一条请求，预期这次要么成功、要么至少出现一次重试记录；若依旧立刻失败，说明还有别的原因（例如窗口声明与实际不符），回到第 1 步继续压体量。

DeepSeek Harness 处置三：别期待「整体放开 PI_AI_ERROR」能一劳永逸

一句话结论：把整个 PI_AI_ERROR 放宽到重试，会把「本不该重试」的错误一起拉进来无限重试。 讨论里多次强调这条边界（#9397、#9502）：

1. 会连累的错误：某些状态类错误（例如运行中、待处理一类）本来就不该重试，重试反而放大成本；
2. 语义相反的相邻分支：靠近 413 的分支与「缓冲超限」语义相反，泛化匹配 buffer / too-large 会把两者混为一谈（#9397）；
3. 更稳的方向：窄修——把上游的 code 前缀整族映射到 TRANSPORT 或 SERVER（例如 upstream_http2_* 整族、server_error 单独一条），并且保持分支顺序、把限流分支提到鉴权分支之前（#9502、#9636）；
4. 上游有现成能力：讨论中提到 pi-ai 自身导出了可重试判定（isRetryableAssistantError），DSH 侧改成调用它可以避免维护第二份会漂移的措辞表（#9589）。

DSH插件 排查注意事项

这一族的排查口诀是：先看「有没有 llm/retry」，再看「turn/end 的 code 是什么」，最后才看上游原文。 九条要点：

1. 没有 llm/retry 就说明没进重试轮，不要把力气花在「重试次数不够」上（#9564）。
2. PI_AI_ERROR 的字面含义是「分类失败」，不是一种具体故障（#9589）。
3. 两张重试表在漂移：上游认为可重试的不等于 DSH 认为可重试的，量级差异可达一半（#9397）。
4. 限流被误判成鉴权很常见，判据是「密钥明明有效却报 AUTH」（#9636）。
5. INVALID_REQUEST 是吸收态：不重试 + 不自动恢复，必须人工介入（#9352）。
6. 错误体被截断（如只剩 31 字节）时，DSH 只能按裸状态码处理，排查很难，先解决「错误体为什么丢了」（#9434）。
7. retryableCodes 是整体替换：写它就必须把默认五类一起写全（#9694）。
8. 设置界面里找不到这个选项是正常的：pi-ai 适配器的 retryPolicy 没有暴露到 UI（#9694）。
9. 修复状态如实：分类器缺口的窄修、INVALID_REQUEST 的可重试性、以及摘要与上游 code 的映射，在讨论所指版本里都未修；本文给出的均是用户侧配置与插件缓解，不是官方修复。

排查这类错误时，先把「插件层」变量排掉往往能省一半时间——毕竟重试策略、视觉附件、计价守卫都是插件形态。如果你想在界面上把当前环境的插件与日志一眼看清，与其在各处手敲命令，不如用 DSH Plugin Hub 这类可视化插件市场：已安装列表、装卸历史与系统日志都在一个面板里。

来源：Discussion #9589、Discussion #9397、Discussion #9502、Discussion #9564、Discussion #9508、Discussion #9636、Discussion #9434、Discussion #9352、Discussion #9694。