@mrrisega/dsh-remote 0.6.14 → 0.6.15

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

@@ -31,7 +31,8 @@ import {
   toFormatterNode,
   CONTROL_HEADER
 } from "../wechat-runtime.mjs";
-import { saveAccount, loadState, formatNotification, SessionCooldown } from "../wechat-channel.mjs";
+import * as channelMod from "../wechat-channel.mjs";
+  import { saveAccount, loadState, formatNotification, SessionCooldown } from "../wechat-channel.mjs";
 import { NODE_KINDS } from "../dsh-events.mjs";
 
 const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), "wc-rt-"));
@@ -61,6 +62,9 @@ function fakeIlink(handler) {
       }
       if (url.pathname.endsWith("/sendmessage")) {
         try { state.sends.push(JSON.parse(body)); } catch { state.sends.push({ raw: body }); }
+        // 可选的发送结果覆盖：用例用它模拟真机上的 `ret=-2 errmsg=prepare failed`
+        // （平台侧发送**间歇性**失败，正是"任务跑完没收到推送"那次的现场）。
+        if (handler && handler.onSendMessage) return handler.onSendMessage(state, reply);
         return reply({ ret: 0, message_id: "m" + state.sends.length });
       }
       if (url.pathname.endsWith("/notifystart")) { state.notifyStart += 1; return reply({ ret: 0 }); }
@@ -642,6 +646,53 @@ test("★ v2:完成推送带会话名称 + 结论,而不只是「任务已停止
   }
 });
 
+test("★ 0.6.15：完成推送必须把「当前会话」切到刚跑完的那个（否则回话会发进上一次的会话）", async () => {
+  // 业主实测：B 任务跑完推了结论，他在微信里直接回一句"再改一下"，那条消息却发给了
+  // **上一次的当前会话 A** —— A 平白多了一条指令，B 永远收不到。
+  const ilink = await fakeIlink();
+  try {
+    const sub = makeFakeSubscriber();
+    sub.sessionsFixture = [
+      { sessionId: "session-b", title: "刚跑完的活", running: false, cwd: "/p" },
+      { sessionId: "session-a", title: "早先的会话", running: false, cwd: "/p" }
+    ];
+    sub.summaryFixture = "已改完。";
+    const { rt, relayDir } = await boundRuntime(ilink, { subscriber: sub });
+    rt.currentSessionId = "session-a";
+    rt.currentSessionTitle = "早先的会话";
+
+    await rt.notify({ kind: NODE_KINDS.TURN_END, sessionId: "session-b", reason: "completed", at: 1 });
+    assert.equal(rt.currentSessionId, "session-b", "推送完必须切到刚完成的会话");
+    assert.equal(loadState(relayDir).current_session_id, "session-b", "切换必须落盘（重启后仍然对）");
+
+    // 现在回一句纯文本 → 必须发给 B，而不是 A
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "再改一下" } }] });
+    const prompt = sub.calls.filter((c) => c.m === "promptSession").pop();
+    assert.ok(prompt, "纯文本必须派给会话");
+    assert.equal(prompt.sessionId, "session-b", "回话必须发给**刚完成**的那个会话");
+    assert.equal(prompt.text, "再改一下");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 0.6.15：已经是当前会话的完成推送不重复写状态（幂等）", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const sub = makeFakeSubscriber();
+    sub.sessionsFixture = [{ sessionId: "session-s1", title: "同一个任务", running: false, cwd: "/p" }];
+    sub.summaryFixture = "完成。";
+    const { rt } = await boundRuntime(ilink, { subscriber: sub });
+    rt.currentSessionId = "session-s1";
+    rt.currentSessionTitle = "同一个任务";
+    await rt.notify({ kind: NODE_KINDS.TURN_END, sessionId: "session-s1", reason: "completed", at: 1 });
+    assert.equal(rt.currentSessionId, "session-s1");
+    assert.match(lastText(ilink.state), /同一个任务/);
+  } finally {
+    await ilink.close();
+  }
+});
+
 test("★ 分层:免费档的完成推送不能承诺「回复就能接着做」,要改成会员说明 + App 链接", async () => {
   // 默认那句「回复这条消息就能接着这个会话往下做」对免费用户是**空头承诺**:
   // 他回复纯文本只会拿到付费引导。文案必须跟着档位走,否则用户会以为产品坏了。
@@ -1745,3 +1796,219 @@ test("★ 日报占位一天一个,换天时会清掉旧占位(不攒文件)", a
     await ilink.close();
   }
 });
