@omdp/dsh-key-fallback 3.3.1 → 3.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XJungit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,34 @@
 
 **Multi-key API key pool with automatic rotation for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)** — hooks DSH's credential seam `credentials.resolve`: each time an adapter asks for a key, if that ref belongs to a configured pool the wrapper returns the pool's current key; when a configured trigger error occurs it marks the failed key cooling (fixed `cooldownMs`, no exponential backoff) and advances to the next key. **Re-sending is left entirely to DSH's own `dsh-llm-retry`** — this plugin never re-sends on its own; it only switches the key and lets the retry policy decide.
 
-Current version: **v3.3.1** (`v7` UI generation).
+Current version: **v3.3.3** (`v7` UI generation).
+
+## What v3.3.3 offers
+
+- **DSH `0.2.1` support declared — zero code change** (2026-10-18). All four dsh peers gained a **second
+  per-triple interval**, so they now read `>=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0`; `cordis` gained
+  `4.0.5` and `schemastery` `3.18.5` (both are exactly what `0.2.1-rc.2` pins). Verified in four layers:
+  a per-file SHA256 diff of the whole `@deepseek-ai/*` tree between `0.2.0-rc.2` and `0.2.1-rc.2`
+  (288 → 305 packages, 177 with real `.js` churn), a real ESM export-set diff of the 9 packages this plugin
+  consumes (identical sets; the only removals are in `dsh-app-boot`, which this plugin does not use), a
+  method-level existence check of every symbol the plugin touches, and a **real `0.2.1-rc.2` CLI assembly**
+  under an isolated `DSH_HOME` (`--dump-config` composes the plugin with zero skips). Counterfactual: reverting
+  the peer to the old single interval makes the same run emit `skipping profile bundle … is incompatible with
+  dsh 0.2.1-rc.2`, so the test is genuinely sensitive.
+
+## What v3.3.2 offers
+
+- **Peer declaration switched to the triple range `>=0.2.0-rc.1 <0.2.1-0` — zero code change**
+  (2026-09-30). Background: after DSH `0.2.0-rc.2` shipped, the gate blocked 3.3.1 exactly as it had
+  blocked 3.2.4 on `0.2.0-rc.1` — the **third consecutive round** of the same failure (settings item
+  gone, routes 404/405). The root cause was never incompatibility but per-version enumeration going
+  stale on every rc. Evidence: a full 20-package file-by-file SHA256 diff `0.2.0-rc.1 → rc.2` shows the
+  six peers this plugin declares change **only in `package.json` version strings**; the real gate
+  function was then run over the whole runtime matrix — `0.2.0-rc.1` / `rc.2` / `rc.3` / `rc.9` /
+  stable `0.2.0` all **PASS**, `0.2.1-rc.1` / `0.3.0-rc.1` all **BLOCK**.
+  ⚠️ **This narrows support**: the `0.1.7` line is **no longer declared** — use **3.3.1** if you need it.
+  ⚠️ The upper bound must be `<0.2.1-0`, never `<0.2.1`: semver sorts prereleases *before* the stable
+  release, so `0.2.1-rc.1 < 0.2.1` holds and `<0.2.1` would leak the next triple's rc.
 
 ## What v3.3.1 offers
 
@@ -128,7 +155,7 @@ Current version: **v3.3.1** (`v7` UI generation).
 
 - DeepSeek Harness with a `web`-profile GUI (`npx @deepseek-ai/dsh web`)
 - Node.js `^22.19` or `>=24`
