dsh-plugin-mobile-link 0.4.1 → 0.6.5

package/lib/qr.js

@@ -551,11 +551,19 @@ export function qrMatrix(text, { mask } = {}) {
  * One path element rather than thousands of rects: small enough to print in a
  * terminal response, and it renders identically. The four-module quiet zone is
  * not decoration — scanners need it to find the symbol at all.
+ *
+ * `caption` draws one line under the symbol. It exists because a pairing code
+ * expires and the page is only a picture: without the line, "还剩多久" is
+ * something a person has to guess, and a guess is what leads to scanning a code
+ * that is already gone. The font stack names the CJK faces explicitly — the
+ * default SVG font renders the caption as boxes on some systems.
  */
-export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light = '#ffffff', mask } = {}) {
+export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light = '#ffffff',
+                              mask, caption } = {}) {
   const matrix = qrMatrix(text, mask === undefined ? {} : { mask })
   const size = matrix.length
   const extent = (size + quietZone * 2) * scale
+  const captionHeight = caption ? Math.round(scale * 4.5) : 0
   const segments = []
   for (let row = 0; row < size; row += 1) {
     for (let column = 0; column < size; column += 1) {
@@ -565,14 +573,35 @@ export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light
       segments.push(`M${x} ${y}h${scale}v${scale}h-${scale}z`)
     }
   }
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${extent}" height="${extent}"`
-    + ` viewBox="0 0 ${extent} ${extent}" shape-rendering="crispEdges" role="img"`
+  const captionMarkup = caption
+    ? `<text x="${extent / 2}" y="${extent + Math.round(captionHeight * 0.7)}"`
+      + ` text-anchor="middle" font-family="PingFang SC, Hiragino Sans GB, Microsoft YaHei, sans-serif"`
+      + ` font-size="${Math.round(scale * 1.75)}" fill="${dark}">${escapeXml(caption)}</text>`
+    : ''
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${extent}" height="${extent + captionHeight}"`
+    + ` viewBox="0 0 ${extent} ${extent + captionHeight}" role="img"`
     + ` aria-label="DSH 配对二维码">`
-    + `<rect width="${extent}" height="${extent}" fill="${light}"/>`
-    + `<path d="${segments.join('')}" fill="${dark}"/>`
+    + `<rect width="${extent}" height="${extent + captionHeight}" fill="${light}"/>`
+    // crispEdges belongs to the symbol, not to the document: the caption is text,
+    // and rendering *that* without antialiasing is what makes it look broken.
+    + `<path d="${segments.join('')}" fill="${dark}" shape-rendering="crispEdges"/>`
+    + captionMarkup
     + '</svg>'
 }
 
