dsh-plugin-mobile-link 0.6.6 → 0.8.0

package/lib/history/session-snapshot.js

@@ -41,39 +41,90 @@ export function createSnapshotCache({
 } = {}) {
   const entries = new Map()
 
+  /// 同一会话的并发读只打一次宿主（预热与首屏可能同时到）。
+  const loading = new Map()
+
+  function fresh(sessionId) {
+    const cached = entries.get(sessionId)
+    if (cached === undefined || now() - cached.at >= ttlMs) return undefined
+    // LRU：命中后挪到队尾。
+    entries.delete(sessionId)
+    entries.set(sessionId, cached)
+    return cached
+  }
+
+  async function load(sessionId) {
+    if (typeof readSession !== 'function') return undefined
+    let snapshot
+    try {
+      snapshot = await readSession(sessionId)
+    } catch {
+      return undefined
+    }
+    const events = snapshot?.events
+    if (!Array.isArray(events) || events.length > maxEvents) return undefined
+    const entry = {
+      events,
+      newestSeq: events.length > 0 ? events[events.length - 1].seq : -1,
+      at: now(),
+    }
+    entries.set(sessionId, entry)
+    while (entries.size > maxEntries) entries.delete(entries.keys().next().value)
+    return entry
+  }
+
   return {
     /** 命中且新鲜就返回；否则读一次；读不到/超限/形状不对一律 undefined。 */
     async get(sessionId) {
-      const cached = entries.get(sessionId)
-      if (cached !== undefined && now() - cached.at < ttlMs) {
-        // LRU：命中后挪到队尾。
-        entries.delete(sessionId)
-        entries.set(sessionId, cached)
-        return cached
-      }
-      if (typeof readSession !== 'function') return undefined
-      let snapshot
-      try {
-        snapshot = await readSession(sessionId)
-      } catch {
-        return undefined
-      }
-      const events = snapshot?.events
-      if (!Array.isArray(events) || events.length > maxEvents) return undefined
-      const entry = {
-        events,
-        newestSeq: events.length > 0 ? events[events.length - 1].seq : -1,
-        at: now(),
-      }
-      entries.set(sessionId, entry)
-      while (entries.size > maxEntries) entries.delete(entries.keys().next().value)
-      return entry
+      const cached = fresh(sessionId)
+      if (cached !== undefined) return cached
+      const pending = loading.get(sessionId)
+      if (pending !== undefined) return pending
+      const task = load(sessionId).finally(() => loading.delete(sessionId))
+      loading.set(sessionId, task)
+      return task
+    },
+    /** 只看缓存，不读宿主（浏览翻页第一次请求用它，避免首屏多付一次整份读）。 */
+    peek(sessionId) { return fresh(sessionId) },
+    /** 后台预热：不阻塞当前请求，下一次翻页就能命中。 */
+    warm(sessionId) {
+      if (fresh(sessionId) !== undefined) return
+      if (loading.has(sessionId)) return
+      void this.get(sessionId)
     },
     invalidate(sessionId) { entries.delete(sessionId) },
     get size() { return entries.size },
   }
 }
 
