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

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

@@ -0,0 +1,524 @@
+// 📣 公告（插件端）回归：徽标 / 面板入口 / 电脑端弹窗 / 已读上报 / 一条铁律（**不轮询**）。
+//
+// 契约：dsh-relay-enterprise/docs/announcements-contract.md（冻结 v1）+ 926 迭代 §1（client=desktop）。
+//   GET  /dsh-remote/announcements?client=desktop → { bubble_enabled, items[], unread_count, popup|null }
+//   POST /dsh-remote/announcements/click { id }   → 记 clicked_at（**现契约只有 /click，没有 /read**）
+//
+// 这个文件锁的是**客户端纪律**（服务端行为另有 enterprise 侧的用例）：
+//   ① 有未读 → 侧栏入口出现数字徽标 + 面板出现「📣 公告」卡；
+//   ② bubble_enabled:false / 字段缺失 → 一个入口都不出现（fail closed）；items 缺失当空数组；
+//   ③ 接口 404 或不可达 → 不显示任何入口、**且不抛**（客户端插件抛异常 = 整个 web app 起不来）；
+//   ④ 点一条公告 → 发 POST /dsh-remote/announcements/click；
+//   ⑤ 弹窗 close/✕/「已读」任意入口 = 关闭 + 上报（同一个收尾函数）；
+//   ⑥ popup 的本地防抖 = 「同 id + 60s」：60s 内不再弹、61s 后可以再弹；
+//   ⑦ **绝不轮询**：`GET /api/announcements` 是"判定即记账"（命中弹窗候选就写 shown_at），
+//      多拉一次就可能把该弹的公告静默消耗掉 —— 每次页面加载只能自动拉一次。
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import vm from "node:vm";
+
+const SOURCE = readFileSync(new URL("../lib/client.js", import.meta.url), "utf8");
+
+function walk(node, visit) {
+  if (node == null) return;
+  if (Array.isArray(node)) { for (const item of node) walk(item, visit); return; }
+  if (typeof node !== "object") return;
+  visit(node);
+  for (const child of node.children || []) walk(child, visit);
+}
+function find(tree, predicate) {
+  let match;
+  walk(tree, (node) => { if (!match && predicate(node)) match = node; });
+  return match;
+}
+function textHas(tree, substr) {
+  return !!find(tree, (node) => (node.children || []).some((c) => typeof c === "string" && c.includes(substr)));
+}
+/** 找到"文字是 substr 且可点"的那颗按钮（按钮文字可能被包在 span 里，所以两处都看）。 */
+function nodeWithText(tree, substr) {
+  return find(tree, (node) => typeof node.props?.onClick === "function" &&
+    ((node.children || []).some((c) => typeof c === "string" && c.includes(substr)) ||
+     (node.children || []).some((c) => c && typeof c === "object" && (c.children || []).some((s) => typeof s === "string" && s.includes(substr)))));
+}
+/** 同上，但**深度**遍历子树里的所有文本（公告条目把标题放在 span > span 里）。 */
+function clickableWithDeepText(tree, substr) {
+  return find(tree, (node) => {
+    if (typeof node.props?.onClick !== "function") return false;
+    let hit = false;
+    walk(node, (n) => {
+      if (!hit && (n.children || []).some((c) => typeof c === "string" && c.includes(substr))) hit = true;
+    });
+    return hit;
+  });
+}
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+/**
+ * 迷你 React（真实 useEffect + 假定时器 + 可控时钟）+ 假 fetch。
+ * @param {object} opts
+ *   - announcements：GET /dsh-remote/announcements 的响应（可以是函数，按第 N 次调用返回不同结果）
+ *   - storage：跨"页面加载"共享的 localStorage（模拟同一个 origin 反复开页面）
+ *   - clock：可推进的时钟对象（测试里用来验证 60s 防抖窗口）
+ */
+function loadPlugin(opts = {}) {
+  let moduleFactory;
+  const registered = new Map();
+  const requests = [];
+
+  let clock = 0;
+  let timerSeq = 1;
+  const timers = new Map();
+  const job = (fn) => { try { fn(); } catch (e) { /* 断言会暴露问题 */ } };
+  const fakeSetTimeout = (fn, ms) => { const id = timerSeq++; timers.set(id, { at: clock + (Number(ms) || 0), fn, every: 0 }); return id; };
+  const fakeSetInterval = (fn, ms) => { const id = timerSeq++; const every = Math.max(1, Number(ms) || 1); timers.set(id, { at: clock + every, fn, every }); return id; };
+  const fakeClear = (id) => { timers.delete(id); };
+
+  const scopes = new Map();
+  const scopeStack = [];
+  const currentScope = () => scopeStack[scopeStack.length - 1];
+
+  const react = {
+    createElement(type, props, ...children) { return { type, props: props || {}, children }; },
+    useState(initial) {
+      const sc = currentScope();
+      const index = sc.hook++;
+      if (!(index in sc.state)) sc.state[index] = typeof initial === "function" ? initial() : initial;
+      return [sc.state[index], (value) => { sc.state[index] = typeof value === "function" ? value(sc.state[index]) : value; }];
+    },
+    useEffect(fn, deps) {
+      const sc = currentScope();
+      const index = sc.effectCursor++;
+      const prev = sc.effects[index];
+      const changed = !prev || !deps || deps.length !== prev.deps.length || deps.some((d, i) => !Object.is(d, prev.deps[i]));
+      if (changed) sc.pending.push({ index, fn, deps: deps ? [...deps] : deps });
+    },
+    useCallback(fn) { return fn; },
+    useSyncExternalStore(_subscribe, getSnapshot) { return getSnapshot(); },
+  };
+
+  function renderNode(node, path) {
+    if (node == null) return node;
+    if (Array.isArray(node)) return node.map((n, i) => renderNode(n, path + "/" + i));
+    if (typeof node !== "object") return node;
+    if (typeof node.type === "function") {
+      const name = node.type.name || "anon";
+      const key = path + ":" + name;
+      const sc = scopes.get(key) || { hook: 0, effectCursor: 0, state: [], effects: [], pending: [] };
+      sc.hook = 0; sc.effectCursor = 0; sc.pending = [];
+      scopes.set(key, sc);
+      scopeStack.push(sc);
+      let out;
+      try {
+        out = node.type(node.props || {});
+      } finally {
+        scopeStack.pop();
+      }
+      const expanded = renderNode(out, key);
+      const todos = sc.pending;
+      sc.pending = [];
+      for (const t of todos) {
+        const prev = sc.effects[t.index];
+        if (prev && typeof prev.cleanup === "function") job(prev.cleanup);
+        const cleanup = t.fn();
+        sc.effects[t.index] = { deps: t.deps, cleanup: typeof cleanup === "function" ? cleanup : null };
+      }
+      return expanded;
+    }
+    return { ...node, children: (node.children || []).map((c, i) => renderNode(c, path + "/" + i)) };
+  }
+
+  const status = opts.status || {
+    ok: true,
+    config: { phone: "138****0000", hasPhone: true, mode: "saas", deviceId: "dev-x" },
+    service: { running: true },
+  };
+  const response = (s, body) => Promise.resolve({ ok: s >= 200 && s < 300, status: s, text: async () => JSON.stringify(body) });
+  // announcements 可以是数组（按第 N 次 GET 依次取，越界用最后一项）或固定对象
+  const annSeq = Array.isArray(opts.announcements) ? opts.announcements.slice() : null;
+  const annFixed = annSeq ? null : (opts.announcements !== undefined
+    ? opts.announcements
+    : { ok: true, bubble_enabled: true, unread_count: 2, items: [
+        { id: 3, title: "新功能上线", body: "扫码登录更快了", image: "", pinned: 1, created_at: 1758500000000, unread: true },
+        { id: 4, title: "维护通知", body: "周日凌晨维护", image: "", pinned: 0, created_at: 1758400000000, unread: true },
+      ], popup: null });
+  let annCalls = 0;
+
+  const makeEl = () => ({
+    tag: "div", children: [], style: {}, className: "", attributes: {}, textContent: "",
+    setAttribute(k, v) { this.attributes[k] = v; },
+    getAttribute(k) { return this.attributes[k] ?? null; },
+    appendChild(c) { this.children.push(c); return c; },
+    removeChild(c) { this.children = this.children.filter((x) => x !== c); return c; },
+    querySelector(sel) {
+      const cls = String(sel || "").replace(/^\./, "");
+      return this.children.find((c) => String(c.className || "").split(/\s+/).includes(cls)) || null;
+    },
+    querySelectorAll() { return []; },
+    addEventListener() {}, removeEventListener() {},
+  });
+  // 侧栏「📱 远程访问」入口：本插件的徽标逻辑要求它**存在**（否则 annRenderNavBadge 会静默跳过）。
+  // 这里先备好这个节点，document.getElementById 对它的 id 返回它 —— 模拟"官方设置按钮已渲染、入口已注入"。
+  const navBtn = makeEl();
+  navBtn.id = "dru-nav-remote";
+  const doc = {
+    hidden: false,
+    createElement: makeEl,
+    head: makeEl(),
+    body: makeEl(),
+    querySelector() { return null; },
+    querySelectorAll() { return []; },
+    getElementById(id) { return id === "dru-nav-remote" ? navBtn : null; },
+    addEventListener() {}, removeEventListener() {},
+  };
+  class MutationObserverMock { constructor() {} observe() {} disconnect() {} }
+
+  const store = opts.storage || new Map();
+  const localStorage = {
+    get length() { return store.size; },
+    key(i) { return Array.from(store.keys())[i] ?? null; },
+    getItem(k) { return store.has(k) ? store.get(k) : null; },
+    setItem(k, v) { store.set(k, String(v)); },
+    removeItem(k) { store.delete(k); },
+  };
+  const sessionStore = new Map();
+  const sessionStorage = {
+    getItem(k) { return sessionStore.has(k) ? sessionStore.get(k) : null; },
+    setItem(k, v) { sessionStore.set(k, String(v)); },
+    removeItem(k) { sessionStore.delete(k); },
+  };
+
+  // 可推进时钟：Date.now() 与 new Date() 都跟着 opts.clock.now 走（fmtDate 需要它）
+  const clockRef = opts.clock || { now: 1758500000000 };
+  class FakeDate extends Date {
+    constructor(...args) { if (args.length === 0) super(clockRef.now); else super(...args); }
+    static now() { return clockRef.now; }
+  }
+
+  const sandbox = {
+    window: { __ModuleLoader__: { load(spec) { moduleFactory = spec.factory; } }, open() { return null; } },
+    document: doc,
+    localStorage,
+    sessionStorage,
+    MutationObserver: MutationObserverMock,
+    navigator: { clipboard: { writeText: async () => {} } },
+    setTimeout: fakeSetTimeout,
+    clearTimeout: fakeClear,
+    setInterval: fakeSetInterval,
+    clearInterval: fakeClear,
+    fetch(path, options = {}) {
+      requests.push({ path, method: options.method || "GET", body: options.body || "" });
+      if (path === "/dsh-remote/status") return response(200, status);
+      if (path === "/dsh-remote/community") return response(200, { ok: true, qrcode: "", wechat: "" });
+      if (path.startsWith("/dsh-remote/announcements/click")) return response(200, { ok: true });
+      if (path.startsWith("/dsh-remote/announcements")) {
+        annCalls += 1;
+        const entry = annSeq ? (annSeq[Math.min(annCalls - 1, annSeq.length - 1)]) : annFixed;
+        if (entry && entry.__status) return response(entry.__status, entry.body || { ok: false });
+        return response(200, entry);
+      }
+      return response(200, { ok: true });
+    },
+    Set, Symbol, Date: FakeDate, JSON, Math, Number, String, Object, Array, console,
+  };
+
+  vm.runInNewContext(SOURCE, sandbox);
+  const plugin = moduleFactory((name) => {
+    assert.equal(name, "react");
+    return react;
+  });
+  const applied = { threw: null };
+  try {
+    plugin.apply({
+      slots: {
+        inject(name, cb) { cb(); },
+        register(meta, component) { registered.set(meta.id, component); return () => {}; },
+      },
+    });
+  } catch (e) {
+    applied.threw = e;
+  }
+
+  return {
+    requests,
+    registered,
+    navBtn,
+    applied,
+    annCalls: () => annCalls,
+    setClock(ms) { clockRef.now = ms; },
+    /** 渲染 → 让在途请求落地 → 再渲染（返回最新树）。 */
+    async settle(times = 2) {
+      let tree = null;
+      for (let i = 0; i < times; i++) { tree = this.render(); await flush(); await flush(); }
+      return this.render();
+    },
+    render() {
+      const root = { type: registered.get("dsh-remote"), props: { close() {} }, children: [] };
+      return renderNode(root, "root");
+    },
+    /** 单独渲染 shell.overlay 上的公告弹窗（它在真实环境里与面板是两棵树）。 */
+    renderPopup() {
+      const comp = registered.get("dsh-announcement-popup");
+      if (!comp) return null;
+      return renderNode({ type: comp, props: {}, children: [] }, "popup");
+    },
+  };
+}
+
+// ───────────────────────────── ① 有未读 → 徽标 + 面板入口 ─────────────────────────────
+
+test("未读公告 → 侧栏入口出现数字徽标；设置面板出现「📣 公告」卡（含条目与未读标签）", async () => {
+  const plugin = loadPlugin();
+  const tree = await plugin.settle();
+
+  // 侧栏徽标（DOM，不走 React）：annEmit 之后挂到 #dru-nav-remote 上
+  const badge = plugin.navBtn.children.find((c) => c.className === "dru-nav-remote-badge");
+  assert.ok(badge, "侧栏「📱 远程访问」入口上应出现未读徽标");
+  assert.equal(badge.textContent, "2", "徽标显示未读条数");
+
+  // 面板卡片 + 两个条目 + 标题
+  assert.ok(textHas(tree, "📣 公告"), "面板应出现公告卡");
+  assert.ok(textHas(tree, "新功能上线"), "应列出第一条公告标题");
+  assert.ok(textHas(tree, "维护通知"), "应列出第二条公告标题");
+  assert.ok(textHas(tree, "未读"), "未读条目应有「未读」文字标签（不靠颜色单独表意）");
+  assert.ok(textHas(tree, "置顶"), "pinned 条目应有「置顶」标签");
+  assert.ok(textHas(tree, "2 条未读"), "卡片标题应带未读数");
+});
+
+test("未读数 > 9 → 徽标显示 9+（不能把 12 挤成一个宽数字）", async () => {
+  const plugin = loadPlugin({
+    announcements: {
+      ok: true, bubble_enabled: true, unread_count: 12,
+      items: [{ id: 1, title: "A", body: "", image: "", pinned: 0, created_at: 0, unread: true }],
+      popup: null,
+    },
+  });
+  await plugin.settle();
+  const badge = plugin.navBtn.children.find((c) => c.className === "dru-nav-remote-badge");
+  assert.ok(badge, "应有徽标");
+  assert.equal(badge.textContent, "9+");
+});
+
+// ───────────────────────── ② bubble_enabled:false / 字段缺失 → 无入口 ─────────────────────────
+
+test("bubble_enabled:false → 面板无入口、侧栏无徽标（后台把入口关掉就是不显示）", async () => {
+  const plugin = loadPlugin({
+    announcements: {
+      ok: true, bubble_enabled: false, unread_count: 3,
+      items: [{ id: 1, title: "不该出现", body: "", image: "", pinned: 0, created_at: 0, unread: true }],
+      popup: null,
+    },
+  });
+  const tree = await plugin.settle();
+  assert.ok(!textHas(tree, "不该出现"), "入口关闭时不得渲染任何公告条目");
+  assert.ok(!textHas(tree, "📣 公告"), "入口关闭时不得渲染公告卡");
+  assert.equal(plugin.navBtn.children.filter((c) => c.className === "dru-nav-remote-badge").length, 0, "入口关闭时不得有徽标");
+});
+
+test("字段缺失（无 bubble_enabled / 无 items / 无 unread_count）→ 一律 fail closed，且不抛", async () => {
+  const plugin = loadPlugin({ announcements: { ok: true } });   // 极端的老/坏响应
+  const tree = await plugin.settle();
+  assert.equal(plugin.applied.threw, null, "客户端插件绝不能抛（会拖垮整个 web app）");
+  assert.ok(!textHas(tree, "📣 公告"), "bubble_enabled 缺失 = false → 不显示入口");
+  assert.ok(textHas(tree, "远程访问"), "面板自身照常渲染");
+});
+
+// ───────────────────────────── ③ 404 / 不可达 → 无入口且不抛 ─────────────────────────────
+
+test("接口 404（老服务端）→ 无入口、无弹窗、不抛", async () => {
+  const plugin = loadPlugin({ announcements: { __status: 404, body: { error: { code: "not_found" } } } });
+  const tree = await plugin.settle();
+  assert.equal(plugin.applied.threw, null, "404 时插件装载不得抛异常");
+  assert.ok(!textHas(tree, "📣 公告"), "拿不到公告时不得显示空入口");
+  assert.equal(plugin.renderPopup(), null, "拿不到公告时不得弹窗");
+  assert.ok(textHas(tree, "远程访问"), "面板其它部分照常可用");
+});
+
+test("接口不可达（fetch reject）→ 无入口且不抛", async () => {
+  // 用 __status: 0 + 让 text() 抛异常，模拟"网络直接断了"
+  const plugin = loadPlugin({ announcements: { __status: 500, body: { ok: false } } });
+  const tree = await plugin.settle();
+  assert.equal(plugin.applied.threw, null, "上游 5xx 时插件装载不得抛异常");
+  assert.ok(!textHas(tree, "📣 公告"), "拉取失败不得显示入口");
+});
+
+// ───────────────────────────── ④ 点公告 → 上报 click ─────────────────────────────
+
+test("点一条未读公告 → 立刻 POST /dsh-remote/announcements/click（带 id），并展开详情", async () => {
+  const plugin = loadPlugin();
+  let tree = await plugin.settle();
+  const item = clickableWithDeepText(tree, "新功能上线");
+  assert.ok(item, "应能点到公告条目");
+
+  item.props.onClick();
+  tree = await plugin.settle();
+
+  const click = plugin.requests.find((r) => r.path === "/dsh-remote/announcements/click");
+  assert.ok(click, "点公告必须上报点击（现契约只有 /click，没有 /read）");
+  assert.equal(click.method, "POST", "点击上报必须是 POST");
+  assert.equal(JSON.parse(click.body).id, 3, "请求体必须带该条公告的 id");
+  assert.ok(textHas(tree, "已读状态已同步到后台"), "点击后应展开详情弹窗");
+  assert.ok(textHas(tree, "扫码登录更快了"), "详情应展示公告正文");
+});
+
+// ───────────────────── ⑤ / ⑦ 弹窗：任意入口都关闭 + 上报 ─────────────────────
+
+test("电脑端弹窗：点「✕」即关闭并上报（任意按钮/遮罩都走同一个已读收尾）", async () => {
+  const plugin = loadPlugin({
+    announcements: {
+      ok: true, bubble_enabled: true, unread_count: 1,
+      items: [{ id: 7, title: "弹窗公告", body: "正文", image: "", pinned: 0, created_at: 0, unread: true }],
+      popup: { id: 7, title: "弹窗公告", body: "正文", image: "" },
+    },
+  });
+  await plugin.settle();
+  let popup = plugin.renderPopup();
+  assert.ok(popup, "有 popup 时应出现电脑端弹窗");
+  assert.ok(textHas(popup, "弹窗公告"), "弹窗应展示公告标题");
+
+  const x = find(popup, (n) => n.props?.className === "dru-popup-x");
+  assert.ok(x, "弹窗应有 ✕");
+  x.props.onClick();
+  await flush();
+  await flush();
+
+  const click = plugin.requests.find((r) => r.path === "/dsh-remote/announcements/click");
+  assert.ok(click, "关闭弹窗必须上报已读（POST /click）");
+  assert.equal(JSON.parse(click.body).id, 7);
+  assert.equal(plugin.renderPopup(), null, "关闭后弹窗必须消失");
+});
+
+test("电脑端弹窗：点底部「已读」按钮同样关闭并上报（两个按钮同一个收尾）", async () => {
+  const plugin = loadPlugin({
+    announcements: {
+      ok: true, bubble_enabled: true, unread_count: 1,
+      items: [{ id: 8, title: "T", body: "", image: "", pinned: 0, created_at: 0, unread: true }],
+      popup: { id: 8, title: "T", body: "", image: "" },
+    },
+  });
+  await plugin.settle();
+  const popup = plugin.renderPopup();
+  const btn = nodeWithText(popup, "已读");
+  assert.ok(btn, "弹窗应有「已读」按钮");
+  btn.props.onClick();
+  await flush();
+  await flush();
+  assert.ok(plugin.requests.some((r) => r.path === "/dsh-remote/announcements/click"));
+  assert.equal(plugin.renderPopup(), null);
+});
+
+// ───────────────────── ⑥ popup 本地防抖：同 id + 60s 时间窗 ─────────────────────
+
+test("弹窗防抖：同一条公告 60s 内不再弹、61s 后可以再弹（不把服务端的 always 压成 once）", async () => {
+  const clock = { now: 1758500000000 };
+  const storage = new Map();   // 跨"页面加载"共享（模拟同一个 origin 反复打开）
+  const popupResp = {
+    ok: true, bubble_enabled: true, unread_count: 0, items: [],
+    popup: { id: 42, title: "重复弹", body: "", image: "" },
+  };
+
+  // 第 1 次页面加载：弹出来 → 关掉（记为已读，落本地防抖记忆）
+  const p1 = loadPlugin({ announcements: popupResp, storage, clock });
+  await p1.settle();
+  const popup1 = p1.renderPopup();
+  assert.ok(popup1, "第一次应弹出");
+  nodeWithText(popup1, "已读").props.onClick();
+  await flush(); await flush();
+
+  // 第 2 次页面加载（+30s）：服务端**仍然**返回同一条（= always 模式的真实形态）→ 本地必须挡住
+  clock.now += 30 * 1000;
+  const p2 = loadPlugin({ announcements: popupResp, storage, clock });
+  await p2.settle();
+  assert.equal(p2.renderPopup(), null, "60s 内同一条不得重复弹（防打扰）");
+
+  // 第 3 次页面加载（+61s）：窗口过了 → 允许再弹（否则等于把服务端的 always 静默压成 once）
+  clock.now += 31 * 1000;
+  const p3 = loadPlugin({ announcements: popupResp, storage, clock });
+  await p3.settle();
+  assert.ok(p3.renderPopup(), "超过 60s 后同一条应可再次弹出");
+});
+
+test("once 模式：服务端不再返回该条 → 后续页面加载都不弹（本地无需永久记忆也等价）", async () => {
+  const clock = { now: 1758500000000 };
+  const storage = new Map();
+  const first = {
+    ok: true, bubble_enabled: true, unread_count: 0, items: [],
+    popup: { id: 5, title: "只此一次", body: "", image: "" },
+  };
+  const later = { ok: true, bubble_enabled: true, unread_count: 0, items: [], popup: null };
+
+  const p1 = loadPlugin({ announcements: first, storage, clock });
+  await p1.settle();
+  assert.ok(p1.renderPopup(), "第一次应弹出");
+  nodeWithText(p1.renderPopup(), "关闭").props.onClick();
+  await flush(); await flush();
+
+  clock.now += 10 * 60 * 1000;   // 十分钟后重开页面
+  const p2 = loadPlugin({ announcements: later, storage, clock });
+  await p2.settle();
+  assert.equal(p2.renderPopup(), null, "服务端不再给 → 永远不再弹");
+});
+
+// ───────────────────────────── ⑧ 绝不轮询 ─────────────────────────────
+
+test("绝不轮询：每次页面加载只自动拉一次公告（重复拉会吃掉该弹的公告）", async () => {
+  const plugin = loadPlugin();
+  await plugin.settle(4);   // 多渲染几轮，任何"render 里顺手拉一次"的实现都会在这里暴露
+  const gets = plugin.requests.filter((r) => r.path === "/dsh-remote/announcements?client=desktop");
+  assert.equal(gets.length, 1, "自动拉取必须只有一次（服务端 GET 是判定即记账）");
+  assert.equal(plugin.annCalls(), 1);
+  // 而且必须带 client=desktop（926 迭代 §1：桌面端只拿 target=desktop/both 的公告）
+  assert.ok(gets[0].path.includes("client=desktop"), "必须显式声明 client=desktop");
+});
+
+test("源码级：面板卡片里的「刷新公告」是唯一的手动重拉入口，且**不**用于弹窗", () => {
+  assert.match(SOURCE, /annPullOnce/, "必须有 sessionStorage 一次性拉取标记");
+  assert.match(SOURCE, /openPopup:\s*false/, "手动刷新必须显式关闭弹窗（openPopup:false）");
+  // 一次性标记必须写在 sessionStorage（localStorage 的 origin 会随端口变，挡不住同页重复拉）
+  const fn = SOURCE.slice(SOURCE.indexOf("function annPullOnce("), SOURCE.indexOf("function annReportClick("));
+  assert.match(fn, /sessionStorage/, "一次性标记必须在 sessionStorage 上");
+  assert.match(fn, /ANN_PULLED_KEY/);
+});
+
+// ───────────────────────── 契约细节：客户端身份维度与上报路径 ─────────────────────────
+
+test("源码级：已读上报走 /dsh-remote/announcements/click（不是 /read）", () => {
+  assert.match(SOURCE, /\/dsh-remote\/announcements\/click/);
+  assert.doesNotMatch(SOURCE, /announcements\/read/, "现契约没有 /read —— 不许自造接口");
+});
+
+test("微信机器人引导：两步走引导块在能力清单之上（DOM 顺序）+ 命令帮助与 HELP_TEXT 对账", async () => {
+  const plugin = loadPlugin();
+  let tree = await plugin.settle();
+  // 进入微信机器人 tab（未登录时不渲染这个 tab，所以先确认它在）
+  const tab = nodeWithText(tree, "微信机器人通道");
+  assert.ok(tab, "应有「微信机器人通道」tab");
+  tab.props.onClick();
+  tree = await plugin.settle();
+
+  const embed = find(tree, (n) => n.props?.className === "dru-wx-embed");
+  assert.ok(embed, "前提：已进入微信 tab");
+  // ① DOM 顺序：引导块（干什么用 + 两步怎么做）必须排在能力清单（.dru-wx-intro）**之上** ——
+  //    先讲"这是什么、我要做哪两步"，再讲"我能用哪些能力"。CSS 里的先后不算数，看渲染树。
+  assert.equal(embed.children[0]?.props?.className, "dru-wx-guide",
+    "「两步走」引导必须是内容体第一个孩子（在能力清单之前）");
+  assert.equal(embed.children[1]?.props?.className, "dru-wx-intro",
+    "能力清单必须紧随引导块之后");
+  const guide = embed.children[0];
+  for (const s of ["微信机器人是做什么的", "第一步", "第二步", "ClawBot", "24 小时", "连接新的 OpenClaw"]) {
+    assert.ok(textHas(guide, s), "引导块必须包含：" + s);
+  }
+  // ② 命令帮助**复用** wechat-channel.mjs 的 HELP_TEXT（跨 bundle 没有 require 通道 → 镜像 + 逐条对账）
+  const helpSrc = readFileSync(new URL("../../../clients/dsh-remote/wechat-channel.mjs", import.meta.url), "utf8");
+  const m = helpSrc.match(/export const HELP_TEXT = \[([\s\S]*?)\]\.join\("\\n"\)/);
+  assert.ok(m, "必须能从 wechat-channel.mjs 抠出 HELP_TEXT");
+  const lines = [...m[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]);
+  const cmds = lines.filter((line) => line.trim().startsWith("/"));
+  assert.ok(cmds.length >= 8, "HELP_TEXT 里应当有一批 /指令 行，实际 " + cmds.length);
+  for (const line of cmds) {
+    const cmd = line.split(/\s+/)[0];
+    assert.ok(SOURCE.includes(cmd), "面板引导必须覆盖 HELP_TEXT 里的指令：" + cmd);
+  }
+  // ③ 引导块在**未绑定**态就可见（它是绑定的理由），且不依赖任何图片资源（可缺省）
+  assert.ok(textHas(guide, "/help"), "命令清单应直接列在引导块里");
+});

