@mrrisega/dsh-remote 0.6.3 → 0.6.4-beta.10

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

@@ -11,12 +11,19 @@
 //     彻底卸载=profile 插件清理（uninstallSelf）+ 运行时清理（uninstallRuntime：停 bridge 自启动 /
 //     删 plist|unit / 杀残留进程 / 清空配置目录 ~/.dsh-remote），0.4.7 起回归真正「未安装」状态
 //   - 运行时自愈：缺运行环境自动后台安装、登录后自动拉起 bridge（0.4.2 起）
+//   - 登录后自动闭环（0.6.4）：GET /dsh-remote/bridge-status 下发连接阶段
+//     （no_account/no_runtime/installing/starting/connecting/online/error），并在返回前自动补装运行环境、
+//     拉起 bridge、清理卡死标记（带退避）；区分「bridge 进程在跑」与「设备已在中继注册成功（online）」。
+//     面板用 2~3s 短轮询自动推进到 online（无需点按钮/刷新页面），error 才给重试与诊断信息；
+//     另 POST /dsh-remote/connect/retry 手动重试、POST <api>/api/install-report 上报安装口径
+//     （install_source/version + host_os/arch，详见 installSourceOf）。
 //   - 0.1.2+ ?token 浏览器鉴权会话代持（0.4.1 起）
 //
 // 不依赖任何第三方包：只使用 node 内置模块与 cordis 注入的 webServer 服务。
-import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync, accessSync, chmodSync, openSync, closeSync, rmSync, statSync, constants as fsConstants } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync, accessSync, chmodSync, openSync, closeSync, readSync, fstatSync, rmSync, statSync, constants as fsConstants } from "node:fs";
 import { join, dirname, sep } from "node:path";
 import { execSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { homedir, platform } from "node:os";
 import { fileURLToPath } from "node:url";
 
@@ -222,9 +229,20 @@ function applySaaSMode(cfg) {
  * 老版本(无该鉴权)下 connection 服务没有 authenticatedUrl → 静默跳过,行为不变。
  */
 const HARNESS_COOKIE_FILE = ".harness-cookie.json";
+/**
+ * 手机端 401「dsh web authentication required; reopen the URL printed by dsh web」的根因就在这里：
+ * 该 Cookie 由本插件在进程内经 ?token= 换取后交给 bridge 代持，**dsh web 每次重启都会换签名密钥**，
+ * 旧 Cookie 立即失效。旧实现只在启动后重试 20 次(约 60s)就放弃、之后 6 小时才刷新一次 ——
+ * 一旦启动那一刻 connection 服务还没就绪（或用户按引导重启 harness 后插件先于服务就绪），
+ * Cookie 就会长时间不可用，手机端看到那段英文提示且**无法自行恢复**（他打不开电脑上打印的 URL）。
+ * 现在改为：① 启动后持续重试 10 分钟；② 每 30 分钟主动刷新；③ 面板每次查状态时按需补齐；
+ * ④ bridge 撞到 401 会写「作废」标记，插件下次查状态立即重取。四处叠加后用户无需任何操作。
+ */
 const HARNESS_AUTH_RETRY_MS = 3000;
-const HARNESS_AUTH_RETRY_MAX = 20; // 最多约 60s 等 connection 服务就绪
-const HARNESS_AUTH_REFRESH_MS = 6 * 3600 * 1000;
+const HARNESS_AUTH_RETRY_WINDOW_MS = 10 * 60 * 1000; // 持续尝试 10 分钟,不再 60s 后放弃
+const HARNESS_AUTH_REFRESH_MS = 30 * 60 * 1000;      // 主动刷新周期(本地一次 fetch,成本可忽略)
+const HARNESS_COOKIE_STALE_MS = 30 * 60 * 1000;      // 超过视为陈旧 → 按需重取
+const HARNESS_COOKIE_REVOKED_FILE = ".harness-cookie-revoked"; // bridge 撞 401 时写的标记
 
 /** 读取响应里的 set-cookie(兼容 getSetCookie / get 两种实现)。 */
 function setCookieOf(res) {
@@ -264,24 +282,63 @@ async function mintHarnessCookie(ctx, relayDir) {
   }
 }
 
-/** 后台调度:启动重试直到换取成功,成功后每 6h 刷新(与插件生命周期同进退)。 */
+/** 读取当前 Cookie 文件状态:{cookie, authority, mintedAt} 或 null。 */
+function readHarnessCookie(relayDir) {
+  try {
+    const j = JSON.parse(readFileSync(join(relayDir, HARNESS_COOKIE_FILE), "utf8"));
+    return j && typeof j.cookie === "string" && j.cookie ? j : null;
+  } catch {
+    return null;
+  }
+}
+
+let harnessMintInflight = false;
+let harnessMintLastAt = 0;
+
+/**
+ * 按需确保 Cookie 可用(去重 + 限频):
+ *   缺失 / 超过 HARNESS_COOKIE_STALE_MS / bridge 写了作废标记 → 重取一次。
+ * 被 /dsh-remote/status 与 /dsh-remote/bridge-status 调用(面板轮询 2.5~30s),
+ * 因此只要面板开着,手机端 401 会在秒级内自愈;不需要用户做任何事。
+ * @param {object} ctx cordis 上下文
+ * @param {string} relayDir 配置目录
+ * @param {{force?: boolean}} [opts]
+ * @returns {Promise<boolean>} 本次是否确认 Cookie 可用
+ */
+async function ensureHarnessCookie(ctx, relayDir, opts) {
+  const force = !!(opts && opts.force);
+  const revoked = existsSync(join(relayDir, HARNESS_COOKIE_REVOKED_FILE));
+  if (!force && !revoked) {
+    const cur = readHarnessCookie(relayDir);
+    if (cur && Date.now() - Number(cur.mintedAt || 0) < HARNESS_COOKIE_STALE_MS) return true;
+  }
+  if (harnessMintInflight) return false;              // 去重:同一时刻只换一次
+  if (Date.now() - harnessMintLastAt < 5000) return false; // 限频:5s 内不重复换
+  harnessMintInflight = true;
+  harnessMintLastAt = Date.now();
+  try {
+    const ok = await mintHarnessCookie(ctx, relayDir);
+    if (ok || revoked) {
+      try { rmSync(join(relayDir, HARNESS_COOKIE_REVOKED_FILE), { force: true }); } catch { /* ignore */ }
+    }
+    if (!ok && revoked) console.warn("[dsh-remote-web] 浏览器会话 Cookie 已被 dsh web 作废,重取失败,下次查状态再试");
+    return ok;
+  } finally {
+    harnessMintInflight = false;
+  }
+}
+
+/** 后台调度:启动后持续重试(10 分钟窗口) + 每 30 分钟主动刷新(与插件生命周期同进退)。 */
 function scheduleHarnessMint(ctx, relayDir) {
-  let succeeded = false;
-  let retries = 0;
-  const attempt = async () => {
-    if (succeeded) return;
-    if (await mintHarnessCookie(ctx, relayDir)) succeeded = true;
-  };
+  const startedAt = Date.now();
   const bootIv = setInterval(() => {
-    if (succeeded || ++retries > HARNESS_AUTH_RETRY_MAX) {
-      clearInterval(bootIv);
-      return;
-    }
-    void attempt();
+    if (Date.now() - startedAt > HARNESS_AUTH_RETRY_WINDOW_MS) { clearInterval(bootIv); return; }
+    void ensureHarnessCookie(ctx, relayDir, { force: true }).catch(() => {});
   }, HARNESS_AUTH_RETRY_MS);
   bootIv.unref?.();
+  void ensureHarnessCookie(ctx, relayDir, { force: true }).catch(() => {}); // 立刻来一次
   const refreshIv = setInterval(() => {
-    void mintHarnessCookie(ctx, relayDir).catch(() => {});
+    void ensureHarnessCookie(ctx, relayDir).catch(() => {});
   }, HARNESS_AUTH_REFRESH_MS);
   refreshIv.unref?.();
   return () => {
@@ -371,6 +428,10 @@ function manualStatus() {
   })();
   const watcher = [];
   const bridge = [];
+  // 全部 bridge 子进程（含 launchd 托管链里的）：连接阶段判定「bridge 进程真的在跑」用它。
+  // launchd 作业本身跑的是 watcher（dsh-setup.mjs run），它再拉起 dsh-bridge.mjs 子进程——
+  // 只看 launchd.running 会把「watcher 在、bridge 子进程没起来」误判成「进程在跑」。
+  const allBridge = [];
   // 取候选进程的父 pid，判断是否属于 launchd 托管链
   const parentOf = (pid) => {
     const r = sh(`ps -o ppid= -p ${pid}`);
@@ -383,11 +444,17 @@ function manualStatus() {
     if (!m) continue;
     const pid = Number(m[1]);
     if (pid === process.pid || pid === launchdPid) continue;
-    if (launchdPid !== null && parentOf(pid) === launchdPid) continue; // launchd 托管的 bridge 子进程
-    if (/dsh-setup\.mjs/.test(m[2])) watcher.push(pid);
-    else if (/dsh-bridge\.mjs/.test(m[2])) bridge.push(pid);
+    const launchdManaged = launchdPid !== null && parentOf(pid) === launchdPid;
+    if (/dsh-setup\.mjs/.test(m[2])) {
+      if (!launchdManaged) watcher.push(pid);
+      continue;
+    }
+    if (/dsh-bridge\.mjs/.test(m[2])) {
+      allBridge.push(pid);
+      if (!launchdManaged) bridge.push(pid); // launchd 托管的 bridge 子进程（原语义：不计入 manual.bridge）
+    }
   }
-  return { watcher, bridge };
+  return { watcher, bridge, allBridge };
 }
 
 // ---------- 插件市场一键全功能：缺桌面运行环境时自动后台安装 dsh-remote ----------
@@ -395,6 +462,13 @@ function manualStatus() {
 const PROVISION_MARKER = ".dsh-setup-installing";
 const AUTO_INSTALL_LOG = ".dsh-setup-install.log";
 const STALE_MARKER_MS = 30 * 60 * 1000; // 超过该时长视为上次进程残留，插件启动时清理
+/**
+ * 「本次运行环境是插件自愈补装的」记录文件（install_source 判据）：
+ * 插件市场只装面板插件时，桌面运行环境由插件后台 `npx @mrrisega/dsh-remote` 补上，
+ * 这条路径归为 install_source=plugin_market；由用户自己跑安装器的（plist 里带
+ * DSH_BRIDGE_INSTALL_SOURCE=npx）归为 npx。见 installSourceOf()。
+ */
+const PROVISIONED_MARKER = ".dsh-provisioned-by-plugin";
 /**
  * 自愈 watcher 轮询间隔（默认 12s）。DSH_RELAY_SELFHEAL_MS 可覆盖——仅供测试把
  * 崩溃循环自愈链路压到亚秒级验证，生产不必设置。调用时读取（而非模块加载时固定），
@@ -436,19 +510,35 @@ function ensureRuntime(relayDir) {
     const log = join(relayDir, AUTO_INSTALL_LOG);
     const child = spawn(npxCommand(), ["--yes", UPDATE_SPEC], {
       detached: true,
-      env: spawnEnv({ npm_config_registry: "https://registry.npmjs.org" }),
+      // DSH_BRIDGE_INSTALL_SOURCE：本机运行环境是插件自愈补的 → 安装器原样透传到 plist/bridge env，
+      // 于是设备行上的 install_source 如实记成 plugin_market（而不是安装器默认的 npx）。
+      env: spawnEnv({ npm_config_registry: "https://registry.npmjs.org", DSH_BRIDGE_INSTALL_SOURCE: "plugin_market" }),
       stdio: ["ignore", openSync(log, "a"), openSync(log, "a")]
     });
     writeMarker(marker, child.pid); // 记 pid：宿主重启后可立即清理死进程残留
+    // 记下「本机运行环境是插件自愈补的」：登录后的 /api/install-report 与 bridge 设备登记
+    // 都据此上报 install_source=plugin_market（区分用户自己跑 npx 安装器的那条路径）。
+    try {
+      writeFileSync(join(relayDir, PROVISIONED_MARKER),
+        JSON.stringify({ at: Date.now(), version: PLUGIN_VERSION, source: "plugin_market" }));
+    } catch { /* 非关键：上报时按缺省判据降级 */ }
     const clear = () => { try { rmSync(marker, { force: true }); } catch { /* ignore */ } };
+    // 匿名遥测：补装生命周期（install_started → runtime_ready / install_failed(fail_code)）。
+    // 失败原因只归类到白名单 fail_code，绝不外发原始错误文本（可能含路径/主机名/用户名）。
+    const tb = telemetryBook(relayDir);
+    tb.installStartedAt = Date.now();
+    telemetryRecord(relayDir, "install_started");
     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)) });
     });
     child.on("error", (e) => {
       clear();
       appendLogLine(relayDir, AUTO_INSTALL_LOG, `[auto-install] 启动失败: ${e.message}`);
       console.warn(`[dsh-remote-web] 自动安装子进程启动失败: ${e.message}`);
+      telemetryRecord(relayDir, "install_failed", { fail_code: telemetryFailCodeFromError(e) });
     });
     child.unref();
     console.log(`[dsh-remote-web] 检测到缺少桌面运行环境,已在后台自动安装(日志: ${log}),完成后将自动启动 bridge`);
