dsh-plugin-mobile-link 0.6.0 → 0.6.6

package/README.md

@@ -30,6 +30,7 @@ plugins/mobile-link/
 │   ├── dlp.js            # DLP v1 frame codec (shared with the relay)
 │   ├── files.js          # phone → computer file transfers (`_link/file*` methods)
 │   ├── enroll.js         # invite-code redemption, writes ~/.dsh/mobile-link/agent.json
+│   ├── journal.js        # lifecycle journal: why a relay link was dropped, after the fact
 │   ├── routes.js         # GET /mobile-link/status, POST /pair-code, GET /qr
 │   ├── qr.js             # dependency-free QR SVG
 │   └── cli.js            # dsh-mobile-link: enroll / mint-pair-code
@@ -95,7 +96,10 @@ dsh plugin --profile web add ./plugins/mobile-link
    else has to be run by hand.
 
 `GET /mobile-link/status` reports whether the link is up, which devices are
-attached, and whether this computer is registered yet.
+attached, and whether this computer is registered yet. Its `journal` block carries
+the current process's newest lifecycle events (link opened/closed with the reason,
+device attached/detached); the counters in it reset when the plugin hot-reloads, so
+the full history — across restarts — is the JSONL file at `journal.path`.
 
 ## Configuration
 
@@ -108,6 +112,9 @@ plugin's config block (`cordis.patch.yml`), not by editing this file.
 | `relayUrl` | from `agent.json` | Relay base URL; a bare deployment dials `<relay>/link/agent` |
 | `agentId` / `agentSecret` | from `agent.json` | Override the enrolled identity |
 | `stateFile` | `~/.dsh/mobile-link/agent.json` | Where the identity lives |
+| `journalFile` | `~/.dsh/mobile-link/link-events.jsonl` | Lifecycle journal (rotated once at 256 KiB); `false` keeps it in memory only |
+| `slowRequestMs` | `2000` | A slower single request gets its own `request.slow` entry; `0` disables those (per-attach `device.summary` is still written) |
+| `diagnostics` | `true` | `false` refuses the phone's phase uploads; the phone ignores the refusal and stays connected |
 | `dshUrl` | discovery | Explicit local DSH base URL (usually unnecessary — the host hands the connector its own address) |
 | `heartbeatMs` | `20000` | DLP ping interval |
 

package/cordis.patch.yml

@@ -20,6 +20,18 @@
 #   agentId        overrides ~/.dsh/mobile-link/agent.json
 #   agentSecret    overrides ~/.dsh/mobile-link/agent.json
 #   stateFile      agent identity file (default ~/.dsh/mobile-link/agent.json)
+#   journalFile    lifecycle journal (default ~/.dsh/mobile-link/link-events.jsonl,
+#                  rotated once at 256 KiB). Every link open/close carries its
+#                  reason, and every device attach/detach is recorded, so "why
+#                  did the connector drop the relay link" stays answerable after
+#                  the fact; the newest entries also ride along in
+#                  GET /mobile-link/status as `journal`. `false` keeps the ring
+#                  in memory only, no file.
+#   slowRequestMs  single-request threshold (default 2000). A request slower than
+#                  this gets its own `request.slow` entry; 0 disables those entries
+#                  (the per-attach `device.summary` is still written).
+#   diagnostics    false refuses the phone's phase uploads (`_link/diagnostics`) with
+#                  `diagnostics/disabled`; the phone ignores it and stays connected.
 #   dshUrl         explicit local DSH base URL override (default: discovery)
 #
 # Address resolution order: this config block, then DSH_RELAY_URL (or

package/lib/client.js

@@ -11,6 +11,7 @@
 /** 路由用相对路径：宿主把插件路由挂在同一个源上。 */
 const STATUS_ROUTE = 'mobile-link/status'
 const PAIR_ROUTE = 'mobile-link/pair-code'
+const REGENERATE_ROUTE = 'mobile-link/pair-code/regenerate'
 const SLOT_ENTRY = 'sidebar.footer.action'
 const SLOT_OVERLAY = 'shell.overlay'
 const ENTRY_ID = 'mobile-link-entry'
