dsh-mobile-plugin 0.5.10 → 0.5.12

package/lib/relay/core.js

@@ -49,6 +49,9 @@ function defaultState() {
     // 用户手填的直连地址（空 = 没填）。与上面那条同一条口径：也是 schema 里的一项、
     // 也不进 sidecar 配置 —— 它只影响「报给手机的候选」与二维码，不影响隧道怎么连。
     manualLanUrl: '',
+    // 用户手填的 IPv6 直连地址（空 = 没填）。与上一条同一条口径：schema 里的一项、不进
+    // sidecar 配置，只影响「报给手机的 IPv6 候选」与二维码。
+    manualIpv6Url: '',
     // 首次接入引导走完没有。**刻意不进 RemoteControlSettingsSchema**：它不是一项
     // 「远程控制设置」，改它不该触发 sidecar 重配（那条链上每加一个字段都要同步改
     // schema、worker 的 allowed 数组与 buildConfig，漏一处就抛 unknown field）。

package/lib/relay/firewall-probe.js

@@ -73,6 +73,12 @@ function asArray(value) {
   return value === null || value === undefined ? [] : [value];
 }
 
+/** PowerShell 报上来的条数：读不到是 `null`，不是 0 —— 「一条都没有」和「没读到」是两件事。 */
+function countOf(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.floor(number) : null;
+}
+
 /**
  * 解析 Windows 那份报告（脚本见 `WINDOWS_SCRIPT`）。
  *
@@ -95,6 +101,9 @@ function parseWindowsReport(text) {
       profile: String(item && item.profile ? item.profile : ''),
     })),
     activeProfiles: asArray(profileObject.activeProfiles).map((item) => String(item)),
+    // 这两个计数只用来区分「一条放行规则都没有」和「规则压根没读出来」，见 `decideWindowsAllows`。
+    filters: countOf(profileObject.filters),
+    rules: countOf(profileObject.rules),
   };
 }
 
@@ -125,11 +134,16 @@ function windowsRuleApplies(profileField, activeProfiles) {
  *
  * 顺序：显式 Block 优先 → 有生效中的 Allow → 防火墙开着却没有规则 = 默认拒绝（这是
  * 第一次弹框点了取消之后的样子）→ 防火墙关着 = 不挡。
+ *
+ * 只有「确实一条这个程序的规则都没有」才走默认拒绝。查到了过滤器却一条规则都没关联上，
+ * 是查询出了问题，回 `null`（查不到）—— 报「挡住了」会把人引去关防火墙、加重复规则，
+ * 真正的原因反而被盖住。
  */
 function decideWindowsAllows(report) {
   if (!report || !Array.isArray(report.apps)) return null;
   const enabled = report.profiles.some((item) => item.enabled === true);
   if (!enabled) return true;
+  if (countOf(report.filters) > 0 && countOf(report.rules) === 0) return null;
   const hits = report.apps.filter((item) => item.program && sameWindowsPath(item.program, report.appPath));
   const live = hits.filter((item) => item.enabled !== false && windowsRuleApplies(item.profile, report.activeProfiles));
   if (live.some((item) => /block/i.test(item.action))) return false;
@@ -150,17 +164,32 @@ function decideWindowsAllows(report) {
  *    机器上，系统界面显示的防火墙开着，按本地库读出来三个 profile 可能全是「关」
  *    —— 用户看到的「实际防火墙开着、自检说关着」就是这一条；反过来，组策略下发的
  *    放行规则也会被漏掉、报成「挡住」。
+ * 4. 从**应用过滤器**反查规则：过滤器对象上的 `Name` 恒为空（规则 ID 不在那儿），拿它当
+ *    规则名去查，一条都查不到 —— 于是「明明放行了」被报成「挡住了」。正确的是问「这个
+ *    过滤器属于哪几条规则」（`-AssociatedNetFirewallApplicationFilter`），见下面注释。
+ * 5. `$ErrorActionPreference = "Stop"`：查询本身失败（权限、服务没起）时必须**整个失败**。
+ *    PowerShell 默认只是往错误流写一行接着往下跑，那样循环一条不转，结果跟「这台没有
+ *    放行规则」一模一样 —— 正是误报的来源。
  */
 const WINDOWS_SCRIPT = [
+  '$ErrorActionPreference = "Stop";',
   '$path = $env:DSH_FIREWALL_PROGRAM;',
   '$profiles = @(Get-NetFirewallProfile -PolicyStore ActiveStore | ForEach-Object { @{ name = "$($_.Name)"; enabled = [bool]$_.Enabled } });',
-  '$active = @(Get-NetConnectionProfile | ForEach-Object { $c = "$($_.NetworkCategory)"; if ($c -eq "DomainAuthenticated") { "Domain" } else { $c } });',
+  // 读不到当前接入的网络类别不算失败：`windowsRuleApplies` 会按「管」算，没必要因此整条查不到。
+  '$active = @();',
+  'try { $active = @(Get-NetConnectionProfile | ForEach-Object { $c = "$($_.NetworkCategory)"; if ($c -eq "DomainAuthenticated") { "Domain" } else { $c } }) } catch {}',
   '$apps = @();',
-  'foreach ($f in @(Get-NetFirewallApplicationFilter -PolicyStore ActiveStore -Program $path)) {',
-  '  $r = Get-NetFirewallRule -Name $f.Name -PolicyStore ActiveStore;',
-  '  if ($r) { $apps += @{ program = "$($f.Program)"; action = "$($r.Action)"; enabled = ("$($r.Enabled)" -eq "True"); profile = "$($r.Profile)" } }',
+  '$filters = @(Get-NetFirewallApplicationFilter -PolicyStore ActiveStore -Program $path);',
+  '$rules = 0;',
+  'foreach ($f in $filters) {',
+  '  foreach ($r in @($f | Get-NetFirewallRule -PolicyStore ActiveStore)) {',
+  '    $rules = $rules + 1;',
+  // 出站规则跟「手机连进来」无关；混进来会把「没有入站放行」看成「有规则」。
+  '    if ("$($r.Direction)" -ne "Inbound") { continue; }',
+  '    $apps += @{ program = "$($f.Program)"; action = "$($r.Action)"; enabled = ("$($r.Enabled)" -eq "True"); profile = "$($r.Profile)" }',
+  '  }',
   '}',
-  '@{ profiles = $profiles; apps = $apps; activeProfiles = $active } | ConvertTo-Json -Depth 6 -Compress',
+  '@{ profiles = $profiles; apps = $apps; filters = $filters.Count; rules = $rules; activeProfiles = $active } | ConvertTo-Json -Depth 6 -Compress',
 ].join(' ');
 
 /** 默认执行器：只跑写死的可执行文件与参数，超时杀进程，输出按 UTF-8 收。 */
@@ -220,6 +249,8 @@ async function probeFirewall(options = {}) {
     });
     if (result.error === 'NO_COMMAND') return unknownFirewall(execPath, 'no-command');
     if (result.error === 'TIMEOUT') return unknownFirewall(execPath, 'timeout');
+    // 脚本是 `$ErrorActionPreference = "Stop"`：查询本身失败就没有 JSON，如实报查不到。
+    if (result.error) return unknownFirewall(execPath, 'parse-failed');
     let report = null;
     try {
       report = parseWindowsReport(result.stdout);
@@ -227,11 +258,12 @@ async function probeFirewall(options = {}) {
       return unknownFirewall(execPath, 'parse-failed');
     }
     if (report.profiles.length === 0) return unknownFirewall(execPath, 'parse-failed');
-    const enabled = report.profiles.some((item) => item.enabled === true);
+    const allowsApp = decideWindowsAllows({ ...report, appPath: execPath });
+    if (allowsApp === null) return unknownFirewall(execPath, 'parse-failed');
     return {
       supported: true,
-      enabled,
-      allowsApp: decideWindowsAllows({ ...report, appPath: execPath }),
+      enabled: report.profiles.some((item) => item.enabled === true),
+      allowsApp,
       appPath: execPath,
       reason: null,
     };

package/lib/relay/lan-network.cjs

@@ -369,6 +369,51 @@ function withManualCandidate(list, value) {
   return [...rest.filter(item => item && item.url !== manual.url), manual]
 }
 
+/**
+ * 用户**自己填的** IPv6 直连地址（设置项 `manualIpv6Url`）→ 候选。
+ *
+ * 与上面那条同一件事，只是拨的是 IPv6：网卡枚举只报这台机器此刻真实挂着的全球单播地址，
+ * 人可能想固定成「运营商分给我、但网卡上暂时没挂」的那一条（临时地址轮换、前缀换了、网卡
+ * 拔了），它只能由人手填。值形如 `http://[240e:338::998]:18787`，与 `ipv6Candidates` 产出的
+ * `url` 同形 —— 地址在 URL 里必须带方括号。
+ *
+ * 校验口径与 `manualCandidate` 一致：只挡明显不能用的（空、非 http(s)、解析不出主机），
+ * 另外要求主机确实是一个 IPv6 字面量：这一份只报 IPv6，混进域名 / v4 会让 App 那条独立
+ * 通道拿到一条不属于它的地址。**不校验是不是全球单播**：填内网 / ULA 地址也是人自己的
+ * 选择，能不能通由手机实测给出，宿主只负责如实上报。
+ */
+function manualIpv6Candidate(value) {
+  const url = typeof value === 'string' ? value.trim().replace(/\/+$/, '') : ''
+  if (!url || !/^https?:\/\/[^\s/]+/i.test(url)) return null
+  let host = ''
+  try { host = new URL(url).hostname } catch { return null }
+  // URL.hostname 对 IPv6 是带方括号的，而候选的 `address` 与网卡那份同形：裸地址。
+  const address = String(host).replace(/^\[/, '').replace(/\]$/, '')
+  if (ipv6Number(address) === null) return null
+  return { url, address, interface: 'manual', family: 'IPv6' }
+}
+
+/**
+ * 候选 = 网卡那几条照旧 + 用户填的那条**排在最后**当兜底。**只追加、不替换**：手填的值
+ * 再准也只是多一条，网卡枚举出来的候选一条都不删 —— 它写错了、或者那条地址暂时不可达时，
+ * 手机还得能顺着网卡地址摸回这台机器。值不合法时原样退回网卡候选，不让一条坏配置把整份
+ * 候选清空。
+ *
+ * 去重按 `ipv6Number` 解出来的数值，与 `ipv6Candidates` / `collectEndpoints` 同一条口径：
+ * `[240E::1]` 与 `[240e:0:0:0:0:0:0:1]` 是同一个地址的两种写法，按 URL 逐字比会留下两条、
+ * 让手机对同一个地址各探一次。
+ *
+ * 排在最后与 `withManualCandidate` 同一个理由：手填的是兜底，同一个 Wi-Fi 下网卡地址快
+ * 一个数量级，排最前就会按「先回话的赢」永远选中手填那条。
+ */
+function withManualIpv6Candidate(list, value) {
+  const manual = manualIpv6Candidate(value)
+  const rest = Array.isArray(list) ? list : []
+  if (!manual) return rest
+  const key = String(ipv6Number(manual.address))
+  return [...rest.filter(item => item && String(ipv6Number(item.address)) !== key), manual]
+}
+
 /**
  * 把用户选中的那条排到最前面（面板上的「手机优先用这条」，存在设置项 `preferredLanAddress`）。
  *
@@ -429,6 +474,8 @@ module.exports = {
   advertisedCandidates,
   manualCandidate,
   withManualCandidate,
+  manualIpv6Candidate,
+  withManualIpv6Candidate,
   orderCandidates,
   phoneCandidates,
 }

package/lib/relay/pairing-payload.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * 配对二维码的载荷与原文。
+ *
+ * 面板（`/api/relay/pairing`）与终端命令（`lib/cli/pair.cjs`）都从这里取，**只此一份**：
+ * 两处各拼一遍的话，迟早出现「面板里的码能配上、终端里打出来的配不上」这种最难查的分叉。
+ *
+ * 只做「把 state 折成一张卡里要说的东西」，不认识 HTTP、不认识渲染：二维码图片怎么画由
+ * 调用方决定（面板要 SVG、终端要字符画）。
+ */
+
+const os = require('node:os');
+const {
+  advertisedCandidates,
+  phoneCandidates,
+  ipv6Candidates,
+  withManualIpv6Candidate,
+} = require('./lan-network.cjs');
+
+/**
+ * @param {object} state relay.json 那份状态（至少要有 name/instanceId/pairingCode/pairingTicket/relayUrl/lanEnabled）
+ * @param {number} [lanPort] 实绑的局域网端口（首选端口被占时会与配置里那个不同）
+ * @returns {{payload: object, text: string}} `text` 就是二维码里那串 `dshpair://`
+ */
+function pairingPayload(state, lanPort) {
+  const port = Number.isInteger(lanPort) ? lanPort : state.lanPort;
+  // 面板上选过的「手机优先用这条」在这里兑现：只挪到最前，其余继续当兜底（App 按顺序挨个试）。
+  const candidates = state.lanEnabled
+    ? phoneCandidates(advertisedCandidates(port), { preferred: state.preferredLanAddress, manual: state.manualLanUrl })
+    : [];
+  const urls = candidates.map(candidate => candidate.url).filter(Boolean);
+  const relayUrl = state.relayUrl || '';
+  const payload = {
+    type: 'dsh-pair',
+    version: 1,
+    name: state.name || os.hostname(),
+    instanceId: state.instanceId,
+    code: state.pairingCode,
+    // 协议版本与一次性票据（§8.3(1)）。
+    //
+    // `proto: 2` 由**宿主**写、也由宿主生成，中转没有任何机会改写它 —— 所以「新 App 被
+    // 中转骗回明文」这个问题从一开始就不存在。`ticket` 是 32 字节随机数，手机拿它派生
+    // 配对密钥；二维码是屏幕对摄像头，这条通道完全绕开中转。
+    //
+    // 老 App 只取自己认识的那几个字段，多出来的两个会被忽略 —— 一张二维码同时服务新旧两种。
+    proto: 2,
+    ticket: state.pairingTicket || '',
+    relayUrl,
+    lanUrls: urls,
+    // 候选列表随二维码一起带走：App 配对后即使换了网段，也能按这份列表
+    // 依次重试而不用先回到公网中转去问。
+    lanCandidates: urls,
+    // IPv6 直连候选（理想情况下是手机**不在同一个 Wi-Fi 里**时唯一能拨到的地址）：不参与上面
+    // 那份的排序，顺序由 App 侧拿它和公网中转实测比出来；直连监听没开就没有这条通道。
+    // 用户手填的那条缀在最后当兜底（只追加、不删网卡候选），见 `withManualIpv6Candidate`。
+    ipv6Candidates: state.lanEnabled
+      ? withManualIpv6Candidate(ipv6Candidates(port), state.manualIpv6Url).map(candidate => candidate.url).filter(Boolean)
+      : [],
+  };
+  return {
+    payload,
+    text: `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`,
+  };
+}
+
+module.exports = { pairingPayload };

package/lib/routes/control-plane.js

@@ -17,6 +17,7 @@
  */
 
 const fs = require('node:fs');
+const net = require('node:net');
 const path = require('node:path');
 const QRCode = require('qrcode');
 const { randomBytes } = require('node:crypto');
@@ -32,7 +33,7 @@ const { canListen } = require('../relay/port-allocator.cjs');
 // ⚠️ 面板里**能被选中的**那份仍然只能是 `lan`（没有私网时才退 `public`）——它与
 // `advertisedCandidates` 同口径。IPv6 那份只**显示**、不进那个选择：它由手机侧实测择优
 // （和公网中转比速度），做成可选中等于骗人（同 A3-40 的刻意设计）。
-const { lanCandidates, publicCandidates, ipv6Candidates } = require('../relay/lan-network.cjs');
+const { lanCandidates, publicCandidates, ipv6Candidates, withManualIpv6Candidate, isPrivateLanAddress } = require('../relay/lan-network.cjs');
 // 「手机连不上时哪一环断了」这份连接自检：本机只读、不改任何东西（口径见
 // connection-check.js 与 firewall-probe.js 的文件头）。
 const { createConnectionCheck } = require('../relay/connection-check.js');
@@ -204,6 +205,42 @@ function panelUrlOf(req) {
   return `${forwarded || 'http'}://${host}/api/relay/panel`;
 }
 
+/**
+ * 面板地址落在哪一类网络上：`loopback` / `private` / `public`（判不出来时算 `public`）。
+ *
+ * 侧边栏那颗手机图标（现在它是进入网页的唯一入口）据此决定点下去要不要先开两小时窗口：
+ *
+ *   - `loopback`：人就在这台机器的 DSH 设置页里，控制面本来就认它，直接跳转；
+ *   - `private`：同一个局域网里的另一台设备 —— 控制面不认它，得先开窗口，但用户点的就是
+ *     自己眼前的界面，不再多弹一次确认；
+ *   - `public`：公网部署，地址谁都能拨，所以先弹一句确认再开。
+ *
+ * **域名一律按 `public` 算**：内网域名、内网穿透域名长得跟公网域名一样，这里分不出来。
+ * 猜错的代价是「多弹一次确认」，反过来猜错就是「不知不觉把公网管理口开了两小时」。
+ */
+function panelScopeOf(req) {
+  const host = typeof req?.headers?.host === 'string' ? req.headers.host : '';
+  if (!host) return 'public';
+  let hostname = '';
+  try {
+    hostname = new URL(`http://${host}`).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  } catch {
+    return 'public';
+  }
+  if (hostname === 'localhost') return 'loopback';
+  if (net.isIP(hostname) === 4) {
+    if (/^127\./.test(hostname)) return 'loopback';
+    return isPrivateLanAddress(hostname) ? 'private' : 'public';
+  }
+  if (net.isIP(hostname) === 6) {
+    if (hostname === '::1') return 'loopback';
+    // fc00::/7 是唯一本地地址（私网），fe80::/10 是链路本地：都只在一个局域网里有意义。
+    if (/^f[cd][0-9a-f]{2}:/.test(hostname) || /^fe[89ab][0-9a-f]:/.test(hostname)) return 'private';
+    return 'public';
+  }
+  return 'public';
+}
+
 /**
  * @param {object} deps 见 `lib/impl.js` 里 registerControlPlaneRoutes({...}) 的调用点
  */
@@ -373,7 +410,19 @@ function registerControlPlaneRoutes(deps) {
     const preferred = typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : ''
     // `manual` 是用户手填的直连地址（内网穿透域名）：网卡扫不出来，所以单列一格让面板回显与修改。
     const manual = typeof state.manualLanUrl === 'string' ? state.manualLanUrl : ''
-    sendJson(res, 200, { ok: true, port, preferred, manual, lan: lanCandidates(port), public: publicCandidates(port), ipv6: ipv6Candidates(port) })
+    // `manualIpv6` 是同一件事的 IPv6 版：面板回显它，同时把它缀进 `ipv6` 候选最后
+    // （只追加、不删网卡候选；排最后的取舍见 lan-network.cjs 的 `withManualIpv6Candidate`）。
+    const manualIpv6 = typeof state.manualIpv6Url === 'string' ? state.manualIpv6Url : ''
+    sendJson(res, 200, {
+      ok: true,
+      port,
+      preferred,
+      manual,
+      manualIpv6,
+      lan: lanCandidates(port),
+      public: publicCandidates(port),
+      ipv6: withManualIpv6Candidate(ipv6Candidates(port), manualIpv6),
+    })
   }) })
   /**
    * 公用中转候选的测速（`POST /api/relay/probe-relays`，body `{ urls: string[] }`）。
@@ -419,7 +468,13 @@ function registerControlPlaneRoutes(deps) {
   }) })
   // 只有可信本机设置入口可以开 / 关窗口；窗口状态仅驻留进程内，DSH 重启后必定关闭。
   registerRoute({ kind: 'exact', path: '/api/relay/web-access', handler: localOnly('POST', async (req, res) => {
-    if (typeof trustedLocalUi !== 'function' || !trustedLocalUi(req)) return sendJson(res, 403, { ok: false, error: { code: 'local_ui_only', message: '请从 DSH 本机设置页管理网页访问' } });
+    // 谁来按这个开关（2026-11-02 用户拍板放宽，取代原先「只认可信本机设置页」）。
+    //
+    // 侧边栏那颗手机图标成为进网页的唯一入口之后，公网 / 局域网部署的人就是在自己的浏览器里
+    // 点它 —— 那时 socket 对端与 Host 都不是回环，按老判据会 403，于是谁也没法把窗口打开，
+    // 面板永远回 423。现在只要求 `localOnly` 已经保证的那一层：同源、不带中转凭据、不经本机
+    // 代理转发。能发出这条请求的只有 DSH 自己页面里的代码，而「人在 DSH 界面里按下了这个
+    // 按钮」正是这个窗口存在的理由。跨站页面、中转与局域网代理转进来的请求仍在 localOnly 挡掉。
     const body = await readJson(req);
     if (typeof body?.enabled !== 'boolean') {
       return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } });
@@ -427,7 +482,7 @@ function registerControlPlaneRoutes(deps) {
     const webAccess = body.enabled ? webAccessWindow.enable() : webAccessWindow.disable();
     return sendJson(res, 200, { ok: true, webAccess });
   }) });
-  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), webAccess: webAccessWindow.status(), ...mobileActivity(), selfCheck: selfCheck.snapshot() })) })
+  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), panelScope: panelScopeOf(req), webAccess: webAccessWindow.status(), ...mobileActivity(), selfCheck: selfCheck.snapshot() })) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
   // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
   //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
@@ -528,22 +583,14 @@ function registerControlPlaneRoutes(deps) {
     return sendJson(res, 200, { ok: true, installed: true, faults: guard.faults(), stats: guard.stats() })
   }) })
   registerRoute({ kind: 'exact', path: '/api/relay/pairing', handler: localOnly('GET', async (req, res) => {
-    // **二维码只在本机屏幕上出现**。
-    //
-    // 二维码里现在装的是一次性票据 —— 用它能派生出整条链路的密钥。而「经中转/局域网
-    // 代理转发来的请求在判据眼里长得像本机」这件事已经被实测证实过，所以这条不能只靠
-    // `localOnly`；它要的是**可信本机界面**这个更强的判据（socket 回环 + Host 回环 +
-    // 没有任何代理来源头）。网页管理窗口（两小时窗口那套）打开时能看到设备列表，但看
-    // 不到这张码 —— 窗口本身是从浏览器发起的，`trustedLocalUi` 对它不成立。
+    // 二维码里装的是一次性票据 —— 用它能派生出整条链路的密钥，所以它本来只该在本机屏幕上
+    // 出现。但「本机屏幕」这个判据在**服务器部署**上是空的：那台机器只有 SSH，人永远够
+    // 不到它，于是这台机器上的用户连一次都配不上（2026-11-01 现场）。
     //
-    // 拿不到就回 423 而不是 403：面板那边据此显示「请在这台电脑上打开面板」，
-    // 也**不给**「点这里强制显示」——那等于把刚堵上的口子又开一遍。
-    if (typeof trustedLocalUi !== 'function' || !trustedLocalUi(req)) {
-      return sendJson(res, 423, {
-        ok: false,
-        error: { code: 'pairing_local_only', message: '配对二维码只在本机屏幕显示，请在这台电脑上打开面板' },
-      })
-    }
+    // 所以这条跟别的管理动作走同一套规矩：外面那层两小时窗口（`WEB_ACCESS_ROUTES`）说了算。
+    // 窗口由本机 DSH 设置页亲手开，开了之后远程本来就能踢掉全部设备、改中转地址、重启
+    // sidecar —— 单独把二维码挡在窗口外面既不自洽，也让那颗按钮名不副实（用户拍板）。
+    // 窗口没开时远程照旧拿不到码；判据不再自己造第二套。
     if (!state.enabled) {
       sendJson(res, 409, { ok: false, error: '请先启用远程控制并保存配置' })
       return
@@ -616,8 +663,8 @@ function registerControlPlaneRoutes(deps) {
    * 只回「面板画一行需要的东西」，**不回 `hash` / `hostToken`** —— 那些是凭据材料，
    * 面板只是显示谁连着、什么时候来的。
    *
-   * 与二维码那条不一样，这条**进** `WEB_ACCESS_ROUTES`：设备列表里没有密钥材料，
-   * 两小时窗口打开时能看、能踢是它的用途；而二维码里是整条链路的密钥，绝不能。
+   * 与二维码那条同一条规矩：都在 `WEB_ACCESS_ROUTES` 里，两小时窗口打开时远程能用是它的
+   * 用途。设备列表里没有密钥材料；二维码那边多一层考虑，见 `/api/relay/pairing` 的注释。
    *
    * `serverNow` 是给面板算「几分钟前」用的：手机与宿主的时钟可能差得多，但面板只需要
    * 一个同一台机器上的基准。
@@ -683,6 +730,10 @@ function registerControlPlaneRoutes(deps) {
     if (typeof body?.manualLanUrl === 'string' && body.manualLanUrl.length <= 200) {
       patch.manualLanUrl = body.manualLanUrl.trim().replace(/\/+$/, '')
     }
+    // 用户手填的 IPv6 直连地址（`http://[240e::1]:18787`）。空串合法 = 清掉，口径同上一条。
+    if (typeof body?.manualIpv6Url === 'string' && body.manualIpv6Url.length <= 200) {
+      patch.manualIpv6Url = body.manualIpv6Url.trim().replace(/\/+$/, '')
+    }
     await settings.update(patch)
     // 换中转地址时宿主会**先在旧隧道上登记迁移、再重建**（顺序在 worker 的 configure 里，
     // 见 lib/relay/migrate.js）—— 面板与手机走的是同一条下发路径，不需要各自实现一遍。
@@ -986,6 +1037,9 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/panel/setup',
   '/api/relay/panel/settings',
   '/api/relay/faults',
+  // 配对二维码：里面是能派生整条链路密钥的一次性票据，所以它只在两小时窗口开着时给网页看
+  // ——窗口由本机设置页亲手开，服务器部署没有「本机屏幕」可看，这条是它唯一的出口。
+  '/api/relay/pairing',
   '/api/relay/toggle',
   '/api/relay/regenerate',
   '/api/relay/onboarded',
@@ -1017,6 +1071,8 @@ const WEB_ACCESS_ROUTES = new Set([
 module.exports = {
   registerControlPlaneRoutes,
   panelDiagnosis,
+  panelUrlOf,
+  panelScopeOf,
   WEB_ACCESS_ROUTES,
   WEB_ACCESS_WINDOW_MS,
   createWebAccessWindow,

package/lib/routes/mobile-api.js

@@ -12,7 +12,7 @@
  */
 
 const { sendJson } = require('../http/routing.js');
