@omdp/dsh-key-fallback 3.1.7 → 3.2.1

package/README.md

@@ -4,13 +4,75 @@
 
 **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.7** (`v6` UI generation).
+Current version: **v3.2.1** (`v7` UI generation).
+
+## What v3.2.1 offers
+
+- **Rescues pools stranded in `settings.yaml.imported`** (2026-09-24). `0.1.7`'s one-shot importer
+  **renames `settings.yaml` to `settings.yaml.imported` before it writes anything**, so if a section fails to
+  import (e.g. the target entry declares no volatile field) it never retries and the pools sit in
+  `.imported` forever. The symptom is exactly: badge shows **"尚未启用"** and the page shows
+  **"还没有任何池，点上方「启用新 provider 池」开始。"** even though the pools are on disk.
+  Note the file fallback was *already* there in v3.2.0 (`readSettingsFromFile()` falls back to
+  `settings.yaml.imported`) — but on `0.1.7` it is **never reached**, because `readSettings()` returns from the
+  live-ref branch first whenever `_liveRef` is set, and the ref holds `{}`. What was missing was a **bridge
+  between the two backends**, not another read fallback.
+  `v3.2.1` performs a **one-time explicit migration** on the first HTTP request (not in `apply()` — see below):
+  when the live config has zero providers *and* the legacy file has some, it writes them into the profile entry via
+  `settings.replace()`. A marker file (`<DSH_HOME>/.key-fallback-migrated`) makes it genuinely once-only, so
+  deliberately deleting every pool does not resurrect them on the next boot.
+  - **Why not in `apply()`:** `settings.replace()` goes through `configEditor.edit()` and requires the entry's fiber
+    to be **ACTIVE** — `describe()` skips entries whose `fiber.state !== 2`, and during `apply()` the fiber is still
+    being created, so the call throws `No configurable plugin entry`. The first UI request (`/pools`) is the
+    earliest safe moment.
+  - The marker is written **only after** the persist succeeds, so a failed write is retried on the next boot.
 
 ## 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 || 0.1.5-rc.2 || 0.1.6-alpha.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.6-alpha.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
 
@@ -81,7 +143,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,74 @@
 # @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.7**（v6 UI 代）。
+当前版本：**v3.2.1**（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 || 0.1.5-rc.2 || 0.1.6-alpha.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.6-alpha.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.1 新增
+
+- **救回滞留在 `settings.yaml.imported` 里的池**（2026-09-24）。`0.1.7` 的一次性导入器会在写入任何东西**之前**
+  先把 `settings.yaml` 改名为 `settings.yaml.imported`——所以某段导入失败时（典型：目标条目没声明 volatile 字段）
+  它永远不会重试，池子会永久留在 `.imported` 里。表现恰是：徽标显示 **「尚未启用」**、页面显示
+  **「还没有任何池，点上方「启用新 provider 池」开始。」**，尽管池子就在磁盘上。
+  注意**文件回退在 v3.2.0 里本来就写了**（`readSettingsFromFile()` 会在 `settings.yaml` 缺失时退读
+  `settings.yaml.imported`）——但在 `0.1.7` 上它**永远轮不到**：只要 `_liveRef` 非空，
+  `readSettings()` 第一行就从 live-ref 分支返回，而 ref 里是 `{}`。**真正缺的不是又一个读回退，
+  而是两个后端之间的一座桥。**
+  `v3.2.1` 在**首个 HTTP 请求**时做一次性显式搬运（不在 `apply()` 里——原因见下）：
+  当 live 配置里 provider 数为 0 *且* 旧文件里有池时，经 `settings.replace()` 写进 profile 条目。
+  标记文件（`<DSH_HOME>/.key-fallback-migrated`）保证「真正只做一次」，因此有意删光所有池后不会在下次启动被复活。
+  - **为什么不能放在 `apply()`：** `settings.replace()` 走 `configEditor.edit()`，要求本 entry 的 fiber 已
+    **ACTIVE**——`describe()` 会跳过 `fiber.state !== 2` 的条目，而 `apply()` 执行时 fiber 还在创建中，
+    调用必抛 `No configurable plugin entry`。首个 UI 请求（`/pools`）才是最早的安全时机。
+  - 标记**只在落盘成功之后**才写，因此写失败会在下次启动重试。
+
+## 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 新增
 
