dsh-plugin-mobile-link 0.6.5 → 0.7.0

package/README.md

@@ -80,7 +80,7 @@ dsh plugin --profile web add ./plugins/mobile-link
    dsh-mobile-link enroll --invite <邀请码> --relay wss://<你的站点>/dsh-link
    ```
 
-   …or register it on the relay host with `relay/admin.py agent-register
+   …or register it on the relay host with `dsh-relay admin agent-register
    --write-config ~/.dsh/mobile-link/agent.json`.
 
 2. Mint a pairing code, and show it as a QR the phone camera can read:

package/cordis.patch.yml

@@ -32,6 +32,12 @@
 #                  (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.
+#   logs           false refuses the phone's runtime logs (`_link/logs`) with
+#                  `logs/disabled`; the phone keeps them in its own ring and retries.
+#   logsFile       log spool root (default ~/.dsh/mobile-link/logs). One directory
+#                  per device, one JSONL per local day, pruned to the last 7 days
+#                  in the write path itself — there is no timer or background job
+#                  to keep alive. Read it with `node scripts/dev/ios-logs.mjs`.
 #   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/dir-listing.js

@@ -0,0 +1,167 @@
+/**
+ * `_link/dirListing`：`workspaceFiles/list` 的同形增强副本，本机补 `mtimeMs`。
+ *
+ * 为什么要它：宿主 `workspaceFiles/list` 的条目只有 `name/type/size?`（宿主类型见
+ * `@deepseek-ai/dsh-api-workspace-files` 的 `WorkspaceDirectoryEntry`），
+ * 没有任何时间字段；`workspaceFiles/stat` 的 `version` 是 opaque token（类型注释明确
+ * "never parsed"），推不出时间。用户要的是"哪个文件最近被动过"，所以由电脑侧补。
+ *
+ * 三条纪律（与 `session-digest.js` 同款）：
+ *   1. **清单的所有者仍是宿主**：连接器只往条目上加一个字段，不删、不改、不重排；
+ *      宿主报错时错误信封逐字透传。
+ *   2. **拿不到就原样返回**：root 缺失/相对/越界、单条目 stat 失败、超出总预算——
+ *      一律退回未增强的原始清单。装饰永不弄坏清单，目录本身一定能打开。
+ *   3. **不提速、不重试**：一个条目最多 stat 一次；没有缓存（mtime 会变，缓存就要失效
+ *      逻辑，而列目录本来就是低频动作）。
+ *
+ * 符号链接用 `fs.stat`（跟随链接）报**目标**的时间——宿主列的 `type`/`size` 本来就是
+ * 按目标解析的（类型注释："A symlink reports the type of its destination"），
+ * `lstat` 报的链接自身时间只在重指时变化，回答不了"内容什么时候改的"。
+ */
+
+import { stat } from 'node:fs/promises'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+/** 方法名（设备发起；`_link/` 前缀 = 连接器自答，永不转发宿主）。 */
+export const DIR_LISTING_METHOD = '_link/dirListing'
+
+/** 宿主的清单方法：连接器只读它，不改它。 */
+const HOST_LIST_METHOD = 'workspaceFiles/list'
+
+/** 可调的上限。`statBudgetMs` 是全部条目补时间的总预算（见 §2.2 失败语义表）。 */
+export const LIMITS = Object.freeze({
+  statBudgetMs: 2000,
+})
+
+export function isDirListingMethod(method) {
+  return method === DIR_LISTING_METHOD
+}
+
+/**
+ * 给一份宿主目录清单补上 `mtimeMs`。
+ *
+ * 认两种输入形状（与 `digestSessionList` 同款）：宿主信封 `{ ok, value: { entries } }`
+ * 以及直接给的 `{ entries }`。**返回的始终是同形状的值**，调用方不必再猜信封在哪一层。
+ * 结构不是预期的样子就原样返回入参——装饰不许把"看不懂"变成"改掉"。
+ *
+ * @param {object} options
+ * @param {{ rpc: (method: string, args: object) => Promise<unknown> }} options.dsh 宿主 RPC
+ * @param {object} options.args 设备发来的参数（`workspaceFileScopeId` / `path` / `root`）
+ * @param {{ debug?: (message: string) => void, warn?: (message: string) => void }} [options.logger]
+ * @param {(path: string) => Promise<{ mtimeMs: number }>} [options.statImpl] 可注入，供单测
+ * @param {number} [options.budgetMs] 总预算，缺省 `LIMITS.statBudgetMs`
+ * @returns {Promise<unknown>} 增强后的同形值；降级时是原始值
+ */
+export async function dirListing({ dsh, args, logger, statImpl = stat, budgetMs = LIMITS.statBudgetMs }) {
+  const request = args ?? {}
+  const result = await dsh.rpc(HOST_LIST_METHOD, {
+    workspaceFileScopeId: request.workspaceFileScopeId,
+    path: typeof request.path === 'string' ? request.path : '.',
+  })
+
+  const entries = listingEntries(result)
+  if (entries === null) {
+    logger?.debug?.('dir-listing: host answered a shape this connector does not decorate')
+    return result
+  }
+
+  const directory = resolveDirectory(request.root, entries.path)
+  if (directory === null) {
+    // root 缺失 / 非绝对 / 宿主回的 path 越出 root：不是错误，只是补不了时间。
+    logger?.debug?.(`dir-listing: cannot resolve the listed directory from root ${JSON.stringify(request.root)}`)
+    return result
+  }
+
+  const decorated = await withBudget(
+    Promise.all(entries.items.map((entry) => decorate(entry, directory, statImpl))),
+    budgetMs
+  )
+  if (decorated === null) {
+    logger?.warn?.(`dir-listing: stat budget of ${budgetMs}ms ran out, answering the plain listing`)
+    return result
+  }
+  return replaceEntries(result, decorated)
+}
+
+/**
+ * 取出清单本体（`{ entries: [...], path }`），形状不对时返回 null。
+ *
+ * 信封可能是 `result` 本身，也可能是 `result.value`——按"哪一层有 entries 数组"判定，
+ * 与 `digestSessionList` 同一读法。
+ */
+function listingEntries(result) {
+  if (result === null || typeof result !== 'object') return null
+  if (result.ok !== true) return null
+  const container = Array.isArray(result.entries) ? result : result.value
+  if (container === null || typeof container !== 'object' || !Array.isArray(container.entries)) return null
+  return { path: container.path, items: container.entries }
+}
+
+/** 按原形状放回增强后的条目数组。 */
+function replaceEntries(result, items) {
+  if (Array.isArray(result.entries)) return { ...result, entries: items }
+  return { ...result, value: { ...result.value, entries: items } }
+}
+
+/**
+ * 宿主回的 `path` 词法解析成绝对目录；解析不了（要求降级）时返回 null。
+ *
+ * - `path` 可以是相对的（`""` 表根、`"docs"`）也可以是绝对的（App/宿主都有先例）。
+ * - 结果必须位于 root 之内：`resolved === root || resolved.startsWith(root + sep)`。
+ *   只比 `startsWith(root)` 会把 `/a/b-sibling` 当成 `/a/b` 的子路径。
+ * - **不做 realpath 越界拦截**（设计 §2.2 决策 1）：符号链接的目标可以合法地在工作区
+ *   之外，宿主今天已经按目标报 `type`/`size`，这里保持同一语义。
+ */
+function resolveDirectory(root, echoedPath) {
+  if (typeof root !== 'string' || !isAbsolute(root)) return null
+  const base = resolve(root)
+  const echoed = typeof echoedPath === 'string' ? echoedPath : ''
+  const resolved = isAbsolute(echoed) ? resolve(echoed) : resolve(base, echoed)
+  if (resolved !== base && !resolved.startsWith(base + sep)) return null
+  return resolved
+}
+
+/**
+ * 一条条目：stat 成功且时间可用就加 `mtimeMs`，其余情况原样返回。
+ *
+ * 条目名逐段校验：含 `/`、`\` 或等于 `.` / `..` 的名字直接跳过（宿主契约说是 basename，
+ * 这里是纵深防御，防的是异常回包，不是防用户）。跳过的意思是"不给它补时间"，
+ * **不是把条目从清单里删掉**——清单的所有者是宿主。
+ */
+async function decorate(entry, directory, statImpl) {
+  if (entry === null || typeof entry !== 'object') return entry
+  if (typeof entry.name !== 'string' || !isPlainName(entry.name)) return entry
+  try {
+    const info = await statImpl(resolve(directory, entry.name))
+    const mtimeMs = info?.mtimeMs
+    if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs)) return entry
+    const rounded = Math.round(mtimeMs)
+    if (!Number.isFinite(rounded)) return entry
+    return { ...entry, mtimeMs: rounded }
+  } catch {
+    // 断链、权限、竞态删除：这个条目没有时间，其余条目照旧。
+    return entry
+  }
+}
+
+function isPlainName(name) {
+  return name.length > 0 && name !== '.' && name !== '..' && !name.includes('/') && !name.includes('\\')
+}
+
+/**
+ * 给整批 stat 一个总预算。超时返回 `null`（调用方据此降级），
+ * **不取消**后台的 stat——它们会自然收尾，取消反而要给每条挂一个 signal。
+ */
+async function withBudget(work, budgetMs) {
+  if (!(budgetMs > 0)) return await work
+  let timer
+  const expiry = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), budgetMs)
+  })
+  try {
+    const outcome = await Promise.race([work, expiry])
+    return outcome === null ? null : outcome
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/lib/dlp.js

@@ -6,11 +6,17 @@
  * Wire contract: docs/RELAY-PROTOCOL.md §3.
  */
 
+import { repairLoneSurrogatesWithCount } from './unicode.js'
+
 /** Frame ceiling aligned with DSH's image-attachment limit (spec §5). */
 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'])
 /**
@@ -36,8 +42,23 @@ export const RELAY_TO_AGENT_CONTROL = new Set(['fsGetCancel'])
 
 const ID_FRAMES = new Set(['req', 'open', 'cancel', 'res', 'item', 'end', 'streamError', 'eventResult'])
 
+/**
+ * 出站帧的唯一序列化出口。
+ *
+ * 为什么要过一遍代理项修复：宿主会给我们**截断过**的预览（`turnOutline` 的
+ * prompt/response 截到 50/120 个码元），截断点落在 emoji 中间时字符串里就有
+ * 落单代理项，`JSON.stringify` 会忠实写成 `"\ud83d…"`。中转能把它修回 U+FFFD，
+ * 但解码方（iOS `JSONDecoder`）遇到这种转义会整条拒绝，所以生产端先把帧修好。
+ */
 export function encodeFrame(frame) {
-  return JSON.stringify(frame)
+  return encodeFrameChecked(frame).text
+}
+
+/** `encodeFrame` 的带诊断版本：`repaired` 是这条帧里修掉的落单代理项条数。 */
+export function encodeFrameChecked(frame) {
+  const raw = JSON.stringify(frame)
+  const { text, repaired } = repairLoneSurrogatesWithCount(raw)
+  return { text, repaired }
 }
 
 /**
@@ -167,6 +188,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/enroll.js

@@ -2,11 +2,11 @@
  * First-run enrollment: turn an invite code into a durable agent identity.
  *
  * Until now an identity could only be provisioned by whoever owns the relay
- * (`relay/admin.py agent-register --write-config`). That does not distribute:
+ * (`dsh-relay admin agent-register --write-config`). That does not distribute:
  * somebody else installs DSH plus this connector on their own computer and has
  * to be handed a credential by the operator, out of band.
  *
- * So the relay grew `POST /agents/enroll` (relay/api.py), which redeems a
+ * So the relay grew `POST /agents/enroll` (relay-go/internal/httpapi), which redeems a
  * one-time invite code for a fresh `agentId` / `agentSecret`. This module is the
  * connector half: one call, then the identity is written to the same
  * `~/.dsh/mobile-link/agent.json` (mode 0600) that `agent-register` writes, so