@mrrisega/dsh-remote 0.6.14 → 0.6.15

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

@@ -39,6 +39,7 @@ import {
   extractDigits,
   extractInboundText,
   extractFromUserId,
+  extractContextToken,
   handleCommand,
   classifyInbound,
   formatCompletion,
@@ -197,6 +198,14 @@ const SPECIAL_EVENT_KINDS = Object.freeze([
  */
 const NOTICE_FORMATTER_KINDS = Object.freeze(["quota", "membership"]);
 
+/**
+ * 主动推送失败后的**待补发队列**上限（见 `#pushProactive`）。
+ * 为什么是 20：够放下"一轮里所有该告诉用户的事"；再多下去，补发就变成刷屏了。
+ */
+const MAX_OUTBOX = 20;
+/** 补发时的正文前缀（迟到必须如实说，不能让用户以为刚刚才发生）。 */
+const OUTBOX_MARK = "（补发）";
+
 /**
  * 把事件节点翻译成文案节点。
  * @returns {{node: object|null, formatterKind: string}}
@@ -479,7 +488,21 @@ export class WeChatRuntime {
         ? { active: true, need_verify_code: !!this.bind.needVerifyCode }
         : { active: false, failed: !!(this.bind && this.bind.done && !this.bind.result) },
       channel_running: !!this.channelTask,
-      events_running: !!this.subscriber
+      events_running: !!this.subscriber,
+      // ── 诊断字段（2026-09-25 事故加的）────────────────────────────────────
+      // 那次「任务跑完一条微信都没收到，日志里也没有任何报错」暴露了三件必须能看见的事：
+      //   ① 事件订阅到底 ready 了没、**正在 follow 哪些会话**（follow 集为空 = turn/end 收不到）；
+      //   ② 有没有排进待补发队列的通知（推送失败不再等于消失）；
+      //   ③ 最近一次订阅异常是什么（以前 fault 只 emit、没人接，全静默）。
+      events_state: this.subscriber && typeof this.subscriber.state === "string" ? this.subscriber.state : "",
+      followed_sessions: this.subscriber && typeof this.subscriber.sessions === "function"
+        ? this.subscriber.sessions()
+        : [],
+      pending_outbox: Array.isArray(state.pending_outbox) ? state.pending_outbox.length : 0,
+      last_fault: state.last_fault || null,
+      last_completed_session_id: state.last_completed_session_id || "",
+      last_completed_at: Number(state.last_completed_at || 0),
+      inbound_shape_null_token: state.inbound_shape || ""
     };
   }
 
@@ -746,10 +769,23 @@ export class WeChatRuntime {
   async handleInbound(msg) {
     const from = extractFromUserId(msg);
     const text = normalizeInput(extractInboundText(msg));
+    // ★ 每条入站消息都带上 `context_token`,而**出站必须回带它**才发得出去
+    //   (不进它 → 真机 `ret=-2 errmsg=prepare failed`,业主「没收到微信通道」)。
+    //   放在 `if (!text) return` **之前**:图片/语音这类没有文本的消息同样会刷新上下文。
+    //   记不住不影响主流程(最坏就是这一条发不出去,与以前一样)。
+    try { this.channel.rememberContextToken(extractContextToken(msg), from); } catch { /* 忽略 */ }
+    // ★ 0.6.15：收到入站消息 = 平台侧这条会话刚刚"活过来"，是补发积压通知的最好时机。
+    //   fire-and-forget：补发失败不能影响用户这条消息的处理。
+    void this.#flushOutbox(from).catch(() => 0);
     if (!text) return;
 
     // 内部统计:任何入站互动都算一次"窗口续期"事件
     this.#bumpToday();
+    // ★ 0.6.15：`context_token` 的形状一直没被验证过（§11）。真机日志里
+    //   `ret=-2 prepare failed` 出现过 48 次，而状态文件里**从来没有** context_token ——
+    //   也就是说入站消息里没带它（或字段名和我们猜的不一样）。这里把**字段名**记一次
+    //   （只有名字，没有值），下次再出这个问题就能一眼看出该取哪个键，不用再猜。
+    this.#noteInboundShapeIfNoToken(msg);
 
     // ── v2 分派:命令 → 数字 → 普通消息 ────────────────────────────────────
     // ⚠️ 顺序不能换:
@@ -1082,7 +1118,59 @@ export class WeChatRuntime {
   #rememberSession(sessionId, title) {
     this.currentSessionId = sessionId || "";
     this.currentSessionTitle = title || "";
-    this.channel.writeState({ current_session_id: this.currentSessionId, current_session_title: this.currentSessionTitle });
+    this.channel.writeState({
+      current_session_id: this.currentSessionId,
+      current_session_title: this.currentSessionTitle,
+      // 「回复目标是什么时候定下来的」——回话前对表要用（见 #retargetToLatestCompletion）。
+      current_session_set_at: this.clock(),
+    });
+  }
+
+  /**
+   * 记下"最近完成的任务"（**无论那条完成推送有没有发出去**）。
+   *
+   * 为什么必须有它：`#rememberSession` 只在推送真的发出去了才会被调用 —— 一旦推送失败
+   * （微信侧 ret=-2）或者订阅漏了 turn/end，当前会话指针就**停在旧会话上**，用户回话会发进
+   * 那个旧会话（业主 2026-09-25 实测：「刚才我回了个话，而且回到了另外一个对话里面去了」）。
+   * 有了这个记录，回话前就能对一次表（见 `#retargetToLatestCompletion`）。
+   */
+  #rememberCompletion(sessionId, title) {
+    if (!sessionId) return;
+    this.channel.writeState({
+      last_completed_session_id: String(sessionId),
+      last_completed_session_title: String(title || ""),
+      last_completed_at: this.clock(),
+    });
+  }
+
+  /**
+   * 回话前的"对表"：当前会话指针是不是**落后于**最近一次完成？
+   *
+   * 判据严格且保守：只有「完成时间**晚于**我们最后一次把回复目标定下来的时间」才切换。
+   * 绝不因为"还有个更活跃的会话"就改主意 —— 那会把用户正在聊的会话顶掉。
+   * @returns {boolean} 是否切换了
+   */
+  async #retargetToLatestCompletion() {
+    try {
+      const st = loadState(this.relayDir);
+      const sid = String(st.last_completed_session_id || "");
+      if (!sid || sid === this.currentSessionId) return false;
+      const doneAt = Number(st.last_completed_at || 0);
+      const setAt = Number(st.current_session_set_at || 0);
+      if (!doneAt || doneAt <= setAt) return false;
+      let title = String(st.last_completed_session_title || "");
+      if (!title) {
+        // 静音路径只记了 id（没解析标题）→ 这里补一次，让确认文案里能出现人话的会话名
+        try {
+          const list = await this.#sessions();
+          const hit = list ? list.find((s) => s.sessionId === sid) : null;
+          if (hit && hit.title) title = hit.title;
+        } catch { /* 取不到就用空标题 */ }
+      }
+      this.#rememberSession(sid, title);
+      this.logger.info(`[wechat] 回话前对表：当前会话落后于最近完成的任务 ${sid}，已自动切过去`);
+      return true;
+    } catch { return false; }
   }
 
   /** 拉一次会话列表(带标题),并记住 1-based 序号供 /use 使用。 */
