@loommii/dsh-provider-usage 0.7.0 → 0.8.0

package/README.md

@@ -1,9 +1,17 @@
 # dsh-provider-usage — DSH「用量中心」
 
-> 当前版本 **v0.7.0** · npm `@loommii/dsh-provider-usage` · [更新历史](docs/CHANGELOG.md)
+> 当前版本 **v0.8.0** · npm `@loommii/dsh-provider-usage` · [更新历史](docs/CHANGELOG.md)
 
 DSH Web GUI 插件 **「用量中心」**：一个常驻右下角的用量卡片，实时显示你的 AI 服务用量 / 余额，不用再打开网页查；附带本地 Token 统计页，不联网也能看自己今天用了多少。
 
+## v0.8.0 更新摘要（适配 dsh 0.1.2-alpha）
+
+- **适配 dsh `0.1.2-alpha` 破坏性重构**：修复升级后「设置页无用量中心 / 卡片消失」与
+  `duplicate loader entry id` 启动崩溃（根因：v0.6.0 包名迁移时 `cordis.patch.yml` 与
+  client 注册 id 仍用旧名，叠加 alpha 新的客户端发现机制导致静默失联）
+- host 侧 API 契约、会话文件解析、平台注入（react / slots）经逐项核对在 alpha.4 全部兼容
+- 完整变更与用户升级指引见 [CHANGELOG](docs/CHANGELOG.md)
+
 ## v0.6.0 更新摘要
 
 - **新增提供方 Command Code（订阅+余额混合卡）**：5 小时 / 周 / 月窗口使用量 + 月度剩余额度（USD），主数字为月已用百分比
@@ -72,6 +80,10 @@ dsh plugin --profile web remove @loommii/dsh-provider-usage
 ## 使用说明
 
 - 提供方实例的增删改、Key 设置都在 **设置 → 用量中心** 里完成，改动即时生效，无需重启
+- 每个实例可在**编辑**里用「启用」开关管理状态：**开 = 启用（绿）/ 关 = 暂停（灰）**，保存后生效；
+  新添加的提供方默认启用。暂停后该实例**不再轮询查询**（卡片 30s 自动刷新跳过它），
+  卡片切换菜单里也**不可选**；暂停的若是当前卡片实例会自动切到其他启用实例，全部暂停时卡片隐藏。
+  启用/暂停只影响查询与卡片选择，编辑 / 删除 / Key 配置都原样保留
 - 设置页有两个标签：「提供方」管理实例，「用量统计」查看本地 Token 统计
 - 设置保存在本机浏览器中；删掉实例不会上传或泄露任何 Key
 - 卡片拖动后的位置会自动保存，下次打开还是老位置

package/cordis.patch.yml

@@ -1,7 +1,10 @@
 # dsh-provider-usage M1: 插入插件行（自动 reconcile 进 profile bundles）
+# v0.8.0: name 使用正式包名 @loommii/dsh-provider-usage（与 package.json 一致）。
+# 0.7.0 及以前误用改名前的旧名 dsh-provider-usage，在 dsh 0.1.2-alpha 上
+# 只能靠 profile node_modules 里的旧名残留符号链接解析——重装后插件即失联。
 - insert:
     - id: provider-usage
-      name: dsh-provider-usage
+      name: '@loommii/dsh-provider-usage'
       config:
         baseUrl: https://opencode.ai/zen/go   # {{baseUrl}}/v1/usage 即官方 usage 接口
         timeoutMs: 15000

