dsh-plugin-mobile-link 0.6.6 → 0.8.0

package/lib/router.js

@@ -18,6 +18,7 @@ import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 import { isHistoryMethod } from './history.js'
 import { trimRecordsForWire } from './history/records.js'
+import { isJobsMethod } from './jobs-roster.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -26,6 +27,16 @@ import { trimRecordsForWire } from './history/records.js'
 export const FSPUT_BEGIN = 'fsPutBegin'
 export const FSPUT_CHUNK = 'fsPutChunk'
 export const FSPUT_END = 'fsPutEnd'
+/**
+ * relay 叫停一次后台上传（占位型前向兼容）。
+ *
+ * 本仓库两个中转**目前都不发这一帧**：手机掐掉 `PUT /files/up` 时，它们在
+ * `finally` 里只摘掉本地的桥接，既不发取消帧、也不断开 agent 的 WebSocket。
+ * 因此真正兜住句柄的是 `FileInbox` 的空闲清扫与"重传接管暂存路径"；这一帧
+ * 让将来的/第三方中转能提前释放。按 bid 寻址，可以不带 `deviceId`
+ * （与 `fsGetCancel` 同口径，未知 bid 是空操作）。
+ */
+export const FSPUT_CANCEL = 'fsPutCancel'
 
 /**
  * 后台大文件下载的桥接帧（relay → 连接器），同一族的另一半：relay 终结
@@ -96,13 +107,16 @@ export function trimHistoryPageForWire(method, result) {
 }
 
 import { DeviceTimeline } from './diagnostics.js'
-import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest } from './session-digest.js'
+import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest, digestDelta } from './session-digest.js'
+import { DIR_LISTING_METHOD, dirListing } from './dir-listing.js'
 
 /** 慢请求阈值默认值（毫秒）；0 = 关闭逐条慢请求记录。 */
 export const DEFAULT_SLOW_REQUEST_MS = 2000
 
 /** App 把自己那份阶段记录推上来的方法（契约 connector-diagnostics-method.md）。 */
 export const DIAGNOSTICS_METHOD = '_link/diagnostics'
+/** 手机把运行日志推上来的方法；落盘在 `logs.js`，与 journal 分开。 */
+export const LOGS_METHOD = '_link/logs'
 /** 单批上限：超过就截断并如实报 `accepted`，剩下的由 App 下次再推（水位不推进）。 */
 export const DIAGNOSTICS_BATCH_BYTES = 32 * 1024
 /** 单条事件里字符串字段的保留长度。 */