+/**
+ * The five characters that cannot appear literally in XML text.
+ *
+ * The caption is built from a clock and a count, but it is a parameter, so it is
+ * escaped here rather than trusted: an unescaped `&` produces an SVG the browser
+ * refuses to render at all — a pairing screen that shows nothing.
+ */
+function escapeXml(value) {
+  return String(value).replace(/[&<>"']/g, (ch) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
+  }[ch]))
+}
+
 /**
  * The same symbol for a terminal, two matrix rows per line of text.
  *

package/lib/router.js

@@ -16,6 +16,8 @@ import { FileInbox, FILE_BEGIN, FILE_CHUNK, FILE_END, isFileMethod } from './fil
 import { FileFetcher, FSGET_CANCEL } from './files-out.js'
 import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
+import { isHistoryMethod } from './history.js'
+import { trimRecordsForWire } from './history/records.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -74,6 +76,62 @@ export function errorObject(code, message, details = {}) {
   return { code, message, details }
 }
 
+/**
+ * 旧分页通道（`session/page`）的下发形态清洗（016）。
+ *
+ * 这一路是**降级通道**：宿主自己回一页记录，连接器只是转发。它和精确窗口
+ * （`_link/sessionWindow`）必须守同一条口径 —— 只用于诊断的宿主模型输出日志
+ * 不下发（见 `specs/016-history-load-perf/contracts/history-record-trim.md`）。
+ *
+ * 两种形态都要认：宿主 RPC 的信封 `{ ok, value: { records } }`，以及直接给
+ * `{ records }` 的桩/测试形态。其余方法或结构一律原样返回，不做推断。
+ */
+export function trimHistoryPageForWire(method, result) {
+  if (method !== 'session/page') return result
+  if (result === null || typeof result !== 'object') return result
+  const page = result.value ?? result
+  if (page === null || typeof page !== 'object' || !Array.isArray(page.records)) return result
+  const trimmed = { ...page, records: trimRecordsForWire(page.records) }
+  return result.value === undefined ? trimmed : { ...result, value: trimmed }
+}
+
+import { DeviceTimeline } from './diagnostics.js'
+import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest } from './session-digest.js'
+
+/** 慢请求阈值默认值（毫秒）；0 = 关闭逐条慢请求记录。 */
+export const DEFAULT_SLOW_REQUEST_MS = 2000
+
+/** App 把自己那份阶段记录推上来的方法（契约 connector-diagnostics-method.md）。 */
+export const DIAGNOSTICS_METHOD = '_link/diagnostics'
+/** 单批上限：超过就截断并如实报 `accepted`，剩下的由 App 下次再推（水位不推进）。 */
+export const DIAGNOSTICS_BATCH_BYTES = 32 * 1024
+/** 单条事件里字符串字段的保留长度。 */
+const DIAGNOSTICS_MAX_TEXT = 400
+
+/**
+ * 只留标量（字符串/数字/布尔）与标量数组。
+ *
+ * **必须把 App 的 `detail` 摊平到顶层**：App 侧的 JSONL 信封是
+ * `{kind, seq, ms, at, detail:{...}}`（见 DSHKit 的 `LinkDiagnostics.Event`），而连接器
+ * 自己的流水是**扁平**的。不摊平的话 `phase`/`ms` 这些字段会在清洗时被当成嵌套对象丢掉——
+ * 实测症状：`app.dial` 落盘后一个字段都没有（2026-10-13 09:25 的中转运行）。
+ */
+function sanitizeDiagnosticEvent(event) {
+  if (!event || typeof event !== 'object' || typeof event.kind !== 'string') return null
+  const { detail, ...envelope } = event
+  const flat = { ...envelope, ...(detail && typeof detail === 'object' ? detail : {}) }
+  const clean = { kind: event.kind }
+  for (const [key, value] of Object.entries(flat)) {
+    if (key === 'kind') continue
+    if (typeof value === 'string') clean[key] = value.slice(0, DIAGNOSTICS_MAX_TEXT)
+    else if (typeof value === 'number' || typeof value === 'boolean') clean[key] = value
+    else if (Array.isArray(value) && value.every((item) => typeof item === 'string' || typeof item === 'number')) {
+      clean[key] = value.slice(0, 32)
+    }
+  }
+  return clean
+}
+
 export class DeviceRouter {
   /**
    * @param {object} options
@@ -83,13 +141,28 @@ export class DeviceRouter {
    */
   constructor({
     dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
-    eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {},
+    eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {}, onEvent = () => {},
+    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true,
   } = {}) {
     this.dsh = dsh
     this.eventsBacklog = eventsBacklog
+    this.slowRequestMs = Number(slowRequestMs) || 0
+    this.diagnosticsEnabled = diagnostics !== false
+    /** 每个 deviceId 当前这次接入的计时（attach 时建、detach 时收）。 */
+    this.timelines = new Map()
+    /**
+     * 当前这次请求已经发出去的字节数（在 `noteSent` 里累加、在请求收尾时取走）。
+     *
+     * 同一设备上并发请求会把字节算到一起——诊断只要量级对得上（"这次响应是几 KB 还是几 MB"），
+     * 不值得为它引入逐请求关联（那要改所有回包点的形状）。
+     */
+    this._sentBytes = new Map()
     // 「跑完了 / 待你回应」这类事件到了就报一声（见 `notifyFor`）。默认空函数，
     // 测试与不关心提醒的调用方可以不管它。帧由 link.js 发（router 不发帧）。
     this.notify = notify
+    // 生命周期事件（设备 attach/detach 等）的去处，由 link.js 接到流水（journal.js）。
+    // 默认空函数，所以 router 单独用时（单测、本地脚本）不需要日志设施。
+    this.onEvent = onEvent
     // Reported to the app so it can tell which wire revision it is talking to.
     this.protocolVersion = protocolVersion
     this.send = send
@@ -109,6 +182,9 @@ export class DeviceRouter {
       logger,
     })
     this.git = new GitBridge(logger)
+    // 历史窗口/检索（spec 007）：由 index.js 注入宿主 `sessionQuery` 后交给它。
+    // 没绑上就回 `link/unsupported`，手机端退回 `session/page`。
+    this.history = undefined
   }
 
   #changed() {
