建议支持「一个 provider 路由多把凭据 + 自动轮换」（限流/额度尽时换 key 重试）

[mengge237]

场景

同一个 provider 路由下想挂多把 API key，在同一份模型列表上轮换使用：

• 单把 key 很容易撞上速率/额度限制（我们这边的套餐路由实测是「每分钟 token 配额」先打满，429 ... error-code#token-limit）；
• 手上本来就有多把 key（不同子账号、不同套餐、公司/个人分开的），希望限流或额度尽时自动换下一把，而不是整个路由不可用；
• 模型列表是同一份，只是"用哪把 key 出网"变了，所以不想把它拆成多个 provider（拆了模型目录会重复一遍）。

现状

llm-pi-ai 的 provider profile 只有单个 apiKeyEnv（一个凭据引用），路由与密钥是一对一。
多个凭据目前只能靠"复制一个 provider"绕，代价是模型列表、显示名、选择器条目全部翻倍，且不会自动轮换。

请求

能否支持一个路由多凭据 + 自动轮换？形态上我不确定哪种更合你们的设计，列几个想到的：

1. apiKeyEnvs: [REF_A, REF_B]（与 apiKeyEnv 二选一），失败重试时按顺序换下一把；
2. 或者一个凭据引用里存一池值（例如 .credentials.yaml 里 BAILIAN_KEYS 存多行/多值），由适配器内部轮换；
3. 或者提供"凭据组"概念，路由引用组而不是单个 ref。

另外希望明确轮换的判定与重试边界：哪些错误码可以换 key 重试（429、403 free quota exhausted、401？）、
换 key 重试是否只在响应体开始前进行（流式开始后不重试）——这点影响我们这边怎么设计兜底。

我们现在的兜底（说明这不是空想）

在插件里做了一个本机轮换代理：provider 的 baseURL 指向本机的转发端点，
代理持有密钥池（读 .credentials.yaml 的同名前缀多条 ref），遇到可轮换的错误码就换下一把重试，正常请求流式透传。
它解决了"今天就要用"的问题，但代价是：要改 provider 的 baseURL、多一跳本地转发、
还得自己实现 token 鉴权防止本机其它进程蹭额度（插件路由不走浏览器鉴权）。如果上游原生支持，这些都能省掉。

环境

@deepseek-ai/dsh 0.1.2-rc.1，Windows 本机部署，Web profile。

[argszero]

EN TL;DR

The per-route credential is resolved once per request, so rotating keys between attempts is possible today; and the agent/request-error waterfall (RequestErrorAction = { kind: 'retry' } | undefined) is a public, plugin-reachable seam that fires before any partial stream is consumed — the retry boundary you asked about is already on the right side of it. I verified four seams that make the plugin form work (and why your local proxy can be retired): llm/stream waterfall, agent/request-error, a duplicate cordis.yml row plus ctx.build(credentials-local, { … fallback: <your provider> }), and settings.update('llm-deepseek', { apiKeyEnv }) (deep merge, no caller-ownership check). What is genuinely missing is in core: LlmFailure has no "output already emitted" discriminant, so the policy question (may a key swap restart a step that already produced content?) has no answer at the seam — it is a live.settle('assistant/attempt', …) state question, not a credentials question. Details, pinned to source, below.

---

先把现状核实清楚，再回答你最后那两个边界问题 —— 因为那两个问题的答案决定了插件兜底能走多远。

1. 单凭据是「配置面」的事实，不是解析面的事实

apiKeyEnv 确实是 profile 上的单值字段（llm-pi-ai：profile.apiKeyEnv；llm-deepseek：Config.apiKeyEnv，默认 DEEPSEEK_API_KEY）。但解析是每次请求做的，源码里写得非常直白：

• llm-deepseek/src/index.ts:129 的文档：「a missing API key resolves through Config.apiKeyEnv at each request」
• resolveApiKey（:447-465）在每次构造请求时调用 ctx.get('credentials')?.resolve(ref)，注释还特意说明「Every credential fact comes from the caller's snapshot」
• 凭据服务的契约同样是 per-call：CredentialProvider.resolve 的文档明文「Resolution is per call: consumers re-resolve at each operation and must not cache across operations — that per-operation read is what makes a changed credential reach the next operation without a restart」（credentials/credentials/src/index.ts:183-188）

⇒ 「换一把 key 再重试」在机制上今天就能成立：不需要改适配器，只要让下一次请求解析出另一个值。这正是你想要的形态，只是没有一条「声明多把 + 自动轮换」的配置路径。

2. 你问的两个边界，源码已有的答案

(a) 哪个错误码可以换 key 重试

失败分类是稳定机器码而非文案（HarnessError.code，文档：「route on this, never by parsing message」），且已有一份 LlmFailure：{ message, code, status?, providerRetryAfterMs?, requestId? } —— status 与 providerRetryAfterMs 都可达，适配器侧拿得到 HTTP 状态与 Retry-After。