-const { orderCandidates, withManualCandidate } = require('../relay/lan-network.cjs');
+const { orderCandidates, withManualCandidate, withManualIpv6Candidate } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
 const sessionModelOptions = require('../mobile/session-model-options.js');
@@ -32,6 +32,7 @@ const archiveClean = require('../mobile/archive-clean.js');
 const sessionLog = require('../mobile/session-log.js');
 const hostSettings = require('../mobile/host-settings.js');
 const channels = require('../mobile/channels.js');
+const modelCaps = require('../mobile/model-caps.js');
 const deepSeekAccount = require('../mobile/deepseek-account.js');
 const skills = require('../mobile/skills.js');
 const mobileCredentials = require('../mobile/credentials.js');
@@ -51,6 +52,7 @@ const pairing = require('../mobile/pairing.js');
 const { credentialsEntry } = require('../shared/credentials-entry.js');
 const { handleCredentialUpgrade } = require('../mobile/credential-upgrade.js');
 const extensions = require('../mobile/extensions.js');
+const extensionDev = require('../mobile/extension-dev.js');
 const sessionDelivery = require('../mobile/session-delivery.js');
 // 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
 const pkg = require('../../package.json');
@@ -200,8 +202,9 @@ function registerMobileRoutes(deps) {
     //
     // 这份是手机配对之后**唯一**能拿到新 IPv6 地址的地方：二维码里带的候选只在配对那一刻
     // 是真值，而隐私地址按小时轮换、运营商换前缀之后旧的那条就拨不通了。少回这一格，
-    // 手机上那条通道就只能靠配对当时的旧地址活着。
-    const ipv6 = state.lanEnabled ? safeIpv6Candidates(port) : []
+    // 手机上那条通道就只能靠配对当时的旧地址活着。手填的 IPv6 那条缀在**最后**当兜底
+    // （只追加、不删网卡候选），理由与上面手填的直连地址同一条。
+    const ipv6 = state.lanEnabled ? withManualIpv6Candidate(safeIpv6Candidates(port), state.manualIpv6Url) : []
     const lanUpdatedAt = getSidecarSnapshot()?.lan?.updatedAt || Date.now()
     sendJson(res, 200, {
       ok: true,
@@ -348,6 +351,11 @@ function registerMobileRoutes(deps) {
   // 渠道管理（见 mobile/channels.js）：只对「本机自建」那一类（`llm-pi-ai` 里的路由）
   // 提供增删；插件 / 宿主注册的提供方只列出来，一个写操作都不做。获取模型由宿主代问
   // （端点常在内网，手机直连未必通），与桌面面板的 `discoverModels` 同一条路。
+  // 模型能力配置（见 mobile/model-caps.js）：公开参数快照（App 拉一次、缓存后在 App 端搜索）
+  // 与「把选中的那份写回这条自建渠道」。写只到 `providers.<id>`，与上面的渠道保存同一条
+  // 边界 —— 内置渠道不在这份清单里，apply 一律 409。
+  route('/api/mobile/v1/model-meta', modelCaps.handleModelMeta)
+  route('/api/mobile/v1/model-meta/apply', modelCaps.handleModelMetaApply)
   route('/api/mobile/v1/channels', channels.handleChannels)
   route('/api/mobile/v1/channels/discover', channels.handleChannelDiscover)
   route('/api/mobile/v1/channels/save', channels.handleChannelSave)
@@ -457,6 +465,14 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/extension/card-state', extensions.handleExtensionCardState)
   route('/api/mobile/v1/extension/action', extensions.handleExtensionAction)
 
+  // 扩展**开发包**：作者放在电脑上的本地扩展目录（`$DSH_HOME/extension-dev`），手机上直接
+  // 列包、取文件，不用每改一行都发一次分发系统（见 mobile/extension-dev.js）。
+  //
+  // 能力面只多「读这一个固定目录」：slug 与包内相对路径拼出来的路径，取文件前先 resolve
+  // 再判前缀。仍然不暴露 shell、系统设置、任意文件读写 —— 不接受任意路径，也不给写。
+  route('/api/mobile/v1/extension/dev/packages', extensionDev.handleDevPackages)
+  route('/api/mobile/v1/extension/dev/file', extensionDev.handleDevFile)
+
   // 分享文件的落地通道（App 把手机分享进来的文件分片传上来，见 mobile/uploads.js）。
   // 手机端没有「把文件交给宿主」的路：图片能进 session.send 的 base64 内容块，其它格式
   // 一律进不去。四条端点只做「收字节 → 落盘」：默认落到 `~/.dsh/mobile-inbox/<日期>/<文件名>`，

package/lib/update-install.cjs

@@ -36,6 +36,9 @@
  * 现场不修的话，这台机器之后每一次更新都会撞同一堵墙。
  *
  * 只动 profile 的依赖树；找不到包管理器就如实失败；装完以盘上版本号为准，退出码 0 不算装上。
+ *
+ * Windows 上包管理器是 `.cmd`（pnpm 装出来的就是个批处理外壳），不是可执行文件：直接
+ * `spawn` 必然 `EINVAL`，得让 cmd 去跑它，见 `cmdInvocation`。
  */
 
 const fs = require('node:fs');
@@ -184,6 +187,7 @@ async function profileRegistry({
       cwd: profileDir,
       env: { ...childEnv, ...candidate.extraEnv },
       timeoutMs,
+      platform,
     });
     if (!result.ok) continue;
     registry = parseRegistryOutput(result.output);
@@ -456,12 +460,70 @@ function withReason(message, output) {
   return reason === '' ? message : `${message}\n${reason}`;
 }
 
+/**
+ * Windows 上「跑一个 `.cmd` / `.bat`」得先翻译成「让 cmd 去跑它」。
+ *
+ * 那不是可执行文件，是给 cmd 解释的批处理：`spawn('…\\pnpm.cmd', …)` 在 Windows 上必然失败
+ * （`EINVAL`，路径形态再不对一点是 `EFTYPE`）—— 包管理器一次都没跑起来，而用户只看到一句
+ * 「更新失败」。所以这里翻成 `cmd /d /s /c "<整行>"`。
+ *
+ * 引号是这个坑里唯一的细活：`/s /c` 会剥掉命令行的**最外一层**引号，所以整行外面包一层、
+ * 每个参数各自再包一层 —— 剥掉外层之后，带空格的路径（`C:\Program Files\…`）才认得出来。
+ * 参数仍然是数组、由这里拼，不经过 shell 的变量展开；`windowsVerbatimArguments` 让 Node
+ * 原样把这一行递过去，别再替我们补一层引号。
+ */
+function cmdInvocation(command, args, { env = process.env } = {}) {
+  const comspec = typeof env.ComSpec === 'string' && env.ComSpec.trim() !== '' ? env.ComSpec.trim() : 'cmd.exe';
+  const quote = (value) => `"${String(value).replace(/"/g, '""')}"`;
+  const line = [command, ...args].map(quote).join(' ');
+  return {
+    command: comspec,
+    args: ['/d', '/s', '/c', `"${line}"`],
+    // 这些值只有路径、包名和版本号，没有 `%`，不用担心 cmd 把它当变量展开。
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+/**
+ * 超时杀进程树。
+ *
+ * Windows 上 `child.kill()` 只杀我们自己起的 cmd.exe，包管理器还活着继续改 profile 的依赖
+ * 树 —— 界面说「超时失败」，盘还在被人写。所以那边按整棵树杀。
+ */
+function killTree(child, platform) {
+  if (platform === 'win32' && typeof child.pid === 'number') {
+    try {
+      // 挂一个空的 error 监听：taskkill 不在 PATH 上时，没人收的 error 事件会把宿主进程带崩。
+      const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
+      killer.on('error', () => {});
+      return;
+    } catch {
+      // taskkill 起不来就退化成杀自己那一层。
+    }
+  }
+  try {
+    child.kill('SIGKILL');
+  } catch {
+    // 已经退出了。
+  }
+}
+
 /** 跑一条命令，收 stdout+stderr 的尾巴。超时或非零退出码都如实带出来。 */
-function run(command, args, { cwd, env, timeoutMs, spawnImpl = spawn }) {
+function run(command, args, { cwd, env, timeoutMs, platform = process.platform, spawnImpl = spawn }) {
+  // `.cmd` / `.bat` 交给 cmd 解释；`.exe` 与别的平台照旧直接起。
+  const invocation = platform === 'win32' && /\.(?:cmd|bat)$/i.test(command)
+    ? cmdInvocation(command, args, { env })
+    : { command, args, options: {} };
   return new Promise(resolve => {
     let child;
     try {
-      child = spawnImpl(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+      child = spawnImpl(invocation.command, invocation.args, {
+        cwd,
+        env,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...invocation.options,
+      });
     } catch (error) {
       resolve({ ok: false, code: null, output: '', error: String(error?.message || error) });
       return;
@@ -473,13 +535,7 @@ function run(command, args, { cwd, env, timeoutMs, spawnImpl = spawn }) {
     };
     child.stdout?.on('data', collect);
     child.stderr?.on('data', collect);
-    const timer = setTimeout(() => {
-      try {
-        child.kill('SIGKILL');
-      } catch {
-        // 已经退出了。
-      }
-    }, timeoutMs);
+    const timer = setTimeout(() => killTree(child, platform), timeoutMs);
     child.on('error', error => {
       clearTimeout(timer);
       resolve({ ok: false, code: null, output, error: String(error?.message || error) });
@@ -552,6 +608,7 @@ async function installLatest({
         cwd: profileDir,
         env: { ...childEnv, ...hostInvocation.env },
         timeoutMs: 20000,
+        platform,
       });
       if (probe.ok) {
         return { command: hostInvocation.command, prefix: hostInvocation.args, manager: 'pnpm', kind: 'host', env: hostInvocation.env };
@@ -597,6 +654,7 @@ async function installLatest({
     cwd: profileDir,
     env: { ...childEnv, ...picked.env, ...(picked.manager === 'pnpm' ? POLICY_ENV : {}) },
     timeoutMs,
+    platform,
   });
 
   let result = await runManager([]);
@@ -788,6 +846,9 @@ module.exports = {
   installLatestIfNeeded,
   installedVersion,
   declaredSource,
+  // 「Windows 上怎么起包管理器」在本机跑不起来，守卫只能验拼好的那一行，所以这两样露出来。
+  cmdInvocation,
+  runCommand: run,
   toolSearchDirs,
   resolveExecutable,
   normalizeInvocation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",
@@ -10,7 +10,8 @@
   "type": "module",
   "main": "lib/index.js",
   "bin": {
-    "dsh-mobile-plugin": "host.js"
+    "dsh-mobile-plugin": "host.js",
+    "dsh-mobile-plugin-pair": "lib/cli/pair.cjs"
   },
   "exports": {
     ".": "./lib/index.js",