dsh-mini-remote 0.1.0

package/lib/store.js

@@ -0,0 +1,334 @@
+/**
+ * 插件端状态：最新一条回复、历史记录、会话绑定、手机在线状态。
+ *
+ * 内存为准，落盘只是为了重启后手机刷新还能看到东西。用 JSON 而不是 SQLite——
+ * 这点数据量（默认 50 条）不值得引依赖。
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+export function createStore({ file, maxHistory = 50, maxSessions = 12 }) {
+  const state = {
+    /**
+     * 单帧模式的数据源：**每个会话各自一条**，sessionId -> { text, title, timestamp, reason }。
+     *
+     * 原来这里是全局一个 latest，于是切到别的会话时，屏幕上还是上一个会话的答案
+     * （2026-09-21 用户实机报的：「切到一个正在执行中的会话，显示的却是之前会话的回答」）。
+     * 和 running 是同一个病根——**显示状态不能跨会话串**。
+     */
+    latestBySession: {},
+    /** 聊天模式的数据源，同样按会话分开。 */
+    historyBySession: {}, // sessionId -> [{ role, text, timestamp, sessionId }]
+    /** 手机当前遥控的那个会话。 */
+    boundSessionId: null,
+    /** 手机会话在线状态，用于决定要不要发外部推送。 */
+    presence: 'foreground',
+    lastSeen: 0,
+    /**
+     * 正在流出来的那一段：sessionId -> string。**故意不落盘**——它是过眼云烟，
+     * 存下来只会在下次启动时冒出一段没头没尾的半句话。
+     *
+     * 为什么要自己留一份：DSH 那条增量事件是**进程本地**的，不重放。手机中途刷新
+     * 或重连时，已经流过的部分再也拿不到，界面会突然空白一下。留一份塞进快照里，
+     * 任何一条广播都能把它补上。
+     */
+    liveBySession: {},
+  }
+
+  /** 已知会话的元信息：sessionId -> { id, title, running, lastActivity, seq } */
+  const sessions = new Map()
+
+  /**
+   * 单调递增的「谁更新」序号。
+   *
+   * 不能用 lastActivity（毫秒时间戳）来判最近活跃：两个会话在同一毫秒里被碰到时
+   * 时间戳相等，而 Map 的迭代顺序是**插入顺序**，于是先插入的那个会赢——
+   * 「最近活跃」就成了错的。这不是理论问题：`session/event` 来得很密，
+   * 同毫秒完全可能。而 index.js 用它决定手机在看哪个会话，判错就会串内容。
+   */
+  let touchSeq = 0
+
+  /** 最近活跃的会话——手机没绑定时默认遥控它。 */
+  function mostRecentSession() {
+    let best = null
+    for (const s of sessions.values()) {
+      if (!best || s.seq > best.seq) best = s
+    }
+    return best
+  }
+
+  /**
+   * 手机此刻在看哪个会话：绑定了认绑定，没绑过才退回最近活跃的。
+   *
+   * 这里和 index.js 的 targetSessionId() 是同一套口径。那边多一层「问 agents 注册表
+   * 要一个」的兜底（插件是热加载进来的、或者会话早就开着了，事件流里一次都没见过），
+   * 但两者都从这张 sessions 表取事实，所以不会打架。
+   */
+  function targetSessionId() {
+    if (state.boundSessionId) return state.boundSessionId
+    return mostRecentSession()?.id ?? null
+  }
+
+  /**
+   * 「队列里还排着什么」从哪儿问。
+   *
+   * 做成一个回调，而不是让 store 自己记一份，是因为队列的**真相在 agent 的收件箱里**
+   * （`agent.inbox.nextTurn`），而 store 拿不到 ctx。每次取快照现读一遍，
+   * 就不存在「手机上显示的队列和电脑上不一致」这种事——根本没有第二份状态可以漂移。
+   *
+   * 默认空实现：测试和 headless 组合里可能没有 agent 注册表，那时就是「队列是空的」。
+   */
+  let queueSource = () => []
+
+  function setQueueSource(fn) {
+    queueSource = typeof fn === 'function' ? fn : () => []
+  }
+
+  /** 某个会话的最新回复；没有就是 null。 */
+  function latestOf(sessionId) {
+    return sessionId ? (state.latestBySession[sessionId] ?? null) : null
+  }
+
+  /** 某个会话的聊天记录；没有就是空数组。 */
+  function historyOf(sessionId) {
+    return sessionId ? (state.historyBySession[sessionId] ?? []) : []
+  }
+
+  /**
+   * 正在流出来的那一段。空字符串表示「这会儿没有东西在流」。
+   *
+   * 只在**已经决定要显示**之后才写进来。服务端会先按兵不动一小会儿再决定露不露
+   * （理由见 lib/index.js 的 STREAM_GRACE_MS），所以这里为空不代表模型没在写，
+   * 只代表「还不到显示的时候」。
+   */
+  function liveOf(sessionId) {
+    return sessionId ? (state.liveBySession[sessionId] ?? '') : ''
+  }
+
+  /**
+   * 只保留最近碰过的若干会话的数据，免得这个 JSON 文件无限长大。
+   * 被丢掉的会话切过去会显示「还没有回复」——**这比显示别人的回答强**。
+   */
+  function trimSessions() {
+    const ids = Object.keys(state.historyBySession)
+    if (ids.length <= maxSessions) return
+    ids.sort((a, b) => (sessions.get(b)?.seq ?? 0) - (sessions.get(a)?.seq ?? 0))
+    for (const id of ids.slice(maxSessions)) {
+      delete state.historyBySession[id]
+      delete state.latestBySession[id]
+      delete state.liveBySession[id]
+    }
+  }
+
+  function pushHistory(sessionId, entry) {
+    let list = state.historyBySession[sessionId]
+    if (!list) list = state.historyBySession[sessionId] = []
+    list.push(entry)
+    if (list.length > maxHistory) list.splice(0, list.length - maxHistory)
+    trimSessions()
+  }
+
+  function load() {
+    try {
+      const raw = JSON.parse(readFileSync(file, 'utf8'))
+      if (raw && typeof raw === 'object') {
+        if (raw.latestBySession && typeof raw.latestBySession === 'object') {
+          state.latestBySession = raw.latestBySession
+        }
+        if (raw.historyBySession && typeof raw.historyBySession === 'object') {
+          for (const [id, list] of Object.entries(raw.historyBySession)) {
+            if (Array.isArray(list)) state.historyBySession[id] = list.slice(-maxHistory)
+          }
+        }
+        // 迁移旧格式（全局一个 latest / history）。按条目里记的 sessionId 归位，
+        // 归不了的丢掉——总比塞给错误的会话强。
+        if (raw.latest?.sessionId && !state.latestBySession[raw.latest.sessionId]) {
+          state.latestBySession[raw.latest.sessionId] = raw.latest
+        }
+        if (Array.isArray(raw.history)) {
+          for (const m of raw.history) {
+            if (m?.sessionId) pushHistory(m.sessionId, m)
+          }
+        }
+        if (raw.boundSessionId) state.boundSessionId = raw.boundSessionId
+      }
+    } catch {
+      // 首次运行没有文件，或文件损坏——都不该让插件起不来。
+    }
+  }
+
+  let flushTimer = null
+  function persist() {
+    if (flushTimer) return
+    // 事件流可能很密（每个 step 都有事件），合并写盘，避免拖慢 agent。
+    flushTimer = setTimeout(() => {
+      flushTimer = null
+      try {
+        mkdirSync(dirname(file), { recursive: true })
+        const tmp = `${file}.tmp`
+        writeFileSync(tmp, JSON.stringify({
+          latestBySession: state.latestBySession,
+          historyBySession: state.historyBySession,
+          boundSessionId: state.boundSessionId,
+        }))
+        renameSync(tmp, file)
+      } catch {
+        // 落盘失败不影响本次运行。
+      }
+    }, 500)
+    if (flushTimer.unref) flushTimer.unref()
+  }
+
+  load()
+
+  return {
+    state,
+    sessions,
+
+    /** 会话出现在事件流里时登记/更新。 */
+    touchSession(sessionId, patch = {}) {
+      let s = sessions.get(sessionId)
+      if (!s) {
+        s = { id: sessionId, title: '', running: false, lastActivity: 0, seq: 0 }
+        sessions.set(sessionId, s)
+      }
+      Object.assign(s, patch, { lastActivity: Date.now(), seq: ++touchSeq })
+      return s
+    },
+
+    forgetSession(sessionId) {
+      sessions.delete(sessionId)
+    },
+
+    setRunning(sessionId, running) {
+      const s = this.touchSession(sessionId, {})
+      s.running = running
+    },
+
+    /** 最近活跃的会话——手机没绑定时默认遥控它。 */
+    mostRecentSession,
+
+    /** 手机此刻在看哪个会话。 */
+    targetSessionId,
+
+    /** 告诉 store「队列里有什么」该去哪儿问（见 setQueueSource）。 */
+    setQueueSource,
+
+    /** 某个会话的最新回复 / 聊天记录。 */
+    latestOf,
+    historyOf,
+
+    bind(sessionId) {
+      state.boundSessionId = sessionId
+      persist()
+    },
+
+    /**
+     * Agent 产出了最终回复。只写进**这个会话**自己的那一份。
+     *
+     * interrupted 是「这一轮被中止了，下面只是已经吐出来的那半句」。
+     * 手机要把它标出来——不标的话，按了停止之后冒出来的半句话看着像模型答崩了。
+     */
+    pushReply({ text, sessionId, reason, interrupted }) {
+      const timestamp = Date.now()
+      const session = sessions.get(sessionId)
+      state.latestBySession[sessionId] = {
+        text, sessionId, title: session?.title ?? '', timestamp, reason,
+        interrupted: interrupted === true,
+      }
+      pushHistory(sessionId, {
+        role: 'assistant', text, timestamp, sessionId, interrupted: interrupted === true,
+      })
+      persist()
+    },
+
+    /** 用户（手机上或电脑上）发出了一条指令。 */
+    pushUser({ text, sessionId, id }) {
+      // id 要留着：排队中的指令靠它和 agent 收件箱里的那一条对上号，
+      // 界面上才能标出「这条还在排队」、也才能撤掉它。
+      pushHistory(sessionId, { role: 'user', text, timestamp: Date.now(), sessionId, id })
+      persist()
+    },
+
+    /**
+     * 清空**当前会话**在单帧模式里的内容。
+     *
+     * **目前没有任何地方调用它**，是历史遗留（清理逻辑当初写在手机端，见 page.html
+     * 的 send()）。而且 2026-09-21 之后，清空这件事本身就是错的方向：用户要的是
+     * 发完指令后上一条回答**留着**，在它下面加一条「正在执行」。别为了「修」什么
+     * 把它接上去。
+     */
+    clearLatest() {
+      const id = targetSessionId()
+      if (id) delete state.latestBySession[id]
+      persist()
+    },
+
+    markSeen(presence) {
+      state.lastSeen = Date.now()
+      if (presence) state.presence = presence
+    },
+
+    /**
+     * 记下「正在流出来的那一段」。传空字符串就是收工。
+     *
+     * **不 persist()**：这是几秒钟的临时状态，写盘只是白费 I/O，还会在下次启动时
+     * 留下一段没头没尾的半句话。快照和广播都从内存里现读。
+     */
+    setLive(sessionId, text) {
+      if (!sessionId) return
+      if (text) state.liveBySession[sessionId] = text
+      else delete state.liveBySession[sessionId]
+    },
+
+    /** 手机是否真的在看着——决定要不要额外发系统推送。 */
+    isForeground() {
+      return state.presence === 'foreground' && Date.now() - state.lastSeen < 60_000
+    },
+
+    snapshot() {
+      const target = targetSessionId()
+      return {
+        /**
+         * latest 和 history 都是**当前这个会话**的那一份。
+         *
+         * 原来是全局一份，于是切到别的会话时，单帧模式里还显示着上一个会话的答案
+         * （2026-09-21 用户实机报的）。和 running 一样，显示状态不能跨会话串。
+         */
+        latest: latestOf(target),
+        history: historyOf(target),
+        /**
+         * 正在流出来的那一段（可能为空）。
+         *
+         * 跟着会话走，和 latest/history 同一条口径。手机把它显示在答案区、但**不**
+         * 当成答案——真正的答案还是要等不含工具调用的那一步落定（见 events.js）。
+         */
+        live: liveOf(target),
+        boundSessionId: state.boundSessionId,
+        /**
+         * 「正在执行」必须跟着会话走。
+         *
+         * 原来它只从 SSE 的 status 事件推过来，于是有两个都实测到的毛病：
+         * 在手机上切到别的会话，那个会话明明闲着也显示「正在执行」（切会话时
+         * 没人重算过它）；页面刷新时如果任务正在跑，又反过来显示「已连接」。
+         * 放进快照里，**任何一条广播都能把它纠正回来**，两个毛病一起没了。
+         */
+        running: target ? (sessions.get(target)?.running ?? false) : false,
+        /**
+         * 排在队里、还没轮到的指令。
+         *
+         * 手机上跑着任务时接着发，那条不会丢，而是排进 agent 的收件箱
+         * （`followup()` 的语义就是「排队一个后续轮次」），等当前这一轮结束再跑。
+         * 既然收下了，就得让用户看见它排在哪——不然和「发出去了但没反应」没区别。
+         *
+         * 每次现读，不缓存：见 setQueueSource 的说明。
+         */
+        queued: target ? queueSource(target) : [],
+        // 同毫秒时用 seq 兜底，顺序才是确定的
+        sessions: [...sessions.values()].sort(
+          (a, b) => (b.lastActivity - a.lastActivity) || (b.seq - a.seq),
+        ),
+      }
+    },
+  }
+}