@@ -1249,6 +1337,9 @@ export class WeChatRuntime {
       await this.reply(from, "暂不可用:DSH 会话服务未就绪。");
       return;
     }
+    // ★ 0.6.15：回话前先对一次表 —— 完成推送**没发出去**时（平台 ret=-2 / 订阅漏了 turn/end），
+    //   当前会话指针会停在旧会话上，这一句"再改一下"就会发给那个旧会话。
+    const switched = await this.#retargetToLatestCompletion();
     // 每月消息额度闸(放在真正派活之前;审批/指令不计数也不拦)
     const gate = this.#msgQuotaGate();
     if (!gate.ok) {
@@ -1258,7 +1349,10 @@ export class WeChatRuntime {
     const r = await this.subscriber.promptSession({ sessionId: this.currentSessionId, text: body });
     if (r && r.ok) {
       this.#msgQuotaBump(); // 只在真的派出去之后扣额度(发失败不该扣)
-      await this.reply(from, `已补充给「${this.currentSessionTitle || "当前任务"}」,跑完推结论给你。`);
+      // 「最后一次把回复目标定下来」的时间：下一次对表要看它，避免把用户正在聊的会话顶掉。
+      this.channel.writeState({ current_session_set_at: this.clock() });
+      const note = switched ? "（刚跑完的那个任务已自动切为回复对象）" : "";
+      await this.reply(from, `已补充给「${this.currentSessionTitle || "当前任务"}」,跑完推结论给你。${note}`);
       // ★ 额度消耗**之后**才可能提醒(顺序不能反:提醒要看的是扣完之后还剩几条);
       //   fire-and-forget,提醒失败不影响"已下发"这条主流程的结果。
       this.#maybeRemindQuota().catch(() => {});
@@ -1360,11 +1454,118 @@ export class WeChatRuntime {
     }
   }
 
+  /**
+   * 入站消息里到底有没有 `context_token`？没有的话，把**字段名**记一次（值一律不记）。
+   *
+   * 为什么需要：出站要回带 `context_token`，而没人验证过它的真实形状（§11）。
+   * 真机证据（2026-09-25）：bridge 日志里 `ret=-2 errmsg=prepare failed` 出现 48 次，
+   * 而状态文件里**从来没有** context_token —— 说明入站消息里没带它，或者它在别的键上。
+   * 猜字段名没有意义，让真机告诉我们：只记名字（不含任何内容/凭据），一次就够。
+   */
+  #noteInboundShapeIfNoToken(msg) {
+    try {
+      if (extractContextToken(msg)) return; // 有令牌就没什么可记的
+      const shape = [];
+      const walk = (obj, prefix, depth) => {
+        if (!obj || typeof obj !== "object" || depth > 2 || shape.length >= 40) return;
+        for (const k of Object.keys(obj)) {
+          if (shape.length >= 40) return;
+          const path = prefix ? `${prefix}.${k}` : k;
+          shape.push(path);
+          const v = obj[k];
+          if (v && typeof v === "object" && !Array.isArray(v)) walk(v, path, depth + 1);
+        }
+      };
+      walk(msg, "", 0);
+      const joined = shape.join(",");
+      const st = loadState(this.relayDir);
+      if (String(st.inbound_shape || "") === joined) return; // 同形状只记一次
+      this.channel.writeState({ inbound_shape: joined });
+      this.logger.info(`[wechat] 入站消息里没有 context_token；字段名（不含值）：${joined}`);
+    } catch { /* 诊断失败不影响主流程 */ }
+  }
+
   #noteFailure(text) {
     this.channel.writeState({ last_error: String(text).slice(0, 200) });
     this.logger.warn(`[wechat] ${text}`);
   }
 