package/docs/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## v0.8.0（2026-09-03）
+
+### 修复：重启/存储丢失后提供方清单被静默重建（严重数据丢失）
+
+**原先的现象**：在用量中心删除某提供方（如 OpenCode Go）后，浏览器存储里的实例清单一旦丢失
+（`dsh web` 重启且访问 origin 变化、清站点数据、浏览器驱逐临时存储、换浏览器等），下次打开页面
+**已删除的默认实例（OpenCode Go/DeepSeek）会凭空复活，而自定义提供方（如 Command Code，`customOnly`
+不在默认清单里）永久消失**；其私有库 Key 成为孤儿，只能重新手动添加。用户实测即「之前删了 OpenCode Go，
+重启后变成 Command Code 被删了」。
+
+**根因**：提供方实例清单此前**只存浏览器 localStorage**（host 端零持久化），且
+`loadProviders()` 在存储 key 读取失败时静默走 `DEFAULT_PROVIDERS` 兜底重建默认清单；
+host 也没有任何路由能枚举私有库 Key 供启动对账。
+
+**修复后的现象**：提供方实例清单以 host 端 `$DSH_HOME/provider-usage/providers.json` 为
+**单一事实源**（0600，与 credentials.json 同边界），localStorage 降级为写穿透缓存；
+浏览器存储全部丢失后重启，清单从 host 完整恢复，删除仍然生效、自定义实例不再消失。
+
+- **host 新增 `GET/POST /api/provider-usage/providers`**（仅回环；POST 整单覆盖保存，幂等）
+  - 条目逐个规范化校验：未知 adapter / 缺 id 的脏条目剔除而非整单拒绝；`paused` 严格归一为布尔；
+    `ref/name/source/type` 长度钳制；上限 64 个实例
+  - 原子写（tmp → rename）+ 0600；损坏文件改名 `providers.json.corrupt-<ts>` 留证并按缺失处理，
+    不卡死恢复流程；目录缺失时自动创建
+- **client 启动恢复**：`useProviders` 首个订阅者触发一次 `GET /providers` 去重恢复；
+  host 有清单 → 应用为当前清单；host 无文件（首次升级 0.8.0）→ 把本地缓存清单一次性写回 host 固化；
+  host 失联 → 继续用本地缓存（乐观值），后续写操作会重试落盘
+- **恢复竞态守卫**：恢复响应迟到且期间用户已增删改实例时，放弃 host 过期数据，
+  不把用户刚删的实例复活（按会话内写计数判定）
+- **`setProviders` 支持函数式更新**（修复同族丢更新竞态）：所有写方（删除/导入/手动添加/编辑/
+  旧数据自愈）改为基于写入时刻的最新清单计算，快速连删两个实例不再复活第一个、
+  自愈写入不再覆盖刚添加的实例；传数组仍兼容旧用法
+- host 场景 40（路由契约/落盘/跨重启恢复/脏条目剔除/400/损坏隔离，13 断言）
+
+### 小功能
+- **提供方支持启用 / 暂停**：设置 → 用量中心 → 提供方设置，每个实例的**编辑卡**里新增「启用」开关
+  - 语义：**开 = 启用（开关亮绿色）/ 关 = 暂停（灰色）**；编辑后点「保存」生效
+  - 新添加（导入 / 手动）的提供方**默认启用**
+  - 暂停后该实例**不再参与轮询查询**（卡片 30s 自动刷新与设置页打开时的状态查询都跳过它），
+    卡片**切换菜单中不可选**；若暂停的正是卡片当前实例，卡片立即切到另一个启用实例，
+    全部暂停时卡片隐藏；恢复启用后立即重新生效（即时持久化，无需重启/刷新），
+    Key 等配置原样保留
+  - 视觉：编辑卡内官方样式 switch（开=绿 / 关=灰）+ 状态文案；列表中暂停行名称与状态点
+    置灰为「已暂停」，编辑 / 删除仍可用（启用/暂停只影响查询与卡片选择）
+  - 启用/暂停状态随实例清单持久化到 host `providers.json`，跨浏览器/存储丢失后同样保留
+
+### 兼容性修复：适配 dsh 0.1.2-alpha（破坏性变更）
+
+本次 dsh `0.1.1-rc.2 → 0.1.2-alpha.4` 重构后，插件出现两类症状：升级当天 `dsh web` 启动即崩
+（`duplicate loader entry id: provider-usage`），重新安装后变为 **host 半区正常（7 条 API 路由全部注册）
+但 Web UI 静默失联**（设置页无「用量中心」、无常驻卡片）。两个问题的根源都在插件自身的
+「包名迁移残留」与 alpha 新的客户端发现机制不兼容，本版全部修复：
+
+- **`cordis.patch.yml` 的 entry `name` 改为正式包名 `@loommii/dsh-provider-usage`**
+  - v0.6.0 包名迁移（`dsh-provider-usage` → `@loommii/dsh-provider-usage`）时漏改了此文件，
+    此后一直靠 profile `node_modules` 里改名前遗留的旧名符号链接 `dsh-provider-usage → 工作区`
+    才能解析到包（rc.2 环境下侥幸可用）
+  - alpha.4 的客户端扫描（`dsh-client-modules` node 半区 `nearestPackage`）从 loader entry
+    的模块位置向上查找 package.json，且要求 `name === entry 名`；旧名在重装后解析失败 →
+    包被判定为「非客户端包」→ 永不进 `window.__DSH_BOOT__` 组合图 → UI 静默消失（host 不受影响）
+  - 升级首日的 `duplicate loader entry id` 崩溃亦与残留链接相关（旧名/新名两条路径同时进树，
+    loader `EntryGroup.update` 对同 id 双行 fail-loud）；清理残留链接 + 本修复后消除
+- **删除 `dsh.client.inject: ["@deepseek-ai/dsh-client-runtime"]` 死引用**
+  - alpha 重构将 `dsh-client-runtime` 并入 `dsh-client-modules`，该包已不存在；
+    插件 client 半区从未 require 过 runtime 的任何导出，声明本就多余
+  - 两侧加载器对 graph 外的 inject 静默跳过，故这是卫生项而非故障源
+- **`lib/client.js` 的 `__ModuleLoader__.load` 注册 id 同步改为 `@loommii/dsh-provider-usage`**
+  - alpha 的 boot graph 行 id = 包名，`serveBundle` 按 id 应答 combo bundle；注册 id 与
+    graph 行不一致时模块系统找不到 factory（对官方包此场景 fail-loud，对插件即静默失联）
+- **peerDependencies 放宽**：`@deepseek-ai/dsh-host-webserver` `^0.1.0-rc.6` → `>=0.1.0-rc.6`
+  （npm prerelease semver 规则下 `^` 不匹配 `0.1.2-alpha.*`，消除安装时 peer 警告）
+
+### 兼容性核对（对 dsh-v0.1.2-alpha.4 源码逐项验证）
+
+- `ctx.webServer.register({kind:'exact'|'prefix', path, handler(req,res)})` 契约不变（`dsh-host-webserver` 健在）
+- `window.__ModuleLoader__.load({id, factory})` 仍是注册协议；`exports.inject`（`['slots']`）仍被
+  vendored cordis Loader 消费（`Cr.resolve(n.inject)`）
+- 平台 seed 词 `react` / `react-dom/client` / `@deepseek-ai/cordis` / `dsh-client-ui-slots` 全保留
+  （React 仍为 18.3.1）
+- `settings.section` 插槽契约保留（`dsh-client-ui-settings` contract/slots.ts）
+- 会话文件格式：JSONL 后端仍默认（`.jsonl.zstd`、`SESSION_FORMAT_VERSION = 0`、目录布局、
+  `assistant/message` → `data.usage{inputTokens,outputTokens,cacheReadTokens}` 事件行全部不变），
+  本地 Token 统计不受影响；alpha.3 已移除可选 SQLite 后端，此前的前瞻风险解除
+- alpha.4 新增的「web 请求一次性 fetch 审批（SSRF 防护）」为 web 客户端侧，不影响 host 侧出站查询
+
+### 用户升级指引（从 ≤0.7.0 升级到 0.8.0）
+
+若升级 dsh 后曾出现 `duplicate loader entry id: provider-usage`，profile 的 `node_modules`
+里可能残留改名前的旧名符号链接。重装插件即可清理：
+
+```sh
+dsh plugin --profile web remove @loommii/dsh-provider-usage
+dsh plugin --profile web add github:loommii/dsh-provider-usage   # 或 npm: @loommii/dsh-provider-usage
+# 若 node_modules 下仍有 dsh-provider-usage/（旧名，非 @loommii scope）残留目录/链接，手动删除
+```
+
 ## v0.7.0（2026-09-01）
 
 ### 小功能