@@ -152,9 +228,12 @@ export class DeviceRouter {
       return
     }
     switch (frame.t) {
-      case 'req':
+      case 'req': {
+        const startedAt = this.now()
         await this.handleRequest(deviceId, frame)
+        this.#noteRequest(deviceId, frame.method, startedAt)
         return
+      }
       case 'open':
         await this.handleOpen(deviceId, frame)
         return
@@ -255,16 +334,117 @@ export class DeviceRouter {
 
   // ── device lifecycle ────────────────────────────────────────────────────
 
+  /**
+   * 记一条请求的耗时与字节（spec 020 的 FR-001–FR-003）。
+   *
+   * `bytes` 取"这次请求期间发出去的字节"（见 `noteSent`）——它是一个近似值，
+   * 只在同一设备上并发请求时才会串味，而诊断要回答的是"这次响应是几 KB 还是几 MB"。
+   */
+  #noteRequest(deviceId, method, startedAt) {
+    const timeline = this.timelines.get(deviceId)
+    if (!timeline) return
+    const bytes = this._sentBytes.get(deviceId) ?? 0
+    this._sentBytes.set(deviceId, 0)
+    timeline.noteRequest({ method, startedAt, ms: this.now() - startedAt, bytes })
+  }
+
+  /** 每发一帧给某台设备就累加它的字节数（由 `link.js` 的 `sendToDevice` 调用）。 */
+  noteSent(deviceId, bytes) {
+    if (!deviceId || !Number.isFinite(bytes)) return
+    this._sentBytes.set(deviceId, (this._sentBytes.get(deviceId) ?? 0) + bytes)
+  }
+
+  /**
+   * 收下 App 推来的阶段记录（spec 020 的 FR-011 / 契约 §2）。
+   *
+   * 三条硬规则：
+   *   1. **时刻照抄**：App 事件的 `at`/`ms` 是它自己钟上的读数，连接器不许改写
+   *      （否则"手机侧几点了"这条信息就没了，而它正是区分"App 挂起"与"拨号卡住"的依据）；
+   *   2. **按序号幂等**：同一批重推不会写两遍（水位记在设备记录上）；
+   *   3. **超批上限就截断**：只收前若干条并如实报 `accepted`/`lastSeq`，剩下的下次再推——
+   *      绝不假装收全了。
+   *
+   * @returns {{ok: true, value: {accepted: number, lastSeq: number}}}
+   */
+  acceptDiagnostics(deviceId, args = {}) {
+    if (!this.diagnosticsEnabled) {
+      // 回退闸：关掉时明确拒绝，手机据此静默忽略（不影响连接）。
+      return { ok: false, error: errorObject('diagnostics/disabled', 'diagnostics intake is disabled on this connector') }
+    }
+    const record = this.devices.get(deviceId)
+    const watermark = Number(record?.diagnosticsSeq) || 0
+    const events = Array.isArray(args.events) ? args.events : []
+    let accepted = 0
+    let lastSeq = watermark
+    let bytes = 0
+    for (const raw of events) {
+      const event = sanitizeDiagnosticEvent(raw)
+      if (!event) continue
+      const seq = Number(event.seq)
+      if (Number.isFinite(seq) && seq <= watermark) continue
+      const size = JSON.stringify(event).length
+      if (bytes > 0 && bytes + size > DIAGNOSTICS_BATCH_BYTES) break
+      // 用 recordForeign：App 的时刻照抄（它是"手机侧几点"的唯一来源）。
+      // 补 `deviceId`：App 自己不知道它的 id，而多设备时没有这一列就没法把事件归到某台手机上。
+      this.onEvent(event.kind, { ...event, deviceId, source: 'app' }, { foreign: true })
+      bytes += size
+      accepted += 1
+      if (Number.isFinite(seq)) lastSeq = Math.max(lastSeq, seq)
+    }
+    if (record) record.diagnosticsSeq = lastSeq
+    const sentAt = Number(args.sentAt)
+    this.onEvent('app.push', {
+      deviceId,
+      count: accepted,
+      dropped: Number(args.dropped) || 0,
+      sentAt: Number.isFinite(sentAt) ? sentAt : undefined,
+      // 手机时钟与本机时钟的差（单向延迟几十毫秒）；采集侧的对齐就靠这一个数。
+      skewMs: Number.isFinite(sentAt) ? this.now() - sentAt : undefined,
+    })
+    return { ok: true, value: { accepted, lastSeq } }
+  }
+
+  /** 起一次新的接入计时（回头客也重起：那确实是一次新连接）。 */
+  #startTimeline(deviceId) {
+    this.timelines.get(deviceId)?.finish()
+    this.timelines.set(deviceId, new DeviceTimeline({
+      deviceId,
+      slowRequestMs: this.slowRequestMs,
+      now: this.now,
+      onEvent: this.onEvent,
+    }))
+    this._sentBytes.set(deviceId, 0)
+  }
+
+  /** 收掉一次接入计时（断开、撤销、进程收尾都走这里）。 */
+  #finishTimeline(deviceId) {
+    const timeline = this.timelines.get(deviceId)
+    if (!timeline) return
+    timeline.finish()
+    this.timelines.delete(deviceId)
+    this._sentBytes.delete(deviceId)
+  }
+
   async attachDevice(deviceId, info = {}) {
     if (!nonEmptyString(deviceId)) return
+    this.#startTimeline(deviceId)
     const existing = this.devices.get(deviceId)
     if (existing) {
       // 回头客：手机又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
       if (existing.offlineSince !== undefined) {
+        const offlineForMs = this.now() - existing.offlineSince
         existing.offlineSince = undefined
+        this.onEvent('device.reattach', { deviceId, offlineForMs, pending: existing.eventsPending.size })
         this.logger.info?.(
           `mobile-link: device ${deviceId} reattached with ${existing.eventsPending.size} unanswered question(s)`)
         this.#changed()
+      } else {
+        // **这条是"同一台设备同时又开了一条"**：中转的 `attach_device` 会直接覆盖旧
+        // 链路，旧的那条既不会再收到 `deviceDetach`、也不会出现在任何一方的状态里
+        // （2026-10-13 01:10 实测：attach 与上一条 detach 之间空了 34 秒）。记下来，
+        // 否则事后只看得到"它连上了"，看不到"它连了两条"。
+        this.onEvent('device.attach-again', { deviceId, connectedForMs: this.now() - existing.connectedAt })
+        this.logger.warn?.(`mobile-link: device ${deviceId} attached again while still attached`)
       }
       return
     }
@@ -284,6 +464,7 @@ export class DeviceRouter {
       offlineSince: undefined,
       eventsPending: new Map(),
     })