+
+// ---------------------------------------------------------------------------
+// 出站必须回带 context_token（2026-09-23 业主实测「没收到微信通道」）
+//
+// 平台要求出站消息带回「这条会话的上下文令牌」，而它只出现在**入站消息**里
+// （官方实现：messaging/send.js 的 buildTextMessageReq → `msg.context_token`；
+//  腾讯自家插件同样是「入站取出 → 按 (账号,用户) 缓存 → 发送时回带」）。
+// 我们以前从不发它 → 真机日志 `sendMessage: ret=-2 errmsg=prepare failed`：消息发不出去。
+// ---------------------------------------------------------------------------
+
+test("★★ 出站必须回带 context_token(入站带来什么就回什么)", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const { rt } = await boundRuntime(ilink, { subscriber: makeFakeSubscriber(), tier: "pro" });
+    // 真实形状：入站消息带顶层 context_token；发送目标是账号的 userId
+    await rt.handleInbound({
+      from_user_id: "user-1", context_token: "CT-abc-123",
+      item_list: [{ type: 1, text_item: { text: "/status" } }]
+    });
+    const last = ilink.state.sends.at(-1);
+    assert.equal(last.msg.context_token, "CT-abc-123",
+      "★出站 msg 必须回带 context_token —— 不带就是 ret=-2 prepare failed(消息根本发不出去)");
+    assert.equal(last.msg.to_user_id, "user-1");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 没有 context_token 时**完全不带这个键**(而不是空串)", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const { rt } = await boundRuntime(ilink, { subscriber: makeFakeSubscriber(), tier: "pro" });
+    await rt.handleInbound({ from_user_id: "user-1", item_list: [{ type: 1, text_item: { text: "/status" } }] });
+    const last = ilink.state.sends.at(-1);
+    assert.ok(!("context_token" in last.msg),
+      "★拿不到令牌时不得塞空串(与官方 `contextToken ?? undefined` 同口径)");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ context_token 落盘持久化:bridge 重启后不必等用户先说话也能发", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const first = await boundRuntime(ilink, { subscriber: makeFakeSubscriber(), tier: "pro" });
+    await first.rt.handleInbound({
+      from_user_id: "user-1", context_token: "CT-persist-9",
+      item_list: [{ type: 1, text_item: { text: "/status" } }]
+    });
+    // 同一个 relayDir 上新建一个 runtime（= bridge 重启）
+    const rt2 = createWeChatRuntime({
+      relayDir: first.relayDir, upstream: "http://127.0.0.1:1", secret: SECRET, tier: "pro", logger: quietLogger()
+    });
+    rt2.subscriber = makeFakeSubscriber();
+    await rt2.reply("user-1", "重启后的第一条推送");
+    assert.equal(ilink.state.sends.at(-1).msg.context_token, "CT-persist-9",
+      "★重启后必须从状态文件恢复令牌 —— 否则重启后的第一条通知(最该送达的那条)发不出去");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 解绑必须清掉 context_token(换绑后不能拿上一个人的上下文去发)", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const { rt } = await boundRuntime(ilink, { subscriber: makeFakeSubscriber(), tier: "pro" });
+    await rt.handleInbound({
+      from_user_id: "user-1", context_token: "CT-old-user",
+      item_list: [{ type: 1, text_item: { text: "/status" } }]
+    });
+    await rt.unbind();
+    assert.equal(rt.channel.client.contextToken, "", "内存里必须清掉");
+    const st = JSON.parse(fs.readFileSync(path.join(rt.relayDir, ".wechat-state.json"), "utf8"));
+    assert.ok(!st.context_token, `状态文件里也必须清掉,实际:${JSON.stringify(st.context_token)}`);
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ extractContextToken 防御式:形状不认识一律当没有,绝不猜", () => {
+  const { extractContextToken } = channelMod;
+  assert.equal(extractContextToken(null), "");
+  assert.equal(extractContextToken("CT-x"), "", "字符串消息没有这个字段");
+  assert.equal(extractContextToken({}), "");
+  assert.equal(extractContextToken({ context_token: "" }), "", "空串=没有");
+  assert.equal(extractContextToken({ context_token: "   " }), "", "纯空白=没有");
+  assert.equal(extractContextToken({ context_token: 123 }), "", "非字符串=没有");
+  assert.equal(extractContextToken({ context_token: " CT-1 " }), "CT-1", "合法值去首尾空白");
+  assert.equal(extractContextToken({ contextToken: "CT-2" }), "CT-2", "兼容驼峰写法");
+});
+
+// ═════════════ 2026-09-25 事故：完成推送"消失" + 回话跑进另一个会话 ═════════════
+//
+// 现场（业主）：任务跑完一条微信都没收到；他在微信里回了一句，结果**发进了上一个会话**。
+// 日志证据：48 条 `sendmessage 失败:sendMessage: ret=-2 errmsg=prepare failed`
+//   —— 平台侧发送是**间歇性**失败的，而旧实现失败即丢弃：那条"任务跑完了"永远消失了。
+// 状态证据：`current_session_id` 停在几天前的旧会话上（因为切换只在推送成功后发生）。
+
+test("★ 事故锁：主动推送失败**不能消失** —— 入队，并在下一次入站时补发（带「补发」标记）", async () => {
+  let failSends = true;
+  const ilink = await fakeIlink({
+    onSendMessage: (_state, reply) => (failSends
+      ? reply({ ret: -2, errmsg: "prepare failed" })
+      : reply({ ret: 0, message_id: "ok" })),
+  });
+  try {
+    const sub = makeFakeSubscriber();
+    sub.sessionsFixture = [{ sessionId: "session-done", title: "跑完的活", running: false, cwd: "/p" }];
+    sub.summaryFixture = "做完了。";
+    const { rt, relayDir } = await boundRuntime(ilink, { subscriber: sub });
+    const stateOf = () => JSON.parse(fs.readFileSync(path.join(relayDir, ".wechat-state.json"), "utf8"));
+
+    // ① 平台侧发不出去 → 完成推送必须**入队**，而不是丢掉
+    await rt.notify({ kind: NODE_KINDS.TURN_END, sessionId: "session-done", reason: "completed", at: 1 });
+    const queued = stateOf().pending_outbox || [];
+    assert.equal(queued.length, 1, "★ 推送失败必须入队（旧实现直接丢，用户永远不知道这条存在过）");
+    assert.match(String(queued[0].text), /跑完的活|做完了/, "入队的应该是那条完整正文");
+
+    // ② 平台恢复 + 用户随便发一条 → 补发必须跟上
+    failSends = false;
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "/status" } }] });
+    await waitFor(() => (stateOf().pending_outbox || []).length === 0);
+    const resent = allTexts(ilink.state).filter((t) => t.startsWith("（补发）"));
+    assert.equal(resent.length, 1, "★ 恢复后必须把积压补上（且只补一次）");
+    assert.match(resent[0], /跑完的活/, "补发的就是那条完成通知");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 事故锁：静音（/quiet）也要记下「最近完成的任务」，回话不能跑进上一个会话", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const sub = makeFakeSubscriber();
+    sub.sessionsFixture = [
+      { sessionId: "session-new", title: "刚跑完的活", running: false, cwd: "/p" },
+      { sessionId: "session-old", title: "早先的会话", running: false, cwd: "/p" },
+    ];
+    sub.summaryFixture = "完成。";
+    const { rt, relayDir } = await boundRuntime(ilink, { subscriber: sub });
+    rt.currentSessionId = "session-old";
+    rt.currentSessionTitle = "早先的会话";
+    // 静音：完成推送**不会**发出来（用户主动要求的"别打扰"）
+    rt.channel.writeState({ quiet: true });
+
+    await rt.notify({ kind: NODE_KINDS.TURN_END, sessionId: "session-new", reason: "completed", at: 2 });
+    assert.equal(lastText(ilink.state).includes("刚跑完的活"), false, "静音时不推送（前置条件）");
+
+    // 用户下一秒回话 → 必须发给他**刚跑完**的那个会话，而不是旧会话
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "再改一下" } }] });
+    const prompt = sub.calls.filter((c) => c.m === "promptSession").pop();
+    assert.ok(prompt, "纯文本必须派给会话");
+    assert.equal(prompt.sessionId, "session-new",
+      "★ 静音只表示不打扰，不表示「当它没发生过」—— 回话目标必须是最近完成的任务");
+    assert.match(lastText(ilink.state), /刚跑完的活/, "确认文案里要说清发给了哪个会话");
+    assert.match(lastText(ilink.state), /已自动切为回复对象/, "自动切换要如实告知（不能悄悄改目标）");
+    void relayDir;
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 事故锁：用户主动 /use 切走的会话不能被「最近完成」抢回去", async () => {
+  const ilink = await fakeIlink();
+  try {
+    const sub = makeFakeSubscriber();
+    sub.sessionsFixture = [
+      { sessionId: "session-done", title: "刚跑完的活", running: false, cwd: "/p" },
+      { sessionId: "session-mine", title: "我要聊的", running: false, cwd: "/p" },
+    ];
+    sub.summaryFixture = "完成。";
+    const { rt } = await boundRuntime(ilink, { subscriber: sub });
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "/use 2" } }] });
+    assert.equal(rt.currentSessionId, "session-mine", "前置条件：/use 切到了 2 号");
+    await rt.notify({ kind: NODE_KINDS.TURN_END, sessionId: "session-done", reason: "completed", at: 3 });
+
+    // 完成事件在处理时会把它自己设为回复目标（这是产品口径）；但用户**之后**再切回去要算数：
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "/use 2" } }] });
+    await rt.handleInbound({ from_user_id: "u", item_list: [{ type: 1, text_item: { text: "继续聊我的" } }] });
+    const prompt = sub.calls.filter((c) => c.m === "promptSession").pop();
+    assert.equal(prompt.sessionId, "session-mine",
+      "★ 对表只在「指针落后于最近完成」时切换；用户明确选过的会话不许被抢回去");
+  } finally {
+    await ilink.close();
+  }
+});
+
+test("★ 事故锁：订阅 fault 必须落到日志 + 状态（旧实现只 emit、没人接 → 全静默）", async () => {
+  // 那次「一条推送都没有、日志里也没有任何报错」的根因就在这类静默里：
+  // `#emitFault` 只 emit('fault')，而运行时没接这个事件 —— follow 失败/发现失败/流上限
+  // 全都不留任何痕迹。现在必须：① 一条 warn 进 bridge 日志；② 非预期的记进状态文件。
+  const ilink = await fakeIlink();
+  try {
+    const warns = [];
+    const sub = makeFakeSubscriber();
+    const { rt, relayDir } = await boundRuntime(ilink, { subscriber: sub });
+    rt.logger = { info() {}, warn: (m) => warns.push(String(m)), error() {}, debug() {}, addSecret() {} };
+    await rt.startChannel(); // 真实接线：#startSubscriber() → 给注入的订阅器挂 handler
+    try {
+      sub.emit("fault", { code: "follow-limit", message: "follow 流已达上限 8", sessionId: "session-x", expected: false });
+      const st = JSON.parse(fs.readFileSync(path.join(relayDir, ".wechat-state.json"), "utf8"));
+      assert.ok(warns.some((m) => m.includes("订阅异常 follow-limit")),
+        `订阅异常必须进日志（否则事后无从查起），实际:${JSON.stringify(warns)}`);
+      assert.equal(st.last_fault && st.last_fault.code, "follow-limit", "非预期的订阅异常要记进状态供面板显示");
+
+      // 预期内的（子代理会话必然被拒 / 会话刚被删）只记日志，不该污染故障状态
+      sub.emit("fault", { code: "session/agent-busy", message: "busy", sessionId: "sub-1", expected: true });
+      const st2 = JSON.parse(fs.readFileSync(path.join(relayDir, ".wechat-state.json"), "utf8"));
+      assert.equal(st2.last_fault.code, "follow-limit", "expected 的异常不该覆盖真正的故障");
+    } finally {
+      await rt.stopChannel();
+    }
+  } finally {
+    await ilink.close();
+  }
+});

