桌面端如何配置 PI_AI_ERROR 进入 自动重试 规则中

[ChuangbinC]

参考 #3112 类似的问题，目前 我安装的是桌面端 DSH，然后 遇到一个问题是 内网 AI 请求排队 落入了 PI_AI_ERROR，导致一直中断，我想把 PI_AI_ERROR 纳入 重试 规则中，应该如何修改？

[PerryLink]

可以配，位置在 $DSH_HOME/settings.yaml。但有一个陷阱会让配置看起来"没生效"，另外你这个改法有副作用，建议先诊断再改。

1. 配置位置与形状

• 重试白名单是插件配置，不是 UI 开关：packages/llm/llm-pi-ai/src/config.ts:348 → retryPolicy: RetryPolicySchema；:500 → resolveRetryPolicy(retryPolicy, \llm-pi-ai: provider "${provider}" retryPolicy`)` ⇒ 可按 provider（路由）分别设置。
• 命名空间取该插件 entry 的 id：packages/llm/llm-pi-ai/src/index.ts:97 → const NS = 'llm-pi-ai'；:156 → settingsNs = ctx.fiber.entry?.options.id ?? NS
• 默认文件 $DSH_HOME/settings.yaml（.agents/notes/archived/architecture/2026-07-28-user-settings-seam.md:18）；重试策略归该文件所有（.agents/notes/archived/architecture/2026-07-30-web-config-plane.md:24：「重试策略、超时及其他字段仍归 settings.yaml 所有」）。

形状（packages/llm/llm/src/retry-policy.ts:87-92）：

llm-pi-ai:
  providers:
    <你的路由名>:
      retryPolicy:
        mode: normal          # 'normal' | 'always'
        maxRetries: 5
        retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, PI_AI_ERROR]

2. ⚠️ 陷阱：retryableCodes 是整体替换，不是追加

packages/llm/llm/src/retry-policy.ts:90 → retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES])

⇒ 你写什么就是什么。如果你只写 [PI_AI_ERROR]，会顺手把 RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT / EMPTY_RESPONSE 全部丢掉 —— 那会让本来会重试的错误也不再重试，症状反而变差。

所以上面那行必须把默认的五个码一起写全。默认集合在 :18-24：

const DEFAULT_RETRYABLE_CODES = Object.freeze([
  EMPTY_RESPONSE_CODE, 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT',
])

3. ⚠️ 为什么要谨慎：PI_AI_ERROR 是兜底码

packages/llm/llm-pi-ai/src/stream.ts 的 classifyPiAiError（:42-68）是一条顺序正则链：:43 AUTH → :44 配额 → :45 RATE_LIMIT → :48-49 INVALID_REQUEST → :50 5xx → :51 TIMEOUT → :58/:59-66 TRANSPORT → :67 return 'PI_AI_ERROR'。

⇒ 落到 PI_AI_ERROR 意味着"前面所有规则都没匹配上"。把它加进白名单，等于重试所有未被识别的错误，其中包括真正不可恢复的那些（内容策略拒绝等）。