+    this.onEvent('device.attach', { deviceId, name: info?.name, model: info?.model })
     this.logger.info?.(`mobile-link: device ${deviceId} attached (${info?.name ?? 'unknown'})`)
     this.#changed()
     await this.ensureEventsStream(deviceId)
@@ -300,10 +481,12 @@ export class DeviceRouter {
    * 那段的说明）。这也是「撤销即放下」是唯一出口的原因。
    */
   async detachDevice(deviceId, reason) {
+    this.#finishTimeline(deviceId)
     const record = this.devices.get(deviceId)
     if (!record) return
     if (reason === 'revoked') {
       await this.#dropDevice(deviceId)
+      this.onEvent('device.revoked', { deviceId })
       this.logger.info?.(`mobile-link: device ${deviceId} 已被撤销，放下（不再替它值班）`)
       return
     }
@@ -322,6 +505,7 @@ export class DeviceRouter {
     for (const entry of keep) record.dlpIds.add(entry.dlpId)
 
     if (record.offlineSince === undefined) record.offlineSince = this.now()
+    this.onEvent('device.detach', { deviceId, reason: reason ?? 'closed' })
     this.logger.info?.(
       `mobile-link: device ${deviceId} detached (${reason ?? 'closed'})；`
       + '$events 流一直替它留着，直到设备被撤销或进程退出')
@@ -362,16 +546,48 @@ export class DeviceRouter {
   teardownAll() {
     const muxIds = []
     for (const deviceId of [...this.devices.keys()]) {
+      // 进程收尾/链路重建也要把这次接入的汇总写掉，否则"连上过、发过请求"这件事没有数字。
+      this.#finishTimeline(deviceId)
       muxIds.push(...this.streams.removeDevice(deviceId))
       this.devices.delete(deviceId)
     }
     this.streams = new StreamTable()
+    // 不该有残留：上面的循环已经逐个收过；这里兜底，防止 attach 之后没进 devices 的路径留下脏项。
+    this.timelines.clear()
+    this._sentBytes.clear()
     return muxIds
   }
 
   // ── device requests ─────────────────────────────────────────────────────
 
   async handleRequest(deviceId, frame) {
+    // App 推上来的阶段记录：**只落盘，不影响任何连接行为**（契约
+    // connector-diagnostics-method.md §4）。放在最前面，免得被后面的方法族顺序影响。
+    // 精简版会话列表（spec 021）：同一份宿主数据，去掉 App 侧零读取点的字段，可按要求 gzip。
+    // 老方法 `session/list` 一个字节都不改——老版本手机继续走它，这是兼容的前提。
+    if (frame.method === SESSION_DIGEST_METHOD) {
+      const args = frame.args ?? {}
+      let result
+      try {
+        result = await this.dsh.rpc('session/list', { _request: args._request ?? {} })
+      } catch (error) {
+        result = { ok: false, error: errorObject('host/unavailable', messageOf(error)) }
+        this.lastError = messageOf(error)
+        this.#changed()
+      }
+      const payload = result?.ok === true
+        ? { ok: true, value: encodeDigest(digestSessionList(result), args.encoding) }
+        : result
+      this.send(deviceId, resultFrame(frame.id, payload, deviceId))
+      return
+    }
+
+    if (frame.method === DIAGNOSTICS_METHOD) {
+      const result = this.acceptDiagnostics(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.
@@ -433,9 +649,28 @@ export class DeviceRouter {
       return
     }
 
+    // History reads run here too (spec 007): the Host owns a seq-exact reader but
+    // does not expose it on the remote surface the phone talks to. Answered
+    // locally when the injected `sessionQuery` is present; otherwise the phone is
+    // told plainly that the capability is missing, so it can keep using
+    // `session/page` instead of reading the failure as "no older history".
+    if (isHistoryMethod(frame.method)) {
+      let result
+      try {
+        result = this.history === undefined
+          ? { ok: false, error: errorObject('link/unsupported', 'history reads are unavailable on this connector') }
+          : await this.history.handle(frame.method, 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 ?? {})
+      result = trimHistoryPageForWire(frame.method, result)
     } catch (error) {
       result = { ok: false, error: errorObject('host/unavailable', messageOf(error)) }
       this.lastError = messageOf(error)

package/lib/routes.js

@@ -2,8 +2,7 @@
  * HTTP routes under `/mobile-link`, registered on DSH's own web server.
  *
  *   GET  /mobile-link/status     connection + device inventory + setup state
- *   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
+ *   POST /mobile-link/pair-code  mint a pairing code (and its QR payload + SVG)
  *
  * All sit behind DSH's own request fence, like every other plugin route:
  * `ctx.get('connection')?.requestRejection?.(req)` performs the Host/Origin check
@@ -23,13 +22,6 @@ export function sendJson(res, status, payload) {
   res.end(JSON.stringify(payload))
 }
 
-export function sendSvg(res, status, svg) {
-  res.statusCode = status
-  res.setHeader('content-type', 'image/svg+xml; charset=utf-8')
-  res.setHeader('cache-control', 'no-store')
-  res.end(svg)
-}
-
 export async function readJsonBody(req) {
   const chunks = []
   let size = 0
@@ -55,9 +47,25 @@ export async function readJsonBody(req) {
 export function makeGuard(ctx, logger) {
   const connectionOf = () => (typeof ctx.get === 'function' ? ctx.get('connection') : undefined)
   return function guard(req, res, { requireFence = false } = {}) {
+    const connection = connectionOf()
+    const fence = connection?.requestRejection
+    // DSH's contract is "a status when refused, **undefined** when the request
+    // may proceed" — so undefined is a pass, not an absence. Reading it as an
+    // absence is what made every privileged route below answer 403 to everyone
+    // with a perfectly authenticated request: the pairing page and
+    // `POST /pair-code` never got past the guard. The service's own presence is
+    // the only thing that can tell "no fence to consult" apart from "fence says
+    // yes", so that is what is checked here.
+    if (typeof fence !== 'function') {
+      if (requireFence) {
+        sendJson(res, 403, { ok: false, message: 'the DSH connection service is unavailable; refusing a privileged request' })
+        return true
+      }
+      return false
+    }
     let rejection
     try {
-      rejection = connectionOf()?.requestRejection?.(req)
+      rejection = fence.call(connection, req)
     } catch (error) {
       logger.warn?.(`mobile-link: request fence failed: ${error}`)
       sendJson(res, 403, { ok: false, message: 'request rejected by the DSH fence' })
@@ -68,10 +76,6 @@ export function makeGuard(ctx, logger) {
       res.end()
       return true
     }
-    if (requireFence && rejection === undefined) {
-      sendJson(res, 403, { ok: false, message: 'the DSH connection service is unavailable; refusing a privileged request' })
-      return true
-    }
     return false
   }
 }
@@ -86,11 +90,10 @@ function ttlFrom(value, fallbackMs) {
  * Register the routes.
  * @returns {Array<() => void>} disposers (already wrapped by the caller in ctx.effect).
  */
-export function registerMobileLinkRoutes(ctx, { agent, logger, config = {} }) {
+export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, history }) {
   const guard = makeGuard(ctx, logger)
   const STATUS_ROUTE = '/mobile-link/status'
   const PAIR_ROUTE = '/mobile-link/pair-code'
-  const QR_ROUTE = '/mobile-link/qr'
   const disposers = []
 
   disposers.push(ctx.webServer.register({
@@ -132,48 +135,16 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {} }) {
       try {
         const minted = await agent.mintPairCode({ ttlMs })
         logger.info?.(`mobile-link: minted a pairing code for ${minted.agentId}`)
-        sendJson(res, 200, { ok: true, ...minted })
-      } catch (error) {
-        sendJson(res, 502, { ok: false, code: 'relay/unavailable', message: String(error?.message ?? error) })
-      }
-    },
-  }))
-
-  // The QR a phone camera can actually read. Rendered here rather than in the
-  // desktop UI so the pairing screen is one URL: anyone can open
-  // `http://127.0.0.1:<port>/mobile-link/qr` (with DSH's own authentication)
-  // and see a scannable code, with no client-side work and no extra dependency.
-  //
-  // `?format=json` returns the payload and the code without the picture, which
-  // is what the automated tests use.
-  disposers.push(ctx.webServer.register({
-    kind: 'exact',
-    path: QR_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
-      }
-      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
-      const ttlMs = ttlFrom(url.searchParams.get('ttlMs'), Number(config.pairTtlMs) || 10 * 60 * 1000)
-      let minted
-      try {
-        minted = await agent.mintPairCode({ ttlMs })
+        // The picture travels with the code. It used to be a route of its own
+        // (`GET /mobile-link/qr`) that a person opened in a browser; the pairing
+        // entry is now the connector's own panel in the DSH client, so the one
+        // caller left is that panel, and it wants the code and the symbol in the
+        // same answer. No caption: the panel runs its own countdown, and a
+        // server-rendered "还剩 N 分钟" freezes the moment the window is up.
+        sendJson(res, 200, { ok: true, ...minted, svg: qrSvg(minted.qrPayload) })
       } catch (error) {
         sendJson(res, 502, { ok: false, code: 'relay/unavailable', message: String(error?.message ?? error) })
-        return
-      }
-      const payload = minted.qrPayload
-      const wantsJson = (url.searchParams.get('format') ?? '').toLowerCase() === 'json'
-      logger.info?.(`mobile-link: rendered a pairing QR for ${minted.agentId}`)
-      if (wantsJson) {
-        sendJson(res, 200, { ok: true, ...minted, svg: qrSvg(payload) })
-        return
       }
-      sendSvg(res, 200, qrSvg(payload))
     },
   }))
 

package/lib/session-digest.js

@@ -0,0 +1,117 @@
+/**
+ * `_link/sessionDigest`：`session/list` 的精简同形副本（spec 021）。
+ *
+ * 为什么要有它：`session/list` 占经中转下行字节的 **96%**，一次固定 714 KB，而中转出口实测只有
+ * 16–112 KB/s（2026-10-13 现场诊断）。其中 **58.8% 的字节是 App/DSHKit 从来不读的字段**
+ * （逐字段扫 79 个源文件核对，清单见 `contracts/session-digest.md` §4）。
+ *
+ * 三条硬约束：
+ *   1. **不动 `session/list`**：老 App 只认它，字段删掉就没有回退路径。
+ *   2. **不改入参**：宿主返回什么就基于它生成新对象，方便"同一份数据两条路径"逐字节对比。
+ *   3. **只删名单里的**：名单之外的字段（包括以后宿主新增的）一律原样透传，避免"裁剪"变成"猜"。
+ */
+
+import { deflateRawSync } from 'node:zlib'
+
+/** 方法名（设备发起，中转不校验方法名，所以不需要中转改动）。 */
+export const SESSION_DIGEST_METHOD = '_link/sessionDigest'
+
+/** 会话项里剔掉的字段：零读取点（`agentAvailable` 1.8%）。 */
+export const DROPPED_ITEM_KEYS = Object.freeze(['agentAvailable'])
+
+/**
+ * 投影键里剔掉的字段（合计 56.7%）。
+ *
+ * 每一条都能在 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` 是请求字段）。
+ */
+export const DROPPED_PROJECTION_KEYS = Object.freeze([
+  'turnOutline', 'imageLimits', 'sessionStats', 'todos', 'subagentCatalog',
+  'contextBreakdown', 'sessionListMetadata', 'subagentTiming', 'agentPreset',
+])
+
+/**
+ * 只接受的压缩编码；其它一律按不压缩处理（保守，不因为多写一个字段就让调用方失败）。
+ *
+ * `deflate-raw` = RFC1951 原始 DEFLATE，**不带** gzip/zlib 包装。选它而不是 gzip 的原因是
+ * 手机侧：Apple 的 `Compression` 框架（`COMPRESSION_ZLIB`）一行 `compression_decode_buffer`
+ * 就能解开原始 DEFLATE，而 gzip 包装它不认，得引 libz 的 `inflateInit2(MAX_WBITS+16)` 做 C 互操作。
+ * 两者压缩比实测相同（239 KiB → 36.8 KiB）。
+ */
+export const DEFLATE_ENCODING = 'deflate-raw'
+export const IDENTITY_ENCODING = 'identity'
+
+/** 按原键序复制并跳过剔除名单：键序稳定才能做"逐字节对比"。 */
+function omit(source, dropped) {
+  const out = {}
+  for (const key of Object.keys(source)) {
+    if (dropped.has(key)) continue
+    out[key] = source[key]
+  }
+  return out
+}
+
+/**
+ * 裁剪一份会话列表的**值**（`{ items: [...] }`）。
+ *
+ * 认两种输入（与 `trimHistoryPageForWire` 同款）：宿主信封 `{ ok, value: { items } }`，
+ * 以及直接给的 `{ items }`。**返回的始终是列表值本身**，调用方不需要再猜信封在哪一层
+ * （曾经因为这里保留信封、外面又包一层，响应成了 `{encoding, value:{ok, value:{items}}}`）。
+ *
+ * 结构不是预期的样子就**原样返回入参**——裁剪不许把"看不懂"变成"删掉"。
+ *
+ * @param {unknown} result 宿主响应或其 `value`
+ * @returns {unknown} 裁剪后的列表值；不合法时原样返回入参
+ */
+export function digestSessionList(result) {
+  if (result === null || typeof result !== 'object') return result
+  const container = Array.isArray(result.items) ? result : result.value
+  if (container === null || typeof container !== 'object' || !Array.isArray(container.items)) {
+    return result
+  }
+  return { ...container, items: container.items.map(digestItem) }
+}
+
+/** 单条会话：剔顶层字段与投影键；`projections` 缺失或形状不对就原样留着。 */
+function digestItem(item) {
+  if (item === null || typeof item !== 'object') return item
+  const out = omit(item, new Set(DROPPED_ITEM_KEYS))
+  const projections = item.projections
+  if (projections === null || typeof projections !== 'object') return out
+  // `kind: "sequenced"` 是信封常量，App 侧模型没解码它（1.3%）。
+  const envelope = omit(projections, new Set(['kind']))
+  const values = projections.values
+  if (values !== null && typeof values === 'object') {
+    envelope.values = omit(values, new Set(DROPPED_PROJECTION_KEYS))
+  }
+  out.projections = envelope
+  return out
+}
+
+/**
+ * 按调用方要求编码裁剪后的值。
+ *
+ * **只在应用层压**：中转的 `WebSocketResponse(compress=False)`，手机侧
+ * `URLSessionWebSocketTask` 也不支持 permessage-deflate，所以 WS 层压缩救不了手机那一跳。
+ * 压缩后的字节 base64 放进 JSON 文本帧（与 `_link/diagnostics` 同款），中转不需要任何改动。
+ *
+ * `rawBytes` 是**解压后的字节长度**：Apple 的 `compression_decode_buffer` 必须预先给足输出缓冲区，
+ * 带上它调用方就能一次分配到位，不必"猜容量、失败再翻倍重试"。
+ *
+ * @param {unknown} value 裁剪后的值
+ * @param {unknown} encoding 调用方要求；只认 `"deflate-raw"`
+ * @returns {{encoding: string, value: unknown, rawBytes?: number}} 带回执，调用方据此决定解不解压
+ */
+export function encodeDigest(value, encoding) {
+  if (encoding !== DEFLATE_ENCODING) return { encoding: IDENTITY_ENCODING, value }
+  const json = JSON.stringify(value ?? null)
+  const raw = Buffer.from(json, 'utf8')
+  return {
+    encoding: DEFLATE_ENCODING,
+    value: deflateRawSync(raw).toString('base64'),
+    rawBytes: raw.length,
+  }
+}