@@ -69,16 +70,39 @@ function report(ctx, message) {
 function describe(error) {
   return error instanceof Error ? error.message : String(error)
 }
-/** 样式表：页面上只留一份，退场时随插件 fiber 一起清掉。 */
+/** 样式节点上的"认领者"标记：谁最后认领，谁负责撤。 */
+const STYLE_OWNER_ATTR = 'data-owner'
+/** 认领序号：同一次 enable 一个 token，跨热更两代不会撞。 */
+let styleOwnerSeq = 0
+
+/**
+ * 样式表：页面上只留一份，**但所有权要认**。
+ *
+ * 为什么不能"存在就复用、退场就删"：热更时两代插件可能同时在世，且顺序可能是
+ * "新一代先起来认领同一个 `<style>`、上一代后退场"。上一代若无条件删节点，新面板就
+ * 变成没有样式的裸 HTML——2026-10-17 owner 看到配对面板"突然不像原版"就是这个。
+ * 所以认领时写下自己的 token，退场时只撤自己认领的那一份。
+ */
 function ensureStyle() {
   if (typeof document === 'undefined' || !document.head) return null
-  const existing = document.getElementById(STYLE_ID)
-  if (existing) return existing
-  const style = document.createElement('style')
-  style.id = STYLE_ID
-  style.textContent = CSS
-  document.head.appendChild(style)
-  return style
+  const token = `o${++styleOwnerSeq}-${Date.now()}`
+  let node = document.getElementById(STYLE_ID)
+  if (!node) {
+    node = document.createElement('style')
+    node.id = STYLE_ID
+    node.textContent = CSS
+    document.head.appendChild(node)
+  }
+  node.setAttribute?.(STYLE_OWNER_ATTR, token)
+  return { node, token }
+}
+
+/** 退场：只有这个节点仍归本次 enable 时才撤掉它。 */
+function releaseStyle(style) {
+  const node = style?.node
+  if (!node) return
+  if (node.getAttribute?.(STYLE_OWNER_ATTR) !== style.token) return
+  node.remove?.()
 }
 /** 极小的外部状态容器：按钮与小窗是两个独立注册项，需要共享的只有几个字段。 */
 function createStore(initial) {
@@ -176,41 +200,44 @@ function createPanel() {
     lastStatusAt: 0,
   }
 }
-/**
- * 这张码是不是已经被兑换掉了：只看"在线手机台数比取码时多了"（问中转要动 relay，spec 010 禁止）。
- * 只用来触发换码，不承担旧实现那种"猜这张码还能不能用"的职责。
- */
-function swapIfSpent(panel) {
-  const code = panel.store.get().code
-  if (!code || panel.disposed) return
-  const count = Number(panel.store.get().status?.deviceCount ?? 0)
-  if (count > code.mintedDeviceCount) void refreshCode(panel)
-}
-
 async function loadStatus(panel) {
   try {
     const status = await requestJson(STATUS_ROUTE, { method: 'GET' })
     if (panel.disposed) return
     panel.store.set({ status, statusError: null })
-    swapIfSpent(panel)
   } catch (error) {
     if (panel.disposed) return
     panel.store.set({ statusError: describe(error) })
   }
 }
-/** 取一张新码。**不复用上一张**：复用正是"扫到已兑换的码"的来源。 */
-async function refreshCode(panel) {
+/**
+ * 取一张码。
+ *
+ * 032 起默认是**持久码**：它一直有效，直到用户点「重新生成」。所以这里有两个与旧实现
+ * 相反的行为，都是有意的：
+ *
+ * * **复用已有的那张**——旧实现每次"换一张"，因为一次性码用过就废；持久码换掉等于
+ *   把用户刚发给别人的那张悄悄作废。
+ * * **不再因为"配过一台"就自动换码**——同一张码本来就是要给多台设备用的。
+ */
+async function refreshCode(panel, { regenerate = false } = {}) {
   if (panel.disposed || panel.store.get().busy) return
   if (needsEnroll(panel.store.get().status)) {
     panel.store.set({ code: null, codeError: null })
     return
   }
+  // 只有**持久码**才复用：限时码到期就得重新取一张（老行为），否则屏幕上会留一张死码。
+  if (!regenerate && panel.store.get().code?.persistent) return
   panel.store.set({ busy: true, codeError: null })
   try {
-    const body = await requestJson(PAIR_ROUTE, {
+    // 两条意图分得很清楚：
+    // * `regenerate`：用户点「重新生成」→ 让中转**作废旧码**再铸一张（新端点）。
+    // * 其余（首次取码、限时码到期续期）→ 走原来的取码端点。老中转没有 regenerate，
+    //   续期这条路必须留在老端点上，否则连着老中转的连接器会在这里失败。
+    const body = await requestJson(regenerate ? REGENERATE_ROUTE : PAIR_ROUTE, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ ttlMs: CODE_TTL_MS }),
+      body: JSON.stringify({}),
     })
     if (panel.disposed) return
     panel.store.set({
@@ -218,9 +245,13 @@ async function refreshCode(panel) {
         code: body.code,
         qrPayload: body.qrPayload,
         svg: body.svg,
-        expiresAt: Number(body.expiresAt),
-        ttlMs: Number(body.ttlMs) || CODE_TTL_MS,
-        mintedDeviceCount: Number(panel.store.get().status?.deviceCount ?? 0),
+        // 持久码没有 expiresAt：界面上不再有倒计时（见 codeSection）。
+        expiresAt: body.expiresAt == null ? null : Number(body.expiresAt),
+        ttlMs: Number(body.ttlMs) || null,
+        persistent: body.persistent === true || body.expiresAt == null,
+        maxPairedDevices: Number(body.maxPairedDevices ?? 0) || null,
+        pairedDevices: Number(body.pairedDevices ?? 0),
+        revoked: Number(body.revoked ?? 0),
       },
       codeError: null,
     })
@@ -241,11 +272,17 @@ function tick(panel) {
     panel.lastStatusAt = now
     void loadStatus(panel)
   }
+  // 持久码不因时间换码（032）：只有用户点「重新生成」才换。限时码（老中转/老调用方）
+  // 仍然按原来的规则在快过期时换一张，免得把一张马上就要失效的码摆在屏幕上。
   const code = panel.store.get().code
-  if (code && code.expiresAt - now <= CODE_FLOOR_MS) void refreshCode(panel)
+  if (code && !code.persistent && code.expiresAt != null && code.expiresAt - now <= CODE_FLOOR_MS) {
+    void refreshCode(panel)
+  }
 }
 function openPanel(panel) {
   if (panel.disposed) return
+  // 自愈：样式若在某次热更里被带走（见 ensureStyle 的头注），打开面板时补回来。
+  if (!panel.style?.node?.isConnected) panel.style = ensureStyle()
   panel.store.set({ open: true, now: Date.now(), copied: false })
   panel.lastStatusAt = Date.now()
   void loadStatus(panel)
@@ -253,7 +290,9 @@ function openPanel(panel) {
 }
 function closePanel(panel) {
   if (panel.disposed) return
-  panel.store.set({ open: false, code: null, codeError: null, copied: false })
+  // 032：**不丢码**。持久码要一直有效，关掉面板再打开必须还是同一张——否则用户刚发给
+  // 别人的码就被这次开关悄悄换掉了（旧实现丢码是对的，因为那时码是一次性的）。
+  panel.store.set({ open: false, codeError: null, copied: false })
 }
 function disposePanel(panel) {
   panel.disposed = true
@@ -263,7 +302,7 @@ function disposePanel(panel) {
   panel.idleTimer = null
   panel.tickTimer = null
   panel.copiedTimer = null
-  panel.style?.remove?.()
+  releaseStyle(panel.style)
   panel.style = null
 }
 /** 插件启用时建立的页面资源；返回退场时用的清理函数。 */
@@ -295,14 +334,20 @@ function copyCode(panel) {
     done()
   }
 }
-/** 控制器：视图只读它的 store、只调它的动作；"码什么时候作废"只在 tick/swapIfSpent 定义。 */
+/**
+ * 控制器：视图只读它的 store、只调它的动作。
+ *
+ * 032 起"码什么时候换"只有一处：用户点「重新生成」（`refreshCode({regenerate:true})`）。
+ * 以前还有一条"配过一台就自动换一张"的规则，持久码下那条是错的——同一张码本来就
+ * 要配多台设备。
+ */
 function createController() {
   const panel = createPanel()
   return {
     store: panel.store,
     open: () => openPanel(panel),
     close: () => closePanel(panel),
-    refreshCode: () => refreshCode(panel),
+    refreshCode: (options) => refreshCode(panel, options),
     copy: () => copyCode(panel),
     toggleError: () => panel.store.set({ showError: !panel.store.get().showError }),
     start: () => startPanel(panel),
@@ -351,22 +396,35 @@ function enrollSection(React, status) {
     React.createElement('div', { className: 'dsh-mobile-link-mono dsh-mobile-link-v', style: { textAlign: 'left' } },
       status?.enroll?.command ?? 'dsh-mobile-link enroll --invite <邀请码> --relay <中转地址>'))
 }
-/** 二维码卡：明文码、图案、倒数条，以及换一张与复制。 */
+/**
+ * 二维码卡。
+ *
+ * 032 之前这里是"倒计时 + 换一张"（一次性码，10 分钟）。现在默认是**持久码**：
+ * 所以卡片上写"长期有效，直到你点重新生成"，并且不再有进度条——一个永远走不到头的
+ * 倒计时只会让人以为码快过期了。限时码（老中转/显式请求）仍然显示倒计时与剩余时间。
+ */
 function codeSection(React, controller, ui, state) {
   const code = state.code
   const children = []
   if (code) {
-    const remaining = Math.max(0, code.expiresAt - state.now)
-    const percent = Math.max(0, Math.min(100, (remaining / (code.ttlMs || CODE_TTL_MS)) * 100))
     children.push(React.createElement('div', { className: 'dsh-mobile-link-code', key: 'code' }, code.code))
     // 二维码：宿主给的 SVG 直接进 data URI，界面不碰图案本身。
     children.push(React.createElement('img', {
       key: 'qr', className: 'dsh-mobile-link-qr', alt: '配对二维码',
       src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(String(code.svg))}`,
     }))
-    children.push(React.createElement('div', { className: 'dsh-mobile-link-count', key: 'count' },
-      React.createElement('div', { className: 'dsh-mobile-link-bar' }, React.createElement('i', { style: { width: `${percent.toFixed(1)}%` } })),
-      React.createElement('span', null, `有效期至 ${clockText(code.expiresAt)}（还剩 ${remainingText(remaining)}）`)))
+    if (code.persistent || code.expiresAt == null) {
+      children.push(React.createElement('div', { className: 'dsh-mobile-link-count', key: 'count' },
+        React.createElement('span', null,
+          `长期有效 · 直到你点「重新生成」${code.maxPairedDevices
+            ? `（已配对 ${code.pairedDevices ?? 0}/${code.maxPairedDevices}）` : ''}`)))
+    } else {
+      const remaining = Math.max(0, code.expiresAt - state.now)
+      const percent = Math.max(0, Math.min(100, (remaining / (code.ttlMs || CODE_TTL_MS)) * 100))
+      children.push(React.createElement('div', { className: 'dsh-mobile-link-count', key: 'count' },
+        React.createElement('div', { className: 'dsh-mobile-link-bar' }, React.createElement('i', { style: { width: `${percent.toFixed(1)}%` } })),
+        React.createElement('span', null, `有效期至 ${clockText(code.expiresAt)}（还剩 ${remainingText(remaining)}）`)))
+    }
   } else if (state.codeError) {
     children.push(React.createElement('div', { className: 'dsh-mobile-link-note dsh-mobile-link-error', key: 'err' }, state.codeError))
   } else {
@@ -375,8 +433,9 @@ function codeSection(React, controller, ui, state) {
   }
   const buttons = [React.createElement(ui.Button, {
     key: 'swap', variant: 'primary', type: 'button', disabled: Boolean(state.busy),
-    onClick: () => void controller.refreshCode(),
-  }, state.busy ? '取码中…' : (state.codeError ? '重试' : '换一张'))]
+    onClick: () => void controller.refreshCode({ regenerate: Boolean(state.code) }),
+  }, state.busy ? '取码中…'
+    : (state.codeError ? '重试' : (state.code ? '重新生成' : '取一张码')))]
   if (code) {
     buttons.push(React.createElement(ui.Button, {
       key: 'copy', variant: 'outline', type: 'button', onClick: () => controller.copy(),
@@ -421,7 +480,8 @@ function panelBody(React, controller, ui, state) {
   const error = errorSection(React, controller, ui, state.status, state.showError)
   if (error) children.push(error)
   children.push(React.createElement('div', { className: 'dsh-mobile-link-note', key: 'hint' },
-    '用 DSH Mobile App 扫码配对：一张码只能配一台手机，被兑换或剩余不足 1 分钟会自动换新。'
+    '用 DSH Mobile App 扫码配对：这串码长期有效，可以配多台设备（手机／浏览器）。'
+    + '换掉它点「重新生成」——已经在用的设备不会掉线，只有拿旧码来配的人需要重新扫。'
     + '相机不方便时，也可以把上面那串配对码手动输进 App 连接页底部的手输入口。'))
   return React.createElement('div', { className: 'dsh-mobile-link-body' }, children)
 }

package/lib/diagnostics.js

@@ -0,0 +1,172 @@
+/**
+ * 一次接入的计时与有界耗时汇总（spec 020）。
+ *
+ * 职责（只做这三件，别的都不做）：
+ *   1. **阶段计时**：一次设备接入走完「接入 → `_link/hello` → 首个数据请求 → 首个响应」各用了多少毫秒；
+ *      没发生的阶段必须是 `null` 并在 `missing` 里列出——**不许记 0**（0 与"没发生"在判读时是两回事）。
+ *   2. **慢请求**：单次请求超过阈值时产出一条 `request.slow`（方法名、耗时、字节数）。
+ *   3. **有界汇总**：一次接入的 `requests / slow / maxMs / p50Ms / p95Ms / top3`，
+ *      用**定长水库**估分位，数组长度不随请求数增长（否则"记日志"本身会变成新的性能问题）。
+ *
+ * 本模块是纯逻辑：它不认识 socket、不认识 journal，事件由上层通过 `onEvent` 注入
+ * （宪法原则 VII.1：能力注入，不在内部读全局状态）。
+ *
+ * 契约：`docs/diagnostics-events.md`
+ * 数据模型：`specs/020-link-diagnostics/data-model.md` §3–§5
+ */
+
+/** 水库样本容量：估 p50/p95 够用，且不随请求数增长。 */
+export const RESERVOIR_SIZE = 256
+/** 每累计这么多请求写一条汇总（加上断开时那条，构成"条数常数级"的上界）。 */
+export const SUMMARY_EVERY = 200
+/** `top3` 保留几条最慢的请求。 */
+export const TOP_SLOWEST = 3
+
+/** 阶段名（对外，出现在 `missing` 里）。 */
+export const PHASES = Object.freeze({
+  helloMs: 'hello',
+  firstRequestMs: 'first-request',
+  firstResponseMs: 'first-response',
+})
+
+/** 握手方法名（与 `hello.js` 同口径；这里只用来区分"握手"与"数据请求"）。 */
+const HELLO_METHOD = '_link/hello'
+
+/** 最近秩分位数：样本少的时候比插值更保守，也更容易在单测里核对。 */
+function percentile(sorted, fraction) {
+  if (sorted.length === 0) return 0
+  const rank = Math.ceil(fraction * sorted.length)
+  return sorted[Math.max(0, Math.min(sorted.length - 1, rank - 1))]
+}
+
+export class DeviceTimeline {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.deviceId]
+   * @param {number} [options.slowRequestMs] 超过它才记 `request.slow`；0 表示关闭该逐条记录
+   * @param {() => number} [options.now]
+   * @param {(kind: string, detail: Record<string, unknown>) => void} [options.onEvent]
+   */
+  constructor({ deviceId, slowRequestMs = 2000, now = Date.now, onEvent = () => {} } = {}) {
+    this.deviceId = deviceId
+    this.slowRequestMs = Number(slowRequestMs) || 0
+    this.now = now
+    this.onEvent = onEvent
+    this.attachedAt = now()
+    this.helloAt = undefined
+    this.firstRequestAt = undefined
+    this.firstResponseAt = undefined
+    this.requests = 0
+    this.slow = 0
+    this.maxMs = 0
+    /** 定长水库：满了以后按步长覆盖（确定性的系统抽样，避免引入随机数让单测发抖）。 */
+    this._samples = []
+    this._sampleCursor = 0
+    /** 最慢的若干条，长度恒 ≤ TOP_SLOWEST。 */
+    this._top = []
+    this._phaseEmitted = false
+  }
+
+  /** 收到 `_link/hello`（只在第一次生效）。 */
+  noteHello(at = this.now()) {
+    if (this.helloAt === undefined) this.helloAt = at
+  }
+
+  /**
+   * 一次请求收尾。
+   *
+   * @param {{method: string, startedAt: number, ms: number, bytes: number}} request
+   */
+  noteRequest({ method, startedAt, ms, bytes }) {
+    const isHello = method === HELLO_METHOD
+    if (isHello) this.noteHello(startedAt)
+    if (!isHello && this.firstRequestAt === undefined) this.firstRequestAt = startedAt
+    // 只认**数据请求**的响应：握手响应不算。否则 `firstResponseMs` 会小于 `firstRequestMs`
+    // （握手先回、数据请求后发），三段的阶梯就读不出来了。
+    if (!isHello && this.firstResponseAt === undefined) this.firstResponseAt = startedAt + ms
+
+    this.requests += 1
+    this.maxMs = Math.max(this.maxMs, ms)
+    this.#sample(ms)
+    this.#keepTop({ method, ms, bytes })
+    if (this.slowRequestMs > 0 && ms > this.slowRequestMs) {
+      this.slow += 1
+      // 字段叫 elapsedMs 而不是 ms：`ms` 是信封上的**时刻**，同名会把时刻冲掉（见 journal.js）。
+      this.onEvent('request.slow', { deviceId: this.deviceId, method, elapsedMs: ms, bytes })
+    }
+    if (this.requests % SUMMARY_EVERY === 0) this.emitSummary()
+    this.#maybeEmitPhase()
+  }
+
+  /** 阶段明细（`missing` 里的阶段名，其 `phases.*Ms` 必为 null）。 */
+  phaseDetail() {
+    const relative = (at) => (at === undefined ? null : at - this.attachedAt)
+    const phases = {
+      helloMs: relative(this.helloAt),
+      firstRequestMs: relative(this.firstRequestAt),
+      firstResponseMs: relative(this.firstResponseAt),
+    }
+    const missing = Object.entries(phases)
+      .filter(([, value]) => value === null)
+      .map(([key]) => PHASES[key])
+    return { deviceId: this.deviceId, phases, missing }
+  }
+
+  /** 汇总明细（分位来自定长水库）。 */
+  summaryDetail() {
+    const sorted = [...this._samples].sort((a, b) => a - b)
+    return {
+      deviceId: this.deviceId,
+      requests: this.requests,
+      slow: this.slow,
+      maxMs: this.maxMs,
+      p50Ms: percentile(sorted, 0.5),
+      p95Ms: percentile(sorted, 0.95),
+      top3: this._top.map((entry) => ({ ...entry })),
+    }
+  }
+
+  /** 断开时调用：补齐阶段事件（若还没写过）并在有请求时才写汇总。 */
+  finish() {
+    if (!this._phaseEmitted) {
+      this._phaseEmitted = true
+      this.onEvent('device.phase', this.phaseDetail())
+    }
+    if (this.requests > 0) this.emitSummary()
+  }
+
+  /** 写一条汇总（供断开与每 `SUMMARY_EVERY` 个请求两个时机调用）。 */
+  emitSummary() {
+    this.onEvent('device.summary', this.summaryDetail())
+  }
+
+  #sample(ms) {
+    if (this._samples.length < RESERVOIR_SIZE) {
+      this._samples.push(ms)
+      return
+    }
+    const index = this._sampleCursor % RESERVOIR_SIZE
+    this._samples[index] = ms
+    this._sampleCursor += 1
+  }
+
+  #keepTop(entry) {
+    this._top.push(entry)
+    this._top.sort((a, b) => b.ms - a.ms)
+    if (this._top.length > TOP_SLOWEST) this._top.length = TOP_SLOWEST
+  }
+
+  #maybeEmitPhase() {
+    if (this._phaseEmitted) return
+    // 三段**全齐**才写；缺哪一段就等 `finish()` 时按 missing 写（读者要知道"没发生"，而不是看到 0）。
+    //
+    // 为什么要求全齐而不是"有数据请求就写"：App 的真实顺序是**先探针（session/list）再握手**
+    // （`ConnectionStore.connect()` 先 `sessions()`，再在 `install()` 里发 `_link/hello`）。
+    // 按旧条件，阶段事件会在探针那一刻写出来、`missing: ['hello']`，于是最有用的
+    // 「attach→hello 用了多久」在事件里永远是空的——2026-10-13 09:28 的中转运行实测到了这一条。
+    if (this.helloAt === undefined) return
+    if (this.firstRequestAt === undefined || this.firstResponseAt === undefined) return
+    this._phaseEmitted = true
+    this.onEvent('device.phase', this.phaseDetail())
+  }
+}

package/lib/dlp.js

@@ -10,7 +10,11 @@
 export const MAX_FRAME_BYTES = 32 * 1024 * 1024
 
 export const DEVICE_TO_AGENT = new Set(['req', 'open', 'cancel', 'eventResult', 'ping', 'hello'])
-export const AGENT_TO_DEVICE = new Set(['res', 'item', 'end', 'streamError', 'event', 'hostStatus', 'pong', 'error'])
+export const AGENT_TO_DEVICE = new Set(['res', 'item', 'end', 'streamError', 'event', 'hostStatus', 'pong', 'error',
+  // 032：账户级状态由**中转自己**发给设备（会话已读水位、提醒开关这类），
+  // 连接器既不产生也不转发它，但这张表是契约镜像，缺一项就与
+  // `docs/relay-contract.json` 对不上（`npm test` 会红）。
+  'accountState'])
 /** Relay-internal control frames carrying device lifecycle (see docs/RELAY-NOTES.md). */
 export const RELAY_CONTROL = new Set(['deviceAttach', 'deviceDetach'])
 /**
@@ -167,6 +171,11 @@ export function pairCodeEndpoint(relayUrl) {
   return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'pair/code')
 }
 
+/** 重新生成配对码（032）：作废旧码、铸一枚新的，不影响已配对设备。 */
+export function pairCodeRegenerateEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'pair/code/regenerate')
+}
+
 /** The relay's self-service enrollment endpoint (`POST /agents/enroll`). */
 export function enrollEndpoint(relayUrl) {
   return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'agents/enroll')

package/lib/hello.js

@@ -11,7 +11,7 @@
  * calling something that would come back as a 404 from the Host.
  */
 
-import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
 
 /** Reserved method the app calls once per connection. */
 export const HELLO_METHOD = '_link/hello'
@@ -22,18 +22,39 @@ export const HELLO_METHOD = '_link/hello'
  * Read from package.json rather than written out twice: the two drifting apart
  * is exactly the kind of thing nobody notices until a support question depends
  * on it (they had drifted: the manifest said 0.1.0 and this said 0.2.0).
+ *
+ * 用 `readFileSync` 而不是 `require('../package.json')`：`require` 会把 JSON 缓存在
+ * CJS 模块表里，而这个文件走热更（模块 URL 带参数重新求值，**缓存表不清**）。实测
+ * 2026-10-17：DSH 进程 10-12 起就一直报 `0.6.0`，而仓库 10-13 已经升到 `0.6.5`——
+ * 报的还是进程启动那天的版本号。读文件没有这层缓存，热更后一问就是真值。
  */
 export const SERVER_VERSION = readManifestVersion()
 
 function readManifestVersion() {
   try {
-    const require = createRequire(import.meta.url)
-    return require('../package.json').version ?? '0.0.0'
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    return typeof manifest.version === 'string' && manifest.version ? manifest.version : '0.0.0'
   } catch {
     return '0.0.0'
   }
 }
 
+/**
+ * 宿主 DSH 的版本，取不到时为 `null`。
+ *
+ * 为什么读环境变量而不是 package.json：连接器跑在宿主进程里，宿主把自己的版本放在
+ * `DSH_CLIENT_VERSION`（桌面版与 `dsh web` 都设）；而连接器是从仓库 / npm 链接进档案的，
+ * 它自己的 `package.json` 里没有宿主的版本，从 `node_modules` 里猜路径又会随打包形态变
+ * （Electron 的 asar 路径 fs 未必读得到）。读不到就如实报 null，不编一个数。
+ *
+ * 用函数而不是常量：热更会重新求值模块，但环境变量在进程生命周期内可能被测试替换；
+ * 每次问都读一次，代价可以忽略。
+ */
+export function hostVersion() {
+  const value = process.env.DSH_CLIENT_VERSION
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
 /**
  * Capabilities the app may rely on.
  *
@@ -62,6 +83,10 @@ export const SERVER_CAPABILITIES = [
   // session-search: it answers `_link/sessionFind` (in-session literal search). The
   // phone switches channels on these and falls back to `session/page` without them.
   'history-window', 'session-search',
+  // session-digest: 连接器答 `_link/sessionDigest`（`session/list` 的精简同形副本，
+  // 去掉 App 侧零读取点的字段、可按要求 gzip）。手机侧按这条能力切换，缺了就回退到
+  // `session/list`——spec 021 只做连接器侧，切换在后续规格。
+  'session-digest',
   // history-role-filter: `_link/sessionWindow` accepts `roles` (e.g. just the
   // "me" role) and returns only matching records; seq cursor semantics are
   // unchanged (spec 009 T031).
@@ -70,6 +95,10 @@ export const SERVER_CAPABILITIES = [
   // scan actually reached — so a caller whose page was filtered empty can still
   // advance instead of asking for the same stretch forever (spec 009 T039).
   'history-scan-boundary',
+  // search-progress: 扫描式搜索的每一页都带 `totalChunks` / `remainingChunks`，
+  // 界面据此从第一页起就能显示「已扫 k/N 片」（026 之后的 App 才读）。
+  'search-progress',
+  'device-subprotocol-auth', 'persistent-pair-code', 'account-state', 'account-state-push',
 ]
 
 export function isHelloMethod(method) {
@@ -107,6 +136,9 @@ export function parseClientInfo(args) {
 export function helloPayload({ protocolVersion, agentId, name } = {}) {
   return {
     serverVersion: SERVER_VERSION,
+    // 宿主 DSH 的版本：手机据此显示「DSH 版本」，中转据此记录这台电脑跑的是哪个宿主。
+    // 老客户端不认识这个键，忽略即可；取不到时是 null（如实表示"不知道"）。
+    hostVersion: hostVersion(),
     capabilities: SERVER_CAPABILITIES,
     protocolVersion,
     agentId: agentId ?? null,