package/clients/dsh-remote/upstream-discovery.mjs

@@ -158,13 +158,140 @@ export function dshProcessPids(platform = process.platform) {
     .filter((n) => Number.isInteger(n) && n > 1 && n !== process.pid);
 }
 
+// ---------- 「本机所有回环监听端口」：NAS 上的救命稻草（0.6.15） ----------
+//
+// 【为什么必须加这一层】飞牛 fnOS 用户诊断（2026-09-25，插件 0.6.14）：
+//   上游 dsh web: http://127.0.0.1:3080（默认值 3080（**未取到 dsh web 实际监听端口**），⚠️ 不可达）
+//   他的 dsh web 实际在 **2298**（fnOS 应用里配的内部监听端口），而上面五条发现路径**全都没命中**：
+//     · 插件半的 ctx.webServer.port 没取到（该环境下拿不到）；
+//     · `lsof` 在 NAS 上**根本没装**；`pgrep -f dsh` 也可能没有；
+//     · 静态候选只有 3080 与 Desktop 的 43120 区间 —— 2298 永远不在里面。
+//   于是用户去改端口号（改成 20xx、又改回 3080）当然都没用：**没有任何一条路径会去试 2298**。
+//
+// 做法：直接把"这台机器上正在 LISTEN 的回环端口"全列出来当候选，再逐个做**身份校验**。
+// 为什么敢全列：身份校验（`looksLikeDshWeb` / `looksLikeDshRemoteSelf`）会拒掉所有陌生服务，
+// 多探几个端口只是几十毫秒；而漏掉一个端口就是"用户永远连不上"。
+
+/** 解析 /proc/net/tcp 一行里的本地地址与状态（Linux 无依赖：不需要 ss/netstat/lsof）。 */
+function parseProcNetLine(line) {
+  const cols = String(line || "").trim().split(/\s+/);
+  if (cols.length < 4) return null;
+  const local = cols[1];
+  const state = cols[3];
+  const m = /^([0-9A-Fa-f]{1,32}):([0-9A-Fa-f]{1,4})$/.exec(local || "");
+  if (!m) return null;
+  return { hex: m[1], port: parseInt(m[2], 16), state: String(state).toUpperCase() };
+}
+
+/** 32 位小端 hex（/proc/net/tcp）→ IPv4 点分串。 */
+function ipv4OfHex(hex) {
+  const h = String(hex).padStart(8, "0").slice(-8);
+  const bytes = [h.slice(6, 8), h.slice(4, 6), h.slice(2, 4), h.slice(0, 2)].map((x) => parseInt(x, 16));
+  return bytes.join(".");
+}
+
+/** 128 位 hex（/proc/net/tcp6）→ 是否回环（::1）。 */
+function isIpv6LoopbackHex(hex) {
+  const h = String(hex).toLowerCase().padStart(32, "0");
+  // ::1 在 /proc 里按 4 组小端 32 位存放 → 末组为 01000000，其余全 0
+  return /^0{24}01000000$/.test(h);
+}
+
+/** Linux：直接读 /proc/net/tcp{,6}（内核真值，NAS 上不需要任何外部命令）。 */
+export function procNetLoopbackPorts() {
+  const ports = new Set();
+  for (const file of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+    let text = "";
+    try { text = fs.readFileSync(file, "utf8"); } catch { continue; }
+    for (const line of text.split("\n").slice(1)) {
+      const row = parseProcNetLine(line);
+      if (!row || row.state !== "0A") continue; // 0A = LISTEN
+      const loop = file.endsWith("tcp6")
+        ? isIpv6LoopbackHex(row.hex)
+        : ipv4OfHex(row.hex).startsWith("127.");
+      // 通配绑定（0.0.0.0 / ::）也收：dsh web 绑 0.0.0.0 时回环照样能连
+      const wildcard = file.endsWith("tcp6") ? /^0+$/.test(String(row.hex)) : ipv4OfHex(row.hex) === "0.0.0.0";
+      if (loop || wildcard) ports.add(row.port);
+    }
+  }
+  return [...ports];
+}
+
+/** `ss -ltnH` 输出里的本地端口（Linux；部分精简系统没有 /proc，或反之）。 */
+function ssLoopbackPorts() {
+  const ports = new Set();
+  const out = tryExec("ss", ["-ltnH"], 5000) || tryExec("ss", ["-ltn"], 5000);
+  for (const line of out.split("\n")) {
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 4) continue;
+    // ss 的本地地址是第 4 列（State Recv-Q Send-Q Local Address:Port Peer Address:Port）
+    const m = /[:.](\d+)$/.exec(cols[3] || "");
+    if (m) ports.add(Number(m[1]));
+  }
+  return [...ports];
+}
+
+/** `netstat -ltn` 输出里的本地端口（BSD/GNU 两种格式都认）。 */
+function netstatLoopbackPorts() {
+  const ports = new Set();
+  const out = (tryExec("netstat", ["-ltn"], 5000) || tryExec("netstat", ["-an"], 6000));
+  for (const line of out.split("\n")) {
+    if (!/listen/i.test(line) && !/^tcp/i.test(line)) continue;
+    const m = /(?:^|\s)(?:\d{1,3}\.){3}\d{1,3}[:.](\d+)|\[?::1?\]?[:.](\d+)/.exec(line);
+    const p = m ? Number(m[1] || m[2]) : 0;
+    if (p > 0 && p < 65536) ports.add(p);
+  }
+  return [...ports];
+}
+
+/** `lsof -nP -iTCP -sTCP:LISTEN` 输出里的本地端口（macOS/装了 lsof 的 Linux）。 */
+function lsofLoopbackPorts() {
+  const ports = new Set();
+  const out = tryExec("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], 6000);
+  for (const line of out.split("\n")) {
+    const m = /(?:TCP\s+)?(?:\d{1,3}\.){3}\d{1,3}:(\d+)\s*\(LISTEN\)/.exec(line) || /TCP\s+\*:(\d+)/.exec(line);
+    if (m) ports.add(Number(m[1]));
+  }
+  return [...ports];
+}
+
+/**
+ * 本机所有回环（含通配绑定）LISTEN 端口，去重。
+ * 多来源合并而不是"取第一个成功的"：NAS 上 lsof/ss/netstat/pgrep 各有缺失，
+ * 只有合起来才够全；重复端口由 Set 消化，代价只是多读几个文件。
+ */
+export function allLoopbackListeningPorts(platform = process.platform) {
+  const ports = new Set();
+  const push = (list) => { for (const p of list) { const n = Number(p); if (Number.isInteger(n) && n > 0 && n < 65536) ports.add(n); } };
+  if (platform === "win32") {
+    for (const line of tryExec("netstat", ["-ano"], 6000).split(/\r?\n/)) {
+      if (!/LISTENING/i.test(line)) continue;
+      const cols = line.trim().split(/\s+/);
+      const m = /:(\d+)$/.exec(cols[1] || "");
+      if (m) push([Number(m[1])]);
+    }
+    return [...ports];
+  }
+  if (platform === "linux") {
+    push(procNetLoopbackPorts()); // 无依赖，优先
+    push(ssLoopbackPorts());
+  }
+  push(lsofLoopbackPorts());
+  push(netstatLoopbackPorts());
+  return [...ports];
+}
+
 /**
  * 候选列表（已去重，按"可能性"排序），每项带**来源标注**（用于日志与测试断言）。
  * 顺序 = 提示里的端口 → 显式额外端口 → DSH_WEB_URL 的端口 → 祖先/dsh 进程实测监听端口
- *        → 3080 → Desktop 默认端口区间。
+ *        → **本机所有回环监听端口** → 3080 → Desktop 默认端口区间。
+ *
+ * 「所有回环监听端口」排在静态候选之前：NAS 上 dsh web 的端口（实测 2298）**只可能**从这一层找到，
+ * 排在 3080 之后就等于白加（3080 探测失败之前不会去试它，而静态候选有 12 个 Desktop 端口）。
+ * 最后仍留静态候选兜底（宿主把端口藏得很深、/proc 也没有的极端情况）。
  * @returns {Array<{port:number, source:string}>}
  */
-export function candidatePorts({ relayDir = "", env = process.env, extraPorts = [], platform = process.platform } = {}) {
+export function candidatePorts({ relayDir = "", env = process.env, extraPorts = [], platform = process.platform, listenPorts = null } = {}) {
   const out = [];
   const seen = new Set();
   const push = (p, source) => {
@@ -179,6 +306,10 @@ export function candidatePorts({ relayDir = "", env = process.env, extraPorts =
   push(portOf(upstreamFromDshWebUrl(env)), "dsh_web_url");
   const pids = [...new Set([process.pid, ...ancestorPids(process.pid, 6, platform), ...dshProcessPids(platform)])];
   for (const pid of pids) for (const p of listeningPortsOfPid(pid, platform)) push(p, "process");
+  // ★ 本机所有回环 LISTEN 端口（0.6.15）：NAS 上 dsh web 在 2298 这类非默认端口时唯一的发现路径。
+  //   调用方可以注入 listenPorts（测试用），避免用例依赖开发机真实监听表。
+  const listen = Array.isArray(listenPorts) ? listenPorts : allLoopbackListeningPorts(platform);
+  for (const p of listen) push(p, "listen");
   push(3080, "static");
   for (let i = 0; i < DESKTOP_PORT_SCAN; i++) push(DESKTOP_DEFAULT_PORT + i, "static");
   return out;
@@ -208,8 +339,28 @@ export function looksLikeDshWeb(status, text) {
   return DSH_WEB_MARKERS.some((m) => body.includes(m));
 }
 
+/** 本插件自己的路由（`GET /dsh-remote/self`）—— 只有"宿主这台 dsh web"才会应答。 */
+export const DSH_REMOTE_SELF_PATH = "/dsh-remote/self";
+
+/**
+ * 身份校验的**第二判据**：本插件自己的 `/dsh-remote/self`。
+ *
+ * 为什么需要它：`looksLikeDshWeb` 依赖 dsh web 首页的 HTML 特征（`__ModuleLoader__` 等），
+ * 而首页在有些部署下是**跳转/登录页/自定义门户**，特征一个字都不出现 —— 于是明明端口就是对的，
+ * 却被判成"陌生服务"。`/dsh-remote/self` 由**本插件**注册在同一个 web server 上，
+ * 返回 `{"ok":true,"version":…,"channel":…,"relayDir":…}`，是本机最硬的同一性证据
+ * （它跑在同一条隧道上，能应答就说明这个端口就是宿主的 dsh web）。
+ */
+export function looksLikeDshRemoteSelf(status, text) {
+  if (Number(status) !== 200) return false;
+  const body = String(text || "");
+  if (!body.includes("relayDir")) return false;
+  return body.includes('"channel"') || body.includes('"runtimeReady"') || body.includes("dsh-remote");
+}
+
 /**
- * 探测一个候选：GET `/`，带身份校验。
+ * 探测一个候选：先 GET `/`（dsh web 首页特征），不中再 GET `/dsh-remote/self`（本插件特征）。
+ * 两条判据任一命中即通过。
  * @returns {Promise<boolean>}
  */
 export async function probeDshWeb(url, { timeoutMs = PROBE_TIMEOUT_MS, fetchImpl } = {}) {
@@ -217,34 +368,38 @@ export async function probeDshWeb(url, { timeoutMs = PROBE_TIMEOUT_MS, fetchImpl
   if (!target) return false;
   const doFetch = fetchImpl || globalThis.fetch;
   if (typeof doFetch !== "function") return false;
-  try {
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), timeoutMs);
-    let res;
-    try {
-      // redirect: manual —— 不跟随跳转（跳走的多半不是我们要的宿主）
-      res = await doFetch(`${target}/`, { signal: ac.signal, redirect: "manual" });
-    } finally {
-      clearTimeout(timer);
-    }
-    const status = Number(res && res.status) || 0;
-    if (status >= 500) return false;
-    // 只读前 8KB 足够命中特征；读流失败按"不是"处理（宁可少一个候选，不可误接）
-    let text = "";
+  const once = async (path, check) => {
     try {
-      if (res.body && typeof res.body.getReader === "function") {
-        const reader = res.body.getReader();
-        const { value } = await reader.read();
-        text = value ? Buffer.from(value).toString("utf8") : "";
-        try { await reader.cancel(); } catch { /* ignore */ }
-      } else if (typeof res.text === "function") {
-        text = await res.text();
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      let res;
+      try {
+        // redirect: manual —— 不跟随跳转（跳走的多半不是我们要的宿主）
+        res = await doFetch(`${target}${path}`, { signal: ac.signal, redirect: "manual" });
+      } finally {
+        clearTimeout(timer);
       }
-    } catch { /* 读失败 → text 为空 → 判否 */ }
-    return looksLikeDshWeb(status, text.slice(0, 8192));
-  } catch {
-    return false;
-  }
+      const status = Number(res && res.status) || 0;
+      if (status >= 500) return false;
+      // 只读前 8KB 足够命中特征；读流失败按"不是"处理（宁可少一个候选，不可误接）
+      let text = "";
+      try {
+        if (res.body && typeof res.body.getReader === "function") {
+          const reader = res.body.getReader();
+          const { value } = await reader.read();
+          text = value ? Buffer.from(value).toString("utf8") : "";
+          try { await reader.cancel(); } catch { /* ignore */ }
+        } else if (typeof res.text === "function") {
+          text = await res.text();
+        }
+      } catch { /* 读失败 → text 为空 → 判否 */ }
+      return check(status, text.slice(0, 8192));
+    } catch {
+      return false;
+    }
+  };
+  if (await once("/", looksLikeDshWeb)) return true;
+  return once(DSH_REMOTE_SELF_PATH, looksLikeDshRemoteSelf);
 }
 
 /**
@@ -261,6 +416,7 @@ export async function discoverUpstream({
   fetchImpl,
   platform = process.platform,
   extraPorts = [],
+  listenPorts = null,
   log
 } = {}) {
   const hint = resolveUpstreamHint({ relayDir, env });
@@ -273,7 +429,7 @@ export async function discoverUpstream({
 
   // ③ 候选并行探测(本地端口,拒绝是瞬时的;并行是为了不让 watcher 卡住)
   const hintPort = portOf(hint.url);
-  const entries = candidatePorts({ relayDir, env, platform, extraPorts }).filter((e) => e.port !== hintPort);
+  const entries = candidatePorts({ relayDir, env, platform, extraPorts, listenPorts }).filter((e) => e.port !== hintPort);
   const results = await Promise.all(entries.map(async (e) => ({ ...e, ok: await probeDshWeb(`http://127.0.0.1:${e.port}`, { timeoutMs, fetchImpl }) })));
   const hit = results.find((r) => r.ok);
   if (hit) {