dsh-mobile-plugin 0.1.63 → 0.1.65

package/lib/relay/lan-network.cjs

@@ -48,10 +48,14 @@ function interfaceRank(name) {
   return 3
 }
 
-// Structured view of the usable LAN endpoints. The relay's `normalizeLanMetadata`
-// and the app's `candidateUrls()` both accept this shape, so callers that want
-// interface metadata (for diagnostics or smarter ordering) should prefer it.
-function lanInterfaces(port, interfaces = os.networkInterfaces()) {
+/**
+ * 扫一遍网卡，把 `accept` 认的 IPv4 地址收成候选（剔除虚拟/VPN 网卡、按物理网卡优先级
+ * 排序、去重、最多 16 条）。
+ *
+ * `lanInterfaces` 与 `publicInterfaces` 共用这一段：两者的差别**只在 accept**——一个挑私网、
+ * 一个挑公网。网卡黑名单与排序规则必须一模一样，否则同一台机器上两份候选会给出互相矛盾的顺序。
+ */
+function collectEndpoints(interfaces, accept) {
   const found = []
   let order = 0
   for (const [name, entries] of Object.entries(interfaces || {})) {
@@ -60,7 +64,7 @@ function lanInterfaces(port, interfaces = os.networkInterfaces()) {
     for (const entry of entries || []) {
       if (!entry || entry.internal) continue
       if (entry.family !== 'IPv4' && entry.family !== 4) continue
-      if (!isPrivateLanAddress(entry.address)) continue
+      if (!accept(entry.address)) continue
       found.push({ name, address: entry.address, order: current })
     }
   }
@@ -73,7 +77,17 @@ function lanInterfaces(port, interfaces = os.networkInterfaces()) {
       return true
     })
     .slice(0, 16)
-    .map((item) => ({ url: `http://${item.address}:${port}`, interface: item.name, family: 'IPv4', address: item.address }))
+}
+
+function toCandidates(list, port) {
+  return list.map((item) => ({ url: `http://${item.address}:${port}`, interface: item.name, family: 'IPv4', address: item.address }))
+}
+
+// Structured view of the usable LAN endpoints. The relay's `normalizeLanMetadata`
+// and the app's `candidateUrls()` both accept this shape, so callers that want
+// interface metadata (for diagnostics or smarter ordering) should prefer it.
+function lanInterfaces(port, interfaces = os.networkInterfaces()) {
+  return toCandidates(collectEndpoints(interfaces, isPrivateLanAddress), port)
 }
 function lanUrls(port, interfaces = os.networkInterfaces()) {
   return lanInterfaces(port, interfaces).map((candidate) => candidate.url)
@@ -82,4 +96,80 @@ function lanCandidates(port, interfaces = os.networkInterfaces()) {
   return lanInterfaces(port, interfaces)
 }
 
-module.exports = { ipv4Number, isPrivateLanAddress, isVpnInterface, isVirtualInterface, interfaceRank, lanInterfaces, lanUrls, lanCandidates }
+/**
+ * 公网地址：同一遍扫描，挑出**真能从外网拨过来**的那些。
+ *
+ * 判据是「不在任何特殊网段里」，而不是「不是 RFC1918」——后者会把 169.254/16（链路本地）、
+ * 100.64/10（CGNAT）、198.18/15（基准测试）这些同样拨不通的地址当成公网地址发出去。
+ * 实测踩过：macOS 上一块多出来的网卡带着 `169.254.87.131`，被当成「公网地址」摆到面板上。
+ * 这份特殊网段清单和本文件开头那句「intentionally excludes VPN/CGNAT, link-local and
+ * benchmarking/test ranges」是同一条口径。
+ *
+ * 为什么不并进 `lanInterfaces`：那份列表的语义是「手机和这台机器在同一个 Wi-Fi 里能直连的
+ * 地址」，混进公网地址会改掉 App 的探测顺序与中转上报的内容（`test/lan-network.test.cjs`
+ * 既钉着「WAF 容器的 192.168.0.1 被当成候选」那次事故，也钉着「只有公网地址的机器候选为空」）。
+ *
+ * 需要公网地址的地方只有两处，都在取回来之后再决定怎么用：面板显示「手机该填哪个地址」，
+ * 以及一台只有公网 IP 的机器上给不出任何私网候选时的兜底（见 `../impl.js` 的
+ * `safeLanCandidates`）。
+ */
+const NOT_PUBLIC_RANGES = [
+  [0x00000000, 0x00ffffff], // 0/8        “本网络”
+  [0x64400000, 0x647fffff], // 100.64/10  CGNAT（运营商级 NAT，外网拨不进来）
+  [0x7f000000, 0x7fffffff], // 127/8      回环
+  [0xa9fe0000, 0xa9feffff], // 169.254/16 链路本地
+  [0xc6120000, 0xc613ffff], // 198.18/15  基准测试
+]
+function isPublicAddress(address) {
+  const value = ipv4Number(address)
+  if (value === null) return false
+  if (isPrivateLanAddress(address)) return false
+  // 224/4 起是组播与保留（含 255.255.255.255）。
+  if (value >= 0xe0000000) return false
+  return !NOT_PUBLIC_RANGES.some(([start, end]) => inRange(value, start, end))
+}
+function publicInterfaces(port, interfaces = os.networkInterfaces()) {
+  return toCandidates(collectEndpoints(interfaces, isPublicAddress), port)
+}
+function publicUrls(port, interfaces = os.networkInterfaces()) {
+  return publicInterfaces(port, interfaces).map((candidate) => candidate.url)
+}
+function publicCandidates(port, interfaces = os.networkInterfaces()) {
+  return publicInterfaces(port, interfaces)
+}
+
+/**
+ * 对外公布的候选地址：**先私网，一个都没有时才退到公网**。
+ *
+ * 为什么要有这一条：`lanInterfaces` 只认 RFC1918，于是「DSH 装在一台只有公网 IP 的服务器上」
+ * 时那份列表**恒为空** —— 二维码里一个可拨的地址都没有，「手机直连」这条路从根上走不通
+ * （2026-10-11 用户报的现场）。只在为空时才退：有私网地址的机器，候选列表一个字都不变。
+ *
+ * 取不到网卡（异常）时回空清单、绝不抛：它喂的是二维码与移动端的连接信息，
+ * 让它把整条控制面拖下水不值得。
+ */
+function advertisedCandidates(port, interfaces = os.networkInterfaces()) {
+  try {
+    const lan = lanCandidates(port, interfaces)
+    if (lan.length > 0) return lan
+    return publicCandidates(port, interfaces)
+  } catch {
+    return []
+  }
+}
+
+module.exports = {
+  ipv4Number,
+  isPrivateLanAddress,
+  isPublicAddress,
+  isVpnInterface,
+  isVirtualInterface,
+  interfaceRank,
+  lanInterfaces,
+  lanUrls,
+  lanCandidates,
+  publicInterfaces,
+  publicUrls,
+  publicCandidates,
+  advertisedCandidates,
+}

package/lib/routes/control-plane.js

@@ -22,6 +22,12 @@ const { randomBytes } = require('node:crypto');
 
 const core = require('../relay/core.js');
 const pairingApproval = require('../relay/pairing-policy.js');
+// 端口自检用的是局域网代理**同一把探针**（见 `../relay/port-allocator.cjs` 的文件头）：
+// 这里说「可用」，真正 listen 时就不会 EADDRINUSE，两边不会各说各话。
+const { canListen } = require('../relay/port-allocator.cjs');
+// 面板的「手机该填哪个地址」要两份：私网（lanCandidates）与公网（publicCandidates）。
+// 两者刻意分开，理由写在 lan-network.cjs 里那两个函数头上。
+const { lanCandidates, publicCandidates } = require('../relay/lan-network.cjs');
 const desktopView = require('../desktop-view.cjs');
 const readReceipt = require('../read-receipt.cjs');
 // 客户端半边的活体台账：两条绿点同步通道都是「单向轮询 + 无回执」，不记账就永远分不开
@@ -173,6 +179,10 @@ function registerControlPlaneRoutes(deps) {
     getLanPortAdjusted,
     pairingPayload,
     restartSidecar,
+    // 「手机上最近来过没有」。**只往本机这条状态路由上补**（和 panelUrl 一样），
+    // 不动 createStatusView——那份 JSON 手机端也在读，给它加字段是另一个决定。
+    // 缺省回 0：没有记账的宿主（老版本 / 测试里单独挂 impl）如实报「从来没来过」。
+    mobileActivity = () => ({ lastMobileAt: 0 }),
     // 插件 ctx。只给「桌面端说它读过了」那条路由用：它要清掉宿主侧的完成提醒。
     // 缺省 null 时那条路由降级为「只回 200、什么都不清」。
     ctx = null,
@@ -203,7 +213,16 @@ function registerControlPlaneRoutes(deps) {
   // 控制面状态里额外带上面板页的绝对地址：客户端半边（lib/client.js）那一项现在只是
   // 一个「打开配置页面」的入口，链接必须是绝对的（原因见 panelUrlOf）。地址只在这里
   // 补，不动 createStatusView —— 那份 JSON 手机端也在读，127.0.0.1 的地址对它没意义。
-  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req) })) })
+  // 面板的「手机该填哪个地址」：把检测到的网卡地址按**局域网 / 公网**分成两份报出来，
+  // 用户不用自己去 `ipconfig`，界面也能一眼看出该填哪个（引导第三、四页用它）。
+  //
+  // 只给面板看：移动端那份候选契约（二维码里带的 `lanUrls`）**一个字都没动**，那边的
+  // 私网/公网取舍见 `../relay/lan-network.cjs` 的 `advertisedCandidates`。
+  registerRoute({ kind: 'exact', path: '/api/relay/addresses', handler: localOnly('GET', async (_req, res) => {
+    const port = lanPortInUse()
+    sendJson(res, 200, { ok: true, port, lan: lanCandidates(port), public: publicCandidates(port) })
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), ...mobileActivity() })) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
   // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
   //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
