dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/routes/control-plane.js

@@ -0,0 +1,311 @@
+'use strict';
+
+/**
+ * 控制面路由（`/api/relay/*`）：桌面端设置页与宿主本机运维动作走这里。
+ *
+ * 与移动端路由表（lib/routes/mobile-api.js）是刻意的两套：控制面只认本机来源
+ * （localOnly），移动端只认 token（guarded）。这条不对称是有原因的——控制面会读
+ * 进程级错误账本（含堆栈）并且能改配置、能吊销全部授权，暴露给中转等于把桌面端的
+ * 后门开到公网；反过来，移动端请求可能来自中转，根本没有本机 socket 可言。
+ *
+ * 抽出来的原因与移动端路由表一样：它们原本是 apply() 闭包里连着 130 多行的注册语句，
+ * 混在 sidecar 生命周期与镜像推送之间，改一条路由要在 1000 行文件里找。依赖以
+ * 取值器/函数注入，不捕获对象——闭包里那些 `let`（sidecarSnapshot、lanPortAdjusted、
+ * sidecarState…）会被整体替换或重新赋值。`getSidecar` 尤其重要：sidecar 会被自重启换掉，
+ * 拿到实例本身就等于拿到一份指向旧 facade 的快照。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const QRCode = require('qrcode');
+const { randomBytes } = require('node:crypto');
+
+const core = require('../relay/core.js');
+const pairingApproval = require('../relay/pairing-policy.js');
+const desktopView = require('../desktop-view.cjs');
+const readReceipt = require('../read-receipt.cjs');
+// 客户端半边的活体台账：两条绿点同步通道都是「单向轮询 + 无回执」，不记账就永远分不开
+// 「那半边根本没在跑」和「跑了但没清掉」（详见 lib/desktop-half-stats.cjs 的文件头）。
+const desktopHalf = require('../desktop-half-stats.cjs');
+const { clearCompletionForAllDevices, invalidateSessionList } = require('../mobile/session-cache.js');
+
+/** 一次 desktop-read 上报最多带多少个会话 id（防灌爆；客户端半边一次最多也就几个）。 */
+const MAX_DESKTOP_READ_IDS = 200;
+
+/**
+ * 面板页（`React/` 那份 React 源码构建成的单文件 HTML）在包里的位置。
+ *
+ * 用 `__dirname` 而不是包根：控制面路由住在「实现代」里（`lib/.live/<releaseId>/…`），
+ * 所以这一份 HTML 跟着实现代一起换代 —— 改版式走 `/update/apply` 就生效，不用重装、
+ * 不用重启 DSH。这正是把设置界面从客户端半边（`lib/client.js`，不可热替换）搬过来的原因。
+ */
+const PANEL_FILE = path.join(__dirname, '..', 'panel', 'index.html');
+
+/** 按 mtime 缓存：换代之后路径变了、内容变了，缓存自然失效，不必手工清。 */
+let panelCache = { file: '', mtime: -1, html: '' };
+
+function panelHtml() {
+  try {
+    const stat = fs.statSync(PANEL_FILE);
+    if (panelCache.file === PANEL_FILE && panelCache.mtime === stat.mtimeMs) return panelCache.html;
+    const html = fs.readFileSync(PANEL_FILE, 'utf8');
+    panelCache = { file: PANEL_FILE, mtime: stat.mtimeMs, html };
+    return html;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 面板页的绝对地址，给客户端半边那个「打开配置页面」的链接用。
+ *
+ * **必须是绝对 http(s) 地址**：桌面版把前端挂在 `dsh-app://app/` 下，页面里写相对
+ * 地址会被解析成那个自定义协议，而 Electron 的 `setWindowOpenHandler` 只把 http(s)
+ * 交给系统浏览器，其它协议一律静默丢弃（devmap 的面板入口踩过这个坑）。
+ * 拿不到 Host 头就回空串，让客户端半边退成「还没就绪」而不是给一个点不开的链接。
+ */
+function panelUrlOf(req) {
+  const host = typeof req?.headers?.host === 'string' ? req.headers.host : '';
+  if (!host) return '';
+  const forwarded = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim();
+  return `${forwarded || 'http'}://${host}/api/relay/panel`;
+}
+
+/**
+ * @param {object} deps 见 index.js 里 registerControlPlaneRoutes({...}) 的调用点
+ */
+function registerControlPlaneRoutes(deps) {
+  const {
+    registerRoute,
+    localOnly,
+    readJson,
+    sendJson,
+    sendHtml,
+    state,
+    sidecarToken,
+    status,
+    settings,
+    syncSidecar,
+    getSidecar,
+    credentials,
+    activeGuard,
+    resolveLanPort,
+    lanPortInUse,
+    getLanPortAdjusted,
+    pairingPayload,
+    restartSidecar,
+    // 插件 ctx。只给「桌面端说它读过了」那条路由用：它要清掉宿主侧的完成提醒。
+    // 缺省 null 时那条路由降级为「只回 200、什么都不清」。
+    ctx = null,
+  } = deps;
+
+  // Pairing approval. The desktop shell used to answer this with an interactive
+  // prompt; a headless host has no surface for one, so `pairingPolicy` decides.
+  // Both transports funnel through here — the relay forwards `pairRequest` and
+  // the LAN proxy calls the worker's onApprove — and the sidecar treats anything
+  // other than an explicit `true` as a rejection, so 'deny' reproduces the
+  // previous fail-closed behaviour exactly.
+  //
+  // 这条不走 localOnly：它由中转与局域网代理代转，没有本机 socket 可言。身份靠
+  // sidecarToken（中转与 worker 之间的共享密钥）。
+  registerRoute({ kind: 'exact', path: '/api/relay/internal/approval', handler: async (req, res) => {
+    if (req.headers.authorization !== `Bearer ${sidecarToken}`) return sendJson(res, 401, { error: 'unauthorized' })
+    let body = {}
+    try { body = (await readJson(req)) || {} } catch { body = {} }
+    const decision = pairingApproval.evaluate(state.pairingPolicy, body.device)
+    // Audit trail: the removed prompt showed the device before letting it in.
+    process.stderr.write(`[dsh-mobile-plugin] pairing ${decision.approved ? 'approved' : 'denied'} policy=${decision.policy} device=${decision.device}${decision.ip ? ` ip=${decision.ip}` : ''}\n`)
+    return sendJson(res, 200, { data: { approved: decision.approved, reason: decision.reason } })
+  } })
+  // 控制面状态里额外带上面板页的绝对地址：客户端半边（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) })) })
+  // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
+  // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
+  //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
+  //   /api/relay/panel/setup      强制走引导（想再看一遍流程时用）
+  //   /api/relay/panel/settings   强制进主页（演示 / 排查时跳过引导）
+  // 整页 HTML 不需要 token，但这几条仍然走 localOnly —— 它读的是本机运维界面，
+  // 而局域网与中转那两条链路本来就不该看到它（它们带 dsh_pair/dsh_lan 凭据，会被挡掉）。
+  const servePanel = (res) => {
+    const html = panelHtml();
+    if (!html) return sendJson(res, 500, { ok: false, error: { code: 'panel_missing', message: '面板页面还没构建：在 dsh-mobile-plugin/React 里跑一次 pnpm run build' } });
+    return sendHtml(res, 200, html);
+  };
+  registerRoute({ kind: 'exact', path: '/api/relay/panel', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
+  registerRoute({ kind: 'exact', path: '/api/relay/panel/setup', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
+  registerRoute({ kind: 'exact', path: '/api/relay/panel/settings', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
+  // 桌面端工作区视图（侧栏展开态）的回传/读取。桌面端只把展开态记在浏览器
+  // localStorage 里，宿主进程读不到，只能由页面内的客户端半边（lib/client.js）
+  // 每 2s 变了就 POST 到这里；App 再经 /api/mobile/v1/desktop-view 取走。
+  registerRoute({ kind: 'exact', path: '/api/relay/desktop-view', handler: localOnly(['GET', 'POST'], async (req, res) => {
+    if (String(req.method || 'GET').toUpperCase() === 'GET') {
+      return sendJson(res, 200, { ok: true, view: desktopView.snapshot() })
+    }
+    let body = {}
+    try { body = (await readJson(req)) || {} } catch { body = {} }
+    try {
+      desktopHalf.noteDesktopViewPost()
+      return sendJson(res, 200, { ok: true, view: desktopView.update(body) })
+    } catch (error) {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: String((error && error.message) || error) } })
+    }
+  }) })
+  // 手机端「已读回执」的下发口：客户端半边每 2s GET 一次，拿 sessionId → readAt 水位，
+  // 对水位前进过的会话在桌面页面里就地清掉 completionUnread（见 lib/client.js）。
+  // 台账由 /api/mobile/v1/session/read 写（lib/mobile/session-send.js）。
+  registerRoute({ kind: 'exact', path: '/api/relay/read-receipt', handler: localOnly('GET', async (_req, res) => {
+    desktopHalf.noteReadReceiptGet()
+    return sendJson(res, 200, { ok: true, receipt: readReceipt.snapshot() })
+  }) })
+  // 客户端半边的自检上报口。它每 10s 把自己「能不能看见那两个服务」报一次：
+  // 宿主只能数出「它没来敲门」，数不出「它为什么没来」，而这条通道是唯一的问法。
+  // 只收白名单里的布尔/短字符串/整数（见 lib/desktop-half-stats.cjs 的 noteClientHalf）。
+  registerRoute({ kind: 'exact', path: '/api/relay/client-half', handler: localOnly('POST', async (req, res) => {
+    let body = {}
+    try { body = (await readJson(req)) || {} } catch { body = {} }
+    return sendJson(res, 200, { ok: true, client: desktopHalf.noteClientHalf(body) })
+  }) })
+  // 反方向：桌面端页面里的客户端半边发现某个会话的未读绿点掉了（用户刚在桌面点开），
+  // 把它报回宿主，宿主清掉**所有设备**维度上的完成提醒，手机端侧栏随之灭灯。
+  // 只清「刚刚掉出去」的那些 id：首帧的全量未读集合不上报，否则会把还没读的也灭掉。
+  registerRoute({ kind: 'exact', path: '/api/relay/desktop-read', handler: localOnly('POST', async (req, res) => {
+    let body = {}
+    try { body = (await readJson(req)) || {} } catch { body = {} }
+    const raw = Array.isArray(body.sessionIds) ? body.sessionIds : []
+    const ids = []
+    for (const item of raw) {
+      if (typeof item !== 'string') continue
+      const id = item.trim()
+      if (!id || id.length > 200 || ids.includes(id)) continue
+      ids.push(id)
+      if (ids.length >= MAX_DESKTOP_READ_IDS) break
+    }
+    if (!ids.length) return sendJson(res, 200, { ok: true, cleared: 0 })
+    if (!ctx) return sendJson(res, 200, { ok: true, cleared: 0 })
+    let cleared = 0
+    for (const id of ids) cleared += clearCompletionForAllDevices(ctx, id)
+    desktopHalf.noteDesktopRead({ ids: ids.length, cleared })
+    // 有东西真被清掉才作废列表缓存：invalidateSessionList 会抬 generation，
+    // 让镜像推送器重建清单并广播 device/list-changed（见 A3-14）。
+    if (cleared > 0) invalidateSessionList(ctx)
+    return sendJson(res, 200, { ok: true, cleared })
+  }) })
+  // The process-level error ledger (see lib/host-guard.cjs). "Stop an unknown
+  // error before it kills DSH" is only actionable if the faults are visible, and
+  // they cannot ride on /api/relay/status: that one is answered by the sidecar
+  // worker, a different process that never sees this one's uncaught errors.
+  // Local-only, same as status — the ledger carries stack traces.
+  registerRoute({ kind: 'exact', path: '/api/relay/faults', handler: localOnly('GET', async (_req, res) => {
+    const guard = activeGuard()
+    if (!guard) return sendJson(res, 200, { ok: true, installed: false, faults: [], stats: null })
+    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) => {
+    if (!state.enabled) {
+      sendJson(res, 409, { ok: false, error: '请先启用远程控制并保存配置' })
+      return
+    }
+    await resolveLanPort()
+    const { payload, text } = pairingPayload(state, lanPortInUse())
+    if (!payload.relayUrl && payload.lanUrls.length === 0) {
+      sendJson(res, 409, { ok: false, error: '没有可用的局域网或中转连接地址' })
+      return
+    }
+    try {
+      const svg = await QRCode.toString(text, {
+        type: 'svg',
+        errorCorrectionLevel: 'M',
+        margin: 2,
+        width: 280,
+      })
+      sendJson(res, 200, {
+        ok: true,
+        name: payload.name,
+        relayUrl: payload.relayUrl,
+        lanUrls: payload.lanUrls,
+        pairingCode: payload.code,
+        // 二维码里带的局域网地址用的是这个端口：首选端口被占时它与 relay.json 里
+        // 的 `lanPort` 不同，不说清楚会让人对着 18787 排查一个根本没在监听的端口。
+        lanPort: lanPortInUse(),
+        lanPortAdjusted: getLanPortAdjusted(),
+        svg,
+      })
+    } catch (error) {
+      sendJson(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+    }
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/toggle', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    await settings.update({ enabled: Boolean(body && body.enabled) })
+    // 等同步真正落地再回状态，否则返回的是重启前的旧快照。
+    await syncSidecar().catch(() => undefined)
+    sendJson(res, 200, status())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/regenerate', handler: localOnly('POST', async (_req, res) => {
+    state.pairingCode = core.genPairingCode()
+    core.saveState(state)
+    await syncSidecar().catch(() => undefined)
+    sendJson(res, 200, status())
+  }) })
+  // 「首次接入引导已经走完」的标记。落盘（saveState 把整个 state 写进 relay.json），
+  // 所以换浏览器、换端口、重启宿主都还在；面板据此决定打开时先走引导还是直接进主页。
+  // 刻意不碰 sidecar、也不进 RemoteControlSettingsSchema：它不是一项远程控制配置，
+  // 改它不该触发一次重配（那条链上每加一个字段都要同步改三处，见 core.js 的注释）。
+  registerRoute({ kind: 'exact', path: '/api/relay/onboarded', handler: localOnly('POST', async (_req, res) => {
+    state.onboarded = true
+    core.saveState(state)
+    sendJson(res, 200, status())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/revoke-all', handler: localOnly('POST', async (_req, res) => {
+    // 清除所有授权 = 中转清空本实例全部设备授权 + 本机吊销局域网设备凭据 +
+    // 轮换 lanSecret/配对码。三处都要做：只清中转的话，同网设备仍能用旧的
+    // `dshc_` 凭据直连宿主，而移动端的「撤销全部授权」正是在要求它们全部失效。
+    let revoked = 0
+    try {
+      const result = await getSidecar().request('/revoke-all', 'POST', undefined, 20_000)
+      revoked = Number(result && result.revoked) || 0
+    } catch { /* 中转不可达时仍继续吊销本机凭据与密钥 */ }
+    const localRevoked = credentials.revokeAllByInstance(state.instanceId)
+    state.lanSecret = randomBytes(32).toString('hex')
+    state.pairingCode = core.genPairingCode()
+    core.saveState(state)
+    await syncSidecar().catch(() => undefined)
+    sendJson(res, 200, { ok: true, revoked: revoked + localRevoked, revokedRelay: revoked, revokedLocal: localRevoked, ...status() })
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/config', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    const patch = {}
+    if (typeof body?.relayUrl === 'string') patch.relayUrl = body.relayUrl.trim()
+    if (typeof body?.lanEnabled === 'boolean') patch.lanEnabled = body.lanEnabled
+    if (Number.isInteger(body?.lanPort) && body.lanPort >= 1024 && body.lanPort <= 65535) patch.lanPort = body.lanPort
+    if (typeof body?.name === 'string' && body.name.trim()) patch.name = body.name.trim()
+    if (body?.pairingPolicy === 'code' || body?.pairingPolicy === 'deny') patch.pairingPolicy = body.pairingPolicy
+    // 注册密钥：只接受字符串，过长拒绝；写空串等于关掉（回到"中转开了校验就连不上"）。
+    if (typeof body?.registerSecret === 'string' && body.registerSecret.length <= 512) patch.registerSecret = body.registerSecret
+    await settings.update(patch)
+    await syncSidecar().catch(() => undefined)
+    sendJson(res, 200, status())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/reconnect', handler: localOnly('POST', async (_req, res) => {
+    await syncSidecar()
+    sendJson(res, 200, status())
+  }) })
+  // ── 插件更新 ──
+  //
+  // 这里**没有**自更新路由了（2026-10 拆掉）：插件从 npm 分发，更新由 DSH 的插件市场做
+  // （网页版那张卡片直接调市场的公共更新接口 `/dsh-market/api/v1/*`，见 React/）。
+  // 原来那四条（`/update/{status,check,apply,reload}`）走的是中转的插件 OTA 与 `.live`
+  // 代机制，整套已经删掉 —— 插件只剩一条更新路径：市场装新版本 + 重启 DSH。
+
+
+  // sidecar 自重启：换掉 worker 子进程 + facade 模块，宿主本身不重启。
+  // 走 localOnly——和其余控制面一样，这是本机运维动作。
+  registerRoute({ kind: 'exact', path: '/api/relay/restart-sidecar', handler: localOnly('POST', async (_req, res) => {
+    const result = await restartSidecar()
+    sendJson(res, result.ok ? 200 : 500, { ...result, status: status() })
+  }) })
+}
+
+module.exports = { registerControlPlaneRoutes };

package/lib/routes/mobile-api.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * 移动端 API 路由表（`/api/mobile/v1/*`）。
+ *
+ * 这块此前是 lib/index.js 里连续 120 多行的注册语句，与控制面路由、sidecar 生命周期、
+ * 镜像推送调度器混在同一个 apply() 闭包里。它本身没有任何逻辑——绝大部分是「路径 → 已
+ * 写好的 handler」的纯映射，只有 status / connection-info / desktop-view 三条带一点内联
+ * 逻辑——但混在装配代码里有两个代价：
+ *
+ *   1. 想确认「App 打的某个地址到底注册没有」必须人工通读 apply()。
+ *      历史上 `workspace/rename` 与 `workspace/archive-session` 就是 App 一直在打、
+ *      插件从来没注册，手机端必然 404。
+ *   2. 改一条路径要在 1000 行文件里找。
+ *
+ * 现在它是一张可以一眼读完、可以对着 App 侧 apiPaths.ts 核对的表。
+ *
+ * 依赖注入只留三样：注册器、移动端守卫、以及两个会变的值。handler 们直接 require，
+ * 因为它们本来就只是被这张表挂上去的。
+ */
+
+const { sendJson } = require('../http/routing.js');
+
+const sessions = require('../mobile/sessions.js');
+const agentPresets = require('../mobile/agent-presets.js');
+const stream = require('../mobile/stream.js');
+const events = require('../mobile/events.js');
+const questions = require('../mobile/questions.js');
+const workspaces = require('../mobile/workspaces.js');
+const sessionLog = require('../mobile/session-log.js');
+const hostSettings = require('../mobile/host-settings.js');
+const skills = require('../mobile/skills.js');
+const mobileCredentials = require('../mobile/credentials.js');
+const subagents = require('../mobile/subagents.js');
+const references = require('../mobile/references.js');
+const plugins = require('../mobile/plugins.js');
+const desktopView = require('../desktop-view.cjs');
+
+const API_VERSION = '1';
+
+/**
+ * @param {object} deps
+ * @param {(route: object) => void} deps.registerRoute 交给 ctx.webServer 的注册器
+ * @param {(handler: Function) => Function} deps.guarded 移动端守卫（token + 500 信封）
+ * @param {object} deps.state 内存里的中转状态（本进程唯一真值）
+ * @param {() => object} deps.hostMetadata 宿主元信息（隧道准入状态等）
+ * @param {() => object} deps.getSidecarSnapshot 取快照的**取值器**。
+ *   这里必须传函数而不是对象：sidecarSnapshot 是会被 applySidecarConfig 整体替换的
+ *   let 变量，闭包捕获对象会让 handler 永远读到启动那一刻的旧快照（lan.updatedAt 停在
+ *   进程启动时间，手机端看连接信息像失联了一样）。
+ * @param {(port: number) => Array<object>} deps.safeLanCandidates 局域网候选地址
+ * @param {() => number} deps.lanPortInUse 手机该拨的局域网端口。**必须用取值器**：
+ *   sidecar 自己 bind 到的端口可能与本进程解析出的不同（两条端口自适应），只认
+ *   `state.lanPort` 会把这个接口变成「报一个没人监听的端口」——真机实测过 50933
+ *   死地址把手机逼回公网中转（见 impl.js 的 advertisedLanPort）。
+ * @param {(route: { path: string, handler: Function }) => void} deps.registerUpgradeRoute
+ *   交给 ctx.webServer 的**升级**路由注册器（`registerUpgrade`）。与 registerRoute 是
+ *   两套名字空间：同一个 path 可以既有一条普通路由又有一条升级路由，但升级路由重复注册
+ *   会抛错。
+ * @param {object} deps.preview 预览字节管道服务（lib/relay/preview.js）。它自带鉴权与
+ *   端口边界，所以**不能**包在 guarded 里——guarded 回的是 JSON，而升级请求需要的是
+ *   一次拒绝或一次握手。
+ */
+function registerMobileRoutes(deps) {
+  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, lanPortInUse, preview } = deps;
+  const route = (path, handler) => registerRoute({ kind: 'exact', path, handler: guarded(handler) })
+
+  registerRoute({ kind: 'exact', path: '/api/mobile/v1/status', handler: guarded(async (_ctx, _req, res) => {
+    // 内存 `state` 是本进程唯一的真值。旧实现这里 `loadRelayState()` 重新读盘，
+    // 于是同一份状态出现两个来源：控制面改完内存立刻返回，而移动端读到的还是
+    // 上一次落盘的内容（多实例/慢盘时甚至永久不一致）。
+    sendJson(res, 200, {
+      ok: true,
+      apiVersion: API_VERSION,
+      instanceId: state.instanceId || null,
+      name: state.name || null,
+      remoteEnabled: Boolean(state.enabled),
+      ...hostMetadata(),
+    })
+  }) })
+  // 局域网/中转连接信息。公网配对时由中转在 `/api/mobile/v1/connection-info`
+  // 代答宿主上报的镜像数据；但纯局域网配对（App 只扫到局域网二维码、完全不经
+  // 中转）需要宿主自己回答同一个地址，否则 App 拿不到 lanCandidates，换网卡后
+  // 就再也找不到这台机器。字段与中转侧保持一致以便 App 用同一套解析。
+  route('/api/mobile/v1/connection-info', async (_ctx, _req, res) => {
+    // 端口取「手机该拨的那个」（sidecar 真 bind 成的），不是配置里的首选端口：
+    // 两者不一致时这里报出去的候选是死地址，手机只能退回公网中转。
+    const port = typeof lanPortInUse === 'function' ? lanPortInUse() : state.lanPort
+    const candidates = state.lanEnabled ? safeLanCandidates(port) : []
+    const lanUpdatedAt = getSidecarSnapshot()?.lan?.updatedAt || Date.now()
+    sendJson(res, 200, {
+      ok: true,
+      instanceId: state.instanceId || null,
+      name: state.name || null,
+      relayUrl: state.enabled ? (state.relayUrl || null) : null,
+      lanUrls: candidates,
+      lanCandidates: candidates,
+      updatedAt: lanUpdatedAt,
+      lastSeen: lanUpdatedAt,
+    })
+  })
+
+  route('/api/mobile/v1/sessions', sessions.handleSessions)
+  route('/api/mobile/v1/session', sessions.handleSession)
+  route('/api/mobile/v1/session/messages', sessions.handleMessages)
+  route('/api/mobile/v1/session/send', sessions.handleSend)
+  route('/api/mobile/v1/commands', sessions.handleCommands)
+  route('/api/mobile/v1/session/read', sessions.handleSessionRead)
+  route('/api/mobile/v1/session/stop', sessions.handleStop)
+  route('/api/mobile/v1/session/rename', sessions.handleRename)
+  route('/api/mobile/v1/session/fork', sessions.handleFork)
+  route('/api/mobile/v1/session/models', sessions.handleModels)
+  route('/api/mobile/v1/session/select-model', sessions.handleSelectModel)
+  route('/api/mobile/v1/session/stats', sessions.handleStats)
+  // 正文检索（宿主 session.search 的移动端代理）：只回 { sessionId, snippet }，
+  // 标题 / 工作区由 App 用自己轮询到的会话列表拼接，见 mobile/sessions.js。
+  route('/api/mobile/v1/session/search', sessions.handleSessionSearch)
+  // Agent 预设（宿主 agentPreset.list / agentPreset.select 的移动端代理）。桌面端
+  // 会话头标签、设置行、hero 芯片都读这份名单；宿主未配置 roster 时 list 回空数组。
+  route('/api/mobile/v1/agent-presets', sessions.handleAgentPresets)
+  // Agent 预设管理（宿主 agentPreset.read / copy / remove 的移动端代理）：桌面端设置页
+  // 那个「管理分区」——只读查看器、复制（桌面端唯一的创建入口）、删除。此前手机只能
+  // 看到名单与当前档，既读不到预设正文也造不出自己的预设。
+  route('/api/mobile/v1/agent-presets/read', agentPresets.handleAgentPresetRead)
+  route('/api/mobile/v1/agent-presets/copy', agentPresets.handleAgentPresetCopy)
+  route('/api/mobile/v1/agent-presets/remove', agentPresets.handleAgentPresetRemove)
+  route('/api/mobile/v1/session/new', sessions.handleNew)
+  route('/api/mobile/v1/session/stream', stream.handleStream)
+  route('/api/mobile/v1/events/stream', events.handleDeviceStream)
+  route('/api/mobile/v1/question/respond', questions.handleQuestionRespond)
+  route('/api/mobile/v1/approval/respond', questions.handleApprovalRespond)
+  route('/api/mobile/v1/session/goal', sessions.handleGoalAction)
+  route('/api/mobile/v1/session/queue/update', sessions.handleQueueUpdate)
+  route('/api/mobile/v1/workspaces', workspaces.handleWorkspaces)
+  // 桌面端工作区展开态镜像（由页面内的客户端半边经 /api/relay/desktop-view 回传）。
+  // 桌面端只把这份状态记在浏览器 localStorage 里，宿主读不到，所以这里给 App 的只是
+  // 「宿主最近收到的快照」；从未收到过时返回 view: null，App 按桌面的折叠缺省处理。
+  route('/api/mobile/v1/desktop-view', async (_ctx, _req, res) => sendJson(res, 200, { ok: true, view: desktopView.snapshot() }))
+  route('/api/mobile/v1/directory/list', workspaces.handleListDirectory)
+  route('/api/mobile/v1/directory/create', workspaces.handleCreateDirectory)
+  route('/api/mobile/v1/workspace/create', workspaces.handleCreateWorkspace)
+  route('/api/mobile/v1/workspace/delete', workspaces.handleDeleteWorkspace)
+  route('/api/mobile/v1/workspace/move-session', workspaces.handleMoveSession)
+  // App 的 `renameWorkspace()` / `archiveSession()` 早就在打这两个地址
+  // （`app/src/services/apiPaths.ts` 的 workspaceRename / workspaceArchiveSession），
+  // 但插件从来没有注册 → 移动端「重命名工作区」和「归档会话」必然 404。
+  route('/api/mobile/v1/workspace/rename', workspaces.handleRenameWorkspace)
+  route('/api/mobile/v1/workspace/archive-session', workspaces.handleArchiveSession)
+  // 桌面端 `/export` 其实是两步：命令本身只留一行 transcript 标记，真正的下载由
+  // @deepseek-ai/dsh-session-log-export 在浏览器侧监听 command/executed 后拉
+  // `GET /api/session.export` 完成。手机端没有浏览器下载管理器，而那个端点绑在宿主
+  // 的 127.0.0.1 上手机直连不到 —— 所以由插件代取（mobile/session-log.js），App 侧
+  // 再落盘。
+  route('/api/mobile/v1/session-log', sessionLog.handleSessionLog)
+  // 宿主设置与模型提供方（宿主 settings.describe / llm.providers 的移动端只读代理）。
+  // 桌面端「设置」里有默认模型、提供方配置、凭据是否已设；手机端此前完全没有这一块，
+  // 只能看到 App 自己的偏好项。两个宿主接口本身已脱敏（secrets 只给 path 与 set），
+  // 插件再丢掉对手机没用的 schema 树，见 mobile/host-settings.js。
+  route('/api/mobile/v1/host-settings', hostSettings.handleHostSettings)
+  // 改设置：与桌面端同一个 settings.mutate（按路径寻址的 op + expectedRevision 乐观并发）。
+  route('/api/mobile/v1/host-settings/mutate', hostSettings.handleHostSettingsMutate)
+  route('/api/mobile/v1/llm/providers', hostSettings.handleLlmProviders)
+  // 技能目录（宿主 skill.list 的移动端只读代理）。桌面端敲「/」时命令候选菜单里
+  // 混着技能（@deepseek-ai/dsh-client-ui-skill 注册的 inputTriggers source），
+  // 手机端此前只有 commands.list 的命令目录，技能一个都看不到，见 mobile/skills.js。
+  route('/api/mobile/v1/skills', skills.handleSkills)
+  // 宿主凭据（宿主 credentials.{describe,set,unset} 的移动端代理）。桌面端设置面板
+  // 能往宿主写 API Key，手机端此前只能看到「1 项密钥未设置」却没有入口，见
+  // mobile/credentials.js。密钥值只在这条路上出现一次，宿主从不回传值。
+  route('/api/mobile/v1/credentials', mobileCredentials.handleCredentialsDescribe)
+  route('/api/mobile/v1/credentials/set', mobileCredentials.handleCredentialsSet)
+  route('/api/mobile/v1/credentials/unset', mobileCredentials.handleCredentialsUnset)
+  // 子代理目录（宿主 subagent.list 的移动端只读代理）。桌面端会话标题栏挂着
+  // 「N 个子代理」下拉，点进去能读子会话的完整记录；手机端把 origin === 'subagent'
+  // 的行在侧栏里 continue 掉之后就再没有任何入口，见 mobile/subagents.js。
+  route('/api/mobile/v1/subagents', subagents.handleSubagents)
+  // 子代理续话与打断（宿主 subagent.prompt / subagent.interrupt 的移动端代理）。
+  // 手机端的输入框只会发 session.send，而宿主对子会话一律回 agent-busy，所以给
+  // 「可继续」子代理发消息必须换这条路由；一次性子代理宿主根本不收续话。
+  route('/api/mobile/v1/subagents/prompt', subagents.handleSubagentPrompt)
+  route('/api/mobile/v1/subagents/interrupt', subagents.handleSubagentInterrupt)
+  // 引用发现（宿主 fileReferences.list / sessionReferenceResolver.candidates 的移动端
+  // 代理）。桌面端输入 @ 会同时查这两个域，文件排在会话前面；手机端此前完全没有补全。
+  // 和插件清单一样，这两个宿主服务不在 apiProxy 上，走 typertGateway，
+  // 见 mobile/references.js。两个域各自独立降级，一个不可用不影响另一个。
+  route('/api/mobile/v1/file-references', references.handleFileReferences)
+  route('/api/mobile/v1/session-references', references.handleSessionReferences)
+
+  // 桌面端 设置 → 插件 的只读部署快照，由 dsh-host-plugin-inventory 拥有，
+  // 经 typertGateway 命名空间 pluginInventory 取，见 mobile/plugins.js。
+  route('/api/mobile/v1/plugins', plugins.handlePlugins)
+
+  // 内置浏览器预览（App 侧「点 localhost 链接在内置浏览器里打开」的宿主端一半）。
+  //
+  // 这是一条 **WebSocket 升级**路由，不是普通 HTTP 路由：手机原生模块按端口在环回监听、
+  // 把 WebView 写下的原始字节塞进 WS 二进制帧；宿主这边 lib/relay/preview.js 完成握手后
+  // 与 `127.0.0.1:<port>` 双向对搬。中转与局域网代理都**不用改**——中转的升级分发只看
+  // 鉴权不看路径，局域网代理更是把任意升级路径原样转给宿主 webServer。
+  //
+  // 端口用查询串带（`?port=3001`）：宿主的升级匹配按 pathname 精确匹配、**忽略查询串**，
+  // 所以下面这个不带查询串的字面量就是那条路由本身。
+  //
+  // 路径字面量必须与 App 侧 apiPaths.ts 的 preview 一致：test/mobile-routes.test.cjs
+  // 就是拿这张表反向核对 App 常量表的。
+  registerUpgradeRoute({ path: '/api/mobile/v1/preview', handler: preview.handleUpgrade })
+}
+
+module.exports = { registerMobileRoutes };

package/lib/routes/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}