package/lib/tree.js

@@ -0,0 +1,185 @@
+/**
+ * 工作区 → 会话 的树，给手机左侧导航栏用。
+ *
+ * 数据来自两个服务，都在 web 组合里，headless 组合里没有：
+ *   - workspaceRegistry.list()    同步。工作区的顺序、每个工作区下有哪些会话，
+ *                                 以及会话的排列顺序，全在这里。桌面端左侧栏的
+ *                                 分组用的就是它。
+ *   - sessionQuery.listSessions() 异步。会话的事实：id、创建时间、cwd、origin。
+ *                                 注意它**不含标题**，标题要另外去读日志。
+ *
+ * 两个都不是必需的：拿不到就退回「只知道当前活跃会话」的老样子，不报错。
+ *
+ * 关于规模：本机实测 35 个工作区，最多的一个有 452 个会话。所以这里所有查询
+ * 都是**按需 + 限量**的——打开导航栏只列工作区（便宜），展开某个工作区才去取
+ * 它的会话（要读日志折标题，贵）。
+ */
+import { basename } from 'node:path'
+
+/** 一个工作区默认最多列多少会话。手机上再多也划不动。 */
+export const SESSIONS_PER_WORKSPACE = 20
+
+function safeList(registry) {
+  if (!registry) return []
+  try {
+    return registry.list() ?? []
+  } catch (err) {
+    // 服务还没启动时 requireState() 会抛。导航栏少几项，不该影响遥控本身。
+    return []
+  }
+}
+
+/**
+ * `listSessions()` 很贵：它要扫盘列出所有持久化的会话，再给每条记录做一次
+ * `structuredClone`。本机几百个会话，实测这个接口要 **850 毫秒左右**。
+ *
+ * 而导航栏会反复问同一个问题——打开一次、展开一个工作区、切回来再看一眼，
+ * 每次都问。用户报的「打开导航栏似乎每次都要重新读取」，根源就是这一秒。
+ *
+ * 所以在这里缓存一份。会话列表晚 30 秒知道不算错（手机上你本来也是手动刷新的），
+ * 真想立刻看到最新的，按导航栏的 ⟳，它带 `refresh=1` 绕过缓存。
+ */
+const CACHE_TTL_MS = 30_000
+/**
+ * query 服务 → { at, records, inflight }。
+ *
+ * **用 WeakMap 而不是一个模块级变量**：缓存必须认得出「这份数据是谁的」。
+ * 写成一个全局变量时，服务实例一换（插件重载、测试里每个用例各给一个桩），
+ * 新来的调用方就会拿到上一个实例的数据——而且不报错，只是安静地串味。
+ * 测试就是这么把它逮住的：五个用例突然读到了别的用例的工作区。
+ */
+const caches = new WeakMap()
+
+async function safeRecords(query, { force = false } = {}) {
+  if (!query) return []
+  let entry = caches.get(query)
+  if (!entry) {
+    entry = { at: 0, records: null, inflight: null }
+    caches.set(query, entry)
+  }
+  if (!force && entry.records && Date.now() - entry.at < CACHE_TTL_MS) return entry.records
+  // 同一时刻来两个请求就共用一趟，别让它们各扫一遍盘。
+  if (entry.inflight) return entry.inflight
+  entry.inflight = (async () => {
+    try {
+      const records = (await query.listSessions()) ?? []
+      entry.at = Date.now()
+      entry.records = records
+      return records
+    } catch (err) {
+      // 读不到就当作没有：导航栏少几项，不该影响遥控本身。失败不进缓存，下次还会重试。
+      return []
+    } finally {
+      entry.inflight = null
+    }
+  })()
+  return entry.inflight
+}
+
+function toRecordMap(records) {
+  const map = new Map()
+  for (const r of records) {
+    if (r?.header?.id) map.set(r.header.id, r)
+  }
+  return map
+}
+
+/** 子 agent 的会话不进手机——用户遥控的是自己的会话，不是它派出去的小弟。 */
+function visible(record) {
+  return Boolean(record) && record.header.origin !== 'subagent'
+}
+
+/**
+ * 把标题从服务返回的形状里抠出来。
+ *
+ * 坑在这里：`readTitleSnapshots()` 给的**不是字符串**，而是一个「标题快照」对象
+ * `{ title, messageSeqs, source, eventSeq, updatedAt }`（见 dsh-session-title 的
+ * `titleSnapshotFromState`）。真正那句话在 `.title` 里。
+ * 而 `readTitle()` 反而直接返回字符串——同一件事的两个接口形状不一样。
+ *
+ * 不处理的话界面会显示 `[object Object]`（真机上就是这么发现的）。
+ * 两种形状都收，免得以后哪边改了又炸。
+ */
+function titleText(value) {
+  if (typeof value === 'string') return value
+  if (value && typeof value === 'object' && typeof value.title === 'string') return value.title
+  return ''
+}
+
+/**
+ * 工作区列表。只给「有会话可切」的那些，空工作区不占地方。
+ * 返回顺序就是桌面端的显示顺序。
+ */
+export async function listWorkspaces({ registry, query, runningIds, force }) {
+  const byId = toRecordMap(await safeRecords(query, { force }))
+  const out = []
+  for (const ws of safeList(registry)) {
+    const ids = (ws.sessionIds ?? []).filter((id) => visible(byId.get(id)))
+    if (!ids.length) continue
+    let running = 0
+    for (const id of ids) if (runningIds?.has(id)) running += 1
+    out.push({
+      id: ws.id,
+      // title 可能为空，退回到目录名——总比一个 UUID 强
+      title: (ws.title || '').trim() || basename(ws.path || '') || '未命名工作区',
+      path: ws.path || '',
+      count: ids.length,
+      running,
+    })
+  }
+  return out
+}
+
+/**
+ * 某个工作区下的会话，新的在前，最多 limit 条。
+ *
+ * 标题分两步拿：插件自己在事件流里见过的（内存里就有，免费）优先；
+ * 剩下的冷会话才去读日志。**只在展开一个工作区时才付这个代价**，所以有上限。
+ */
+export async function listSessionsOf({ registry, query, agents, knownTitles, workspaceId, limit = SESSIONS_PER_WORKSPACE, force }) {
+  const ws = safeList(registry).find((w) => w.id === workspaceId)
+  if (!ws) return null
+
+  const byId = toRecordMap(await safeRecords(query, { force }))
+  const rows = (ws.sessionIds ?? [])
+    .map((id) => byId.get(id))
+    .filter(visible)
+    .sort((a, b) => (b.header.createdAt ?? 0) - (a.header.createdAt ?? 0))
+    .slice(0, limit)
+
+  // 内存里已知的标题先用着，缺的再去读日志。
+  const titles = new Map()
+  const missing = []
+  for (const r of rows) {
+    const known = knownTitles?.get(r.header.id)
+    if (known) titles.set(r.header.id, known)
+    else missing.push(r.header.id)
+  }
+  if (missing.length && query?.readTitleSnapshots) {
+    try {
+      for (const item of await query.readTitleSnapshots(missing)) {
+        const title = item?.status === 'fulfilled' ? titleText(item.value?.title) : ''
+        if (title) titles.set(item.sessionId, title)
+      }
+    } catch (err) {
+      // 读不出来就没有标题，界面会退回用日期，不影响切换。
+    }
+  }
+
+  return {
+    workspaceId,
+    total: (ws.sessionIds ?? []).length,
+    truncated: (ws.sessionIds ?? []).length > rows.length,
+    sessions: rows.map((r) => {
+      const id = r.header.id
+      const status = agents?.get(id)?.status
+      return {
+        id,
+        title: titles.get(id) ?? '',
+        createdAt: r.header.createdAt ?? 0,
+        running: status === 'running',
+        live: Boolean(r.live),
+      }
+    }),
+  }
+}

