@mrrisega/dsh-remote 0.6.5 → 0.6.6-beta.2

package/clients/dsh-remote/mobile-adapter.mjs

@@ -478,13 +478,31 @@ const SCRIPT = `(() => {
 
       const toggleSel = '[aria-label="打开侧边栏"], [aria-label="关闭侧边栏"], [aria-label="Open sidebar"], [aria-label="Close sidebar"]';
       const toggleOf = () => document.querySelector(toggleSel) || document.querySelector(".hHd-Xa_toggle");
-      const expanded = () => !frame.hasAttribute("data-sidebar-collapsed");
+      /* 官方用 data-sidebar-collapsed 表达折叠态，但写法有两种可能：只输出属性本身，
+         或输出 attribute 的值（例如 =false）。旧实现只看 hasAttribute 是否存在，
+         只兼容前一种：一旦官方用带值写法，就会被永久判定为「展开」→ 遮罩常亮且拦截点击、
+         汉堡按钮被隐藏 → 手机端整屏阴影、点哪都没反应（用户实测）。
+         这里改成读值，两种写法都能正确判断。 */
+      const truthyAttr = (el, name) => {
+        const v = el.getAttribute(name);
+        if (v === null) return false;
+        const s = String(v).trim().toLowerCase();
+        return !(s === "" || s === "false" || s === "0" || s === "off" || s === "no");
+      };
+      const collapsed = () => truthyAttr(frame, "data-sidebar-collapsed");
+      const expanded = () => !collapsed();
 
       /* 遮罩:点击 = 点官方 toggle(走官方 store,无私有状态) */
       const scrim = document.createElement("div");
       scrim.className = "dsh-ma-scrim";
       document.body.appendChild(scrim);
-      scrim.addEventListener("click", (e) => { e.stopPropagation(); const t = toggleOf(); if (t) t.click(); });
+      scrim.addEventListener("click", (e) => {
+        e.stopPropagation();
+        const t = toggleOf();
+        if (t) { t.click(); return; }
+        /* 兜底:找不到官方 toggle 时**至少让用户能自救**（否则就是"点哪都没反应"的死局） */
+        document.documentElement.classList.remove("dsh-ma-sidebar-open", "dsh-ma-details-open");
+      });
 
       /* 顶部小鲸鱼/菜单按钮 */
       const hamburger = document.createElement("button");
@@ -496,21 +514,44 @@ const SCRIPT = `(() => {
       hamburger.addEventListener("click", (e) => {
         e.stopPropagation(); e.preventDefault();
         const t = toggleOf();
-        if (t) t.click();
-        else document.documentElement.classList.add("dsh-ma-sidebar-open"); /* 兜底 */
+        if (t) { t.click(); return; }
+        /* 兜底（无官方 toggle）：按当前状态切换，保证"开得了也关得掉" */
+        const open = document.documentElement.classList.contains("dsh-ma-sidebar-open");
+        if (open) document.documentElement.classList.remove("dsh-ma-sidebar-open", "dsh-ma-details-open");
+        else document.documentElement.classList.add("dsh-ma-sidebar-open");
       });
 
-      /* 状态唯一真源 = 官方 frame 的 data 属性 */
+      /* 侧栏是否**真的**滑进了视口。这是"遮罩能不能拦截点击"的最后一道保险：
+         只要官方属性语义与我们理解的不一致，光看属性就可能误判；而遮罩一旦拦截整屏，
+         用户看到的就是"整屏阴影 + 点哪都没反应"。以实测几何为准，误判也不会挡住用户。 */
+      const inView = (el) => {
+        if (!el) return false;
+        try { const r = el.getBoundingClientRect(); return !!r && r.right > 8 && r.width > 40; }
+        catch (e2) { return false; }
+      };
+      const sidebarInView = () => inView(sidebar || document.querySelector(".dsh-ma-sidebar"));
+      /* 状态唯一真源 = 官方 frame 的 data 属性（判定）+ 真实几何（放行遮罩） */
       const sync = () => {
         const open = expanded();
-        document.documentElement.classList.toggle("dsh-ma-sidebar-open", open);
-        if (hamburger) hamburger.style.display = open ? "none" : "";
-        const dOpen = !frame.hasAttribute("data-details-collapsed") && !!details;
+        const scrimOn = open && sidebarInView();
+        document.documentElement.classList.toggle("dsh-ma-sidebar-open", scrimOn);
+        /* 汉堡按钮**始终可见**：以前判定为"展开"时会把它 display:none 隐藏，
+           于是判定一旦出错（或遮罩因异常常亮），用户既点不动内容、也没有任何入口 —— 死局。
+           保持可见 + 点它可开可关（见其 click 处理），任何异常状态下都留一条出路。 */
+        if (hamburger) hamburger.style.display = "";
+        // 详情栏同理：只有"判定为展开"且"真的在视口里"才让遮罩拦截
+        const dOpen = !truthyAttr(frame, "data-details-collapsed") && !!details && inView(details);
         document.documentElement.classList.toggle("dsh-ma-details-open", dOpen);
       };
       try {
         new MutationObserver(sync).observe(frame, { attributes: true, attributeFilter: ["data-sidebar-collapsed", "data-details-collapsed"] });
       } catch (e2) { /* 退化:仅在下次 boot 同步 */ }
+      // 几何变化（旋转屏幕 / 窗口缩放 / 侧栏动画结束）也要重算，否则会把 boot 时的判定一直沿用
+      try {
+        window.addEventListener("resize", sync, { passive: true });
+        window.addEventListener("orientationchange", sync, { passive: true });
+        if (sidebar && typeof ResizeObserver === "function") new ResizeObserver(sync).observe(sidebar);
+      } catch (e2) { /* 非关键 */ }
       sync();
       /* 窄屏抽屉:点选会话(激活行)/点侧栏内「新建会话」后自动收起(官方不做;适配层点官方 toggle)。
          仅当:窄屏 && 抽屉展开 && 点击发生在侧栏抽屉内;行内「⋯」按钮 stopPropagation 不会误触。 */

package/clients/dsh-remote/test/mobile-adapter-runtime.test.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * mobile-adapter **运行时**契约测试（假 DOM + vm 执行真实注入脚本）。
+ *
+ * 事故背景（2026-09-15 生产反馈）：
+ *   手机端用户打开后**整屏被阴影覆盖、点哪都没反应**，只有左侧栏（z-index 300，在遮罩之上）能点。
+ *   根因是适配层自己创建的全屏 scrim（div.dsh-ma-scrim, z-index 290）：
+ *     · 判定「侧栏是否展开」用的是 `!frame.hasAttribute("data-sidebar-collapsed")`，
+ *       只兼容"折叠时才输出属性"这一种写法；官方若用带值写法，就永久判定为展开 →
+ *       html 上的 dsh-ma-sidebar-open 常亮 → scrim 永久 pointer-events:auto（拦截整屏点击）；
+ *     · 且判定为展开时还会把汉堡按钮 display:none 隐藏掉，"打开菜单/关掉遮罩"的入口也没了；
+ *     · 唯一关闭路径是"点 scrim → 点官方 toggle"，找不到 toggle 就彻底卡死。
+ *
+ * 本用例直接拿 injectMobileAdapter() 注入的**真实脚本**在假 DOM 里跑，断言运行时行为
+ * （既有用例只测注入纯函数，覆盖不到这里，所以这个 bug 当初没被任何测试拦住）。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import { injectMobileAdapter } from "../mobile-adapter.mjs";
+
+/** 从注入结果里取出真正的 <script> 内容（不加壳，原样执行）。 */
+function adapterScript() {
+  const { html } = injectMobileAdapter("<!doctype html><html><head></head><body></body></html>");
+  const m = /<script id="[^"]*-js"[^>]*>([\s\S]*?)<\/script>/.exec(html);
+  assert.ok(m, "应能取出注入脚本");
+  return m[1];
+}
+
+// ── 极简假 DOM ────────────────────────────────────────────────────────────────
+class El {
+  constructor(tag = "div", attrs = {}) {
+    this.tagName = String(tag).toUpperCase();
+    this.attrs = { ...attrs };
+    this.children = [];
+    this._cls = new Set();
+    this._listeners = new Map();
+    this.style = {};
+    this._rect = { left: 0, right: 0, top: 0, bottom: 0, width: 0, height: 0 };
+    this.classList = {
+      add: (...cs) => cs.forEach((c) => this._cls.add(c)),
+      remove: (...cs) => cs.forEach((c) => this._cls.delete(c)),
+      contains: (c) => this._cls.has(c),
+      toggle: (c, on) => { if (on === undefined) { this._cls.has(c) ? this._cls.delete(c) : this._cls.add(c); } else if (on) this._cls.add(c); else this._cls.delete(c); return this._cls.has(c); },
+    };
+  }
+  get className() { return [...this._cls].join(" "); }
+  set className(v) { this._cls = new Set(String(v).split(/\s+/).filter(Boolean)); }
+  getAttribute(n) { return n in this.attrs ? this.attrs[n] : null; }
+  setAttribute(n, v) { this.attrs[n] = String(v); }
+  hasAttribute(n) { return n in this.attrs; }
+  appendChild(c) { c.parent = this; this.children.push(c); return c; }
+  addEventListener(t, fn) { (this._listeners.get(t) || this._listeners.set(t, []).get(t)).push(fn); }
+  removeEventListener() {}
+  dispatch(t, ev = {}) { for (const fn of this._listeners.get(t) || []) fn({ stopPropagation() {}, preventDefault() {}, ...ev }); }
+  getBoundingClientRect() { return this._rect; }
+  querySelector() { return null; }
+  querySelectorAll() { return []; }
+  matches() { return false; }
+  click() { this._clicked = (this._clicked || 0) + 1; this.dispatch("click"); }
+  get isConnected() { return true; }
+}
+
+/** 搭一个最小 dsh web 环境：frame（带官方 data 属性）内含 sidebar/center 两列 + 可选官方 toggle。 */
+function harness({ collapsedAttr = undefined, detailsAttr = undefined, sidebarRect = null, width = 390, withToggle = true } = {}) {
+  const html = new El("html");
+  // HOSTISH 门禁会读 documentElement.outerHTML 找官方特征（__ModuleLoader__ / DeepSeek Harness）
+  html.outerHTML = '<html><head><script>window.__ModuleLoader__ = { mode: "queue" }</script>'
+    + "<title>DeepSeek Harness</title></head><body></body></html>";
+  const body = new El("body");
+  const frame = new El("div");
+  if (collapsedAttr !== undefined) frame.setAttribute("data-sidebar-collapsed", collapsedAttr);
+  if (detailsAttr !== undefined) frame.setAttribute("data-details-collapsed", detailsAttr);
+
+  const sidebar = new El("div", { class: "sidebarCol" });
+  const center = new El("div", { class: "centerCol" });
+  if (sidebarRect) sidebar._rect = sidebarRect;
+  frame.appendChild(sidebar);
+  frame.appendChild(center);
+  const toggle = new El("button");
+  toggle.setAttribute("aria-label", "打开侧边栏");
+
+  const pickByClass = (sel) => {
+    // 只支持本用例需要的极少数选择器（脚本里 querySelector 的用法就这些）
+    const s2 = String(sel);
+    if (/\.dsh-ma-sidebar/.test(s2)) return sidebar._cls.size ? sidebar : null;
+    if (/\.hHd-Xa_root|sidebar/i.test(s2)) return sidebar;
+    return null;
+  };
+  const frameQ = (sel) => pickByClass(sel);
+  frame.querySelector = frameQ;
+  frame.querySelectorAll = () => [];
+  const doc = {
+    documentElement: html,
+    body,
+    readyState: "complete",
+    addEventListener() {},
+    querySelector(sel) {
+      const s2 = String(sel);
+      if (s2.includes(".pI_x6G_frame") || s2.includes("[data-sidebar-collapsed], [data-details-collapsed]") || s2.includes("[data-shell-overlay]")) return frame;
+      if (s2.includes("aria-label=")) return withToggle ? toggle : null;
+      if (s2.includes(".hHd-Xa_toggle")) return withToggle ? toggle : null;
+      if (s2.includes("hHd-Xa")) return sidebar; // 子列识别用（真实页面里这是侧栏）
+      return pickByClass(s2);
+    },
+    querySelectorAll() { return []; },
+    createElement: (t) => new El(t),
+    createTextNode: (t) => ({ nodeValue: t }),
+    getElementById: () => null,
+  };
+
+  const timers = new Map();
+  const win = {
+    innerWidth: width,
+    innerHeight: 800,
+    devicePixelRatio: 1,
+    localStorage: { getItem: () => null, setItem() {}, removeItem() {} },
+    addEventListener() {},
+    removeEventListener() {},
+    getComputedStyle: () => ({ getPropertyValue: () => "" }),
+    requestAnimationFrame: (fn) => { const id = setImmediate(fn); return id; },
+    setTimeout: (fn, ms) => { const id = setTimeout(fn, ms); timers.set(id, fn); return id; },
+    clearTimeout: (id) => clearTimeout(id),
+    MutationObserver: class { observe() {} disconnect() {} },
+    ResizeObserver: class { observe() {} disconnect() {} },
+  };
+  const ctx = vm.createContext({
+    window: win, document: doc, console, setTimeout: win.setTimeout, clearTimeout: win.clearTimeout,
+    setInterval: () => 0, clearInterval() {}, MutationObserver: win.MutationObserver,
+    ResizeObserver: win.ResizeObserver, requestAnimationFrame: win.requestAnimationFrame,
+    navigator: { userAgent: "iPhone Safari", maxTouchPoints: 5, platform: "iPhone" },
+    location: { href: "https://n.risegao.cn:13443/app/", host: "n.risegao.cn" },
+    localStorage: win.localStorage, URL, Date, Math, JSON, Object, Array, String, Number, RegExp, Boolean, Promise, Error, isNaN, parseInt, parseFloat,
+    HTMLElement: El, // 脚本用 `c instanceof HTMLElement` 过滤 frame 的子列
+  });
+  win.onerror = (m) => { if (ADAPTER_DEBUG) console.error("ADAPTER onerror:", m); };
+  const dbgConsole = ADAPTER_DEBUG
+    ? { log: (...a) => console.error("[adapter]", ...a), warn: (...a) => console.error("[adapter warn]", ...a), error: (...a) => console.error("[adapter err]", ...a) }
+    : console;
+  ctx.console = dbgConsole;
+  ctx.globalThis = ctx;
+  ctx.self = win;
+  return { ctx, html, body, frame, sidebar, toggle, win };
+}
+
+const ADAPTER_DEBUG = process.env.DSH_ADAPTER_DEBUG === "1";
+
+function runAdapter(env) {
+  try {
+    vm.runInContext(adapterScript(), env.ctx, { timeout: 5000 });
+  } catch (e) {
+    if (ADAPTER_DEBUG) console.error("ADAPTER THREW:", e && e.message);
+    throw e;
+  }
+  // sync() 在 boot 时立即执行一次；脚本内用 setTimeout/rAF 的场景再推一轮
+  return env;
+}
+
+const findScrim = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-scrim"));
+const findHamburger = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-hamburger"));
+
+// ── 用例 ─────────────────────────────────────────────────────────────────────
+
+test("运行时：官方属性带值写法 =false 时不得判定为展开 → 遮罩不拦截点击（用户报的整屏阴影）", () => {
+  // 官方若输出 data-sidebar-collapsed="false"（属性存在但语义为未折叠），旧实现 hasAttribute → 判定展开 → 遮罩常亮
+  const env = runAdapter(harness({ collapsedAttr: "false", sidebarRect: null }));
+  assert.ok(!env.html.classList.contains("dsh-ma-sidebar-open"),
+    "属性值 false = 未折叠 → 不应加 sidebar-open（否则遮罩会拦住整屏点击）");
+});
+
+test("运行时：即使判定为展开，侧栏没真的滑进视口时也不得拦截点击", () => {
+  // 属性"存在且无值"在旧实现里就是展开；这里再叠加"侧栏几何不在视口内"（left:0/right:0）→ 仍不得拦截
+  const env = runAdapter(harness({ collapsedAttr: "", sidebarRect: { left: 0, right: 0, top: 0, bottom: 800, width: 0, height: 800 } }));
+  assert.ok(!env.html.classList.contains("dsh-ma-sidebar-open"),
+    "侧栏未滑入视口 → 遮罩必须保持 pointer-events:none（几何兜底）");
+  const scrim = findScrim(env);
+  assert.ok(scrim, "遮罩元素本身仍应创建（关闭态只是不拦截）");
+});
+
+test("运行时：侧栏真的滑入视口（right>8 且有宽度）时才允许拦截点击", () => {
+  const env = runAdapter(harness({ collapsedAttr: "", sidebarRect: { left: 0, right: 300, top: 0, bottom: 800, width: 300, height: 800 } }));
+  assert.ok(env.html.classList.contains("dsh-ma-sidebar-open"),
+    "抽屉确实展开时遮罩才应显示并拦截（正常行为不能被改坏）");
+});
+
+test("运行时：判定为展开时不再隐藏汉堡按钮（避免用户没有任何入口）", () => {
+  const env = runAdapter(harness({ collapsedAttr: "", sidebarRect: { left: 0, right: 300, top: 0, bottom: 800, width: 300, height: 800 } }));
+  const ham = findHamburger(env);
+  assert.ok(ham, "汉堡按钮应存在");
+  assert.notEqual(ham.style.display, "none",
+    "抽屉展开时也不应把汉堡隐藏 —— 判定一旦出错，用户会连入口都没有（事故现场就是这个死局）");
+});
+
+test("运行时：找不到官方 toggle 时，点遮罩必须能自救（摘掉遮挡类）", () => {
+  const env = runAdapter(harness({ collapsedAttr: "", sidebarRect: { left: 0, right: 300, top: 0, bottom: 800, width: 300, height: 800 }, withToggle: false }));
+  assert.ok(env.html.classList.contains("dsh-ma-sidebar-open"), "前提：先处于遮挡态");
+  const scrim = findScrim(env);
+  scrim.dispatch("click");
+  assert.ok(!env.html.classList.contains("dsh-ma-sidebar-open"),
+    "找不到官方 toggle 时，点遮罩应直接摘掉遮挡类（否则点哪都没反应）");
+});
+
+test("运行时：能拿到官方 toggle 时，点遮罩仍走官方 toggle（不引入私有状态）", () => {
+  const env = runAdapter(harness({ collapsedAttr: "", sidebarRect: { left: 0, right: 300, top: 0, bottom: 800, width: 300, height: 800 }, withToggle: true }));
+  const scrim = findScrim(env);
+  scrim.dispatch("click");
+  assert.ok(env.toggle._clicked >= 1, "应点击官方 toggle");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrisega/dsh-remote",
-  "version": "0.6.5",
+  "version": "0.6.6-beta.2",
   "description": "手机远程控制 DeepSeek Harness · Remote control DeepSeek Harness (dsh web) from any phone browser — 100% 全功能 App 级体验：发消息、看工具执行、审批权限、改设置、管凭据，含特权操作，免内网穿透。一条命令安装 npx @mrrisega/dsh-remote。Mobile remote control for DSH, self-host or SaaS, no server needed on LAN.",
   "keywords": [
     "deepseek-harness",
@@ -54,9 +54,7 @@
     "_comment:test:plugin": "DSH_RELAY_SKIP_SERVICE=1 = 测试隔离：插件加载时不做真实系统操作（npx 补装 / launchctl / 重启 harness）；需要真实分支的用例自行 unset（见 account-switch / runtime-provision / harness-restart 用例注释）",
     "test:plugin": "DSH_REMOTE_TELEMETRY=0 DSH_RELAY_SKIP_SERVICE=1 node --test --test-concurrency=1 packages/dsh-remote-web/test/*.test.mjs",
     "test:bridge": "node --test clients/dsh-remote/test/*.test.mjs",
-    "check": "node --check clients/dsh-remote/dsh-bridge.mjs && node --check clients/dsh-remote/e2ee-shim.mjs && node --check dsh-setup.mjs && node --check packages/dsh-remote-web/lib/index.js && node --check packages/dsh-remote-web/lib/client.js && bash -n deploy/install-open.sh && npm run check:alias",
-    "sync:alias": "node scripts/sync-legacy-alias.mjs",
-    "check:alias": "node scripts/sync-legacy-alias.mjs --check",
+    "check": "node --check clients/dsh-remote/dsh-bridge.mjs && node --check clients/dsh-remote/e2ee-shim.mjs && node --check dsh-setup.mjs && node --check packages/dsh-remote-web/lib/index.js && node --check packages/dsh-remote-web/lib/client.js && bash -n deploy/install-open.sh",
     "release:tarballs": "bash scripts/release-tarballs.sh"
   },
   "dependencies": {

package/packages/dsh-remote-web/lib/client.js

@@ -1010,7 +1010,15 @@ window.__ModuleLoader__.load({
             if (!b.running) {
               clearInterval(iv);
               setUpdating(false);
-              setUpdated(true);
+              // 关键:进程结束 ≠ 更新成功。以前这里无条件显示"已更新完成"，
+              // 于是 spawn 失败（例如 npx 不可用）时界面只报成功、真实原因躺在日志里 ——
+              // 用户看到的就是"点了一键修复没反应"。现在按失败信息与版本是否变化如实反馈。
+              if (b.failure && b.failure.detail) {
+                setUpdated(false);
+                setSelfMsg({ kind: "err", text: "更新失败：" + b.failure.detail + "（可点「复制诊断信息」，或查看下方日志）" });
+              } else {
+                setUpdated(true);
+              }
               loadVer();
               doCheck();
             }

package/packages/dsh-remote-web/lib/index.js

@@ -499,10 +499,56 @@ function appendLogLine(relayDir, name, line) {
  * 已有环境(包括手动 npx 装过)直接跳过。返回 true=已就绪。
  * 注意：默认优先官方源——镜像(npmmirror)可能滞后于刚发布的版本，装到旧版会把
  * 已被 0.4.5 移除的“用户 include”重新写回 profile（历史上造成 dsh web 重复 ID 崩溃）。 */
+/**
+ * 补装失败退避（2026-09-15 生产事故）。
+ *
+ * 背景：Windows 用户补装 `npx @mrrisega/dsh-remote` 持续失败时，自愈调度每轮都重试，
+ * 生产遥测里看到单机 12 秒一次、累计 606 次的失败风暴（1659 次 install_failed 全在 Windows）。
+ * 这既刷屏日志、也让真实失败原因淹没在噪声里。
+ *
+ * 策略：连续失败后按 30s → 2m → 10m 退避（封顶 10 分钟）；用户点「一键修复 / 一键更新」时
+ * 显式放行（resetProvisionRetry），保证人工操作永远能立即重试。
+ */
+const PROVISION_RETRY_BACKOFF_MS = [30_000, 120_000, 600_000];
+
+function provisionRetryGate(relayDir) {
+  const key = String(relayDir);
+  let st = provisionRetry.get(key);
+  if (!st) { st = { fails: 0, nextAt: 0 }; provisionRetry.set(key, st); }
+  if (Date.now() < st.nextAt) {
+    return { ok: false, waitMs: st.nextAt - Date.now(), fails: st.fails };
+  }
+  return { ok: true, st };
+}
+
+function noteProvisionFailure(relayDir) {
+  const key = String(relayDir);
+  const st = provisionRetry.get(key) || { fails: 0, nextAt: 0 };
+  st.fails += 1;
+  const wait = PROVISION_RETRY_BACKOFF_MS[Math.min(st.fails, PROVISION_RETRY_BACKOFF_MS.length) - 1];
+  st.nextAt = Date.now() + wait;
+  provisionRetry.set(key, st);
+  return { fails: st.fails, waitMs: wait };
+}
+
+function noteProvisionSuccess(relayDir) {
+  provisionRetry.delete(String(relayDir));
+}
+
+/** 用户显式要求重试（一键修复/一键更新）→ 清掉退避，让这次一定真的执行。 */
+function resetProvisionRetry(relayDir) {
+  provisionRetry.delete(String(relayDir));
+}
+
 function ensureRuntime(relayDir) {
   if (UNINSTALLED_DIRS.has(relayDir)) return false; // 已彻底卸载：不再自动安装运行环境
   if (runtimeReady(relayDir)) return true;
   if (skipsSystemOps()) return false; // 测试隔离：绝不在用例里 spawn 真实 npx 安装
+  const gate = provisionRetryGate(relayDir);
+  if (!gate.ok) {
+    // 退避中：不重复 spawn（避免失败风暴）。面板会据 provisionRetryInfo() 显示"上次失败、X 后可重试"。
+    return false;
+  }
   const marker = join(relayDir, PROVISION_MARKER);
   if (existsSync(marker)) return false; // 正在安装中
   try {
@@ -531,13 +577,23 @@ function ensureRuntime(relayDir) {
     child.on("exit", (code) => {
       clear();
       appendLogLine(relayDir, AUTO_INSTALL_LOG, `[auto-install] npx 退出 code=${code ?? "?"}`);
-      if (code === 0 && runtimeReady(relayDir)) telemetryRuntimeReady(relayDir); // 退出码 0 ≠ 装好了
-      else if (code !== 0) telemetryRecord(relayDir, "install_failed", { fail_code: telemetryFailCodeFromText(readTail(log)) });
+      if (code === 0 && runtimeReady(relayDir)) {
+        noteProvisionSuccess(relayDir);
+        telemetryRuntimeReady(relayDir); // 退出码 0 ≠ 装好了
+      } else {
+        // 退出码非 0，或退出码 0 但安装脚本没落盘（装到一半/装错包）→ 都算失败并进入退避
+        const code2 = code === 0 ? "install_script_missing" : telemetryFailCodeFromText(readTail(log));
+        const back = noteProvisionFailure(relayDir);
+        appendLogLine(relayDir, AUTO_INSTALL_LOG,
+          `[auto-install] 第 ${back.fails} 次失败（归因 ${code2}），${Math.round(back.waitMs / 1000)}s 后才会重试`);
+        telemetryRecord(relayDir, "install_failed", { fail_code: code2 });
+      }
     });
     child.on("error", (e) => {
       clear();
       appendLogLine(relayDir, AUTO_INSTALL_LOG, `[auto-install] 启动失败: ${e.message}`);
       console.warn(`[dsh-remote-web] 自动安装子进程启动失败: ${e.message}`);
+      noteProvisionFailure(relayDir);
       telemetryRecord(relayDir, "install_failed", { fail_code: telemetryFailCodeFromError(e) });
     });
     child.unref();
@@ -546,6 +602,7 @@ function ensureRuntime(relayDir) {
   } catch (e) {
     console.warn(`[dsh-remote-web] 自动安装启动失败: ${e.message}`);
     try { rmSync(marker, { force: true }); } catch { /* ignore */ }
+    noteProvisionFailure(relayDir);
     telemetryRecord(relayDir, "install_failed", { fail_code: telemetryFailCodeFromError(e) });
     return false;
   }
@@ -713,6 +770,8 @@ function stopBridge() {
  * 直到 dsh web 重启（profile 引用已移除，插件整体不再加载）或重新激活（apply 时清除）。
  */
 const UNINSTALLED_DIRS = new Set();
+/** 补装失败退避状态（relayDir → {fails, nextAt}）；见 provisionRetryGate。 */
+const provisionRetry = new Map();
 
 /** 标记某 relayDir 已完成彻底卸载（其后续自愈/代持调度全部停摆）。 */
 function markUninstalled(relayDir) {
@@ -1753,7 +1812,7 @@ const PLUGIN_ID = "dsh-remote-web";
 const PLUGIN_LEGACY_IDS = ["dsh-remote-ui"];
 const PLUGIN_ALL_IDS = [PLUGIN_ID, ...PLUGIN_LEGACY_IDS];
 /** 插件自身发布版本（与 dsh-remote 根包同步递增）。 */
-const PLUGIN_VERSION = "0.6.5";
+const PLUGIN_VERSION = "0.6.6-beta.2";
 const UPDATE_LOG = ".dsh-update.log";
 const UPDATE_MARKER = ".dsh-update-running";
 
@@ -1816,6 +1875,29 @@ function compareVersions(a, b) {
   return 0;
 }
 
+/**
+ * 最近一次在线更新的失败信息（内存态，TTL 10 分钟）。
+ *
+ * 为什么需要它：此前"一键更新/一键修复"点了没反应 —— spawn 是异步的，npx 解析失败时
+ * 同步分支仍然返回 `{ok:true}`，而错误只写进 `.dsh-update.log`；前端看到 ok:true 就显示
+ * 「更新已开始」，2 秒后轮询到 marker 被清（running:false）便显示「已更新完成」——
+ * 版本没变、运行环境仍缺失，界面上没有任何失败提示（用户实测：点了没反应）。
+ * 现在失败原因进内存态并可查询，前端在"没成功"时能如实报错。
+ */
+const updateFailures = new Map(); // relayDir → { at, detail, failCode }
+const UPDATE_FAILURE_TTL_MS = 10 * 60 * 1000;
+
+function noteUpdateFailure(relayDir, detail, failCode) {
+  updateFailures.set(String(relayDir), { at: Date.now(), detail: String(detail || "未知原因"), failCode: failCode || "unknown" });
+}
+
+function recentUpdateFailure(relayDir) {
+  const rec = updateFailures.get(String(relayDir));
+  if (!rec) return null;
+  if (Date.now() - rec.at > UPDATE_FAILURE_TTL_MS) { updateFailures.delete(String(relayDir)); return null; }
+  return rec;
+}
+
 /** 以 detached 子进程执行 `npx --yes <UPDATE_SPEC>`（env 可覆盖 npm 源/更新通道）。 */
 function spawnUpdater(relayDir, extraEnv) {
   const log = join(relayDir, UPDATE_LOG);
@@ -1842,7 +1924,18 @@ function runOnlineUpdate(relayDir) {
   try {
     mkdirSync(relayDir, { recursive: true });
     const marker = join(relayDir, UPDATE_MARKER);
-    if (existsSync(marker)) return { ok: false, detail: "已有更新在进行中，请稍候" };
+    if (existsSync(marker)) {
+      // 残留 marker（进程被强杀/上次异常退出）会让点击**永久**被拒，前端还会把它当成
+      // "正在跟踪进度"而只转圈不报错。超过 10 分钟一律视为陈旧并清理。
+      let stale = false;
+      try { stale = Date.now() - statSync(marker).mtimeMs > 10 * 60 * 1000; } catch { /* ignore */ }
+      if (stale) {
+        try { rmSync(marker, { force: true }); } catch { /* ignore */ }
+        appendLogLine(relayDir, UPDATE_LOG, "[update] 清理超过 10 分钟的陈旧 in-progress 标记");
+      } else {
+        return { ok: false, detail: "已有更新在进行中，请稍候（若长时间无进展，最多 10 分钟后可重试）" };
+      }
+    }
     appendLogLine(relayDir, UPDATE_LOG, `[update] 开始在线更新 ${UPDATE_SPEC} (${new Date().toISOString()})`);
     telemetryRecord(relayDir, "update_started"); // 匿名遥测：在线更新开始
 
@@ -1866,17 +1959,34 @@ function runOnlineUpdate(relayDir) {
         // 插件走 patch 热加载、bridge 是独立进程，重启 harness 已无必要（用户实测反馈）。
         // 成功不发事件（update_started 已发过，失败才发 update_failed；白名单里没有 update_done，
         // 硬发只会被服务端静默丢弃）。
-        if (code !== 0) telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromText(readTail(join(relayDir, UPDATE_LOG))) });
+        if (code !== 0) {
+          const tail = readTail(join(relayDir, UPDATE_LOG));
+          const fc = telemetryFailCodeFromText(tail);
+          // 只把最后的可读片段给用户看（不含完整路径/用户名）；分类码仍按白名单上报
+          const lastLine = String(tail || "").split("\n").map((l) => l.trim()).filter(Boolean).slice(-1)[0] || "";
+          noteUpdateFailure(relayDir, lastLine || `安装进程退出码 ${code}`, fc);
+          telemetryRecord(relayDir, "update_failed", { fail_code: fc });
+        } else {
+          updateFailures.delete(String(relayDir)); // 成功即清掉旧失败
+        }
       });
       child.on("error", (e) => {
         appendLogLine(relayDir, UPDATE_LOG, `[update] 子进程启动失败: ${e.message}`);
         clear();
-        telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromError(e) });
+        const fc = telemetryFailCodeFromError(e);
+        noteUpdateFailure(relayDir, e.message, fc); // ← 面板可查询，不再只躺在日志里
+        telemetryRecord(relayDir, "update_failed", { fail_code: fc });
       });
       child.unref();
       return child;
     };
     const child = run();
+    // spawn 是异步的：解析失败时 pid 可能是 undefined。此时**不能**同步返回 ok:true，
+    // 否则前端会显示"更新已开始"、随后看到 running:false 便报"已完成"（实测的静默失败）。
+    if (!child || !child.pid) {
+      const rec = recentUpdateFailure(relayDir);
+      return { ok: false, detail: (rec && rec.detail) || "无法启动更新进程（npx 不可用？）", failCode: rec ? rec.failCode : "unknown" };
+    }
     return { ok: true, pid: child.pid, log: join(relayDir, UPDATE_LOG) };
   } catch (e) {
     try { rmSync(join(relayDir, UPDATE_MARKER), { force: true }); } catch { /* ignore */ }
@@ -2517,14 +2627,29 @@ function telemetryEventOf(name, extra = {}) {
 /** 从既有日志/错误文本归类 fail_code（白名单内）；原始文本绝不外发（可能含路径/主机名）。 */
 function telemetryFailCodeFromText(text) {
   const t = String(text || "");
-  if (/EACCES|EPERM|permission denied|权限不足/i.test(t)) return "npm_eacces";
+  // 顺序有意义：从"最具体"到"最泛"。
+  // 2026-09-15：Windows 装机失败此前**全部**落到 unknown（1659 次 install_failed 无法定位），
+  // 所以把真实会遇到的形态拆开。仍然只上报枚举，原始文本不出机器（见下方注释与隐私测试）。
+  // ① Windows 上 `npx.cmd` 根本调不起来（不是内部命令 / 找不到 cmd / EINVAL 等）
+  if (/npx(\.cmd)?\s+(is not recognized|不是内部或外部命令)|不是内部或外部命令|无法将.*识别为/i.test(t)) return "npx_cmd_unavailable";
+  if (/EINVAL|spawn .*\.cmd/i.test(t)) return "npx_cmd_unavailable";
+  // ② 拿到的包不对：404 / 版本被 deprecate / 装完仍没有安装脚本
+  if (/404|Not Found - GET|ETARGET|No matching version/i.test(t)) return "install_script_missing";
+  // ③ 纯网络层问题（含 npm ERR! network / 超时 / TLS）
+  if (/ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ETIMEOUT|ECONNREFUSED|ENETUNREACH|ECONNRESET|ERR_SOCKET_TIMEOUT|npm ERR! network|registry\.npmjs\.org.*(timeout|timed out)|超时/i.test(t)) {
+    return "registry_timeout";
+  }
+  if (/network|registry|EAI|socket hang up/i.test(t)) return "npm_unreachable";
+  // ④ 权限（含只读目录 / 沙箱拦截）
+  if (/EACCES|EPERM|permission denied|权限不足|read-only file system/i.test(t)) return "npm_eacces";
   if (/platform|不支持的平台/i.test(t)) return "platform_unsupported";
-  if (/too old|版本过低|engine/i.test(t)) return "node_too_old";
-  if (/ENOENT|not found|No such file/i.test(t)) return "node_missing";
-  if (/ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ETIMEOUT|ECONNREFUSED|ENETUNREACH|ECONNRESET|network|registry|超时/i.test(t)) {
-    return "npm_unreachable";
-  }
-  return "unknown";
+  if (/too old|版本过低|engine|Unsupported engine/i.test(t)) return "node_too_old";
+  if (/ENOENT|not found|No such file|Cannot find module/i.test(t)) return "node_missing";
+  // ⑤ 输出是乱码（Windows GBK 代码页下 npm 输出可能整段不可读）→ 谁都没法归因，单独标出来
+  if (/[\uFFFD]/.test(t)) return "npx_output_encoding";
+  // ⑥ 兜底：进程确实退出了非零码，但日志里没有可识别的特征 —— 标成 npx_exit_nonzero，
+  // 与"启动都没起来"（npx_cmd_unavailable / node_missing）区分开，便于下轮定位。
+  return "npx_exit_nonzero";
 }
 /** 子进程启动失败（spawn error）→ fail_code。 */
 function telemetryFailCodeFromError(e) {
@@ -2777,6 +2902,9 @@ export const __telemetryInternals = {
   installId: (relayDir) => telemetryInstallId(relayDir),
   queueOf: (relayDir) => telemetryLoadQueue(relayDir, telemetryBook(relayDir)).slice(),
   eventOf: (name, extra) => telemetryEventOf(name, extra),
+  // 归因函数也暴露出来：Windows 装机失败此前全落到 unknown，需要能被用例逐条锁住
+  failCodeFromText: (text) => telemetryFailCodeFromText(text),
+  failCodeFromError: (e) => telemetryFailCodeFromError(e),
   eventNames: [...TELEMETRY_EVENT_NAMES],
   failCodes: [...TELEMETRY_FAIL_CODES],
   queueMax: TELEMETRY_QUEUE_MAX,
@@ -2913,7 +3041,15 @@ function registerRoutes(ctx, relayDir) {
       method: "GET",
       path: "/dsh-remote/self/update-log",
       handler: async (_req, res) => {
-        sendJson(res, 200, { ok: true, running: existsSync(join(relayDir, UPDATE_MARKER)), log: tailOf(join(relayDir, UPDATE_LOG)) });
+        const failure = recentUpdateFailure(relayDir);
+        sendJson(res, 200, {
+          ok: true,
+          running: existsSync(join(relayDir, UPDATE_MARKER)),
+          log: tailOf(join(relayDir, UPDATE_LOG)),
+          // 供前端在"没成功"时如实报错（此前失败只写日志，界面显示"已完成"）
+          failure: failure ? { detail: failure.detail, failCode: failure.failCode, at: failure.at } : null,
+          version: PLUGIN_VERSION
+        });
       },
     },
     {

package/packages/dsh-remote-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.6.5",
+  "version": "0.6.6-beta.2",
   "description": "公网远程控制 DeepSeek Harness（dsh web）：安装即得专属加密地址，人在外面也能用手机访问电脑上的 dsh——无需同一局域网/WiFi、无需公网 IP 与内网穿透，全程加密；手机端 100% 还原电脑体验（对话/工具/审批/设置）。技术用户可选自建服务，流量走自己的服务器。Remote control DeepSeek Harness (dsh web) from anywhere over the public internet — install, get an encrypted URL, use it from your phone on any network (dual-half cordis plugin: Settings panel + same-origin /dsh-remote routes). (2026-09 由 dsh-remote-ui 更名 / renamed from dsh-remote-ui; dsh-remote 的 dsh web 插件半，不是纯 UI/皮肤插件)",
   "type": "module",
   "main": "lib/index.js",
@@ -24,10 +24,7 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ]
+      "platform": "web"
     }
   },
   "repository": {

package/packages/dsh-remote-web/test/plugin-manifest.test.mjs

@@ -0,0 +1,131 @@
+/**
+ * 插件清单与「一键更新静默失败」契约测试（node:test，零框架）。
+ *
+ * 事故背景（2026-09-15 生产反馈）：
+ *  A. 用户扫码后报「fail to load plugin / DeepSeek client collection」。
+ *     排查发现 package.json 的 dsh.client.inject 声明了 `@deepseek-ai/dsh-client-runtime`，
+ *     而该包在 harness 安装树里**根本不存在**（harness 只有 dsh-client-ui-* 等真包）。
+ *     inject 取不到图行时该插件永不 arrive（面板不出现），且清单与真实依赖不符 ——
+ *     一旦 harness 侧改为严格校验，就会直接变成启动期加载失败。
+ *  B. 用户报「桌面运行环境缺失 + 一键修复点了没反应」。
+ *     根因链：spawn 是异步的，npx 解析失败时同步分支仍返回 ok:true；错误只写进日志；
+ *     前端看到 ok:true 显示"更新已开始"，2 秒后轮询到 marker 被清便显示"已完成"——
+ *     版本没变、环境仍缺，界面零反馈。另：残留 marker 会让点击被永久拒绝。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = join(HERE, "..", "..", "..");
+const INDEX = join(HERE, "..", "lib", "index.js");
+const CLIENT = join(HERE, "..", "lib", "client.js");
+
+const indexSrc = readFileSync(INDEX, "utf8");
+const clientSrc = readFileSync(CLIENT, "utf8");
+
+test("清单：dsh.client 不得声明不存在的宿主包（幻影 inject 会让插件永不装载）", () => {
+  // 注：旧名别名包 dsh-remote-ui 已于 2026-09-15 退役并从仓库删除（npm 上已 deprecate），
+  // 因此这里只校验当前插件包 dsh-remote-web。
+  const pkg = "packages/dsh-remote-web/package.json";
+  const manifest = JSON.parse(readFileSync(join(REPO, pkg), "utf8"));
+  const client = manifest.dsh && manifest.dsh.client;
+  assert.ok(client, `${pkg} 应有 dsh.client`);
+  assert.equal(client.platform, "web");
+  const inject = client.inject || [];
+  assert.deepEqual(inject, [], `${pkg} 的 inject 必须为空：我们的浏览器半只 require("react")，不需要任何宿主包`);
+  for (const name of inject) {
+    assert.ok(!/dsh-client-runtime|dsh-client-collection/.test(name), `inject 里不得出现不存在的包名：${name}`);
+  }
+});
+
+test("旧名别名包确已退役：目录/同步脚本/发布步骤都不应再存在", () => {
+  assert.ok(!existsSync(join(REPO, "packages", "dsh-remote-ui")), "别名目录应已删除");
+  assert.ok(!existsSync(join(REPO, "scripts", "sync-legacy-alias.mjs")), "别名同步脚本应已删除");
+  const root = JSON.parse(readFileSync(join(REPO, "package.json"), "utf8"));
+  for (const k of ["sync:alias", "check:alias"]) {
+    assert.ok(!(k in root.scripts), `package.json 不应再有 ${k}`);
+  }
+  assert.ok(!/check:alias/.test(root.scripts.check || ""), "check 不应再引用别名校验");
+  // 但**旧名清理/迁移逻辑必须保留**：老用户升级依赖它
+  const setup = readFileSync(join(REPO, "dsh-setup.mjs"), "utf8");
+  assert.match(setup, /PLUGIN_LEGACY_IDS/, "安装器必须保留旧名清理（老用户升级路径）");
+  assert.match(setup, /dsh-remote-ui/, "旧名清理里应仍认得 dsh-remote-ui");
+});
+
+test("清单：浏览器半只依赖 shell 提供的 react（不 require 宿主客户端包）", () => {
+  const requires = [...clientSrc.matchAll(/require\("([^"]+)"\)/g)].map((m) => m[1]);
+  assert.deepEqual([...new Set(requires)], ["react"], `实际 require: ${[...new Set(requires)].join(",")}`);
+  // exports["./client"] 必须存在，否则 harness 报 "declares dsh.client but exports no ./client bundle"
+  const manifest = JSON.parse(readFileSync(join(REPO, "packages/dsh-remote-web/package.json"), "utf8"));
+  assert.ok(manifest.exports && manifest.exports["./client"], "必须声明 exports['./client']");
+  assert.ok(existsSync(join(HERE, "..", "lib", "client.js")), "client bundle 文件必须存在");
+});
+
+test("一键更新：spawn 失败不得同步返回 ok:true（否则界面显示已开始、却什么也没发生）", () => {
+  assert.match(indexSrc, /if \(!child \|\| !child\.pid\)/, "pid 缺失时必须返回失败");
+  assert.match(indexSrc, /noteUpdateFailure\(relayDir/, "失败原因要进可查询状态，不能只写日志");
+  assert.match(indexSrc, /recentUpdateFailure\(relayDir\)/, "应能查出最近的失败");
+});
+
+test("一键更新：残留 marker 必须有过期判定（否则点击被永久拒绝、界面只转圈）", () => {
+  assert.match(indexSrc, /10 \* 60 \* 1000/, "应有 10 分钟陈旧判定");
+  assert.match(indexSrc, /清理超过 10 分钟的陈旧 in-progress 标记/, "应真的清理陈旧 marker");
+});
+
+test("一键更新：前端在进程结束但没成功时必须报错，而不是显示已完成", () => {
+  assert.match(clientSrc, /if \(b\.failure && b\.failure\.detail\)/, "前端应消费 failure");
+  assert.match(clientSrc, /"更新失败：" \+ b\.failure\.detail/, "应把失败原因显示出来");
+  // update-log 端点要下发 failure
+  assert.match(indexSrc, /failure: failure \? \{ detail: failure\.detail/, "update-log 应下发 failure");
+});
+
+test("补装失败退避：Windows 的失败风暴不再每轮重试", () => {
+  assert.match(indexSrc, /PROVISION_RETRY_BACKOFF_MS\s*=\s*\[30_000, 120_000, 600_000\]/, "应有 30s→2m→10m 退避");
+  assert.match(indexSrc, /function provisionRetryGate/, "应有退避闸门");
+  assert.match(indexSrc, /noteProvisionFailure\(relayDir\)/, "失败要记退避");
+  assert.match(indexSrc, /noteProvisionSuccess\(relayDir\)/, "成功要清退避");
+});
+
+test("失败归因：Windows 真实错误不再全部落到 unknown（1659 次无法定位的教训）", () => {
+  const codes = ["npx_cmd_unavailable", "registry_timeout", "install_script_missing", "npx_exit_nonzero", "npx_output_encoding"];
+  for (const c of codes) {
+    assert.ok(indexSrc.includes(`"${c}"`), `客户端归因应包含 ${c}`);
+  }
+  // 与服务端白名单保持一致（服务端不认的码会被静默丢弃 → 又变成 unknown）
+  const server = join(REPO, "..", "dsh-relay-enterprise", "relay-enterprise", "src", "api.js");
+  if (existsSync(server)) {
+    const apiSrc = readFileSync(server, "utf8");
+    for (const c of codes) {
+      assert.ok(apiSrc.includes(`"${c}"`), `服务端 TELEMETRY_FAIL_CODES 必须接受 ${c}（否则上报被丢弃）`);
+    }
+  }
+});
+
+test("失败归因：逐条映射真实日志（不联网、不起进程）", () => {
+  const mod = JSON.parse(execFileSync(process.execPath, ["-e", `
+    import("${INDEX}").then((m) => {
+      const f = m.__telemetryInternals.failCodeFromText;
+      console.log(JSON.stringify([
+        ["'npx.cmd' 不是内部或外部命令", f("'npx.cmd' 不是内部或外部命令，也不是可运行的程序")],
+        ["spawn EINVAL", f("spawn npx.cmd EINVAL")],
+        ["404", f("npm ERR! 404 Not Found - GET https://registry.npmjs.org/@mrrisega%2fdsh-remote")],
+        ["ETIMEDOUT", f("npm error code ETIMEDOUT")],
+        ["EACCES", f("npm ERR! EACCES: permission denied")],
+        ["engine", f("Unsupported engine: wanted node >=22.13.0")],
+        ["other", f("something unfamiliar")]
+      ]));
+    });
+  `], { encoding: "utf8" }).trim());
+  const map = new Map(mod);
+  assert.equal(map.get("'npx.cmd' 不是内部或外部命令"), "npx_cmd_unavailable");
+  assert.equal(map.get("spawn EINVAL"), "npx_cmd_unavailable");
+  assert.equal(map.get("404"), "install_script_missing");
+  assert.equal(map.get("ETIMEDOUT"), "registry_timeout");
+  assert.equal(map.get("EACCES"), "npm_eacces");
+  assert.equal(map.get("engine"), "node_too_old");
+  assert.equal(map.get("other"), "npx_exit_nonzero", "兜底不得再是 unknown");
+});