package/packages/dsh-remote-web/test/connect-stuck-visibility.test.mjs

@@ -29,10 +29,13 @@ import { chmodSync, existsSync, readFileSync, statSync, utimesSync, writeFileSyn
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { apply } from "../lib/index.js";
 
-const HERE = path.dirname(new URL(import.meta.url).pathname);
+// ⚠️ 必须用 fileURLToPath：Windows 上 `new URL(...).pathname` 得到的是 "/D:/a/..."（带前导斜杠），
+// path.join 之后会拼成 "D:\\D:\\a\\..." → ENOENT。CI 的 Windows 专项就死在这条上。
+const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SETUP_SRC = readFileSync(path.join(HERE, "..", "..", "..", "dsh-setup.mjs"), "utf8");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/packages/dsh-remote-web/test/diag-report.test.mjs

@@ -13,10 +13,13 @@ import { readFileSync, rmSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { apply } from "../lib/index.js";
 
-const HERE = path.dirname(new URL(import.meta.url).pathname);
+// ⚠️ 必须用 fileURLToPath：Windows 上 `new URL(...).pathname` 得到的是 "/D:/a/..."（带前导斜杠），
+// path.join 之后会拼成 "D:\\D:\\a\\..." → ENOENT。CI 的 Windows 专项就死在这条上。
+const HERE = path.dirname(fileURLToPath(import.meta.url));
 const readOrEmpty = async (p) => { try { return await readFile(p, "utf8"); } catch { return ""; } };
 
 /** 假反馈服务：只收 /api/feedback 与 /api/feedback/:id/replies（与企业端契约同构）。 */

package/packages/dsh-remote-web/test/harness-restart.test.mjs

@@ -247,7 +247,11 @@ test("重启实现：被 launchd 托管 → 交回监管者（kickstart -k，pid
     const { host, base } = await serve(routes);
     try {
       const body = await (await fetch(`${base}/dsh-remote/harness/restart`, { method: "POST" })).json();
-      if (process.platform !== "darwin") {
+      // ⚠️ 判据必须与**被测代码**同源：插件用 osPlatform() = `DSH_RELAY_PLATFORM || process.platform`
+      //    （CI 里显式声明了 darwin，好让结果不随 runner 变），而本用例以前只看 process.platform
+      //    → Linux runner 上「代码走 launchd、用例却断言 relaunch」→ 红。两处判据一致才不会打架。
+      const effectivePlatform = process.env.DSH_RELAY_PLATFORM || process.platform;
+      if (effectivePlatform !== "darwin") {
         assert.equal(body.mode, "relaunch", "非 macOS 不检测 launchd");
       } else {
         assert.equal(body.mode, "launchd");

package/packages/dsh-remote-web/test/installer-cli.test.mjs

@@ -71,7 +71,7 @@ test("参数拼错：明确报错、退出码 1、也不落盘", async () => {
 });
 
 test("源码级：用法文本只有一处实现（避免提前退出与末尾分派两处漂移）", () => {
-  const src = fs.readFileSync(SETUP, "utf8");
+  const src = fs.readFileSync(SETUP, "utf8").replace(/\r\n/g, "\n"); // CRLF 检出时源码锚点失配
   const hits = src.match(/dsh-remote — 手机远程控制 dsh web/g) || [];
   assert.equal(hits.length, 1, "用法文案应只出现一次（共用 printHelp()）");
   assert.match(src, /function printHelp\(\)/, "应有 printHelp()");

package/packages/dsh-remote-web/test/launchd-domain.test.mjs

@@ -178,3 +178,29 @@ test("★ watcher 退出前必须确保子进程真的死了（只『请』不
   assert.match(tail, /bridgeProc\.exitCode === null/, "判活要用 exitCode（已退出就别再杀）");
   assert.match(src, /function looksLikeBridge\(pid\)/, "应有 looksLikeBridge 供回收前校验命令行");
 });
+
+test("★ 守护惊群：启动锁必须排在去重读取**之前**，且先写 pid 再释放锁", () => {
+  // 2026-09-26 真机事故：一次重启窗口里同时活下来 6 个 `dsh-setup.mjs run` + 6 个 bridge，
+  // 全部用同一 deviceId 抢 router 注册（日志刷满 `replaced by new connection`），隧道无限抖动。
+  // 成因：去重是"先读 pid 文件、后写 pid 文件"，N 个实例同时启动时每个都读到"没有别人"。
+  const rb = src.slice(src.indexOf("async function runBridge()"), src.indexOf("// ---------- setup"));
+  const iLock = rb.indexOf("tryAcquireSpawnLock()");
+  const iRead = rb.indexOf("const other = readPidFile(WATCHER_PID_FILE)");
+  assert.ok(iLock > 0, "runBridge 必须有启动锁");
+  assert.ok(iRead > 0, "找不到去重读取点");
+  assert.ok(iLock < iRead, "🔴 抢锁必须在读 pid 文件之前，否则惊群照旧");
+  assert.match(rb, /writePidFile\(WATCHER_PID_FILE, process\.pid\);\s*\n\s*releaseSpawnLock\(\);/,
+    "🔴 必须先把自己的 pid 落盘再释放锁 —— 否则'释放 → 1373 行才写'之间又是一个空窗");
+  assert.match(rb, /另一个守护正在启动（启动锁被占用）/, "抢不到锁的实例必须让位并留下可诊断的日志");
+});
+
+test("★ 启动锁：必须是排他创建 + 带陈旧可抢占（绝不能让一把残留锁把 bridge 永久挡在门外）", () => {
+  const fn = src.slice(src.indexOf("function tryAcquireSpawnLock()"), src.indexOf("function releaseSpawnLock()"));
+  assert.match(fn, /openSync\(f, "wx"\)/, "必须用 wx 排他创建（原子的'要么拿到要么没有'）");
+  assert.match(fn, /SPAWN_LOCK_STALE_MS/, "必须有陈旧阈值");
+  assert.match(fn, /!pidAlive\(pid\)/, "持锁进程已死 → 视为陈旧，可抢占");
+  assert.match(fn, /fs\.rmSync\(f, \{ force: true \}\)/, "陈旧锁必须被清掉再抢");
+  const rel = src.slice(src.indexOf("function releaseSpawnLock()"), src.indexOf("// ---------- run："));
+  assert.match(rel, /owner === process\.pid/, "只删自己那把锁（别把接管者的锁删了）");
+  assert.match(src, /XPC_SERVICE_NAME/, "被监管者要能等到锁（它必须能接管）");
+});

package/packages/dsh-remote-web/test/picker-pin.test.mjs

@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
 
 import {
   __pinBrowseDirectoryPicker,
+  __schedulePickerPin,
   __pickerPinState,
   __PICKER_AUTO_ENTRY_ID,
   __PICKER_AUTO_PACKAGE,
@@ -188,8 +189,37 @@ test("诊断面板必须显示目录选择器状态(这类'按钮没反应'才
   assert.match(SRC, /系统原生（远程时对话框弹在电脑那台机器上/, "原生时要给出可操作的解释");
 });
 
-test("接线:apply 里挂了选择器固定（eff/effect），并且是 fire-and-forget 不阻塞装载", () => {
-  assert.match(SRC, /ctx\.effect\(\(\) => \{[\s\S]{0,200}?pinBrowseDirectoryPicker\(ctx\)[\s\S]{0,120}?\}, "dsh-remote-web: pin browser directory picker"\);/);
+test("接线:apply 挂的是**延后**接线（schedulePickerPin），绝不在启动期直接切 Loader", () => {
+  // 🔴 2026-09-26 事故锁：旧实现是 apply() 里直接 `pinBrowseDirectoryPicker(ctx)`，
+  //    于是 dsh 还在装配插件图时就去 loader.remove/create → dsh-client-modules 反复 compose
+  //    整张前端图（buildCombo/newlineCount/identitySectionMap 热点）→ dsh web 3 分钟不监听、
+  //    表现为假死。DSH_REMOTE_NATIVE_PICKER=1 能立刻恢复，正是这条链的证据。
+  assert.match(SRC, /ctx\.effect\(\(\) => schedulePickerPin\(ctx\), "dsh-remote-web: pin browser directory picker"\);/,
+    "apply 必须走延后接线");
+  assert.ok(!/ctx\.effect\(\(\) => \{[\s\S]{0,200}?pinBrowseDirectoryPicker\(ctx\)/.test(SRC),
+    "apply() 里不得再直接调用 pinBrowseDirectoryPicker —— 那正是启动假死的成因");
+});
+
+test("延后闸门:必须等宿主 listen（boundWebPort）并静置，且只在 native 时换一次", () => {
+  const fn = SRC.slice(SRC.indexOf("function schedulePickerPin"), SRC.indexOf("export function apply"));
+  assert.ok(fn.length > 400, "找不到 schedulePickerPin 的实现");
+  assert.match(fn, /boundWebPort\(\) > 0/, "必须先等宿主 HTTP 服务 listen 起来（‘宿主已启动’最可靠的信号）");
+  assert.match(fn, /PICKER_PIN_SETTLE_MS/, "listen 之后必须静置，避开首轮 client-module compose");
+  assert.match(fn, /kind !== "native"/, "只有认得出是 native 才换");
+  assert.match(fn, /attempts: 1, gapMs: 0/, "只换一次，不再轮询（避免反复触发 compose）");
+  // 认不出/超时一律保留原生，绝不动 Loader
+  assert.match(fn, /action: "skipped"/, "认不出时必须优雅跳过");
+});
+
+test("延后接线可取消(ctx.effect 清理)：返回取消函数且取消后不再动作", async () => {
+  const loader = { store: {}, removed: [], created: [], async remove(id) { this.removed.push(id); }, async create(o) { this.created.push(o); return "id"; }, ctx: {} };
+  const ctx = { get: (n) => (n === "loader" ? loader : null), logger: {} };
+  const cancel = __schedulePickerPin(ctx);
+  assert.equal(typeof cancel, "function", "必须返回可取消的清理函数（宿主随时可能关掉我们）");
+  cancel();
+  await new Promise((r) => setTimeout(r, 30));
+  assert.deepEqual(loader.removed, [], "取消后不得动 Loader");
+  assert.deepEqual(loader.created, [], "取消后不得动 Loader");
 });
 
 test("回归锁:源码里不得再出现「先建 browse、后摘 auto」的顺序（0.6.14 的坏版本）", () => {