dsh-plugin-mobile-link 0.3.0 → 0.4.0

package/lib/router.js

@@ -12,13 +12,60 @@
 import {
   StreamTable, WaterfallDedupe, deviceFrameError, deviceIdOf, nonEmptyString, resultFrame,
 } from './dlp.js'
-import { FileInbox, isFileMethod } from './files.js'
+import { FileInbox, FILE_BEGIN, FILE_CHUNK, FILE_END, isFileMethod } from './files.js'
+import { FileFetcher, FSGET_CANCEL } from './files-out.js'
 import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 
+/**
+ * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
+ * 的 `agentControl`。转义成 `FileInbox` 的三件套，见 `handleFsPutBegin` 那段注释。
+ */
+export const FSPUT_BEGIN = 'fsPutBegin'
+export const FSPUT_CHUNK = 'fsPutChunk'
+export const FSPUT_END = 'fsPutEnd'
+
+/**
+ * 后台大文件下载的桥接帧（relay → 连接器），同一族的另一半：relay 终结
+ * `GET /files/down` 并慢慢读，这里驱动 host 的 `workspaceFiles/readBytes`
+ * 一片一片回。实现体在 `lib/files-out.js`。
+ */
+export const FSGET_BEGIN = 'fsGetBegin'
+
 export const EVENTS_ENDPOINT = '$events'
 export const EVENTS_RESULT = '$events/result'
 
+/**
+ * 手机不在时一直替它留 `$events`，直到设备被撤销或进程退出。
+ *
+ * 为什么需要：手机是唯一客户端时，它一断，DSH 那边就没人持有这条流了——
+ * 提问（waterfall）会随 Agent Context 释放被撤掉，用户回到手机再也看不到——
+ * 这正是留流的原因。留着流就等于"代手机值班"：这期间来的提问先攒着，手机回来补发。
+ *
+ * **没有时限**：这里曾经有一个 15 分钟的宽限期（`DEFAULT_EVENTS_GRACE_MS`），
+ * 到点撤流；2026-09-28 的 R-1 把它拆掉了——手机离线超过 15 分钟提问就永远丢了，
+ * 而那正是"值班"最该起作用的时候。唯一的出口是 `reason === 'revoked'`（见
+ * `detachDevice`），以及进程退出（`teardownAll`）。
+ *
+ * 代价是这段时间里 DSH 认为"设备还在"，会话的 Agent Context 不会因此释放；
+ * 也就是"挂着的提问所在会话的 Agent Context 长期不释放"。owner 已裁定这不是
+ * 风险（电脑一直运行），所以不加上限、也不为此写额外的清理机制。
+ */
+
+/** 离线期间最多替一台设备攒多少条 `$events` 项（只攒 waterfall/cancel）。 */
+export const DEFAULT_EVENTS_BACKLOG = 50
+
+/**
+ * 手机不在时要攒下来的 `$events` 项：只有"待回答的提问"和"提问作废"两种。
+ *
+ * 别的一律不攒——emit 类的都是"某事刚发生"的通知，几分钟后补发只会让 App
+ * 对着旧事件发通知（例如一条早就结束的 turn）。
+ */
+export function isBufferedEvent(value) {
+  if (!value || typeof value !== 'object') return false
+  return value.type === 'waterfall' || value.type === 'cancel'
+}
+
 export function messageOf(error) {
   return error instanceof Error ? error.message : String(error)
 }
