dsh-api-dashboard 1.4.0 → 1.4.1

package/README.md

@@ -5,7 +5,7 @@
 > [!CAUTION]
 > **给安装/维护本插件的 AI 代理的一则警告 —— 动手前必读 [`AGENTS.md`](AGENTS.md)。**
 >
-> 1. **推荐安装方式**：`dsh plugin --profile web add dsh-api-dashboard`（已发布到 npm，一行命令搞定）。也可用「下载→解压→`dsh plugin add file:`」三步法。`pnpm add <远程tarball>` **装不上**。
+> 1. **安装方式（v1.4.1 实测重写）**：**手机版 DSHA 请用「下载 → 解压 → 建 node_modules 软链 → `dsh plugin add link:`」**（见下方「安装」一节，可复制命令；仓库根目录另有 `install.sh` 一键脚本）。`dsh plugin --profile web add dsh-api-dashboard`（npm 裸包名）在 DSHA 上**会失败**：pnpm 把包文件软链到全局 store（proot 的 `--link2symlink` 把硬链接降级成软链），Node 的 ESM 按 realpath 解析后找不到宿主的 peer 依赖。v1.4.1 已加解析回退让**宿主半身不再把整个 `dsh web` 拖死**，但**客户端 UI 仍不会出现**（框架按模块路径找不到 package.json）。`pnpm add <远程tarball>` 同样**装不上**。
 > 2. **数据准确性红线**：部分平台余额解析有待验证项（OpenRouter/SiliconFlow/Novita/one-api/xAI），且「限流窗口 ≠ 真实余额」——**不要伪造或硬塞一个数字**，查不到就如实显示「未开放」。
 > 3. **推送前先问用户**；改 `client/client.js` 后需**重启 dsh web GUI** 才生效。
 >
@@ -81,44 +81,54 @@ OpenRouter、Novita AI、xAI Grok
 
 ## 安装
 
-### ✅ 推荐方式：npm 一行命令
-
-```sh
-dsh plugin --profile web add dsh-api-dashboard
-```
-
-> 从 npm 拉取最新版本，自动安装依赖、注册 bundle 层，无需手动下载或建软链。
-
-### 备选：下载源码后安装（无 npm registry 环境时）
+### ✅ 手机版 DSHA（Android）—— 实测可用，照抄即可
 
 ```sh
 # 1. 下载源码（codeload 地址，github.com 主站不可达时也能用）
-curl -L "https://codeload.github.com/133563825as-ai/dsh-api-dashboard/tar.gz/refs/heads/main" -o /tmp/dsh-api-dashboard.tar.gz
+curl -L "https://codeload.github.com/133563825as-ai/dsh-api-dashboard/tar.gz/refs/heads/main" \
+     -o /tmp/dsh-api-dashboard.tar.gz
 
-# 2. 解压到固定位置（--strip-components=1 去掉顶层目录，必须带）
-mkdir -p /root/dsha-api-dashboard
+# 2. 解压到固定位置（--strip-components=1 必须带，否则会多一层目录）
+rm -rf /root/dsha-api-dashboard && mkdir -p /root/dsha-api-dashboard
 tar xzf /tmp/dsh-api-dashboard.tar.gz -C /root/dsha-api-dashboard --strip-components=1
 
-# 3. 安装进 web profile：自动装依赖 + 自动注册 bundle 层
-dsh plugin --profile web add file:/root/dsha-api-dashboard
+# 3. 建 node_modules 软链 —— 这一步不能省！
+#    插件的 peer 依赖（@deepseek-ai/schemastery / zod）由宿主 DSH 提供，
+#    软链让它从源码目录就能解析到它们。
+ln -sfn /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules /root/dsha-api-dashboard/node_modules
 
-# 4. 重启 dsh web 生效
+# 4. 装进 web profile（link: 方式，文件保持真实路径，客户端 UI 才能被框架找到）
+dsh plugin --profile web add link:/root/dsha-api-dashboard
+
+# 5. 重启 dsh web
 ```
 
+> 仓库根目录的 `install.sh` 把上面 5 步做完了，也可以直接 `sh install.sh`。
+
+### 桌面版 DSH（Linux/macOS/Windows）
+
+同样推荐上面的「源码 + `link:`」方式（把路径换成你自己的）。
+npm 一行命令 `dsh plugin --profile web add dsh-api-dashboard` 在**桌面版**上通常可用
+（桌面文件系统支持硬链接，pnpm 不会把包文件软链到 store）；但 v1.4.1 起仍建议用 `link:`，
+因为自更新与资产路径都按真实路径工作。
+
 ### 升级到新版本
 
-1. **推荐**：插件设置面板 →「检查更新」→「一键自更新」（内置更新引擎，下载→校验→备份→原子替换→失败回滚，重启 web 生效）；
-2. 或：`dsh plugin --profile web remove dsh-api-dashboard` 后重新执行上面的推荐/备选安装；
-3. 兜底：重复「下载源码」步骤 1-2 覆盖目录，再执行第 3 步。
+1. **推荐**：重新执行上面第 1、2 步（覆盖源码目录）→ 重启 `dsh web`；
+2. 插件设置面板里的「一键自更新」也可用（下载→校验→备份→替换→失败回滚，重启生效）；
+   ⚠️ 它会**保留 `.git` 与 `node_modules`**（v1.4.1 修复：此前会把 `.git` 一起删掉，历史无法恢复）；
+3. 或 `dsh plugin --profile web remove dsh-api-dashboard` 后重新安装。
 
-### ⚠️ 安装姿势对照（实测）
+### ⚠️ 安装姿势对照（2026-09-11 在 DSHA 上逐条实测）
 
 | 方式 | 结果 |
 |------|------|
-| `dsh plugin --profile web add dsh-api-dashboard`（npm 裸包名） | ✅ 推荐，一行命令 |
-| `dsh plugin --profile web add file:/root/dsha-api-dashboard`（源码方式） | ✅ 备选 |
+| 源码 + `node_modules` 软链 + `dsh plugin add link:<dir>` | ✅ **可用**（推荐） |
+| 包目录放在 `$DSH_HOME/profiles/` 之下再 `add file:` | ✅ 可用 |
+| `dsh plugin --profile web add dsh-api-dashboard`（npm 裸包名，**手机版 DSHA**） | ❌ 客户端 UI 不会出现；v1.4.1 之前更糟 —— **整个 `dsh web` 启动失败** |
+| `dsh plugin --profile web add file:/源码目录`（目录里**没有** node_modules） | ❌ 同上 |
 | `pnpm add <远程 tarball URL>` | ❌ pnpm 不剥离 codeload 压缩包顶层目录，装出来是空壳 |
-| 手动软链 node_modules | ⚠️ 可用但繁琐，层级写错会被启动校准摘除，不推荐 |
+| 手动软链整个插件目录到 `node_modules` | ⚠️ 会被启动校准摘除，别用；软链 `node_modules` 子目录是**必须**的 |
 
 ## 配置
 
@@ -190,6 +200,26 @@ dsh-api-dashboard/
 
 ## 版本
 