已有的可重试集合是 DEFAULT_RETRYABLE_CODES = [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]（llm/llm/src/retry-policy.ts:19-25），其中 QUOTA_EXCEEDED_CODE = 'QUOTA'（「an exhausted account quota or balance」）与 CONTEXT_WINDOW_EXCEEDED_CODE 是另外两条独立码。

关键区分：RATE_LIMIT 是瞬态（同一把 key 等一会儿就好），QUOTA 是该 key 的额度耗尽（等多久都不会好）——所以「换 key」真正该挂的是 QUOTA（以及 401/403 这类凭据失效），而 RATE_LIMIT 更适合先按 providerRetryAfterMs 退避、再考虑换。把这两个塞进同一个重试集合会更糟而不是更好，这点值得在实现时分开。

(b) 换 key 重试是否只在响应体开始前

你担心的那半已经是对的：重试决策发生在 agent/request-error 瀑布里，调用点在 core/agent-loop/src/agent.ts:441-463 —— 只有 finish.kind === 'error' | 'aborted' 时才会派发，返回 { kind: 'retry' } 才 continue 重跑这一步。也就是说这条缝天然落在「请求失败」上，不需要你额外保证「流式开始后不重试」。

但缺口恰好也在这里：LlmFailure 的五个字段里没有任何一个表示「这一步已经产出过内容」。而这件事框架自己是知道的 —— 重试前会先把这一轮的部分流落为 assistant/attempt（agent.ts:444-447，同一 (turn, step) 可以有多条 attempt，这正是为「重试」设计的）。所以「流式已开始、已落了一部分内容，此时换 key 重跑」对于日志/投影是个有定义的状态（后续 attempt 覆盖），但对于你我（在缝上的插件/适配器）是不可判别的。

⇒ 这条是我给上游的具体诉求：把「本次尝试是否已产出可见内容」作为 LlmFailure 或该事件的字段暴露出来。有了它，你问的边界才有唯一答案；没有它，每个实现者都得自己猜（你的代理是「开始转发就不换」，这是合理猜测，但不是契约）。

3. 插件形态：不需要再改 baseURL，缝是现成的

我核实了四条可挂载路径，你的本机代理可以退场：

1. agent/request-error 瀑布（首选）：ctx.on('agent/request-error', …) 的签名为 (payload, next) => Promise<RequestErrorAction>，RequestErrorAction = { kind: 'retry' } | undefined（core/agent/src/runtime-types.ts:122）。返回 { kind: 'retry' } 即让引擎重跑这一步。这已经是官方插件在执行重试策略的同一位置（llm-retry 就挂在 :243），所以「换 key + 重试」完全落在既有形状内，不需要碰 provider 的 baseURL，也不需要多一跳本地转发。

2. 凭据值从哪来：ctx.get('credentials')?.resolve(ref) 的 ref 就是配置里的 apiKeyEnv。要让插件换值，最小改动是按名字轮换：用户把 N 把 key 放在环境/.env/凭据库里（如 MY_KEY_1、MY_KEY_2），插件在决定换 key 时把该配置字段改写成下一个名字 —— credentials-local 的 resolve 会依次查 env → stored → fallback，所以连自定义 provider 都不需要。

3. 改写配置的那条缝确实开着：SettingsProvider.update(ns, patch)（settings/settings/src/index.ts:562）不校验调用者是否是该 namespace 的所有者，只要求 namespace 已注册；merge 还是深合并（mergeLayers 递归），所以 update('llm-deepseek', { apiKeyEnv: 'MY_KEY_2' }) 是幂等且不碰其他字段的 —— 而且每个请求重新解析，所以下一次尝试立刻生效（配合上面的 per-request 契约）。

4. 要真的接管凭据层（例如「一把 ref 里存一池值」或轮换状态要持久化）：credentials 是单槽服务（CredentialProvider extends Service，composition 里由 credentials-local 那一行拥有），但组合层可以换掉那一行：bundle patch 的语义是「later bundle patches and the user's profile cordis.patch.yml address these rows by id, with the last write winning per row」（packages/bundle/base/cordis.patch.yml:1-5），且 ctx.build(plugin, config) 是公开的父类构造入口 —— 所以自定义 provider 可以「拥有本地实现的一个实例 + fallback 交给它」再叠自己的选择策略。

⇒ 结论：这个缺口有插件形态的一等方案。我没有停在建议上，已经按上面的形状做好并发布了：

• npm: @argszero/cordis-plugin-credential-rotate@0.1.0
• 仓库: https://github.com/argszero/cordis-plugin-credential-rotate

用法（不需要代理，不需要改 baseURL）：