@@ -456,6 +546,7 @@ function ensureRuntime(relayDir) {
   } catch (e) {
     console.warn(`[dsh-remote-web] 自动安装启动失败: ${e.message}`);
     try { rmSync(marker, { force: true }); } catch { /* ignore */ }
+    telemetryRecord(relayDir, "install_failed", { fail_code: telemetryFailCodeFromError(e) });
     return false;
   }
 }
@@ -476,7 +567,7 @@ function writeAutostartFile(relayDir) {
   <key>ThrottleInterval</key><integer>10</integer>
   <key>StandardOutPath</key><string>${join(relayDir, ".dsh-bridge.log")}</string>
   <key>StandardErrorPath</key><string>${join(relayDir, ".dsh-bridge.log")}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string></dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string><key>DSH_BRIDGE_INSTALL_SOURCE</key><string>${installSourceOf(relayDir)}</string><key>DSH_BRIDGE_INSTALL_VERSION</key><string>${PLUGIN_VERSION}</string></dict>
 </dict></plist>`;
   mkdirSync(dirname(plistPath), { recursive: true });
   writeFileSync(plistPath, plist, { mode: 0o644 });
@@ -580,12 +671,17 @@ function scheduleRuntime(relayDir) {
       if (!runtimeReady(relayDir)) {
         reapBrokenAutostart(relayDir); // 先摘掉指向不存在脚本的自启动，止住崩溃循环
         ensureRuntime(relayDir);       // 后台 npx 补齐（marker 防重入）；就绪后下一轮自动拉起
+        telemetryRuntimeProbe(relayDir); // 匿名遥测：补装超时归类（runtime_install_timeout）
         return;
       }
+      telemetryRuntimeProbe(relayDir); // 匿名遥测：环境刚补齐 → runtime_ready（每进程一次）
       if (awaitingRestartHint) {
         awaitingRestartHint = false;
-        // 首次安装：运行环境（bridge + 自启动）刚在本进程内补齐 → 提示重启，重启后即完全可用
-        markRestartPending(relayDir, "first-install", "首次安装需要重启 DeepSeek harness");
+        // 运行环境刚在本进程内补齐 —— **不需要重启 harness**：
+        //   · bridge 是独立 launchd 进程，补齐后自愈调度会直接把它拉起；
+        //   · 插件本体走 patch 热加载，装完即生效。
+        // 以前这里会 markRestartPending("first-install") 弹出"需要重启 DeepSeek harness"横幅，
+        // 在热加载落地后已经变成纯粹的误导（用户实测反馈），故移除。
       }
       const cfg = loadConfig(relayDir);
       const hasAcct = Boolean((cfg.phone || cfg.email) && cfg.password) || Boolean(cfg.local_key);
@@ -756,7 +852,10 @@ function writeRestartState(relayDir, state) {
   } catch { /* 写盘失败不致命：面板退化为不提示 */ }
 }
 
-/** 标记「需要重启 DeepSeek harness」。kind: first-install(首次安装) | update(在线更新)。 */
+/**
+ * 标记「需要用户动一下」的状态。kind = refresh(插件被运行时改写,刷新页面即可)。
+ * 历史 kind(first-install / update)已废弃:热加载落地后,装插件与在线更新都不再需要重启 harness。
+ */
 function markRestartPending(relayDir, kind, reason) {
   const cur = readRestartState(relayDir);
   if (cur.pending && cur.kind === kind) return cur; // 幂等：同一原因不反复重写
@@ -788,7 +887,15 @@ function pluginInstalledAfterBoot() {
     const pkgFile = join(dirname(dirname(here)), "package.json");
     const mtimeMs = statSync(pkgFile).mtimeMs;
     const bootMs = Date.now() - process.uptime() * 1000;
-    return mtimeMs > bootMs + 2000;
+    if (!(mtimeMs > bootMs + 2000)) return false;
+    // ⚠️ 只看时间戳会**误报**:安装器补装/在线更新会把同样的文件重写一遍(哪怕是同一个版本),
+    // 时间戳变新 → 被当成"有新插件要装载" → 弹出"需要重启/刷新"横幅(用户实测踩到:
+    // 自愈补装把 profile 副本重写了一次,运行中的旧代码就写下了"需要重启")。
+    // 真正该提示用户的只有一件事:**磁盘上的插件版本与本进程装载的版本不同**。
+    // 版本相同 → 运行中的代码就是目标版本,什么都不用做。
+    const diskVersion = String(JSON.parse(readFileSync(pkgFile, "utf8")).version || "");
+    const runningVersion = String(PLUGIN_VERSION || "");
+    return Boolean(diskVersion && runningVersion && diskVersion !== runningVersion);
   } catch { return false; }
 }
 
@@ -859,6 +966,10 @@ function restartHarness(relayDir, opts = {}) {
     if (unit) { mode = "systemd"; target = unit; }
   }
   const script = buildRestartScript(mode, target, cmd, relayDir);
+  // 匿名遥测：重启 DeepSeek harness（自动倒计时或手动按钮都经这里）——触发一次记一条。
+  // 放在 dry-run 之前：测试/诊断用的 dry-run 也走同一条入口，便于用例锁死这条埋点。
+  telemetryRecord(relayDir, "harness_restart");
+  telemetryFlushSoon(relayDir); // 本进程约 1~2 秒后就会被替换：尽量当下把这条发出去（发不出去留盘上，下次装载补发）
   if (opts.dryRun || process.env.DSH_RELAY_RESTART_DRYRUN === "1") {
     // 测试/诊断用：只返回将要执行的脚本，不做任何真实动作
     return { ok: true, status: "dry-run", mode, target, script, log: join(relayDir, RESTART_LOG_FILE) };
@@ -901,6 +1012,8 @@ async function relayFetch(relayDir, pathname, init) {
   try {
     // 6s 超时：relay 不可达时快速降级，不拖慢面板
     const res = await fetch(url, { ...init, signal: AbortSignal.timeout(6000) });
+    // 企业端拒绝当前 JWT（过期/轮换）→ 立刻让 token 缓存失效，下一次请求重新认证
+    if (res.status === 401 || res.status === 403) invalidateRelayToken(relayDir);
     const text = await res.text();
     let body = null;
     try {
@@ -1014,6 +1127,38 @@ const AUTH_RELAY_NOT_READY = "relay_not_ready";     // 凭证齐全但企业端
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+/**
+ * relay token 短期缓存（60s）：连接阶段的 2~3s 短轮询会反复取 token，若每次都走 device-login
+ * （即账号密码认证），就会**每几秒打一次企业端认证接口**——审计日志刷屏、可能触发限流，且纯属浪费。
+ *   - TTL 60s：远短于 JWT 自身有效期；账号密码/共享密钥变更最多 60s 生效；
+ *   - 键含 api_url + 账号 + 模式：换账号、切自建/云端、换服务端会自动 miss；
+ *   - 并发合并（relayTokenInflight）：同一时刻多个请求共用一次认证；
+ *   - 只缓存成功结果；企业端回 401/403（JWT 过期/轮换）时 relayFetch 立即 invalidateRelayToken。
+ */
+const RELAY_TOKEN_TTL_MS = 60_000;
+const relayTokenCache = new Map();    // relayDir → { key, token, exp, status }
+const relayTokenInflight = new Map(); // relayDir → { key, promise }
+/** 缓存键：同一台机器换了账号/服务端/模式时自动失效，避免把别人的 token 用错地方。 */
+function relayTokenKeyOf(cfg) {
+  return [
+    (cfg.api_url || DEFAULT_API).replace(/\/+$/, ""),
+    cfg.local_key ? "local" : "saas",
+    cfg.local_key ? String(cfg.local_key).slice(0, 8) : (cfg.phone || cfg.email || ""),
+  ].join("|");
+}
+/** 丢弃某 relayDir 的 token 缓存（账号变更、退出登录、企业端拒绝 JWT 时调用）。 */
+function invalidateRelayToken(relayDir) {
+  if (!relayDir) return;
+  relayTokenCache.delete(relayDir);
+  deviceProbeCache.delete(relayDir); // 认证失效时「设备探活」结论同样过期（否则 15s 内不会重试）
+}
+/**
+ * 账号设备表探活缓存（见 accountDeviceBound）：企业端每次 GET /api/devices 都会写一行活跃明细
+ * （user_activity），因此绝不跟着 2.5s 的 UI 轮询打——15s 一次，且只在与中继注册证据缺失时才探。
+ */
+const DEVICE_PROBE_TTL_MS = 15_000;
+const deviceProbeCache = new Map(); // relayDir → { at, value }
+
 /** 单次 device-login：返回 { ok, status, token, code, detail }（不抛错，便于按原因降级/重试）。 */
 async function deviceLoginOnce(api, cfg, secret) {
   try {
@@ -1065,8 +1210,35 @@ async function localLoginOnce(cfg, api) {
  * ③ 网络抖动/5xx 退避重试一次；④ 失败时给出**可判定原因**而非空串（消除“尚未登录”误报）。
  * @returns {Promise<{token:string, reason:string, status:number, detail:string}>}
  */
-async function relayTokenWithReason(relayDir, cfgOverride) {
+async function relayTokenWithReason(relayDir, cfgOverride, opts = {}) {
   const cfg = cfgOverride && typeof cfgOverride === "object" ? { ...loadConfig(relayDir), ...cfgOverride } : loadConfig(relayDir);
+  const key = relayTokenKeyOf(cfg);
+  const now = Date.now();
+  const hit = relayTokenCache.get(relayDir);
+  if (!opts.force && hit && hit.key === key && hit.token && now < hit.exp) {
+    return { token: hit.token, reason: "", status: hit.status || 200, detail: "", cached: true };
+  }
+  // 并发合并：同一时刻的多个请求（状态轮询 / 二维码 / 设备列表 / 上报）共用一次认证
+  const flying = relayTokenInflight.get(relayDir);
+  if (!opts.force && flying && flying.key === key) return flying.promise;
+  const promise = relayTokenUncached(relayDir, cfg, cfgOverride).then((res) => {
+    if (res && res.token) {
+      relayTokenCache.set(relayDir, { key, token: res.token, exp: Date.now() + RELAY_TOKEN_TTL_MS, status: res.status || 200 });
+    } else {
+      relayTokenCache.delete(relayDir); // 失败不缓存：下一轮立刻重试
+    }
+    relayTokenInflight.delete(relayDir);
+    return res;
+  }, (e) => {
+    relayTokenInflight.delete(relayDir);
+    throw e;
+  });
+  relayTokenInflight.set(relayDir, { key, promise });
+  return promise;
+}
+
+/** 未缓存的真实取 token 逻辑（relayTokenWithReason 的缓存/合并外壳在这里之上一层）。 */
+async function relayTokenUncached(relayDir, cfg, cfgOverride) {
   const api = (cfg.api_url || DEFAULT_API).replace(/\/+$/, "");
   if (cfg.local_key) {
     let r = await localLoginOnce(cfg, api);
@@ -1470,6 +1642,10 @@ async function composeStatus(relayDir) {
     // 是否需要重启 DeepSeek harness（首次安装 / 在线更新后必须重启才加载插件本体）：
     // {pending, kind: first-install|update, reason, at}，供面板顶部醒目提示 + 重启按钮。
     restart: readRestartState(relayDir),
+    // 连接阶段（登录后自动闭环：环境 → bridge 进程 → 设备已在中继注册）：
+    // 面板用它显示「正在准备运行环境…/正在启动 Bridge…/正在连接中继…/已连接 ✅」，
+    // 并用 /dsh-remote/bridge-status 以 2~3s 短轮询自动推进（无需用户点按钮或刷新页面）。
+    connect: await composeConnect(relayDir, { cfg, launchd, manual }),
     // 隐私审计(2026-09):不再下发真实 hostname(移除 host 字段)——设备标识统一走 deviceId/服务端登记名
   };
 }
@@ -1577,7 +1753,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.3";
+const PLUGIN_VERSION = "0.6.4-beta.10";
 const UPDATE_LOG = ".dsh-update.log";
 const UPDATE_MARKER = ".dsh-update-running";
 
@@ -1608,7 +1784,9 @@ function spawnUpdater(relayDir, extraEnv) {
   return spawn(npxCommand(), ["--yes", UPDATE_SPEC], {
     detached: true,
     cwd: homedir(),
-    env: spawnEnv(extraEnv), // PATH 补 node 目录：App 最小 PATH 下也能跑 npx
+    // PATH 补 node 目录：App 最小 PATH 下也能跑 npx；同时保持本机既有的安装来源口径
+    // （在线更新会重跑安装器并重写 plist，若不带来源就会把 plugin_market 误记成 npx）。
+    env: spawnEnv({ DSH_BRIDGE_INSTALL_SOURCE: installSourceOf(relayDir), ...(extraEnv || {}) }),
     stdio: ["ignore", openSync(log, "a"), openSync(log, "a")]
   });
 }
@@ -1628,6 +1806,7 @@ function runOnlineUpdate(relayDir) {
     const marker = join(relayDir, UPDATE_MARKER);
     if (existsSync(marker)) return { ok: false, detail: "已有更新在进行中，请稍候" };
     appendLogLine(relayDir, UPDATE_LOG, `[update] 开始在线更新 ${UPDATE_SPEC} (${new Date().toISOString()})`);
+    telemetryRecord(relayDir, "update_started"); // 匿名遥测：在线更新开始
 
     let retried = false;
     const clear = () => { try { rmSync(marker, { force: true }); } catch { /* ignore */ } };
@@ -1644,12 +1823,17 @@ function runOnlineUpdate(relayDir) {
         }
         appendLogLine(relayDir, UPDATE_LOG, `[update] npx 退出 code=${code ?? "?"}（${retried ? "默认源" : "官方源"}）`);
         clear();
-        // 在线更新改写了插件/运行环境文件 → 必须重启 DeepSeek harness 才装载新版本
-        if (code === 0) markRestartPending(relayDir, "update", "已在线更新，需要重启 DeepSeek harness 生效");
+        // 在线更新改写了插件/运行环境文件 → 版本对不上时由 pluginInstalledAfterBoot() 自动识别，
+        // 面板会提示"刷新页面"。这里**不再**写"需要重启 DeepSeek harness"的待重启标记：
+        // 插件走 patch 热加载、bridge 是独立进程，重启 harness 已无必要（用户实测反馈）。
+        // 成功不发事件（update_started 已发过，失败才发 update_failed；白名单里没有 update_done，
+        // 硬发只会被服务端静默丢弃）。
+        if (code !== 0) telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromText(readTail(join(relayDir, UPDATE_LOG))) });
       });
       child.on("error", (e) => {
         appendLogLine(relayDir, UPDATE_LOG, `[update] 子进程启动失败: ${e.message}`);
         clear();
+        telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromError(e) });
       });
       child.unref();
       return child;
@@ -1658,6 +1842,7 @@ function runOnlineUpdate(relayDir) {
     return { ok: true, pid: child.pid, log: join(relayDir, UPDATE_LOG) };
   } catch (e) {
     try { rmSync(join(relayDir, UPDATE_MARKER), { force: true }); } catch { /* ignore */ }
+    telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromError(e) });
     return { ok: false, detail: String(e.message || e) };
   }
 }
@@ -1714,6 +1899,935 @@ function uninstallSelf(relayDir, profileDir, patchFile, pkgFile) {
 // ---------- 路由 ----------
 
 /** 路由表：{method, path, handler}。 */
+// ---------- 登录后自动闭环：连接阶段（运行环境 → bridge 进程 → 设备已在中继注册=online） ----------
+
+/**
+ * 生产现场（2026-09，id 42~52 共 11 个真实注册用户）：7 人注册后手机端 /api/devices 一直是空列表，
+ * 多人反复点「生成访问链接」（auth.key_create 10~23 次）而 device.bind 始终为 0——他们的电脑端
+ * bridge 从未连上过中继。典型路径：注册 → 手机端拿不到设备 → 反复轮询 → 放弃。
+ *
+ * 缺口不是某个按钮坏了，而是「登录 → 设备已在中继注册成功」这条链路既不可见也不自动：
+ * 用户看不出卡在哪一步（运行环境没装？bridge 没起？还是没注册上中继？），也不知道要不要刷新页面。
+ *
+ * 本段把链路拆成可查询的阶段（GET /dsh-remote/bridge-status），并刻意区分两个极易混淆的状态：
+ *   - starting ：「bridge 进程已在跑」——只说明进程起来了；
+ *   - online   ：「设备已在中继注册成功」——手机端能看到并进入这台电脑，这才是用户要的「能用了」。
+ * 阶段推进所需的动作（补装运行环境 / 拉起 bridge / 可重试错误退避重试）全部由 ensureConnection
+ * 在轮询里自动完成，用户零操作、零刷新；只有「彻底失败」才给按钮，且永远留一条可走的路。
+ */
+const BRIDGE_LOG_FILE = ".dsh-bridge.log";
+const BRIDGE_STATE_FILE = ".dsh-bridge-state.json";
+const BIND_ERROR_FILE = ".bind-error.json";
+/** 安装标记超时（进程已死或超 10 分钟）→ 视为卡死，清掉标记重新补装（否则 marker 会把补装永久挡住）。 */
+const INSTALL_STALE_MS = 10 * 60 * 1000;
+/** 设备登记失败提示只在一小时内当作「当前故障」（.bind-error.json 是持久文件，成功时才被清掉）。 */
+const BIND_ERROR_FRESH_MS = 60 * 60 * 1000;
+/** 自动重试退避（毫秒）：可重试错误按此节奏自动重试，用尽后停在 60s（仍会自动重试，不出现死胡同）。 */
+const CONNECT_BACKOFF_MS = [2000, 4000, 8000, 16_000, 30_000, 60_000];
+
+/** 连接阶段文案（面向非技术用户；node 半算好，面板直接显示，避免两端各写一套）。 */
+const CONNECT_TEXT = {
+  no_account: "请先登录手机号账号（下方「🔑 账号」卡片），登录后会自动完成剩余步骤",
+  no_runtime: "正在准备运行环境（首次约 1~2 分钟）…",
+  installing: "正在准备运行环境（首次约 1~2 分钟）…",
+  starting: "正在启动 Bridge…",
+  connecting: "正在连接中继…",
+  online: "已连接 ✅ 现在可以用手机扫码访问",
+  error: "连接失败，请按下方提示处理",
+};
+const CONNECT_PHASES = ["no_account", "no_runtime", "installing", "starting", "connecting", "online", "error"];
+
+/** 每个 relayDir 的连接状态簿（尝试次数 / 退避 / 上报节流）：放内存，进程重启即重置。 */
+const connectBooks = new Map();
+function connectBook(relayDir) {
+  let b = connectBooks.get(relayDir);
+  if (!b) {
+    b = { attempts: 0, lastAttemptAt: 0, reportAt: 0 };
+    connectBooks.set(relayDir, b);
+  }
+  return b;
+}
+/** 已尝试 attempts 次后的退避时长。 */
+function connectBackoffMs(attempts) {
+  const i = Math.min(Math.max(attempts, 0), CONNECT_BACKOFF_MS.length - 1);
+  return CONNECT_BACKOFF_MS[i];
+}
+/** 本机是否已有可用账号凭据（SaaS 账号或自建访问密钥）——没有就谈不上自动连接，先引导登录。 */
+function hasAccountCreds(cfg) {
+  return Boolean((cfg.phone || cfg.email) && cfg.password) || Boolean(cfg.local_key);
+}
+
+/** 读文件尾部（日志可能很长，只取末尾用于判定最近一次连接结果）。 */
+function readTail(filePath, maxBytes = 64 * 1024) {
+  try {
+    const fd = openSync(filePath, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const start = Math.max(0, size - maxBytes);
+      const buf = Buffer.alloc(size - start);
+      readSync(fd, buf, 0, buf.length, start);
+      return buf.toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch { return ""; }
+}
+
+/** 读取 bridge 写的状态文件（新版 bridge 会写；旧版没有 → 走日志/账号兜底判据）。 */
+function bridgeStateFile(relayDir) {
+  try {
+    const j = JSON.parse(readFileSync(join(relayDir, BRIDGE_STATE_FILE), "utf8"));
+    return j && typeof j === "object" ? j : null;
+  } catch { return null; }
+}
+
+/**
+ * 从 bridge 日志尾部判定「最近一次连接是否注册成功」。
+ * 依据 dsh-bridge.mjs 的既有输出：`✅ 设备已登记到账号` / `✅ router 注册成功`；
+ * 出现新一轮连接（`隧道已连`）或登记失败/拒绝时，之前那次成功不再代表当前状态。
+ */
+function bridgeLogState(relayDir) {
+  const tail = readTail(join(relayDir, BRIDGE_LOG_FILE));
+  if (!tail) return { tunnelRegistered: false, accountBound: false, lastError: "" };
+  let tunnelRegistered = false;
+  let accountBound = false;
+  let lastError = "";
+  for (const raw of tail.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/✅\s*router 注册成功/.test(line)) { tunnelRegistered = true; lastError = ""; continue; }
+    if (/✅\s*设备已登记到账号/.test(line)) { accountBound = true; lastError = ""; continue; }
+    if (/隧道已连|\[dsh-remote\] dsh web 在线，启动 bridge|bridge 退出/.test(line)) {
+      tunnelRegistered = false;
+      accountBound = false;
+      continue;
+    }
+    if (/拒绝注册|注册发送失败|设备登记失败|无法连接账号 API|设备数已达上限/.test(line)) {
+      tunnelRegistered = false;
+      accountBound = false;
+      lastError = line.slice(0, 300);
+    }
+  }
+  return { tunnelRegistered, accountBound, lastError };
+}
+
+/** 读取设备登记失败提示（bridge 在 409/网络失败时写 .bind-error.json）。 */
+function readBindError(relayDir) {
+  try {
+    const f = join(relayDir, BIND_ERROR_FILE);
+    if (!existsSync(f)) return null;
+    const j = JSON.parse(readFileSync(f, "utf8"));
+    return j && typeof j === "object" ? j : null;
+  } catch { return null; }
+}
+
+/** 运行环境安装状态：installing=安装子进程在跑；stale=标记超时/进程已死（可清掉重来）。 */
+function installStateOf(relayDir) {
+  const marker = join(relayDir, PROVISION_MARKER);
+  if (!existsSync(marker)) return { installing: false, stale: false, at: 0 };
+  const info = readMarkerInfo(marker) || {};
+  const at = Number(info.at) || 0;
+  const pidDead = info.pid ? pidAlive(Number(info.pid)) === false : false;
+  const stale = pidDead || (at > 0 && Date.now() - at > INSTALL_STALE_MS);
+  return { installing: !stale, stale, at };
+}
+
+/** 清掉卡死的安装标记（下轮 ensureRuntime 才能重新拉起补装）。 */
+function clearStaleInstallMarker(relayDir) {
+  try {
+    rmSync(join(relayDir, PROVISION_MARKER), { force: true });
+    appendLogLine(relayDir, AUTO_INSTALL_LOG, "[dsh-remote-web] 清理卡死的安装标记（安装进程已退出或超时），将重新补装运行环境");
+    return true;
+  } catch { return false; }
+}
+
+/** 账号设备表里是否已登记本机 device_id（手机端 /api/devices 能看到的那一份）+ 节流缓存。 */
+async function accountDeviceBound(relayDir, cfg) {
+  const deviceId = String(cfg.device_id || "");
+  if (!deviceId) return { bound: false, reason: "no_device_id" };
+  const cached = deviceProbeCache.get(relayDir);
+  if (cached && Date.now() - cached.at < DEVICE_PROBE_TTL_MS) return cached.value;
+  const done = (value) => { deviceProbeCache.set(relayDir, { at: Date.now(), value }); return value; };
+  const token = await relayToken(relayDir).catch(() => "");
+  if (!token) return done({ bound: false, reason: "no_token" });
+  const api = (cfg.api_url || DEFAULT_API).replace(/\/+$/, "");
+  try {
+    const r = await fetch(`${api}/api/devices`, {
+      headers: { authorization: `Bearer ${token}`, "x-dsh-client": `dsh-remote-web/${PLUGIN_VERSION}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!r.ok) {
+      if (r.status === 401 || r.status === 403) invalidateRelayToken(relayDir); // JWT 过期/轮换 → 下次重新认证
+      return done({ bound: false, reason: `http_${r.status}` });
+    }
+    const body = await r.json().catch(() => null);
+    const list = Array.isArray(body?.devices) ? body.devices : Array.isArray(body) ? body : [];
+    const bound = list.some((d) => String(d?.id || d?.device_id || "") === deviceId);
+    return done({ bound, reason: bound ? "" : "not_in_list", count: list.length });
+  } catch (e) {
+    return done({ bound: false, reason: `unreachable: ${e.message}` });
+  }
+}
+
+/**
+ * 计算当前连接阶段（纯读，不做任何系统操作）。
+ * 阶段：no_account | no_runtime | installing | starting | connecting | online | error
+ * 判据严格区分「进程在跑」与「已在中继注册」：
+ *   online 需要 bridge 进程在跑 **且** 有中继注册证据（状态文件 > 日志 > 账号设备表）。
+ */
+async function composeConnect(relayDir, opts = {}) {
+  const cfg = opts.cfg || loadConfig(relayDir);
+  const launchd = opts.launchd || launchdStatus();
+  const manual = opts.manual || manualStatus();
+  const book = connectBook(relayDir);
+  const now = Date.now();
+  const hasAcct = hasAccountCreds(cfg);
+  const runtime = runtimeReady(relayDir);
+  const inst = installStateOf(relayDir);
+  const bridgePids = Array.isArray(manual.allBridge) ? manual.allBridge : [];
+  const bridgeRunning = Boolean(launchd.running || bridgePids.length > 0 || (manual.bridge || []).length > 0);
+  const bindError = readBindError(relayDir);
+  const bindFresh = Boolean(bindError && (!bindError.at || now - Number(bindError.at) < BIND_ERROR_FRESH_MS));
+  const log = bridgeLogState(relayDir);
+  const state = bridgeStateFile(relayDir);
+  const deviceId = String(cfg.device_id || "");
+
+  // ── 中继注册证据（只有 bridge 进程在跑时才算「现在能用」） ──
+  let registered = false;
+  let registerSource = "";
+  if (runtime && bridgeRunning) {
+    if (state && state.phase === "online" && Number(state.tunnel_registered_at) > 0) {
+      registered = true; registerSource = "state";
+    } else if (log.tunnelRegistered) {
+      registered = true; registerSource = "tunnel";
+    } else if (state && Number(state.account_bound_at) > 0) {
+      registered = true; registerSource = "state_account";
+    } else if (log.accountBound) {
+      registered = true; registerSource = "account";
+    } else if (hasAcct) {
+      const probe = await accountDeviceBound(relayDir, cfg);
+      if (probe.bound) { registered = true; registerSource = "account_api"; }
+    }
+  }
+
+  let phase;
+  let error = null;
+  let detail = "";
+  let retryable = true;
+  if (UNINSTALLED_DIRS.has(relayDir)) {
+    phase = "error"; retryable = false;
+    error = { code: "uninstalled", message: "本插件已彻底卸载，重启 dsh web 后不再自动启动 bridge" };
+    detail = error.message;
+  } else if (!hasAcct) {
+    phase = "no_account"; retryable = false;
+    detail = "尚未登录账号：登录后会自动补装运行环境 → 启动 bridge → 连接中继，全程无需其他操作。";
+  } else if (!runtime) {
+    if (inst.stale) {
+      phase = "error";
+      error = {
+        code: "install_stuck",
+        message: "运行环境安装没有完成（上次安装进程已退出或超时），已清理残留标记并准备重新安装",
+      };
+      detail = error.message;
+    } else {
+      phase = inst.installing ? "installing" : "no_runtime";
+      detail = inst.installing
+        ? "正在后台安装运行环境（bridge 本体），首次约 1~2 分钟，装完会自动启动。"
+        : "检测到缺少运行环境，正在后台自动安装（首次约 1~2 分钟），无需任何操作。";
+    }
+  } else if (!bridgeRunning) {
+    if (launchd.crashing) {
+      phase = "error";
+      error = {
+        code: "launchd_crash",
+        message: `后台服务反复启动失败（launchd state=${launchd.state || "?"}，lastExit=${launchd.lastExitCode ?? "?"}）`,
+      };
+      detail = "已自动清理失效的自启动项并重新拉起，稍候会自动恢复。";
+    } else if (bindFresh && bindError) {
+      phase = "error";
+      error = { code: bindError.code || "bind_failed", message: bindError.message || "设备登记失败" };
+      detail = "bridge 因设备登记失败退出，已进入自动重试；请按提示处理后重试。";
+    } else {
+      phase = "starting";
+      detail = launchd.running
+        ? "后台服务已启动，正在等待 bridge 进程就绪…"
+        : "正在启动后台服务（bridge），通常几秒内完成，无需任何操作。";
+    }
+  } else if (registered) {
+    phase = "online";
+    detail = registerSource === "account_api" || registerSource === "account" || registerSource === "state_account"
+      ? "设备已登记到你的账号：手机端「设备列表」能看到这台电脑，扫码/打开链接即可进入。"
+      : "bridge 已注册到中继：手机端扫码/打开链接即可进入这台电脑。";
+  } else if (bindFresh && bindError) {
+    phase = "error";
+    error = { code: bindError.code || "bind_failed", message: bindError.message || "设备登记失败" };
+    detail = bindError.code === "device_limit_exceeded"
+      ? "已达本套餐设备数上限：同机重装会自动顶替旧设备；仍失败请到手机端「设备管理」解绑旧设备后点「重试」。"
+      : "请确认网络与账号状态后点「重试」；仍不成功可点「复制诊断信息」发给客服。";
+  } else {
+    phase = "connecting";
+    detail = "bridge 进程已在运行，正在等待设备注册到中继…通常几秒内完成。";
+  }
+
+  const wait = connectBackoffMs(book.attempts);
+  const elapsed = book.lastAttemptAt ? now - book.lastAttemptAt : wait;
+  const autoRetrying = phase !== "online" && phase !== "no_account" && retryable !== false;
+  const nextRetryInMs = autoRetrying ? Math.max(0, wait - elapsed) : 0;
+  const conn = {
+    phase,
+    online: phase === "online",
+    text: CONNECT_TEXT[phase] || "正在连接…",
+    detail,
+    retryable: retryable !== false,
+    deviceId,
+    runtimeReady: runtime,
+    installing: inst.installing,
+    installStale: inst.stale,
+    bridgeRunning,
+    bridgePids,
+    launchdState: launchd.state || "",
+    launchdCrashLoop: Boolean(launchd.crashing),
+    registered,
+    registerSource,
+    attempts: book.attempts,
+    nextRetryInMs,
+    error,
+    bindError: bindFresh && bindError ? { code: bindError.code || "", message: bindError.message || "" } : null,
+    logPath: join(relayDir, BRIDGE_LOG_FILE),
+    installLogPath: join(relayDir, AUTO_INSTALL_LOG),
+  };
+  conn.diagnostics = buildConnectDiagnostics(relayDir, conn, log);
+  return conn;
+}
+
+/** 可复制的诊断信息（面板「复制诊断信息」按钮）：版本 / relayDir / 阶段 / 最近错误 / 进程状态 / 日志路径。 */
+function buildConnectDiagnostics(relayDir, conn, log) {
+  return [
+    "dsh-remote 连接诊断",
+    `插件版本: ${PLUGIN_VERSION}`,
+    `配置目录: ${relayDir}`,
+    `连接阶段: ${conn.phase}（${conn.text}）`,
+    `设备 ID: ${conn.deviceId || "（未生成）"}`,
+    `运行环境: ${conn.runtimeReady ? "已就绪" : "缺失"}${conn.installing ? "（后台安装中）" : ""}${conn.installStale ? "（安装标记已超时）" : ""}`,
+    `bridge 进程: ${conn.bridgeRunning ? "在运行" : "未运行"}（pid=${conn.bridgePids && conn.bridgePids.length ? conn.bridgePids.join(",") : "-"}，launchd state=${conn.launchdState || "-"}，崩溃循环=${conn.launchdCrashLoop ? "是" : "否"}）`,
+    `中继注册: ${conn.registered ? "已注册（" + conn.registerSource + "）" : "未注册"}`,
+    `最近错误: ${conn.error ? conn.error.code + ": " + conn.error.message : (log && log.lastError ? log.lastError : "无")}`,
+    `自动重试: 已尝试 ${conn.attempts} 次${conn.nextRetryInMs ? `，约 ${Math.ceil(conn.nextRetryInMs / 1000)} 秒后重试` : ""}`,
+    `bridge 日志: ${conn.logPath}`,
+    `安装日志: ${conn.installLogPath}`,
+    `时间: ${new Date().toISOString()}`,
+  ].join("\n");
+}
+
+/**
+ * 自动闭环的动作执行（幂等、内部退避）：
+ *   ① 缺运行环境 → ensureRuntime（后台 npx 补装；卡死的安装标记先清掉）；
+ *   ② 不再缺环境但没账号 → 什么都不做（先把登录引导交给 UI）；
+ *   ③ 有账号但 bridge 没在跑 → startBridge（运行环境缺失时它自己会拒绝并转补装）。
+ * 由面板的短轮询驱动（GET /dsh-remote/bridge-status），因此用户在登录后不需要点任何按钮、
+ * 也不需要刷新页面；退避避免失败时把 launchctl/npx 打成风暴。
+ */
+function ensureConnection(relayDir, opts = {}) {
+  if (UNINSTALLED_DIRS.has(relayDir)) return null;
+  const book = connectBook(relayDir);
+  if (opts.force) { book.attempts = 0; book.lastAttemptAt = 0; }
+  const now = Date.now();
+  if (!opts.force && book.lastAttemptAt && now - book.lastAttemptAt < connectBackoffMs(book.attempts)) return null;
+  const cfg = loadConfig(relayDir);
+  if (!hasAccountCreds(cfg)) return null; // 未登录：不补装也不拉服务，先让用户登录
+  if (!runtimeReady(relayDir)) {
+    if (installStateOf(relayDir).stale) clearStaleInstallMarker(relayDir);
+    book.lastAttemptAt = now;
+    book.attempts += 1;
+    ensureRuntime(relayDir);
+    return { action: "provision" };
+  }
+  const launchd = launchdStatus();
+  const manual = manualStatus();
+  if (launchd.running || (manual.allBridge || []).length || (manual.bridge || []).length) {
+    book.attempts = 0; // 进程已在跑：退避计数归零，后续只等注册
+    book.lastAttemptAt = now;
+    return { action: "none" };
+  }
+  if (launchd.crashing) reapBrokenAutostart(relayDir);
+  book.lastAttemptAt = now;
+  book.attempts += 1;
+  const r = startBridge(relayDir);
+  if (r && r.ok === false) {
+    appendLogLine(relayDir, AUTO_INSTALL_LOG,
+      `[dsh-remote-web] 自动启动 bridge 未成功(${r.status || "?"}): ${r.detail || ""}`);
+  }
+  return { action: "start", result: r };
+}
+
+// ---------- 匿名装机/连接遥测（客户端半；契约与隐私边界见 docs/telemetry.md） ----------
+//
+// 背景（2026-09 生产诊断）：11 个新注册用户里只有 3 个把设备连上——6 人电脑端从未安装、2 人装了但
+// bridge 没连上。而「装不上」的人没有任何账号、也就没有任何数据，「本地 OK、新机器失败」因此无法归因。
+// 本通道只补这一段装机/连接事实，且必须守住开源项目的隐私边界：
+//
+//   · 完全匿名：不带 Authorization、不带任何账号标识；install_id 是本机随机 UUID（非硬件派生、
+//     重装即变，不可跨机器关联）；
+//   · 只发白名单事件（TELEMETRY_EVENT_NAMES）与白名单 fail_code（TELEMETRY_FAIL_CODES），
+//     原始错误文本一律不透传（它可能含路径/主机名）；
+//   · 允许的字段**只有**：install_id / 事件名 / fail_code / 版本号 / os(process.platform) /
+//     arch(process.arch) / node(仅主版本号)——唯一构造点是 telemetryEventOf()；
+//   · 禁止采集（代码与 docs/telemetry.md 双写死）：手机号、邮箱、账号 ID、任何会话内容或文件内容、
+//     真实 hostname / 用户名 / 文件路径、密码与密钥、设备指纹(machine_fp)、原始 IP、精确地理位置；
+//   · 可关闭：DSH_REMOTE_TELEMETRY=0 → 完全关闭（不生成 install_id、不落任何文件、不发任何请求）；
+//   · 全程静默：任何异常都被吞掉，绝不影响面板 / bridge / 连接流程与用户可见行为。
+//
+// 契约（服务端冻结）：POST <api_url>/api/telemetry/events，headers
+//   { content-type: application/json, x-dsh-client: dsh-remote/<PLUGIN_VERSION> }（无 Authorization），
+//   body { install_id, source: "plugin", events: [{ name, at, version, os, arch, node, fail_code? }] }，
+//   单批 ≤ 20 条、body ≤ 32KB。
+
+/** 事件名白名单：只用这些，其它一律不发。 */
+const TELEMETRY_EVENT_NAMES = new Set([
+  "install_started", "install_failed", "runtime_ready", "bridge_started", "bridge_registered",
+  "tunnel_disconnected", "first_remote_ok", "plugin_loaded", "panel_opened", "harness_restart",
+  "update_started", "update_failed",
+]);
+/** fail_code 白名单（白名单外的分类一律落 unknown）。 */
+const TELEMETRY_FAIL_CODES = new Set([
+  "node_missing", "node_too_old", "npm_unreachable", "npm_eacces", "platform_unsupported",
+  "runtime_install_timeout", "launchd_failed", "bridge_exit", "bind_conflict", "bind_device_limit", "unknown",
+]);
+/** node 半只发 source=plugin。 */
+const TELEMETRY_SOURCE = "plugin";
+const TELEMETRY_INSTALL_ID_FILE = ".telemetry-install-id";
+const TELEMETRY_QUEUE_FILE = ".telemetry-queue.json";
+const TELEMETRY_ONCE_FILE = ".telemetry-once.json";
+/** 本地队列上限（0600）：超出丢最旧，避免长离线机器把磁盘堆满。 */
+const TELEMETRY_QUEUE_MAX = 200;
+/** 单批事件上限 / body 上限（契约冻结）。 */
+const TELEMETRY_BATCH_MAX = 20;
+const TELEMETRY_BODY_MAX = 32 * 1024;
+/** 每 60s 或队列 ≥5 条时批量发送。 */
+const TELEMETRY_FLUSH_MS = 60_000;
+const TELEMETRY_FLUSH_THRESHOLD = 5;
+/** 失败退避（30s → 2m → 10m → 1h；落在 60s 心跳网格上），累计 6 次仍失败则丢弃该批。 */
+const TELEMETRY_BACKOFF_MS = [30_000, 120_000, 600_000, 3_600_000];
+const TELEMETRY_MAX_ATTEMPTS = 6;
+
+/**
+ * 发送心跳间隔（毫秒）。DSH_REMOTE_TELEMETRY_MS 仅供本仓库测试/诊断把节奏压到亚秒级
+ * （生产不必设置，与 DSH_RELAY_SELFHEAL_MS 同一约定）；调用时读取，import 之后再改也生效。
+ */
+function telemetryFlushMs() {
+  const v = Number(process.env.DSH_REMOTE_TELEMETRY_MS);
+  return Number.isFinite(v) && v > 0 ? Math.max(10, v) : TELEMETRY_FLUSH_MS;
+}
+
+/**
+ * 遥测开关：DSH_REMOTE_TELEMETRY=0/false/off/no → 完全关闭（不生成 install_id、不落文件、不发请求）；
+ * 默认开启（=1/true 显式开启）。
+ * 另外：DSH_RELAY_SKIP_SERVICE=1（测试/诊断隔离，见 skipsSystemOps）时同样不发送——
+ * 本仓库的测试脚本全局设了该变量，用例绝不能把匿名事件发到真实生产端点。
+ */
+function telemetryEnabled() {
+  if (skipsSystemOps()) return false;
+  const v = String(process.env.DSH_REMOTE_TELEMETRY ?? "").trim().toLowerCase();
+  return !(v === "0" || v === "false" || v === "off" || v === "no");
+}
+
+/**
+ * 第 attempt 次失败后到下次重试的退避时长（毫秒）：30s → 2m → 10m → 1h（封顶）。
+ * 设置了 DSH_REMOTE_TELEMETRY_MS 时按同一比例缩放（仅供本仓库测试把整条重试链压到亚秒级；
+ * 生产绝不设置该变量，生产值就是上面这串）。
+ */
+function telemetryBackoffMs(attempt) {
+  const base = TELEMETRY_BACKOFF_MS[Math.min(Math.max(attempt, 0), TELEMETRY_BACKOFF_MS.length - 1)];
+  const v = Number(process.env.DSH_REMOTE_TELEMETRY_MS);
+  const scale = Number.isFinite(v) && v > 0 ? Math.max(10, v) / TELEMETRY_FLUSH_MS : 1;
+  return Math.max(10, Math.round(base * scale));
+}
+
+/** 每个 relayDir 的遥测簿：内存队列 + 心跳句柄 + 退避/去重状态（进程重启即重置）。 */
+const telemetryBooks = new Map();
+function telemetryBook(relayDir) {
+  let b = telemetryBooks.get(relayDir);
+  if (!b) {
+    b = {
+      queue: null,          // null=尚未从磁盘读回
+      timer: null,          // 心跳定时器（unref，不阻塞进程退出）
+      kickPending: false,   // 已排队一次「立即发送」
+      sending: false,
+      attempts: 0,          // 当前批次连续失败次数
+      nextAt: 0,            // 退避解禁时间
+      closed: false,        // 插件已停摆（dispose）→ 不再调度发送
+      fired: new Set(),     // 本进程已发过的事件名（每进程每阶段只发一次）
+      runtimeMissingSeen: false,
+      installStartedAt: 0,
+      tunnelDown: false,    // 同一掉线周期只发一条 tunnel_disconnected
+      wasRegistered: false,
+    };
+    telemetryBooks.set(relayDir, b);
+  }
+  return b;
+}
+
+/**
+ * 只在配置目录**已存在**时落盘：遥测绝不为自己的统计去创建配置目录（否则会改变
+ * 「本机是否装过运行时」的既有语义——例如彻底卸载用例里 relayDir 本不该存在）。
+ * 目录还没出现时事件只留在内存里等下一次心跳，装好了/登录后目录出现即恢复持久化。
+ */
+function telemetryDirReady(relayDir) {
+  try { return Boolean(relayDir) && existsSync(relayDir); } catch { return false; }
+}
+
+/**
+ * 本机 install_id：<relayDir>/.telemetry-install-id（0600），首次 crypto.randomUUID()，之后复用。
+ * 它是**随机 UUID**（非硬件派生、不含机器信息、换机/重装即变），因此不可跨机器关联到同一个人。
+ * 生成/落盘失败 → 返回 null（本次不发，静默，不阻断任何流程）。
+ */
+function telemetryInstallId(relayDir) {
+  if (!telemetryEnabled()) return null;   // 关闭：连 ID 都不生成（更不落盘）
+  if (!telemetryDirReady(relayDir)) return null;
+  const file = join(relayDir, TELEMETRY_INSTALL_ID_FILE);
+  try {
+    const cur = readFileSync(file, "utf8").trim();
+    if (/^[0-9A-Za-z-]{16,64}$/.test(cur)) return cur;
+  } catch { /* 首次生成 */ }
+  try {
+    const id = randomUUID();
+    try {
+      writeFileSync(file, id, { mode: 0o600, flag: "wx" }); // wx：并发时不会互相覆盖
+    } catch {
+      const cur = readFileSync(file, "utf8").trim();        // 别的进程刚生成 → 复用它
+      if (cur) return cur;
+      throw new Error("install_id 写入失败");
+    }
+    try { chmodSync(file, 0o600); } catch { /* 权限位不生效不影响使用 */ }
+    return id;
+  } catch {
+    return null; // 生成失败 → 本次不发
+  }
+}
+
+/** 读回本地队列（懒加载；只接受白名单事件名，杜绝外来/损坏内容被转发）。 */
+function telemetryLoadQueue(relayDir, book) {
+  if (Array.isArray(book.queue)) return book.queue;
+  book.queue = [];
+  try {
+    const raw = JSON.parse(readFileSync(join(relayDir, TELEMETRY_QUEUE_FILE), "utf8"));
+    const list = Array.isArray(raw?.events) ? raw.events : [];
+    book.queue = list.filter((ev) => ev && typeof ev === "object" && TELEMETRY_EVENT_NAMES.has(String(ev.name)));
+  } catch { book.queue = []; }
+  return book.queue;
+}
+
+/** 落盘本地队列（0600；写不进去也不影响主流程——退化为只在内存里排队）。 */
+function telemetrySaveQueue(relayDir, book) {
+  try {
+    if (!telemetryDirReady(relayDir)) return;
+    const file = join(relayDir, TELEMETRY_QUEUE_FILE);
+    writeFileSync(file, JSON.stringify({ v: 1, events: book.queue || [] }), { mode: 0o600 });
+    try { chmodSync(file, 0o600); } catch { /* 非关键 */ }
+  } catch { /* 非关键 */ }
+}
+
+/** 从队列移除已送达/已放弃的一批（按引用比较，避免并发写入被误删）。 */
+function telemetryDrop(relayDir, book, batch) {
+  const queue = telemetryLoadQueue(relayDir, book);
+  for (const ev of batch) {
+    const i = queue.indexOf(ev);
+    if (i >= 0) queue.splice(i, 1);
+  }
+  telemetrySaveQueue(relayDir, book);
+}
+
+/** 一次性事件标记（跨进程、跨重启只发一次，如 first_remote_ok）读/写。 */
+function telemetryOnceFlags(relayDir) {
+  try {
+    const j = JSON.parse(readFileSync(join(relayDir, TELEMETRY_ONCE_FILE), "utf8"));
+    return j && typeof j === "object" ? j : {};
+  } catch { return {}; }
+}
+function telemetryMarkOnce(relayDir, name) {
+  try {
+    if (!telemetryDirReady(relayDir)) return;
+    writeFileSync(join(relayDir, TELEMETRY_ONCE_FILE),
+      JSON.stringify({ ...telemetryOnceFlags(relayDir), [name]: Date.now() }), { mode: 0o600 });
+  } catch { /* 非关键 */ }
+}
+
+/**
+ * 【唯一的 payload 构造点】把事件名 + 少量上下文编译成一条遥测事件。
+ * 字段仅限契约白名单：name / fail_code / at / version / os / arch / node。
+ * 这里**绝不**写入手机号、邮箱、账号 ID、会话或文件内容、hostname、用户名、文件路径、
+ * 密码/密钥、machine_fp、IP、地理位置等任何可识别信息（见 docs/telemetry.md「不采集什么」）。
+ * 返回 null = 事件名不在白名单 → 调用方一律不发。
+ */
+function telemetryEventOf(name, extra = {}) {
+  if (!TELEMETRY_EVENT_NAMES.has(name)) return null;
+  const ev = {
+    name,
+    at: Date.now(),
+    version: PLUGIN_VERSION,
+    os: process.platform,                                       // 仅平台名（darwin/linux/win32），非主机名
+    arch: process.arch,                                         // 仅架构（arm64/x64）
+    node: String(process.versions?.node || "").split(".")[0],   // 仅主版本号，如 "22"
+  };
+  if (name === "install_failed" || name === "update_failed") {
+    const code = String(extra.fail_code || "");
+    ev.fail_code = TELEMETRY_FAIL_CODES.has(code) ? code : "unknown"; // 白名单外 → unknown
+  }
+  return ev;
+}
+
+/** 从既有日志/错误文本归类 fail_code（白名单内）；原始文本绝不外发（可能含路径/主机名）。 */
+function telemetryFailCodeFromText(text) {
+  const t = String(text || "");
+  if (/EACCES|EPERM|permission denied|权限不足/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";
+}
+/** 子进程启动失败（spawn error）→ fail_code。 */
+function telemetryFailCodeFromError(e) {
+  const code = String(e?.code || "");
+  if (code === "ENOENT") return "node_missing";   // 连 node/npx 可执行文件都找不到 = 本机没有 node
+  if (code === "EACCES") return "npm_eacces";
+  return telemetryFailCodeFromText(e?.message);
+}
+
+/** 启动发送心跳（懒启动；unref 不阻塞进程退出）。 */
+function telemetryTickerStart(relayDir) {
+  const book = telemetryBook(relayDir);
+  if (book.timer || book.closed) return;
+  const t = setInterval(() => { void telemetryFlush(relayDir); }, telemetryFlushMs());
+  t.unref?.();
+  book.timer = t;
+}
+
+/** 排队一次「立即发送」（下一轮事件循环执行；不阻塞调用方）。 */
+function telemetryFlushSoon(relayDir) {
+  const book = telemetryBook(relayDir);
+  if (book.kickPending || book.closed || !telemetryEnabled()) return;
+  book.kickPending = true;
+  const t = setTimeout(() => { book.kickPending = false; void telemetryFlush(relayDir); }, 0);
+  t.unref?.();
+}
+
+/**
+ * 入队一条事件：白名单 → 队列（上限 200 丢最旧）→ 落盘 → 队列 ≥5 条立即发送，否则等 60s 心跳。
+ * 全程 try/catch 静默：遥测绝不能影响面板 / bridge / 连接流程或用户可见行为。
+ * @returns {boolean} 是否入队
+ */
+function telemetryRecord(relayDir, name, extra = {}) {
+  try {
+    if (!telemetryEnabled()) return false;   // 关闭：不落文件、不入队、不发请求
+    const ev = telemetryEventOf(name, extra);
+    if (!ev) return false;                   // 白名单外一律不发
+    const book = telemetryBook(relayDir);
+    if (book.closed) return false;
+    const queue = telemetryLoadQueue(relayDir, book);
+    queue.push(ev);
+    if (queue.length > TELEMETRY_QUEUE_MAX) queue.splice(0, queue.length - TELEMETRY_QUEUE_MAX); // 丢最旧
+    telemetrySaveQueue(relayDir, book);
+    telemetryTickerStart(relayDir);
+    if (queue.length >= TELEMETRY_FLUSH_THRESHOLD) telemetryFlushSoon(relayDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 每进程只发一次的事件（plugin_loaded / panel_opened / bridge_started / bridge_registered）。 */
+function telemetryOnce(relayDir, name, extra) {
+  if (!telemetryEnabled()) return false;
+  const book = telemetryBook(relayDir);
+  if (book.fired.has(name)) return false;
+  book.fired.add(name);
+  return telemetryRecord(relayDir, name, extra);
+}
+
+/** 跨进程只发一次的事件（first_remote_ok：持久化标记，先落标记再入队，宁可丢一条也不重复）。 */
+function telemetryOnceEver(relayDir, name, extra) {
+  if (!telemetryEnabled()) return false;
+  if (telemetryOnceFlags(relayDir)[name]) return false;
+  telemetryMarkOnce(relayDir, name);
+  return telemetryRecord(relayDir, name, extra);
+}
+
+/** 运行环境就绪（每进程一次）。 */
+function telemetryRuntimeReady(relayDir) {
+  if (!telemetryEnabled()) return false;
+  const book = telemetryBook(relayDir);
+  if (book.fired.has("runtime_ready")) return false;
+  book.fired.add("runtime_ready");
+  return telemetryRecord(relayDir, "runtime_ready");
+}
+
+/**
+ * 运行环境探针（在补装 watcher 与面板轮询里顺手调用，不额外起定时器）：
+ *   - 现在缺运行环境 → 记下「本进程见过缺失」，并在超过 INSTALL_STALE_MS 仍缺时归因为
+ *     install_failed(runtime_install_timeout)（每进程一次）；
+ *   - 之前见过缺失、现在已就绪 → runtime_ready（每进程一次）。
+ */
+function telemetryRuntimeProbe(relayDir) {
+  if (!telemetryEnabled()) return;
+  try {
+    const book = telemetryBook(relayDir);
+    if (runtimeReady(relayDir)) {
+      if (book.runtimeMissingSeen) telemetryRuntimeReady(relayDir);
+      return;
+    }
+    book.runtimeMissingSeen = true;
+    if (book.installStartedAt && Date.now() - book.installStartedAt > INSTALL_STALE_MS && !book.fired.has("install-timeout")) {
+      book.fired.add("install-timeout");
+      telemetryRecord(relayDir, "install_failed", { fail_code: "runtime_install_timeout" });
+    }
+  } catch { /* 静默 */ }
+}
+
+/**
+ * 「当前隧道是否断连中」判据（仅供遥测）：bridge 日志里最后一次「隧道断开」晚于最后一次
+ * 「隧道已连 / ✅ router 注册成功」即为断连中。只看行序，不读任何内容。
+ */
+function telemetryTunnelDown(relayDir) {
+  const lines = readTail(join(relayDir, BRIDGE_LOG_FILE)).split("\n");
+  let up = -1;
+  let down = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    if (/✅\s*router 注册成功|隧道已连/.test(line)) up = i;
+    else if (/隧道断开/.test(line)) down = i;
+  }
+  return down > up && down >= 0;
+}
+
+/** 「本机设备在账号设备表可见」（first_remote_ok 的第二个条件）：状态文件 / 日志 / 账号接口三选一。 */
+function telemetryAccountVisible(relayDir, conn) {
+  const src = String(conn?.registerSource || "");
+  if (src === "account_api" || src === "account" || src === "state_account") return true;
+  const state = bridgeStateFile(relayDir);
+  if (state && Number(state.account_bound_at) > 0) return true;   // bridge POST /api/devices 成功留下的证据
+  return Boolean(bridgeLogState(relayDir).accountBound);
+}
+
+/**
+ * 连接阶段观察（复用既有阶段引擎，不新造状态机）：阶段推进到 starting / online 时各发一次
+ * （每进程每阶段只发一次，避免 2~3s 轮询把事件刷爆），掉线时发一条 tunnel_disconnected
+ * （同一掉线周期去重）。由持有 conn 的路由调用。
+ */
+function telemetryObserveConnect(relayDir, conn) {
+  if (!telemetryEnabled() || !conn) return;
+  try {
+    const phase = String(conn.phase || "");
+    // bridge_started = bridge 进程被拉起（面板阶段 starting）
+    if (phase === "starting") telemetryOnce(relayDir, "bridge_started");
+    // bridge_registered = 设备已在中继注册成功（面板阶段 online）——这才是「真正可用」
+    if (phase === "online" || conn.registered) telemetryOnce(relayDir, "bridge_registered");
+    // tunnel_disconnected = bridge 掉线：日志里最后一次是「隧道断开」，或注册证据由真变假
+    const book = telemetryBook(relayDir);
+    const dropped = telemetryTunnelDown(relayDir) || (book.wasRegistered === true && !conn.registered);
+    if (dropped) {
+      if (!book.tunnelDown) {
+        book.tunnelDown = true;
+        telemetryRecord(relayDir, "tunnel_disconnected");
+      }
+    } else {
+      book.tunnelDown = false; // 已恢复/未掉线 → 复位，下一轮掉线可再记一条
+    }
+    if (conn.registered) book.wasRegistered = true;
+    // first_remote_ok = 本机首次观察到 online 且本机设备在账号设备表可见（跨进程只发一次）
+    if (phase === "online" && conn.registered && telemetryAccountVisible(relayDir, conn)) {
+      telemetryOnceEver(relayDir, "first_remote_ok");
+    }
+  } catch { /* 静默 */ }
+}
+
+/**
+ * 批量发送一批（≤20 条、≤32KB；调用方一律不 await）。成功出队；失败按 30s→2m→10m→1h 退避，
+ * 累计 6 次仍失败丢弃该批——不永久堆积、不阻塞任何主流程。
+ * 匿名：只有 content-type 与 x-dsh-client，**不带 Authorization**（服务端也不接受账号关联）。
+ */
+async function telemetryFlush(relayDir) {
+  const book = telemetryBook(relayDir);
+  try {
+    if (!telemetryEnabled() || book.closed) return;
+    if (book.sending) return;
+    if (Date.now() < book.nextAt) return;        // 退避中：等下一轮心跳到点再看
+    const queue = telemetryLoadQueue(relayDir, book);
+    if (!queue.length) return;
+    const installId = telemetryInstallId(relayDir);
+    if (!installId) return;                      // install_id 生成失败 → 本次不发
+    const build = (list) => JSON.stringify({ install_id: installId, source: TELEMETRY_SOURCE, events: list });
+    let batch = queue.slice(0, TELEMETRY_BATCH_MAX);
+    let body = build(batch);
+    while (batch.length > 1 && Buffer.byteLength(body, "utf8") > TELEMETRY_BODY_MAX) {
+      batch = batch.slice(0, batch.length - 1);  // body 超 32KB：收缩批次（正常远小于该上限）
+      body = build(batch);
+    }
+    if (Buffer.byteLength(body, "utf8") > TELEMETRY_BODY_MAX) {
+      telemetryDrop(relayDir, book, batch);      // 单条就超限 → 丢弃该批（防御性）
+      return;
+    }
+    const cfg = loadConfig(relayDir);
+    const api = String(cfg.api_url || DEFAULT_API).replace(/\/+$/, "");
+    book.sending = true;
+    let ok = false;
+    try {
+      const r = await fetch(`${api}/api/telemetry/events`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-dsh-client": `dsh-remote/${PLUGIN_VERSION}`,   // 契约冻结：dsh-remote/<version>（非 dsh-remote-web）
+        },
+        body,
+        signal: AbortSignal.timeout(8000),
+      });
+      ok = Boolean(r && r.ok);
+    } catch { ok = false; }                       // 网络失败 → 静默退避（老服务端 404 同理）
+    book.sending = false;
+    if (ok) {
+      telemetryDrop(relayDir, book, batch);
+      book.attempts = 0;
+      book.nextAt = 0;
+      return;
+    }
+    book.attempts += 1;
+    if (book.attempts >= TELEMETRY_MAX_ATTEMPTS) {
+      telemetryDrop(relayDir, book, batch);       // 上限 6 次仍失败 → 丢弃该批
+      book.attempts = 0;
+      book.nextAt = 0;
+      return;
+    }
+    book.nextAt = Date.now() + telemetryBackoffMs(book.attempts - 1);
+  } catch {
+    book.sending = false;                         // 任何异常：静默
+  }
+}
+
+/**
+ * 插件装载时的遥测初始化：读回磁盘队列（上次进程遗留的事件不丢，例如重启前那条 harness_restart）
+ * 并启动发送心跳。DSH_REMOTE_TELEMETRY=0 时连读都不读 → 零文件零请求。
+ */
+function telemetryStart(relayDir) {
+  try {
+    if (!telemetryEnabled()) return;
+    const book = telemetryBook(relayDir);
+    book.closed = false;
+    const queue = telemetryLoadQueue(relayDir, book);
+    telemetryTickerStart(relayDir);
+    if (queue.length) telemetryFlushSoon(relayDir);
+  } catch { /* 静默 */ }
+}
+
+/** 插件停摆（dispose）→ 停掉心跳，之后不再调度发送（磁盘队列留给下次装载）。 */
+function telemetryStop(relayDir) {
+  try {
+    const b = telemetryBooks.get(relayDir);
+    if (!b) return;
+    b.closed = true;
+    if (b.timer) { clearInterval(b.timer); b.timer = null; }
+  } catch { /* 静默 */ }
+}
+
+/** 内部接口（仅供本仓库测试与隐私审计；不属于插件对外契约，也不被面板/浏览器半使用）。 */
+export const __telemetryInternals = {
+  enabled: telemetryEnabled,
+  record: (relayDir, name, extra) => telemetryRecord(relayDir, name, extra),
+  flush: (relayDir) => telemetryFlush(relayDir),
+  installId: (relayDir) => telemetryInstallId(relayDir),
+  queueOf: (relayDir) => telemetryLoadQueue(relayDir, telemetryBook(relayDir)).slice(),
+  eventOf: (name, extra) => telemetryEventOf(name, extra),
+  eventNames: [...TELEMETRY_EVENT_NAMES],
+  failCodes: [...TELEMETRY_FAIL_CODES],
+  queueMax: TELEMETRY_QUEUE_MAX,
+  batchMax: TELEMETRY_BATCH_MAX,
+  bodyMax: TELEMETRY_BODY_MAX,
+  stateOf: (relayDir) => {
+    const b = telemetryBook(relayDir);
+    return { attempts: b.attempts, nextAt: b.nextAt, sending: b.sending, queueLen: telemetryLoadQueue(relayDir, b).length };
+  },
+  reset: (relayDir) => {
+    const b = telemetryBooks.get(relayDir);
+    if (b && b.timer) clearInterval(b.timer);
+    telemetryBooks.delete(relayDir);
+  },
+};
+
+/**
+ * 安装信息上报（插件侧通道）：登录后把本机安装信息发给企业端，供「已登录用户升级插件后刷新版本号」
+ * 之类的口径统计。无账号凭据不上报；失败静默（绝不阻塞面板、不弹错误）。
+ * 契约：POST <api_url>/api/install-report，头 `authorization: Bearer <device-login JWT>`，
+ * body { device_id?, install_source, install_version, host_os, host_arch }，成功 200 {ok:true}；
+ * 404/400 一律忽略（老服务端没有该接口时不能报错）。
+ */
+const INSTALL_REPORT_FILE = ".dsh-install-report.json";
+const INSTALL_REPORT_TTL_MS = 24 * 3600 * 1000;
+const INSTALL_SOURCES = new Set(["npx", "plugin_market"]);
+/** 本机安装来源判据：环境变量 > 插件自愈记录 > 有运行环境即安装器部署 > 默认插件路径。 */
+function installSourceOf(relayDir) {
+  const env = String(process.env.DSH_BRIDGE_INSTALL_SOURCE || "").trim();
+  if (INSTALL_SOURCES.has(env)) return env;
+  if (existsSync(join(relayDir, PROVISIONED_MARKER))) return "plugin_market";
+  if (runtimeReady(relayDir)) return "npx";
+  return "plugin_market";
+}
+async function reportInstallOnce(relayDir, cfgOverride, opts = {}) {
+  const cfg = cfgOverride || loadConfig(relayDir);
+  if (!hasAccountCreds(cfg)) return { ok: false, skipped: "no_credentials" };
+  const source = installSourceOf(relayDir);
+  const version = PLUGIN_VERSION;
+  const marker = join(relayDir, INSTALL_REPORT_FILE);
+  if (!opts.force) {
+    try {
+      const prev = JSON.parse(readFileSync(marker, "utf8"));
+      if (prev && prev.version === version && prev.source === source && Date.now() - Number(prev.at || 0) < INSTALL_REPORT_TTL_MS) {
+        return { ok: true, skipped: "already_reported" };
+      }
+    } catch { /* 首次上报 */ }
+  }
+  const token = await relayToken(relayDir).catch(() => "");
+  if (!token) return { ok: false, skipped: "no_token" };
+  const api = (cfg.api_url || DEFAULT_API).replace(/\/+$/, "");
+  const body = {
+    ...(cfg.device_id ? { device_id: String(cfg.device_id) } : {}),
+    install_source: source,
+    install_version: version,
+    host_os: process.platform,
+    host_arch: process.arch,
+  };
+  try {
+    const r = await fetch(`${api}/api/install-report`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "x-dsh-client": `dsh-remote-web/${version}`,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(6000),
+    });
+    // 老服务端没有该接口（404）或字段不认（400）→ 忽略，绝不影响 UI
+    if (r.status === 400 || r.status === 404) return { ok: false, skipped: `http_${r.status}` };
+    if (!r.ok) return { ok: false, status: r.status };
+    try { writeFileSync(marker, JSON.stringify({ at: Date.now(), version, source })); } catch { /* 非关键 */ }
+    return { ok: true, status: r.status, install_source: source, install_version: version };
+  } catch (e) {
+    return { ok: false, skipped: `unreachable: ${e.message}` };
+  }
+}
+/** 上报节流入口（fire-and-forget）：失败最多 60s 再试一次；成功则按 version/source 去重。 */
+function maybeReportInstall(relayDir, opts = {}) {
+  const book = connectBook(relayDir);
+  const now = Date.now();
+  if (!opts.force && book.reportAt && now - book.reportAt < 60_000) return;
+  book.reportAt = now;
+  // 认证走 relayTokenWithReason（60s token 缓存 + 并发合并），因此启动/登录/轮询多次调用
+  // 也只会打一次 device-login，不会放大企业端认证请求。
+  reportInstallOnce(relayDir, null, opts).catch(() => { /* 静默失败：不影响 UI */ });
+}
+
 function registerRoutes(ctx, relayDir) {
   // 本插件所在 profile(由插件自身文件位置推导,覆盖市场 git 安装与本地 include 两种形态)
   let profileDir = join(homedir(), ".dsh", "profiles", "web");
@@ -1793,9 +2907,51 @@ function registerRoutes(ctx, relayDir) {
       method: "GET",
       path: "/dsh-remote/status",
       handler: async (_req, res) => {
+        // 按需补齐浏览器会话 Cookie(不 await:状态接口不能被本地换 Cookie 拖慢)。
+        // 面板轮询会持续触达本接口 → 手机端的 401 会在秒级内自愈。
+        void ensureHarnessCookie(ctx, relayDir).catch(() => {});
         sendJson(res, 200, await composeStatus(relayDir));
       },
     },
+    // 连接阶段短轮询端点（面板 2~3s 一次，非 online 时自动推进；online 后退避到 15s）。
+    // 返回前先执行自动闭环动作（缺环境→补装 / 有账号没进程→拉起 / 卡死标记→清理），
+    // 于是「登录后自动连上」不需要任何按钮或刷新；每步都自带退避，失败不会打成风暴。
+    {
+      method: "GET",
+      path: "/dsh-remote/bridge-status",
+      handler: async (_req, res) => {
+        ensureConnection(relayDir);
+        maybeReportInstall(relayDir);
+        void ensureHarnessCookie(ctx, relayDir).catch(() => {}); // 同上:手机端授权会话自愈
+        telemetryRuntimeProbe(relayDir); // 匿名遥测：运行环境刚补齐 → runtime_ready（不额外起定时器）
+        const connect = await composeConnect(relayDir);
+        telemetryObserveConnect(relayDir, connect); // 匿名遥测：bridge_started / bridge_registered / 掉线
+        sendJson(res, 200, { ok: true, connect });
+      },
+    },
+    // 面板打开（浏览器半在「远程访问」栏目首次渲染时调一次）：每进程只记一次。
+    // 只发事件名，不含任何账号/内容/设备信息；DSH_REMOTE_TELEMETRY=0 时静默丢弃。
+    {
+      method: "POST",
+      path: "/dsh-remote/telemetry/panel-opened",
+      handler: async (_req, res) => {
+        telemetryOnce(relayDir, "panel_opened");
+        sendJson(res, 200, { ok: true });
+      },
+    },
+    // 手动重试（error 阶段的「重试」按钮）：清掉退避计数立刻再走一遍闭环。
+    {
+      method: "POST",
+      path: "/dsh-remote/connect/retry",
+      handler: async (_req, res) => {
+        const action = ensureConnection(relayDir, { force: true });
+        maybeReportInstall(relayDir, { force: true });
+        await sleep(600); // 给 launchctl 一点进入运行态的时间，重试点下去立刻能看到「正在启动 Bridge…」
+        const connect = await composeConnect(relayDir);
+        telemetryObserveConnect(relayDir, connect); // 匿名遥测：同 bridge-status（去重后不会重复计数）
+        sendJson(res, 200, { ok: true, retried: true, action: action && action.action ? action.action : "none", connect });
+      },
+    },
     {
       method: "GET",
       path: "/dsh-remote/account",
@@ -1919,7 +3075,10 @@ function registerRoutes(ctx, relayDir) {
           }
         }
         saveConfig(relayDir, cfg);
+        invalidateRelayToken(relayDir); // 账号可能变了：丢弃旧 token 缓存，立即用新账号认证
         const bridgeRestart = startBridge(relayDir);
+        // 登录成功即上报本机安装信息（企业端用于「升级插件后刷新版本号」口径）；失败静默。
+        maybeReportInstall(relayDir, { force: true });
         sendJson(res, 200, { ok: true, bridgeRestart, ...(await composeStatus(relayDir)) });
       },
     },