+  // ── 待补发队列（主动推送失败不再静默丢失） ──────────────────────────────
+  //
+  // 【2026-09-25 事故】业主的任务跑完后**一条微信都没收到**，而日志里躺着 48 条
+  // `sendmessage 失败:sendMessage: ret=-2 errmsg=prepare failed` —— 平台侧发送失败是
+  // **间歇性**的（实测同一台机器上有的消息发得出去、有的发不出去），而旧实现失败即丢弃：
+  // 用户永远不知道那条"任务跑完了"存在过。
+  //
+  // 做法：主动推送（通知类）失败就**入队**，在下一次成功发送/成功入站时按 FIFO 补发。
+  // 补发时正文前加「（补发）」——迟到就要如实说，不能让用户以为刚刚才发生。
+  // ⚠️ 队列落盘且**只存正文**（不含 token/eventId）：状态文件是面板可读的，
+  //    凭据一律不进（§8）。
+  #outbox() {
+    try {
+      const st = loadState(this.relayDir);
+      return Array.isArray(st.pending_outbox) ? st.pending_outbox : [];
+    } catch { return []; }
+  }
+
+  #writeOutbox(items) {
+    const list = Array.isArray(items) ? items : [];
+    this.channel.writeState({ pending_outbox: list, pending_outbox_count: list.length });
+    return list;
+  }
+
+  #enqueueOutbox(text, kind = "") {
+    const body = String(text || "");
+    if (!body) return 0;
+    const list = this.#outbox();
+    list.push({ text: body, kind: String(kind || ""), at: this.clock() });
+    // 上限：丢最旧的（用户最需要的是"最近发生了什么"，而无限攒下去只会让补发像刷屏）
+    while (list.length > MAX_OUTBOX) list.shift();
+    return this.#writeOutbox(list).length;
+  }
+
+  /**
+   * 把待补发队列按 FIFO 发出去（碰到第一条失败就停，保留剩下的下次再试）。
+   * @returns {Promise<number>} 这次补发成功的条数
+   */
+  async #flushOutbox(to) {
+    const list = this.#outbox();
+    if (!list.length || !to) return 0;
+    let sent = 0;
+    const rest = [...list];
+    while (rest.length) {
+      const item = rest[0];
+      const ok = await this.reply(to, `${OUTBOX_MARK}${String(item && item.text ? item.text : "")}`);
+      if (!ok) break; // 还是发不出去：原样留着，下次再试
+      rest.shift();
+      sent += 1;
+    }
+    if (sent > 0) {
+      this.#writeOutbox(rest);
+      this.logger.info(`[wechat] 待补发队列已送出 ${sent} 条（剩 ${rest.length} 条）`);
+    }
+    return sent;
+  }
+
+  /**
+   * 主动推送（通知类）：先补发积压，再发这一条；发不出去就入队，绝不丢。
+   * @returns {Promise<{sent:boolean, queued:boolean}>} queued=true 表示"已排进待补发"，
+   *   调用方据此仍可登记待拍板项（用户稍后看到时还能回执）。
+   */
+  async #pushProactive(to, text, kind = "", { queue = true } = {}) {
+    const body = String(text || "");
+    if (!body) return { sent: false, queued: false };
+    await this.#flushOutbox(to).catch(() => 0);
+    const ok = await this.reply(to, body);
+    if (ok) return { sent: true, queued: false };
+    // queue=false：**自己有重试/占位语义**的通知（日报）绝不能排队 ——
+    // 排队 + 它自己的下一次 tick 补发 = 用户收到两条，而且"当天已发"的占位账也会算错。
+    if (!queue) return { sent: false, queued: false };
+    const depth = this.#enqueueOutbox(body, kind);
+    this.logger.warn(`[wechat] 主动推送失败(${kind || "?"})：已排进待补发队列（${depth} 条），下一条能发出去时会补上`);
+    return { sent: false, queued: true };
+  }
+
   // ── 出站:DSH 事件 → 微信通知 ───────────────────────────────────────────
 
   #startSubscriber() {