+/**
+ * 快照上的「再往旧读一批」读取器（概要 v2 用）：`(cursor) => {events, floorSeq, exhausted, clamped}`。
+ *
+ * 与 `scanSnapshot` 的区别只在职责：`scanSnapshot` 是"过滤 + 交给 `pageFrom` 裁一页"，
+ * 这里只回答"seq ≤ cursor 的原始事件有哪些"，因为概要 v2 的分页单位是**整轮**，
+ * 裁剪由 `summary-window.js` 按轮做。事件已经在内存里，所以这一层是同步的。
+ */
+export function snapshotOlderReader(snapshot) {
+  const events = Array.isArray(snapshot?.events) ? snapshot.events : []
+  const newest = Number.isInteger(snapshot?.newestSeq) ? snapshot.newestSeq : -1
+  return (cursor) => {
+    const batch = []
+    for (const event of events) {
+      if (!Number.isInteger(event?.seq)) continue
+      if (event.seq > cursor) break
+      batch.push(event)
+    }
+    const floorSeq = batch.length > 0 ? batch[0].seq : 0
+    return {
+      events: batch,
+      floorSeq,
+      // 日志被裁剪过时第一条的 seq 可能不是 0；下一次读到空批就自然收敛（见调用方）。
+      exhausted: floorSeq === 0,
+      clamped: cursor > newest,
+    }
+  }
+}
+
 /**
  * 从快照扫一页。**纯函数**，返回形状与 `scanOlder` / `filteredScan` 完全一致，
  * 于是裁剪与分页仍然由 `pageFrom` 一处决定。

package/lib/history/summary-window.js

@@ -0,0 +1,168 @@
+/**
+ * 概要 v2 的**整轮切页**（能力 `history-fold-summary-v2`）。
+ *
+ * 规格（`maintainers/设计/20261025-过程折叠-对齐桌面.md` §3.4 第 5 条）：
+ * 窗口**从轮次边界开始、到轮次边界结束**；一页装不下整轮就少给轮次，不能给半轮。
+ * 这样手机侧不再出现"记录不完整"与"连续孤立摘要"两种 UI（设计 §5 G9）。
+ *
+ * 唯一的 IO 是调用方给的 `readOlder(cursor)`，返回 `seq ≤ cursor` 的原始事件
+ * （升序）+ `floorSeq` / `exhausted` / `clamped`。两个实现（会话快照 / 分块回读）
+ * 形状相同，所以这里可以纯逻辑地单测。
+ *
+ * 三条不变量，任何改动都不许破坏：
+ * 1. **绝不下发半轮**：一轮的事件没读全（到了调用上限或时间预算）就整轮丢掉；
+ *    连最新一轮都读不全时回可重试错误，而不是给一段残缺的过程。
+ * 2. **至少给一轮**：`limit` 比一轮投影后的记录数还小也照给这一轮——否则翻页会卡在
+ *    同一处永远前进不了（客户端按 `startSeq` 当游标）。
+ * 3. **游标落在轮次边界**：`startSeq` 永远是某个 `turn/start`（或日志真正的起点），
+ *    下一次请求 `before = startSeq` 正好落在上一轮的 `turn/end` 之后。
+ */
+
+import { projectTurnUnit } from './fold-summary.js'
+
+/// 一次调用最多回读多少批原始事件。分块路径一批 51 条（宿主 `readEvent` 的上限），
+/// 64 批 ≈ 3264 条 ≈ 1.5–2 s；快照路径一批就是整份日志，用不到这个数。
+export const SUMMARY_MAX_BATCHES = 64
+/// 一次调用最多花多久在"往回读"上（毫秒）。到点即按"没读全"处理，绝不下发半轮。
+export const SUMMARY_DEADLINE_MS = 6000
+/// 一页最多塞多少轮。防"预算设得极大 + 会话极长"时把一页做成整份日志。
+export const SUMMARY_MAX_UNITS = 200
+
+const EMPTY_PAGE = {
+  records: [], summaries: [], startSeq: null, endSeq: null,
+  hasMore: false, truncatedBy: null, clamped: false,
+}
+
+/**
+ * 从 `upper` 往回按整轮取一页。
+ *
+ * @param {object} input
+ * @param {(cursor: number) => ({events?: Array<object>, floorSeq?: number, exhausted?: boolean, clamped?: boolean})
+ *   | Promise<object>} input.readOlder 往回读一批（`seq ≤ cursor`）
+ * @param {number} input.upper 本页最新一条的 seq（含）
+ * @param {number} input.limit 本页最多几**轮**（本模式的页单位是轮；普通窗口里它是记录条数）
+ * @param {number} input.maxBytes 字节预算（按**投影后**的下发记录算）
+ * @param {boolean} [input.clamped] 调用方已经把上界夹到日志最新（越界请求）
+ * @param {number} [input.maxBatches] 回读批数上限
+ * @param {number} [input.deadlineMs] 回读时间上限
+ * @param {() => number} [input.now] 时钟（测试用）
+ * @returns {Promise<object>} 页；`{error:{code,message}}` 表示这一页取不出来
+ */
+export async function readSummaryPage({
+  readOlder,
+  upper,
+  limit,
+  maxBytes,
+  clamped: upperClamped = false,
+  maxBatches = SUMMARY_MAX_BATCHES,
+  deadlineMs = SUMMARY_DEADLINE_MS,
+  now = Date.now,
+}) {
+  if (!Number.isInteger(upper) || upper < 0) return { ...EMPTY_PAGE }
+  const startedAt = now()
+  const stack = []
+  let nextRead = upper
+  let exhausted = false
+  let capped = false
+  let clamped = upperClamped === true
+  let batches = 0
+
+  const budgetSpent = () => batches >= maxBatches || now() - startedAt >= deadlineMs
+
+  async function fill() {
+    if (stack.length > 0 || exhausted) return
+    if (budgetSpent()) { capped = true; return }
+    const batch = await readOlder(nextRead)
+    batches += 1
+    if (batch?.clamped === true) clamped = true
+    const events = Array.isArray(batch?.events) ? batch.events : []
+    for (const event of events) {
+      if (!Number.isInteger(event?.seq) || event.seq > nextRead) continue
+      stack.push(event)
+    }
+    const floorSeq = Number.isInteger(batch?.floorSeq)
+      ? batch.floorSeq
+      : (events[0]?.seq ?? 0)
+    if (batch?.exhausted === true || floorSeq <= 0 || events.length === 0) exhausted = true
+    nextRead = Math.min(nextRead, floorSeq) - 1
+  }
+
+  /// 读一轮：往回读到 `turn/start`（含）为止。`complete` 为假表示没读全（上限/没数据），
+  /// 调用方必须整轮丢掉。
+  async function readUnit() {
+    const events = []
+    while (true) {
+      await fill()
+      if (stack.length === 0) return { events: events.reverse(), complete: exhausted }
+      const event = stack.pop()
+      events.push(event)
+      if (event.type === 'turn/start') return { events: events.reverse(), complete: true }
+    }
+  }
+
+  const kept = []
+  let byteCount = 0
+  let unitsSeen = 0
+  let droppedHalf = false
+  let stop = null
+
+  for (let index = 0; index < SUMMARY_MAX_UNITS; index += 1) {
+    const { events, complete } = await readUnit()
+    if (events.length === 0) { stop ??= 'done'; break }
+    unitsSeen += 1
+    if (!complete) {
+      // 半轮：整轮丢掉（最新一轮也不破例，宁可报错让客户端重试）。
+      droppedHalf = true
+      stop = 'incomplete'
+      break
+    }
+    const projected = projectTurnUnit(events)
+    if (projected.records.length > 0) {
+      // 字节预算只约束"较旧的那些轮"：最新的这一轮无论如何都要给全（宁可超一点，
+      // 也不给半轮、也不让客户端永远看不到当前轮）。
+      if (kept.length > 0 && byteCount + projected.bytes > maxBytes) { stop = 'bytes'; break }
+      // 页边界取**整轮原始事件**的首尾，不是首尾下发记录：一轮起点前的
+      // `request/header` 之类虽然在 v2 里不下发，但它们确实属于这一页的 seq 段，
+      // 游标必须越过它们，否则下一次请求会把同一段重扫一遍。
+      kept.push({
+        ...projected,
+        unitStartSeq: events[0].seq,
+        unitEndSeq: events[events.length - 1].seq,
+      })
+      byteCount += projected.bytes
+    }
+    if (kept.length >= limit) { stop = 'count'; break }
+    if (byteCount >= maxBytes) { stop = 'bytes'; break }
+    if (exhausted && stack.length === 0) { stop = 'done'; break }
+  }
+  if (stop === null) stop = 'units'
+
+  if (kept.length === 0) {
+    if (droppedHalf && unitsSeen > 0) {
+      return {
+        error: {
+          code: 'link/too-large',
+          message: 'one turn cannot be read within a single page; retry',
+        },
+      }
+    }
+    return { ...EMPTY_PAGE, clamped }
+  }
+
+  const ordered = [...kept].reverse()
+  const records = ordered.flatMap((unit) => unit.records)
+  const summaries = ordered.flatMap((unit) => unit.summaries)
+  return {
+    records,
+    summaries,
+    startSeq: ordered[0].unitStartSeq,
+    endSeq: ordered[ordered.length - 1].unitEndSeq,
+    // "还有更早的"只由"往回读到底没有"回答：预算停下、或者被回读上限截住，
+    // 都还有更早的轮次。游标永远是 `startSeq`（一轮的起点），不靠猜。
+    hasMore: !(exhausted && stack.length === 0),
+    truncatedBy: stop === 'count' ? 'count' : stop === 'bytes' ? 'bytes' : null,
+    clamped,
+    batches,
+    units: ordered.length,
+  }
+}