@@ -81,7 +139,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,18 @@ 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')
+// 一次性 legacy→profile 迁移的标记（见 apply() 里的迁移块）。
+const MIGRATED_MARKER = join(DSH_HOME, '.key-fallback-migrated')
 if (!existsSync(BACKUP_DIR)) try { mkdirSync(BACKUP_DIR, { recursive: true }) } catch (e) {}
 let _backupCounter = 0
 function tsName(prefix) {
@@ -66,21 +75,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 +236,59 @@ 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)) }
+
+  // ── 一次性迁移：老 settings.yaml(.imported) 里的池 → settings 托管的 entry config ──
+  // 0.1.7 的 importLegacyDocument() 在首次写入前就把 settings.yaml 改名成
+  // settings.yaml.imported，而本机的池恰好躺在 .imported 里 —— 迁移入口已永久失活，
+  // 池不会自己回到 UI（表现为徽标「尚未启用」+「还没有任何池」）。
+  //
+  // 必须在首个 HTTP 请求时做，不能在这里（apply 期间）做：settings.replace() 走
+  // configEditor.edit()，要求本 entry 的 fiber 已 ACTIVE（describe() 会跳过
+  // state !== 2 的 entry），apply() 执行时 fiber 尚在创建中，必然抛
+  // "No configurable plugin entry"。UI 打开设置页就会请求 /pools，时机正好。
+  // 标记文件保证「真正只做一次」：否则用户有意清空所有池后，下次启动又会灌回来。
+  let _migrationAttempted = false
+  async function ensureLegacyMigration() {
+    if (_migrationAttempted) return
+    _migrationAttempted = true
+    try {
+      if (!_liveRef || existsSync(MIGRATED_MARKER)) return
+      if (Object.keys((_cache && _cache.providers) || {}).length > 0) return
+      const migrated = (readSettingsFromFile() || {}).providers || {}
+      const names = Object.keys(migrated)
+      if (names.length === 0) {
+        // 无可搬运内容：也落标记（空文件算「已处理过」），避免每次启动重复探测。
+        try { writeFileSync(MIGRATED_MARKER, new Date().toISOString() + '\n', 'utf8') } catch (e) {}
+        return
+      }
+      // 直接 await 真正的 replace：只有落盘成功才写标记，否则下次启动还能重试。
+      if (!_settingsSvc || typeof _settingsSvc.replace !== 'function') return
+      _cache = { providers: cloneJson(migrated) }
+      await _settingsSvc.replace(ENTRY_ID, { providers: cloneJson(migrated) })
+      try { writeFileSync(MIGRATED_MARKER, new Date().toISOString() + '\n', 'utf8') } catch (e) {}
+      diag('migrate', 'imported ' + names.length + ' provider(s) from settings.yaml(.imported): ' + names.join(','))
+    } catch (e) { diag('migrate', 'failed: ' + ((e && e.message) || e)) }
+  }
   // ── 包装 credentials.resolve：ref 命中池 env 时返回池当前 key（llm-pi-ai 唯一读取入口）──
   const poolsByEnv = new Map()
   const credSvc = ctx.credentials
@@ -460,6 +576,11 @@ export function apply(ctx) {
   if (webServer) {
     const route = async (req, res) => {
       try {
+        // 首次请求时补做 legacy 池迁移（此时 fiber 已 ACTIVE，settings.replace 可用）。
+        // 放在所有分支之前，保证无论 UI 先请求哪个端点，池都已被搬进 live 配置。
+        // 首次请求时补做 legacy 池迁移（此时 fiber 已 ACTIVE，settings.replace 可用）。
+        // 放在所有分支之前，保证无论 UI 先请求哪个端点，池都已被搬进 live 配置。
+        await ensureLegacyMigration()
         const url = new URL(req.url, 'http://127.0.0.1')
         const path = url.pathname.replace(new RegExp('^' + API_BASE + '/?'), '').replace(/\/$/, '')
         const readBody = () => new Promise((resolve, reject) => {

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.7",
+  "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.1",
   "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 || 0.1.5-rc.2 || 0.1.6-alpha.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.6-alpha.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.6-alpha.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"
   }
 }