@@ -1401,6 +1602,20 @@ export class WeChatRuntime {
     sub.on("auth-error", (info) => {
       this.logger.warn(`[wechat/events] 鉴权失败(${info && info.surface}):需要刷新 harness cookie`);
     });
+    sub.on("fault", (info) => {
+      // ★ 2026-09-25：订阅层的 fault **以前完全没人接**（`#emitFault` 只 emit、不 log），
+      //   于是「follow 失败 / 发现失败 / 流上限」全都**静默消失** —— 用户看到的是
+      //   「任务跑完没有任何推送，日志里也没有任何报错」，事后只能靠数日志行数考古。
+      //   现在：一条 warn 落进 bridge 日志（带时间戳），并把**非预期**的那条记进状态文件供面板显示。
+      //   `expected: true`（子代理会话必然被拒 / 会话刚被删）只记日志，不当故障刷状态。
+      const code = String((info && info.code) || "unknown");
+      const message = String((info && info.message) || "").slice(0, 160);
+      const sessionId = String((info && info.sessionId) || "");
+      this.logger.warn(`[wechat/events] 订阅异常 ${code}${sessionId ? ` session=${sessionId}` : ""}: ${message}`);
+      if (!(info && info.expected === true)) {
+        this.channel.writeState({ last_fault: { code, message, session_id: sessionId, at: this.clock() } });
+      }
+    });
   }
 
   async #tellGap() {