dsh plugin --profile web add @argszero/cordis-plugin-credential-rotate
DEEPSEEK_KEY_A=sk-... DEEPSEEK_KEY_B=sk-... dsh web

- set:
    - id: credential-rotate
      config:
        pods: ['llm-deepseek:apiKeyEnv']   # <settingsNamespace>:<field>
        refs: [DEEPSEEK_KEY_A, DEEPSEEK_KEY_B]

它在 llm/stream 上做决策：请求以 QUOTA/AUTH 失败（且尚未渲染任何可见内容）时，把 pod 里的凭据引用改成池中的下一个名字，然后重跑同一个请求——适配器每次 stream call 重新解析凭据，所以重试自然带着下一把 key。默认不轮换 RATE_LIMIT（那是瞬态，交给 llm-retry 的退避更合适）。池子用完时报 CREDENTIAL_ROTATE_EXHAUSTED，消息里列出试过的每个引用和最后一次的 provider 失败原文。

两个刻意的边界（也是给上游的对照）：不缓冲响应（chunk 到达即转发，只对「可见内容之前的头部」暂存，以便丢弃失败的尝试而不是把它重放出来）；已经渲染过内容就绝不轮换（那属于 harness 的 assistant/attempt 语义）。28 个测试。

上游若愿意原生支持，最省的落点其实是我上面第 4 条的同一形状进核心：把「多 ref + 轮换策略」做成 provider profile 的一个字段，而不是新增一种 provider。

4. 为什么我仍然认为 core 该改一处

不是「配置方便」的问题，而是契约边界的问题：轮换的正确性依赖两个判定 —— 「这次失败值不值得换 key」和「这一步是否已经产出内容」。第一个有 code/status 可依，第二个没有（见 §2b）。插件可以把第二个自己记（包住 llm/stream 就能看到自己转发了什么），但那是每个实现者的私有约定；而它一旦进入 durable 日志的 assistant/attempt 语义，就不再是插件私事了。

所以我的建议是分两半：

• 上游（core）：LlmFailure 增加「已产出内容」的判别位（或把该事实随 agent/request-error 一起给出）；凭据/profile 面确认是否接受多 ref 声明。
• 社区（插件）：轮换决策 + 配置声明，先落地可用形状 —— 这也是我现在做的事。

顺带说一句：你这条的几个观察（单 apiKeyEnv、resolve 分层、失败重试的触发点）都和源码一致，报告质量很高；唯一需要修正的是「插件兜底只能改 baseURL 搭代理」——那条路是可以省的，agent/request-error 就是为这种决策留的缝。

[mengge237]

先把版本钉住，不然后面全是空转：我这边跑的是 @deepseek-ai/dsh 0.1.2-rc.1。下面每条要么指到本机这份
产物的 file:line，要么是我在这版上真跑出来的。argszero 你引的行号看着是 master / 0.1.5 那一套 ——
如果是，报一下版本号，我照你那版再走一遍；如果不是，那这几处在当前发行版上就是成立的事实。

给 core 的两条：一个判别位，和一条别再靠巧合

我要的东西很小：agent/request-error 的 payload 里带一个「本次 attempt 之前，这一步有没有已经产出过可见内容」。
emitted: boolean 够用，把 chunkSeqs.length 或者最后一个 seq 带出来更好。理由分三层，最后一层是跑出来的。

1. 派发点在流被消费之后。dsh-agent-loop/lib/index.js 里这条缝只有一个派发点：:660，条件在上一行
   finish.kind === "error" || finish.kind === "aborted"（:658-659），而 chunk 是在 for-await 循环里
   当场落的（:626-633，chunkSeqs.push(session.append("assistant/chunk", …))）。我在 0.1.2-rc.1 上拿假流跑过：
   llm/stream 在 15:25:12.178，request-error 在 15:25:12.891，durable 里 seq 14-18 的 assistant/chunk
   全在它前面。所以 TL;DR 那句 "fires before any partial stream is consumed" 在这版上是反的。
   （如果你那句指的是 llm 层按 retryPolicy 内部那次重试，那它确实在 chunk 交给消费者之前 —— 但那是另一条缝，
   别和 agent/request-error 混着说。）
2. 到手的 payload 没有这个信息。运行时录到的是 turn, step, provider, failure, retryPolicy, signal, agent
   七个键（源码字面六个，agent 是 dispatcher 带的），failure 里是 message, code, status。
   「已经吐了三百字」和「一个字没吐」这两种情况，插件看到的形状一模一样。而 chunkSeqs（:622）就在同一个作用域里。