@@ -142,9 +156,11 @@ export class DeviceRouter {
   constructor({
     dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
     eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {}, onEvent = () => {},
-    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true,
+    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true, logs = null,
   } = {}) {
     this.dsh = dsh
+    /** 设备日志落盘（见 logs.js）；null = 不接日志（老配置或单测）。 */
+    this.logs = logs
     this.eventsBacklog = eventsBacklog
     this.slowRequestMs = Number(slowRequestMs) || 0
     this.diagnosticsEnabled = diagnostics !== false
@@ -185,6 +201,21 @@ export class DeviceRouter {
     // 历史窗口/检索（spec 007）：由 index.js 注入宿主 `sessionQuery` 后交给它。
     // 没绑上就回 `link/unsupported`，手机端退回 `session/page`。
     this.history = undefined
+    // 活动名单与 `link/jobs` 推帧（spec 018）。订阅与去抖都在 roster 里，router 只负责
+    // 转交设备生命周期与把帧广播出去。
+    this.jobsRoster = undefined
+  }
+
+  /**
+   * 挂上活动名单（spec 018）。
+   *
+   * 注入可能晚于第一台设备连接（`ctx.inject` 的时序），所以这里要对**已经挂着**的
+   * 设备补报一遍：只在 attach 时通知的话，这台连接会一直到下一次 attach 才开始推帧。
+   */
+  bindJobsRoster(roster) {
+    this.jobsRoster = roster
+    if (roster === undefined) return
+    for (const deviceId of this.devices.keys()) roster.addDevice(deviceId)
   }
 
   #changed() {
@@ -221,6 +252,11 @@ export class DeviceRouter {
       this.handleFsGetCancel(frame)
       return
     }
+    // 上传的取消帧同样是 bid 寻址，可能不带 `deviceId`；放在守卫之前，理由同上。
+    if (frame.t === FSPUT_CANCEL) {
+      this.handleFsPutCancel(frame)
+      return
+    }
     if (!deviceId) return
     const problem = deviceFrameError(frame)
     if (problem) {
@@ -305,6 +341,17 @@ export class DeviceRouter {
     }
   }
 
+  /**
+   * relay 叫停一次上传：立刻关句柄、删 `.part`。
+   *
+   * 不回帧：取消本身不是一次请求，也没有可报的错（与 `handleFsGetCancel` 同）。
+   */
+  handleFsPutCancel(frame) {
+    const bid = String(frame?.bid ?? '')
+    if (!bid) return
+    this.fileInbox.cancel(bid)
+  }
+
   /**
    * 开一次下载。**不 await**：分片要在 relay 读响应体时陆续发出去，一个 await
    * 会把这条 socket 上其它帧全挡住（与上传那条流水线的理由相同）。
@@ -404,6 +451,22 @@ export class DeviceRouter {
     return { ok: true, value: { accepted, lastSeq } }
   }
 
+  /**
+   * 收下手机推来的日志行。
+   *
+   * 与 `acceptDiagnostics` 的区别：这里不产生任何生命周期事件（日志是数据，不是状态），
+   * 也不做批量解释；`logs.js` 只负责按天落盘与 7 天清理。失败一律当无事：
+   * 手机侧把未确认的条目留在自己的环里，下次再推。
+   */
+  acceptLogs(deviceId, args = {}) {
+    if (!this.logs) {
+      return { ok: false, error: errorObject('logs/disabled', 'log intake is disabled on this connector') }
+    }
+    const entries = Array.isArray(args.entries) ? args.entries : []
+    const result = this.logs.append(deviceId, entries, { full: args.full === true })
+    return { ok: true, value: result }
+  }
+
   /** 起一次新的接入计时（回头客也重起：那确实是一次新连接）。 */
   #startTimeline(deviceId) {
     this.timelines.get(deviceId)?.finish()
@@ -428,6 +491,9 @@ export class DeviceRouter {
   async attachDevice(deviceId, info = {}) {
     if (!nonEmptyString(deviceId)) return
     this.#startTimeline(deviceId)
+    // 活动名单（018）：第一台设备连上才订阅宿主任务事件；回头客这里也要补一次
+    // （detach 时它从名单里撤下过）。
+    this.jobsRoster?.addDevice(deviceId)
     const existing = this.devices.get(deviceId)
     if (existing) {
       // 回头客：手机又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
@@ -484,6 +550,9 @@ export class DeviceRouter {
     this.#finishTimeline(deviceId)
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 活动名单（018）：断了就不再往它那儿推任务帧（离线补发旧任务状态没有意义），
+    // 最后一台设备离开时 roster 自己会释放宿主订阅。
+    this.jobsRoster?.removeDevice(deviceId)
     if (reason === 'revoked') {
       await this.#dropDevice(deviceId)
       this.onEvent('device.revoked', { deviceId })
@@ -516,6 +585,7 @@ export class DeviceRouter {
   async #dropDevice(deviceId) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    this.jobsRoster?.removeDevice(deviceId)
     for (const muxId of this.streams.removeDevice(deviceId)) this.dsh.cancelStream(muxId)
     this.devices.delete(deviceId)
     this.logger.info?.(
@@ -555,6 +625,12 @@ export class DeviceRouter {
     // 不该有残留：上面的循环已经逐个收过；这里兜底，防止 attach 之后没进 devices 的路径留下脏项。
     this.timelines.clear()
     this._sentBytes.clear()
+    // 链路断了：在传的上传与下载都不可能再完成。上传要关句柄、删 `.part`；
+    // 下载要停掉还没读完的窗口。
+    this.fileInbox.clear()
+    this.fileFetcher.clear()
+    // 活动名单（018）：设备都没了，宿主任务订阅与排队的帧一起放掉。
+    this.jobsRoster?.releaseAll()
     return muxIds
   }
 
@@ -575,19 +651,67 @@ export class DeviceRouter {
         this.lastError = messageOf(error)
         this.#changed()
       }
-      const payload = result?.ok === true
-        ? { ok: true, value: encodeDigest(digestSessionList(result), args.encoding) }
-        : result
+      let payload = result
+      if (result?.ok === true) {
+        const trimmed = digestSessionList(result)
+        const items = Array.isArray(trimmed?.items) ? trimmed.items : []
+        const since = typeof args.since === 'string' ? args.since : null
+        this.digestCursors ??= new Map()
+        const previous = since ? this.digestCursors.get(deviceId) : null
+        // 版本对得上才认那份指纹表；对不上（首次、连接器重启、设备被清理）就当没有历史。
+        // 能不能当增量发由 digestDelta 决定：它持有指纹，也只有它能判断身份是否可识别。
+        const usable = previous && previous.version === since ? previous : null
+        const delta = digestDelta(usable ? usable.fingerprints : null, items)
+        this.digestCursors.set(deviceId, { version: delta.version, fingerprints: delta.fingerprints })
+        if (this.digestCursors.size > 32) {
+          const oldest = this.digestCursors.keys().next().value
+          this.digestCursors.delete(oldest)
+        }
+        const value = {
+          ...trimmed,
+          items: delta.changed,
+          removed: delta.removed,
+          version: delta.version,
+          full: delta.full,
+        }
+        payload = { ok: true, value: encodeDigest(value, args.encoding) }
+      }
       this.send(deviceId, resultFrame(frame.id, payload, deviceId))
       return
     }
 
+    // 目录清单的本机增强（设计 20261024）：连接器读宿主的 `workspaceFiles/list`，
+    // 在电脑本机对每个条目 `fs.stat` 补一个 `mtimeMs`——宿主没有时间字段，而
+    // `workspaceFiles/stat` 的 `version` 是 opaque token（推不出时间）。
+    // 与 sessionDigest 同款：清单的内容仍是宿主的，连接器只加字段；任何一步出问题
+    // 都退回未增强的原始清单（装饰永不弄坏清单）。
+    if (frame.method === DIR_LISTING_METHOD) {
+      let result
+      try {
+        // `dirListing` 认宿主信封本身（`{ ok, value: { entries } }`）并原样回同形状的值：
+        // 宿主报错时**信封逐字透传**，`resultFrame` 照常把它翻成 `ok:false` + 原错误码。
+        // 这里不能再包一层 `{ ok: true, value }`——那会把宿主的失败塞进 `value` 里，
+        // 帧上反而成了 `ok:true`（手机就会把"目录不存在"读成"空目录"）。
+        result = await dirListing({ dsh: this.dsh, args: frame.args ?? {}, logger: this.logger })
+      } catch (error) {
+        result = { ok: false, error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}) }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     if (frame.method === DIAGNOSTICS_METHOD) {
       const result = this.acceptDiagnostics(deviceId, frame.args ?? {})
       this.send(deviceId, resultFrame(frame.id, result, deviceId))
       return
     }
 
+    if (frame.method === LOGS_METHOD) {
+      const result = this.acceptLogs(deviceId, frame.args ?? {})
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     // Files the phone sends are answered here rather than forwarded: the Host
     // has no upload endpoint, and carrying them on the existing unary frame
     // means neither the relay nor the protocol has to change.
@@ -667,6 +791,22 @@ export class DeviceRouter {
       return
     }
 
+    // 活动名单（spec 018）与 history 同一条短路：连接器自己回答，不转发宿主。
+    // 没挂上宿主 `ctx.jobs` 时回 `link/unsupported`——**不**回空名单，否则手机
+    // 会把"这台连接器不支持"显示成"没有任务在跑"。
+    if (isJobsMethod(frame.method)) {
+      let result
+      try {
+        result = this.jobsRoster === undefined
+          ? { ok: false, error: errorObject('link/unsupported', 'job roster is unavailable on this connector') }
+          : await this.jobsRoster.handle(frame.args ?? {})
+      } catch (error) {
+        result = { ok: false, error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}) }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     let result
     try {
       result = await this.dsh.rpc(frame.method, frame.args ?? {})
@@ -831,12 +971,38 @@ export class DeviceRouter {
       record.readyValue = value
       this.#changed()
     }
+    this.#sendEventItem(deviceId, record, value)
+  }
+
+  /**
+   * 向一台设备投递一条 `$events` 形态的项（item，或未开流时的 event 帧）。
+   *
+   * 抽出来是为了让连接器自造的帧（`link/jobs`，见 `publishEvent`）与宿主事件走**同一段**
+   * 投递口径，帧语义不变：开了 `$events` 的按 dlpId 走 item，没开的按 event 广播。
+   */
+  #sendEventItem(deviceId, record, value) {
     for (const dlpId of record.dlpIds) this.send(deviceId, { t: 'item', id: dlpId, value })
     // Spec §4.1.5: every $events item is broadcast as an `event` frame until the
     // device opens the stream explicitly, so nothing is delivered twice.
     if (record.dlpIds.size === 0) this.send(deviceId, { t: 'event', value })
   }
 
+  /**
+   * 把一条连接器自造的项广播给**每台在线设备**（活动名单的 `link/jobs`，spec 018）。
+   *
+   * 与 `forwardEvent` 的区别是来源：那条项来自某台设备自己的 `$events` 流，只回给它；
+   * 这条是宿主任务事件的产物，没有归属设备，所以每台在线设备各收一份。
+   *
+   * **离线设备不推**：`$events` 还替它留着（见 `detachDevice`），但旧任务状态没有补发
+   * 意义——重连后手机重新问一次 `_link/jobRoster` 即可（契约 §3）。
+   */
+  publishEvent(value) {
+    for (const record of this.devices.values()) {
+      if (record.offlineSince !== undefined) continue
+      this.#sendEventItem(record.deviceId, record, value)
+    }
+  }
+
   /**
    * 要不要为这条 `$events` 项报一声（就是「提醒手机」）。
    *

package/lib/routes.js

@@ -86,6 +86,31 @@ function ttlFrom(value, fallbackMs) {
     : fallbackMs
 }
 
+/** Map an enrollment error code onto the HTTP status the panel sees. */
+export function enrollStatus(code) {
+  switch (code) {
+    case 'enroll/already-registered':
+    case 'enroll/disabled':
+      return 409
+    case 'enroll/timeout':
+      return 504
+    case 'enroll/rate-limited':
+      return 429
+    case 'enroll/state-write':
+    case 'enroll/internal':
+      return 500
+    case 'enroll/bad-request':
+    case 'enroll/invalid-relay':
+    case 'enroll/placeholder-relay':
+    case 'enroll/unknown':
+    case 'enroll/used':
+    case 'enroll/expired':
+      return 400
+    default:
+      return 502
+  }
+}
+
 /**
  * Register the routes.
  * @returns {Array<() => void>} disposers (already wrapped by the caller in ctx.effect).
@@ -93,6 +118,9 @@ function ttlFrom(value, fallbackMs) {
 export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, history }) {
   const guard = makeGuard(ctx, logger)
   const STATUS_ROUTE = '/mobile-link/status'
+  const ENROLL_ROUTE = '/mobile-link/enroll'
+  const REVOKE_ROUTE = '/mobile-link/devices/revoke'
+  const DEVICES_ROUTE = '/mobile-link/devices'
   const PAIR_ROUTE = '/mobile-link/pair-code'
   const REGENERATE_ROUTE = '/mobile-link/pair-code/regenerate'
   const disposers = []
@@ -116,6 +144,125 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
     },
   }))
 
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: ENROLL_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('allow', 'POST')
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      if (body === undefined) {
+        sendJson(res, 400, { ok: false, code: 'enroll/bad-request', message: 'invalid JSON body' })
+        return
+      }
+      const relayUrl = typeof body.relayUrl === 'string' ? body.relayUrl.trim() : ''
+      const inviteCode = typeof body.inviteCode === 'string' ? body.inviteCode.trim() : ''
+      const agentName = typeof body.agentName === 'string' ? body.agentName.trim() : ''
+      if (!relayUrl) {
+        sendJson(res, 400, {
+          ok: false,
+          code: 'enroll/bad-request',
+          message: 'relayUrl is required',
+        })
+        return
+      }
+      try {
+        // 开放登记：不需要邀请码；旧调用方仍可带（历史兼容）。
+        const settled = await agent.enroll({
+          inviteCode: inviteCode || undefined,
+          relayUrl,
+          agentName: agentName || undefined,
+        })
+        logger.info?.(`mobile-link: panel enrollment succeeded for ${settled.agentId}`)
+        // Never return `agentSecret`: the browser has no use for it, and one
+        // XSS in the panel would otherwise hand over the machine's credential.
+        sendJson(res, 200, {
+          ok: true,
+          agentId: settled.agentId,
+          agentName: settled.agentName,
+          relayUrl: settled.relayUrl,
+        })
+      } catch (error) {
+        // Read the code off the error rather than using `instanceof`: a hot
+        // reload can leave the route and the link on different module
+        // generations, and an identity check would then downgrade a precise
+        // "already registered" into a generic 500.
+        const code = typeof error?.code === 'string' && error.code.startsWith('enroll/')
+          ? error.code
+          : 'enroll/internal'
+        const status = enrollStatus(code)
+        if (code === 'enroll/internal') {
+          logger.warn?.(`mobile-link: panel enrollment failed: ${String(error?.message ?? error)}`)
+        }
+        sendJson(res, status, { ok: false, code, message: String(error?.message ?? error) })
+      }
+    },
+  }))
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: DEVICES_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'GET') {
+        res.statusCode = 405
+        res.setHeader('allow', 'GET')
+        res.end()
+        return
+      }
+      try {
+        const result = await agent.listPairedDevices()
+        sendJson(res, 200, { ok: true, ...result })
+      } catch (error) {
+        sendJson(res, 502, {
+          ok: false,
+          code: 'devices/list-failed',
+          message: String(error?.message ?? error),
+        })
+      }
+    },
+  }))
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: REVOKE_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('allow', 'POST')
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      if (body === undefined) {
+        sendJson(res, 400, { ok: false, code: 'request/bad-request', message: 'invalid JSON body' })
+        return
+      }
+      const deviceId = typeof body.deviceId === 'string' ? body.deviceId.trim() : ''
+      if (!deviceId) {
+        sendJson(res, 400, { ok: false, code: 'request/device-id', message: 'deviceId is required' })
+        return
+      }
+      try {
+        const result = await agent.revokeDevice(deviceId)
+        logger.info?.(`mobile-link: revoked device ${result.deviceId}`)
+        sendJson(res, 200, { ok: true, deviceId: result.deviceId })
+      } catch (error) {
+        sendJson(res, 502, {
+          ok: false,
+          code: 'devices/revoke-failed',
+          message: String(error?.message ?? error),
+        })
+      }
+    },
+  }))
+
   disposers.push(ctx.webServer.register({
     kind: 'exact',
     path: PAIR_ROUTE,

package/lib/session-digest.js

@@ -12,25 +12,33 @@
  */
 
 import { deflateRawSync } from 'node:zlib'
+import { createHash } from 'node:crypto'
 
 /** 方法名（设备发起，中转不校验方法名，所以不需要中转改动）。 */
 export const SESSION_DIGEST_METHOD = '_link/sessionDigest'
 
 /** 会话项里剔掉的字段：零读取点（`agentAvailable` 1.8%）。 */
-export const DROPPED_ITEM_KEYS = Object.freeze(['agentAvailable'])
+// `agentAvailable` 曾是"零读取点"，018 之后列表行要用它区分"会话是否还有活实例"
+// （`ActivityStore` 与 `session.activity.*`），因此**不再剔除**。留空数组是为了保住
+// 「剔除机制 + 逐字节稳定」这两条不变式；将来要剔字段仍从这里加。
+export const DROPPED_ITEM_KEYS = Object.freeze([])
 
 /**
- * 投影键里剔掉的字段（合计 56.7%）。
+ * 投影键里剔掉的字段（合计约 55%）。
  *
  * 每一条都能在 App/DSHKit 里复查"零读取点"：
  * `turnOutline` 33.4%（每轮 prompt/response 原文）、`imageLimits` 6.2%（上传限制）、
  * `sessionStats` 4.2%、`todos` 2.6%、`subagentCatalog` 2.6%、`contextBreakdown` 2.5%、
  * `sessionListMetadata` 1.9%（唯一被读的 `blank` 在顶层已有同名字段）、
- * `subagentTiming` 1.5%、`agentPreset` 0.8%（`SessionCreateRequest.agentPreset` 是请求字段）。
+ * `agentPreset` 0.8%（`SessionCreateRequest.agentPreset` 是请求字段）。
+ *
+ * **2026-10-20 起不再剔除 `subagentTiming`**（原 1.5%）：018 的活动可见性靠它判断
+ * "某子会话当前是否在跑"与已跑时长；剔除后手机永远看不到「N 智能体」。
+ * 同理 `agentAvailable` 也不再剔除。代价是摘要通道多约 1.5% 字节，换来功能可用。
  */
 export const DROPPED_PROJECTION_KEYS = Object.freeze([
   'turnOutline', 'imageLimits', 'sessionStats', 'todos', 'subagentCatalog',
-  'contextBreakdown', 'sessionListMetadata', 'subagentTiming', 'agentPreset',
+  'contextBreakdown', 'sessionListMetadata', 'agentPreset',
 ])
 
 /**
@@ -115,3 +123,64 @@ export function encodeDigest(value, encoding) {
     rawBytes: raw.length,
   }
 }
+
+/** 单条会话的稳定指纹：内容不变则指纹不变（用于增量比较）。 */
+export function digestFingerprint(item) {
+  try {
+    return createHash('sha1').update(JSON.stringify(item)).digest('hex').slice(0, 16)
+  } catch {
+    return 'unhashable'
+  }
+}
+
+/**
+ * 一批会话的指纹表（sessionId → 指纹）。
+ *
+ * 键是宿主 `SessionSummary.sessionId`——会话身份在宿主只有这一个名字。
+ * 这里不认 `id`：多认一个名字就是第二份身份，正是它让指纹表恒为空（2026-10-27）。
+ */
+export function digestFingerprints(items) {
+  const map = new Map()
+  for (const item of items ?? []) {
+    if (item && typeof item.sessionId === 'string') map.set(item.sessionId, digestFingerprint(item))
+  }
+  return map
+}
+
+/** 指纹表的版本：指纹集合不变则版本不变。 */
+export function fingerprintsVersion(map) {
+  const keys = [...map.keys()].sort()
+  const digest = createHash('sha1')
+  for (const key of keys) digest.update(key).update('\u0000').update(map.get(key)).update('\u0001')
+  return digest.digest('hex').slice(0, 16)
+}
+
+/**
+ * 相对上一次指纹表的增量。
+ *
+ * 入参 `previous` 为 Map 或 null。返回：
+ *   - `full`：能不能把这份结果当增量发；
+ *   - `changed`：新增或内容变化的项（`full` 时为整份 items）；
+ *   - `removed`：消失的 sessionId（`full` 时为空）；
+ *   - `version` / `fingerprints`：下一次比较用的版本与指纹表。
+ *
+ * **身份不可识别时退化为全量**：摘要是优化，不是事实来源。只要有一项没有 `sessionId`，
+ * 就没法证明其余项没变；此时宁可多发一份全量，也不能回空增量——后者不报错、不更新，
+ * 界面看起来正常却永远冻结（2026-10-27 的现场）。
+ */
+export function digestDelta(previous, items) {
+  const list = Array.isArray(items) ? items : []
+  const identifiable = list.every((item) => item && typeof item.sessionId === 'string')
+  const next = digestFingerprints(list)
+  const version = fingerprintsVersion(next)
+  if (previous === null || !identifiable) {
+    return { full: true, changed: list, removed: [], version, fingerprints: next }
+  }
+  const changed = []
+  for (const item of list) {
+    if (previous.get(item.sessionId) !== next.get(item.sessionId)) changed.push(item)
+  }
+  const removed = []
+  for (const sessionId of previous.keys()) if (!next.has(sessionId)) removed.push(sessionId)
+  return { full: false, changed, removed, version, fingerprints: next }
+}

package/lib/state.js

@@ -3,8 +3,8 @@
  *
  * The file holds the long-lived `agentId` / `agentSecret` for this computer.
  * There are two ways it gets there, and they are deliberately indistinguishable
- * afterwards: the relay operator provisions it by hand (relay/admin.py
- * `agent-register --write-config`), or the person running the computer redeems
+ * afterwards: the relay operator provisions it by hand (`dsh-relay admin
+ * agent-register --write-config`), or the person running the computer redeems
  * an invite code themselves (`dsh-mobile-link enroll`, see enroll.js).
  * Environment variables and the plugin config block override the file, which is
  * how the integration test injects a throwaway identity.
@@ -106,10 +106,10 @@ export async function resolveIdentity({ stateFile, agentId, agentSecret, relayUr
   }
   if (!resolved.agentId || !resolved.agentSecret) {
     throw new MissingIdentity(
-      `mobile-link: this computer is not registered yet. Run "dsh-mobile-link enroll`
-      + ` --invite <code> --relay <relay-url>" with the invite code you were given, or set`
-      + ` ${INVITE_ENV} and restart DSH. (Provisioning by hand is still possible:`
-      + ` "python3 relay/admin.py agent-register --account <acc> --name <name>`
+      `mobile-link: this computer is not registered yet. Open the "移动端连接" panel`
+      + ` and click 登记, or run "dsh-mobile-link enroll --relay <relay-url>".`
+      + ` (Provisioning by hand is still possible:`
+      + ` "dsh-relay admin agent-register --account <acc> --name <name>`
       + ` --write-config ${path}".)`,
       { stateFile: path },
     )

package/lib/status.js

@@ -6,6 +6,7 @@
  * 函数只读 agent 的字段，不持有状态，因此可以直接被单测调用。
  */
 
+import { isPlaceholderRelayUrl } from './dlp.js'
 import { SERVER_CAPABILITIES, SERVER_VERSION, hostVersion } from './hello.js'
 
 const PROTOCOL_VERSION = 1
@@ -81,6 +82,26 @@ const STATUS_JOURNAL_ENTRIES = 20
  */
 export function statusSnapshot(agent) {
   const hostEntry = HOST_HINTS[agent.hostForm] ?? HOST_HINTS.unknown
+  // One resolved view of the relay address, shared by the form and the panel:
+  // a configured address outranks the identity, but the repository placeholder
+  // is "unset", never a value to prefill. `relayLocked` says the address came
+  // from config/env, so the form must be read-only — otherwise the panel would
+  // enroll with one address and the next boot would dial another.
+  const configuredRelay = typeof agent.config?.relayUrl === 'string' ? agent.config.relayUrl : ''
+  const realConfiguredRelay = configuredRelay && !isPlaceholderRelayUrl(configuredRelay)
+    ? configuredRelay
+    : null
+  // `defaultRelayUrl` is a *form default*, not a dialing override: it only
+  // prefills the input, so the user can replace it and the identity file still
+  // wins on the next boot. A real `relayUrl` is the operator pin and locks it.
+  const configuredDefault = typeof agent.config?.defaultRelayUrl === 'string'
+    ? agent.config.defaultRelayUrl
+    : ''
+  const defaultRelay = configuredDefault && !isPlaceholderRelayUrl(configuredDefault)
+    ? configuredDefault
+    : null
+  const effectiveRelay = agent.identity?.relayUrl ?? realConfiguredRelay ?? null
+  const relayPrefill = realConfiguredRelay ?? defaultRelay ?? agent.identity?.relayUrl ?? null
   return {
     ok: true,
     enabled: agent.enabled !== false,
@@ -102,11 +123,18 @@ export function statusSnapshot(agent) {
       // computer half is installed but not yet registered, and what to run.
       registered: !agent.needsEnroll,
       needsEnroll: agent.needsEnroll,
+      // `panel` is a host-UI capability, not a phone capability: an older
+      // connector omits it, and the panel falls back to the command. It is
+      // deliberately not in SERVER_CAPABILITIES (that list is what the app asks
+      // for over `_link/hello`; the phone has no use for a panel form).
+      panel: true,
       stateFile: agent.identity?.stateFile ?? agent.config.stateFile ?? null,
-      relayUrl: agent.config.relayUrl ?? null,
+      relayUrl: effectiveRelay,
+      relayPrefill,
+      relayLocked: Boolean(realConfiguredRelay),
       command: agent.needsEnroll ? agent.enrollHint() : null,
       hint: agent.needsEnroll
-        ? '这台电脑还没有登记到中转。请带上邀请码运行一次登记命令，然后重启 DSH。'
+        ? '这台电脑还没有登记到中转。在「移动端连接」面板里确认中转地址，然后点「登记」。'
         : null,
     },
     state: agent.state,