-- Peer ranges strictly enumerate **only compatibility-tested versions** — `@deepseek-ai/dsh` `0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1` (the plugin's claimed DSH runtime; the gate that enforces it only exists from 0.1.7, so older runtimes just see an unrecognized peer), `@deepseek-ai/dsh-credentials` `0.1.0-rc.6 || 0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1`, `@deepseek-ai/dsh-llm` / `@deepseek-ai/dsh-settings` `0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1`, `@deepseek-ai/cordis` `4.0.1 || 4.0.2 || 4.0.4`, `@deepseek-ai/schemastery` `3.18.1 || 3.18.2 || 3.18.4`. No open-ended ranges (`<0.2.0`, caret): untested versions are deliberately excluded until verified. The plugin only uses the credential-reference half (`resolve`/`describe`/`set`/`unset`/`credentialRef` — stable since `0.1.0-rc.6`) and the `agent/request` + `agent/request-error` waterfall (payload unchanged across the enumerated versions); `isCredentialRefName` (added `rc.8`) is implemented locally for compatibility. The `0.1.2-alpha.2 → alpha.5 → 0.1.2-rc.1` companion packages are byte-identical (2026-09-03 verified), so DSH `0.1.2-rc.1` (`next`) needs no plugin change.
+- Peer ranges use **per-triple intervals** (single segment since 3.3.2, **two segments since 3.3.3**; per-version enumeration before that) — `@deepseek-ai/dsh` / `@deepseek-ai/dsh-credentials` / `@deepseek-ai/dsh-llm` / `@deepseek-ai/dsh-settings` all declare `>=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0`: testing the first rc of a triple clears its later rc builds (`0.2.0-rc.2`/`rc.3`…, `0.2.1-rc.2`/`rc.3`…) and that triple's stable release, while crossing into a *new* triple (`0.2.2-rc.1`) is still gated off and requires a fresh check. The `-0` upper bound is mandatory: semver sorts prereleases *before* the stable release, so `<0.2.1` would leak the next triple's rc (see `AGENTS.md` rule 3). `@deepseek-ai/cordis` `4.0.1 || 4.0.2 || 4.0.4 || 4.0.5` and `@deepseek-ai/schemastery` `3.18.1 || 3.18.2 || 3.18.4 || 3.18.5` stay **enumerated** (neither goes through the gate, which only inspects `@deepseek-ai/dsh` and `dsh-*`, and they have sparse version sets with no prerelease chain). The plugin only uses the credential-reference half (`resolve`/`describe`/`set`/`unset`/`credentialRef` — stable since `0.1.0-rc.6`) and the `agent/request` + `agent/request-error` waterfall (payload unchanged across versions); `isCredentialRefName` (added `rc.8`) is implemented locally for compatibility. **Note the `0.1.7` line is no longer declared as of 3.3.2** — install 3.3.1 if you need it.
 
 ## What v3.2.0 offers
 

package/README.zh-CN.md

@@ -4,13 +4,26 @@
 
 **为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 提供多 key 池 + 自动轮换**——插件挂在 DSH 的凭证接缝 `credentials.resolve` 上：每次适配器取 key 时，若该 ref 属于已配置的池，就返回池的当前 key；遇到配置的触发错误时，把失败 key 标记为冷却（固定 `cooldownMs`，无指数退避）并前进到下一把。**重发完全交给 DSH 自带的 `dsh-llm-retry`**——本插件从不自行重发，只负责换 key，重试策略由 retry policy 决定。
 
-当前版本：**v3.3.1**（v7 UI 代）。
+当前版本：**v3.3.2**（v7 UI 代）。
+
+## v3.3.2 新增
+
+- **peer 声明改用三元组区间 `>=0.2.0-rc.1 <0.2.1-0`——代码零改动**（2026-09-30）。
+  背景：DSH `0.2.0-rc.2` 发布后，门禁把 3.3.1 拦下的方式与当初把 3.2.4 在 `0.2.0-rc.1` 上拦下
+  完全一致——已是**连续第三轮**同型故障（设置项消失、路由 404/405）。根因从来不是不兼容，而是
+  逐版本枚举在每次 rc 迭代下必然过时。核查依据：`0.2.0-rc.1 → rc.2` 全量 20 包逐文件 SHA256
+  对比显示，本插件声明的六个 peer **只有 `package.json` 版本号变化**；再用真门禁跑全版本矩阵——
+  `0.2.0-rc.1` / `rc.2` / `rc.3` / `rc.9` / 正式版 `0.2.0` 全 **放行**，
+  `0.2.1-rc.1` / `0.3.0-rc.1` 全 **拦截**。
+  ⚠️ **本条同时收窄支持面**：不再声明 `0.1.7` 线，需要在 0.1.7 上运行请装 **3.3.1**。
+  ⚠️ 上界必须写 `<0.2.1-0` 而非 `<0.2.1`：semver 里预发布排在正式版**之前**，
+  `0.2.1-rc.1 < 0.2.1` 成立，写 `<0.2.1` 会漏放行下一个三元组的 rc。
 
 ## 环境要求
 
 - DeepSeek Harness 带 `web` profile GUI（`npx @deepseek-ai/dsh web`）
 - Node.js `^22.19` 或 `>=24`
-- peer 范围**只枚举已实际进行过兼容测试的版本**——`@deepseek-ai/dsh` `0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1`（本插件声明的 DSH 运行时；**执行该声明的门禁本身只有 0.1.7 才有**，更旧的运行时只是看到一条不认识的 peer 而已，不受影响）、`@deepseek-ai/dsh-credentials` `0.1.0-rc.6 || 0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1`、`@deepseek-ai/dsh-llm` / `@deepseek-ai/dsh-settings` `0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1`、`@deepseek-ai/cordis` `4.0.1 || 4.0.2 || 4.0.4`、`@deepseek-ai/schemastery` `3.18.1 || 3.18.2 || 3.18.4`。不使用 `<0.2.0`、caret 之类的开放范围：未测试版本在核查通过前刻意排除。插件只使用 credential-reference 半边（`resolve`/`describe`/`set`/`unset`/`credentialRef`，自 `0.1.0-rc.6` 起稳定）与 `agent/request` + `agent/request-error` waterfall（载荷跨上述枚举版本未变）；`isCredentialRefName`（rc.8 新增）本地实现兜底。`0.1.2-alpha.2 → alpha.5 → 0.1.2-rc.1` 配套包逐字节一致（2026-09-03 复核），故 DSH `0.1.2-rc.1`（`next`）无需改动插件。
+- peer 范围用**按三元组划分的区间**（自 3.3.2 起；此前为逐版本枚举）——`@deepseek-ai/dsh` / `@deepseek-ai/dsh-credentials` / `@deepseek-ai/dsh-llm` / `@deepseek-ai/dsh-settings` 四条均声明 `>=0.2.0-rc.1 <0.2.1-0`：实测该三元组的首个 rc 即自动放行其后续 rc（`0.2.0-rc.2`/`rc.3`…）与正式版 `0.2.0`，跨三元组（如 `0.2.1-rc.1`）仍会被门禁拦下、须重新核查。上界写 `-0` 是必须的：semver 里预发布排在正式版之前，写 `<0.2.1` 会漏放行下一个三元组的 rc（规范见 `AGENTS.md` 规范 3）。`@deepseek-ai/cordis` `4.0.1 || 4.0.2 || 4.0.4`、`@deepseek-ai/schemastery` `3.18.1 || 3.18.2 || 3.18.4` 仍**精确枚举**（两者不进版本门禁——门禁只检查 `@deepseek-ai/dsh` 与 `dsh-*`——且版本稀疏无预发布链）。插件只使用 credential-reference 半边（`resolve`/`describe`/`set`/`unset`/`credentialRef`，自 `0.1.0-rc.6` 起稳定）与 `agent/request` + `agent/request-error` waterfall（载荷跨各版本未变）；`isCredentialRefName`（rc.8 新增）本地实现兜底。**注意 `0.1.7` 线自 3.3.2 起不再声明**，需要它请装 3.3.1。
 
 ## v3.3.1 新增
 

package/lib/index.js

@@ -291,7 +291,7 @@ export function apply(ctx, config) {
   }
   // ── 包装 credentials.resolve：ref 命中池 env 时返回池当前 key ──
   // 这是 DSH 官方唯一的「每次请求都问一次用哪把 key」接缝（dsh-llm-pi-ai:2563、
-  // dsh-llm-deepseek-api-key:44、dsh-vision-bridge:91、dsh-cost-meter:957 等全部经它取值），
+  // dsh-llm-deepseek-api-key:44、dsh-cost-meter:957 等全部经它取值；已归档的 vision-bridge 亦然），
   // 因此拦这一处即可覆盖所有 provider，且语义与「重发归官方、插件只切 key」完全同构。
   const poolsByEnv = new Map()
   const credSvc = ctx.credentials

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@omdp/dsh-key-fallback",
   "description": "API Key 回退轮换插件：多 key 池 + 自动轮换（触发码可配置，含 LlmError 标准码全集）+ 环境密钥编辑 + 明文揭示 + 短 ref 迁移。同时兼容 DSH 0.1.5-rc.3（settings.yaml 后端）与 0.1.7+（profile entry config 后端）。Settings → API Key 回退 UI. v7.",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -38,11 +38,11 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.1 || 4.0.2 || 4.0.4",
-    "@deepseek-ai/dsh": "0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": "0.1.0-rc.6 || 0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": "0.1.1-rc.2 || 0.1.2-alpha.1 || 0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.6-alpha.1 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1",
-    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2 || 3.18.4"
+    "@deepseek-ai/cordis": "4.0.1 || 4.0.2 || 4.0.4 || 4.0.5",
+    "@deepseek-ai/dsh": ">=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0",
+    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0",
+    "@deepseek-ai/dsh-llm": ">=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0",
+    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0",
+    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2 || 3.18.4 || 3.18.5"
   }
 }