+v1.4.1 — **审计修复版**（全部先在真机/隔离环境复现再修，新增 `test/test-v141-fixes.mjs` 62 条回归钉子）：
+  🔴 **状态文件形状损坏不再拖死整个 GUI** —— `{"customRelays": 5}` 这类「合法 JSON 但字段类型跑偏」以前会让 `apply()` 抛 `TypeError`，进而**整个 `dsh web` 启动失败**（不是插件不显示，是 GUI 打不开）。现在加载时统一消毒形状并夹取数值范围。
+  🔴 **一键自更新不再删 `.git`** —— codeload 的 tarball 里没有 `.git`，旧代码 `rmSync` 掉除 `node_modules` 外的一切再覆盖，点一次更新就抹掉 git 历史且无法恢复。现在保留 `.git`；`~/dsha-api-dashboard` 的自动同步**只对非 git 工作区生效**；target 是符号链接时直接拒绝（旧行为会删光软链指向的真实目录，且回滚不回来）。
+  🔴 **插件路由补鉴权** —— `/api-dashboard/*` 以前完全绕过 DSH 的浏览器鉴权：无 token、无 cookie 就能读配置/改配置/触发自更新；且 `Content-Type: text/plain` 属于浏览器**不预检的 simple request**，实测带 `Origin: https://evil.example` 的跨域 POST 返回 **200 且配置真的被改了**。现在复用 `connection.requestRejection`（与 `dsh-web-mobile` 同一闸门）：无 cookie → 401、跨域 → 403。
+  🔴 **peer 依赖解析回退** —— npm 安装后宿主半身不再 `Cannot find package '@deepseek-ai/schemastery'`；另修 `SELF_ROOT` 走 realpath 导致 npm 布局下图标/挂件资产 404、版本号读不到的问题。
+  🐛 **「刷新间隔 1 秒」真正生效** —— 输入框与服务端都允许 1 秒，只有 `save()` 悄悄夹成 5 秒；旧回归断言钉的是**旧变量名**，换个名字就绕过（假绿）。四处下限现已一致。
+  🐛 **冷启动打开设置面板不再覆盖用户配置** —— 面板以前只从 `/balances` 拿阈值/币种，冷启动要等 8~10s，那期间点「保存并生效」会把真实阈值写成默认 50/10、把 `overseasCurrency` 写回 `'follow'`。`/config` 现在返回阈值，客户端也补读。
+  🐛 **`openai` 分支不再伪造负数余额**（`total_granted` 为 null/非数字时 `0 - used` → 面板红色「-5」），与已修的 `openrouter` 同类。
+  🐛 **冷启动不再「等半天 + 报失败」** —— 实测维护者真实配置下一次全量刷新要 **8~13.6 秒**（5 个中转站的 auto 探测是串行试 3 个候选端点，每个跑满 8s）。
+      v1.4.1 第一版给 fetch 统一加了 15s 超时，正好卡在这中间 → **冷启动首屏必超时 → 面板显示「余额接口请求失败」**。现已：① 余额端点超时放宽到 90s（超时只用来兜底卡死的 socket，不是给正常慢启动设上限）；② 冷启动改成**后台刷新**——服务端立刻回 `loading:true` + 空列表，客户端保持骨架屏并把轮询压到 1.5 秒，数据一到就上屏（实测前 5 发 2~3ms 返回，第 6 发拿到数据）；③ 加载超 4 秒补一句「首次加载要逐个平台拉取余额…请稍候」；④ **记住每个中转站上次命中的余额端点**并优先试它（存状态文件 `relayEndpoints`，重启后仍生效），稳态下每个中转站只打 1 个请求。
+  🐛 **错误路径有了出口** —— fetch 全部加 15s 超时（以前一个 `AbortController` 都没有，请求挂住就永久骨架屏且从此不再轮询）；抽屉在请求失败时显示错误文案 + 「重试」按钮（以前只画空看板，`snapshot.message` 从不渲染）；保存与配置请求补 `catch`。
+  🐛 **状态条金额三色类名补上 CSS**（`.dshadb_bar_ok/warn/err` 以前只有使用处、没有规则 = 死类名，负余额金额从不标红）。
+  🐛 **子代理胶囊监听器不再累加**（内联 ref 使每次 render 都挂 7 个 `addEventListener`，5 秒轮询下每小时约 5000 个）。
+  🐛 **强刷加 2 秒节流 + 响应序列号**（连点刷新会并发，且旧响应会覆盖新响应造成数据倒退）。
+  🐛 **中文名不再被写坏**：请求体改为按字节收集后整体 `utf8` 解码（跨 chunk 切分多字节字符会产生 U+FFFD 并存进状态文件）。
+  🐛 持久化的 `refreshIntervalMs` 加载时夹取（曾经能是 -1 → 3 秒内 1794 次上游请求）；状态文件保存前建父目录，失败时如实上报。
+  🐛 **设置面板开着时大肥鱼可以拖动了** —— 旧逻辑把「设置面板」也算进 `overlayOpen`，一进设置挂件立刻被 `pointer-events:none` 锁死，必须关掉才能拖（维护者反馈）。而设置里的「大肥鱼」页恰恰是要边看实时预览边拖位置/调大小的地方。现在只对会盖住挂件的**看板 / 详情**两个整屏抽屉上锁。
+  🎨 **UI：余额条恢复成独立药丸，整块水平居中**（子代理行同样居中；不再塞进一个容器）。子代理行真正溢出时右侧渐隐，不再被屏幕齐口切一半。
+  ⚠️ **已知未修**：会话消耗按「查看时刻」的峰谷单价重算（同一会话在峰谷切换时会显示 1×/2× 两个数）。要修得在事件折叠时按 `isPeakTime(事件时刻)` 分桶存储并 bump `stateVersion`，属投影状态结构变更，留待下个版本。
+v1.4.0 — 价格表改原生币种 + 会话消耗漏计/前缀吞模型修复 + 子代理消耗可见 + DSH provider 自动入列 + 设置界面统一 + 三处交互修复
 v0.2.0 — 最初版本
 v0.2.1 — 修复图标映射，加入 DeepSeek 峰谷计费
 v0.3.0 — 完整三层 UI，国内外分组，三色阈值，趣味峰谷，设置面板

package/client/client.js

