dsh-mobile-plugin 0.5.21 → 0.5.22

package/lib/relay/pairing-payload.cjs

@@ -58,10 +58,18 @@ function pairingPayload(state, lanPort) {
       ? withManualIpv6Candidate(ipv6Candidates(port), state.manualIpv6Url).map(candidate => candidate.url).filter(Boolean)
       : [],
   };
-  return {
-    payload,
-    text: `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`,
-  };
+  return { payload, text: pairingText(payload) };
+}
+
+/**
+ * 载荷 → 二维码里那一串 `dshpair://`。
+ *
+ * 单独导出是因为**直连隧道那段信息要在拼 text 之前塞进 payload**：隧道窗口是异步起的
+ * （要拉一个节点），拼装函数本身是纯的，不能为了它变成异步。调用方拿到 payload、补上
+ * `tailcat`，再调这里生成 text —— 仍然只有这一处拼格式。
+ */
+function pairingText(payload) {
+  return `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`;
 }
 
-module.exports = { pairingPayload };
+module.exports = { pairingPayload, pairingText };

package/lib/relay/snapshot-auth.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * 读取隔离（镜像快照直回）这层的鉴权。
+ *
+ * `snapshotRead` 命中本地快照时直接序列化好 JSON 回给手机，**绕开了主进程的守卫**。早先
+ * 这里只挡了「协议 v2 要回源信封」那一面，鉴权这一面还开着：只要知道实例号（它就印在配对
+ * 二维码上），不带任何凭据也能经中转读到会话列表、工作区列表。所以这条捷径在回任何快照
+ * 之前，必须自己按主进程守卫同样的口径验一遍凭据。
+ *
+ * 口径（与 `lib/mobile/auth.js` 的 `authOutcome`、`lib/relay/lan-proxy.js` 的 `authOutcome`
+ * 一致，顺序是这里唯一要紧的东西）：
+ *   - 凭据头 / `Authorization: Bearer` / `dsh_lan` cookie 三处，取所有非空候选；
+ *   - 候选里**只要有一枚**是本机签发过的记录，就以记录为准：被吊销、已过期立即判否，
+ *     **不许**再退回更宽松的无状态令牌（否则吊销永远不生效）；
+ *   - 本机**一枚都查不到**时，才回退旧的无状态 HMAC token（升级前配过的老 App 走这条）
+ *     与「中转签发的凭据」。
+ *
+ * 这里不复用 `authOutcome`：那条路每次都要读一遍 relay 状态文件拿实例号，而这是每条高频
+ * 读都走的快路径；实例号、lanSecret 在本进程的 config 里都是现成的，用依赖注入传进来即可。
+ *
+ * @param {object} headers 请求头（原始大小写都行）
+ * @param {{ lookup?: (presented: string) => object|null, verifyLanToken?: (token: string) => boolean }} deps
+ * @returns {boolean} 是否放行；false 时调用方应回源，交给主进程守卫如实驳回。
+ */
+function snapshotAuthorized(headers, deps = {}) {
+  const { lookup, verifyLanToken } = deps;
+  const candidates = credentialCandidates(headers);
+  if (!candidates.length) return false;
+
+  const now = Date.now();
+  for (const presented of candidates) {
+    const known = typeof lookup === 'function' ? lookup(presented) : null;
+    if (!known) continue;
+    if (known.revokedAt) return false;
+    if (known.expiresAt && known.expiresAt <= now) return false;
+    return true;
+  }
+
+  // 本机不认识这些凭据：可能是升级前的 HMAC token，或中转签的。按无状态令牌再验一次。
+  for (const presented of candidates) {
+    try {
+      if (typeof verifyLanToken === 'function' && verifyLanToken(presented)) return true;
+    } catch { /* 验不过就继续看下一枚 */ }
+  }
+  return false;
+}
+
+/** 按大小写不敏感取一个头部的值；数组取第一个，非字符串或空值返回空串。 */
+function headerValue(headers, target) {
+  if (!headers || typeof headers !== 'object') return '';
+  const lower = target.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== lower) continue;
+    const raw = headers[key];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' ? value.trim() : '';
+  }
+  return '';
+}
+
+/** 三条出示凭据的通道：独立凭据头 → Bearer → dsh_lan cookie。去重后返回非空候选。 */
+function credentialCandidates(headers) {
+  const out = [];
+  const seen = new Set();
+  const push = (value) => {
+    if (typeof value !== 'string') return;
+    const token = value.trim();
+    if (!token || seen.has(token)) return;
+    seen.add(token);
+    out.push(token);
+  };
+
+  push(headerValue(headers, 'x-dsh-device-credential'));
+  const bearer = /^Bearer\s+([^\s]+)$/i.exec(headerValue(headers, 'authorization'));
+  if (bearer) push(bearer[1]);
+  const cookie = /(?:^|;\s*)dsh_lan=([^;]+)/.exec(headerValue(headers, 'cookie'));
+  if (cookie) push(cookie[1]);
+  return out;
+}
+
+module.exports = { snapshotAuthorized, credentialCandidates };

