@mrrisega/dsh-remote 0.6.17 → 0.6.18-beta.2

package/clients/dsh-remote/test/e2ee-shim.test.mjs

@@ -39,7 +39,7 @@ import {
   maybeInjectE2eeShim,
   e2eeShimEnabled
 } from "../e2ee-shim.mjs";
-import { loadShimCore, extractShimCore } from "./lib-e2ee-shim.mjs";
+import { loadShimCore, extractShimCore, readShimScript } from "./lib-e2ee-shim.mjs";
 import { loadNativeHandoverCore, extractNativeHandoverCore, loadNativeWcCore } from "./lib-native-e2ee.mjs";
 
 const OFFICIAL_HTML = `<!doctype html>
@@ -562,3 +562,45 @@ test("fetch 包装:真实字节往返(shim 密封 → 桥端打开 → 封回
     assert.equal(res.headers.get("x-round"), String(i));
   }
 });
+
+// ─────────────── 2026-09-27：P0-1 收尾（设备作用域必须在"没有会话"时也生效） ───────────────
+
+test("★ WS 设备作用域：不改写就走放行分支时，也必须用**改写后**的 URL", () => {
+  // 事故现场：镜像页**没有会话**（未解锁）→ 不加密 → 走放行分支。
+  // 官方客户端把 mux 拼成根路径 `/api/remote.mux`，中继只认会过期的 dsh_device cookie → 404
+  // （rejectUpgrade 写状态行后立刻 destroy → nginx 只看到 009）→ e2ee-hello 送不到 →
+  // 会话永远建不起来 → 每个受保护请求 unknown_session 502。死循环。
+  const ORIGIN = "http://relay.local";
+  const patched = shim.seMakeWsCtor(FakeNative, { sess: null, origin: ORIGIN, deviceId: "dev-8e5fb209cdc8" });
+  const ws = patched(ORIGIN + "/api/remote.mux?e2ee=abc&w=def");
+  assert.ok(ws instanceof FakeNative, "无会话 → 不套加密代理（放行）");
+  assert.equal(ws.url, ORIGIN + "/remote/dev-8e5fb209cdc8/api/remote.mux?e2ee=abc&w=def",
+    "🔴 放行分支必须带**改写后**的设备作用域 URL —— 否则改写算了又被丢掉，等于没做");
+
+  // 反向：本来就在设备作用域里 → 一个字节都不改
+  const ws2 = patched(ORIGIN + "/remote/dev-x/api/remote.mux?w=1");
+  assert.equal(ws2.url, ORIGIN + "/remote/dev-x/api/remote.mux?w=1", "已在设备作用域 → 原样放行");
+
+  // 反向：非受保护路径（如静态资源）不做设备改写，保持原样
+  const ws3 = patched(ORIGIN + "/assets/index.js");
+  assert.equal(ws3.url, ORIGIN + "/assets/index.js", "非受保护前缀不改写");
+
+  // 反向：拿不到 deviceId（例如旧入口 `/`）→ 不改写，且不得崩
+  const patchedNoDev = shim.seMakeWsCtor(FakeNative, { sess: null, origin: ORIGIN, deviceId: "" });
+  const ws4 = patchedNoDev(ORIGIN + "/api/remote.mux");
+  assert.equal(ws4.url, ORIGIN + "/api/remote.mux", "没有 deviceId 时保持原样（宁可 404 也不要乱拼）");
+});
+
+test("★ 补丁必须在 boot 阶段**无条件**安装（没会话也要装，否则建不了会话）", () => {
+  const src = readShimScript();
+  // 三条"放弃会话"的早退分支，都必须在 return 之前先装补丁
+  for (const marker of ["未加密:未解锁(明文)", "未加密:交接单无效", "未加密:环境不支持"]) {
+    const i = src.indexOf(marker);
+    assert.ok(i > 0, `找不到分支 ${marker}`);
+    const before = src.slice(Math.max(0, i - 320), i);
+    assert.match(before, /_install\(null\)/, `🔴 「${marker}」分支必须在 return 之前先 _install(null)，否则 WS 改写根本不生效`);
+  }
+  // 会话后到时只填 ctx，不重复包装（否则 fetch/WS 会被套多层）
+  assert.match(src, /if \(sess\) \{[\s\S]{0,200}?_ctx\.sess = sess; return;/,
+    "同一页面重复 _install(sess) 只能更新会话，不得重复包装 window.fetch/WebSocket");
+});

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

@@ -125,10 +125,11 @@ class El {
     this.children = [];
     for (const m of String(html).matchAll(/<(\w+)([^>]*)>/g)) {
       const el = new El(m[1]);
-      const cls = /class="([^"]*)"/.exec(m[2] || "");
-      if (cls) el.className = cls[1];
-      const type = /type="([^"]*)"/.exec(m[2] || "");
-      if (type) el.attrs.type = type[1];
+      /* 任意 `attr="v"` 都要收进 attrs：0.6.18 新增的 FAB 延迟角标（data-role="rtt"）、
+         菜单里的网络延迟行（data-role="net"）与「打开右侧栏」按钮（data-role="right-pane"）
+         都是靠属性找的 —— 只认 class 的旧解析器会让它们恒为 null，护栏就变成假绿灯。 */
+      for (const a of (m[2] || "").matchAll(/([\w-]+)="([^"]*)"/g)) el.attrs[a[1]] = a[2];
+      if (el.attrs.class) el.className = el.attrs.class;
       this.appendChild(el);
     }
   }
@@ -897,3 +898,143 @@ test("★ 加载疑似失败时的提示：只在**已有的悬浮菜单**里多
   assert.match(script, /dsh-remote 手机端加载疑似卡住/, "必须给一句可直接发给客服的话");
   assert.match(script, /maLoadCopyLine/, "要能复制（否则用户只能截图）");
 });
+
+// ══════════════════════════════════════════════════════════════════════════════
+// Bug 4（0.6.18，用户实测）：「点官方抽屉里的收起按钮 → 左半边一片白色占位，只有刷新能出去」
+//
+// 根因：userWantsOpen 一旦为 true 就**永不复位** → html.dsh-ma-sidebar-open 常亮 →
+// CSS 把 sidebarCol 钉成 fixed + translateX(0) + z-index:310 的**空壳**（官方已把列宽压成 0、
+// 内容收起，只剩一个没有内容的白色固定柱盖住左半屏）；它几何上"在视口里"（width≈340 < 0.98vw），
+// 遮罩不变量也跟着误判 → 整屏被困；而汉堡按钮又**无条件**点官方 toggle → 两态互相打架。
+// 四层修复：① sync() 里放弃过期意图；② 汉堡按钮仅在"官方态 ≠ 期望态"时才点 toggle；
+//          ③ 官方折叠态镜像到 <html> + CSS 硬兜底；④ 遮罩不变量把"空壳"排除在外。
+// ══════════════════════════════════════════════════════════════════════════════
+
+/** 模拟"用户点了官方抽屉内的收起按钮"：官方写回折叠属性（真机就是这个动作）。 */
+function officialCollapse(env) {
+  env.frame.setAttribute("data-sidebar-collapsed", "true");
+  const obs = MutationObserverStub.instances.find((o) => o.targets.some((t) => t.t === env.frame));
+  if (obs) obs.fire("data-sidebar-collapsed");
+}
+
+test("白柱：官方抽屉被收起后，适配层必须放弃自己的展开意图（不留空壳、不困住用户）", () => {
+  const { js, css } = injected();
+  // 现场：官方初始是**展开**的（属性缺席）+ 抽屉已在视口里 → 用户点过正文让详情列滑入过；
+  // 随后官方把侧栏收起来（用户点了抽屉内的收起按钮）
+  // ⚠️ 2026-09-27 修（本用例原先的前提不成立，是**假红**）：
+  //    原来先用 `collapsedAttr: null` 造"官方不写属性"，再中途改成 `="false"` 并 fire 观察者回调，
+  //    然后点汉堡 —— 但 `collapsed()` 对"从没见过这个属性"的返回值是**收起**（`return !sidebarAttrSeen`），
+  //    于是那次 fire 恰好构成一次"官方由收起→展开"的边沿，`lastOfficialCollapsed` 的记录与
+  //    随后的点击时序耦合，前提断言 `dsh-ma-sidebar-open === true` 就不成立了。
+  //    现在直接照**已通过的**兄弟用例（「汉堡按钮不再无条件点官方 toggle」）的写法：官方一开始就说"展开"。
+  const env = run(harness({ collapsedAttr: "false", detailsAttr: "true" }), js);
+  const ham = findHamburger(env);
+  // 官方一开始说"展开" ⇒ 启动时 class 就是开的（`open = expanded()`）。要点出"**用户**的展开意图"，
+  // 需要走一次"关 → 开"：第一次点=关（并让官方 toggle 走一次），第二次点=用户明确要开。
+  ham.dispatchEvent(new Ev("click", {}));                        // 关
+  assert.equal(env.html.classList.contains("dsh-ma-sidebar-open"), false, "第一次点：关掉");
+  ham.dispatchEvent(new Ev("click", {}));                        // 开（建立用户意图）
+  assert.equal(env.html.classList.contains("dsh-ma-sidebar-open"), true, "前提：抽屉是展开的（用户意图已建立）");
+
+  officialCollapse(env);                                        // ← 用户点了**官方抽屉内**的收起按钮
+  assert.equal(env.html.classList.contains("dsh-ma-official-collapsed"), true,
+    "官方折叠态必须镜像到 <html>（CSS 据此做不依赖 JS 判定的硬兜底）");
+  assert.equal(env.html.classList.contains("dsh-ma-sidebar-open"), false,
+    "官方收起后适配层必须放弃展开意图 —— 否则就是那根白色空壳柱（只有刷新能出去）");
+  assert.equal(env.html.classList.contains("dsh-ma-scrim-on"), false, "不得留下任何拦截层");
+  // CSS 硬兜底必须在（哪怕 JS 判定全部失手，也不会留下可见空壳）
+  assert.match(css, /html\.dsh-ma-official-collapsed[^{]*\{\s*transform:\s*translateX\(-103%\)\s*!important/,
+    "必须有 html.dsh-ma-official-collapsed 的 translateX(-103%) 兜底规则（不依赖任何 JS 判定）");
+});
+
+test("白柱：官方已收起时不留下「白色空壳」——空壳不算可交互抽屉，遮罩必须摘掉", () => {
+  const { js } = injected();
+  const env = run(harness({ collapsedAttr: "true", detailsAttr: "true" }), js);
+  // 造出"空壳"：这一列被判成展开、几何也在视口里，但里面一个可交互内容都没有
+  env.html.classList.add("dsh-ma-sidebar-open", "dsh-ma-scrim-on");
+  env.sidebar.children = [];                       // 官方把内容收走了（卸载）
+  env.sidebar.getBoundingClientRect = () => IN_LEFT;
+  env.doc.dispatchEvent(new Ev("resize", {}));
+  env.tickTimers();                                // 800ms 看门狗
+  assert.equal(env.html.classList.contains("dsh-ma-scrim-on"), false,
+    "空壳在视口里不等于「可交互抽屉」→ 遮罩必须被摘掉（用户不能被一张看不见的遮罩困住）");
+});
+
+test("白柱：汉堡按钮不再无条件点官方 toggle（两态不得互相打架）", () => {
+  const { js } = injected();
+  const env = run(harness({ collapsedAttr: "false", detailsAttr: "true" }), js);
+  // 官方明确说"展开"，而我们这边还没表达意图 → 点汉堡 = 要关（官方态 ≠ 期望态 → 该点 toggle）
+  const clicks = toggleClicks(env);
+  const ham = findHamburger(env);
+  ham.dispatchEvent(new Ev("click", {}));
+  assert.equal(clicks(), 1, "期望态与官方态不一致时必须点官方 toggle（走官方 store）");
+  assert.equal(env.html.classList.contains("dsh-ma-sidebar-open"), false, "点击后应关掉抽屉");
+  // 再点一次：官方此刻仍是"展开"（假 DOM 的 toggle 不改属性）→ 期望是展开、官方已是展开
+  // → 不得再点官方 toggle（那会把官方推到**相反**方向，正是"两个状态互相打架"的来源）
+  ham.dispatchEvent(new Ev("click", {}));
+  assert.equal(clicks(), 1, "官方态与期望态一致时**不得**再点官方 toggle（否则交替打架、白柱反复重现）");
+  assert.equal(env.html.classList.contains("dsh-ma-sidebar-open"), true, "第二次点击应把抽屉打开（意图生效）");
+});
+
+test("打开右侧栏：官方右栏里有宿主注册的内容时，FAB 菜单那颗按钮必须能把它滑进来", () => {
+  const { js } = injected();
+  // 现场（用户报的「右侧按钮区看不见」）：better-sidebar 这类插件把 tab 注册进官方右栏，
+  // 但它只翻自己的 store → 官方 cols.rightbar 永远是 0（data-rightbar-collapsed 恒为 true）。
+  const env = harness({ collapsedAttr: "true", variant: "rc2", detailsAttr: null, rightbarAttr: "true" });
+  env.third.appendChild(env.doc.createElement("div"));   // 官方右栏里确实有内容（插件注册的 tab 面板）
+  run(env, js);
+  assert.equal(env.html.classList.contains("dsh-ma-details-open"), false, "前提：默认不显示右栏");
+  const menu = env.body.children.find((c) => c._cls.has("dsh-ma-menu"));
+  assert.ok(menu, "应有悬浮菜单");
+  const btn = menu.querySelector('[data-role="right-pane"]');
+  assert.ok(btn, "菜单里必须有「打开右侧栏」按钮（用户唯一的明路）");
+  btn.dispatchEvent(new Ev("click", {}));
+  assert.equal(env.html.classList.contains("dsh-ma-details-open"), true,
+    "点「打开右侧栏」后，即便官方说收起（第三方插件不会让官方展开），也必须把有内容的右栏滑进来");
+  assert.equal(menu.hidden, true, "点完应关闭菜单（让用户看见滑入的面板）");
+});
+
+test("打开右侧栏：右栏里没有任何内容时不得滑出一个空白面板（2026-09-19 白框事故的回归）", () => {
+  const { js } = injected();
+  const env = run(harness({ collapsedAttr: "true", variant: "rc2", detailsAttr: null, rightbarAttr: "true" }), js);
+  const menu = env.body.children.find((c) => c._cls.has("dsh-ma-menu"));
+  menu.querySelector('[data-role="right-pane"]').dispatchEvent(new Ev("click", {}));
+  assert.equal(env.html.classList.contains("dsh-ma-details-open"), false,
+    "官方右栏里什么都没有 → 宁可什么都不发生，也不弹一个空白白面板（那正是白框事故）");
+});
+
+test("打开右侧栏：绝不允许「载入即滑出白框」——必须由用户动作解锁", () => {
+  const { js } = injected();
+  // 载入时官方右栏就是"有内容"的（面板挂载着）+ 官方属性说不清 → 旧实现在这里弹白框
+  const env = harness({ collapsedAttr: "true", variant: "rc2", detailsAttr: null, rightbarAttr: null });
+  env.third.appendChild(env.doc.createElement("div"));
+  run(env, js);
+  assert.equal(env.html.classList.contains("dsh-ma-details-open"), false,
+    "没有任何用户动作时，绝不允许因为「右栏有内容」就把面板滑出来（白框必须是用户要的才出现）");
+  assert.equal(env.html.classList.contains("dsh-ma-scrim-on"), false, "同理：遮罩不得跟着拦点击");
+});
+
+test("护栏：延迟角标必须是 FAB 内的子元素（不得新增 body 级固定层）", () => {
+  const { js, css } = injected();
+  const env = run(harness({ collapsedAttr: "true", detailsAttr: "true" }), js);
+  const fab = env.body.children.find((c) => c._cls.has("dsh-ma-fab"));
+  assert.ok(fab, "应有悬浮按钮");
+  const rtt = fab.querySelector('[data-role="rtt"]');
+  assert.ok(rtt, "延迟角标必须在 FAB 内部（绝对定位子元素）");
+  // body 下不得多出"角标层"这种节点。
+  // ⚠️ 2026-09-27 修：`body.children` 里**还有官方 frame**（`pI_x6G_frame`，测试脚手架自己放进去的），
+  //    它不是适配层注入的。原来的写法拿"白名单命中数 === body.children.length"去比，
+  //    等于要求官方 frame 也得命中白名单 → 恒差 1（假红）。现在改成**指名道姓找漏网节点**，
+  //    既排除了官方 frame，又比原来更严：多出来的节点会被打印出来。
+  const allowed = ["dsh-ma-fab", "dsh-ma-menu", "dsh-ma-scrim", "dsh-ma-hamburger", "dsh-ma-sessionbar"];
+  const stray = env.body.children
+    .filter((c) => !c._cls.has("pI_x6G_frame"))                                  // 官方 frame 不是我们注入的
+    .filter((c) => !allowed.some((k) => c._cls.has(k)));
+  assert.deepEqual(stray.map((c) => [...c._cls].join(".")), [],
+    "适配层注入到 body 的节点只能是既有那几个（角标必须挂在 FAB 里，不许新建浮层）");
+  // CSS 侧：角标规则不得出现 fixed / 超高 z-index
+  assert.match(css, /button\.dsh-ma-fab \.dsh-ma-fab-rtt\s*\{[^}]*position:\s*absolute/, "角标应绝对定位在 FAB 内");
+  assert.ok(!/\.dsh-ma-fab-rtt\s*\{[^}]*position:\s*fixed/.test(css), "角标不得是 fixed 浮层");
+  assert.ok(!/\.dsh-ma-fab-rtt\s*\{[^}]*z-index/.test(css), "角标不得自带 z-index（它活在 FAB 的层叠上下文里）");
+  void js;
+});

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

@@ -45,7 +45,11 @@ class El {
       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); },
     };
   }
-  // 极简 innerHTML：只认本用例需要的那点结构（class / input[type=range] / 文本）
+  // 极简 innerHTML：只认本用例需要的那点结构（class / 任意 attr="v" / input[type=range]）
+  // ⚠️ 必须把**任意** `attr="v"` 都收进 el.attrs：0.6.18 新增的 FAB 延迟角标
+  //    （`<span class="dsh-ma-fab-rtt" data-role="rtt" hidden>`）就是靠 data-role 找的，
+  //    只认 class 的旧解析器会让 fab.querySelector('[data-role="rtt"]') 恒为 null，
+  //    "角标到底有没有出现"就永远测不出来（假 DOM 失真 → 假绿灯）。
   set innerHTML(html) {
     this._html = String(html);
     this.children = [];
@@ -53,10 +57,8 @@ class El {
       const tag = m[1];
       const attrs = m[2] || "";
       const el = new El(tag);
-      const cls = /class="([^"]*)"/.exec(attrs);
-      if (cls) el.className = cls[1];
-      const type = /type="([^"]*)"/.exec(attrs);
-      if (type) el.attrs.type = type[1];
+      for (const a of attrs.matchAll(/([\w-]+)="([^"]*)"/g)) el.attrs[a[1]] = a[2];
+      if (el.attrs.class) el.className = el.attrs.class;
       this.children.push(el);
     }
   }
@@ -81,6 +83,9 @@ class El {
       if (s2.includes('input[type="range"]')) return el.tagName === "INPUT" && el.attrs.type === "range";
       if (s2.startsWith(".")) return el._cls.has(s2.slice(1));
       if (s2.startsWith("input")) return el.tagName === "INPUT";
+      // `[attr="v"]` / `[attr]`（0.6.18 的 FAB 角标、菜单里的网络延迟行都靠它找）
+      const at = /^\[([\w-]+)(?:="([^"]*)")?\]$/.exec(s2);
+      if (at) return at[2] === undefined ? at[1] in el.attrs : String(el.attrs[at[1]]) === at[2];
       return false;
     };
     return this.children.find(match) || null;
@@ -100,7 +105,7 @@ class El {
  * 折叠时**没有拖拽把手**——这正是 2026-09-19 线上"整屏遮罩"的现场结构。
  */
 function harness({ collapsedAttr = undefined, detailsAttr = undefined, sidebarRect = null, width = 390, withToggle = true,
-  variant = "rc1", rightbarAttr = undefined, overlayRect = null, rightbarRect = null } = {}) {
+  variant = "rc1", rightbarAttr = undefined, overlayRect = null, rightbarRect = null, fetchImpl = null } = {}) {
   const html = new El("html");
   // HOSTISH 门禁会读 documentElement.outerHTML 找官方特征（__ModuleLoader__ / DeepSeek Harness）
   html.outerHTML = '<html><head><script>window.__ModuleLoader__ = { mode: "queue" }</script>'
@@ -168,6 +173,9 @@ function harness({ collapsedAttr = undefined, detailsAttr = undefined, sidebarRe
     removeEventListener() {},
     getComputedStyle: () => ({ getPropertyValue: () => "" }),
     requestAnimationFrame: (fn) => { const id = setImmediate(fn); return id; },
+    /* 0.6.18：适配层会在**已有的** window.fetch 包装里采网络延迟样本（零新增请求）。
+       不传 fetchImpl 时保持"页面没有 fetch"的旧现场（适配层会跳过包装，零行为）。 */
+    fetch: fetchImpl || undefined,
     // unref：同上 —— 适配层的 4 分钟兜底计时器会让测试进程空等到期（本来 240s，只剩 0.2s）。
     // 用例里的 `_pendingTimers` 仍会被 runAdapter() 主动跑一轮，行为不变。
     setTimeout: (fn, ms) => { const id = setTimeout(fn, ms); try { id.unref?.(); } catch { /* 忽略 */ } timers.set(id, fn); return id; },
@@ -441,3 +449,84 @@ test("悬浮按钮：菜单跟随按钮位置（按钮在上半屏 → 菜单挂
   assert.equal(menu.style.left, "20px", "按钮靠左 → 菜单左对齐到按钮");
   assert.equal(menu.style.right, "auto", "左对齐时不应残留 right");
 });
+
+// ── 0.6.18：悬浮按钮图标化 + 去掉预览行 + 网络延迟（用户需求 1 / 1a） ────────────
+// 需求原话：①「手机端的悬浮按钮，把那个『字』改成我们自己用的那个手机的图标」；
+//          ②「设置面板里那行预览的字去掉」；③「要能看见网络延迟」。
+
+test("悬浮按钮：图标化为手机 SVG（不再是「字」），且延迟角标在 FAB 内部", () => {
+  const env = runAdapter(harness({ width: 390 }));
+  const fab = findFab(env);
+  assert.ok(fab, "悬浮按钮应存在");
+  const html = fab.innerHTML;
+  assert.ok(!/>字</.test(html), "按钮里不得再有原来的「字」");
+  assert.match(html, /<svg[^>]*viewBox="0 0 24 24"/, "应内联一个 24×24 的 SVG 图标（照汉堡按钮的写法）");
+  assert.match(html, /stroke="currentColor"/, "图标颜色必须继承 currentColor（暗色主题/官方变量变化都跟着走）");
+  assert.match(html, /class="dsh-ma-fab-ico"/, "图标应包在 .dsh-ma-fab-ico 里（CSS 负责居中）");
+  // 延迟角标：必须是 FAB 的**子元素**（护栏：适配层不得新增 body 级固定层）
+  const rtt = fab.querySelector('[data-role="rtt"]');
+  assert.ok(rtt, "延迟角标必须是 FAB 内的绝对定位子元素（不是新的浮层）");
+  assert.equal(rtt.hidden, true, "还没有任何网络样本时角标必须隐藏（显示 0ms 是谎言）");
+  // 锁图标仍在（且仍在右上角样式里，角标不许抢它的位置）
+  assert.ok(fab.querySelector('[data-role="lock"]'), "加密锁图标不能被图标化改掉");
+});
+
+test("悬浮菜单：预览行已彻底删除（DOM 里不得再有 .dsh-ma-menu-preview）", () => {
+  const env = runAdapter(harness({ width: 390 }));
+  const menu = findMenu(env);
+  assert.equal(menu.querySelector(".dsh-ma-menu-preview"), null, "「预览：手机远程控制，随手可用。」那一行必须删除");
+  assert.ok(!/预览：手机远程控制/.test(menu.innerHTML), "菜单 HTML 里不得再出现那行预览文案");
+  // 删的是"那一行"，不是功能：字号滑块与档位文案必须还在（这条回归守着误删）
+  assert.ok(menu.querySelector('input[type="range"]'), "字号滑块必须还在");
+  assert.match(menu.innerHTML, /只影响这台设备的远程页面/, "字号说明文案应保留");
+});
+
+test("悬浮菜单：新增「网络延迟」一行与「打开右侧栏」按钮（只读文案 + 显式出口）", () => {
+  const env = runAdapter(harness({ width: 390 }));
+  const menu = findMenu(env);
+  assert.ok(menu.querySelector(".dsh-ma-menu-net"), "菜单里应有网络延迟块");
+  assert.match(menu.innerHTML, /网络延迟/, "应有「网络延迟」小标题");
+  assert.ok(menu.querySelector('[data-role="net"]'), "延迟块要带 data-role=net（供渲染函数更新）");
+  assert.ok(menu.querySelector('[data-role="right-pane"]'), "菜单里应有「打开右侧栏」按钮");
+});
+
+test("网络延迟：只在**已有**的 fetch 包装里采样，成功样本显示成角标（绝不主动测速）", async () => {
+  const calls = [];
+  // 刻意让响应"慢" 5ms：亚毫秒（同帧缓存命中）会被刻意丢弃，见 noteRtt 的注释
+  const env = harness({
+    width: 390,
+    fetchImpl: async (input) => { calls.push(String(input)); await new Promise((r) => setTimeout(r, 5)); return { status: 200, ok: true }; },
+  });
+  runAdapter(env);
+  const fab = findFab(env);
+  const rtt = fab.querySelector('[data-role="rtt"]');
+  assert.equal(rtt.hidden, true, "前提：还没有样本");
+  await env.win.fetch("/api/session/list");
+  await new Promise((r) => setTimeout(r, 10));
+  assert.equal(calls.length, 1, "适配层不得额外发探测请求（只包装、不加请求）");
+  assert.equal(rtt.hidden, false, "有成功样本后角标应出现");
+  assert.match(String(rtt.textContent), /^\d+ms$/, `角标应是「<数字>ms」，实际:${rtt.textContent}`);
+  assert.ok(["ok", "mid", "bad"].includes(rtt.getAttribute("data-rtt")), "角标应带分档（ok/mid/bad）供 CSS 上色");
+  assert.equal(rtt.hidden === false, true);
+  // 菜单里的那一行也要跟着更新（同一个 renderRtt）
+  const menu = findMenu(env);
+  const net = menu.querySelector(".dsh-ma-menu-net");
+  assert.ok(["ok", "mid", "bad"].includes(net.getAttribute("data-rtt")), "菜单行也应按同一分档着色");
+});
+
+test("网络延迟：无样本 / 失败请求绝不显示 0ms（显示「测速中…」是唯一正确的空态）", async () => {
+  const env = harness({
+    width: 390,
+    fetchImpl: async () => { throw new Error("network down"); },
+  });
+  runAdapter(env);
+  const fab = findFab(env);
+  const rtt = fab.querySelector('[data-role="rtt"]');
+  // 失败的请求：连会话过期探测都不该被触发，更不该产生延迟样本
+  await env.win.fetch("/api/session/list").catch(() => {});
+  await new Promise((r) => setTimeout(r, 10));
+  assert.equal(rtt.hidden, true, "只有失败/超时样本时角标必须保持隐藏");
+  assert.notEqual(String(rtt.textContent), "0ms", "绝不能显示 0ms（那是谎言）");
+  const menu = findMenu(env);
+  assert.match(menu.innerHTML, /测速中…/, "空态文案必须是「测速中…」");
+});

package/clients/dsh-remote/wechat-runtime.mjs

@@ -1173,12 +1173,35 @@ export class WeChatRuntime {
     } catch { return false; }
   }
 
-  /** 拉一次会话列表(带标题),并记住 1-based 序号供 /use 使用。 */
+  /**
+   * 可切换会话列表（`/ls` 与 `/use` **共用同一份**）—— 过滤必须收口在这里。
+   *
+   * 为什么（业主反馈「/ls 列出一堆(未命名)会话」）：`listSessions` 返回的会话里有大量**空白会话**
+   * （新建后一句话没说的坑），官方已经在数据里标了 `blank`（`dsh-events.mjs:1654` 解析出来却
+   * 一直没人用）。规则：只留 **有名字 / 正在跑 / 当前选中** 的会话；`blank === true` 一律剔除。
+   *
+   * ⚠️ 过滤**只能**放在这里（或同步过滤 sessionIndex）：`/ls` 渲染 1..N 编号、`/use <n>` 按下标取
+   *    会话、而 `sessionIndex`（/use 的列表来源）就是本函数的返回值 —— 任何一处单独过滤都会让
+   *    两边编号分叉（用户 `/ls` 看到第 2 条是 A，`/use 2` 却切到 B）。
+   * ⚠️ 老版本 DSH 不带 `blank` 字段：`undefined === true` 为假 → 自动退化成"有名字/在跑/当前"，
+   *    不会因为升级或降级把整张列表清空。
+   */
+  #usableSessions(list) {
+    return (Array.isArray(list) ? list : []).filter((s) => {
+      if (!s || typeof s !== "object") return false;
+      if (s.blank === true) return false;                       // 官方明确标记的空白会话
+      if (s.sessionId === this.currentSessionId) return true;    // 当前选中：永远留在列表里
+      if (s.running === true) return true;                       // 正在跑
+      return Boolean(String(s.title || "").trim());              // 有名字
+    });
+  }
+
+  /** 拉一次会话列表(带标题),并记住 1-based 序号供 /use 使用(列表已按 #usableSessions 过滤)。 */
   async #sessions() {
     if (!this.subscriber || typeof this.subscriber.listSessions !== "function") return null;
     const r = await this.subscriber.listSessions();
     if (!r || !r.ok) return null;
-    this.sessionIndex = r.sessions || [];
+    this.sessionIndex = this.#usableSessions(r.sessions || []);
     return this.sessionIndex;
   }
 

package/docs/telemetry.md

@@ -57,7 +57,13 @@
 `bridge_started`（bridge 进程拉起）· `bridge_registered`（设备已在中继注册成功 = 真正可用）·
 `tunnel_disconnected` · `first_remote_ok`（首次远程打通）· `plugin_loaded` · `panel_opened` ·
 `harness_restart`（自动重启触发）· `update_started` · `update_failed`（附 `fail_code`）·
-`wechat_bound` / `wechat_unbound`（微信机器人通道的**绑定态跳变**，语义见下）
+`wechat_bound` / `wechat_unbound`（微信机器人通道的**绑定态跳变**，语义见下）·
+`mirror_load`（手机镜像页**就绪耗时**；附 `ms` 耗时毫秒、`at` 客户端事件时刻、`outcome` = `ok` / `slow`）
+
+> `mirror_load` 是唯一带**数值**的事件：`ms` 由客户端量测（口径见下），服务端把它落在
+> `telemetry_events.value_ms`，`at` 落在 `at_ms`（`created_at` 仍是服务端收包时刻，语义不变）。
+> 量测起点是导航开始（`performance.timeOrigin` 对齐）、终点是页面真正可用；`outcome` 为 `slow`
+> 表示触发了看门狗兜底。**不采集**任何页面内容、URL、设备信息。
 
 ### 微信机器人通道的绑定 / 解绑（`wechat_bound` / `wechat_unbound`）
 

package/dsh-setup.mjs

@@ -1125,6 +1125,61 @@ function loginRateLimitUntil() {
   return 0;
 }
 
+/* ── 守护启动锁：把"一堆守护同时被拉起"的惊群收敛成串行 ─────────────────────────────
+ *
+ * 🔴 2026-09-26 真机事故（dsh web 启动故障的连带伤害）：一次重启窗口里同时出现了
+ *    **6 个 `dsh-setup.mjs run` 守护 + 6 个 bridge**，全部用同一个 deviceId 去 router 注册，
+ *    互相把对方顶掉 —— bridge 日志刷满
+ *      `隧道断开(code=4000, replaced by new connection)` → `2s 后重连` → 再被顶掉，
+ *    手机侧表现为隧道无限抖动、随机不可用。
+ *    成因是 `runBridge()` 的去重是**先读 pid 文件、后写 pid 文件**：N 个实例在同一瞬间启动时，
+ *    每个都读到"还没有别人" → 一起活下来。launchd 的 `com.dshremote.bridge`(KeepAlive) 与
+ *    插件自愈拉起的脱离进程又都会各自拉一个，正好构成惊群。
+ *
+ * 修法：进入去重逻辑**之前**先抢一把原子锁（`wx` = 排他创建）。抢到的人才继续走原来的
+ *       supervisor 判定；抢不到的人只在"被监管者"时才稍等（它必须能接管），否则直接让位。
+ *      锁文件带 `pid:时间戳`，超过 STALE 就视为残留（进程被强杀时留下的），可安全抢占 ——
+ *      **绝不允许一把陈旧的锁把 bridge 永久挡在门外**。
+ */
+const WATCHER_SPAWN_LOCK = ".dsh-watcher-spawn.lock";
+const SPAWN_LOCK_STALE_MS = 30_000;
+const SPAWN_LOCK_WAIT_MS = 15_000;
+
+function tryAcquireSpawnLock() {
+  const f = path.join(CONFIG_DIR, WATCHER_SPAWN_LOCK);
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const fd = fs.openSync(f, "wx");           // 排他创建：要么拿到，要么 EEXIST
+    fs.writeSync(fd, `${process.pid}:${Date.now()}`);
+    fs.closeSync(fd);
+    return true;
+  } catch {
+    // 已存在：可能是残留（强杀留下的），也可能是真有人在启动
+    try {
+      const [pidStr, tsStr] = String(fs.readFileSync(f, "utf8")).split(":");
+      const pid = Number(pidStr);
+      const ts = Number(tsStr);
+      const stale = !Number.isFinite(ts) || Date.now() - ts > SPAWN_LOCK_STALE_MS || !pidAlive(pid);
+      if (stale) {
+        fs.rmSync(f, { force: true });
+        const fd = fs.openSync(f, "wx");
+        fs.writeSync(fd, `${process.pid}:${Date.now()}`);
+        fs.closeSync(fd);
+        return true;
+      }
+    } catch { /* 读不到/抢不到 → 当作没拿到 */ }
+    return false;
+  }
+}
+
+function releaseSpawnLock() {
+  const f = path.join(CONFIG_DIR, WATCHER_SPAWN_LOCK);
+  try {
+    const owner = Number(String(fs.readFileSync(f, "utf8")).split(":")[0]);
+    if (owner === process.pid) fs.rmSync(f, { force: true });  // 只删自己那把
+  } catch { /* 没锁/已被抢 → 忽略 */ }
+}
+
 // ---------- run：前台跑 bridge（带配置 + 自启动 watcher） ----------
 async function runBridge() {
   // 去重（所有平台）：自启动服务、登录任务、插件半的脱离进程兜底都可能拉起 watcher，
@@ -1138,6 +1193,18 @@ async function runBridge() {
   //    只剩插件面板的「启动」能救回来。
   //    被监管者拉起 = 我们才是那个该活下来的实例 → 请游离实例让位，然后接管。
   {
+    // 抢启动锁（见上方长注释）：把同时被拉起的多个实例串行化，杜绝"大家都读到没有别人"。
+    const supervised = String(process.env.XPC_SERVICE_NAME || "");
+    let locked = tryAcquireSpawnLock();
+    if (!locked && supervised) {
+      // 被监管者必须能接管：等一会儿再抢（游离实例写完 pid 文件就会释放）
+      const deadline = Date.now() + SPAWN_LOCK_WAIT_MS;
+      while (!locked && Date.now() < deadline) { sleepSync(150); locked = tryAcquireSpawnLock(); }
+    }
+    if (!locked) {
+      console.log("[dsh-remote] 另一个守护正在启动（启动锁被占用），本进程直接退出，避免重复实例。");
+      return;
+    }
     const other = readPidFile(WATCHER_PID_FILE);
     if (other && other !== process.pid && pidAlive(other)) {
       const supervisor = String(process.env.XPC_SERVICE_NAME || "");
@@ -1157,9 +1224,15 @@ async function runBridge() {
         writePidFile(WATCHER_PID_FILE, process.pid);
       } else {
         console.log(`[dsh-remote] 已有一个 bridge 守护在运行（pid=${other}），本进程直接退出，避免重复实例。`);
+        releaseSpawnLock();
         return;
       }
     }
+    // 🔒 关键顺序：**先把自己的 pid 落盘，再释放启动锁**。
+    //    否则"释放锁 → 下面 1373 行才 writePidFile"之间又是一个空窗，第二个实例会读到
+    //    "没有别人" → 惊群只是被缩小、并没有消除。1373 行那次写入保持原样（它还负责注册退出清理）。
+    writePidFile(WATCHER_PID_FILE, process.pid);
+    releaseSpawnLock();
     // ── 回收「上一任留下的 bridge 子进程」────────────────────────────────────
     //
     // 🔴 真机 bug（2026-09-23 用户实测）：一条微信指令**回两条**。
@@ -1899,10 +1972,50 @@ function normalizePatchBase(patch) {
     .trimEnd();
 }
 
+/**
+ * 插件目录里**必须存在且非空**的文件。缺任何一个都说明这次拷贝是"半个插件"。
+ *
+ * 🔴 为什么必须有这一步（2026-09-26 23:46 真实事故）：当时是"先 rmSync 整个 dest、再逐文件 cpSync"，
+ *    而 dsh 恰好在这个空窗里启动 → `package.json` 已经声明 bundle，但 `cordis.patch.yml` 还没拷到
+ *    → dsh 读 overlay 直接 `ENOENT: no such file or directory` 退出，**整个 GUI 起不来**：
+ *
+ *        Error: dsh: failed to read overlay
+ *        .../node_modules/dsh-remote-web/cordis.patch.yml: ENOENT
+ *
+ *    拷贝完成时间 23:46:05，dsh 报错时间 23:46:03 —— 差 2 秒。
+ *    所以"拷完必须先自检，再切换"不是优化，是**防止宿主起不来**的硬闸门。
+ */
+const PLUGIN_REQUIRED_FILES = ["package.json", "lib/index.js", "lib/client.js", "cordis.patch.yml"];
+
+/** 校验某个插件目录是否"完整可加载"；返回缺失/为空的相对路径数组（空数组 = 通过）。 */
+function missingPluginFiles(dir) {
+  const missing = [];
+  for (const rel of PLUGIN_REQUIRED_FILES) {
+    try {
+      const st = fs.statSync(path.join(dir, rel));
+      if (!st.isFile() || st.size === 0) missing.push(`${rel}(空)`);
+    } catch {
+      missing.push(rel);
+    }
+  }
+  return missing;
+}
+
 /**
  * 把插件整目录拷贝进 profile 的固定子目录并返回该目录。
  * 源(本包 packages/${PLUGIN_ID})可能在 npx 临时缓存里,因此必须拷到 profile 内持久化,
  * include 用相对路径直接指向拷贝出的入口,不写依赖、不跑任何包管理器。
+ *
+ * 🔴 **原子覆盖（2026-09-26 事故后的硬要求）**：
+ *   1. 先整份拷到同级的 `.staging-<pid>`，**全程不碰 dest** —— dsh 任何时刻读到的
+ *      要么是完整的旧版、要么是完整的新版；
+ *   2. 拷完**校验**必需文件（见 `PLUGIN_REQUIRED_FILES`），不通过就丢弃 staging、抛错、
+ *      **保留旧版可用**；
+ *   3. 再 `renameSync` 原子切换（同目录内 rename 是原子操作，空窗只有两次 syscall 之间，
+ *      相比旧实现"整个拷贝过程都处于半空状态"是数量级的改善）；
+ *   4. 切换失败 → 立刻把 backup 改回 dest；成功 → 删 backup。
+ *
+ * 另外清掉上次被强杀留下的 `.staging-*` / `.backup-*`，不留垃圾。
  */
 function copyPluginIntoProfile(profileDir, pluginDir) {
   // 清理历史名残留目录（≤0.4.9 的 dsh-remote-ui-plugin），避免与新版并存
@@ -1910,8 +2023,9 @@ function copyPluginIntoProfile(profileDir, pluginDir) {
     try { fs.rmSync(path.join(profileDir, `${id}-plugin`), { recursive: true, force: true }); } catch { /* ignore */ }
   }
   const dest = path.join(profileDir, PLUGIN_LOCAL_DIR);
-  fs.rmSync(dest, { recursive: true, force: true });
-  fs.cpSync(pluginDir, dest, {
+  const stage = `${dest}.staging-${process.pid}`;
+  const backup = `${dest}.backup-${process.pid}`;
+  const cpOpts = {
     recursive: true,
     // 注意：插件源(npx 缓存 / npm 全局)本身就位于某个 node_modules 之下，
     // 过滤必须基于“相对插件目录”的路径片段，绝不能整条 src 路径包含判断，
@@ -1921,7 +2035,42 @@ function copyPluginIntoProfile(profileDir, pluginDir) {
       const rel = path.relative(pluginDir, src);
       return !String(rel).split(path.sep).some((seg) => seg === "node_modules" || seg === ".git" || seg === ".DS_Store");
     }
-  });
+  };
+
+  // 0) 清掉上次被强杀（或本次同 pid 重入）留下的临时目录
+  for (const d of [stage, backup]) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* ignore */ } }
+
+  // 1) 拷到 staging —— **绝不动 dest**
+  try {
+    fs.cpSync(pluginDir, stage, cpOpts);
+  } catch (e) {
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error(`插件拷贝失败（已保留原目录不动）：${e && e.message ? e.message : e}`);
+  }
+
+  // 2) 自检：必需文件一个都不能少（这一步就是 23:46 那次事故的闸门）
+  const missing = missingPluginFiles(stage);
+  if (missing.length > 0) {
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error(
+      `插件拷贝不完整，缺少必需文件：${missing.join("、")}（已保留原目录不动，避免宿主读 overlay 失败起不来）`
+    );
+  }
+
+  // 3) 原子切换
+  try {
+    if (fs.existsSync(dest)) fs.renameSync(dest, backup);
+    try {
+      fs.renameSync(stage, dest);
+    } catch (e) {
+      if (fs.existsSync(backup)) { try { fs.renameSync(backup, dest); } catch { /* 尽力回滚 */ } }
+      throw e;
+    }
+    try { fs.rmSync(backup, { recursive: true, force: true }); } catch { /* ignore */ }
+  } catch (e) {
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error(`插件切换失败（旧版仍在原位）：${e && e.message ? e.message : e}`);
+  }
   return dest;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrisega/dsh-remote",
-  "version": "0.6.17",
+  "version": "0.6.18-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",