而闸门在 packages/llm/llm-retry/src/index.ts:215 → } else if (!policy.retryableCodes.includes(failure.code)) { ⇒ 不在白名单就直接放行、不重试。所以"加进去就重试"确实成立，代价是粒度变粗。

4. ⭐ 建议：先诊断，再改配置（很可能你根本不需要改）

你说"内网排队"落到 PI_AI_ERROR。但排队通常会先被前面的规则抓到：

• 若是 429 / rate limit 字样 ⇒ :45 会判成 RATE_LIMIT，本来就在白名单里；
• 若是超时 ⇒ :51 判 TIMEOUT，也在白名单里；
• 若是 5xx ⇒ :50 判 SERVER，也在白名单里。

请先确认实际码是什么：在会话日志的 turn/end 事件里看 reason.error.code（当前会话日志是 session.v4.jsonl.zstd，因为 SESSION_FORMAT_VERSION = 4）。

• 若实际是 RATE_LIMIT / TIMEOUT / SERVER ⇒ 它已经在重试，问题不在白名单（可能是重试 5 次后仍失败，或根本没走到重试层）；
• 若确实是 PI_AI_ERROR ⇒ 那才需要改配置，且建议同时收紧 maxRetries，因为每次重试都是一次计费请求。

5. 备选：mode: always

若你只想"什么都重试"，可以用 mode: always（retry-policy.ts:94-97）。但请注意 packages/llm/llm-retry/README.md:132 明说 always 会连 auth / quota / invalid-request / protocol 这些永久失败一起重试 —— 对一次计费的 API 来说代价更大。所以 mode: normal + 白名单更合适。

6. 关于"桌面端在哪里配"

你问"桌面端如何配置"，可能是因为设置页里找不到。这一点据我所知是对的：Models 卡片不含 retryPolicy 字段，它只能编辑 $DSH_HOME/settings.yaml。⇒ 这可以作为一个独立的可用性诉求提出（"这个字段没有 UI 入口"），与你现在这条分开写。

7. 版本与边界

• 我核的是 origin/master = 571902028a75c64c1d767f4ae5fd099485f0ddf0（2026-10-14T21:15:15+08:00）。retry-policy.ts:14/18-24/90 与 llm-retry/src/index.ts:215 在最新线上行号未变。
• ⚠️ dsh-v0.2.1-alpha.3 = 2fbf4359b8（2026-10-14 发布）与 master 不是同一个提交（master 多 16 个）。请在你的产物里对一遍上面的行号。
• ⚠️ 你写的是"桌面端"，但没写版本号。另外有个已知的版本区分：桌面端此前停在 0.2.0-rc.2，而 CLI/npm 已到 0.2.1-alpha.3 —— 如果你在桌面上找不到某个配置面，先确认你那份的版本，否则可能是在对照不同版本。
• ⚠️ "内网排队到底报哪个码"我无法核实（需要你的日志）；上面第 4 节就是为这个设计的第一步。

[ChuangbinC]

@PerryLink 我想问下，我这边是直接安装桌面端，所以没找到这些文件，packages/llm/llm/src/retry-policy.ts，那应该如何修改？

[PerryLink]

先道个歉——我上一条给的 $DSH_HOME/settings.yaml 是过时的路径，你找不到是对的。那个文件现在只是遗留兼容：旧版留下的 settings.yaml 会在启动时被导入一次，然后改名成 settings.yaml.imported，之后就不再是活的配置了。所以别去动它。

另外澄清一下：packages/llm/llm/src/retry-policy.ts 是源码仓库里的路径，你装的是桌面端，本机不会有这个文件（代码打包在 app.asar 里）。你不需要源码——要改的是你自己机器上的一个配置文件。我上一条没说清这点，是我的问题。

你真正要改的文件

桌面端（desktop profile）是这个：

C:\Users\<你的用户名>\.dsh\profiles\desktop\cordis.patch.yml

如果你改过 DSH_HOME，就把开头的 .dsh 换成那个目录。用 %USERPROFILE%\.dsh\profiles\desktop\ 在资源管理器地址栏粘一下就能到。

为什么是这个文件：设置表单背后写入的文档就是 profile patch（config-editor 的 documentPath 直接返回 profileContext.patchPath），而它的文件名固定叫 cordis.patch.yml。

建议先打开看一眼，它里面应该已经有你那条路由的 providers 配置（就是你截图里那条）。在它上面加，不要把整块删了重写。

具体加什么

找到 - id: llm-pi-ai 那一条，在它的 config.providers.<你的路由名> 下面加 retryPolicy：

- id: llm-pi-ai
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      <你原来那条路由名>:
        # ……原有的 apiKeyEnv / api / baseURL / models 等保持不动……
        retryPolicy:
          mode: normal
          maxRetries: 5
          retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, PI_AI_ERROR]

这里有个坑必须提醒：retryableCodes 是整个替换，不是往里追加。上面那行得把默认的五个码一起写全，不然你只写 PI_AI_ERROR 的话，RATE_LIMIT、TIMEOUT 这些本来会重试的错误反而不重试了，情况会更糟。

为什么设置界面里找不到这个选项

我顺手核了一下，这不是 bug：设置表单只显示标记为 volatile 的字段。同一个 retryPolicy，在 deepseek 适配器里是 RetryPolicySchema.volatile()，在 pi-ai 适配器里是 retryPolicy: RetryPolicySchema（没有 .volatile()）。所以只有走 deepseek 那条路线时才可能出现在界面里，pi-ai 这条只能改文件。

如果你其实用的是 deepseek 那条路线而不是 pi-ai，那设置页里应该有——可以先确认一下你实际走的是哪个适配器。

两点建议

一是先别急着改。你说的是"内网排队"，但排队失败通常会先被判成 RATE_LIMIT 或 TIMEOUT，这两个本来就在默认重试名单里。真要确认，去看会话日志里 turn/end 事件的 reason.error.code 到底是什么码——如果是这两个，那问题不在白名单，改配置也不会有效果。

二是如果确认就是 PI_AI_ERROR，那也建议像上面那样显式列白名单，别用 mode: always。always 会把认证失败、配额不足、请求格式错误这些重试也没用的错误一起重试，而每次重试都是一次真实计费请求。顺带说一句，PI_AI_ERROR 本身是分类器最后那个兜底码——前面所有规则都没匹配上才会落到它，所以把它加进白名单，等于对所有"没认出来的错误"都重试，粒度比较粗，maxRetries 别设太大。

边界

我核的是 origin/master 上的代码（2026-10-14），确认的是配置应该放在哪个文档、用什么形状。你那份桌面端的实际版本号、以及它默认把 DSH_HOME 放在哪里，我没法从这边确认——上面那个路径是按默认值写的，如果你的目录结构不一样，把实际路径贴出来我再看。

另外你说的"内网排队到底报哪个码"，这个只有你的日志能回答，我没法替你判断。