package/lib/history.js

@@ -1,11 +1,19 @@
 import { HOST_CALL_TIMEOUT_MS, withTimeout, messageOf } from './history/shared.js'
+import { sliceRangeSafe, truncateSafe } from './unicode.js'
 import {
   DEFAULT_LIMIT, DEFAULT_MAX_BYTES, WINDOW_CHUNK,
   bytesOfRecords, displayRoleOf, roleOf, toRecord, trimRecordForWire, trimRecordsForWire,
 } from './history/records.js'
 import { pageFrom, scanOlder } from './history/window.js'
 import { filteredScan } from './history/filter-scan.js'
-import { createSnapshotCache, scanSnapshot } from './history/session-snapshot.js'
+import { createSnapshotCache, scanSnapshot, snapshotOlderReader } from './history/session-snapshot.js'
+import {
+  HISTORY_COMPRESSION_CAPABILITY, maybeCompressHistoryValue,
+} from './history/compress.js'
+import { FOLD_CAPABILITY, foldProcessRuns } from './history/fold.js'
+import { SUMMARY_FOLD_CAPABILITY, SUMMARY_FOLD_MODE } from './history/fold-summary.js'
+import { readSummaryPage } from './history/summary-window.js'
+import { emptySpans } from './history/coverage.js'
 
 // Re-exported for the caller/tests that read them off this module (single source
 // is `history/records.js`; the call ceiling lives in `history/shared.js`).