package/lib/relay/status.js

@@ -107,6 +107,9 @@ function createStatusView(deps) {
       ...hostMetadata(),
       localPort: webServerPort,
       tunnel: describeTunnel(sidecarSnapshot.tunnel),
+      // 直连隧道（tailcat）：手机据此自己把通道加进来，**不需要重新扫码**。
+      // 没开或起不来就是 null，老手机不认识这个字段也无害。
+      tailcat: typeof deps.getTailcat === 'function' ? deps.getTailcat() : null,
       // 以本进程解析出的实际端口为准：sidecar 的快照里 `port` 才是最终 bind 成功的
       // 那个（它在 listen 之后才拿得到），而这里在探测阶段就已经知道了，两个值一致
       // 才不会让状态接口和二维码互相打架。

package/lib/routes/control-plane.js

@@ -20,6 +20,7 @@ const fs = require('node:fs');
 const net = require('node:net');
 const path = require('node:path');
 const QRCode = require('qrcode');
+const { pairingText } = require('../relay/pairing-payload.cjs');
 const { randomBytes } = require('node:crypto');
 
 const core = require('../relay/core.js');
@@ -285,6 +286,7 @@ function registerControlPlaneRoutes(deps) {
     lanPortInUse,
     getLanPortAdjusted,
     pairingPayload,
+    tailcat,
     restartSidecar,
     // 「手机上最近来过没有」。**只往本机这条状态路由上补**（和 panelUrl 一样），
     // 不动 createStatusView——那份 JSON 手机端也在读，给它加字段是另一个决定。
@@ -503,7 +505,43 @@ 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), panelScope: panelScopeOf(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(), tailcat: deps.tailcat && typeof deps.tailcat.status === 'function' ? deps.tailcat.status() : null, panelUrl: panelUrlOf(req), panelScope: panelScopeOf(req), webAccess: webAccessWindow.status(), ...mobileActivity(), selfCheck: selfCheck.snapshot() })) })
+
+  // ── 手机直连隧道（Tailcat）：面板查看与管理 ────────────────────────────────
+  //
+  // 状态那一格已经跟着 `/api/relay/status` 一起回了（`tailcat`），这里再补两条**动作**：
+  // 一是这整条通道的总开关，二是把某台手机从白名单里摘掉。两道都直接转给宿主侧的
+  // tailcat 会话（`lib/tailcat/session.cjs`），面板不碰 tailcat 的任何细节。
+  //
+  // 为什么白名单是「节点公钥」而不是设备 id：隧道那一层只认 WireGuard 公钥，和移动端
+  // 凭据是两套东西 —— 吊销设备凭据并不会把它从隧道白名单里摘掉（见 A3-87）。所以这里
+  // 单独给一个出口，否则「踢一台手机」在隧道这一层无法完成。
+  const tailcatSnapshot = () => {
+    const state = deps.tailcat && typeof deps.tailcat.status === 'function' ? deps.tailcat.status() : null
+    const allowed = deps.tailcat && typeof deps.tailcat.allowedClients === 'function' ? deps.tailcat.allowedClients() : []
+    return { ok: true, status: state, allowedClients: Array.isArray(allowed) ? allowed : [] }
+  }
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat', handler: localOnly('GET', async (_req, res) => {
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat/enabled', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    if (deps.tailcat && typeof deps.tailcat.setEnabled === 'function') {
+      deps.tailcat.setEnabled(Boolean(body && body.enabled))
+    }
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat/revoke', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    const client = body && typeof body.client === 'string' ? body.client.trim() : ''
+    if (!client) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 client' } })
+    const current = deps.tailcat && typeof deps.tailcat.allowedClients === 'function' ? deps.tailcat.allowedClients() : []
+    const next = (Array.isArray(current) ? current : []).filter((key) => key !== client)
+    if (deps.tailcat && typeof deps.tailcat.setAllowed === 'function') {
+      deps.tailcat.setAllowed(next)
+    }
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
   // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
   //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