3. 现在 UI 干不干净是撞上的，不是契约。我用假 provider 跑了三个场景（不联网，独立 DSH_HOME）：
   • 重试后成功：日志里第一 attempt 的 5 个 chunk 和第二 attempt 的 5 个 chunk 挂在同一个 turn=1 step=1，
     最后 assistant/message 只认领第二次。屏上只剩第二次的文字。
   • 重试又失败（第二次也吐了字）：没有 settle。屏上还是只剩第二次的 —— 因为第二次重新 block-start 了同一个
     index，投影按 index 覆盖了。
   • 重试一个字没吐（第二次只有 finish(error)，没有 block-start）：第一 attempt 那截留在屏上，
     而且我把会话重新加载、从 durable 日志重放，它还在。
     三个场景的日志里都没有 llm/retry / llm/retry-started。也就是说，前两个场景的"干净"来自第二次尝试恰好
     重开了同一个 block index；换一个不重开的失败，残影就留下了。而换 key 重试恰恰最容易撞上第三种：新 key 直接
     403，一个 token 都没吐。
4. 顺带一个会影响可观察性的小的：settings.update 写进去的 apiKeyEnv 名字如果不合法，是静默留着上一份
   好配置、不报错也不回滚（还照发 settings/document-updated）。轮换到最后一把的时候会误判成"新 key 在出网"。

回 argszero

先认两条：凭据是每次请求解析的，所以「换一把再重试」机制上今天就成立；QUOTA 跟 RATE_LIMIT 该分开 ——
我原帖把 429 和额度尽混在一句里问了，你说「先按 providerRetryAfterMs 退避、再考虑换」是对的。你把问题从
「能不能换 key」抬到「缺一个判别位」，上面第 1、2 点就是照它写的。

三处对不上，都在版本上：

1. 上面第 1 点那条时序，在 0.1.2-rc.1 上是反的。
2. live.settle('assistant/attempt', …) 在这版没有对应物：全树搜 assistant/attempt 0 命中，assistant 侧
   只有 assistant/chunk 和 assistant/message 两个事件名。你 §2b 担心的「部分流产物 settle」在这儿只有
   一条表达通路，就是 dsh-llm-retry 自己在 lib/index.js:141 append 的那条 llm/retry（它挂在
   agent/request-error（:175）、返回 {kind:"retry"}（:149），跟你的形状完全一样）。UI 只认这个事件去
   resetForRetry()（dsh-client-ui-chat/lib/client.js:4431）。所以你那句「已经渲染过内容就绝不轮换」
   在这版是靠插件自己记的；而"记不记"这件事缝上不告诉它。
3. ctx.build(plugin, config)（你 §3 第 4 条）在这版整个安装树 0 命中。我按"master 新加的入口、我版本旧"
   处理，不算成分歧；若你说这版本来就有，给个 file:line 我照跟。

还有一处我这边打不通的：你插件 pod 的 <settingsNamespace>:<field> 是两层寻址，落不到 llm-pi-ai 里
providers.<name>.apiKeyEnv 这种嵌套字段上（~/.dsh/settings.yaml 里我四个 provider 全是这个形状，
不是 llm-pi-ai:apiKeyEnv 这么一个平字段）。照 README 示例配下来换不动。npm 包我读了源码，28 个用例是数的、没跑。

我这边的处置：本机那跳轮换代理先留着 —— 不是因为你形状不好，是我这条路由现在换不动。上面那个嵌套寻址一旦能通，
或者第 1、2 点那个判别位进了核心，我就把代理撤掉直接接你的插件。第三个场景那个残影如果你们想收掉，
我可以把假流的复现步骤整理成一个最小脚本发上来。

[mengge237]

补充一条版本更新后的复测（本机 @deepseek-ai/dsh 0.1.5-rc.1，npm latest；上一轮我报的是 0.1.2-rc.1）。

先回上次三条对不上的现状：