@@ -34,8 +81,15 @@ export class DeviceRouter {
    * @param {(deviceId: string, frame: object) => boolean} options.send  deliver one frame to one device
    * @param {() => void} [options.onChange]    called whenever the status snapshot changes
    */
-  constructor({ dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1 } = {}) {
+  constructor({
+    dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
+    eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {},
+  } = {}) {
     this.dsh = dsh
+    this.eventsBacklog = eventsBacklog
+    // 「跑完了 / 待你回应」这类事件到了就报一声（见 `notifyFor`）。默认空函数，
+    // 测试与不关心提醒的调用方可以不管它。帧由 link.js 发（router 不发帧）。
+    this.notify = notify
     // Reported to the app so it can tell which wire revision it is talking to.
     this.protocolVersion = protocolVersion
     this.send = send
@@ -47,6 +101,13 @@ export class DeviceRouter {
     this.dedupe = new WaterfallDedupe({ now })
     this.lastError = undefined
     this.fileInbox = new FileInbox(logger)
+    // 下载桥（`fsGetBegin`）：它自己经 `this.dsh.rpc` 读 host，回复只带 bid。
+    // `send(undefined, frame)` 与 `fsPut*` 同路——relay 靠 bid 关联回 HTTP 请求。
+    this.fileFetcher = new FileFetcher({
+      send: (frame) => this.send(undefined, frame),
+      rpc: (method, args) => dsh.rpc(method, args),
+      logger,
+    })
     this.git = new GitBridge(logger)
   }
 
@@ -72,6 +133,18 @@ export class DeviceRouter {
       await this.detachDevice(deviceId, frame.reason)
       return
     }
+    // **Before the `deviceId` guard, not after it.** The download bridge family
+    // is addressed by `bid` alone — the relay is the one that terminates the
+    // HTTP request and it knows which device it is for; putting a `deviceId` on
+    // these frames would break the correlation the whole family rests on. So a
+    // cancel legitimately arrives with no `deviceId`, and the guard below would
+    // have dropped it silently: the connector would read the whole file for a
+    // reader that left. Found by probe (the run kept pumping past the cancel),
+    // which is why this is a test and not a comment.
+    if (frame.t === FSGET_CANCEL) {
+      this.handleFsGetCancel(frame)
+      return
+    }
     if (!deviceId) return
     const problem = deviceFrameError(frame)
     if (problem) {
@@ -91,16 +164,110 @@ export class DeviceRouter {
       case 'eventResult':
         await this.handleEventResult(deviceId, frame)
         return
+      case FSPUT_BEGIN:
+        this.handleFsPutBegin(deviceId, frame)
+        return
+      case FSPUT_CHUNK:
+        this.handleFsPutChunk(frame)
+        return
+      case FSPUT_END:
+        this.handleFsPutEnd(frame)
+        return
+      case FSGET_BEGIN:
+        this.handleFsGetBegin(frame)
+        return
       default:
         /* Unknown frame types are ignored by design (spec §3). */
         return
     }
   }
 
+  // ── background-transfer bridge (relay → connector) ──────────────────────
+  //
+  // 一族 agent 侧控制帧（`docs/relay-contract.json` 的 `agentControl`），由 relay 的
+  // `PUT /files/up` 驱动。它们**不跨到设备**——手机走的是普通 HTTPS，relay 终结它、
+  // 再把字节泵到这条 agent WSS 上，落盘仍然是连接器的活（中转不落盘）。
+  //
+  // 实现体复用 `FileInbox`：它的 begin/chunk/end 语义正好是这三帧要的。
+  // **上行回复只带 `bid`，不带 `deviceId`**——relay 靠 `bid` 关联回那个 HTTP 请求。
+
+  handleFsPutBegin(deviceId, frame) {
+    // `deviceId` 只用来在出错时记账；**回复一律不带 deviceId**——relay 是靠
+    // `bid` 把它对回那个 HTTP 请求的（见 `handleRelayFrame` 那段注释）。
+    void deviceId
+    try {
+      this.fileInbox.handle(FILE_BEGIN, {
+        transferId: frame.bid, sessionId: frame.sessionId, name: frame.name, bytes: frame.bytes,
+      })
+      this.send(undefined, { t: 'fsPutAck', bid: frame.bid, received: 0 })
+    } catch (error) {
+      this.sendFsError(frame.bid, error)
+    }
+  }
+
+  handleFsPutChunk(frame) {
+    // **不回 ack**：整条链是流水线，一片一个 RTT 会把吞吐毁掉（roof 见
+    // `02-design.md` §4.4 第 3 条）。出错用 `fsErr` 中断。
+    try {
+      this.fileInbox.handle(FILE_CHUNK, {
+        transferId: frame.bid, seq: frame.seq, data: frame.data,
+      })
+    } catch (error) {
+      this.sendFsError(frame.bid, error)
+    }
+  }
+
+  handleFsPutEnd(frame) {
+    try {
+      const done = this.fileInbox.handle(FILE_END, { transferId: frame.bid })
+      this.send(undefined, { t: 'fsPutDone', bid: frame.bid, path: done.path, bytes: done.bytes })
+    } catch (error) {
+      this.sendFsError(frame.bid, error)
+    }
+  }
+
+  /**
+   * 开一次下载。**不 await**：分片要在 relay 读响应体时陆续发出去，一个 await
+   * 会把这条 socket 上其它帧全挡住（与上传那条流水线的理由相同）。
+   */
+  handleFsGetBegin(frame) {
+    this.fileFetcher.start(frame)
+  }
+
+  /**
+   * relay 叫停一次下载读取（手机挂断 / 额度截断）。
+   *
+   * 只置 `cancelled`，**不回任何帧**：这不是一次请求，取消一个已经没人要的
+   * 传输也没有可报的错。`#drive` 在每次窗口返回后检查这个标志，所以最多再
+   * 多读一个窗口就停——不是立刻，但也不是读完整个文件。
+   */
+  handleFsGetCancel(frame) {
+    const bid = String(frame?.bid ?? '')
+    if (!bid) return
+    this.fileFetcher.cancel(bid)
+  }
+
+  /** One failure shape for the whole family; the relay turns it into an HTTP error. */
+  sendFsError(bid, error) {
+    this.logger.warn?.(`mobile-link: file bridge ${bid} failed: ${messageOf(error)}`)
+    this.send(undefined, { t: 'fsErr', bid, ...errorObject('file/rejected', messageOf(error)) })
+  }
+
   // ── device lifecycle ────────────────────────────────────────────────────
 
   async attachDevice(deviceId, info = {}) {
-    if (!nonEmptyString(deviceId) || this.devices.has(deviceId)) return
+    if (!nonEmptyString(deviceId)) return
+    const existing = this.devices.get(deviceId)
+    if (existing) {
+      // 回头客：手机又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
+      if (existing.offlineSince !== undefined) {
+        existing.offlineSince = undefined
+        this.logger.info?.(
+          `mobile-link: device ${deviceId} reattached with ${existing.eventsPending.size} unanswered question(s)`)
+        this.#changed()
+      }
+      return
+    }
     this.devices.set(deviceId, {
       deviceId,
       name: info?.name,
@@ -110,18 +277,65 @@ export class DeviceRouter {
       readyValue: undefined,
       eventsMuxId: undefined,
       dlpIds: new Set(),
+      // 手机不在时的"值班"状态：offlineSince 有值 = 这条流在替它留着；
+      // eventsPending 是**还没被回答**的提问（按 eventId 存）。
+      // 注意它不是一个"送一次就清空"的队列：送过也要留着，否则 App 再重启一次
+      // （或崩一次）这条提问就永远丢了——2026-09-22 验收时正是这么发现的。
+      offlineSince: undefined,
+      eventsPending: new Map(),
     })
     this.logger.info?.(`mobile-link: device ${deviceId} attached (${info?.name ?? 'unknown'})`)
     this.#changed()
     await this.ensureEventsStream(deviceId)
   }
 
+  /**
+   * 手机断了。
+   *
+   * `reason === 'revoked'`（中转发来的"这台设备被撤销了"）是**放下**：撤掉它全部的流、
+   * 删掉记录——不再有人会回来拿那些提问了，继续值班只是白占一条流。
+   *
+   * 别的 reason（socket closed、backpressure…）一律是"手机暂时不在"：普通流（文件、
+   * 会话流）立刻撤，`$events` 留着替它值班——**一直留**，没有时限（见 `$events`
+   * 那段的说明）。这也是「撤销即放下」是唯一出口的原因。
+   */
   async detachDevice(deviceId, reason) {
+    const record = this.devices.get(deviceId)
+    if (!record) return
+    if (reason === 'revoked') {
+      await this.#dropDevice(deviceId)
+      this.logger.info?.(`mobile-link: device ${deviceId} 已被撤销，放下（不再替它值班）`)
+      return
+    }
+    // 除了 `$events`，其它流（文件、会话流）立刻撤掉：它们没有"值班"的意义，
+    // 留着只会占资源。`$events` 留着，见上面那段说明。
+    const keep = []
+    for (const entry of this.streams.byDevice(deviceId)) {
+      if (entry.endpoint === EVENTS_ENDPOINT) {
+        keep.push(entry)
+        continue
+      }
+      this.streams.removeByMux(entry.muxId)
+      this.dsh.cancelStream(entry.muxId)
+    }
+    record.dlpIds.clear()
+    for (const entry of keep) record.dlpIds.add(entry.dlpId)
+
+    if (record.offlineSince === undefined) record.offlineSince = this.now()
+    this.logger.info?.(
+      `mobile-link: device ${deviceId} detached (${reason ?? 'closed'})；`
+      + '$events 流一直替它留着，直到设备被撤销或进程退出')
+    this.#changed()
+  }
+
+  /** 真的把这台设备放下：撤全部流、删记录。唯一调用点是撤销与进程收尾。 */
+  async #dropDevice(deviceId) {
     const record = this.devices.get(deviceId)
     if (!record) return
     for (const muxId of this.streams.removeDevice(deviceId)) this.dsh.cancelStream(muxId)
     this.devices.delete(deviceId)
-    this.logger.info?.(`mobile-link: device ${deviceId} detached (${reason ?? 'closed'})`)
+    this.logger.info?.(
+      `mobile-link: 放下设备 ${deviceId}（丢掉 ${record.eventsPending.size} 条没人回答的提问）`)
     this.#changed()
   }
 
@@ -253,6 +467,17 @@ export class DeviceRouter {
       if (record.readyValue !== undefined) {
         this.send(deviceId, { t: 'item', id: frame.id, value: record.readyValue })
       }
+      // 还没被回答的提问在这里补发：ready 已经发过，所以 App 拿得到 clientId，
+      // 补发的提问是可以被回答的。**送出去不清空**——App 可能又崩/又重启，
+      // 只要还没人回答，下次连上还得再给一遍（App 侧按 eventId 去重）。
+      if (record.eventsPending.size > 0) {
+        const pending = [...record.eventsPending.values()]
+        this.logger.info?.(
+          `mobile-link: replaying ${pending.length} unanswered question(s) to ${deviceId}`)
+        for (const value of pending) {
+          this.send(deviceId, { t: 'item', id: frame.id, value })
+        }
+      }
       return
     }
     const muxId = `s:${deviceId}:${frame.id}`
@@ -302,6 +527,8 @@ export class DeviceRouter {
       })
       return
     }
+    // 答过了就不再是"待答"：删掉它，免得下次重连又把已经回答过的问题推给 App。
+    record.eventsPending.delete(eventId)
     // The clientId is always the one from *this device's* $events ready frame
     // (spec §4.1.5); any clientId the device echoed is ignored on purpose.
     if (!this.dedupe.claim(eventId)) return
@@ -339,6 +566,31 @@ export class DeviceRouter {
   forwardEvent(deviceId, value) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 只有"待回答的提问"值得留：别的都是"某事刚发生"的通知，补发只会让 App
+    // 对着几分钟前的事件发通知（例如一条早就结束的 turn）。
+    // 待答表：不管手机在不在都记下来，直到**有人回答**或 host 作废它。
+    // 只记在线时的转发是不够的——App 收下提问后崩一次/重启一次，那条提问就再也没人
+    // 记得了（host 认为已经投给这条流了，不会重发）。连接器记着，重连时再给一遍。
+    if (nonEmptyString(value?.eventId)) {
+      if (value.type === 'cancel') record.eventsPending.delete(value.eventId)
+      else if (value.type === 'waterfall') {
+        record.eventsPending.set(value.eventId, value)
+        if (record.eventsPending.size > this.eventsBacklog) {
+          // 超上限时丢最老的（Map 保持插入顺序）。
+          const oldest = record.eventsPending.keys().next().value
+          record.eventsPending.delete(oldest)
+        }
+      }
+    }
+    // 「报一声」与「要不要攒」是两件事：攒只对 waterfall/cancel，报的是"跑完了"与
+    // "待你回应"两类。这里放在离线早退**之前**，所以在不在线都会报——
+    // 手机在线时它自己会弹本地通知，这条 notify 到了中转会被判"在线不推"（不然重复）。
+    this.notifyFor(value)
+    if (record.offlineSince !== undefined && isBufferedEvent(value)) {
+      this.logger.debug?.(
+        `mobile-link: kept ${value.type} ${value.event ?? value.eventId ?? ''} for offline ${deviceId}`)
+      return
+    }
     if (value && value.type === 'ready' && nonEmptyString(value.clientId)) {
       record.clientId = value.clientId
       record.readyValue = value
@@ -350,6 +602,36 @@ export class DeviceRouter {
     if (record.dlpIds.size === 0) this.send(deviceId, { t: 'event', value })
   }
 
+  /**
+   * 要不要为这条 `$events` 项报一声（就是「提醒手机」）。
+   *
+   * 只有两类，判据都是现成的：
+   *
+   * - **跑完了**：`emit: api-session/status(sid, false)`。只能从这条 `emit` 认——
+   *   `turn/end` 不在 `$events` 的转发白名单里（`docs/DSH-PROTOCOL.md:3141-3165`；
+   *   `turn/end` 在 `:3229`，那是 `session/follow` 的事件），在这条流上永远看不到。
+   * - **待你回应**：两种 `waterfall` 都算——`user-questions/request`（`:3164`）与
+   *   `approval/request`（`:3145`），两者都让 host 停在那儿等人。App 侧本来就两种都认
+   *   （`Support/HostEventHub.swift:191-198`）。
+   *
+   * `api-session/error`（`:3150`）**有意不推**：它不一定是"跑完了"（也可能是一轮中途
+   * 报错后继续），拿它当"跑完了"会发出一堆噪音提醒。这是决定，不是漏做。
+   *
+   * 不做去抖、不做队列、不做重试：一轮才一条，发失败（中转断了）就丢。`turnEnd` 丢一条
+   * 不值得为它做重试；`attention` 丢不了，它同时被记账，手机回来会补发。
+   */
+  notifyFor(value) {
+    if (!value || typeof value !== 'object') return
+    if (value.type === 'emit' && value.event === 'api-session/status' && value.args?.[1] === false) {
+      const sid = String(value.args[0] ?? '')
+      if (sid) this.notify({ kind: 'turnEnd', sid })
+      return
+    }
+    if (value.type === 'waterfall') {
+      this.notify({ kind: 'attention', sid: value.agentId, eid: value.eventId })
+    }
+  }
+
   onStreamError(muxId, error) {
     const entry = this.streams.entryOfMux(muxId)
     if (!entry) return
@@ -411,6 +693,8 @@ export class DeviceRouter {
       // Which build that phone reported on its last handshake.
       client: record.client ?? null,
       connectedAt: record.connectedAt,
+      offlineSince: record.offlineSince ?? null,
+      unansweredEvents: record.eventsPending.size,
       eventsReady: Boolean(record.clientId),
       openStreams: record.dlpIds.size,
     }))

package/lib/routes.js

@@ -5,7 +5,7 @@
  *   POST /mobile-link/pair-code  mint a pairing code (and its QR payload)
  *   GET  /mobile-link/qr         mint a pairing code and render it as a QR SVG
  *
- * All sit behind DSH's own request fence, exactly like dsh-plugin-desktop-shell:
+ * All sit behind DSH's own request fence, like every other plugin route:
  * `ctx.get('connection')?.requestRejection?.(req)` performs the Host/Origin check
  * and browser authentication. `/status` stays readable when the fence service is
  * missing (it is diagnostic); the other two mint a credential, so they fail

package/lib/state.js

@@ -45,23 +45,14 @@ export function defaultStatePath() {
   return join(dshHome(), 'mobile-link', 'agent.json')
 }
 
-export function defaultEndpointFile() {
-  return join(dshHome(), 'desktop-shell', 'endpoint.json')
-}
-
 /**
- * The desktop shell's log, which is the *second* place the live endpoint can be
- * read from.
+ * 连接器**自己写出**的交接文件：给跑在宿主进程之外的脚本用（它们没有进程内上下文，
+ * 拿不到注入的服务）。消费者与格式见 `contracts/out-of-process-handoff.md`。
  *
- * The shell writes `endpoint.json` as a handoff, but it also removes it again
- * (observed after the shell quit and re-attached to an already running `dsh
- * web`), and a machine whose host was started as a bare `dsh web --port 0` only
- * ever sees the URL printed into this log. Both spellings appear here, so the
- * log is a usable last resort — without it the connector sits at the default
- * port with no launch token and every phone request fails.
+ * 注意：这不是连接器自己的发现来源——发现走宿主进程内的注入（见 `dsh-client.js`）。
  */
-export function defaultShellLogFile() {
-  return join(dshHome(), 'desktop-shell', 'dsh-shell.log')
+export function defaultHandoffFile() {
+  return join(dshHome(), 'mobile-link', 'endpoint.json')
 }
 
 /** @returns {Promise<Record<string, unknown> | undefined>} */

package/lib/status.js

@@ -0,0 +1,101 @@
+/**
+ * `GET /mobile-link/status` 的快照。
+ *
+ * 单独成文件的目的：这份载荷是**对外契约**（`contracts/status-endpoint.md` 规定了
+ * "只增不改"），把它和传输/生命周期代码分开，改动时更容易看出"是不是又动了老字段"。
+ * 函数只读 agent 的字段，不持有状态，因此可以直接被单测调用。
+ */
+
+import { SERVER_CAPABILITIES, SERVER_VERSION } from './hello.js'
+
+const PROTOCOL_VERSION = 1
+
+/**
+ * 失败分类 → 用户可读的一句话 + 文档锚点（FR-012）。
+ *
+ * 锚点标题与 `docs/ONBOARDING.md` 里的小节标题**逐字一致**，这样"锚点存在"可以机械核对。
+ */
+export const DSH_HINTS = {
+  config: { hint: '你手工配置的本机地址不对或已失效', docAnchor: '手工指定本机地址' },
+  'host-service': { hint: '当前宿主没有把本机访问方式交给插件（多为插件没装进正在运行的宿主）', docAnchor: '装在哪里：档案与插件入口' },
+  DSH_WEB_URL: { hint: '环境变量里的本机地址已过期', docAnchor: '手工指定本机地址' },
+  unreachable: { hint: '本机 DSH 不可达；请确认宿主正在运行', docAnchor: '排查：连不上时看这里' },
+}
+
+/**
+ * 宿主形态 → 用户可读的一句话 + 文档锚点（FR-012：分类必须可行动，不能只给分类名）。
+ *
+ * 锚点标题与 `docs/ONBOARDING.md` 的小节标题逐字一致，`test/status.test.js` 会核对。
+ */
+export const HOST_HINTS = {
+  desktop: { hint: '你正在用官方桌面版（连接器已装进它的档案）', docAnchor: '安装：官方桌面版' },
+  web: { hint: '你正在用命令行 web 版', docAnchor: '安装：命令行 web 版' },
+  unknown: { hint: '无法识别当前宿主；若连不上，请按"排查"一节处理', docAnchor: '排查：连不上时看这里' },
+}
+
+/** 本机 DSH 侧的诊断块（老字段一个不少，新字段只增）。 */
+function dshBlock(agent) {
+  const errorKind = agent.dshError ? (agent.dsh?.errorKind ?? 'unreachable') : null
+  const entry = errorKind ? DSH_HINTS[errorKind] : undefined
+  return {
+    endpoint: agent.dsh?.endpoint?.base ?? null,
+    source: agent.dsh?.endpoint?.source ?? null,
+    port: agent.dsh?.endpoint?.port ?? null,
+    authenticated: Boolean(agent.dsh?.cookie),
+    muxUp: Boolean(agent.dsh?.muxReady),
+    error: agent.dshError ?? null,
+    // 新增（只增不改）：失败分类 + 用户可读的一句话 + 文档锚点。
+    errorKind,
+    hint: entry?.hint ?? null,
+    docAnchor: entry?.docAnchor ?? null,
+  }
+}
+
+/**
+ * @param {import('./link.js').MobileLinkAgent} agent
+ * @returns {Record<string, unknown>} 可直接序列化给 `/status` 的对象
+ */
+export function statusSnapshot(agent) {
+  const hostEntry = HOST_HINTS[agent.hostForm] ?? HOST_HINTS.unknown
+  return {
+    ok: true,
+    enabled: agent.enabled !== false,
+    // 新增（只增不改）：宿主形态 + 它对应的一句话与文档锚点，
+    // 决定用户该按哪条说明安装/排障（FR-012）。
+    host: agent.hostForm,
+    hostHint: hostEntry.hint,
+    hostDocAnchor: hostEntry.docAnchor,
+    protocolVersion: PROTOCOL_VERSION,
+    // Same facts as `_link/hello`, which is the channel the app actually uses:
+    // this route only exists on the direct path.
+    serverVersion: SERVER_VERSION,
+    capabilities: SERVER_CAPABILITIES,
+    enroll: {
+      // A phone (or the user's browser) can read this to find out that the
+      // computer half is installed but not yet registered, and what to run.
+      registered: !agent.needsEnroll,
+      needsEnroll: agent.needsEnroll,
+      stateFile: agent.identity?.stateFile ?? agent.config.stateFile ?? null,
+      relayUrl: agent.config.relayUrl ?? null,
+      command: agent.needsEnroll ? agent.enrollHint() : null,
+      hint: agent.needsEnroll
+        ? '这台电脑还没有登记到中转。请带上邀请码运行一次登记命令，然后重启 DSH。'
+        : null,
+    },
+    state: agent.state,
+    connected: agent.state === 'connected',
+    relayUrl: agent.identity?.relayUrl ?? agent.config.relayUrl ?? null,
+    agentId: agent.identity?.agentId ?? agent.config.agentId ?? null,
+    agentName: agent.identity?.agentName ?? null,
+    stateFile: agent.identity?.stateFile ?? agent.config.stateFile ?? null,
+    dsh: dshBlock(agent),
+    devices: agent.router.snapshot(),
+    deviceCount: agent.devices.size,
+    openStreams: agent.streams.size,
+    pendingWaterfalls: agent.dedupe.size,
+    lastError: agent.failure ?? null,
+    startedAt: agent.startedAt ?? null,
+    connectedAt: agent.connectedAt ?? null,
+    reconnectAttempts: agent.reconnectAttempts,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Put your PC's DeepSeek Harness in your pocket: dials a relay over WSS so the native iOS client reaches this machine even without a public IP.",
   "keywords": [
     "dsh",