@@ -655,8 +693,25 @@ function registerControlPlaneRoutes(deps) {
     const source = preview && /^https?:\/\/[^\s]+$/i.test(preview.trim())
       ? { ...state, relayUrl: preview.trim().replace(/\/+$/, '') }
       : state
-    const { payload, text } = pairingPayload(source, lanPortInUse())
-    if (!payload.relayUrl && payload.lanUrls.length === 0) {
+    const { payload } = pairingPayload(source, lanPortInUse())
+    // 直连隧道：这一个是「不配中转也能连」的那条路。窗口是现开的一次性小节点（两分钟、
+    // 只放行当场那把钥匙），开不出来就照旧只给局域网与中转——所以它永远只是加一条路，
+    // 不会让原来那套配不上。
+    const tailcat = deps.tailcat && typeof deps.tailcat.openPairingWindow === 'function'
+      ? await deps.tailcat.openPairingWindow(120).catch(() => null)
+      : null
+    if (tailcat) {
+      payload.tailcat = {
+        version: 1,
+        address: tailcat.address,
+        port: tailcat.port,
+        key: tailcat.key,
+        proof: tailcat.proof,
+        expiresAt: tailcat.expiresAt,
+      }
+    }
+    const text = pairingText(payload)
+    if (!payload.relayUrl && payload.lanUrls.length === 0 && !payload.tailcat) {
       sendJson(res, 409, { ok: false, error: '没有可用的局域网或中转连接地址' })
       return
     }
@@ -677,6 +732,9 @@ function registerControlPlaneRoutes(deps) {
         // 的 `lanPort` 不同，不说清楚会让人对着 18787 排查一个根本没在监听的端口。
         lanPort: lanPortInUse(),
         lanPortAdjusted: getLanPortAdjusted(),
+        // 手机拿到的那三样（地址 / 一次性私钥 / 证明串）——只在本机屏幕上出现，
+        // 与二维码同等敏感，所以面板以外的地方不要 log 它。
+        tailcat: tailcat ? { address: tailcat.address, port: tailcat.port, expiresAt: tailcat.expiresAt } : null,
         svg,
       })
     } catch (error) {
@@ -1094,6 +1152,10 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/onboarded',
   '/api/relay/devices',
   '/api/relay/devices/revoke',
+  // 手机直连隧道（Tailcat）的查看与管理。
+  '/api/relay/tailcat',
+  '/api/relay/tailcat/enabled',
+  '/api/relay/tailcat/revoke',
   '/api/relay/revoke-all',
   '/api/relay/config',
   '/api/relay/check-port',

package/lib/routes/mobile-api.js

@@ -12,6 +12,7 @@
  */
 
 const { sendJson } = require('../http/routing.js');
+const { readJsonBody } = require('../shared/http-util.js');
 const { orderCandidates, withManualCandidate, withManualIpv6Candidate } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
@@ -58,8 +59,13 @@ 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 extensionCatalog = require('../mobile/extension-catalog.js');
 const sessionDelivery = require('../mobile/session-delivery.js');
 const { createPhoneRoutes } = require('../mobile/phone/routes.js');
+// 公众号文章库（见 mobile/wechat.js）：AI 在对话里写、手机上翻阅。
+const wechat = require('../mobile/wechat.js');
+// 悬浮宠物的包目录（见 mobile/pets.js）：素材存在电脑上，手机连着哪台就看哪台。
+const pets = require('../mobile/pets.js');
 // 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
 const pkg = require('../../package.json');
 const desktopView = require('../desktop-view.cjs');
@@ -87,7 +93,7 @@ const API_VERSION = '1';
  *   所以它走 route() 即包 guarded。
  */
 function registerMobileRoutes(deps) {
-  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing, terminalService, cliService, phoneService } = deps;
+  const { registerRoute, tailcat, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing, terminalService, cliService, phoneService } = deps;
   // CLI 会话（`cli-*`）在这张表上分派一次（见 mobile/cli/mobile.js）：它们是 ACP 子进程、
   // 不是宿主的会话，但手机上必须像普通会话一样可用 —— 列表 / 历史 / 发送 / 停止 / 流 /
   // 审批 / 模型全走宿主那套端点。分派发生在 `route()` 里面，下面每条注册都还是原样一行，
@@ -198,6 +204,27 @@ function registerMobileRoutes(deps) {
   // 这里曾写成 `(_ctx, _req, res)`，于是 `res` 是 undefined，而 `sendJson` 的 catch 会把
   // TypeError 当成「连接已关闭」吞掉——既没报错也没回包，请求**永久挂住**；手机 5s 超时后
   // 退回探活接口拿到 ok，报「能连上但不是 DSH 移动端服务」。纯文本的路由表测试抓不到这类错。
+  /**
+   * 直连隧道：一台**已经配过对**的手机把自己的公钥发上来，换回它该拨的地址。
+   *
+   * 这是「插件更新之后老设备不用重新扫码」的那条路：手机手上本来就有这台电脑的凭据，
+   * 只是不知道有隧道这回事。宿主把它的公钥加进白名单、把节点拉起来，再把地址回给它。
+   * 隧道没开（或者这台机器上没有助手）就回 503 + `tunnel-unavailable`，手机照旧走原来的通道。
+   */
+  route('/api/mobile/v1/tunnel', async (_ctx, req, res) => {
+    if (req.method !== 'POST') { sendJson(res, 405, { ok: false }); return }
+    // 信封请求的明文在 `req.body`（守卫解开之后放那儿），原始流已经被守卫读掉了 —— 自己读流
+    // 只会拿到空串，公钥永远为空、一律 400，手机那边看到的却是一句笼统的失败。
+    const body = await readJsonBody(req, 64 * 1024)
+    const publicKey = typeof body?.publicKey === 'string' ? body.publicKey.trim() : ''
+    if (!/^nodekey:[0-9a-f]{64}$/.test(publicKey)) { sendJson(res, 400, { ok: false, error: { code: 'invalid-public-key' } }); return }
+    const entry = tailcat && typeof tailcat.enroll === 'function' ? await tailcat.enroll(publicKey).catch(() => null) : null
+    // 拿不到地址要回一个**非 2xx + 错误码**：手机那侧的 `unwrap` 见到 `ok:false` 会抛，和「请求
+    // 根本没送到」在同一条 catch 里混成一团，界面上就只剩一句笼统的失败（真机上正是这么卡的）。
+    if (!entry) { sendJson(res, 503, { ok: false, error: { code: 'tunnel-unavailable', message: '这台电脑现在给不出隧道地址' } }); return }
+    sendJson(res, 200, { ok: true, address: entry.address, port: entry.port })
+  })
+
   registerRoute({ kind: 'exact', path: '/api/mobile/v1/health', handler: async (_req, res) => {
     sendJson(res, 200, { ok: true, service: 'dsh-mobile-plugin', apiVersion: API_VERSION, version: pkg.version })
   } })
@@ -563,6 +590,13 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/extension/dev/packages', extensionDev.handleDevPackages)
   route('/api/mobile/v1/extension/dev/file', extensionDev.handleDevFile)
 
+  // 随插件 npm 包发布的已审核扩展（见 mobile/extension-catalog.js）：只读包内 extensions/
+  // 这一个固定目录，catalog.json 是审核清单，只有登记过的 slug 才下发。文件清单的 size 与
+  // sha256 由宿主扫目录现算，不信清单里的数字；取文件仍先 resolve 再判前缀，不接受任意路径。
+  // 能力面与开发包那两条同一档 —— 不暴露 shell / 系统设置 / 任意文件读写，也不给写。
+  route('/api/mobile/v1/extension/catalog', extensionCatalog.handleCatalog)
+  route('/api/mobile/v1/extension/catalog/file', extensionCatalog.handleCatalogFile)
+
   // 分享文件的落地通道（App 把手机分享进来的文件分片传上来，见 mobile/uploads.js）。
   // 手机端没有「把文件交给宿主」的路：图片能进 session.send 的 base64 内容块，其它格式
   // 一律进不去。四条端点只做「收字节 → 落盘」：默认落到 `~/.dsh/mobile-inbox/<日期>/<文件名>`，
@@ -664,6 +698,25 @@ function registerMobileRoutes(deps) {
     route('/api/mobile/v1/phone/unbind', phoneRoutes.unbind)
     registerUpgradeRoute({ path: '/api/mobile/v1/phone/control', handler: phoneService.handleUpgrade })
   }
+
+  // 公众号文章库（见 mobile/wechat.js）：文章存在这台电脑上，手机只读。
+  //
+  // 能力面只多「读这一个固定目录」：编号形状卡死（`wx` + 8 位十六进制）、图片名不含斜杠，
+  // 路径全由宿主拼。写文章那条正常走 AI 的工具（`wechat_article_write`）；这里那条 POST
+  // 是给以后「手机上改名 / 删除」留的，App 目前没有入口。
+  route('/api/mobile/v1/wechat/articles', wechat.handleArticleList)
+  route('/api/mobile/v1/wechat/article', wechat.handleArticleRead)
+  route('/api/mobile/v1/wechat/media', wechat.handleArticleMedia)
+  route('/api/mobile/v1/wechat/article/save', wechat.handleArticleWrite)
+  route('/api/mobile/v1/wechat/article/delete', wechat.handleArticleDelete)
+
+  // 悬浮宠物的包目录（见 mobile/pets.js）：内置包随插件包走、只读，用户包在
+  // `$DSH_HOME/storages/mobile-plugin/pets/`。能力面只多「读这两个固定目录 + 删一个用户包」：
+  // id 与文件名都卡成不含斜杠的形状，取文件还要对上列表里那一份，客户端给不了路径。
+  // 建包走 AI 的工具（`pet_pack_write`）；删是人的动作，所以只有那一条 POST。
+  route('/api/mobile/v1/pet/packs', pets.handlePackList)
+  route('/api/mobile/v1/pet/pack/file', pets.handlePackFile)
+  route('/api/mobile/v1/pet/pack/delete', pets.handlePackDelete)
 }
 
 module.exports = { registerMobileRoutes };

package/lib/sidecar-facade-worker.cjs

@@ -26,6 +26,7 @@ const { lanUrls } = require('./relay/lan-network.cjs')
 const core = require('./relay/core.js')
 const { createReconnectScheduler } = require('./reconnect-scheduler.cjs')
 const { isMirrorSnapshotFresh } = require('./mirror-snapshot.cjs')
+const { snapshotAuthorized } = require('./relay/snapshot-auth.js')
 // 凭据库在这个进程里**只读**（§3.7）：写盘只有宿主主进程一家。签发与吊销都经 IPC 交给它，
 // 本地这份按文件指纹重载 —— 两个进程各持一份内存副本、各自整份覆写，后写的赢，于是
 // 「经中转配上的手机回局域网 401」「吊销被回滚」这两条必然出现。
@@ -242,6 +243,13 @@ function snapshotRead(info) {
   // 镜像只在中转连着时才会有新版本推来（原因见 mirror-snapshot.cjs 的说明）：冻结的快照必须
   // 回源主进程，否则中转一断、局域网仍健康时，新建的会话/工作区在 App 里永远不出现。
   if (!isMirrorSnapshotFresh(localSnapshot)) return null
+  // **鉴权**：这条捷径绕开主进程守卫直接回快照，必须自己验一遍凭据。否则只要知道实例号
+  // （印在配对二维码上），不带任何凭据也能经中转读到会话 / 工作区列表。验不过回 null 回源，
+  // 交给主进程守卫如实驳回（401）；被吊销 / 已过期的凭据同样回落，吊销才不会在这条路上失效。
+  if (!snapshotAuthorized(info && info.headers, {
+    lookup: (presented) => credentials.lookup(presented, config.instanceId),
+    verifyLanToken: (presented) => core.verifyLanToken(config.lanSecret, presented, config.instanceId),
+  })) return null
   let url
   try { url = new URL(String((info && info.path) || ''), 'http://127.0.0.1') } catch { return null }
   const pathname = url.pathname

package/lib/tailcat/host-process.cjs

@@ -0,0 +1,266 @@
+'use strict';
+
+/**
+ * 手机直连隧道的电脑端助手进程：找得到就拉起、挂了重拉、退出收掉。
+ *
+ * 这个文件只管「进程」：助手在哪、怎么起、stdout 上那几行事件是什么意思。业务判断
+ * （白名单该是谁、配对窗口什么时候开、状态存到哪）留给调用方——它通过 onEvent 收事件，
+ * 通过 `persist` 事件里的 id 回执告诉助手「这笔改动存住了没有」。助手自己不留状态，
+ * 所以插件永远只有一份真相。
+ *
+ * 二进制从按平台的 npm 包装出来（`dsh-mobile-tailcat-<平台>`），装不上就没有这条通道，
+ * 其余功能一点不受影响——这也是不做运行时下载的理由：走的还是插件自己那条包管理器链路，
+ * 国内镜像、完整性校验、断点重试都是包管理器现成的。
+ *
+ * 助手是 Go 编的原生程序，Windows 上是 .exe；它只监听回环（由插件告诉它本机端口），
+ * 隧道里也只开一个固定端口。
+ */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/** 助手 IPC 版本，跟 tailcat-host/main.go 的 protoVersion 一起改。 */
+const IPC_VERSION = 1;
+
+/** 隧道里那个固定端口，与 tailcat-host/node.go 的 virtualPort 一致。 */
+const TUNNEL_PORT = 48941;
+
+/** 配对窗口那个端口，与 pairingPort 一致（手机侧知道它，但只需拨它一次）。 */
+const PAIRING_PORT = 48942;
+
+/** 一行 IPC 的上限，与助手的 lineLimit 一致。 */
+const MAX_LINE = 64 * 1024;
+
+/** 重启退避：起不来时别把机器打满。 */
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+
+/** 事件里允许出现的键，多一个少一个都当脏数据丢掉（stdout 是私有 IPC）。 */
+const EVENT_KEYS = {
+  ready: ['address'],
+  pairing: ['address', 'port', 'key', 'proof', 'expiresAt'],
+  paired: ['address', 'client'],
+  pairingClosed: [],
+  persist: ['id', 'state', 'allowedClients'],
+  error: ['code'],
+};
+
+const ADDRESS = /^tc[\x21-\x7e]{0,4095}$/;
+const PRIVATE_KEY = /^privkey:[0-9a-f]{64}$/;
+const CLIENT_KEY = /^nodekey:[0-9a-f]{64}$/;
+const PROOF = /^[A-Za-z0-9_-]{43}$/;
+
+/** 这台机器对应哪个平台包（与 tools/build-tailcat-helper.mjs 的 id 一致）。 */
+function platformId(platform = process.platform, arch = process.arch) {
+  const os = platform === 'win32' ? 'win32' : platform;
+  const cpu = arch === 'x64' ? 'x64' : arch === 'arm64' ? 'arm64' : arch;
+  const id = `${os}-${cpu}`;
+  return ['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64', 'win32-x64'].includes(id) ? id : undefined;
+}
+
+/**
+ * 找助手二进制：先按平台包解析（npm 装出来的正常形态），找不到就回 null——
+ * 调用方据此把这条通道标成「不可用」，不要抛错、不要影响插件启动。
+ */
+function resolveBinary(options = {}) {
+  const platform = options.platformId || platformId(options.platform, options.arch);
+  if (!platform) return null;
+  const name = platform === 'win32-x64' ? 'dsh-tailcat-host.exe' : 'dsh-tailcat-host';
+  const pkg = `dsh-mobile-tailcat-${platform}`;
+
+  // 1. 平台包（可选依赖装出来的那份）。npm / pnpm 把可选依赖装在「插件自己这份 node_modules」里，
+  //    所以先按本模块自身所在位置解析（从本文件往上找，嵌套与 hoisted 布局都命中）——运行时的工作
+  //    目录（宿主可能是别处）跟安装目录不是一回事，只按工作目录找会在真实部署里找不到；再退回调用方
+  //    指定路径 / 当前工作目录（老行为，部署方把包放在工作目录时仍可用）。
+  for (const paths of [undefined, options.paths || [process.cwd()]]) {
+    try {
+      const manifest = require.resolve(`${pkg}/package.json`, paths ? { paths } : undefined);
+      const candidate = path.join(path.dirname(manifest), name);
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* 这一路没有：试下一路 */
+    }
+  }
+
+  // 2. 指定的路径（开发机、或者部署方自己放好的那一份）。
+  const override = process.env.DSHM_TAILCAT_HELPER;
+  if (typeof override === 'string' && override && fs.existsSync(override)) return override;
+
+  // 3. 本仓交叉编译的产物（开发与自测用）。
+  const dev = path.join(__dirname, '..', '..', '..', 'build', 'tailcat-runtime', platform, name);
+  if (fs.existsSync(dev)) return dev;
+  return null;
+}
+
+/**
+ * 拉起一个助手进程。
+ *
+ * options:
+ *   localPort        插件本机 HTTP 端口（隧道里唯一的去处）
+ *   name             这台电脑的名字（手机配对时显示）
+ *   state            上次存下来的身份（字符串）或 null
+ *   allowedClients   已经配过对的手机公钥
+ *   onEvent(event)   事件回调，event 已去掉 event 字段之外的脏数据
+ *   resolve          覆盖二进制查找（测试用）
+ */
+function createTailcatHost(options) {
+  const binary = (options.resolve || resolveBinary)(options);
+  let child;
+  let buffer = '';
+  let closed = false;
+  let restarts = 0;
+  let backoffIndex = 0;
+  let restartTimer;
+  let ready = false;
+  let address = '';
+
+  const status = () => ({ available: Boolean(binary), running: Boolean(child), ready, address, restarts });
+
+  function write(value) {
+    if (!child || !child.stdin || !child.stdin.writable) return;
+    child.stdin.write(`${JSON.stringify(value)}\n`);
+  }
+
+  function handleLine(line) {
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      return; // 脏行直接丢，从不回显
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+    const kind = value.event;
+    if (typeof kind !== 'string' || !EVENT_KEYS[kind]) return;
+    const keys = Object.keys(value);
+    const fields = EVENT_KEYS[kind];
+    if (keys.length !== fields.length + 1 || fields.some(field => !(field in value))) return;
+
+    if (kind === 'ready' && typeof value.address === 'string' && (value.address === '' || ADDRESS.test(value.address))) {
+      ready = true;
+      address = value.address;
+      backoffIndex = 0;
+    } else if (kind === 'pairing') {
+      if (!ADDRESS.test(String(value.address)) || value.port !== PAIRING_PORT) return;
+      if (!PRIVATE_KEY.test(String(value.key)) || !PROOF.test(String(value.proof))) return;
+      if (!Number.isSafeInteger(value.expiresAt)) return;
+    } else if (kind === 'paired') {
+      if (!CLIENT_KEY.test(String(value.client)) || !ADDRESS.test(String(value.address))) return;
+      address = value.address;
+    } else if (kind === 'persist') {
+      if (typeof value.id !== 'string' || value.id.length > 32) return;
+      if (!Array.isArray(value.allowedClients)) return;
+    } else if (kind === 'error') {
+      if (typeof value.code !== 'string' || value.code.length > 64) return;
+      ready = false;
+    }
+    options.onEvent({ ...value });
+  }
+
+  function scheduleRestart() {
+    if (closed || restartTimer) return;
+    const delay = BACKOFF_MS[Math.min(backoffIndex, BACKOFF_MS.length - 1)];
+    backoffIndex += 1;
+    restarts += 1;
+    restartTimer = setTimeout(() => {
+      restartTimer = undefined;
+      launch();
+    }, delay);
+    restartTimer.unref?.();
+  }
+
+  function launch() {
+    if (closed || !binary) return;
+    let proc;
+    try {
+      proc = spawn(binary, [], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
+    } catch {
+      scheduleRestart();
+      return;
+    }
+    child = proc;
+    buffer = '';
+    ready = false;
+    proc.on('error', () => {});
+    proc.stdin?.on('error', () => {});
+    proc.stdout?.setEncoding('utf8');
+    proc.stdout?.on('data', chunk => {
+      if (child !== proc) return;
+      buffer += chunk;
+      for (let at = buffer.indexOf('\n'); at >= 0; at = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, at);
+        buffer = buffer.slice(at + 1);
+        handleLine(line);
+      }
+      if (buffer.length > MAX_LINE) proc.kill();
+    });
+    proc.on('exit', () => {
+      if (child !== proc) return;
+      child = undefined;
+      ready = false;
+      address = '';
+      if (!closed) scheduleRestart();
+    });
+    write({
+      version: IPC_VERSION,
+      localPort: options.localPort,
+      name: String(options.name || os.hostname()).slice(0, 64),
+      state: options.state === undefined ? null : options.state,
+      allowedClients: Array.isArray(options.allowedClients) ? options.allowedClients : [],
+    });
+  }
+
+  return {
+    status,
+    start() {
+      if (closed || child) return;
+      launch();
+    },
+    /** 开一个配对窗口（助手自己管两分钟过期）。 */
+    pair(ttlSeconds) {
+      write({ command: 'pair', ttl: ttlSeconds });
+    },
+    cancelPairing() {
+      write({ command: 'cancelPairing' });
+    },
+    /** 换白名单（吊销手机就走这条）。 */
+    setAllowed(allowedClients) {
+      write({ command: 'setAllowed', allowedClients: allowedClients || [] });
+    },
+    /** 回执：state 存住了没有。 */
+    ack(id, ok) {
+      write({ command: 'ack', id, ok: Boolean(ok) });
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      if (restartTimer) clearTimeout(restartTimer);
+      restartTimer = undefined;
+      const proc = child;
+      child = undefined;
+      if (!proc || proc.exitCode !== null) return;
+      // 收起 stdin 就是助手的停止信号；它无视才强杀。
+      await new Promise(done => {
+        const timer = setTimeout(() => {
+          proc.kill();
+          done();
+        }, 3_000);
+        timer.unref?.();
+        proc.once('exit', () => {
+          clearTimeout(timer);
+          done();
+        });
+        proc.stdin?.end();
+      });
+    },
+  };
+}
+
+module.exports = {
+  IPC_VERSION,
+  TUNNEL_PORT,
+  PAIRING_PORT,
+  platformId,
+  resolveBinary,
+  createTailcatHost,
+};