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

package/packages/dsh-remote-web/runtime/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/packages/dsh-remote-web/runtime/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/packages/dsh-remote-web/test/account-switch-device.test.mjs

@@ -18,6 +18,7 @@
  * ⚠️ 隔离：unset 隔离开关的用例必须同时伪造 HOME 与 PATH（否则会碰真实 HOME 下的 launchd）。
  */
 import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
 import http from "node:http";
 import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
@@ -44,7 +45,7 @@ fi
 exit 0
 `;
 
-async function makeEnv({ fakeLaunchd = true } = {}) {
+async function makeEnv({ fakeLaunchd = true, fakeBridgeJobs = false } = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "dsh-acct-dev-"));
   const fakeHome = path.join(root, "home");
   const fakeBin = path.join(root, "bin");
@@ -65,9 +66,24 @@ async function makeEnv({ fakeLaunchd = true } = {}) {
   process.env.DSH_TEST_LAUNCH_LOG = path.join(root, "launchctl.log");
   process.env.DSH_REMOTE_TELEMETRY = "0";
   process.env.DSH_RELAY_SKIP_SERVICE = "1"; // 默认隔离：用例按需 unset
+  // 假的 pgrep/ps：让 manualStatus「看得见」一个**旧账号的 bridge 进程**。
+  // 🔴 2026-09-25：本文件测的现场就是「旧账号的 bridge 还在跑」（否则面板压根看不到 accountCurrent=false）,
+  //   而旧实现只伪造了 launchctl、**没伪造 pgrep/ps** —— 于是用例偷偷依赖「开发机上正好有 bridge 在跑」：
+  //   开发机有 → 绿；CI 上没有 → 红（`npm test` 在 router 那步就断了，所以这个红一直被挡住）。
+  //   真实进程状态不该影响用例结果，所以这里显式伪造。
+  let fakeJob = null;
+  if (fakeBridgeJobs) {
+    fakeJob = spawn(process.execPath, ["-e", "setTimeout(() => {}, 30000)"], { stdio: "ignore" });
+    const stub = (body) => `#!/bin/sh\n${body}\n`;
+    await writeFile(path.join(fakeBin, "pgrep"), stub(`echo "${fakeJob.pid} node /x/clients/dsh-remote/dsh-bridge.mjs"`));
+    await chmod(path.join(fakeBin, "pgrep"), 0o755);
+    await writeFile(path.join(fakeBin, "ps"), stub('echo "1"')); // ppid=1 → 不会被当成 launchd 托管
+    await chmod(path.join(fakeBin, "ps"), 0o755);
+  }
   return {
     root, relayDir, fakeHome, launchLog: path.join(root, "launchctl.log"),
     async restore() {
+      try { fakeJob?.kill("SIGKILL"); } catch { /* 已退出 */ }
       for (const [k, v] of Object.entries(saved)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
       await rm(root, { recursive: true, force: true });
     },
@@ -101,7 +117,9 @@ const json = async (p, init) => {
 // ─────────── ① 旧账号的 bridge 不得被当成「已连接」 ───────────
 
 test("切换账号后：旧账号留下的 online 状态不得再当作注册证据", async () => {
-  const env = await makeEnv();
+  // fakeBridgeJobs：这个现场的前提就是「旧账号的 bridge 进程还在跑」——必须伪造出来，
+  // 而不是指望跑用例的那台机器上恰好有一个（CI 上没有 → 曾经必红）。
+  const env = await makeEnv({ fakeBridgeJobs: true });
   try {
     await writeFile(path.join(env.relayDir, "dsh-setup.mjs"), "// runtime stub");
     // 切账号后的配置：新账号、device_id 已被清空

package/packages/dsh-remote-web/test/announcements-proxy.test.mjs

@@ -0,0 +1,310 @@
+// 📣 公告 / 📶 镜像页耗时 —— **宿主半边**（lib/index.js）的路由契约回归。
+//
+// 为什么单独一个文件：announcements-ui.test.mjs 锁的是浏览器半的行为（徽标/入口/弹窗/不轮询），
+// 这里锁的是 node 半的两条**代理**路由 —— 它们是被浏览器半当"不存在的接口"来对待的
+// （fail closed 的前提是"拿不到就什么都不显示"），所以最要紧的用例是 **失败也不抛**。
+//
+// 两条路由：
+//   GET  /dsh-remote/announcements        → 上游 GET  {api}/api/announcements?client=desktop[&install_id=]
+//   POST /dsh-remote/announcements/click  → 上游 POST {api}/api/announcements/click {id[, install_id]}
+//   POST /dsh-remote/telemetry/mirror-load → 入队 mirror_load（ms / at / outcome），非法入参**静默丢弃**
+import assert from "node:assert/strict";
+import http from "node:http";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { apply, __telemetryInternals as TELEMETRY } from "../lib/index.js";
+
+/** 起一个假上游中继（只实现本文件关心的两个端点），把收到的请求记下来。 */
+async function startUpstream(handler) {
+  const seen = [];
+  const srv = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => { raw += c; });
+    req.on("end", () => {
+      const entry = { method: req.method, url: req.url, headers: req.headers, body: raw };
+      seen.push(entry);
+      handler(entry, res);
+    });
+  });
+  await new Promise((r) => srv.listen(0, "127.0.0.1", r));
+  return { srv, seen, base: `http://127.0.0.1:${srv.address().port}` };
+}
+
+function boot(relayDir) {
+  const routes = [];
+  apply({
+    webServer: { register(rt) { routes.push(rt); return () => {}; } },
+    effect(reg) { return reg(); },
+    logger: { info() {}, warn() {} },
+  }, { relayDir });
+  const host = http.createServer((req, res) => {
+    const url = new URL(req.url, "http://x");
+    // 与 lib/index.js 的注册语义一致：kind=exact 精确匹配；kind=prefix 匹配自身或子路径。
+    // 🔴 注册对象上**只有** {kind, path, handler} —— 没有 method/prefix 字段，
+    //    方法判定与子路径分发都在插件自己的 handler 里（见 registerRoutes 的注册循环）。
+    //    2026-09-27 修：本文件原来按 `route.prefix` / `route.method` 去匹配（那两个字段根本不存在）
+    //    ⇒ methodOk 恒为 false ⇒ 所有请求都落到兜底 404、body 为空 ⇒ 真路由的用例集体报
+    //    "Unexpected end of JSON input"（假红，不是实现的问题）。照 community-qr-ui.test.mjs 的写法对齐。
+    const rt = routes.find((r) => (r.kind === "prefix"
+      ? url.pathname === r.path || url.pathname.startsWith(r.path + "/")
+      : url.pathname === r.path));
+    (rt ? rt.handler : ((_r, rs) => { rs.writeHead(404); rs.end(); }))(req, res);
+  });
+  return host;
+}
+
+// 注：本文件**不需要**自己管理 DSH_RELAY_SKIP_SERVICE —— `npm run test:plugin` 已给整个套件设了 `=1`。
+// 曾经这里有个 withEnv() 提前 delete 它（既无人调用，又会被 setup-output.test.mjs 的静态护栏判为
+// 「unset 开关却没伪造 HOME」）。删掉它，隔离与护栏两边都干净。
+
+/**
+ * 从假上游收到的请求里**只挑公告那一条**。
+ * 为什么不能写 `up.seen[0]`：插件装载时还会对同一个 api_url 发起旁路请求
+ * （harness 会话代持 scheduleHarnessMint、账号 device-login 等），它们同样落进 seen，
+ * 谁先到不确定 —— 按下标取会变成**偶发假红**（2026-09-27 实测踩到一次）。
+ */
+const annReq = (up) => up.seen.find((e) => String(e.url || "").startsWith("/api/announcements"));
+
+const writeCfg = (relayDir, apiUrl, extra = {}) => writeFile(path.join(relayDir, ".dsh-config.json"), JSON.stringify({
+  device_id: "dev-ann-1", api_url: apiUrl, ...extra,
+}));
+
+// ───────────────────────────── GET 代理 ─────────────────────────────
+
+test("GET /dsh-remote/announcements：显式带 client=desktop，未登录时带本机 install_id（复用 device_id，不新造 ID）", async () => {
+  const up = await startUpstream((_e, res) => { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, bubble_enabled: true, items: [], unread_count: 0, popup: null })); });
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    await writeCfg(relayDir, up.base);
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    const r = await (await fetch(`${base}/dsh-remote/announcements?client=desktop`)).json();
+    assert.equal(r.ok, true);
+
+    const got = annReq(up);
+    assert.ok(got, "必须真的打到上游 /api/announcements");
+    assert.equal(got.method, "GET");
+    const u = new URL(got.url, "http://x");
+    assert.equal(u.pathname, "/api/announcements", "必须打到上游 /api/announcements");
+    assert.equal(u.searchParams.get("client"), "desktop", "必须显式声明桌面端（926 迭代 §1）");
+    assert.equal(u.searchParams.get("install_id"), "dev-ann-1", "未登录时用本机既有 device_id 做维度");
+    assert.equal(got.headers.authorization, undefined, "没有账号时不得凭空造 Bearer");
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    up.srv.close();
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+test("GET：浏览器已带 Bearer → 透传，且**不再**带 install_id（两种身份维度绝不能混用）", async () => {
+  const up = await startUpstream((_e, res) => { res.writeHead(200, { "content-type": "application/json" }); res.end("{\"ok\":true}"); });
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    await writeCfg(relayDir, up.base, { phone: "13800000000", password: "pw" });
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    await fetch(`${base}/dsh-remote/announcements?client=desktop`, { headers: { authorization: "Bearer browser-jwt" } });
+    const got = annReq(up);
+    assert.ok(got, "必须真的打到上游 /api/announcements");
+    assert.equal(got.headers.authorization, "Bearer browser-jwt", "浏览器带上的身份必须原样透传");
+    const u = new URL(got.url, "http://x");
+    assert.equal(u.searchParams.get("install_id"), null,
+      "有 user 维度时不得再带 install_id —— 唯一索引会把同一人两台机器算成两行，UV 翻倍");
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    up.srv.close();
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+test("GET：上游 404（老服务端）→ 原样透传 404（浏览器半据此 fail closed），路由本身不抛", async () => {
+  const up = await startUpstream((_e, res) => { res.writeHead(404, { "content-type": "application/json" }); res.end("{\"error\":{\"code\":\"not_found\"}}"); });
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    await writeCfg(relayDir, up.base);
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    const res = await fetch(`${base}/dsh-remote/announcements?client=desktop`);
+    assert.equal(res.status, 404);
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    up.srv.close();
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+test("GET：上游不可达 → 502 + {ok:false}（软着陆：绝不抛成 500 堆栈）", async () => {
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    // 指向一个已经关掉的端口：连接必然失败
+    await writeCfg(relayDir, "http://127.0.0.1:1");
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    const res = await fetch(`${base}/dsh-remote/announcements?client=desktop`);
+    assert.equal(res.status, 502, "不可达必须是 502（不是 500、不是抛异常）");
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.match(String(body.error), /公告服务不可达/);
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+// ───────────────────────────── click 代理 ─────────────────────────────
+
+test("POST /dsh-remote/announcements/click：转发 {id} 到上游 /api/announcements/click，并补 install_id", async () => {
+  const up = await startUpstream((_e, res) => { res.writeHead(200, { "content-type": "application/json" }); res.end("{\"ok\":true}"); });
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    await writeCfg(relayDir, up.base);
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    const r = await (await fetch(`${base}/dsh-remote/announcements/click`, {
+      method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: 7 }),
+    })).json();
+    assert.equal(r.ok, true);
+
+    const got = annReq(up);
+    assert.ok(got, "必须真的打到上游 /api/announcements/click");
+    assert.equal(got.method, "POST");
+    assert.equal(new URL(got.url, "http://x").pathname, "/api/announcements/click");
+    const sent = JSON.parse(got.body);
+    assert.equal(sent.id, 7, "id 必须原样转发");
+    assert.equal(sent.install_id, "dev-ann-1", "未登录维度要补 install_id，否则点击记不到这台机器名下");
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    up.srv.close();
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+test("未知子路径 → 404（不自造接口，也不把奇怪路径代理到上游）", async () => {
+  const up = await startUpstream((_e, res) => { res.writeHead(200); res.end("{}"); });
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    await writeCfg(relayDir, up.base);
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    // 契约里没有 /read —— 老客户端若按错的路径打过来，必须明确 404（而不是打到上游去）
+    const res = await fetch(`${base}/dsh-remote/announcements/read`, { method: "POST", body: "{}" });
+    assert.equal(res.status, 404);
+    assert.equal(up.seen.length, 0, "未命中子路径时不得触碰上游");
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    up.srv.close();
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});
+
+// ───────────────────────────── mirror_load 事件 ─────────────────────────────
+
+test("mirror_load 事件形状：ms / at / outcome 三个字段，且越界由 eventOf 兜底钳制", () => {
+  const ev = TELEMETRY.eventOf("mirror_load", { ms: 1234, at: 1758500000000, outcome: "slow" });
+  assert.ok(ev, "mirror_load 必须在白名单里（否则事件被静默丢弃）");
+  assert.equal(ev.name, "mirror_load");
+  assert.equal(ev.ms, 1234);
+  assert.equal(ev.at, 1758500000000, "at 必须是客户端事件时刻（覆盖默认的 Date.now）");
+  assert.equal(ev.outcome, "slow");
+  // 缺 at → 保留默认时刻（绝不发 0，0 会被读成 1970 年）
+  const noAt = TELEMETRY.eventOf("mirror_load", { ms: 10 });
+  assert.ok(noAt.at > 0, "没给 at 时必须退回事件构造时刻，绝不发 0");
+  assert.equal(noAt.outcome, "ok", "outcome 只认 slow，其余一律 ok");
+  // 越界 / 非法 ms：不写入该字段（路由层已先挡掉，这是第二道防线）
+  const bad = TELEMETRY.eventOf("mirror_load", { ms: "abc" });
+  assert.equal("ms" in bad, false, "非法 ms 不得进 payload");
+  const huge = TELEMETRY.eventOf("mirror_load", { ms: 10 ** 9 });
+  assert.equal(huge.ms, 600000, "越界 ms 钳到契约上限");
+});
+
+test("POST /dsh-remote/telemetry/mirror-load：合法/非法入参都回 200 {ok:true}，非法**静默丢弃**", async () => {
+  const relayDir = await mkdtemp(path.join(os.tmpdir(), "dsh-ann-"));
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";
+  try {
+    const host = boot(relayDir);
+    await new Promise((r) => host.listen(0, "127.0.0.1", r));
+    const base = `http://127.0.0.1:${host.address().port}`;
+    const post = async (body) => {
+      const res = await fetch(`${base}/dsh-remote/telemetry/mirror-load`, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+      });
+      return { status: res.status, body: await res.json() };
+    };
+    // 隔离开关（DSH_RELAY_SKIP_SERVICE=1）下遥测整体关闭 → 这里看到的就是"路由**永远**回 200"，
+    // 而不是 4xx/5xx —— 手机镜像页的加载路径绝不能被一条统计请求打扰。
+    for (const payload of [
+      { ms: 800, at: Date.now(), outcome: "ok" },
+      { ms: -1, at: Date.now() },                 // 负数
+      { ms: 600001, at: Date.now() },             // 超上限
+      { ms: "abc" },                              // 非数字
+      {},                                          // 缺字段
+    ]) {
+      const r = await post(payload);
+      assert.equal(r.status, 200, "任何入参都必须是 200 " + JSON.stringify(payload));
+      assert.equal(r.body.ok, true);
+    }
+    // 极端：连 JSON 都不是 → 仍然 200（绝不因为一条统计把页面打成错误）
+    const raw = await fetch(`${base}/dsh-remote/telemetry/mirror-load`, { method: "POST", body: "not-json" });
+    assert.equal(raw.status, 200);
+    host.close();
+  } finally {
+    // 恢复套件级隔离（**不要 delete**）：package.json 的 test:plugin 就是把 DSH_RELAY_SKIP_SERVICE=1
+    // 设给整个套件的；这里 delete 会把它一起删掉 → 本文件之后的用例失去隔离，真的去后台
+    // `npx @mrrisegao/dsh-remote` 装运行环境（2026-09-27 实测：日志里刷出一串
+    // 「检测到缺少桌面运行环境,已在后台自动安装」，既慢又有真实副作用）。
+    // 本文件只测路由，不需要走真实分支。
+    process.env.DSH_RELAY_SKIP_SERVICE = "1";
+    TELEMETRY.reset(relayDir);
+    await rm(relayDir, { recursive: true, force: true });
+  }
+});