@@ -50,6 +58,17 @@ export const HISTORY_CAPABILITIES = [
   // 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',
+  // history-compression: `_link/sessionWindow` 接受 `encoding: "deflate-raw"`，
+  // 回包变成 `{encoding, value(base64), rawBytes}`。手机只在看到这条能力时才请求；
+  // 老客户端不传 encoding，拿到的仍是纯 JSON。
+  HISTORY_COMPRESSION_CAPABILITY,
+  // history-fold-summary: `_link/sessionWindow` 接受 `fold: true`，把本页内
+  // 已完成的轮次折成一条 `+link/fold` 摘要记录（展开时用不带 fold 的普通窗口取回）。
+  FOLD_CAPABILITY,
+  // history-fold-summary-v2: `fold: "summary"` —— 概要先行取数模式（设计
+  // 20261025 §3.4/M6）。只回讲话 + `+link/fold` v2 概要 + 正式回答，按整轮切页。
+  // 独立能力位：老连接器不认识这个值，老客户端也不会传它，两边都没有行为变化。
+  SUMMARY_FOLD_CAPABILITY,
 ]
 
 export function isHistoryMethod(method) {
@@ -129,12 +148,12 @@ function makeSnippet(text, query, radius = 36) {
   const haystack = String(text ?? '')
   const at = haystack.toLowerCase().indexOf(query.toLowerCase())
   if (at < 0) {
-    const head = haystack.slice(0, radius * 2).replace(/\s+/g, ' ').trim()
+    const head = truncateSafe(haystack, radius * 2).replace(/\s+/g, ' ').trim()
     return { snippet: head, highlightStart: 0, highlightLength: 0 }
   }
   const start = Math.max(0, at - radius)
   const end = Math.min(haystack.length, at + query.length + radius)
-  const snippet = haystack.slice(start, end).replace(/\s+/g, ' ').trim()
+  const snippet = sliceRangeSafe(haystack, start, end).replace(/\s+/g, ' ').trim()
   // Re-find the match inside the flattened snippet so the offsets line up with
   // what is actually displayed.
   const flatAt = snippet.toLowerCase().indexOf(query.toLowerCase())
@@ -167,7 +186,11 @@ function hostFailure(error) {
 /**
  * @param {{ logger?: { warn?: Function, info?: Function } }} deps
  */
-export function createHistoryService({ logger = console } = {}) {
+export function createHistoryService({
+  logger = console,
+  cacheTtlMs = 15_000,
+  cacheLimit = 32,
+} = {}) {
   let sessionQuery
   /// 会话日志快照（只给**按角色过滤**的读取用）：一个会话读一次整份、本地过滤、短 TTL。
   /// 它把"每条命中一次宿主调用"那道墙去掉——灌库一个会话从十几次往返变成一次读。
@@ -179,6 +202,42 @@ export function createHistoryService({ logger = console } = {}) {
   let indexSearchable = true
   const inFlight = new Set()
   const lastSeqCache = new Map()
+  /// 最近读过的页（spec 016 后续）：回看、回收后再水合、重复请求同一段时不再走网络。
+  /// 只缓存"已经结束在 before-1"的页：日志只追加，旧 seq 段的内容不会变；
+  /// 会话被裁剪是唯一例外，用短 TTL 兜底（默认 15s）。键里带全部影响结果的参数，
+  /// 少一个就可能把过滤页当成浏览页返回。
+  const pageCache = new Map()
+
+  /// 缓存键里带**折叠模式**（`none` / `v1` / `summary`）而不是布尔值：三种模式的回包
+  /// 形状不同，混用一个键会把概要页当普通页发出去。
+  function cacheKey({ sessionId, before, through, limit, maxBytes, roles, foldMode, coverage }) {
+    return [sessionId, before, through ?? '', limit, maxBytes,
+            roles === undefined ? '' : [...roles].sort().join(','), foldMode,
+            coverage === true ? '1' : '0'].join('|')
+  }
+
+  function cacheGet(key, now = Date.now()) {
+    const hit = pageCache.get(key)
+    if (hit === undefined) return undefined
+    if (now - hit.at > cacheTtlMs) {
+      pageCache.delete(key)
+      return undefined
+    }
+    // 重新插入：Map 的插入序当作 LRU 序，命中也要刷新位置。
+    pageCache.delete(key)
+    pageCache.set(key, hit)
+    return hit.value
+  }
+
+  function cachePut(key, value, now = Date.now()) {
+    if (cacheLimit <= 0) return
+    pageCache.delete(key)
+    pageCache.set(key, { at: now, value })
+    while (pageCache.size > cacheLimit) {
+      const oldest = pageCache.keys().next().value
+      pageCache.delete(oldest)
+    }
+  }
 
   /// The log's newest seq, cached briefly: it is only needed to clamp a request
   /// that runs past the end (a session can be trimmed between two pages).
@@ -347,7 +406,7 @@ export function createHistoryService({ logger = console } = {}) {
           if (!browsing && !text.toLowerCase().includes(needle)) continue
           hits.push({ seq: doc.seq, role: display, ...(query.length > 0
             ? makeSnippet(text, query)
-            : { snippet: String(text).slice(0, 72).replace(/\s+/g, ' ').trim(),
+            : { snippet: truncateSafe(String(text), 72).replace(/\s+/g, ' ').trim(),
                 highlightStart: 0, highlightLength: 0 }) })
           if (hits.length >= limit) {
             // 装满了：这一条已经收进本页，下一页从它的**前一条**继续——不能从整块之前
@@ -390,11 +449,60 @@ export function createHistoryService({ logger = console } = {}) {
     return Number.isSafeInteger(value) && value >= 0 ? value : undefined
   }
 
+  /// 概要 v2 的一页（能力 `history-fold-summary-v2`，`fold: "summary"`）。
+  ///
+  /// 为什么走**整份快照**：这一页的单位是"整轮"，而一轮可以长达两千级 seq。
+  /// 分块回读一次只有 51 条（宿主 `readEvent` 的硬上限），一页要几十次往返；
+  /// 快照一次读完整份（本机 13k 事件实测 116–315 ms），之后每页零往返。
+  /// 快照不可用（老宿主没 `readSession`、会话超过内存护栏、读失败）时退回分块回读：
+  /// 语义不变（仍按整轮、仍不切半轮），只是慢一些，并且在单轮超过回读预算时
+  /// 如实回 `link/too-large` 让客户端重试，而不是下发半轮。
+  async function summaryWindowValue({ sessionId, before, through, limit, maxBytes }) {
+    let snapshot = await snapshots.get(sessionId)
+    // 与浏览翻页同一条护栏：快照必须是"这段的上界之内"的。请求上界比快照还新
+    // （刚发出去一条消息，或快照刚好过期一瞬）时不能拿旧快照夹上界——那会把
+    // 最新的一轮整段漏掉，还谎报 `clamped`（"日志变短了"）。改走实时读。
+    if (snapshot !== undefined && before - 1 > snapshot.newestSeq) snapshot = undefined
+    let newest = snapshot?.newestSeq
+    if (!Number.isInteger(newest)) newest = await newestSeq(sessionId)
+    let upper = Math.min(before - 1, through ?? Number.MAX_SAFE_INTEGER)
+    let clamped = false
+    if (Number.isInteger(newest) && upper > newest) {
+      upper = newest
+      clamped = true
+    }
+    const readOlder = snapshot !== undefined
+      ? snapshotOlderReader(snapshot)
+      : async (cursor) => {
+          const { window: result, clamped: chunkClamped } = await readChunk(sessionId, cursor)
+          const events = Array.isArray(result.events) ? result.events : []
+          const floorSeq = Number.isInteger(result.startSeq) ? result.startSeq : (events[0]?.seq ?? 0)
+          return { events, floorSeq, exhausted: floorSeq === 0, clamped: chunkClamped }
+        }
+    const page = await readSummaryPage({ readOlder, upper, limit, maxBytes, clamped })
+    if (page.error !== undefined) return page
+    // 字段与普通窗口同形（`startSeq`/`endSeq`/`hasMore`/`truncatedBy`/`clamped`/
+    // `scanBoundary`），客户端沿用同一套游标规则即可。**不带 `folds` 副本**：
+    // 摘要已经在记录里，再抄一份就是白白多一倍概要字节（设计 §十一 的预算是按一份算的）。
+    return {
+      records: page.records,
+      startSeq: page.startSeq,
+      endSeq: page.endSeq,
+      hasMore: page.hasMore,
+      truncatedBy: page.truncatedBy,
+      clamped: page.clamped === true,
+      scanBoundary: page.startSeq,
+    }
+  }
+
   async function window(args) {
     const sessionId = idOfAddress(args.address)
     const before = Number(args.before)
     if (sessionId === undefined) return failure('gateway/bad-request', 'address must name a session')
     if (!Number.isSafeInteger(before) || before < 0) return failure('gateway/bad-request', 'before must be a non-negative integer')
+    // `limit` 的单位随模式变：普通窗口是**记录条数**；概要 v2（`fold: "summary"`）是
+    // **轮数**，因为这一模式的页单位就是整轮（字节预算由 `maxBytes` 兜）。客户端按
+    // 自己要知道的"首屏几轮"传即可。
     const limit = Number.isSafeInteger(Number(args.limit)) && Number(args.limit) > 0 ? Number(args.limit) : DEFAULT_LIMIT
     const maxBytes = Number.isSafeInteger(Number(args.maxBytes)) && Number(args.maxBytes) > 0
       ? Number(args.maxBytes) : DEFAULT_MAX_BYTES
@@ -408,10 +516,36 @@ export function createHistoryService({ logger = console } = {}) {
     const { roles, error: rolesError } = parseRoles(args.roles)
     if (rolesError) return rolesError
 
+    // 折叠模式三态：`none`（不传）/ `v1`（`fold: true`）/ `summary`（`fold: "summary"`）。
+    // 只有精确的 `"summary"` 切到概要 v2；`fold: true` 与所有其它取值一律按老规矩走，
+    // 所以老客户端的回包与改动前逐字节相同（`test/helpers/fold-v1-golden.json`）。
+    const summaryFold = args.fold === SUMMARY_FOLD_MODE
+    const fold = !summaryFold && args.fold === true
+    const foldMode = summaryFold ? 'summary' : fold ? 'v1' : 'none'
+    const coverage = args.coverage === true
+    // 概要 v2 的语义是"整轮 + 只讲话与概要"：角色过滤会切碎轮次，覆盖区间也按原始
+    // 记录算，两者与它拼不到一起。明确拒绝，不静默退回另一种语义（否则回包看起来
+    // 正常、内容却是错的）。
+    if (summaryFold && (roles !== undefined || coverage)) {
+      return failure('gateway/bad-request',
+        'fold "summary" cannot be combined with roles or coverage')
+    }
+    const requestKey = cacheKey({ sessionId, before, through, limit, maxBytes, roles, foldMode, coverage })
+    const cachedPage = cacheGet(requestKey)
+    if (cachedPage !== undefined) {
+      return { ok: true, value: maybeCompressHistoryValue(cachedPage, args.encoding) }
+    }
+
     const key = `window:${sessionId}`
     if (inFlight.has(key)) return failure('link/busy', 'another window read is in flight for this session')
     inFlight.add(key)
     try {
+      if (summaryFold) {
+        const summary = await summaryWindowValue({ sessionId, before, through, limit, maxBytes })
+        if (summary.error !== undefined) return failure(summary.error.code, summary.error.message)
+        cachePut(requestKey, summary)
+        return { ok: true, value: maybeCompressHistoryValue(summary, args.encoding) }
+      }
       // 按角色过滤时走"先定位命中 seq、再定向取完整记录"（spec 016 的"来回次数"一条）：
       // 同样一段日志，过滤路径实测从 2.5–4.1 s 降到数百毫秒；未过滤的浏览翻页保持原样
       // （它要的是精确的一段原始事件，`readEvent` 每块 51 条正合适）。
@@ -419,9 +553,21 @@ export function createHistoryService({ logger = console } = {}) {
       // 三级：① 角色过滤 + 宿主能整份读 → 从快照出（一次读、之后每页零往返）；
       //       ② 角色过滤但快照不可用（没有 readSession / 太大 / 读失败）→ A1 的分块定位；
       //       ③ 不带角色 → 原来的分块扫描（浏览翻页要的是精确的一段原始事件）。
-      const snapshot = roles !== undefined && typeof sessionQuery?.readSession === 'function'
-        ? await snapshots.get(sessionId)
-        : undefined
+      // 未过滤的浏览翻页也走整份快照：本机 13k 会话一次 `readSession` 约 0.3s，
+      // 而逐页 `readEvent` 每页都要付一次宿主地板价（实测 300–500ms/页）。
+      // 第一次请求仍走实时读（首屏不能等快照），同时在后台预热；之后的更早页命中快照。
+      // 只有"请求上界落在快照最新 seq 之内"才用快照——更新的那段必须实时读，
+      // 否则刚发出去的消息会被旧快照挡住。
+      let snapshot
+      if (roles !== undefined) {
+        snapshot = typeof sessionQuery?.readSession === 'function'
+          ? await snapshots.get(sessionId)
+          : undefined
+      } else {
+        snapshot = snapshots.peek(sessionId)
+        if (snapshot === undefined) snapshots.warm(sessionId)
+        if (snapshot !== undefined && before - 1 > snapshot.newestSeq) snapshot = undefined
+      }
       const scan = snapshot !== undefined
         ? scanSnapshot(snapshot, { before, through, limit, maxBytes, roles, roleOf })
         : useFilterScan
@@ -433,7 +579,23 @@ export function createHistoryService({ logger = console } = {}) {
       const page = pageFrom(scan, { limit, maxBytes, roles })
       // 016：下发前统一清掉只用于诊断的宿主模型输出日志（口径只有一份，
       // 见 specs/016-history-load-perf/contracts/history-record-trim.md）。
-      return { ok: true, value: { ...page, records: trimRecordsForWire(page.records) } }
+      const trimmed = trimRecordsForWire(page.records)
+      const folded = fold ? foldProcessRuns(trimmed) : { records: trimmed, folds: [] }
+      const value = { ...page, records: folded.records }
+      // 已知为空：只覆盖"最老返回记录..窗口上界"。版本取会话最新号；
+      // 客户端版本不一致时不采纳（宿主重排号段后旧结论失效）。
+      if (coverage) {
+        const upper = before - 1
+        const lower = Math.max(1, before - limit)
+        value.knownEmpty = emptySpans(trimmed, lower, upper)
+        value.revision = String(await newestSeq(sessionId))
+      }
+      // `folds` 只在折叠时出现：老客户端不认识这个字段也不会读它；新客户端没有它
+      // 就按普通记录折（老连接器）。
+      if (folded.folds.length > 0) value.folds = folded.folds
+      cachePut(requestKey, value)
+      // 压缩只改回包形态，不改分页语义：解压后逐字段等于不压缩的那份。
+      return { ok: true, value: maybeCompressHistoryValue(value, args.encoding) }
     } catch (error) {
       logger.warn?.(`mobile-link: sessionWindow failed: ${messageOf(error)}`)
       return hostFailure(error)

package/lib/index.js

@@ -4,8 +4,8 @@
  * Scope (deliberately tiny so a DSH upgrade can never make it fatal):
  *   1. Run the DLP agent: dial the relay over WSS, serve the iOS client's
  *      session/event traffic from the local DSH instance. On a computer that has
- *      never been registered, redeem the invite code from the environment (or
- *      the config) first, so a fresh install becomes usable without the relay
+ *      never been registered, enroll with the relay address first (open
+ *      enrollment), so a fresh install becomes usable without the relay
  *      operator provisioning anything by hand.
  *   2. Two routes under `/mobile-link` behind DSH's own connection fence:
  *      GET  /status     — is the link up, which devices are attached, and is
@@ -43,6 +43,10 @@ const DEFAULTS = {
   relayUrl: process.env.DSH_RELAY_URL
     || process.env.DSH_MOBILE_LINK_RELAY
     || 'wss://relay.example.com/dsh-link',
+  // 面板的默认中转：只用于预填，不参与拨号优先级。它和 `relayUrl` 分开，是因为
+  // 把地址钉进 `relayUrl` 会覆盖身份文件里真正登记过的地址；这里只给表单一个
+  // 可修改的初值。
+  defaultRelayUrl: process.env.DSH_DEFAULT_RELAY_URL || '',
   agentId: '',
   agentSecret: '',
   stateFile: '',
@@ -56,6 +60,10 @@ const DEFAULTS = {
   // 是否接收手机推上来的阶段记录（`_link/diagnostics`）。false = 回 diagnostics/disabled，
   // 手机静默忽略——这是"记录出问题时的回退闸"，关掉不影响连接。
   diagnostics: true,
+  // 是否接收手机推上来的运行日志（`_link/logs`），落盘目录见 logs.js。
+  // 关掉后手机收到的同样是明确拒绝，不会影响连接。
+  logs: true,
+  logsFile: '',
   heartbeatMs: 20000,
   pongTimeoutMs: 60000,
   maxBackoffMs: 30000,
@@ -97,6 +105,9 @@ function buildAgent(config, logger) {
   return new MobileLinkAgent({
     enabled: config.enabled !== false,
     relayUrl: typeof config.relayUrl === 'string' ? config.relayUrl : DEFAULTS.relayUrl,
+    defaultRelayUrl: typeof config.defaultRelayUrl === 'string'
+      ? config.defaultRelayUrl
+      : DEFAULTS.defaultRelayUrl,
     agentId: typeof config.agentId === 'string' ? config.agentId : '',
     agentSecret: typeof config.agentSecret === 'string' ? config.agentSecret : '',
     stateFile: typeof config.stateFile === 'string' && config.stateFile ? config.stateFile : undefined,
@@ -112,6 +123,10 @@ function buildAgent(config, logger) {
       ? DEFAULTS.slowRequestMs
       : Number(config.slowRequestMs) || 0,
     diagnostics: config.diagnostics !== false,
+    // 设备日志落盘（见 lib/logs.js）：`logsFile` 换根目录，`logs: false` 关掉接收。
+    // 保留期固定 7 天，不做配置项——清理在写入路径上，配错就是悄悄留不住或悄悄写满。
+    logs: config.logs !== false,
+    logsRoot: typeof config.logsFile === 'string' && config.logsFile ? config.logsFile : undefined,
     heartbeatMs: Number(config.heartbeatMs) || DEFAULTS.heartbeatMs,
     pongTimeoutMs: Number(config.pongTimeoutMs) || DEFAULTS.pongTimeoutMs,
     maxBackoffMs: Number(config.maxBackoffMs) || DEFAULTS.maxBackoffMs,
@@ -190,6 +205,26 @@ function wireSessionQuery(ctx, history, logger) {
   }
 }
 
+/**
+ * 把宿主的任务与活会话服务交给活动名单（**可选注入**，spec 018）。
+ *
+ * 两个服务都到位才回答 `_link/jobRoster`；缺一个就保持"不支持"，手机整块不显示
+ * （缺一个却回空名单，等于把降级说成"没有任务在跑"）。
+ * 注入可能晚于第一台设备连接——roster 在绑定后会补一次订阅，见 `jobs-roster.js`。
+ */
+function wireJobsServices(ctx, agent, logger) {
+  try {
+    ctx.inject(['jobs', 'sessions'], (scope) => {
+      agent.setJobsServices?.({ jobs: scope.jobs, sessions: scope.sessions })
+      // 服务卸载（宿主换代/插件禁用）时同步摘掉宿主任务事件订阅。
+      scope.effect?.(() => () => agent.setJobsServices?.({}), 'mobile-link: jobs roster')
+      logger.info?.('mobile-link: activity roster bound to ctx.jobs / ctx.sessions')
+    })
+  } catch (error) {
+    logger.warn?.(`mobile-link: jobs service unavailable (activity roster falls back): ${error}`)
+  }
+}
+
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
  * @param {Record<string, unknown>} rawConfig
@@ -205,6 +240,7 @@ export function apply(ctx, rawConfig) {
   registerRoutes(ctx, agent, logger, config, history)
   wireEndpointResolver(ctx, agent, logger)
   wireSessionQuery(ctx, history, logger)
+  wireJobsServices(ctx, agent, logger)
   logger.info?.(`mobile-link: ready (relay ${config.relayUrl})`)
 }