@@ -191,6 +191,11 @@ window.__ModuleLoader__.load({
 .dshadb_bar_logo{width:16px;height:16px;border-radius:5px;background:#eef2ff;display:flex;align-items:center;justify-content:center;font-size:9px;font-weight:800;color:#4f7cff}
 .dshadb_bar_name{font-weight:700;color:#17181c;font-size:11px}
 .dshadb_bar_amount{font-weight:800;font-variant-numeric:tabular-nums;color:#17181c}
+/* C-4a (v1.4.1): .dshadb_bar_ok/warn/err 以前只有使用处、没有 CSS 规则(死类名),
+   于是"负余额/低余额金额变红"从来没生效过, 只有小圆点变色。 */
+.dshadb_bar_ok{color:#2e9e5b}
+.dshadb_bar_warn{color:#c8891a}
+.dshadb_bar_err{color:#d8443f}
 .dshadb_bar_dot{width:6px;height:6px;border-radius:50%;flex:none}
 .dshadb_bar_dot_ok{background:#35b56b}
 .dshadb_bar_dot_warn{background:#e6a72f}
@@ -367,9 +372,15 @@ window.__ModuleLoader__.load({
    见 bindSubagentTip()。浮层必须挂在 document.body 上 —— 挂在胶囊里会被
    .dshadb_subs 的 overflow-x:auto 裁掉。
    ⚠️ 本段在 JS 模板字符串里, 注释里**不能出现反引号**(会提前结束模板串)。 */
-.dshadb_barwrap{display:inline-flex;flex-direction:column;align-items:flex-start;gap:0;max-width:100%;min-width:0}
-.dshadb_barrow{display:inline-flex;align-items:center;gap:2px;max-width:100%}
-.dshadb_subs{display:flex;flex-wrap:nowrap;align-items:center;gap:4px;margin:3px 0 0 2px;max-width:100%;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;-ms-overflow-style:none;-webkit-overflow-scrolling:touch}
+/* UI v1.4.1（按维护者反馈改）：**不再把两行塞进一个容器** —— 余额条恢复成独立的药丸，
+   整块（余额条 + 子代理行）**水平居中**：wrap 用 fit-content + margin:auto，
+   子项 align-items:center，于是窄的时候两行都居中，宽的时候 wrap 撑到 100% 子代理行在内部横滑。 */
+.dshadb_barwrap{display:flex;flex-direction:column;align-items:center;gap:0;width:fit-content;max-width:100%;min-width:0;margin:0 auto}
+.dshadb_barrow{display:inline-flex;align-items:center;gap:2px;max-width:100%;min-width:0}
+.dshadb_subs{display:flex;flex-wrap:nowrap;align-items:center;gap:4px;margin:3px 0 0 0;max-width:100%;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;-ms-overflow-style:none;-webkit-overflow-scrolling:touch}
+/* UI v1.4.1: 子代理行只在**真的溢出**时右侧渐隐(由 syncSubsOverflow 打类名),
+   这样"被切一半"看起来是有意的可滑动提示, 而不是被屏幕齐口截断。 */
+.dshadb_subs_overflow{-webkit-mask-image:linear-gradient(to right,#000 calc(100% - 20px),transparent);mask-image:linear-gradient(to right,#000 calc(100% - 20px),transparent)}
 .dshadb_subs::-webkit-scrollbar{display:none}
 .dshadb_sub{flex:none;display:inline-flex;align-items:center;gap:4px;font-size:10px;line-height:1.15;padding:2px 7px;border-radius:8px;background:#f5f6f8;border:1px solid #e7e8ec;color:#777b84;white-space:nowrap;-webkit-touch-callout:none;-webkit-user-select:none;user-select:none}
 .dshadb_sub_dot{width:5px;height:5px;border-radius:50%;background:#8b93a7;flex:none}
@@ -625,6 +636,7 @@ window.__ModuleLoader__.load({
     let snapshot = { status: "loading", balances: [], config: { safeThreshold: 50, warnThreshold: 10 } };
     const listeners = new Set();
     let timer = null, pollMs = DEFAULT_POLL_MS, inflight = null, started = false;
+    let lastForceAt = 0, seq = 0, appliedSeq = 0;
     function notify() { for (const fn of [...listeners]) fn(); }
     /**
      * @param force 显式强刷 (手动刷新按钮 / 保存设置后) —— **阻塞**, 等服务端拉完最新数据
@@ -632,8 +644,36 @@ window.__ModuleLoader__.load({
      *              刷新丢后台。force 那条路要等服务端跑完一次全量轮询(最慢端点可到 8s),
      *              应用切回前台时用它就会「等一段时间」。
      */
+    /**
+     * C-3a (v1.4.1): fetch 必须带超时。
+     * 以前整份客户端一个 AbortController 都没有 —— 请求一旦既不 resolve 也不 reject
+     * (弱网黑洞、WebView 被冻结、服务端被最慢端点拖住), inflight 永远不为 null,
+     * schedule() 又只在 promise settle 后才续期 → 插件永久停在 4 条骨架屏, 手动刷新也救不回来。
+     */
+    const FETCH_TIMEOUT_MS = 15000;
+    /**
+     * ⚠️ 余额端点的超时**必须远大于**其他端点。
+     * 实测（维护者真实配置：5 个中转站 + 16 个预设平台）：服务端一次全量刷新要 **8~13.6 秒** ——
+     * `queryCustomRelay` 的 auto 探测是**串行**试 3 个候选端点（billing/subscription → api/user/self
+     * → credit_grants），每个都要跑到 `timeoutMs`(默认 8s) 才放弃；冷启动还要叠加 DNS/TLS 首次握手。
+     * v1.4.1 第一版把这里也写成 15s，结果**冷启动首屏必超时** → 面板直接显示「余额接口请求失败」。
+     * 超时的意义只是"别让一个彻底卡死的 socket 永远挂着"，不是给正常慢启动设上限。
+     */
+    const BALANCES_TIMEOUT_MS = 90000;
+    const fetchT = (url, opts, ms) => {
+      const timeout = typeof ms === "number" ? ms : FETCH_TIMEOUT_MS;
+      try { return fetch(url, { ...(opts || {}), signal: AbortSignal.timeout(timeout) }); }
+      catch (e) { return fetch(url, opts); }
+    };
     async function refresh(force = false, peek = false) {
       if (inflight !== null && !force && !peek) return inflight;
+      // C-4c (v1.4.1): 强刷节流 2s(AGENTS 里写了「强刷 2 秒节流」, 但代码里一直没有);
+      // 并且在飞时直接复用同一个请求, 避免连点刷新打出一串并发。
+      if (force) {
+        const now = Date.now();
+        if (inflight !== null && now - lastForceAt < 2000) return inflight;
+        lastForceAt = now;
+      }
       if ((force || peek) && snapshot.isRefreshing !== true) { snapshot = { ...snapshot, isRefreshing: true }; notify(); }
       inflight = (async () => {
         try {
@@ -641,16 +681,26 @@ window.__ModuleLoader__.load({
             : force ? "/api-dashboard/balances?force=1&_t=" + Date.now()
               : "/api-dashboard/balances";
           // v0.5.0: 走浏览器默认缓存 (配合服务端 ETag), 数据没变时 304 空响应; force 用独立 URL + no-store 强刷
-          const res = await fetch(url, { headers: { accept: "application/json" }, cache: force ? "no-store" : "default" });
+          const mySeq = ++seq;
+          const res = await fetchT(url, { headers: { accept: "application/json" }, cache: force ? "no-store" : "default" }, BALANCES_TIMEOUT_MS);
           if (!res.ok) throw new Error("HTTP " + res.status);
           const data = await res.json();
+          // C-4c: 只接受最新一次请求的结果 —— 否则「新请求先回、旧请求后回」会把界面数据倒退回去
+          if (mySeq <= appliedSeq) { inflight = null; return; }
+          appliedSeq = mySeq;
           if (data.config?.clientPollIntervalMs >= 1000) pollMs = Math.min(data.config.clientPollIntervalMs, 3600000);
           // v0.5.0 性能适配: 内容无变化就不重建快照引用, useSyncExternalStore 判定 Object.is 相同直接跳过整棵树重渲
           const newBalances = data.balances || [];
           const oldBalances = Array.isArray(snapshot.balances) ? snapshot.balances : [];
           const changed = JSON.stringify(newBalances) !== JSON.stringify(oldBalances) || snapshot.status !== "ok";
           const nextFetchedAt = data.fetchedAt || Date.now();
-          if (!changed) {
+          // v1.4.1: 服务端冷启动不再阻塞首屏 —— 立刻回 `loading:true` + 空列表, 刷新丢后台。
+          // 这里保持「加载中」状态(骨架屏), 并把轮询临时压到 1.5 秒, 数据一到就上屏。
+          // 注意这不是假数据: 显示的是"加载中", 不是 0 元。
+          if (data.loading === true) {
+            snapshot = { ...snapshot, status: "loading", balances: [], config: data.config || snapshot.config, fetchedAt: nextFetchedAt, isRefreshing: false };
+            pollMs = Math.min(pollMs, 1500);
+          } else if (!changed) {
             // v1.1.0: config 必须始终跟随最新响应 —— 旧写法在余额未变时保留旧 config,
             // 导致设置里改完开关(如 whaleEnabled)后前端永远读不到新值, 表现为"开了又变回关"
             snapshot = { ...snapshot, config: data.config || snapshot.config, fetchedAt: nextFetchedAt, isRefreshing: false };
@@ -757,6 +807,12 @@ window.__ModuleLoader__.load({
     }
     /** 给一个胶囊挂长按: 位移 > 8px(其实是在滑动这一行) 或抬手都取消; 长按抬手后的 click 吞掉。 */
     function bindSubagentTip(node, text) {
+      // C-4b (v1.4.1): ref 是内联箭头函数 → 每次 render 都重新调用本函数,
+      // 而这里挂 7 个 addEventListener 却从不 remove → 5 秒轮询下每小时约 5000 个监听器
+      // 堆在同一个胶囊节点上。改成"同一个节点只挂一次", tip 存在节点上按需读。
+      node.__dshadbTip = text;
+      if (node.__dshadbTipBound === true) return;
+      node.__dshadbTipBound = true;
       let timer = 0, sx = 0, sy = 0, fired = false;
       const cancel = () => { if (timer) { clearTimeout(timer); timer = 0; } };
       node.addEventListener("pointerdown", (e) => {
@@ -764,7 +820,7 @@ window.__ModuleLoader__.load({
         fired = false;
         sx = e.clientX; sy = e.clientY;
         cancel();
-        timer = setTimeout(() => { timer = 0; fired = true; showSubagentTip(node, text); }, SUBTIP_LONG_PRESS_MS);
+        timer = setTimeout(() => { timer = 0; fired = true; showSubagentTip(node, node.__dshadbTip || text); }, SUBTIP_LONG_PRESS_MS);
       });
       node.addEventListener("pointermove", (e) => {
         if (timer && (Math.abs(e.clientX - sx) > 8 || Math.abs(e.clientY - sy) > 8)) cancel();
@@ -789,7 +845,18 @@ window.__ModuleLoader__.load({
       const list = Array.isArray(cost && cost.subagents) ? cost.subagents : [];
       if (list.length === 0) return null;
       const mainCur = (cost && cost.currency) || "CNY";
-      return react.createElement("span", { className: "dshadb_subs", key: "subs" },
+      // UI v1.4.1: 只在真的横向溢出时才加渐隐类名, 避免内容没满也糊一条边
+      const syncSubsOverflow = (n) => {
+        if (!n) return;
+        try {
+          const over = n.scrollWidth > n.clientWidth + 1;
+          if (over) n.classList.add("dshadb_subs_overflow");
+          else n.classList.remove("dshadb_subs_overflow");
+        } catch (e) { /* 忽略 */ }
+      };
+      return react.createElement("span", { className: "dshadb_subs", key: "subs",
+        ref: (n) => { if (n) requestAnimationFrame(() => syncSubsOverflow(n)); },
+        onScroll: (e) => syncSubsOverflow(e.currentTarget) },
         list.map((s, i) => {
           const f = formatSessionCost({ cost: s.cost, currency: mainCur, costByCurrency: s.costByCurrency, waiting: false });
           const amt = f !== null && f.hasValue ? "~" + f.text : "~—";
@@ -1043,6 +1110,13 @@ window.__ModuleLoader__.load({
       const handleRefresh = () => { setRefreshing(true); store.forceRefresh().then(() => setTimeout(() => setRefreshing(false), 500)); };
       const balances = data.balances || [];
       const isLoading = data.status === "loading" && balances.length === 0;
+      // v1.4.1: 加载超过 4 秒就在骨架屏下面补一句「首次加载较慢」的解释（冷启动全量刷新实测 8~30s）
+      const [slowLoad, setSlowLoad] = react.useState(false);
+      react.useEffect(() => {
+        if (!isLoading) { setSlowLoad(false); return undefined; }
+        const timer = setTimeout(() => setSlowLoad(true), 4000);
+        return () => clearTimeout(timer);
+      }, [isLoading]);
       const okCount = balances.filter(b => b.status === "ok").length;
 
       const groups = { domestic: [], abroad: [], relay: [], custom: [] };
@@ -1119,19 +1193,35 @@ window.__ModuleLoader__.load({
         ]);
       };
 
+      const slowHint = isLoading && slowLoad;
       let bodyContent;
       if (isLoading) {
-        bodyContent = react.createElement("div", null, [0,1,2,3].map(i => react.createElement("div", { className: "dshadb_skeleton", key: i }, [
-          react.createElement("div", { className: "dshadb_skeleton_logo", key: "logo" }),
-          react.createElement("div", { className: "dshadb_skeleton_lines", key: "lines" }, [
-            react.createElement("div", { className: "dshadb_skeleton_line dshadb_skeleton_line_long", key: "l1" }),
-            react.createElement("div", { className: "dshadb_skeleton_line dshadb_skeleton_line_short", key: "l2" }),
-          ]),
-        ])));
+        // v1.4.1: 冷启动全量刷新实测要 8~30 秒（中转站 auto 探测是串行的），
+        // 光画骨架屏用户会以为卡死 → 超过 4 秒补一句解释。
+        bodyContent = react.createElement("div", null, [
+          ...([0,1,2,3].map(i => react.createElement("div", { className: "dshadb_skeleton", key: i }, [
+            react.createElement("div", { className: "dshadb_skeleton_logo", key: "logo" }),
+            react.createElement("div", { className: "dshadb_skeleton_lines", key: "lines" }, [
+              react.createElement("div", { className: "dshadb_skeleton_line dshadb_skeleton_line_long", key: "l1" }),
+              react.createElement("div", { className: "dshadb_skeleton_line dshadb_skeleton_line_short", key: "l2" }),
+            ]),
+          ]))),
+          slowHint ? react.createElement("div", { key: "slow", style: { fontSize: 11, color: "#8b91a0", textAlign: "center", lineHeight: 1.6, margin: "10px 4px 2px" } },
+            "首次加载要逐个平台拉取余额（含中转站探测），通常 10~30 秒，请稍候…") : null,
+        ]);
       } else if (balances.length === 0) {
+        // C-3c (v1.4.1): 请求失败时以前只画"空看板" —— 用户分不清「没有平台」和「请求失败」。
+        // 实测 snapshot.message 全文件只被赋值、从不渲染。
+        const isErr = snapshot.status === "error";
         bodyContent = react.createElement("div", { className: "dshadb_empty" }, [
-          react.createElement("span", { key: "icon", style: { fontSize: 30, opacity: 0.5 } }, "📊"),
-          react.createElement("span", { key: "title" }, t("title")),
+          react.createElement("span", { key: "icon", style: { fontSize: 30, opacity: 0.5 } }, isErr ? "⚠️" : "📊"),
+          react.createElement("span", { key: "title" }, isErr ? "余额接口请求失败" : t("title")),
+          isErr && snapshot.message ? react.createElement("span", { key: "msg", style: { fontSize: 11, color: "#e05252", wordBreak: "break-all" } }, String(snapshot.message)) : null,
+          isErr ? react.createElement("button", {
+            key: "retry", type: "button", className: "dshadb_add_btn",
+            style: { width: "auto", padding: "6px 18px", marginTop: "4px" },
+            onClick: () => { try { store.forceRefresh(); } catch (e) { /* 忽略 */ } },
+          }, "重试") : null,
         ]);
       } else {
         bodyContent = [
@@ -1214,7 +1304,7 @@ window.__ModuleLoader__.load({
       react.useEffect(() => {
         if (!isOpen || platformId !== "deepseek") return;
         let live = true;
-        fetch("/api-dashboard/prices", { headers: { accept: "application/json" } })
+        fetchT("/api-dashboard/prices", { headers: { accept: "application/json" } })
           .then((r) => (r.ok ? r.json() : null))
           .then((d) => { if (live && d && d.ok) setPriceData(d); })
           .catch(() => {});
@@ -1398,7 +1488,7 @@ window.__ModuleLoader__.load({
       });
       const checkUpdate = react.useCallback((force) => {
         setUpd(s => ({ ...s, phase: "checking" }));
-        fetch("/api-dashboard/update" + (force ? "?force=1" : ""), { headers: { accept: "application/json" } })
+        fetchT("/api-dashboard/update" + (force ? "?force=1" : ""), { headers: { accept: "application/json" } })
           .then(r => r.json())
           .then(d => {
             // v0.6.2: 检查完必有反馈 —— 已是最新也提示, 有新版提示版本号, 失败给固定文案
@@ -1411,7 +1501,7 @@ window.__ModuleLoader__.load({
       react.useEffect(() => { if (isOpen) checkUpdate(false); }, [isOpen]);  // 打开面板自动检查
       const installUpdate = () => {
         setUpd(s => ({ ...s, phase: "installing" }));
-        fetch("/api-dashboard/update/install", { method: "POST" })
+        fetchT("/api-dashboard/update/install", { method: "POST" }, 120000)
           .then(r => r.json().then(d => ({ code: r.status, body: d })))
           .then(({ code, body }) => {
             if (code === 200 && body.ok) {
@@ -1443,12 +1533,18 @@ window.__ModuleLoader__.load({
         setRefreshSec(Math.round((config?.clientPollIntervalMs || 5000) / 1000) || 5);
         setWhaleOn(!!(config && config.whaleEnabled));
         let cancelled = false;
-        fetch("/api-dashboard/config", { cache: "no-store" }).then(r => r.json()).then(d => {
+        fetchT("/api-dashboard/config", { cache: "no-store" }).then(r => r.json()).then(d => {
           if (cancelled) return;
           if (d.ok) {
             setRelays(d.customRelays || []);
             setModels(d.customModels || []);
             if (d.refreshIntervalSec) setRefreshSec(d.refreshIntervalSec);
+            // C-2 (v1.4.1): 阈值/主币种也必须从 /config 补一次。
+            // 以前只从 /balances 的 config 读, 而冷启动 /balances 要等 8~10s →
+            // 那期间打开面板看到的是默认 50/10/CNY, 一点"保存并生效"就把用户真实配置覆盖了。
+            if (typeof d.safeThreshold === "number") setSafe(d.safeThreshold);
+            if (typeof d.warnThreshold === "number") setWarn(d.warnThreshold);
+            if (typeof d.currency === "string") setCurrency(d.currency);
             if (typeof d.overseasCurrency === "string") setOverseasCurrency(d.overseasCurrency);
             if (typeof d.whaleEnabled === "boolean") setWhaleOn(d.whaleEnabled);
             if (Array.isArray(d.officialProviders)) setOfficialText(d.officialProviders.join(", "));
@@ -1458,7 +1554,7 @@ window.__ModuleLoader__.load({
           }
         }).finally(() => { if (!cancelled) setLoading(false); });
         // 大肥鱼细项与主配置并行拉取, 失败保持默认值
-        fetch("/api-dashboard/whale/settings", { cache: "no-store" }).then(r => r.json()).then(d => {
+        fetchT("/api-dashboard/whale/settings", { cache: "no-store" }).then(r => r.json()).then(d => {
           if (cancelled || !d || !d.ok || !d.settings) return;
           const s = d.settings;
           setWf(prev => ({
@@ -1476,11 +1572,13 @@ window.__ModuleLoader__.load({
       }, [isOpen]);
       if (!isOpen) return null;
       const save = async () => {
-        const nextRefreshSec = Math.min(Math.max(Number(refreshSec) || 5, 5), 60)
+        // C-1 (v1.4.1): 原来这里夹的是 5 —— 输入框允许 1 秒、服务端 clampRefreshSec 也吃 1 秒,
+        // 只有 save() 把它悄悄改回 5 秒(用户设 1 秒保存后变 5 秒)。四处下限现在一致。
+        const nextRefreshSec = Math.min(Math.max(Number(refreshSec) || 1, 1), 60)
         setRefreshSec(nextRefreshSec)
         setSaving(true);
         try {
-          await fetch("/api-dashboard/config", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({
+          await fetchT("/api-dashboard/config", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({
             customRelays: relays, customModels: models,
             safeThreshold: Number(safe), warnThreshold: Number(warn), currency, overseasCurrency,
             refreshIntervalSec: nextRefreshSec,
@@ -1514,7 +1612,7 @@ window.__ModuleLoader__.load({
         setWhaleOn(next);
         if (next) ensureWhaleWidget(); else removeWhaleWidget();
         try {
-          await fetch("/api-dashboard/config", {
+          await fetchT("/api-dashboard/config", {
             method: "POST", headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ whaleEnabled: !!next }),
           });
@@ -1525,7 +1623,7 @@ window.__ModuleLoader__.load({
       const toggleBrands = async (next) => {
         setShowBrands(next);
         try {
-          await fetch("/api-dashboard/config", {
+          await fetchT("/api-dashboard/config", {
             method: "POST", headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ showNoBalanceBrands: !!next }),
           });
@@ -1539,7 +1637,7 @@ window.__ModuleLoader__.load({
         setWf(prev => ({ ...prev, ...patch }));
         patchWhaleWidget(patch);
         try {
-          fetch("/api-dashboard/whale/settings", {
+          fetchT("/api-dashboard/whale/settings", {
             method: "PUT", headers: { "Content-Type": "application/json" },
             body: JSON.stringify(patch),
           }).catch(() => {});
@@ -2052,7 +2150,7 @@ window.__ModuleLoader__.load({
             peekRatio: st.peekRatio, left: st.left, top: st.top, side: st.side,
           };
           try {
-            fetch("/api-dashboard/whale/settings", {
+            fetchT("/api-dashboard/whale/settings", {
               method: "PUT", headers: { "Content-Type": "application/json" },
               body: JSON.stringify(lastWhaleSettings),
             }).catch(function () {});
@@ -2362,7 +2460,7 @@ window.__ModuleLoader__.load({
       }
       revealTimer = setTimeout(reveal, 2000);   // 兜底: 请求挂住也不能让鱼永远不出现
       applyAll();
-      fetch("/api-dashboard/whale/settings", { cache: "no-store" })
+      fetchT("/api-dashboard/whale/settings", { cache: "no-store" })
         .then(function (r) { return r.json(); })
         .then(function (d) {
           if (disposed) return;
@@ -2451,11 +2549,23 @@ window.__ModuleLoader__.load({
           // v1.4.0: 看板/详情/设置任一开着 → 锁住大肥鱼挂件的触摸。
           // 不这么做的话, 挂件(在 body 上, z-index 9600)会盖在设置面板上面,
           // 拖「身体大小 / 露出比例」滑块时实际拖的是挂件。
-          const overlayOpen = isSettingsOpen || view !== "bar";
+          /**
+           * 大肥鱼挂件锁定（v1.4.1 定稿）：**任何界面下都不锁**。
+           *
+           * 演进过程（别再走回头路）：
+           *   v1.4.0   `overlayOpen = isSettingsOpen || view !== "bar"` —— 一开设置就锁死，
+           *            维护者反馈「在设置里开启大肥鱼，图片动不了，得关掉才能动」。
+           *   v1.4.1a  改成只锁「看板 / 详情」两个整屏抽屉 —— 维护者再次要求全部放开。
+           *   v1.4.1b  **本版：永不锁定**，挂件在任何界面下都能拖。
+           *
+           * 锁的机制本身（`setWhaleLocked` / `.dshadb-whale-locked` CSS / `onDown` 里那道兜底）
+           * **保留着**：万一以后又出现「面板开着时拖滑块被挂件吃掉」这类反馈，
+           * 把下面这行换成 `setWhaleLocked(view !== "bar")` 即可恢复按界面锁定。
+           */
           react.useEffect(() => {
-            setWhaleLocked(overlayOpen);
+            setWhaleLocked(false);
             return () => setWhaleLocked(false);
-          }, [overlayOpen]);
+          }, []);
           // 峰谷时段变化同步给挂件 (台词里的「当前时间段」用它, 不涉及任何金额)
           react.useEffect(() => {
             updateWhaleContext({ isPeak: !!(config && config.isPeak) });
@@ -2514,7 +2624,7 @@ window.__ModuleLoader__.load({
           react.useEffect(() => {
             const cachedAt = window.__dshadbUpdateCheckedAt || 0;
             if (Date.now() - cachedAt < 5 * 60 * 1000) return; // 会话内查过就不重复
-            fetch("/api-dashboard/update", { headers: { accept: "application/json" } })
+            fetchT("/api-dashboard/update", { headers: { accept: "application/json" } })
               .then((r) => r.json())
               .then((d) => { if (d && d.ok) { window.__dshadbUpdateInfo = d; window.__dshadbUpdateCheckedAt = Date.now(); } })
               .catch(() => { /* 网络异常静默, 打开设置时可见固定错误文案 */ });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-api-dashboard",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "多平台 API 余额/用量看板插件：官方真实品牌图标，三层 UI 直接在输入框下方显示当前选中平台余额与估算消耗，点开底部抽屉切换所有平台；支持国内外平台与自定义中转站自动探测余额（查不到标未开放）；自定义安全/预警阈值，余额告警提醒；进入页面自动刷新",
   "keywords": [
     "dsh",
@@ -67,4 +67,4 @@
     }
   },
   "license": "MIT"
-}
+}

package/src/index.js

@@ -13,14 +13,53 @@
  *   - sessionProjections 单元 queryBalanceCost 估算本会话消耗 (按模型单价)。
  */
 
-import Schema from '@deepseek-ai/schemastery'
-import { z } from 'zod'
-import { readFileSync, writeFileSync, renameSync, chmodSync, existsSync, mkdirSync, rmSync, cpSync, statSync, readdirSync, realpathSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { readFileSync, writeFileSync, renameSync, chmodSync, existsSync, mkdirSync, rmSync, cpSync, statSync, lstatSync, readdirSync, realpathSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { tmpdir, homedir } from 'node:os'
 import { join, dirname, basename } from 'node:path'
 
+/**
+ * peer 依赖加载器（v1.4.1）—— 这一条直接决定「别人下载后能不能用」。
+ *
+ * 病症（真机实测复现）：用户按 README 执行 `dsh plugin --profile web add dsh-api-dashboard`，
+ * 安装成功，但启动时 **整个 dsh web 起不来**：
+ *
+ *   Cannot find package '@deepseek-ai/schemastery' imported from
+ *   /root/.local/share/pnpm/store/v10/files/42/e96689...
+ *
+ * 链路：profile 用 hoisted linker + autoInstallPeers:false（插件把它声明成 optional peer），
+ * DSHA 的 proot 带 `--link2symlink`，于是 pnpm 的硬链接被降级成**指向全局 store 的软链**；
+ * Node 的 ESM 会先把模块解析成 realpath，再从那开始向上找 node_modules ——
+ * 从 store 目录往上永远也走不到 `$DSH_HOME/profiles/node_modules`（DSH 放宿主依赖的地方）。
+ *
+ * 修法：先按常规 import；失败时改用宿主自己的模块回退目录做 CJS 解析
+ * （`createRequire` 用的是**给定路径**而不是 realpath，因此能穿透这层软链）。
+ * 这样 npm 安装、源码安装、软链安装三种布局都能加载。
+ */
+const resolvePeer = async (spec) => {
+  let primary = null
+  try { return await import(spec) } catch (e) { primary = e }
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const bases = [
+    join(home, 'profiles', 'node_modules', '__dshadb_resolver__.cjs'),
+    join(home, 'profiles', process.env.DSHA_STARTUP_PROFILE || 'web', 'node_modules', '__dshadb_resolver__.cjs'),
+  ]
+  for (const base of bases) {
+    try {
+      const entry = createRequire(base).resolve(spec)
+      return await import(pathToFileURL(entry).href)
+    } catch { /* 试下一个基准目录 */ }
+  }
+  throw primary
+}
+
+const schemaMod = await resolvePeer('@deepseek-ai/schemastery')
+const Schema = schemaMod.default ?? schemaMod
+const zodMod = await resolvePeer('zod')
+const z = zodMod.z ?? zodMod.default?.z ?? zodMod
+
 export const name = 'dsh-api-dashboard'
 
 // ============================================================
@@ -36,7 +75,33 @@ const MANIFEST_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/co
 const TARBALL_URL = `https://codeload.github.com/${REPO_OWNER}/${REPO_NAME}/tar.gz/refs/heads/${REPO_BRANCH}`
 
 /** 插件运行实体的安装根目录 (src/index.js 上两级; ESM 默认按 realpath 加载) */
-const SELF_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+/**
+ * 插件自身的安装根目录（v1.4.1）。
+ *
+ * 不能只用 `dirname(dirname(import.meta.url))`：ESM 会把符号链接解析成 realpath，
+ * 而 npm 装进 profile 后文件常常是**指向 pnpm store 的软链** → 算出来的根目录是
+ * `.../store/v10/files`，于是 assets（图标 / 大肥鱼贴图 / 音效）全部 404、
+ * 版本号也读不到（一键更新会误判）。
+ * 这里按候选顺序找第一个「package.json 里 name 就是本插件」的目录。
+ */
+const resolveSelfRoot = () => {
+  const fromUrl = dirname(dirname(fileURLToPath(import.meta.url)))
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profile = process.env.DSHA_STARTUP_PROFILE || 'web'
+  const candidates = [
+    fromUrl,
+    join(home, 'profiles', profile, 'node_modules', 'dsh-api-dashboard'),
+    join(home, 'profiles', 'node_modules', 'dsh-api-dashboard'),
+  ]
+  for (const dir of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+      if (pkg && pkg.name === 'dsh-api-dashboard') return dir
+    } catch { /* 试下一个 */ }
+  }
+  return fromUrl
+}
+const SELF_ROOT = resolveSelfRoot()
 
 /** 读取指定目录中 package.json 的 version, 异常返回 null */
 const readVersionAt = (dir) => {
@@ -96,7 +161,12 @@ export async function applyUpdate({ targets = null, timeoutMs = 30000, remoteVer
     try {
       const legacyReal = realPathSafe(join(homedir(), 'dsha-api-dashboard'))
       const selfReal = realPathSafe(SELF_ROOT)
-      if (legacyReal && selfReal && legacyReal !== selfReal && existsSync(join(legacyReal, 'package.json'))) {
+      // H-2 (v1.4.1): 自动同步 ~/dsha-api-dashboard 只对「非 git 工作区」生效。
+      // 以前不判断, 于是维护者/开发者的 git clone 会在一次"一键更新"后被 tarball 覆写 ——
+      // codeload 的 tarball 里**没有 .git**(已实测), 删掉就再也回不来。
+      if (legacyReal && selfReal && legacyReal !== selfReal
+          && existsSync(join(legacyReal, 'package.json'))
+          && !existsSync(join(legacyReal, '.git'))) {
         dirs.push(legacyReal)
       }
     } catch { /* 探测失败不影响主流程 */ }
@@ -104,6 +174,16 @@ export async function applyUpdate({ targets = null, timeoutMs = 30000, remoteVer
   for (const dir of dirs) {
     if (!existsSync(join(dir, 'package.json'))) throw new Error(`target missing: ${dir}`)
   }
+  // H-2 (v1.4.1): target 是符号链接时, 下面的 rmSync 会**穿透软链删光真实目录的内容**,
+  // 而 cpSync 对软链会抛 ERR_FS_CP_DIR_TO_NON_DIR; 备份 tar 里存的又只是软链本身 →
+  // 真实目录永久损坏且回滚不回来。遇到软链直接拒绝, 让用户改用真实路径。
+  for (const dir of dirs) {
+    let st = null
+    try { st = lstatSync(dir) } catch { st = null }
+    if (st && st.isSymbolicLink()) {
+      throw new Error(`refusing to update a symbolic-link target: ${dir} (use its real path instead)`)
+    }
+  }
 
   // 1) 下载 tarball 到临时文件
   const tmpBase = join(tmpdir(), `dshadb-update-${Date.now()}`)
@@ -138,7 +218,9 @@ export async function applyUpdate({ targets = null, timeoutMs = 30000, remoteVer
     // 5) 交换: 删旧内容 → 拷新内容 (node_modules 保留, 避免重装依赖)
     for (const dir of dirs) {
       swapped = true
-      const keep = new Set(['node_modules'])
+      // H-2 (v1.4.1): 必须保留 .git —— codeload 的 tarball 里没有它(实测),
+      // 删掉就等于把用户的 git 历史抹了, 且没有任何恢复途径。
+      const keep = new Set(['node_modules', '.git'])
       for (const entry of readdirSafe(dir)) {
         if (!keep.has(entry)) rmSync(join(dir, entry), { recursive: true, force: true })
       }
@@ -202,6 +284,15 @@ async function getUpdateStatus(force = false) {
 // ============================================================
 const STATE_FILE = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'dsh-api-dashboard.json')
 
+/**
+ * A（v1.4.1）: 每个中转站「上次探到的可用余额端点」的记忆表。
+ * `queryCustomRelay` 的 auto 探测是**串行**试 3 个候选端点, 每个都要跑满 timeoutMs ——
+ * 实测一次全量刷新因此要 8~13.6 秒。记住命中过的端点并优先试它, 稳态下每个中转站只打 1 个请求。
+ * 只做**排序提示**, 候选全表仍然会依次试, 所以某个中转站换了端点也能自动跟上。
+ * 持久化在状态文件 `relayEndpoints`（重启后依然生效）。
+ */
+const relayEndpointHints = new Map()
+
 /**
  * 状态文件结构版本。**改动已持久化字段的默认值时必须 +1 并补一段迁移**,
  * 否则老用户的状态文件会把字段钉死在旧值上 —— 新默认值对老用户永远不生效。
@@ -211,8 +302,44 @@ const STATE_FILE = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'dsh-ap
  */
 const CONFIG_VERSION = 2
 
+/**
+ * 形状消毒 (v1.4.1): 状态文件是**我们自己的代码**写的, 但写盘可能被打断
+ * (磁盘满/进程被杀/UTF-8 截断), 用户也可能手改。字段形状一旦跑偏,
+ * 后面的 `(persisted.customRelays ?? []).map(...)` 会抛 TypeError —— 而 apply() 抛出
+ * 会让 **整个 dsh web 启动失败**(不是插件不显示, 是 GUI 打不开), 用户完全无从下手。
+ * 所以这里把所有"本该是数组/对象/数字"的字段统一消毒, 消毒不了就丢弃, 绝不让 apply() 抛。
+ * ⚠️ 新增持久化字段时, 记得同步登记到这里。
+ */
+const ARRAY_FIELDS = ['customRelays', 'customModels', 'officialProviders', 'dshProviderOptOut', 'presets']
+const OBJECT_FIELDS = ['whaleSettings', 'prices', 'relayEndpoints']
+const NUMBER_FIELDS = [
+  ['refreshIntervalMs', 1000, 60000],   // H-4b: 曾经能持久化成 -1 → 3 秒内 1794 次上游请求
+  ['clientPollIntervalMs', 1000, 60000],
+  ['timeoutMs', 1000, 60000],
+  ['safeThreshold', 0, Number.MAX_SAFE_INTEGER],
+  ['warnThreshold', 0, Number.MAX_SAFE_INTEGER],
+  ['configVersion', 0, Number.MAX_SAFE_INTEGER],
+]
+
+const sanitizePersistedShape = (s) => {
+  const out = { ...s }
+  for (const k of ARRAY_FIELDS) {
+    if (k in out && !Array.isArray(out[k])) delete out[k]
+  }
+  for (const k of OBJECT_FIELDS) {
+    if (k in out && (out[k] === null || typeof out[k] !== 'object' || Array.isArray(out[k]))) delete out[k]
+  }
+  for (const [k, min, max] of NUMBER_FIELDS) {
+    if (!(k in out)) continue
+    const n = Number(out[k])
+    if (!Number.isFinite(n)) { delete out[k]; continue }
+    out[k] = Math.min(Math.max(Math.round(n), min), max)
+  }
+  return out
+}
+
 const migratePersistedState = (parsed) => {
-  const s = (parsed && typeof parsed === 'object') ? parsed : {}
+  const s = sanitizePersistedShape((parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {})
   const ver = Number.isFinite(s.configVersion) ? s.configVersion : 1
   let out = s
   if (ver < 2) {
@@ -234,6 +361,9 @@ const loadPersistedState = () => {
 const savePersistedState = (state) => {
   try {
     const merged = { ...loadPersistedState(), ...state }
+    // H-4c (v1.4.1): 以前这里从不建父目录, 且吞掉所有异常 → ~/.dsh 不存在时
+    // 接口照样回 ok:true, 用户配置"保存成功"却没落盘, 重启即丢。现在先建目录。
+    mkdirSync(dirname(STATE_FILE), { recursive: true })
     // mode 0o600: 状态文件含自定义中转站/模型的 API Key 明文, 必须限定本用户可读
     // (不能依赖 umask —— 默认 umask 0022 的桌面机会落成 0644); chmod 兜底修正旧文件
     writeFileSync(STATE_FILE + '.tmp', JSON.stringify(merged, null, 2), { encoding: 'utf8', mode: 0o600 })
@@ -471,7 +601,15 @@ export const selectDshProviders = (entries, kinds, optOut) => {
  */
 export const planBalancesFetch = ({ force = false, peek = false, hasData = false, age = 0, intervalMs = 5000 } = {}) => {
   const stale = age > (intervalMs || 300000)   // 兼容旧行为: intervalMs 缺失时用 5 分钟
-  if (!hasData) return 'wait'                  // 冷启动(服务端刚重启): 确实没东西可显示, 只能等
+  /**
+   * v1.4.1: 冷启动**不再阻塞首屏**。
+   * 旧行为是 `return 'wait'` —— 服务端刚重启时缓存为空, 第一个请求要 await 一次**全量**刷新,
+   * 而实测全量刷新要 8~13.6 秒(中转站 auto 探测是串行试 3 个端点), 用户看到的就是
+   * 「重启进来等半天」。现在改成: 立刻回「还在加载」+ 把刷新丢后台, 客户端保持骨架屏并**1.5 秒后重问**,
+   * 数据一到就上屏。注意这**不是假数据** —— 返回的是空列表 + loading 标记, 界面显示的是"加载中"而非 0。
+   * 只有显式强刷(force, 用户主动要新数据)才继续阻塞等。
+   */
+  if (!hasData) return force ? 'wait' : 'background'
   if (!force && !stale) return 'none'
   if (peek) return age > 1000 ? 'background' : 'none'  // 1 秒内刚拉过就不重复打
   return age > 2000 ? 'wait' : 'none'          // 显式强刷留 2 秒节流, 防连点打爆平台接口
@@ -945,12 +1083,18 @@ async function fetchWithTimeout(url, headers, timeoutMs, method = 'GET') {
 
 /** 读取请求体并限制大小 (默认 256KB) —— 防持有 token 者灌大包打爆内存。超限抛错。 */
 async function readBody(req, limit = 256 * 1024) {
-  let body = ''
+  // H-4d (v1.4.1): 不能对每个 chunk 单独 toString —— 一个汉字的 3 个字节被 TCP 分到两个 chunk 时,
+  // 两边都会解出替换字符 U+FFFD, 中文中转站名/自定义模型名会被写坏并持久化(实测)。
+  // 改成先收集 Buffer 再整体解码。
+  const chunks = []
+  let size = 0
   for await (const chunk of req) {
-    body += chunk
-    if (body.length > limit) throw Object.assign(new Error('request body too large'), { statusCode: 413 })
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buf.length
+    if (size > limit) throw Object.assign(new Error('request body too large'), { statusCode: 413 })
+    chunks.push(buf)
   }
-  return body
+  return Buffer.concat(chunks).toString('utf8')
 }
 
 /** 字符串清洗: 截断到 max 长度 (设置面板传入的任意字段统一过这里) */
@@ -1140,11 +1284,22 @@ export function parseResponse(queryType, json) {
       if (!json || typeof json !== 'object') return null
       const hasAny = 'total_granted' in json || 'total_available' in json || 'total_used' in json
       if (!hasAny) return null
-      const total = toAmount(json?.total_granted)
-      const used = toAmount(json?.total_used)
-      const hasAvail = json?.total_available != null
-      const available = hasAvail ? toAmount(json.total_available) : null
-      return { total: hasAvail ? available : (total - used), currency: 'USD', available, used, note: 'OpenAI 兼容额度' }
+      // H-4a (v1.4.1): 字段**存在但值无效**(null / 非数字)时, toAmount 会归 0,
+      // 于是 total = 0 - used 得到一个**负数余额** —— 与 openrouter 那次是同一类漏洞
+      // (红线: 不许把解析失败冒充成真实数字)。这里改成「值无效就不表态」。
+      // ⚠️ Number(null) === 0、Number('') === 0 —— 必须先把「空值」挡掉, 否则等于没挡
+      const numOrNull = (v) => {
+        if (v === null || v === undefined || v === '') return null
+        const n = Number(v)
+        return Number.isFinite(n) ? n : null
+      }
+      const grantedN = numOrNull(json?.total_granted)
+      const usedN = numOrNull(json?.total_used)
+      const availN = numOrNull(json?.total_available)
+      if (availN === null && (grantedN === null || usedN === null)) return null
+      const used = usedN ?? 0
+      const hasAvail = availN !== null
+      return { total: hasAvail ? availN : (grantedN - used), currency: 'USD', available: hasAvail ? availN : null, used, note: 'OpenAI 兼容额度' }
     }
     case 'siliconflow': {
       const d = json?.data
@@ -1398,6 +1553,13 @@ async function queryCustomRelay(relay, config) {
     )
   }
 
+  // A: 命中过的端点排到最前（只影响顺序, 不影响"全都会试一遍"的语义）
+  if (candidates.length > 1 && relayEndpointHints.has(id)) {
+    const hint = relayEndpointHints.get(id)
+    const idx = candidates.findIndex((c) => c.type === hint)
+    if (idx > 0) candidates.unshift(candidates.splice(idx, 1)[0])
+  }
+
   for (const cand of candidates) {
     const headers = { Accept: 'application/json', Authorization: `Bearer ${apiKey}` }
     const method = cand.type === 'quota' ? 'POST' : 'GET'
@@ -1409,6 +1571,11 @@ async function queryCustomRelay(relay, config) {
       try { json = JSON.parse(text) } catch { continue }
       const parsed = parseResponse(cand.type, json)
       if (parsed) {
+        // A: 记住这次命中的端点（变了才落盘, 避免每次刷新都写状态文件）
+        if (relayEndpointHints.get(id) !== cand.type) {
+          relayEndpointHints.set(id, cand.type)
+          try { savePersistedState({ relayEndpoints: Object.fromEntries(relayEndpointHints) }) } catch { /* 落盘失败不影响本次结果 */ }
+        }
         return {
           platform: id, name: name || '中转站', icon: 'relay', color: '#64748B', category: '中转站',
           status: 'ok', total: parsed.total, currency: parsed.currency, available: parsed.available,
@@ -1914,13 +2081,25 @@ export function makeCostProjection(configOrGetter, services) {
 export function apply(ctx, config) {
   // 用户保存的配置优先于 cordis.patch.yml 的默认 config (持久化状态)
   const persisted = loadPersistedState()
+  // A: 载入上次记住的中转站端点
+  try {
+    relayEndpointHints.clear()
+    const saved = persisted.relayEndpoints
+    if (saved && typeof saved === 'object' && !Array.isArray(saved)) {
+      for (const [k, v] of Object.entries(saved)) {
+        if (typeof k === 'string' && k.length <= 128 && typeof v === 'string' && v.length <= 32) relayEndpointHints.set(k, v)
+      }
+    }
+  } catch { /* 忽略 */ }
   const runtimeConfig = {
     refreshIntervalMs: persisted.refreshIntervalMs ?? config.refreshIntervalMs ?? 5000,
     clientPollIntervalMs: persisted.clientPollIntervalMs ?? config.clientPollIntervalMs ?? 5000,
     timeoutMs: persisted.timeoutMs ?? config.timeoutMs ?? 8000,
     presets: config.presets ?? PLATFORM_PRESETS.map(p => p.id),
-    customRelays: (persisted.customRelays ?? config.customRelays ?? []).map(r => ({ ...r })),
-    customModels: (persisted.customModels ?? config.customModels ?? []).map(m => ({ ...m })),
+    // H-1 (v1.4.1): 这里必须带 Array.isArray —— 状态文件形状跑偏时 apply() 抛出 =
+    // 整个 dsh web 启动失败(migratePersistedState 已消毒, 这里是第二道防线)
+    customRelays: (Array.isArray(persisted.customRelays) ? persisted.customRelays : (Array.isArray(config.customRelays) ? config.customRelays : [])).map(r => ({ ...r })),
+    customModels: (Array.isArray(persisted.customModels) ? persisted.customModels : (Array.isArray(config.customModels) ? config.customModels : [])).map(m => ({ ...m })),
     prices: config.prices ?? { 'deepseek-chat': { cacheHit: 0.1, cacheMiss: 1, output: 2 } },
     defaultPrices: config.defaultPrices ?? { cacheHit: 0.1, cacheMiss: 1, output: 2 },
     currency: persisted.currency ?? config.currency ?? 'CNY',
@@ -2129,9 +2308,51 @@ export function apply(ctx, config) {
       res.end(body)
     }
 
+    /**
+     * H-3 (v1.4.1): 插件路由的鉴权闸门。
+     *
+     * 为什么必须有这道闸: dsh 的 webserver 是「先查 exact 路由表, 再走 fallback」,
+     * 而浏览器的登录 cookie 校验只写在 fallback 里(dsh-host-frontend-static) ——
+     * 于是 `/api-dashboard/*` 全部绕过鉴权: 无需 token、无需 cookie 就能读配置、
+     * 改配置、改挂件、甚至触发 `/update/install`(会重写插件目录)。
+     * 更糟的是 `Content-Type: text/plain` 属于**浏览器不预检的 simple request**,
+     * 用户手机上随便打开一个网页, 那个网页就能 POST 过来改配置(实测 HTTP 200 且真的改了)。
+     *
+     * 老版本 dsh 没有 connection 服务时放行(那时本来也没有鉴权概念), 避免把插件打死。
+     */
+    /**
+     * H-3 (v1.4.1): 插件路由的鉴权闸门。
+     *
+     * 为什么必须有这道闸: dsh 的 webserver 是「先查 exact 路由表, 再走 fallback」,
+     * 而浏览器的登录 cookie 校验只写在 fallback 里(dsh-host-frontend-static) ——
+     * 于是 `/api-dashboard/*` 全部绕过鉴权: 无需 token、无需 cookie 就能读配置、
+     * 改配置、改挂件、甚至触发 `/update/install`(会重写插件目录)。
+     * 更糟的是 `Content-Type: text/plain` 属于**浏览器不预检的 simple request**,
+     * 用户手机上随便打开一个网页, 那个网页就能 POST 过来改配置(实测 HTTP 200 且真的改了)。
+     *
+     * 用 `connection.requestRejection(req)`: 与 dsh-web-mobile 同一个闸门,
+     * 同时覆盖「浏览器 cookie 鉴权」与「Host/来源可信」两项检查。
+     * ⚠️ 不能写 `ctx.get('connection')` —— 实测在插件 fiber 上取不到(返回 undefined),
+     *    必须用嵌套 inject 拿服务实例。
+     */
+    let connectionSvc = null
+    ctx.inject(['connection'], (c) => { connectionSvc = c.connection })
+    const allowRequest = (req, res) => {
+      const conn = connectionSvc
+      // 老版本 dsh 没有 connection 服务时放行(那时本来也没有鉴权概念), 避免把插件打死
+      if (!conn || typeof conn.requestRejection !== 'function') return true
+      let rejection
+      try { rejection = conn.requestRejection(req) } catch { rejection = undefined }
+      if (rejection === undefined) return true
+      res.writeHead(rejection, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' })
+      res.end(rejection === 401 ? 'dsh web authentication required; reopen the URL printed by dsh web.\n' : 'forbidden\n')
+      return false
+    }
+
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/balances',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (!['GET', 'HEAD', 'POST'].includes(req.method)) { res.writeHead(405, { Allow: 'GET, HEAD, POST' }); res.end(); return }
         const params = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams
         const force = req.method === 'POST' || params.get('force') === '1'
@@ -2160,7 +2381,7 @@ export function apply(ctx, config) {
           res.end()
           return
         }
-        const body = JSON.stringify({ ok: true, balances: cache.balances, fetchedAt: cache.fetchedAt, config: cache.config })
+        const body = JSON.stringify({ ok: true, balances: cache.balances, fetchedAt: cache.fetchedAt, config: cache.config, loading: cache.balances.length === 0 })
         res.writeHead(200, {
           'Content-Type': 'application/json; charset=utf-8',
           'Cache-Control': 'private, no-cache',
@@ -2175,6 +2396,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/prices',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         const cfg = runtimeConfig
         const cur = (cfg.currency ?? 'CNY').toUpperCase() === 'USD' ? 'USD' : 'CNY'
@@ -2195,6 +2417,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/platforms',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         const presets = PLATFORM_PRESETS.filter(p => runtimeConfig.presets.includes(p.id)).map(p => ({
           id: p.id, name: p.label, icon: p.icon, color: p.color, category: p.category, queryType: p.queryType,
@@ -2207,6 +2430,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/update',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         const force = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('force') === '1'
         try {
@@ -2221,6 +2445,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/update/install',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'POST') { res.writeHead(405, { Allow: 'POST' }); res.end(); return }
         try {
           const result = await applyUpdate({})
@@ -2242,6 +2467,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/icon',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         try {
           if (!iconCache) {
@@ -2267,6 +2493,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/whale/image.png',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         try {
           if (!whaleImgCache) whaleImgCache = readFileSync(whaleAsset('DSniang1.png'))
@@ -2284,6 +2511,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/whale/rua.gif',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
         try {
           if (!whaleGifCache) whaleGifCache = readFileSync(whaleAsset('rua.gif'))
@@ -2301,6 +2529,7 @@ export function apply(ctx, config) {
       webCtx.effect(() => webCtx.webServer.register({
         kind: 'exact', path: `/api-dashboard/whale/sound/${kind}.mp3`,
         async handler(req, res) {
+        if (!allowRequest(req, res)) return
           if (req.method !== 'GET') { res.writeHead(405, { Allow: 'GET' }); res.end(); return }
           try {
             const set = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('set') === 'fx1' ? 'fx1' : 'duck'
@@ -2322,6 +2551,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/whale/settings',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method === 'GET') { sendJson(res, 200, { ok: true, settings: runtimeConfig.whaleSettings }); return }
         if (req.method === 'PUT' || req.method === 'POST') {
           try {
@@ -2372,6 +2602,7 @@ export function apply(ctx, config) {
     webCtx.effect(() => webCtx.webServer.register({
       kind: 'exact', path: '/api-dashboard/config',
       async handler(req, res) {
+        if (!allowRequest(req, res)) return
         if (req.method === 'GET') {
           sendJson(res, 200, {
             ok: true,
@@ -2380,6 +2611,11 @@ export function apply(ctx, config) {
             presets: runtimeConfig.presets,
             refreshIntervalSec: Math.round(runtimeConfig.refreshIntervalMs / 1000),
             currency: runtimeConfig.currency,
+            // C-2 (v1.4.1): 以前这里不返回阈值, 设置面板只能等 /balances 带过来;
+            // 冷启动那几秒(/balances 可能要等 8~10s)打开面板 → 显示默认 50/10 →
+            // 用户一点"保存并生效"就把自己存的阈值覆盖掉了。补上。
+            safeThreshold: runtimeConfig.safeThreshold,
+            warnThreshold: runtimeConfig.warnThreshold,
             overseasCurrency: runtimeConfig.overseasCurrency,
             whaleEnabled: !!runtimeConfig.whaleEnabled,
             showNoBalanceBrands: !!runtimeConfig.showNoBalanceBrands,