@@ -376,6 +395,32 @@ function registerControlPlaneRoutes(deps) {
     await syncSidecar().catch(() => undefined)
     sendJson(res, 200, status())
   }) })
+  // 端口自检：面板上那颗「检查端口」用的。真实地试绑一次，回答「本机现在能不能监听它」，
+  // 探针就是局域网代理挑端口用的那一把，所以它给的答案和真正 listen 的结果是同一件事。
+  //
+  // 只读，不写任何配置：用户点着玩的动作不该改落盘状态（要改端口走上面的 `/config`）。
+  // 一个例外必须认出来：同一个端口如果是这台宿主**自己**正在监听的直连端口，
+  // `canListen` 当然会失败，但那不是「被别的程序占用」，要单独回 `ours`。
+  registerRoute({ kind: 'exact', path: '/api/relay/check-port', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    const port = Number(body?.port)
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+      return sendJson(res, 200, { ok: true, port: null, available: false, reason: 'out-of-range' })
+    }
+    const snapshot = status()
+    const listening = snapshot.lan.state === 'listening'
+    const currentPort = snapshot.lan.port
+    // 宿主自己的网页端口不能当直连端口——那等于把桌面 GUI 挂到手机上（预览那条路由的
+    // `protectedPorts` 也排它）。**这一条光靠试绑发现不了**：实测 macOS 上别的进程占着
+    // `127.0.0.1:P` 时，`0.0.0.0:P` 照样绑得成功，于是「可用」会是个假答案。
+    if (snapshot.localPort === port) {
+      return sendJson(res, 200, { ok: true, port, available: false, ours: false, listening, currentPort, reason: 'host-web-port' })
+    }
+    if (listening && currentPort === port) {
+      return sendJson(res, 200, { ok: true, port, available: true, ours: true, listening, currentPort })
+    }
+    sendJson(res, 200, { ok: true, port, available: await canListen(port, '0.0.0.0'), ours: false, listening, currentPort })
+  }) })
   registerRoute({ kind: 'exact', path: '/api/relay/reconnect', handler: localOnly('POST', async (_req, res) => {
     await syncSidecar()
     sendJson(res, 200, status())
@@ -424,7 +469,10 @@ function registerControlPlaneRoutes(deps) {
   // 拿不到（无头部署 / 没有外壳的那一版）就退回这一代自己的版本号。
   registerRoute({ kind: 'exact', path: '/api/relay/update/check', handler: localOnly('POST', async (_req, res) => {
     const runtime = pluginRuntime()
-    const snapshot = runtime ? runtime.status() : null
+    // 形状必须和上面那条 `update/status` **一模一样**（含 `available`）。2026-10-11 的真机现场：
+    // 这条只回 `runtime.status()`，面板拿它 `setHost()` 覆盖掉好状态，`available` 变成 undefined，
+    // 卡片当场从「宿主模式」掉进取降级那一半 —— 用户看到的现象是「有新版本却没有『立即更新』」。
+    const snapshot = runtime ? { available: true, ...runtime.status() } : null
     try {
       const update = await checkForUpdate({
         installedVersion: snapshot?.installedVersion ?? snapshot?.version ?? generationVersion(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",
@@ -15,8 +15,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/WNLUO/deepseek-harness-desktop.git",
-    "directory": "dsh-mobile-plugin"
+    "url": "git+https://github.com/WNLUO/dsh-mobile-plugin.git"
   },
   "keywords": [
     "dsh",