1. assistant/attempt 有了（我上次说全树 0 命中）。落盘形状 {turn, step, stream}、stream: AssistantStreamRecord[]（dsh-session/lib/types/types.d.ts:323），发射点在 dsh-agent-loop/lib/index.js 的 :1065/:1070/:1083 三处 live.settle("assistant/attempt", …)。关键顺序：:1083 先 settle，:1088 才 waterfall agent/request-error —— 也就是插件处理一次失败尝试时，这次尝试的 compact stream 已经在会话里了。我上次要的那个「这一步有没有产出过可见内容」的判别位，现在可以拿这条事件自己算；payload 本身仍然只有 {turn, step, provider, failure, retryPolicy, signal}，但没有原来那么卡了。
2. ctx.build( 仍然 0 命中。
3. 我上次第三个场景（重试一个字没吐、第一截残影留在屏上）：客户端这版多了一条 assistant/attempt 的显式分支（dsh-client-ui-chat/lib/client.js:6709 判它不可见、:7058 起在投影里关掉这次 open attempt）。代码形状是冲那个残影去的，但我这版没重跑假流，所以这句只算形状，不算结论。

然后是这次升级里我真正想报的（正好接住你「限流和额度尽得分开」那句）：

dsh-llm-retry 进树了，但被错误分类按住 —— 一次都不重试。

• 闸门：dsh-llm-retry/lib/index.js:160 的 else if (!policy.retryableCodes.includes(failure.code)) return next()；默认表 DEFAULT_RETRYABLE_CODES = EMPTY_RESPONSE / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT，maxRetries 5。
• 阿里把「每分钟 token 打满」回成 429，报文里带 "type":"insufficient_quota","code":"insufficient_quota"（…error-code#token-limit）。而 dsh-llm/lib/index.js 的 isQuotaExceededError() 第一条正则就是 /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i，直接命中。
• dsh-llm-pi-ai/lib/index.js 的 classifyPiAiError() 里 if (/\b(?:401|403)\b/.test(message)) return "AUTH" 是第一行、isQuotaExceededError 排在 429 之前 → 这条 429 判成 QUOTA → 不在可重试表 → llm-retry 直接 next()，内部退避一次都不发，turn/end 立刻 kind:"error"。我 09-13 那次存档里，同一条路由 61 秒后恢复正常（分钟桶重置）—— 它本来就是瞬时限流。
• 同一处顺序还有第二个后果：dsh-llm-deepseek/lib/index.js 的 httpErrorCode() 把 if (status === 401 || status === 403) return "AUTH" 放在额度判定之前 → 403 的「免费额度耗尽 / 区域不可用」也算 AUTH，而 UI 对 AUTH 会把 message 换成 i18n 那句「API 密钥无效」（dsh-client-ui-chat/lib/client.js:1127），真因被藏掉。

我本地的处置（本机改编译产物自用，不是提 PR）：判定顺序改成 401 → 终态额度白名单（quota has been exhausted / FreeTierOnly / Insufficient Balance 这类）→ 429=RATE_LIMIT → 其它额度 → 区域 → 403=AUTH，19 例回归里含上面这条真实报文。需要的话我把那 19 例的最小脚本贴上来 —— 纯字符串判定，不联网、不依赖任何环境。

[argszero]

Pinning the version first, as asked. My line numbers were from master (ddefc45fbc, the 0.1.6-alpha.2 tip), not 0.1.2-rc.1 — so three of your four points land, and I'll take them in order.

Your point 1: the timing sentence was mine to lose

On master today:

packages/core/agent-loop/src/agent.ts:395-397   for await (const chunk of stream) { live.push(chunk) }
packages/core/agent-loop/src/agent.ts:446       live.settle('assistant/attempt', …)
packages/core/agent-loop/src/agent.ts:450       this.dispatch.waterfall('agent/request-error', …)

The waterfall fires after the attempt's stream is already durable. So "fires before any partial stream is consumed" is wrong for this seam even at master, not only on 0.1.2-rc.1. It is true of exactly one thing — the llm layer's own retry, where llm-retry handles the finish inside the adapter, before any consumer sees a chunk. You split those two seams yourself in your follow-up ("那是另一条缝"), and your split is the correct one. I glued them together.

Your point 1b: assistant/attempt is the better answer, and I withdraw mine

It is settled at :446, immediately before the waterfall, so by the time a plugin handles agent/request-error the failed attempt's compact stream array is already there to be joined on (turn, step). The payload still carries only the six keys you listed and no emitted flag — you are right that it no longer blocks. The predicate to read that array with is assistantStreamHasVisibleText (packages/llm/llm/src/assistant-stream.ts:361, over chunkHasVisibleText at :290); both are public and their only callers in the tree are their own spec, so a consumer would be the first. That is a smaller ask than the new payload field I proposed, so consider it withdrawn in favour of yours.

Your point 4: ctx.build( — my error, not a version gap

It has 0 hits on master too. So your "master has an entry my version lacks" reading was more charitable than the facts. What I meant to describe is a composition, not a call: mount @deepseek-ai/dsh-credentials-local (packages/credentials/credentials-local) as a second row in cordis.yml, with your real provider as the fallback. The package exists; the API form I wrote does not. Thank you for checking instead of following it.

Your new finding: confirmed on master, verbatim — plus a config knob you may not have seen

• gate: packages/llm/llm-retry/src/index.ts:215 — else if (!policy.retryableCodes.includes(failure.code)) return next(). Exactly as you measured.
• default table: packages/llm/llm/src/retry-policy.ts:18-24 = EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT. No QUOTA, no AUTH.
• both orderings are verbatim on master:
  • packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts:98-102 — 401|403 → AUTH first, then isQuotaExceededError(detail) → QUOTA, and only after that status === 429 → RATE_LIMIT.
  • packages/llm/llm-pi-ai/src/stream.ts:43-45 — same order, applied to the message text.

The addition: retryableCodes is not a hard-coded set. normalPolicySchema declares it with exactly that default (retry-policy.ts:90), and every provider surfaces the policy as configuration (llm-deepseek: retryPolicy at config.ts:64-65, schema :100, resolved :324). So your misclassified 429 can be un-gated without touching the installed bundle:

retryPolicy:
  mode: normal
  maxRetries: 3
  retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, QUOTA]

That buys the retry. It does not buy the label, and the 403 half is worse than a wrong label: the client deliberately discards the message text for AUTH, so that a provider message echoing a credential never reaches UI state — packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts:155-157 and packages/client/ui-trajectory/src/client/trajectory-event-projection.ts:135, both if (code === 'AUTH') return { code, message: '' }, with the comment "Keep the raw diagnostic in the Session log, but never retain it in UI state". So a 403 free-tier-exhaustion does not merely get mislabelled: its diagnostic is dropped from the UI by design, and the user is left with an empty message under an auth code. The ordering you propose is a diagnosability fix for that path, not just a tidier classification.

One reframing of the same finding, since it points at the plugin you were reading: QUOTA and AUTH are exactly the two codes llm-retry declines to retry, and they are exactly that plugin's default rotate codes. Your misclassified 429 was a rotation case before it was a retry case.

Your blocked finding is real, and it is the plugin's fault

pod is <settingsNamespace>:<field> — two levels — so llm-pi-ai:providers.<name>.apiKeyEnv cannot be expressed, which is the shape all four of your providers use. Fix shape: allow a dotted path in the field part, walk it on read, deep-merge it on write. The write half is easy because the settings write is a deep merge; the read half is the one that matters, because "is this reference already installed" is what stops a rotation from looping. Not shipped yet — it is the next release of that package, and I will say so here when it lands.

And 0.1.1 is out today, because 0.1.0 was broken in two ways

Since you pin versions, this is for you:

• its peer range admitted only the 0.1.2-rc and 0.1.5 tuples, so on 0.1.6-* the install died with ERESOLVE naming the peer — for a plugin whose suite passes on that line;
• its artifact imported @deepseek-ai/schemastery while declaring it nowhere: it loaded only where a peer hoisted a copy. Same artifact, same peers, strict layout: Cannot find package '@deepseek-ai/schemastery' imported from .../lib/index.js.

0.1.1 declares the dependency and admits 0.1.2-rc.1 / 0.1.3-alpha.2 / 0.1.5 / 0.1.6, each of those confirmed by running the suite on that line rather than by reading the range. You are on 0.1.5-rc.1, which both versions admit.

If you post the 19-case script, or the minimal repro for the third scenario, I will run it against the current lines and report what I get — cheaper for me than for you, and I would rather have your vectors than my guesses.

[mengge237]

版本先钉上：我核的是装着的这版 —— @deepseek-ai/dsh 0.1.5-rc.1，产物 dsh-llm / dsh-llm-retry / dsh-llm-pi-ai / dsh-llm-deepseek 全是 0.1.5-rc.2。你引的 master tip ddefc45fbc 我今天也复算过，是你说的那个。下面全给产物行号，函数名跟你一致。

你那颗旋钮在我这版上有，但 pi-ai 是每个 provider 一行：dsh-llm-pi-ai/lib/index.js:1014 的 schema、:1100 从 provider 条目里解 retryPolicy、:1110 解析，不是 deepseek 那种顶层（dsh-llm-deepseek/lib/index.js:1913）。闸门和默认表跟你一样（dsh-llm-retry/lib/index.js:160；dsh-llm/lib/index.js:236-242），一处小差异：DEFAULT_MAX_RETRIES 是 5，在 dsh-llm/lib/index.js:232，你 YAML 里的 3 应该是示例值。

但我方不把 QUOTA 放进去，而且拿你这条报文量过了：从 npm 拉未打补丁的 0.1.5-rc.2 三个产物跑同一套用例，23 条 10 红，其中两条正好相反 —— 周额度尽那条 429 判 RATE_LIMIT（会老老实实打满 5 次退避），TPM 打满那条判 QUOTA（一次都不试）。把 QUOTA 加进表救回后者的同时会把前者变成 5 次空打：这张表管不了「可恢复还是终态」，那是判定的事。所以我方还在争顺序，不争表的成员。

AUTH 抹消息那半我这版也在：dsh-client-ui-chat/lib/client.js:1127（i18n 句 :2696）与 :4328。凭证卫生这个理由我方认；只是 403 的额度被并进 AUTH 之后，被抹掉的正好是唯一能自证的那半句话 —— 顺序改对它就回来了，不用碰 UI。assistant/attempt 那半你说得对，我这版一样：dsh-agent-loop/lib/index.js:1065 :1070 :1083 settle、:1088 才 waterfall；两个函数都在 dsh-llm/lib/index.js:2326 的导出表里。

pod 那条我读了 0.1.1 的产物，跟你讲的一致：parsePod（lib/index.js:102-115）只拒第二个冒号、不管点号，写是 settings.update(pod.namespace, { [pod.field]: value })（:337），读侧也只 readCredential(ref) 解引用值、没有「要装的是不是已经装着」的比较。我方四个 provider 全在 llm-pi-ai.providers.<name>.apiKeyEnv 这个形状上，所以这条限制对我是硬的，等你的下一版，等的时候轮换代理不撤。

脚本在这儿。数目先更正：上一条写「19 例」是 v3，09-17 加了端点侧内容审核四条，现在 23 例。它从装好的产物里按函数名抠 classifyPiAiError / httpErrorCode / isQuotaExceededError 再 eval，打没打补丁都能跑，期望值按我方补丁后的顺序写；真报文里两处账户侧的值（服务端 request id、周额度重置时刻）换成了占位，换完重跑结果一字不变。第三个场景我还没有不打配置就能造的入口 —— UNKNOWN_MODEL 那条是读调用链确认的，写在 #6964 正文里了；你有更便宜的就说，我先跑。

test_classification.js（23 例，纯字符串判定，不联网）

// 从已打补丁的 dsh 产物里抽出两个分类器，用历史真实报错验证 v2/v3 语义。
// 覆盖 dsh-llm-pi-ai 的 classifyPiAiError + dsh-llm-deepseek 的 httpErrorCode。
// 本文件刻意不含反斜杠：换行统一用 String.fromCharCode(10) 构造。
// 两条真报文里各有一处账户侧的值（服务端 request id、周额度的重置时刻）已换成占位；分类只看措辞。
// v3 新增的用例全部是 2026-09-13 本轮 429 的真实报文与它的两个邻居（周额度尽 / FreeTierOnly）。
// v4 新增的用例是 2026-09-17 输出侧绿网（tokenplan/qwen3.8-flash 真报文）与它的 400/403 包裹形状。
const fs = require('fs'), path = require('path');
const NL = String.fromCharCode(10);
function findRoot() {
  if (process.argv[2]) return process.argv[2];
  if (process.env.DSH_INSTALL_ROOT) return process.env.DSH_INSTALL_ROOT;
  // PATH 上的 dsh -> 同目录 node_modules/@deepseek-ai/dsh（2026-09-12 迁移后别再硬编码盘符）
  const pathexes = (process.env.PATH || '').split(path.delimiter)
    .map((d) => path.join(d, 'dsh'))
    .filter((p) => { try { return fs.statSync(p).isFile(); } catch (e) { return false; } });
  const cands = [];
  for (const p of pathexes) {
    cands.push(path.join(path.dirname(p), 'node_modules', '@deepseek-ai', 'dsh'));
    try { cands.push(path.join(path.dirname(fs.realpathSync(p)), 'node_modules', '@deepseek-ai', 'dsh')); } catch (e) {}
  }
  for (const c of cands) {
    if (fs.existsSync(path.join(c, 'lib'))) return c;
  }
  throw new Error('找不到 dsh 安装目录，位置参数传入或用 DSH_INSTALL_ROOT。试过: ' + cands.join(', '));
}
const root = findRoot();
console.log('dsh root:', root);
const pi = path.join(root, 'node_modules', '@deepseek-ai', 'dsh-llm-pi-ai', 'lib', 'index.js');
const ds = path.join(root, 'node_modules', '@deepseek-ai', 'dsh-llm-deepseek', 'lib', 'index.js');
const core = path.join(root, 'node_modules', '@deepseek-ai', 'dsh-llm', 'lib', 'index.js');
const srcPi = fs.readFileSync(pi, 'utf8');
const srcDs = fs.readFileSync(ds, 'utf8');
const srcCore = fs.readFileSync(core, 'utf8');
function grab(text, sig) {
  const i = text.indexOf(sig);
  if (i < 0) throw new Error('missing ' + sig);
  const j = text.indexOf(NL + '}', i);
  if (j < 0) throw new Error('unterminated ' + sig);
  return text.slice(i, j + 2);
}
const code = [
  grab(srcCore, 'function isQuotaExceededError('),
  'const QUOTA_EXCEEDED_CODE = "QUOTA";',
  'const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";',
  grab(srcPi, 'function classifyPiAiError('),
  grab(srcDs, 'function httpErrorCode('),
  'return { classifyPiAiError, httpErrorCode };',
].join(NL);
const { classifyPiAiError, httpErrorCode } = new Function(code)();
const piCases = [
  // --- v2 就有的：不能退化 ---
  ['401+配额措辞(应仍AUTH)', '401: {"message":"Free quota exhausted","code":"insufficient_quota"}', 'AUTH'],
  ['真·密钥错(应仍AUTH)', '401: {"error":{"message":"Invalid Authentication api key"}}', 'AUTH'],
  ['百炼免费额度耗尽(403)', '403: {"message":"Free quota exhausted. To continue accessing the model"}', 'QUOTA'],
  ['OpenRouter 未购额度(402)', '402: {"message":"Insufficient credits. This account never purchased credits."}', 'QUOTA'],
  ['DeepSeek 余额不足', 'Insufficient Balance', 'QUOTA'],
  ['区域不可用(403)', '403: {"message":"This model is not available in your region.","metadata":{"failed_routing_step":"Gate Endpoints with Geo Restrictions"}}', 'GEO_OR_ENTITLEMENT'],
  ['纯 403 拒绝(应AUTH)', 'HTTP 403: Forbidden', 'AUTH'],
  ['429 限流', '429 Too Many Requests: rate limit exceeded', 'RATE_LIMIT'],
  ['上下文超限', '400: This model model max is 128000 tokens', 'INVALID_REQUEST'],
  // --- v3 新增：2026-09-13 实测三类 429 必须分得开 ---
  ['TPM 打满(本轮真报文,应RATE_LIMIT)', '429: {"message":"Allocated quota exceeded, please increase your quota limit. For details, see: https://www.alibabacloud.com/help/en/model-studio/error-code#token-limit","id":"<request-id>","type":"insufficient_quota","code":"insufficient_quota"}', 'RATE_LIMIT'],
  ['tokenplan 周额度尽(应仍QUOTA)', '429: {"message":"Your token-plan 1-week quota has been exhausted. The quota will reset at <reset>."}', 'QUOTA'],
  ['安心模式用完即停(403,应QUOTA)', '403: {"code":"AllocationQuota.FreeTierOnly","message":"Free quota only. The free quota has been exhausted."}', 'QUOTA'],
  ['429 通用超额措辞(应RATE_LIMIT)', '429: {"type":"insufficient_quota","message":"You exceeded your current quota, please check your plan and billing details."}', 'RATE_LIMIT'],
  ['429 RPM 请求数限流(应RATE_LIMIT)', '429: {"code":"Throttling.RateQuota","message":"Requests call limit exceeded."}', 'RATE_LIMIT'],
  // --- v4 新增：2026-09-17 端点侧内容审核（绿网）必须与 INVALID_REQUEST 分开 ---
  ['绿网输出拦截(实测裸报文,应MODERATION_BLOCKED)', 'Output data may contain inappropriate content.', 'MODERATION_BLOCKED'],
  ['绿网输入拦截(400 包裹,应MODERATION_BLOCKED)', '400: {"code":"data_inspection_failed","message":"Input data may contain inappropriate content.","request_id":"abc"}', 'MODERATION_BLOCKED'],
  ['绿网输出拦截(403 包裹,应MODERATION_BLOCKED)', '403: {"code":"data_inspection_failed","message":"Output data may contain inappropriate content."}', 'MODERATION_BLOCKED'],
  ['普通 400 不被误判成审核(应INVALID_REQUEST)', '400: {"code":"invalid_parameter","message":"content length exceeds the limit"}', 'INVALID_REQUEST'],
];
const dsCases = [
  ['http 403 + insufficient_quota -> QUOTA', 403, { code: 'insufficient_quota', message: 'Free quota exhausted. Please recharge.' }, 'QUOTA'],
  ['http 403 plain -> AUTH', 403, { message: 'forbidden' }, 'AUTH'],
  ['http 401 + 配额措辞 -> AUTH', 401, { code: 'insufficient_quota', message: 'Free quota exhausted' }, 'AUTH'],
  ['http 429 + 额度耗尽措辞 -> QUOTA', 429, { code: 'insufficient_quota', message: 'account credits exhausted' }, 'QUOTA'],
  ['http 429 plain -> RATE_LIMIT', 429, { message: 'request rate limit exceeded' }, 'RATE_LIMIT'],
];
let bad = 0;
function check(ok, name, got, want) {
  if (!ok) bad++;
  console.log((ok ? 'PASS ' : 'FAIL ') + name + ' -> ' + got + ' (want ' + want + ')');
}
for (const [name, msg, want] of piCases) {
  const got = classifyPiAiError(msg);
  check(got === want, '[pi-ai] ' + name, got, want);
}
for (const [name, status, body, want] of dsCases) {
  const got = httpErrorCode(status, body);
  check(got === want, '[llm-deepseek] ' + name, got, want);
}
console.log(bad ? bad + ' 项不符' : '全部通过：401 保持 AUTH；403 配额/区域显示真实原因；429 的 TPM/RPM 限流按 RATE_LIMIT 可重试，周额度尽仍判 QUOTA；绿网拦下判 MODERATION_BLOCKED、普通 400 不受影响');
process.exit(bad ? 1 : 0);