package/lib/client.js

@@ -3,9 +3,11 @@
 // （OpenCode Go 订阅 / DeepSeek 余额），卡片按结果字段自适应渲染（%+倒计时=订阅卡；
 // 金额+币种=余额卡）。
 // 设置项全部即时生效（localStorage 持久化，无需重启）。
+// v0.8.0: 注册 id 必须等于包名 @loommii/dsh-provider-usage —— dsh 0.1.2-alpha 的
+// boot graph 行 id = 包名，serveBundle 按 id 应答 bundle，不一致即客户端静默失联。
 
 window.__ModuleLoader__.load({
-  id: 'dsh-provider-usage',
+  id: '@loommii/dsh-provider-usage',
   factory: (require) => {
     var module = { exports: {} };
     var exports = module.exports;
@@ -119,6 +121,20 @@ window.__ModuleLoader__.load({
         '.zGbnIq_credentialDot.dsh-pu-dot-gray{background:var(--dsw-alias-label-tertiary,#8b93a7)}',
         '@keyframes dsh-pu-ms-breathe{0%,100%{opacity:1;transform:scale(1)}50%{opacity:.4;transform:scale(.72)}}@media (prefers-reduced-motion:reduce){.dsh-pu-chip.dsh-pu-chip-loading i,.zGbnIq_credentialDot.dsh-pu-dot-loading{animation:none}}',
         '.ms-plus{color:var(--dsw-alias-brand-primary);font-size:15px;line-height:1}',
+        // ── 提供方「启用/暂停」开关（官方 switch 视觉；开=启用=绿 / 关=暂停=灰）──
+        '.dsh-pu-switch{box-sizing:border-box;width:36px;height:20px;background:var(--dsw-alias-border-l3);cursor:pointer;border:0;border-radius:10px;flex:none;padding:2px;position:relative}',
+        '.dsh-pu-switch:hover:not(:disabled){background:var(--dsw-alias-border-l4)}',
+        '.dsh-pu-switch:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}',
+        '.dsh-pu-switch-on{background:var(--dsw-alias-state-success-primary)}',
+        '.dsh-pu-switch-on:hover:not(:disabled){background:var(--dsw-alias-state-success-primary)}',
+        '.dsh-pu-switch-thumb{box-sizing:border-box;background:var(--dsw-alias-label-primary-foreground);border-radius:50%;width:16px;height:16px;display:block;transition:transform .12s}',
+        '.dsh-pu-switch-on .dsh-pu-switch-thumb{transform:translate(16px)}',
+        '.zGbnIq_editorSwitchRow{align-items:center;gap:10px;display:flex}',
+        '.dsh-pu-switchText{color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px}',
+        // ── 提供方列表：暂停行（灰点 + 名称变灰，编辑/删除保持可用）──
+        '.zGbnIq_rowNameDim{color:var(--dsw-alias-label-tertiary)}',
+        '.zGbnIq_rowCard .zGbnIq_credentialDot.dsh-pu-dot-paused{background:var(--dsw-alias-label-tertiary,#8b93a7)}',
+        '.zGbnIq_rowPaused .zGbnIq_rowIdentity .zGbnIq_rowName{color:var(--dsw-alias-label-tertiary)}',
       ].join('');
       var tag = document.createElement('style');
       tag.dataset.plugin = 'dsh-provider-usage';
@@ -169,35 +185,67 @@ window.__ModuleLoader__.load({
       return s;
     }
 
-    // ── 供应商实例清单（localStorage，即时生效）──────────────────────
-    function loadProviders() {
+    // ── 供应商实例清单（v0.8.0：host 端 providers.json 为单一事实源，localStorage 只是写穿透缓存）──
+    // 修复「重启后提供方清单被静默重建」：此前清单只存 localStorage，存储 key 一旦丢失
+    // （换 origin/清站点数据/浏览器驱逐临时存储），启动就走 DEFAULT_PROVIDERS 兜底 →
+    // 已删除的默认实例（OpenCode Go/DeepSeek）复活、自定义实例（如 Command Code）永久消失。
+    // 现在启动时从 host 恢复；host 无数据时才一次性迁移本地缓存/默认清单并立即写回 host。
+    function normalizeProviders(arr) {
+      if (!Array.isArray(arr)) return null;
+      return arr.filter(function (p) {
+        return p && typeof p === 'object' && typeof p.adapter === 'string' && ADAPTER_META[p.adapter];
+      }).map(function (p) {
+        var name = typeof p.name === 'string' && p.name ? p.name : (ADAPTER_META[p.adapter] || {}).displayName;
+        if (String(p.id || '') === 'deepseek-balance' && name === 'DeepSeek 余额') name = 'DeepSeek'; // 0.4.0 更名
+        // source：Key 解析位置（vault=插件私有库直取；dsh=DSH 凭证链）；type：创建方式（import=导入 / manual=自定义）
+        var source = p.source === 'vault' ? 'vault' : 'dsh';
+        // 显式 type 优先；旧数据无 type 时由 source 推导（vault→manual，其余→import）
+        var type = p.type === 'manual' || p.type === 'import' ? p.type : (source === 'vault' ? 'manual' : 'import');
+        // paused：true=暂停（不轮询查询、卡片菜单不可选）；旧数据无该字段 = false（启用）
+        return { id: String(p.id || ''), name: name, adapter: p.adapter, ref: typeof p.ref === 'string' ? p.ref : '', source: source, type: type, paused: p.paused === true };
+      });
+    }
+    function readProvidersCache() {
       try {
-        var arr = JSON.parse(window.localStorage.getItem(PROVIDERS_KEY) || 'null');
-        if (Array.isArray(arr)) {
-          if (arr.length === 0) return []; // 用户删光后保持空清单，不复活默认实例
-          return arr.filter(function (p) {
-            return p && typeof p === 'object' && typeof p.adapter === 'string' && ADAPTER_META[p.adapter];
-          }).map(function (p) {
-            var name = typeof p.name === 'string' && p.name ? p.name : (ADAPTER_META[p.adapter] || {}).displayName;
-            if (String(p.id || '') === 'deepseek-balance' && name === 'DeepSeek 余额') name = 'DeepSeek'; // 0.4.0 更名
-            // source：Key 解析位置（vault=插件私有库直取；dsh=DSH 凭证链）；type：创建方式（import=导入 / manual=自定义）
-            var source = p.source === 'vault' ? 'vault' : 'dsh';
-            // 显式 type 优先；旧数据无 type 时由 source 推导（vault→manual，其余→import）
-            var type = p.type === 'manual' || p.type === 'import' ? p.type : (source === 'vault' ? 'manual' : 'import');
-            return { id: String(p.id || ''), name: name, adapter: p.adapter, ref: typeof p.ref === 'string' ? p.ref : '', source: source, type: type };
-          });
-        }
+        return normalizeProviders(JSON.parse(window.localStorage.getItem(PROVIDERS_KEY) || 'null'));
       } catch (e) { /* ignore */ }
-      return DEFAULT_PROVIDERS.slice();
+      return null;
     }
-    var providersState = loadProviders();
+    function saveProvidersCache(list) {
+      try { window.localStorage.setItem(PROVIDERS_KEY, JSON.stringify(list)); } catch (e) { /* ignore */ }
+    }
+    // host 恢复完成前的乐观缓存：优先用 localStorage 旧数据（多数场景与 host 一致），否则默认清单
+    var providersState = readProvidersCache() || DEFAULT_PROVIDERS.slice();
     var providersListeners = new Set();
+    // 本次页面会话内的写入计数：恢复响应迟到时，若期间用户已写入则放弃应用 host 过期数据（防复活）
+    var providersMutations = 0;
     function saveProviders() {
-      try { window.localStorage.setItem(PROVIDERS_KEY, JSON.stringify(providersState)); } catch (e) { /* ignore */ }
+      // 写穿透：localStorage 缓存 + host 落盘（fire-and-forget；host 失联时本地缓存仍可用）
+      saveProvidersCache(providersState);
+      try {
+        fetch('/api/provider-usage/providers', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify({ providers: providersState }),
+        }).catch(function () { /* ignore */ });
+      } catch (e) { /* ignore */ }
+    }
+    // 内部应用（不记写入数）：host 恢复/一次性迁移专用
+    function applyProvidersUpdate(update) {
+      var next = typeof update === 'function' ? update(providersState) : update;
+      providersState = next;
+      saveProviders();
+      providersListeners.forEach(function (fn) { fn(); });
     }
     function getProviders() { return providersState; }
-    function setProviders(list) {
-      providersState = list;
+    // v0.8.0 修复（丢更新竞态）：所有写方共享同一份 providersState 快照，整体覆盖式写入
+    // 在写入交错时会把先写的整单覆盖掉（如连删两个实例会复活第一个）。
+    // 现支持函数式更新：setProviders(function (prev) { return next; }) —— next 基于写入时刻的最新状态计算；
+    // 兼容旧用法：传数组视为恒等函数。
+    function setProviders(update) {
+      providersMutations += 1;
+      var next = typeof update === 'function' ? update(providersState) : update;
+      providersState = next;
       saveProviders();
       providersListeners.forEach(function (fn) { fn(); });
     }
@@ -205,15 +253,43 @@ window.__ModuleLoader__.load({
       providersListeners.add(fn);
       return function () { providersListeners.delete(fn); };
     }
+    // host 恢复只执行一次（首个订阅者触发；fetch 去重）
+    var hostRestoreStarted = false;
     function useProviders() {
       var [p, setP] = useState(getProviders);
-      useEffect(function () { return subscribeProviders(function () { setP(getProviders()); }); }, []);
+      useEffect(function () {
+        var unsub = subscribeProviders(function () { setP(getProviders()); });
+        if (!hostRestoreStarted) {
+          hostRestoreStarted = true;
+          fetch('/api/provider-usage/providers', { headers: { accept: 'application/json' } })
+            .then(function (r) { return r.json().catch(function () { return null; }); })
+            .then(function (j) {
+              if (!j || !j.ok) return;
+              // 恢复期间用户已做过修改（增删改实例）→ 放弃 host 过期数据，避免把用户刚删的实例复活
+              if (providersMutations > 0) return;
+              if (j.exists && Array.isArray(j.providers)) {
+                // 主路径：host 有清单 → 恢复（host 为单一事实源；本地缓存仅作 host 失联时的乐观值）
+                applyProvidersUpdate(j.providers);
+              } else {
+                // 一次性迁移：host 无文件（首次升级到 0.8.0）→ 把当前缓存清单写回 host 固化
+                applyProvidersUpdate(getProviders());
+              }
+            })
+            .catch(function () { /* host 失联：继续用本地缓存，后续写操作会重试落盘 */ });
+        }
+        return unsub;
+      }, []);
       return p;
     }
-    /** 当前选中实例；若被删除则回落到第一个。 */
+    /** 可用（未暂停）的实例清单：卡片轮询与切换只在这些实例里进行。 */
+    function activeProviders(providers) {
+      return providers.filter(function (p) { return !p.paused; });
+    }
+    /** 当前选中实例；若被删除或已暂停则回落到第一个可用实例（全暂停/无实例 → null）。 */
     function currentProvider(providers, providerId) {
-      for (var i = 0; i < providers.length; i++) if (providers[i].id === providerId) return providers[i];
-      return providers[0] || null;
+      var actives = activeProviders(providers);
+      for (var i = 0; i < actives.length; i++) if (actives[i].id === providerId) return actives[i];
+      return actives[0] || null;
     }
 
     // ── 工具 ──────────────────────────────────────────────────────────
@@ -326,7 +402,7 @@ window.__ModuleLoader__.load({
         return function () { window.removeEventListener('resize', onResize); };
       }, [s.right, s.bottom, s.visible, data]);
       var current = currentProvider(providers, s.providerId);
-      var multiple = providers.length > 1;
+      var multiple = activeProviders(providers).length > 1;
       var curKey = current ? current.id + '|' + current.adapter + '|' + current.ref : 'none';
 
       var load = useCallback(function (force) {
@@ -440,7 +516,7 @@ window.__ModuleLoader__.load({
       var menu = null;
       if (multiple && menuOpen) {
         menu = React.createElement('div', { ref: menuRef, className: 'dsh-pu-menu' },
-          providers.map(function (p) {
+          activeProviders(providers).map(function (p) {
             var active = p.id === current.id;
             var mini = p.adapter === 'balance-json'
               ? React.createElement('img', { src: LOGO_DEEPSEEK, width: 16, height: 16, alt: '' })
@@ -767,6 +843,8 @@ window.__ModuleLoader__.load({
       var [queryStatus, setQueryStatus] = useState({});
       var [errOpen, setErrOpen] = useState({}); // 展开的错误详情（按实例 id）
       var refsKey = providers.map(function (p) { return p.ref || ''; }).join(',');
+      // 暂停态也进依赖：切「恢复/暂停」后让设置页状态查询重新跑（暂停的不查、恢复的马上查）
+      var refsPauseKey = providers.map(function (p) { return (p.paused ? '1' : '0') + ':' + (p.ref || ''); }).join(',');
       // 添加卡：mode = null | 'import' | 'manual'；编辑卡：edit = null | { id, kind, adapter, ref }
       var [mode, setMode] = useState(null);
       var [edit, setEdit] = useState(null);
@@ -777,14 +855,22 @@ window.__ModuleLoader__.load({
       var [formError, setFormError] = useState(null);
 
       function removeProvider(p) {
-        var next = providers.filter(function (x) { return x.id !== p.id; });
         if (p.source === 'vault' && p.ref) {
           // 删除自定义实例时同步清理插件私有库中的 Key（fire-and-forget）
           fetch('/api/provider-usage/credentials?ref=' + encodeURIComponent(p.ref), { headers: { accept: 'application/json' } })
             .catch(function () { /* ignore */ });
         }
-        setProviders(next);
-        if ((s.providerId || '') === p.id) setSettings({ providerId: next.length > 0 ? next[0].id : '' });
+        // v0.8.0：函数式更新 —— 基于写入时刻的最新清单计算，连删/交错写入不再互相覆盖
+        var next = null;
+        setProviders(function (prev) {
+          next = prev.filter(function (x) { return x.id !== p.id; });
+          return next;
+        });
+        // 若当前卡片实例被删除，回落到第一个可用实例（跳过已暂停的）
+        if (currentProvider(next, s.providerId || '') === null) {
+          var first = activeProviders(next)[0];
+          setSettings({ providerId: first ? first.id : '' });
+        }
       }
 
       function openImport() {
@@ -818,8 +904,8 @@ window.__ModuleLoader__.load({
         var item = null;
         for (var i = 0; i < dshItems.length; i++) if (dshItems[i].route === form.provider) item = dshItems[i];
         if (!item) { setFormError('导入项不存在'); return; }
-        var inst = { id: item.route + '-' + Date.now(), name: name, adapter: item.adapter, ref: item.ref, source: 'dsh', type: 'import' };
-        setProviders(providers.concat([inst]));
+        var inst = { id: item.route + '-' + Date.now(), name: name, adapter: item.adapter, ref: item.ref, source: 'dsh', type: 'import', paused: false };
+        setProviders(function (prev) { return prev.concat([inst]); });
         setSettings({ providerId: inst.id });
         setMode(null);
       }
@@ -840,8 +926,8 @@ window.__ModuleLoader__.load({
           });
           var j = await resp.json().catch(function () { return null; });
           if (!j || !j.ok) { setFormError((j && j.error && j.error.message) || '保存 Key 失败'); return; }
-          var inst = { id: instId, name: name, adapter: form.adapter, ref: instId, source: 'vault', type: 'manual' };
-          setProviders(providers.concat([inst]));
+          var inst = { id: instId, name: name, adapter: form.adapter, ref: instId, source: 'vault', type: 'manual', paused: false };
+          setProviders(function (prev) { return prev.concat([inst]); });
           setSettings({ providerId: inst.id });
           setMode(null);
         } catch (e) {
@@ -851,11 +937,12 @@ window.__ModuleLoader__.load({
         }
       }
 
-      // ── 编辑：导入的只改名称；自定义（vault）可改名称 + 覆盖 Key ──
+      // ── 编辑：导入的只改名称 + 启用状态；自定义（vault）可改名称 + 覆盖 Key + 启用状态 ──
+      // enabled = 表单暂存值（false 表示“暂停”）；开关只暂存在表单里，点「保存」才真正写入实例
       function startEdit(p) {
         setMode(null);
-        setEdit({ id: p.id, kind: p.type === 'manual' ? 'manual' : 'import', adapter: p.adapter, ref: p.ref });
-        setForm({ provider: '', name: p.name, adapter: p.adapter, key: '', ref: p.ref, nameTouched: true });
+        setEdit({ id: p.id, kind: p.type === 'manual' ? 'manual' : 'import', adapter: p.adapter, ref: p.ref, paused: !!p.paused });
+        setForm({ provider: '', name: p.name, adapter: p.adapter, key: '', ref: p.ref, nameTouched: true, enabled: !p.paused, _editId: p.id });
         setFormError(null);
       }
 
@@ -883,10 +970,30 @@ window.__ModuleLoader__.load({
             setBusy(false);
           }
         }
-        setProviders(providers.map(function (p) { return p.id === edit.id ? Object.assign({}, p, { name: name }) : p; }));
+        // 名称 + 启用状态在同一次 setProviders 里写入（避免两次基于旧数组的写入互相覆盖）
+        var enabled2 = form.enabled === false ? false : true;
+        // v0.8.0：函数式更新 —— next 基于写入时刻的最新清单计算，不再依赖渲染闭包的旧 providers
+        var next = null;
+        setProviders(function (prev) {
+          next = prev.map(function (p) {
+            return p.id === edit.id ? Object.assign({}, p, { name: name, paused: !enabled2 }) : p;
+          });
+          return next;
+        });
+        // 卡片当前实例处理（基于更新后的 next）：
+        // - 停用的正是当前卡片实例 → 显式切到下一个仍启用的（currentProvider 会自动回落，不能依赖它判空）
+        // - 恢复某实例且此前没有任何可用实例（卡片隐藏态）→ 恢复的这个直接成为卡片当前实例
+        if (!enabled2 && (s.providerId || '') === edit.id) {
+          var fallback = null;
+          var act = activeProviders(next);
+          for (var i = 0; i < act.length; i++) if (act[i].id !== edit.id) { fallback = act[i]; break; }
+          setSettings({ providerId: fallback ? fallback.id : '' });
+        } else if (enabled2 && !currentProvider(next, s.providerId || '')) {
+          setSettings({ providerId: edit.id });
+        }
         if (keyChanged) setNonce(function (n) { return n + 1; });
         setEdit(null);
-        setForm({ provider: '', name: '', adapter: 'usage-percent', key: '', ref: '', nameTouched: false });
+        setForm({ provider: '', name: '', adapter: 'usage-percent', key: '', ref: '', nameTouched: false, enabled: true, _editId: null });
       }
 
       // ── 状态查询（打开设置页时：describe + 每实例实际查询）──
@@ -900,6 +1007,7 @@ window.__ModuleLoader__.load({
           var jobs = [];
           providers.forEach(function (p) {
             if (!p.ref) return;
+            if (p.paused) return; // 已暂停的实例不做任何查询（设置页打开时也只显示「已暂停」灰点）
             if (configuredMap && !configuredMap[p.ref]) return;
             var key = p.adapter + '|' + p.ref;
             setQueryStatus(function (prev) {
@@ -941,13 +1049,16 @@ window.__ModuleLoader__.load({
               j.refs.forEach(function (x) { map[x.name] = !!x.configured; storeMap[x.name] = x.store; });
               setRefStatus(map);
               // 旧数据自愈：source 非 vault 但 Key 只存在插件私有库 → 升级为手动实例（可改名称+Key）
-              var changed = false;
-              var next = providers.map(function (p) {
-                if (p.source === 'vault' || !p.ref) return p;
-                if (storeMap[p.ref] === 'vault') { changed = true; return Object.assign({}, p, { source: 'vault' }); }
-                return p;
+              // v0.8.0：函数式更新，避免覆盖恢复/添加等交错写入
+              setProviders(function (prev) {
+                var changed = false;
+                var next = prev.map(function (p) {
+                  if (p.source === 'vault' || !p.ref) return p;
+                  if (storeMap[p.ref] === 'vault') { changed = true; return Object.assign({}, p, { source: 'vault' }); }
+                  return p;
+                });
+                return changed ? next : prev;
               });
-              if (changed) setProviders(next);
               return startQueries(map, nonce > 0);
             }
             return startQueries(null, nonce > 0);
@@ -958,7 +1069,7 @@ window.__ModuleLoader__.load({
             startQueries(null, nonce > 0);
           });
         return function () { alive = false; };
-      }, [refsKey, nonce]);
+      }, [refsKey, refsPauseKey, nonce]);
 
       var adapterOptions = Object.keys(ADAPTER_META).map(function (a) {
         return React.createElement('option', { key: a, value: a }, ADAPTER_META[a].displayName);
@@ -1033,6 +1144,19 @@ window.__ModuleLoader__.load({
             React.createElement('button', { type: 'button', className: 'zGbnIq_primaryButton', disabled: busy, onClick: saveManual }, '保存')));
       } else if (edit) {
         var editManual = edit.kind === 'manual';
+        var enabled = form.enabled === false ? false : true;
+        var enableToggle = React.createElement('div', { className: 'zGbnIq_field' },
+          React.createElement('span', { className: 'zGbnIq_fieldLabel' }, '启用'),
+          React.createElement('label', { className: 'zGbnIq_editorSwitchRow' },
+            React.createElement('button', {
+              type: 'button', role: 'switch',
+              'aria-checked': enabled ? 'true' : 'false',
+              'aria-label': enabled ? ('已启用 ' + form.name + '，点击暂停') : ('已暂停 ' + form.name + '，点击启用'),
+              className: 'dsh-pu-switch' + (enabled ? ' dsh-pu-switch-on' : ''),
+              onClick: function () { setForm(Object.assign({}, form, { enabled: !enabled })); },
+            }, React.createElement('span', { className: 'dsh-pu-switch-thumb' })),
+            React.createElement('span', { className: 'dsh-pu-switchText' }, enabled ? '已启用' : '已暂停')),
+          React.createElement('span', { className: 'zGbnIq_advancedHint' }, enabled ? '启用中：正常轮询查询，卡片可切换选择' : '已暂停：不再轮询查询，卡片菜单中不可选（Key 与配置保留）'));
         addCard = React.createElement('div', { className: 'zGbnIq_editor' },
           React.createElement('div', { className: 'zGbnIq_editorHeader' },
             React.createElement('span', { className: 'zGbnIq_editorTitle' }, editManual ? '编辑自定义提供方' : '编辑提供方')),
@@ -1048,6 +1172,7 @@ window.__ModuleLoader__.load({
               className: 'zGbnIq_input', value: form.name,
               onChange: function (e) { setForm(Object.assign({}, form, { name: e.target.value, nameTouched: true })); },
             })),
+          enableToggle,
           editManual ? React.createElement('div', { className: 'zGbnIq_field' },
             React.createElement('span', { className: 'zGbnIq_fieldLabel' }, 'API 密钥'),
             React.createElement('input', {
@@ -1094,7 +1219,8 @@ window.__ModuleLoader__.load({
               : providers.map(function (pl) {
               var qs = pl.ref ? queryStatus[pl.adapter + '|' + pl.ref] : null;
               var refKnownRow = pl.ref ? Object.prototype.hasOwnProperty.call(refStatus, pl.ref) : true;
-              var status = pl.ref ? statusOf(refKnownRow, refCheckFailed, !!refStatus[pl.ref], qs) : null;
+              // 已暂停的实例不再轮询/查询，状态点固定为「已暂停」灰点，查询状态一律不展示
+              var status = (pl.paused || !pl.ref) ? null : statusOf(refKnownRow, refCheckFailed, !!refStatus[pl.ref], qs);
               return React.createElement(ProviderRow, {
                 key: pl.id,
                 provider: pl,
@@ -1142,7 +1268,7 @@ window.__ModuleLoader__.load({
         usagePanel);
     }
     // 提供方单行：状态点 + 名称 + 编辑/删除 + 展开详情
-    // 状态判定全部交给 statusOf；本组件只做渲染
+    // 状态判定全部交给 statusOf；本组件只做渲染；启用/暂停开关在编辑弹层里管理
     function ProviderRow(props) {
       var pl = props.provider;
       var status = props.status;
@@ -1150,24 +1276,36 @@ window.__ModuleLoader__.load({
       var onToggle = props.onToggle;
       var onEdit = props.onEdit;
       var onRemove = props.onRemove;
-      var dotEl = status.dotCls ? React.createElement('span', {
-        className: 'zGbnIq_credentialDot' + status.dotCls,
-        role: 'img', 'aria-label': status.label,
-        style: status.clickable ? { cursor: 'pointer' } : undefined,
-        onClick: status.clickable ? onToggle : undefined,
-      }) : null;
+      var paused = pl.paused === true;
+      var dotEl;
+      if (paused) {
+        // 已暂停：灰点「已暂停」，不可展开（暂停时不再查询，无新鲜结果/错误可看）
+        dotEl = React.createElement('span', {
+          className: 'zGbnIq_credentialDot dsh-pu-dot-paused',
+          role: 'img', 'aria-label': '已暂停',
+        });
+      } else if (status && status.dotCls) {
+        dotEl = React.createElement('span', {
+          className: 'zGbnIq_credentialDot' + status.dotCls,
+          role: 'img', 'aria-label': status.label,
+          style: status.clickable ? { cursor: 'pointer' } : undefined,
+          onClick: status.clickable ? onToggle : undefined,
+        });
+      } else {
+        dotEl = null;
+      }
       var detailEl = null;
-      if (expanded && status.detailKind) {
+      if (!paused && expanded && status && status.detailKind) {
         if (status.detailKind === 'err') {
           detailEl = React.createElement('p', { className: 'zGbnIq_error', style: { margin: '10px 0 0' } }, status.detailText);
         } else if (status.detailKind === 'resp') {
           detailEl = React.createElement('div', { className: 'zGbnIq_json' }, status.detailText);
         }
       }
-      return React.createElement('li', { key: pl.id, className: 'zGbnIq_rowCard' },
+      return React.createElement('li', { key: pl.id, className: 'zGbnIq_rowCard' + (paused ? ' zGbnIq_rowPaused' : '') },
         React.createElement('div', { className: 'zGbnIq_rowHead' },
           React.createElement('span', { className: 'zGbnIq_rowIdentity' },
-            React.createElement('span', { className: 'zGbnIq_rowName' }, pl.name),
+            React.createElement('span', { className: 'zGbnIq_rowName' + (paused ? ' zGbnIq_rowNameDim' : '') }, pl.name),
             dotEl),
           React.createElement('span', { className: 'zGbnIq_rowActions' },
             React.createElement('button', { type: 'button', className: 'zGbnIq_secondaryButton', onClick: onEdit }, '编辑'),
@@ -1196,6 +1334,8 @@ window.__ModuleLoader__.load({
         try {
           if (!getSettings().visible) return; // 用户主动隐藏，不自动复活
           if (getProviders().length === 0) return; // 无提供方实例：卡片本就渲染 null，避免 10s 空转重挂
+          // 全部已暂停同理：currentProvider 回落为 null → 卡片渲染 null，无需重挂
+          if (!currentProvider(getProviders(), getSettings().providerId)) return;
           if (rootEl && rootEl.isConnected && document.querySelector('.dsh-pu-card')) return;
           mount();
         } catch (e) {

package/lib/index.js

@@ -4,14 +4,15 @@
 //   balance-json（余额型）  ：DeepSeek     {{baseUrl}}/user/balance    → balance_infos[]
 // 凭证链 per provider：DSH 设置 provider.apiKeyEnv → 凭证服务 → 环境变量。
 // 路由：/api/provider-usage/opencode-go（兼容旧版）、/api/provider-usage/query?provider=<id>、
-//       /api/provider-usage/templates / credentials / dsh-providers / credential-refs / reset-local-stats（仅回环）。
+//       /api/provider-usage/templates / credentials / dsh-providers / credential-refs / reset-local-stats（仅回环）、
+//       /api/provider-usage/providers（提供方实例清单持久化，v0.8.0 —— host 端 providers.json 为单一事实源）。
 // 本地 Token 统计（v0.5.0）：/api/provider-usage/local-usage（累计+按模型汇总，按天物化存储），
 //       数据源 = 自读 $DSH_HOME/sessions 会话文件（fzstd 解压，assistant/message 事件 data.usage），只读、不联网；
 //       存储 = $DSH_HOME/provider-usage/daily-stats/YYYY-MM-DD.json：历史天封存（deps mtime 校验），只算今天。
 // 缓存：每 provider 独立 30s 新鲜窗口 + 并发去重 + 3 快照环；stale-while-error。
 
 import { join, dirname } from 'node:path'
-import { stat as fsStat } from 'node:fs/promises'
+import { stat as fsStat, readFile, writeFile, rename, chmod, mkdir } from 'node:fs/promises'
 import { readFileSync } from 'node:fs'
 import { createSecureStore, resolveProviderUsageDir } from './secure-store.js'
 import * as daily from './daily-stats.js'
@@ -406,12 +407,67 @@ export function apply(ctx, rawConfig) {
       ? rawConfig.sessionsDir
       : join(dirname(resolveProviderUsageDir()), 'sessions'),
     dailyDir: join(resolveProviderUsageDir(), 'daily-stats'),
+    // 提供方实例清单（v0.8.0）：host 端单一事实源（localStorage 只是缓存），防重启后清单被静默重建
+    providersFile: join(resolveProviderUsageDir(), 'providers.json'),
   }
 
   // cordis 配置的 baseUrl 仅覆盖 opencode-go（历史语义），其余 preset 用内置 URL（插件自维护）
   const effectiveBaseUrl = (cfg) =>
     cfg.id === 'usage-percent' && config.baseUrlOverride ? config.baseUrlOverride : cfg.baseUrl
 
+  // ── 提供方实例清单持久化（v0.8.0）─
+  // 修复「重启后提供方清单被静默重建」：实例清单此前只存浏览器 localStorage，
+  // 存储 key 丢失（换 origin/清站点数据/浏览器驱逐）后 loadProviders() 走 DEFAULT_PROVIDERS
+  // 兜底 → 已删除的默认实例复活、自定义实例（如 Command Code）永久消失。
+  // 现在 host 端 providers.json 为单一事实源；客户端启动时从 host 恢复，写操作同步落盘。
+  const PROVIDER_ADAPTER_IDS = new Set(ADAPTERS.map((a) => a.id))
+  const PROVIDERS_MAX = 64
+
+  /** 规范并校验一个提供方实例（不合法字段一律剔除，而非整单拒绝——避免脏数据把恢复流程卡死）。 */
+  function normalizeProviderEntry(raw) {
+    if (!raw || typeof raw !== 'object') return null
+    if (typeof raw.adapter !== 'string' || !PROVIDER_ADAPTER_IDS.has(raw.adapter)) return null
+    const id = typeof raw.id === 'string' && raw.id.trim() !== '' ? raw.id.trim().slice(0, 128) : null
+    if (!id) return null
+    const name = typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name.trim().slice(0, 64) : ''
+    const ref = typeof raw.ref === 'string' ? raw.ref.slice(0, 128) : ''
+    const source = raw.source === 'vault' ? 'vault' : 'dsh'
+    const type = raw.type === 'manual' || raw.type === 'import' ? raw.type : (source === 'vault' ? 'manual' : 'import')
+    return { id, name, adapter: raw.adapter, ref, source, type, paused: raw.paused === true }
+  }
+
+  /** 读清单：providers.json 缺失/损坏 → null（调用方决定兜底，损坏文件同时改名留证）。 */
+  async function readProvidersDoc() {
+    let raw
+    try {
+      raw = await readFile(config.providersFile, 'utf8')
+    } catch (e) {
+      if (e && e.code === 'ENOENT') return null
+      return null // 其它读错误按缺失处理
+    }
+    try {
+      const doc = JSON.parse(raw)
+      if (!doc || doc.version !== 1 || !Array.isArray(doc.providers)) throw new Error('bad doc')
+      const providers = doc.providers.map(normalizeProviderEntry).filter(Boolean)
+      return { version: 1, providers }
+    } catch (e) {
+      // 损坏文件改名留证（.corrupt-<ts>），下次写盘重建；绝不静默吞掉用户清单
+      try { await rename(config.providersFile, config.providersFile + '.corrupt-' + Date.now()) } catch { /* ignore */ }
+      return null
+    }
+  }
+
+  /** 写清单：原子写（tmp → rename）+ 0600（与 credentials.json 同款边界）；目录缺失时先建（0700）。 */
+  async function writeProvidersDoc(providers) {
+    const doc = { version: 1, providers, savedAt: Date.now() }
+    await mkdir(dirname(config.providersFile), { recursive: true, mode: 0o700 }).catch(() => {})
+    const tmp = config.providersFile + '.tmp'
+    await writeFile(tmp, JSON.stringify(doc, null, 2), { mode: 0o600 })
+    await chmod(tmp, 0o600)
+    try { await rename(tmp, config.providersFile) } catch (e) { await writeFile(config.providersFile, JSON.stringify(doc, null, 2), { mode: 0o600 }) }
+    return doc
+  }
+
   // 私有加密凭证库（方案 B，懒初始化：首次使用时生成密钥）
   let secure = null
   async function secureStore() {
@@ -1154,6 +1210,28 @@ export function apply(ctx, rawConfig) {
           return { ok: true, refs }
         }),
       }),
+      // 提供方实例清单持久化（v0.8.0）─：host 端 providers.json 为单一事实源。
+      // GET 读清单（缺失返回 ok:true + items:null，由客户端走一次性迁移）；
+      // POST 整单覆盖保存（幂等）。仅回环，条目逐个规范化，不合法条目剔除。
+      ctx.webServer.register({
+        kind: 'exact',
+        path: '/api/provider-usage/providers',
+        handler: jsonRoute(async (req, body) => {
+          if (req.method === 'POST') {
+            if (!body || !Array.isArray(body.providers)) {
+              return { ok: false, error: { type: 'bad-providers', message: 'providers 必须是数组', httpStatus: 400 } }
+            }
+            if (body.providers.length > PROVIDERS_MAX) {
+              return { ok: false, error: { type: 'too-many-providers', message: '提供方实例最多 ' + PROVIDERS_MAX + ' 个', httpStatus: 400 } }
+            }
+            const providers = body.providers.map(normalizeProviderEntry).filter(Boolean)
+            await writeProvidersDoc(providers)
+            return { ok: true, providers }
+          }
+          const doc = await readProvidersDoc()
+          return { ok: true, providers: doc ? doc.providers : null, exists: doc !== null }
+        }, true),
+      }),
     ]
     return () => { for (const dispose of disposers) { if (typeof dispose === 'function') dispose() } }
   }, 'provider-usage: routes')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loommii/dsh-provider-usage",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "DSH 插件（用量中心）：常驻用量卡片 · 多提供方用量/余额查询（OpenCode Go 订阅 + DeepSeek 余额 + Command Code 订阅/余额，对齐 cc-switch 查询语义）",
   "type": "module",
   "main": "lib/index.js",
@@ -48,15 +48,12 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ]
+      "platform": "web"
     }
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.6",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },