@omdp/dsh-key-fallback 3.1.6 → 3.2.0

package/README.md

@@ -4,13 +4,59 @@
 
 **Multi-key API key pool with automatic rotation for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)** — sits between the LLM adapter and the credential store. Before each request the plugin picks a key from the per-provider pool and pre-writes it into the provider's credential reference; 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.1.6** (`v6` UI generation).
+Current version: **v3.2.0** (`v7` UI generation).
 
 ## Requirements
 
 - 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-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`, `@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`, `@deepseek-ai/cordis` `4.0.1 || 4.0.2`, `@deepseek-ai/schemastery` `3.18.1 || 3.18.2`. 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 strictly enumerate **only compatibility-tested versions** — `@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`, `@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`, `@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.
+
+## What v3.2.0 offers
+
+- **DSH `0.1.7-rc.1` support declared, with `0.1.5-rc.3` kept** (2026-09-24). This release is the first to need an
+  actual code change, because DSH `0.1.7` **relocates plugin configuration**: see the next section.
+
+### Two config backends, one build
+
+Since DSH `0.1.7`, plugin configuration stopped living in `<DSH_HOME>/settings.yaml`. On first boot, `0.1.7`
+**renames that file to `settings.yaml.imported`** and copies each section into the profile patch
+(`~/.dsh/profiles/<profile>/cordis.patch.yml`) as the `config:` of the matching loader entry; from then on the
+`settings` service owns it, and plugins read it through an injected `config` parameter instead of touching the
+YAML file. `ctx.settings.get()` / `register()` / `installSection()` — the rc.x API — **no longer exist** on `0.1.7`.
+
+This plugin therefore auto-detects the backend at startup and keeps both paths working:
+
+| | DSH `0.1.5-rc.3` (and older rc.x) | DSH `0.1.7-rc.1` (and newer) |
+|---|---|---|
+| Where pools live | `<DSH_HOME>/settings.yaml`, section `key-fallback:` | profile patch, the `key-fallback` entry's `config` |
+| How the plugin reads/writes | reads/writes that YAML file directly (with timestamped backups) | `config.providers` is a live volatile ref; writes go through `settings.replace()` |
+| Detection | no volatile-schema support ⇒ file backend | `Config` declares a volatile field ⇒ backend comes from `config` |
+
+Two implementation notes that matter if you port this pattern elsewhere:
+
+1. **`Config` must exist, or the migration silently drops your config.** `0.1.7`'s import path calls
+   `settings.update(ns, values)`, which throws unless the entry declares a **volatile** field; on failure it logs
+   `settings: section ... was not imported` and the section survives only inside `settings.yaml.imported`. So
+   `v3.2.0` exports `Config = z.object({ providers: <dict>.volatile() })`.
+2. **The volatile API differs between the two schemastery builds.** `.volatile()` is available in schemastery
+   `3.18.4` (`0.1.7`) but **not** in `3.18.2` (`rc.3`) — calling it there returns `undefined` and registering a
+   schema without it would change rc.3 behaviour. The export is therefore guarded:
+   `typeof field.volatile === 'function' ? z.object({ providers: field.volatile() }) : undefined` — rc.3 gets
+   **no** `Config` (byte-identical behaviour to v3.1.x) while `0.1.7` gets the volatile one.
+
+The values from `config.providers` are deep-frozen by DSH, so `readSettings()` hands callers a mutable deep copy;
+writes are applied optimistically to an in-memory copy and flushed via `settings.replace()` (an unresolved-write
+counter prevents the UI from briefly re-reading the pre-write tree).
+
+Both backends were exercised end-to-end on real installs: read (both providers appear in `/dsh-key-fallback/pools`
+with live env-key values), create/update/delete (POST/DELETE round-trip, persisted), and the rc.3 regression
+(`settings.yaml` untouched and *not* renamed, `cordis.patch.yml` still `[]`, backups still written).
+
+## What v3.1.7 offers
+
+- **DSH `0.1.5-rc.2` support declared** (2026-09-15). Source check: `@deepseek-ai/dsh-credentials` / `dsh-llm` / `dsh-settings` `0.1.5-rc.1 → rc.2` differ in **`package.json` only** — every lib/docs file is SHA256-identical. Runtime check: strict peer install (no `--legacy-peer-deps`) against a real `dsh@0.1.5-rc.2` web profile + clean boot, zero browser-console errors, `/dsh-key-fallback/*` routes serve, Settings → API Key 回退 renders.
+- **DSH `0.1.6-alpha.1` support declared** (2026-09-15, source-level file-hash diff **plus a runtime boot smoke test** on a real `0.1.6-alpha.1` install). No code change was needed: `@deepseek-ai/dsh-credentials` and `@deepseek-ai/dsh-settings` are **byte-identical in `lib/`** vs `0.1.5-rc.2` (version/docs bump only), and `@deepseek-ai/dsh-llm`'s removals (`priceImages`, the `projectImagesForTextModel`/request-image-offload family) are outside every API this plugin calls — `credentialRef`, `credentials.resolve/set/unset/describe`, `llm.listProviders/listConfigurableProviders`, `agent/request`, `agent/request-error`, `settings`, `webServer` all verified present (`dsh-host-webserver` — the `webServer.register` provider — is itself byte-identical). Runtime check: plugin activates, `/dsh-key-fallback/*` routes serve, Settings → API Key 回退 renders. Old versions stay supported — both `0.1.5-rc.2` and `0.1.6-alpha.1` are *appended*, nothing dropped.
 
 ## What v3.1.6 offers
 
@@ -76,7 +122,7 @@ dsh plugin --profile web add link:D:/WorkSpace/omdp/dsh-key-fallback
 ## Known limitations
 
 - Cooldown is a fixed per-pool `cooldownMs` (no exponential backoff); a cooled key becomes live again when the timer expires.
-- The plugin manages rotation/cooldown state in-memory plus persisted pool config (`keyFallback.providers` in `settings.yaml`); a DSH restart re-reads config and recomputes live status.
+- The plugin manages rotation/cooldown state in-memory plus persisted pool config; a DSH restart re-reads config and recomputes live status. On DSH `0.1.5-rc.3` and older that config is the `key-fallback` section of `<DSH_HOME>/settings.yaml`; on `0.1.7`+ it is the `key-fallback` entry's `config` inside `~/.dsh/profiles/<profile>/cordis.patch.yml`.
 - The env key cannot be deleted through the UI (it is the pool's identity).
 
 ## License

package/README.zh-CN.md

@@ -1,16 +1,61 @@
 # @omdp/dsh-key-fallback
 
-English | [简体中文](README.md)
+[English](README.md) | 简体中文
 
 **为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 提供多 key 池 + 自动轮换**——插件位于 LLM 适配器与凭证存储之间：每次请求前从按 provider 分组的 key 池里选一把，预写入该 provider 的凭证引用；遇到配置的触发错误时，把失败 key 标记为冷却（固定 `cooldownMs`，无指数退避）并前进到下一把。**重发完全交给 DSH 自带的 `dsh-llm-retry`**——本插件从不自行重发，只负责换 key，重试策略由 retry policy 决定。
 
-当前版本：**v3.1.6**（v6 UI 代）。
+当前版本：**v3.2.0**（v7 UI 代）。
 
 ## 环境要求
 
 - DeepSeek Harness 带 `web` profile GUI（`npx @deepseek-ai/dsh web`）
 - Node.js `^22.19` 或 `>=24`
-- 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`、`@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`、`@deepseek-ai/cordis` `4.0.1 || 4.0.2`、`@deepseek-ai/schemastery` `3.18.1 || 3.18.2`。不使用 `<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 范围**只枚举已实际进行过兼容测试的版本**——`@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`、`@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`、`@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`）无需改动插件。
+
+## v3.2.0 新增
+
+- **声明支持 DSH `0.1.7-rc.1`，同时保留 `0.1.5-rc.3`**（2026-09-24）。这是本插件首个需要改动代码的版本，原因是 DSH `0.1.7`
+  **改变了插件配置的存放位置**——详见下节。
+
+### 两种配置后端，同一份构建
+
+自 DSH `0.1.7` 起，插件配置不再位于 `<DSH_HOME>/settings.yaml`。首次启动时 `0.1.7` 会把该文件
+**改名成 `settings.yaml.imported`**，并把每个段的内容写入 profile 补丁
+（`~/.dsh/profiles/<profile>/cordis.patch.yml`）中对应 loader 条目的 `config:`；此后由 `settings` 服务托管，
+插件通过注入的 `config` 参数读取，而不再自行读写该 YAML。rc.x 时代的 `ctx.settings.get()` /
+`register()` / `installSection()` 在 `0.1.7` 上**已不存在**。
+
+因此本插件在启动时自动判别后端，两条路径同时可用：
+
+| | DSH `0.1.5-rc.3`（及更早 rc.x） | DSH `0.1.7-rc.1`（及更新） |
+|---|---|---|
+| 池配置位置 | `<DSH_HOME>/settings.yaml` 的 `key-fallback:` 段 | profile 补丁中 `key-fallback` 条目的 `config` |
+| 插件如何读写 | 直接读写该 YAML 文件（附时间戳备份） | `config.providers` 是活的 volatile ref；写入走 `settings.replace()` |
+| 判别方式 | 无 volatile schema 支持 ⇒ 文件后端 | `Config` 声明了 volatile 字段 ⇒ 后端来自 `config` |
+
+移植该模式时有两个关键点：
+
+1. **必须声明 `Config`，否则迁移会静默丢弃配置。** `0.1.7` 的导入路径调用
+   `settings.update(ns, values)`，若该条目没有声明 **volatile** 字段就会抛错，仅打印
+   `settings: section ... was not imported`，配置只残留在 `settings.yaml.imported` 里。因此
+   `v3.2.0` 导出 `Config = z.object({ providers: <dict>.volatile() })`。
+2. **volatile API 在两种 schemastery 构建上不同。** `.volatile()` 在 schemastery `3.18.4`（`0.1.7`）上可用，
+   但在 `3.18.2`（`rc.3`）上**不存在**——在那里调用会得到 `undefined`，而若据此注册一个无 volatile 的
+   schema 就会改变 rc.3 的行为。故导出做了守卫：
+   `typeof field.volatile === 'function' ? z.object({ providers: field.volatile() }) : undefined`——
+   rc.3 拿到 **没有** `Config`（行为与 v3.1.x 逐字节一致），`0.1.7` 拿到含 volatile 的那一份。
+
+`config.providers` 的值被 DSH 深度冻结，故 `readSettings()` 向调用方返回可变深拷贝；写入先乐观地更新内存副本
+再经 `settings.replace()` 落盘（未决写入计数避免 UI 短暂读回写入前的旧树）。
+
+两条后端均已在真实安装上端到端实测：读取（两个 provider 都出现在 `/dsh-key-fallback/pools`，含 env key 实时值）、
+增删改（POST/DELETE 往返并落盘）、以及 rc.3 回归（`settings.yaml` 未被改名也未改内容、`cordis.patch.yml` 仍为
+`[]`、备份照旧生成）。
+
+## v3.1.7 新增
+
+- **声明支持 DSH `0.1.5-rc.2`**（2026-09-15）。源码核查：`@deepseek-ai/dsh-credentials` / `dsh-llm` / `dsh-settings` 从 `0.1.5-rc.1` 到 `rc.2` **只有 `package.json` 变化**——lib/文档逐文件 SHA256 全一致。运行时核查：对真实 `dsh@0.1.5-rc.2` web profile **严格模式**安装 peer（不加 `--legacy-peer-deps`）零告警通过，启动零浏览器控制台错误，`/dsh-key-fallback/*` 路由服务，设置页「API Key 回退」渲染。
+- **声明支持 DSH `0.1.6-alpha.1`**（2026-09-15，源码级逐文件哈希比对 + **真实运行时冒烟**：在临时安装的 `0.1.6-alpha.1` 上以 web profile 实测加载）。未改动任何代码：`@deepseek-ai/dsh-credentials` 与 `@deepseek-ai/dsh-settings` 的 `lib/` 相对 `0.1.5-rc.2` **逐字节一致**（仅版本号/文档变化），`@deepseek-ai/dsh-llm` 的删除项（`priceImages`、`projectImagesForTextModel`/request-image-offload 系列）均在本插件调用面之外——本插件调用的 `credentialRef`、`credentials.resolve/set/unset/describe`、`llm.listProviders/listConfigurableProviders`、`agent/request`、`agent/request-error`、`settings`、`webServer` 全部实测保留（`webServer` 提供方 `dsh-host-webserver` 整包字节一致）。运行时验证：插件激活、`/dsh-key-fallback/*` 路由服务、设置页「API Key 回退」渲染。**旧版本继续兼容**——`0.1.5-rc.2` 与 `0.1.6-alpha.1` 均为**追加**进枚举，未删除任何版本。
 
 ## v3.1.6 新增
 
@@ -76,7 +121,7 @@ dsh plugin --profile web add link:D:/WorkSpace/omdp/dsh-key-fallback
 ## 已知限制
 
 - 冷却为每池固定 `cooldownMs`（无指数退避）；冷却到期 key 自动恢复 live。
-- 轮换/冷却状态为内存态 + 持久化池配置（`settings.yaml` 的 `keyFallback.providers`）；DSH 重启会重读配置并重算 live 状态。
+- 轮换/冷却状态为内存态 + 持久化池配置；DSH 重启会重读配置并重算 live 状态。在 DSH `0.1.5-rc.3` 及更早版本上，该配置是 `<DSH_HOME>/settings.yaml` 的 `key-fallback` 段；在 `0.1.7`+ 上则是 `~/.dsh/profiles/<profile>/cordis.patch.yml` 中 `key-fallback` 条目的 `config`。
 - env key 不能通过 UI 删除（它是池的身份标识）。
 
 ## License

package/lib/index.js

@@ -32,9 +32,16 @@ function deriveEnvName(name) {
 export const name = 'key-fallback'
 export const inject = ['llm', 'settings', 'webServer', 'credentials']
 const API_BASE = '/dsh-key-fallback'
-const SETTINGS_FILE = join(homedir(), '.dsh', 'settings.yaml')
-const CRED_FILE = join(homedir(), '.dsh', '.credentials.yaml')
-const BACKUP_DIR = join(homedir(), '.dsh', 'backups')
+// 遵循 DSH_HOME（未设置时回落 ~/.dsh）：与 dsh-connector / dsh-archived-sessions 的
+// 路径推导保持一致，也让隔离冒烟环境可以直接切换整个 home。
+const DSH_HOME = (() => {
+  const h = process.env.DSH_HOME
+  return (typeof h === 'string' && h) ? h : join(homedir(), '.dsh')
+})()
+const SETTINGS_FILE = join(DSH_HOME, 'settings.yaml')
+const SETTINGS_FILE_IMPORTED = SETTINGS_FILE + '.imported'
+const CRED_FILE = join(DSH_HOME, '.credentials.yaml')
+const BACKUP_DIR = join(DSH_HOME, 'backups')
 if (!existsSync(BACKUP_DIR)) try { mkdirSync(BACKUP_DIR, { recursive: true }) } catch (e) {}
 let _backupCounter = 0
 function tsName(prefix) {
@@ -66,21 +73,80 @@ const profileSchema = z.object({
   refsCompacted: z.boolean().default(false),
 })
 
-function readSettings() {
-  if (!existsSync(SETTINGS_FILE)) return { providers: {} }
+// ── 配置后端（双版本兼容）─────────────────────────────────────────────
+// 0.1.5-rc.3：配置在 <home>/settings.yaml 的 `key-fallback:` 段，插件自己读写该文件。
+// 0.1.7+   ：DSH 启动时把 settings.yaml 改名为 settings.yaml.imported，段内容成为该 entry 的
+//            config override（写进 profiles/<p>/cordis.patch.yml），由 ctx.settings 服务托管；
+//            插件通过「volatile Config + describe/replace」读写，不再碰 settings.yaml。
+//
+// 关键前提：0.1.7 的迁移走 settings.update(ns, values) → write()，要求该 entry 存在且其
+// Config 含 volatile 字段，否则抛错并打印「section ... was not imported」——配置静默丢失。
+// 因此必须声明 Config（下面），且只在本版本 schemastery 支持 .volatile() 时声明，
+// 使 rc.3 行为与改造前逐字节一致。
+const _providersField = z.dict(z.any()).default({})
+export const Config = (typeof _providersField.volatile === 'function')
+  ? z.object({ providers: _providersField.volatile() })
+  : undefined
+
+const ENTRY_ID = 'key-fallback'
+const diagLog = []
+const diag = (kind, msg) => {
   try {
-    const raw = readFileSync(SETTINGS_FILE, 'utf8')
-    const doc = loadYaml(raw) || {}
-    const block = (doc && (doc['key-fallback'] || doc.keyFallback)) || {}
-    return block && block.providers ? block : { providers: {} }
-  } catch (e) { return { providers: {} } }
+    diagLog.push({ kind, msg: String(msg).slice(0, 300), at: Date.now() })
+    if (diagLog.length > 200) diagLog.splice(0, diagLog.length - 200)
+  } catch (e) {}
+}
+let _settingsSvc = null   // ctx.settings（0.1.7+）
+let _liveRef = null       // 0.1.7+: config.providers 的 volatile Ref（原地热更新）
+let _cache = null         // 0.1.7+: 内存权威副本（乐观写，避免异步落盘窗口内读到旧值）
+let _writing = 0          // 未确认写入计数
+
+function readSettingsFromFile() {
+  // settings.yaml 优先；0.1.7 迁移后已改名，回退读 .imported（只读引导，避免配置真空）
+  for (const file of [SETTINGS_FILE, SETTINGS_FILE_IMPORTED]) {
+    if (!existsSync(file)) continue
+    try {
+      const doc = loadYaml(readFileSync(file, 'utf8')) || {}
+      const block = (doc && (doc[ENTRY_ID] || doc.keyFallback)) || {}
+      if (block && block.providers) return block
+    } catch (e) {}
+  }
+  return { providers: {} }
+}
+
+function cloneJson(v) {
+  try { return v === undefined ? {} : JSON.parse(JSON.stringify(v)) } catch (e) { return v }
+}
+
+function readSettings() {
+  if (_liveRef) {
+    // _liveRef 就是 config.providers 这个 Ref：.get() 直接返回 providers 字典。
+    // 它由 DSH deepFreeze，调用方却要就地改（新增/删除 provider、compactRefs 改 keyRefs），
+    // 所以这里始终返回「可变深拷贝」。未决写入期间以内存副本为源（replace 是异步的，
+    // 否则会读到落盘前的旧树，UI 立刻刷新会闪回旧值）。
+    let src = _cache
+    if (_writing === 0) { try { src = { providers: _liveRef.get() || {} } ; _cache = src } catch (e) {} }
+    if (!src) { try { src = { providers: _liveRef.get() || {} }; _cache = src } catch (e) { src = { providers: {} } } }
+    return { providers: cloneJson(src.providers) || {} }
+  }
+  return readSettingsFromFile()
 }
 
 function writeSettings(data) {
+  if (_liveRef) {
+    _cache = { providers: cloneJson((data && data.providers) || {}) }
+    if (!_settingsSvc || typeof _settingsSvc.replace !== 'function') return
+    _writing++
+    Promise.resolve()
+      .then(() => _settingsSvc.replace(ENTRY_ID, { providers: cloneJson(_cache.providers) }))
+      .catch((e) => diag('settings-write', 'replace failed: ' + ((e && e.message) || e)))
+      .finally(() => { _writing-- })
+    return
+  }
   backupFile(SETTINGS_FILE, 'settings')
   let root = {}
   try { if (existsSync(SETTINGS_FILE)) root = loadYaml(readFileSync(SETTINGS_FILE, 'utf8')) || {} } catch (e) {}
-  root['key-fallback'] = data
+  root[ENTRY_ID] = data
   writeFileSync(SETTINGS_FILE, dumpYaml(root, { lineWidth: 120 }), 'utf8')
 }
 
@@ -168,11 +234,26 @@ function displayNameOf(entry) {
   return ref
 }
 
-export function apply(ctx) {
-  try { ctx.logger.info('key-fallback: v6 host apply() starting (config = settings.yaml)') } catch (e) {}
-  const diagLog = []
-  const diag = (kind, msg) => { try { diagLog.push({ kind, msg: String(msg).slice(0, 300), at: Date.now() }); if (diagLog.length > 200) diagLog.splice(0, diagLog.length - 200) } catch (e) {} }
+export function apply(ctx, config) {
+  try { ctx.logger.info('key-fallback: v7 host apply() starting') } catch (e) {}
   diag('apply', 'host loaded')
+
+  // ── 0.1.7+：把配置接到 settings 服务托管的那份树 ──
+  // config.providers 平时是 volatile Ref（.get() 随编辑热更新）；无 config 或非 Ref 时
+  // 保持文件后端。两者都在这里判定一次，之后 readSettings/writeSettings 自动分流。
+  try {
+    const svc = ctx.get('settings')
+    const prov = config && config.providers
+    if (svc && typeof svc.replace === 'function' && prov && typeof prov.get === 'function') {
+      _settingsSvc = svc
+      _liveRef = prov   // = config.providers，Ref.get() 直接给 providers 字典
+      _cache = { providers: prov.get() || {} }
+      diag('settings', 'backend = profile entry (0.1.7+), providers=' + Object.keys(_cache.providers).join(','))
+      // 无需额外订阅：readSettings() 每次（无未决写入时）都从 Ref 重取，外部编辑自动生效
+    } else {
+      diag('settings', 'backend = settings.yaml file (rc.x)')
+    }
+  } catch (e) { diag('settings', 'probe failed: ' + ((e && e.message) || e)) }
   // ── 包装 credentials.resolve：ref 命中池 env 时返回池当前 key（llm-pi-ai 唯一读取入口）──
   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 迁移。Settings → API Key 回退 UI. v6.1.",
-  "version": "3.1.6",
+  "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.2.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -38,10 +38,10 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.1 || 4.0.2",
-    "@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",
-    "@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",
-    "@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",
-    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2"
+    "@deepseek-ai/cordis": "4.0.1 || 4.0.2 || 4.0.4",
+    "@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",
+    "@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",
+    "@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",
+    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2 || 3.18.4"
   }
 }