dsh-plugin-mobile-link 0.6.5 → 0.6.6

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/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.
  *
@@ -74,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) {
@@ -111,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,

package/lib/history.js

@@ -46,6 +46,10 @@ export const FIND_METHOD = '_link/sessionFind'
 /// does not read the field keeps the old cursor rule.
 export const HISTORY_CAPABILITIES = [
   'history-window', 'session-search', 'history-role-filter', 'history-scan-boundary',
+  // search-progress: a scanned page also carries `totalChunks` / `remainingChunks`,
+  // so the reader can be told "已扫 k/N 片" from the first page on. Purely additive:
+  // `totalChunks` comes from the log's newest seq, which a scan already fetches.
+  'search-progress',
 ]
 
 export function isHistoryMethod(method) {
@@ -59,7 +63,15 @@ export function isHistoryMethod(method) {
 export const SEARCH_CHUNK = 2000
 export const MAX_SEARCH_CHUNKS_PER_CALL = 4
 export const DEFAULT_SEARCH_LIMIT = 50
-export const MIN_QUERY_LENGTH = 2
+/// 查询下限：**1 个字符**（owner 2026-10-17 决定）。
+///
+/// 原来卡在 2 个字，理由是「一个字几乎命中整段历史、翻不完」。这个代价在 2026-10-17
+/// 变成可接受：搜索有了分页与片数进度（`search-progress`，界面显示「已扫 k/N 片」），
+/// 一页仍只回 50 条、一次调用仍最多扫 4 块（≈1.3 秒），所以下限降到 1。
+///
+/// 仍然拒绝的是**空关键词且没带 roles**：那不是搜索，是一次没有范围的全表扫描
+/// （「浏览我的提问」必须带 roles，见 `browsing`）。
+export const MIN_QUERY_LENGTH = 1
 
 function idOfAddress(address) {
   if (address === null || typeof address !== 'object') return undefined
@@ -86,6 +98,29 @@ function parseRoles(value) {
   return { roles }
 }
 
+/// 一条文档里所有可读正文：宿主给的 `text`、`data.text`、`data.content[].text`
+/// （blocks 形态，可能**不止一段**）、`data.message.content[].text`，以及工具结果的
+/// `output` / `result` / `stdout` / `stderr`。
+///
+/// 为什么自己做匹配、不把 `{kind:'text'}` 交给宿主：宿主的文本过滤只看它自己认定的那一段，
+/// 2026-10-17 真机实测（搜"我"/"的"拿不到全部用户输入）说明会漏掉 `content` 里靠后的部分。
+/// 改成"取回这一段全部文档、在这里逐字匹配"之后，命中集合只由我们自己的规则决定。
+function docText(doc) {
+  const data = doc?.data ?? {}
+  const parts = []
+  const push = (value) => {
+    if (typeof value === 'string' && value.length > 0) parts.push(value)
+  }
+  push(doc?.text)
+  push(data.text)
+  for (const blocks of [data.content, data.message?.content]) {
+    if (!Array.isArray(blocks)) continue
+    for (const block of blocks) push(block?.text)
+  }
+  for (const key of ['output', 'result', 'stdout', 'stderr']) push(data[key])
+  return parts.join('\n')
+}
+
 /// A hit snippet with the highlight offsets the phone's list already renders.
 ///
 /// Offsets, not ranges: the value crosses the wire and a character offset stays
@@ -217,7 +252,8 @@ export function createHistoryService({ logger = console } = {}) {
     // 这时不按文本过滤，只按 seq 段扫，按角色筛。
     const browsing = query.length === 0 && roles !== undefined
     if (!browsing && query.length < MIN_QUERY_LENGTH) {
-      return failure('link/query-too-short', `query must be at least ${MIN_QUERY_LENGTH} characters`)
+      return failure('link/query-too-short',
+        `query must be at least ${MIN_QUERY_LENGTH} character (or pass roles to browse)`)
     }
     const limit = Number.isSafeInteger(Number(args.limit)) && Number(args.limit) > 0
       ? Math.min(Number(args.limit), 200) : DEFAULT_SEARCH_LIMIT
@@ -261,15 +297,25 @@ export function createHistoryService({ logger = console } = {}) {
           logger.info?.(`mobile-link: full-text index unavailable, scanning instead: ${messageOf(error)}`)
         }
       }
+      const needle = query.toLowerCase()
       const from = parseSearchCursor(args.cursor)
-      const ceiling = from !== undefined ? from : await newestSeq(sessionId)
+      // `newestSeq` also carries the progress denominator below; it is cached for
+      // 5s, and a scan would have fetched it anyway on the first page.
+      const newest = await newestSeq(sessionId)
+      // 游标是上一页留下的 seq，可能**越过**当前最新（日志被裁剪过、或手机拿着旧游标回来）。
+      // 越界时不夹住的话，扫描会从一个不存在的 seq 往下空跑满 4 块，`remainingChunks`
+      // 还会算出比 `totalChunks` 更大的数（实测 996/2），界面的"已扫 k/N"随即变成假的。
+      const cursorSeq = from !== undefined && newest >= 0 ? Math.min(from, newest) : from
+      const ceiling = cursorSeq !== undefined ? cursorSeq : newest
+      // 片数（进度的分母）：由日志最新 seq 算出，与游标无关，所以第一页就是精确的。
+      const total = newest >= 0 ? Math.floor(newest / chunk) + 1 : 0
       const hits = []
       let to = ceiling
       let scanned = 0
       while (to >= 0 && hits.length < limit && scanned < MAX_SEARCH_CHUNKS_PER_CALL) {
         const chunkFrom = Math.max(0, to - chunk + 1)
+        // 只按 seq 段取文档；正文匹配在下面自己做（见 `docText` 的头注）。
         const filters = [{ kind: 'seq', from: chunkFrom, to }]
-        if (!browsing) filters.push({ kind: 'text', text: query })
         const docs = await withTimeout(
           sessionQuery.filterEvents(sessionId, filters),
           HOST_CALL_TIMEOUT_MS,
@@ -278,6 +324,12 @@ export function createHistoryService({ logger = console } = {}) {
         scanned += 1
         // Newest first inside the chunk: the reader asked about something recent
         // far more often than about something old.
+        //
+        // **游标必须落在"这一页读到哪儿"**，不能一律跳到整块之前：一页在块中途装满时，
+        // 块尾还没读过的文档会被永久跳过——2026-10-17 owner 报的"全局搜索不是用户提问的超集"
+        // 就是这条（用户提问正好落在片尾时被吞掉；索引路径不受影响）。
+        // `resumeFrom` 默认 = 整块之前（读完这块才成立），中途停下时改成"下一条还没读的 seq"。
+        let resumeFrom = chunkFrom - 1
         for (let index = docs.length - 1; index >= 0; index -= 1) {
           const doc = docs[index]
           // **已知局限**：这里只能按文档判角色，而宿主的 `filterEvents` 文档不带 `data.source`，
@@ -291,13 +343,20 @@ export function createHistoryService({ logger = console } = {}) {
           if (roles !== undefined && (role === undefined || !roles.has(role))) continue
           const display = displayRoleOf(doc)
           if (display === undefined) continue
+          const text = docText(doc)
+          if (!browsing && !text.toLowerCase().includes(needle)) continue
           hits.push({ seq: doc.seq, role: display, ...(query.length > 0
-            ? makeSnippet(doc.text, query)
-            : { snippet: String(doc.text ?? '').slice(0, 72).replace(/\s+/g, ' ').trim(),
+            ? makeSnippet(text, query)
+            : { snippet: String(text).slice(0, 72).replace(/\s+/g, ' ').trim(),
                 highlightStart: 0, highlightLength: 0 }) })
-          if (hits.length >= limit) break
+          if (hits.length >= limit) {
+            // 装满了：这一条已经收进本页，下一页从它的**前一条**继续——不能从整块之前
+            // （会丢块尾），也不能从这一条本身（会重复）。
+            resumeFrom = doc.seq - 1
+            break
+          }
         }
-        to = chunkFrom - 1
+        to = resumeFrom
       }
       const hasMore = to >= 0 && hits.length >= limit ? true : to >= 0
       return {
@@ -307,6 +366,12 @@ export function createHistoryService({ logger = console } = {}) {
           cursor: hasMore ? String(to) : null,
           hasMore,
           scannedChunks: scanned,
+          // 进度：片数是**扫描单位**（一段 `chunk` 个 seq，从新往旧），不是命中页数。
+          // `totalChunks` 由日志最新 seq 算出，所以从第一页起就是精确的；命中的**条数**
+          // 仍然要扫到最早那一片才定稿（不开宿主全文索引的必然结果）。
+          totalChunks: total,
+          // 剩余片数不可能多于总片数：越界游标、被裁剪的日志都不该让进度超过 100%。
+          remainingChunks: to >= 0 ? Math.min(Math.floor(to / chunk) + 1, total) : 0,
           source: 'scan',
         },
       }

package/lib/link.js

@@ -22,12 +22,12 @@ import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
 import { LinkJournal, defaultJournalPath } from './journal.js'
 import { statusSnapshot } from './status.js'
-import { mintPairCode } from './pairing.js'
+import { mintPairCode, regeneratePairCode } from './pairing.js'
 import {
   DEFAULT_EVENTS_BACKLOG, DEFAULT_SLOW_REQUEST_MS,
   EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
 } from './router.js'
-import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
+import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
 import { MissingIdentity, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
@@ -420,6 +420,10 @@ export class MobileLinkAgent extends EventEmitter {
       agentId: identity.agentId,
       attempt: this.reconnectAttempts,
       sinceCloseMs: this._lastClosedAt === undefined ? undefined : this.now() - this._lastClosedAt,
+      // 这次连接属于哪套版本：连接器 + 宿主 DSH。一连接一行，事后从本机流水就能
+      // 认出"出问题的那天跑的是哪两个版本"，不必再去翻安装记录。
+      serverVersion: SERVER_VERSION,
+      hostVersion: hostVersion(),
     })
     this.emit('status')
 
@@ -606,6 +610,10 @@ export class MobileLinkAgent extends EventEmitter {
         name: this.identity?.agentName || undefined,
         dshPort: this.dsh?.endpoint?.port,
         protocol: PROTOCOL_VERSION,
+        // 这台电脑的两段版本。中转据此按 agent 记一行（变化才写），手机据此
+        // 在「关于」里显示 DSH 版本——只在控制帧上走一次，不进任何业务流。
+        version: SERVER_VERSION,
+        hostVersion: hostVersion(),
       },
     })
   }
@@ -653,12 +661,22 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── relay-side helpers ──────────────────────────────────────────────────
 
-  /** Ask the relay to mint a pairing code for this agent (relay NOTES.md §2). */
-  async mintPairCode({ ttlMs = 10 * 60 * 1000, fetchImpl = fetch } = {}) {
+  /**
+   * Ask the relay to mint a pairing code for this agent (relay NOTES.md §2).
+   *
+   * 032：默认持久（`ttlMs: null`）；传秒数得到限时码。
+   */
+  async mintPairCode({ ttlMs = null, fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
     return mintPairCode({ identity, ttlMs, fetchImpl })
   }
 
+  /** 用户点「重新生成」：作废旧码、铸新的，**不碰已配对设备**（032）。 */
+  async regeneratePairCode({ fetchImpl = fetch } = {}) {
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    return regeneratePairCode({ identity, fetchImpl })
+  }
+
   /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */
   status() {
     return statusSnapshot(this)

package/lib/pairing.js

@@ -1,25 +1,34 @@
 /**
- * Pairing helper: ask the relay to mint a one-time code and build the QR
- * payload the desktop shows. Spec §2.1 plus docs/RELAY-NOTES.md §2 (the endpoint the
- * spec's table is missing).
+ * Pairing helper: ask the relay to mint a pairing code and build the QR payload
+ * the desktop shows. Spec §2.1 plus docs/RELAY-NOTES.md §2 (the endpoint the spec's
+ * table is missing).
+ *
+ * 032：默认铸**持久码**（不过期，直到用户点「重新生成」）。传 `ttlMs` 仍然得到一张
+ * 限时码——那是老行为，留给还用它的调用方与老测试。
  */
 
-import { pairCodeEndpoint, qrPayload } from './dlp.js'
+import { pairCodeEndpoint, pairCodeRegenerateEndpoint, qrPayload } from './dlp.js'
 
 /**
  * @param {object} options
  * @param {{agentId: string, agentSecret: string, relayUrl: string}} options.identity
- * @param {number} [options.ttlMs] requested lifetime (the relay caps it at 1 hour)
+ * @param {number|null} [options.ttlMs] requested lifetime; `null`/省略 = 持久码
  * @param {typeof fetch} [options.fetchImpl] injectable for tests
  */
-export async function mintPairCode({ identity, ttlMs = 10 * 60 * 1000, fetchImpl = fetch }) {
+export async function mintPairCode({ identity, ttlMs = null, fetchImpl = fetch }) {
+  // 032：**持久码那条路不能把 `ttlMs` 放进请求体**。中转的判据是 `"ttlMs" not in body`
+  // （`relay/api.py` 的 `pair_code`）：带一个 `ttlMs: null` 会被读成"限时、但没给时长"，
+  // 于是落到中转的默认 10 分钟——面板显示倒计时，码十分钟后就废（用户看到的就是这个）。
+  const payload = ttlMs == null
+    ? { agentId: identity.agentId }
+    : { agentId: identity.agentId, ttlMs }
   const response = await fetchImpl(pairCodeEndpoint(identity.relayUrl), {
     method: 'POST',
     headers: {
       'content-type': 'application/json',
       authorization: `Bearer ${identity.agentSecret}`,
     },
-    body: JSON.stringify({ agentId: identity.agentId, ttlMs }),
+    body: JSON.stringify(payload),
   })
   let body
   try {
@@ -32,8 +41,50 @@ export async function mintPairCode({ identity, ttlMs = 10 * 60 * 1000, fetchImpl
   }
   return {
     code: body.code,
-    expiresAt: body.expiresAt,
-    ttlMs: body.ttlMs ?? ttlMs,
+    expiresAt: body.expiresAt ?? null,
+    ttlMs: body.ttlMs ?? ttlMs ?? null,
+    persistent: body.persistent === true || body.expiresAt == null,
+    // 「已配对 N/8」以中转的库为准：连接器只知道自己这次见过的设备。
+    maxPairedDevices: Number(body.maxPairedDevices ?? 0) || null,
+    pairedDevices: Number(body.pairedDevices ?? 0),
+    relayUrl: identity.relayUrl,
+    agentId: identity.agentId,
+    qrPayload: qrPayload({ relay: identity.relayUrl, code: body.code }),
+  }
+}
+
+/**
+ * 用户点「重新生成」：让中转作废旧码、铸一枚新的。
+ *
+ * **不碰已配对的设备**（032 FR-002）：那台手机/浏览器靠自己的 deviceToken 活着，
+ * 换码只影响"还没来配的人"。所以这个动作可以放心点，不需要提醒"会把手机踢下线"。
+ */
+export async function regeneratePairCode({ identity, fetchImpl = fetch }) {
+  const response = await fetchImpl(pairCodeRegenerateEndpoint(identity.relayUrl), {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${identity.agentSecret}`,
+    },
+    body: JSON.stringify({ agentId: identity.agentId }),
+  })
+  let body
+  try {
+    body = await response.json()
+  } catch {
+    throw new Error(`relay returned HTTP ${response.status} for /pair/code/regenerate`)
+  }
+  if (!response.ok || body?.ok !== true) {
+    throw new Error(body?.error?.message ?? `relay refused the regeneration (HTTP ${response.status})`)
+  }
+  return {
+    code: body.code,
+    expiresAt: null,
+    ttlMs: null,
+    persistent: true,
+    revoked: Number(body.revoked ?? 0),
+    maxPairedDevices: Number(body.maxPairedDevices ?? 0) || null,
+    pairedDevices: Number(body.pairedDevices ?? 0),
     relayUrl: identity.relayUrl,
     agentId: identity.agentId,
     qrPayload: qrPayload({ relay: identity.relayUrl, code: body.code }),

package/lib/routes.js

@@ -94,6 +94,7 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
   const guard = makeGuard(ctx, logger)
   const STATUS_ROUTE = '/mobile-link/status'
   const PAIR_ROUTE = '/mobile-link/pair-code'
+  const REGENERATE_ROUTE = '/mobile-link/pair-code/regenerate'
   const disposers = []
 
   disposers.push(ctx.webServer.register({
@@ -131,10 +132,14 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
         sendJson(res, 400, { ok: false, message: 'invalid JSON body' })
         return
       }
-      const ttlMs = ttlFrom(body.ttlMs, Number(config.pairTtlMs) || 10 * 60 * 1000)
+      // 032：调用方**没提** ttlMs 就要一张持久码（面板走这条路）；显式给了才限时，
+      // 那是老行为，留给还在用的调用方。
+      const wantsTtl = Object.prototype.hasOwnProperty.call(body, 'ttlMs')
+      const ttlMs = wantsTtl ? ttlFrom(body.ttlMs, Number(config.pairTtlMs) || 10 * 60 * 1000) : null
       try {
         const minted = await agent.mintPairCode({ ttlMs })
-        logger.info?.(`mobile-link: minted a pairing code for ${minted.agentId}`)
+        logger.info?.(`mobile-link: minted a ${minted.persistent ? 'persistent' : 'time-limited'}`
+          + ` pairing code for ${minted.agentId}`)
         // 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
@@ -148,5 +153,32 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
     },
   }))
 
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: REGENERATE_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, message: 'invalid JSON body' })
+        return
+      }
+      try {
+        const minted = await agent.regeneratePairCode()
+        logger.info?.(`mobile-link: regenerated the pairing code for ${minted.agentId}`
+          + ` (revoked ${minted.revoked})`)
+        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 disposers
 }

package/lib/status.js

@@ -6,7 +6,7 @@
  * 函数只读 agent 的字段，不持有状态，因此可以直接被单测调用。
  */
 
-import { SERVER_CAPABILITIES, SERVER_VERSION } from './hello.js'
+import { SERVER_CAPABILITIES, SERVER_VERSION, hostVersion } from './hello.js'
 
 const PROTOCOL_VERSION = 1
 
@@ -93,6 +93,9 @@ export function statusSnapshot(agent) {
     // Same facts as `_link/hello`, which is the channel the app actually uses:
     // this route only exists on the direct path.
     serverVersion: SERVER_VERSION,
+    // 宿主 DSH 的版本（`null` = 这个宿主没把版本放进环境）。与 `serverVersion`
+    // 是两个命名空间：前者是连接器，后者是跑它的 DSH。
+    hostVersion: hostVersion(),
     capabilities: SERVER_CAPABILITIES,
     enroll: {
       // A phone (or the user's browser) can read this to find out that the

package/package.json

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