package/lib/tunnel.js

@@ -0,0 +1,144 @@
+/**
+ * 起一条 cloudflared 快速隧道，把本机的手机服务暴露到一个公网网址。
+ *
+ * 「快速隧道」是 Cloudflare 提供的免账号模式：跑起来就给你一个
+ * `https://<随机词>.trycloudflare.com` 的地址，转发回本机。代价是**这个网址
+ * 每次重启都会换一个**，所以手机上的旧链接会失效，得重新扫一次二维码。
+ */
+import { spawn } from 'node:child_process'
+
+/**
+ * 从 cloudflared 的输出里挑出公网网址。
+ *
+ * 有个坑：输出里会**先**出现 `https://api.trycloudflare.com`——那是它向
+ * Cloudflare 注册时用的接口地址，不是给你的网址。不加排除就会把用户送到一个
+ * 打不开的地址上。所以用负向前瞻把 `api.` 开头的排掉。
+ *
+ * 这个坑不是我们自己踩出来的，是从 dsh-pocket（shaobeichen，GPL-2.0）的注释里知道的，
+ * 它记在自己的 issue #32。**知道一个坑和抄一段代码是两回事**——这个正则、这里的函数
+ * 划分、以及这段说明都是我们自己写的。README 的「致谢」一节写明了这层关系。
+ */
+export const QUICK_TUNNEL_URL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/i
+
+/**
+ * 公网隧道失败时，告诉用户「接下来做什么」。
+ *
+ * 2026-09-22 实测：本机代理的 **TUN 模式**（Clash 这类）会掐断 cloudflared 到 Cloudflare
+ * 边缘的连接——cloudflared 好好活着，却一条 ESTABLISHED 都没有；DNS 还被劫持成
+ * `198.18.x.x` 这种假地址（RFC 2544 保留段，真实世界不存在），走假地址访问隧道，
+ * Cloudflare 回 530（也就是用户看到的 Error 1033）。
+ *
+ * 这个坑 dsh-pocket 也踩过，它的报错文案里就写着「是否开着代理/VPN（Clash 等 TUN 模式
+ * 会掐断隧道连接）」。它没有解决，只是把它写进报错——因为**用户看到「连不上」的第一
+ * 反应是重试，而正确的动作往往是关代理**。所以这句必须写出来，不能省。
+ *
+ * 顺带指一条走得通的路：这个插件本来就有 Tailscale 那条，不必在 Cloudflare 上死磕。
+ *
+ * 放在这里（而不是 index.js 里）是为了能单测：文案本身就是这次的交付物，
+ * 少写一句「关代理」用户就会一直重试，值得钉住。
+ */
+export const TUNNEL_HINT = '如果电脑上开着代理或 VPN（Clash 这类），先关掉再试一次——它们的'
+  + '「TUN 模式」会把隧道连接掐断。关掉还不行，就说明这条网络走不通 Cloudflare，'
+  + '改用设置页里的 Tailscale 那条（出门在外它更稳）。'
+
+/**
+ * 从一段输出里挑出公网网址，没有就返回 null。
+ * 单独抽出来是为了能直接测——这段正则的坑（`api.trycloudflare.com` 要先出现）
+ * 值得用测试钉住，而不是靠真连一次 Cloudflare 去碰运气。
+ */
+export function parseTunnelUrl(text) {
+  return QUICK_TUNNEL_URL_RE.exec(String(text ?? ''))?.[0] ?? null
+}
+
+/** 累积输出的上限。网址最多几十字节，留 8KB 足够，免得日志越攒越多。 */
+const TAIL_LIMIT = 8000
+
+const START_TIMEOUT_MS = 30_000
+
+/**
+ * @param {object} opts
+ * @param {string} opts.binPath cloudflared 可执行文件
+ * @param {number} opts.port 本机手机服务的端口
+ * @returns {Promise<{url: string, stop: () => void, onExit: (cb: (code: number|null) => void) => () => void}>}
+ */
+export function startTunnel({ binPath, port, log }) {
+  // --no-autoupdate 必须放在子命令**之前**：cloudflared 2026.x 去掉了 `tunnel`
+  //   子命令层级的这个参数，全局位置仍然有效。
+  // --protocol http2 是必要的：默认走 QUIC（UDP 7844），国内网络和不少企业网把
+  //   UDP 封掉，表现是隧道报 error 1033 连不上；HTTP/2 走 TCP 443，基本都通。
+  // --edge-ip-version 4 同样是必要的，而且更隐蔽：隧道控制面 region1/region2.
+  //   v2.argotunnel.com 在不少网络里**只解析出 IPv6**，而那条路往往不通。实测
+  //   不加这个参数时，cloudflared 要么卡在向 api.trycloudflare.com 注册（POST
+  //   超时），要么拿到网址却连不上边缘（公网访问回 HTTP 530）；加上之后连接
+  //   立刻注册成功。走 IPv4 的代价是可以接受的——隧道两端都是 Cloudflare 的
+  //   任播地址，IPv4 覆盖没有短板。
+  const child = spawn(
+    binPath,
+    [
+      '--no-autoupdate',
+      'tunnel',
+      '--url', `http://127.0.0.1:${port}`,
+      '--protocol', 'http2',
+      '--edge-ip-version', '4',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+
+  const exitListeners = new Set()
+  const stop = () => {
+    try {
+      child.kill()
+    } catch {
+      // 已经退出了
+    }
+  }
+  const onExit = (cb) => {
+    exitListeners.add(cb)
+    return () => exitListeners.delete(cb)
+  }
+  child.on('exit', (code) => {
+    for (const cb of exitListeners) cb(code)
+  })
+
+  return new Promise((resolve, reject) => {
+    let settled = false
+    let tail = ''
+
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      stop()
+      reject(new Error(`等了 30 秒还没拿到公网网址。cloudflared 最后说的话：\n${tail.trim().slice(-500)}`))
+    }, START_TIMEOUT_MS)
+    timer.unref?.()
+
+    // 拿到网址之后仍然保持监听、只是不再处理——中途摘掉监听会让管道不再被消费，
+    // 64KB 缓冲填满后 cloudflared 会被卡住。
+    const onData = (chunk) => {
+      if (settled) return
+      // 要在**累积**的缓冲区里找，不能只看刚到这一块：网址有可能被拆成两次写出来。
+      tail = (tail + String(chunk)).slice(-TAIL_LIMIT)
+      const found = parseTunnelUrl(tail)
+      if (!found) return
+      settled = true
+      clearTimeout(timer)
+      log?.info?.(`公网地址：${found}`)
+      resolve({ url: found, stop, onExit })
+    }
+
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.on('error', (err) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(new Error(`cloudflared 起不来：${err?.message ?? err}`))
+    })
+    child.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(new Error(`cloudflared 提前退出了（退出码 ${code}）。它最后说的话：\n${tail.trim().slice(-500)}`))
+    })
+  })
+}