@@ -1932,6 +3091,7 @@ function registerRoutes(ctx, relayDir) {
         delete cfg.phone;
         delete cfg.password;
         saveConfig(relayDir, cfg);
+        invalidateRelayToken(relayDir); // 退出登录：token 缓存立即失效
         sendJson(res, 200, { ok: true, ...(await composeStatus(relayDir)) });
       },
     },
@@ -2053,7 +3213,10 @@ function registerRoutes(ctx, relayDir) {
         const smsCode = String(body.sms_code ?? "").trim();
         const password = String(body.password ?? "");
         if (!phone || !smsCode || !password) return sendJson(res, 400, { ok: false, error: "手机号、短信验证码与密码必填" });
-        const payload = { phone, sms_code: smsCode, password };
+        // 全量透传 body（不挑字段）：注册来源 reg_source（面板=panel_register／手机端网页=remoteweb_register）
+        // 等扩展字段必须原样进企业端，否则「用户从哪注册的」这类增长口径会全部丢失。
+        const payload = { ...body, phone, sms_code: smsCode, password };
+        delete payload.__parseError;
         const captchaId = body.captcha_id ?? body.captchaId;
         const captchaAnswer = body.captcha_answer ?? body.captcha;
         if (captchaId !== void 0) payload.captcha_id = String(captchaId);
@@ -2163,6 +3326,11 @@ export function apply(ctx, config = {}) {
   const relayDir = config.relayDir || process.env.DSH_RELAY_DIR || DEFAULT_RELAY_DIR;
   // 全新激活（dsh web 重启后插件重新加载，或卸载后再次安装）→ 解除上次的「已卸载」停摆标记
   UNINSTALLED_DIRS.delete(relayDir);
+  // 匿名遥测：装载即初始化（读回上次进程遗留的磁盘队列，例如重启前那条 harness_restart，
+  // 并启动 60s 发送心跳），随后记一条 plugin_loaded（每进程一次）。
+  // DSH_REMOTE_TELEMETRY=0 → 这里连读都不读：零文件、零请求、零 install_id。
+  telemetryStart(relayDir);
+  telemetryOnce(relayDir, "plugin_loaded");
   // 清理上次进程残留的安装/更新 marker（宿主被重启/强杀时子进程清理回调会丢失）
   sweepStaleMarkers(relayDir);
   // 「待重启」状态结清 + 运行时安装检测：
@@ -2174,20 +3342,30 @@ export function apply(ctx, config = {}) {
     ctx.logger?.info?.("dsh-remote-web: 检测到 DeepSeek harness 已重启，撤下「需要重启」提示");
   }
   if (!readRestartState(relayDir).pending && pluginInstalledAfterBoot()) {
-    markRestartPending(relayDir, "first-install", "首次安装需要重启 DeepSeek harness");
-    ctx.logger?.info?.("dsh-remote-web: 插件文件晚于本次进程启动 → 需要重启 DeepSeek harness");
+    // 唯一还需要用户动一下的情形:插件文件晚于本进程启动才落盘(= 运行中被市场安装/在线更新改写),
+    // 此时本进程里没有本插件的路由与面板。**先让用户刷新页面**(客户端半随之更新);
+    // 只有刷新后仍无面板才需要重启(那时多半是 profile patch 行没被 HMR 读到)。
+    // 不再对"首次安装/在线更新完成"提示重启:插件走 patch 热加载、bridge 是独立进程,重启 harness 无必要。
+    markRestartPending(relayDir, "refresh", "插件已更新，刷新页面即可生效");
+    ctx.logger?.info?.("dsh-remote-web: 插件文件晚于本次进程启动 → 提示刷新页面");
   }
   ctx.effect(() => registerRoutes(ctx, relayDir), "dsh-remote-web: /dsh-remote routes");
   // 0.1.2-rc.1+ 浏览器会话代持：换取 Harness 会话 Cookie 供 bridge 上游携带（手机点设备不再 401 白页）
   ctx.effect(() => scheduleHarnessMint(ctx, relayDir), "dsh-remote-web: harness browser-session mint");
   // 插件市场一键全功能:缺桌面运行环境则自动安装,登录后自动拉起 bridge(不依赖用户跑 npx)
   ctx.effect(() => scheduleRuntime(relayDir), "dsh-remote-web: runtime self-provision");
+  // 匿名遥测：插件停摆（卸载/重载）时停掉发送心跳；磁盘队列留给下次装载补发。
+  ctx.effect(() => () => telemetryStop(relayDir), "dsh-remote-web: telemetry flush ticker");
   // 【0.6.2】市场安装路径的「装到用户电脑上」第一步：插件加载即后台补装桌面运行环境
   // （bridge + 自启动），不再等用户先登录、也不再依赖 launchd 状态判断是否「已在运行」。
   // 已就绪时是零副作用 no-op；正在安装中/已卸载时 ensureRuntime 自身幂等挡下。
   const provisioned = ensureRuntime(relayDir);
   if (!provisioned && !runtimeReady(relayDir)) {
     ctx.logger?.info?.(`dsh-remote-web: 桌面运行环境缺失，已在后台自动安装（relayDir=${relayDir}）`);
+    telemetryRuntimeProbe(relayDir); // 匿名遥测：记下「本进程见过运行环境缺失」（装好后发 runtime_ready）
   }
+  // 插件启动即上报本机安装信息（install_source/version + 主机 OS/架构；仅有账号凭据时上报，失败静默）。
+  // 面板登录成功（POST /dsh-remote/config）时会再上报一次，覆盖「已登录用户升级插件」的口径。
+  maybeReportInstall(relayDir);
   ctx.logger?.info?.(`dsh-remote-web: /dsh-remote routes ready (relayDir=${relayDir})`);
 }