@@ -1414,7 +1629,7 @@ export class WeChatRuntime {
    * 把一条**事件**节点发到微信。可回执的登记进待答队列。
    * 公开方法:bridge 与测试都直接调用它(不叫 #notify 是因为它是本模块的主要出口之一)。
    */
-  async notify(eventNode) {
+  async notify(eventNode, opts = {}) {
     if (!eventNode || !this.channel.account) return { ok: false, reason: "not_bound" };
     const acct = this.channel.account;
 
@@ -1427,7 +1642,15 @@ export class WeChatRuntime {
         NODE_KINDS.PLAN_REVIEW,
         NODE_KINDS.SESSION_ERROR
       ].includes(eventNode.kind);
-      if (!important) return { ok: false, reason: "quiet" };
+      if (!important) {
+        // ★ 0.6.15：静音也要**记账**。完成推送被静音时，这条"最近完成的任务"仍然必须被记下来 ——
+        //   否则用户下一秒回话就会发进上一次的会话（业主实测的那个"回到另一个对话"）。
+        //   静音只表示"不打扰"，不表示"当它没发生过"。
+        if (eventNode.kind === NODE_KINDS.TURN_END && eventNode.sessionId) {
+          this.#rememberCompletion(eventNode.sessionId, "");
+        }
+        return { ok: false, reason: "quiet" };
+      }
     }
 
     // 没有文案模板的节点:按设计另行处理,不是漏接线
@@ -1465,10 +1688,22 @@ export class WeChatRuntime {
         const list = await this.#sessions();
         const hit = list ? list.find((s) => s.sessionId === sid) : null;
         if (hit && hit.title) title = hit.title;
-        // 学到标题就记住,后面 /status 与 /ls 都能直接用
-        if (hit && sid === this.currentSessionId && title !== this.currentSessionTitle) {
-          this.#rememberSession(sid, title);
-        }
+      }
+      // ★ 0.6.15 修（业主实测）：**完成推送要把"当前会话"切到刚跑完的那个**。
+      //   旧行为只在 sid 已经是当前会话时才更新标题，于是：B 会话跑完推了结论，用户直接在微信里
+      //   回一句"再改一下"，那条消息却被 `#sendToSession` 发给了**上一次的当前会话 A** ——
+      //   A 莫名其妙多了一条指令，B 永远收不到。用户看到的正是"推送过来了，我准备回话，
+      //   它还停留在我之前的会话里"。
+      //   语义：**最近完成的任务 = 最近一次推送的对象 = 你现在回话的对象**。这是唯一不会让人踩空的解释。
+      //
+      // ★ 0.6.15 补：**先无条件记下"最近完成的任务"**（与推送成败无关）。
+      //   推送失败（微信 ret=-2）或订阅漏了 turn/end 时，这一步是回话前对表的唯一依据，
+      //   否则当前会话指针会停在旧会话上，用户回话直接发进旧会话（业主实测的第二个症状）。
+      this.#rememberCompletion(sid, title);
+      if (sid && sid !== this.currentSessionId) {
+        this.#rememberSession(sid, title);
+      } else if (sid && title && title !== this.currentSessionTitle) {
+        this.#rememberSession(sid, title); // 学到标题就记住,后面 /status 与 /ls 都能直接用
       }
       const summary = sid ? await this.#sessionSummary(sid) : "";
       const c = formatCompletion({
@@ -1524,7 +1759,15 @@ export class WeChatRuntime {
       ? `${built.text}\n\n（你还有 ${othersWaiting + 1} 条待拍板，回完这条我会把下一条发到下面）`
       : built.text;
 
-    const sent = await this.reply(acct.userId, outgoing);
+    // ★ 0.6.15：走 `#pushProactive`（先补发积压 → 再发这条 → 发不出去就入队），
+    //   不再直接 `reply()`。旧实现失败即丢弃 —— 平台的发送失败是间歇性的，用户于是
+    //   "任务跑完了却一条都没收到"，而且谁也不知道那条通知存在过。
+    // 日报（`daily`）自带重试与"当天已发"占位：它一旦进了补发队列就会与下一次 tick 撞成两条，
+    // 也会把占位账算错 —— 这类通知**明确不排队**（其余通知都排队，失败不再等于消失）。
+    const queueFailedPush = opts.queueFailedPush !== false && formatterKind !== "daily";
+    const pushed = await this.#pushProactive(acct.userId, outgoing, formatterKind, { queue: queueFailedPush });
+    // 入队也算"已经安排了送达"：用户稍后看到补发时，回执必须仍然认得出这条待办。
+    const sent = pushed.sent || pushed.queued;
     if (sent && built.replyable && built.eventId) {
       this.pendingReplies.push({
         eventId: built.eventId,

package/packages/dsh-remote-web/runtime/dsh-setup.mjs

@@ -170,6 +170,7 @@ function printHelp() {
   dsh-remote status       查看配置与服务状态
   dsh-remote plugin       手动安装 dsh web 远程访问插件（--uninstall 卸载）
   dsh-remote repair       修复插件挂载（dsh web 起不来时用；只碰 profile，不联网）
+  dsh-remote doctor       一条命令自检「为什么连不上」（只读；含上游/进程/微信/日志尾部）
   dsh-remote --help       显示本用法（等同 dsh-remote help）
 
 自建模式（可选）:
@@ -202,7 +203,11 @@ const KNOWN_FLAGS = new Set([
     process.exit(1);
   }
 }
-try { ensureRuntimeCopy(); } catch (e) { console.warn(`⚠️ 运行时固化跳过: ${e.message}`); }
+// `doctor` 承诺"只读"：它连运行时脚本同步都不做 —— 否则"自检"会先往用户磁盘写 9 个文件，
+// 与承诺不符（也会把"我什么都没改却多了文件"变成新的困惑）。
+if (process.argv[2] !== "doctor") {
+  try { ensureRuntimeCopy(); } catch (e) { console.warn(`⚠️ 运行时固化跳过: ${e.message}`); }
+}
 
 /** 自启动服务应指向的 dsh-setup.mjs：优先配置目录内的固化副本，否则当前执行文件。 */
 function runtimeSetupPath() {
@@ -764,12 +769,32 @@ function restartBridgeService() {
     return startBridgeDarwin(plistPath);
   }
   if (process.platform === "linux") {
-    const r = sh(`systemctl --user restart dsh-bridge`);
-    if (!r.ok) return { ok: false, status: "failed", detail: (r.stderr || r.stdout).trim() || "systemctl restart 失败" };
-    const a = sh(`systemctl --user is-active dsh-bridge`);
-    return a.ok && a.stdout.trim() === "active"
-      ? { ok: true, status: "running", pid: null }
-      : { ok: false, status: "failed", detail: (a.stdout || a.stderr).trim() };
+    // 【0.6.15】飞牛 fnOS / 群晖这类 NAS 上**没有 user systemd 会话**（插件跑在系统服务里，
+    // 没有 XDG_RUNTIME_DIR）→ `systemctl --user` 只会报 "Failed to connect to bus"，
+    // 于是这一支原本必然失败、且没有任何兜底。现在：有会话就用 systemd（可自愈），
+    // 没有就退到脱离进程（spawnDetachedBridge，与 macOS 的兜底同一条路径）。
+    const hasUserSystemd = Boolean(process.env.XDG_RUNTIME_DIR) && sh("systemctl --user show-environment").ok;
+    if (hasUserSystemd) {
+      const r = sh(`systemctl --user restart dsh-bridge`);
+      if (r.ok) {
+        const a = sh(`systemctl --user is-active dsh-bridge`);
+        if (a.ok && a.stdout.trim() === "active") return { ok: true, status: "running", pid: null };
+        return { ok: false, status: "failed", detail: (a.stdout || a.stderr).trim() };
+      }
+      // 有会话却重启失败：继续往下走脱离进程兜底，绝不留一个"重启失败但没有任何进程"的空档
+    }
+    const d = spawnDetachedBridge();
+    if (d.ok) {
+      return {
+        ok: true,
+        status: "degraded-detached",
+        pid: d.pid,
+        detail: hasUserSystemd
+          ? "systemd --user 重启失败，已改为后台进程运行（现在可用；systemd 恢复后下一次重启会回到托管）"
+          : "本机没有 user systemd 会话（NAS/容器常见），已改为后台进程运行（现在可用，但不会开机自启）",
+      };
+    }
+    return { ok: false, status: "failed", detail: d.error || "systemd 与后台进程均启动失败" };
   }
   return { ok: false, status: "unsupported", detail: `平台 ${process.platform} 不支持自启动` };
 }
@@ -2332,6 +2357,134 @@ async function pluginCmd(argv) {
  *   resolve = dsh 的裸包名解析能不能走通（浏览器半注入面板就靠它）
  *   client = dsh.client.platform 声明在不在
  */
+/**
+ * `dsh-remote doctor` —— **一条命令回答「为什么连不上」**（只读，不改任何东西）。
+ *
+ * 【为什么产品上必须有它】2026-09-25 排查两条用户反馈（fb_7b4ee6ec9862 / fb_4cc2c9df749c）时，
+ * 判断"bridge 到底有没有被拉起来"花了大量时间，而且**只能靠翻日志行数估时间** ——
+ * 因为当时的日志连时间戳都没有，用户端也没有任何一个入口能把
+ * 「上游端口 / 守护状态 / 事件订阅 / 待补发队列」一次性说清楚。
+ * 那两个用户都是 linux + 「starting / bridge 未运行」，而我们的自愈当时在 Linux 上**根本没有实现**
+ * （见 0.6.15 的 startBridgeLinux）：如果有一份这样的自检，用户自己 10 秒就能看出问题在哪。
+ *
+ * 输出四段：① 身份与版本 ② 上游（含来源与探测结论） ③ 进程与自启动 ④ 通道（微信/加密/待补发）
+ * ⑤ 日志尾部（带时间戳）。任何一项失败都只影响那一行，绝不中断整份自检。
+ *
+ * @param {string[]} argv 额外参数（--profile <dir> 透传给插件挂载诊断）
+ */
+async function doctorCmd(argv = []) {
+  const mask = (s) => (s ? String(s).slice(0, 3) + "****" + String(s).slice(-2) : "");
+  const ms = (t) => (t ? new Date(Number(t)).toISOString().replace("T", " ").slice(0, 19) : "-");
+  const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; } };
+  const readText = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return ""; } };
+  const alive = (pid) => {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
+  };
+
+  console.log("dsh-remote 自检（doctor，只读，不改任何东西）");
+  console.log("时间:", new Date().toISOString(), "| 平台:", `${process.platform}/${process.arch}`, "| node:", process.version);
+  console.log("配置目录:", CONFIG_DIR);
+
+  // ── ① 插件与运行环境版本 ────────────────────────────────────────────────
+  const pluginPkg = readJson(path.join(CONFIG_DIR, "node_modules", PLUGIN_ID, "package.json"))
+    || readJson(new URL("./packages/dsh-remote-web/package.json", import.meta.url));
+  const setupVersion = readText(path.join(CONFIG_DIR, ".dsh-setup-version")).trim();
+  console.log("\n① 版本");
+  console.log(`   插件        : ${pluginPkg && pluginPkg.version ? "v" + pluginPkg.version : "（读不到）"}`);
+  console.log(`   运行环境     : ${setupVersion ? "v" + setupVersion : "（未固化 / 未知）"}`);
+  console.log(`   运行环境入口 : ${fs.existsSync(runtimeSetupPath()) ? runtimeSetupPath() : "缺失！"}`);
+  try {
+    const profileDir = resolveProfileDir(argv);
+    if (fs.existsSync(path.join(profileDir, "package.json"))) printPluginDiagnostics(profileDir);
+    else console.log(`   [plugin]  未找到 profile（${profileDir}）`);
+  } catch (e) { console.log(`   [plugin]  诊断失败：${e.message}`); }
+
+  // ── ② 上游 dsh web（bridge 要连的那个本机地址） ──────────────────────────
+  console.log("\n② 上游 dsh web");
+  const hint = resolveUpstreamHint({ relayDir: CONFIG_DIR });
+  const probed = await discoverUpstream({ relayDir: CONFIG_DIR, log: (m) => console.log(`   ${m}`) });
+  console.log(`   提示来源     : ${hint.url ? `${hint.url}（${hint.source}）` : "（无）"}`);
+  console.log(`   最终采用     : ${probed.url}（${probed.source}）`);
+  console.log(`   身份校验     : ${probed.source === "fallback" ? "⚠️ 未找到在听的 dsh web（会一直重试）" : "✅ 已确认为本机 dsh web"}`);
+  if (probed.probed && probed.probed.length) console.log(`   探测过的端口 : ${probed.probed.join(", ")}`);
+
+  // ── ③ 守护与 bridge 进程 ───────────────────────────────────────────────
+  console.log("\n③ 进程与自启动");
+  const watcherPid = readPidFile(WATCHER_PID_FILE);
+  const bridgePid = readPidFile(BRIDGE_PID_FILE);
+  console.log(`   watcher pid  : ${watcherPid || "-"}${watcherPid ? (alive(watcherPid) ? "（在跑）" : "（已死，pid 文件过期）") : ""}`);
+  console.log(`   bridge pid   : ${bridgePid || "-"}${bridgePid ? (alive(bridgePid) ? "（在跑）" : "（已死，pid 文件过期）") : ""}`);
+  // 进程扫描（平台各自的方式）：只报数量，不猜
+  try {
+    const r = process.platform === "win32"
+      ? sh("tasklist /FI \"IMAGENAME eq node.exe\" /FO CSV 2>NUL")
+      : sh("pgrep -fl 'dsh-setup.mjs|dsh-bridge.mjs' 2>/dev/null");
+    const lines = String(r.stdout || "").split("\n").map((l) => l.trim()).filter((l) => l && !/pgrep/.test(l));
+    const watchers = lines.filter((l) => /dsh-setup\.mjs/.test(l));
+    const bridges = lines.filter((l) => /dsh-bridge\.mjs/.test(l)).filter((l) => !/dsh-setup/.test(l));
+    console.log(`   实测进程     : watcher ${watchers.length} 个 / bridge ${bridges.length} 个`);
+    if (watchers.length && !bridges.length) console.log("   ⚠️ 守护在跑、bridge 没起来 —— 这类情况看日志尾部（通常是在等 dsh web 或登录限流）");
+    if (!watchers.length && !bridges.length) {
+      console.log("   ⚠️ 一个进程都没在跑。手动起一次看报错：`dsh-remote run`（前台，能直接看到输出）");
+    }
+  } catch (e) { console.log(`   实测进程     : 扫描失败（${e.message}）`); }
+  if (process.platform === "linux") {
+    const hasUser = Boolean(process.env.XDG_RUNTIME_DIR);
+    console.log(`   自启动       : systemd --user ${hasUser ? "（有 runtime dir）" : "（无 XDG_RUNTIME_DIR → 本机没有 user systemd，插件会用后台进程兜底）"}`);
+    if (hasUser) {
+      const r = sh("systemctl --user is-active dsh-bridge");
+      console.log(`   systemd 状态 : ${r.ok ? r.stdout.trim() : (r.stderr || "").trim() || "查不到"}`);
+    }
+  }
+
+  // ── ④ 通道：E2EE / 微信 / 待补发 ───────────────────────────────────────
+  console.log("\n④ 通道");
+  const e2ee = readJson(path.join(CONFIG_DIR, ".e2ee-state.json"));
+  console.log(`   端到端加密   : ${e2ee ? (e2ee.enabled ? `已启用（${e2ee.reason || "ok"}）` : `未启用（${e2ee.reason || "?"}）`) : "（无状态文件 = 明文）"}`);
+  const wx = readJson(path.join(CONFIG_DIR, ".wechat-state.json"));
+  if (!wx) {
+    console.log("   微信通道     : 未使用（无状态文件）");
+  } else {
+    const outbox = Array.isArray(wx.pending_outbox) ? wx.pending_outbox.length : 0;
+    const faults = wx.last_fault && wx.last_fault.code ? `${wx.last_fault.code}（${ms(wx.last_fault.at)}）` : "无";
+    console.log(`   微信通道     : ${wx.bound ? "已绑定" : "未绑定"} | 最近成功推送 ${ms(wx.last_push_ok_at)}`);
+    console.log(`   待补发通知   : ${outbox ? `⚠️ ${outbox} 条（下次在微信里发一句话就会补上）` : "0 条"}`);
+    console.log(`   最近订阅异常 : ${faults}`);
+    console.log(`   当前会话     : ${wx.current_session_title || "-"}（${wx.current_session_id || "-"}）`);
+    console.log(`   最近完成     : ${wx.last_completed_session_title || "-"}（${ms(wx.last_completed_at)}）`);
+    if (outbox) console.log(`   ℹ️ 入站消息的形状（字段名，用于定位 context_token 缺失）：${wx.inbound_shape || "（还没记到）"}`);
+  }
+  const cfg = loadConfig();
+  console.log(`   账号         : ${mask(cfg.phone) || (cfg.local_key ? "自建（本地密钥）" : "（未登录）")}`);
+  console.log(`   中继/API     : ${cfg.tunnel_url || "-"} ${cfg.api_url ? `| ${cfg.api_url}` : ""}`);
+
+  // ── ⑤ 日志尾部（现在每行都有时间戳，直接能对时间） ─────────────────────
+  console.log("\n⑤ 日志尾部（bridge + 安装）");
+  for (const name of [".dsh-bridge.log", ".dsh-setup-install.log"]) {
+    const p = path.join(CONFIG_DIR, name);
+    if (!fs.existsSync(p)) { console.log(`   ${name}: （无）`); continue; }
+    let tail = "";
+    try {
+      const st = fs.statSync(p);
+      const len = Math.min(st.size, 8 * 1024);
+      const fd = fs.openSync(p, "r");
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, Math.max(0, st.size - len));
+      fs.closeSync(fd);
+      tail = buf.toString("utf8");
+    } catch { /* 读不了就当没有 */ }
+    const lines = tail.split("\n").map((l) => l.trim()).filter(Boolean).slice(-12);
+    console.log(`   --- ${name}（末尾 ${lines.length} 行 / ${p}）---`);
+    for (const l of lines) console.log("   " + l.slice(0, 220));
+    console.log("");
+  }
+  console.log("结论怎么读：① 版本对不上 → 面板点「一键修复 / 重装运行环境」；");
+  console.log("           ② 上游 fallback → 把 dsh web 起在本机可回环访问的端口（插件会自动发现）；");
+  console.log("           ③ 没有任何进程 → 先手动 `dsh-remote run` 看前台输出；");
+  console.log("           ④ 待补发 > 0 → 在微信里随便发一句话即可补收。");
+}
+
 function printPluginDiagnostics(profileDir) {
   const nmPlugin = path.join(profileDir, "node_modules", PLUGIN_ID);
   const link = describePluginLink(profileDir);
@@ -2417,6 +2570,7 @@ else if (cmd === "settings") settingsHint();
 else if (cmd === "run") await runBridge();
 else if (cmd === "plugin") await pluginCmd(process.argv.slice(3));
 else if (cmd === "repair") repairProfile(process.argv.slice(3));
+else if (cmd === "doctor") await doctorCmd(process.argv.slice(3));
 else if (cmd === "status") {
   const cfg = loadConfig();
   const local = Boolean(cfg.local_key);