dsh-plugin-mobile-link 0.6.5 → 0.7.0

package/lib/logs.js

@@ -0,0 +1,242 @@
+/**
+ * 设备日志落盘（`_link/logs`）。
+ *
+ * 与 `journal.js` 的分工：journal 记的是**连接器自己**的生命周期事件（几百条、可以随手丢），
+ * 这里记的是**手机端**产生的日志行（量级大、需要按时间窗回看）。两者共用"诊断设施不许抛"
+ * 这条硬约束，但容量与保留期完全不同。
+ *
+ * 保留期 **7 天**，清理不靠定时器、也不新增任何进程：每次 `append` 顺手做一次，
+ * 且 60 秒内最多一次。理由是不引入定时任务就不会有"任务没跑起来、盘悄悄满了"这种状态。
+ *
+ * 目录布局：`<root>/<deviceId>/<YYYYMMDD>.jsonl`。按天分文件有三个好处：
+ * 清理只需 unlink 整个文件，不必重写；`tail` 只需盯当天的文件；超限时按天淘汰。
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { defaultStatePath } from './state.js'
+
+/** 日志保留期：7 天。 */
+export const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+/** 单台设备磁盘上限；超了按天淘汰最旧的。 */
+export const DEFAULT_MAX_DEVICE_BYTES = 200 * 1024 * 1024
+/** 单条日志正文上限；超长截断而不是丢弃（截断仍能看出是哪一行）。 */
+export const MAX_TEXT_CHARS = 4000
+/** 每批最多收多少条、多少字节；超了如实报 `accepted`，剩下的由手机下次推。 */
+export const MAX_BATCH_ENTRIES = 500
+export const MAX_BATCH_BYTES = 64 * 1024
+/** 清理的最小间隔：清理一次最多 60 秒一次。 */
+const PRUNE_INTERVAL_MS = 60 * 1000
+
+/** 默认落在身份文件旁边：`$DSH_HOME/mobile-link/logs`。测试用临时 DSH_HOME 自动隔离。 */
+export function defaultLogsRoot() {
+  return join(dirname(defaultStatePath()), 'logs')
+}
+
+/** 本地日 `YYYYMMDD`，与 journal 的 `local_day` 口径一致。 */
+export function dayStamp(ms) {
+  const date = new Date(ms)
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
+}
+
+/** 设备 id 会直接进路径：只留安全字符，避免 `../` 之类的路径穿越。 */
+export function safeDeviceId(deviceId) {
+  const text = String(deviceId ?? '').trim()
+  if (!text) return 'unknown'
+  return text.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 120)
+}
+
+/** 一条上报 → 一行落盘 JSON；非法条目返回 null（调用方计入拒收）。 */
+export function normalizeEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  const ms = Number(raw.ms)
+  const text = typeof raw.text === 'string' ? raw.text : ''
+  if (!Number.isFinite(ms) || !text) return null
+  const seq = Number(raw.seq)
+  return {
+    seq: Number.isFinite(seq) ? seq : undefined,
+    ms,
+    at: typeof raw.at === 'string' && raw.at ? raw.at : new Date(ms).toISOString(),
+    level: typeof raw.level === 'string' ? raw.level.slice(0, 16) : 'info',
+    source: typeof raw.source === 'string' ? raw.source.slice(0, 32) : 'app',
+    text: text.slice(0, MAX_TEXT_CHARS),
+  }
+}
+
+export class LogSpool {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.root] 目录（默认 `$DSH_HOME/mobile-link/logs`）
+   * @param {number} [options.retentionMs] 保留期
+   * @param {number} [options.maxDeviceBytes] 单设备上限
+   * @param {() => number} [options.now]
+   * @param {{ debug?: (message: string) => void }} [options.logger]
+   */
+  constructor({
+    root, retentionMs = DEFAULT_RETENTION_MS, maxDeviceBytes = DEFAULT_MAX_DEVICE_BYTES,
+    now = Date.now, logger,
+  } = {}) {
+    this.root = typeof root === 'string' && root.trim() ? root : defaultLogsRoot()
+    this.retentionMs = Math.max(60_000, Number(retentionMs) || DEFAULT_RETENTION_MS)
+    this.maxDeviceBytes = Math.max(1024, Number(maxDeviceBytes) || DEFAULT_MAX_DEVICE_BYTES)
+    this.now = now
+    this.logger = logger
+    /** 每台设备已接受的最高序号（幂等：同批重推不会写两遍）。 */
+    this.watermarks = new Map()
+    this._lastPruneAt = 0
+  }
+
+  /** 一台设备当天的文件路径。 */
+  pathFor(deviceId, ms = this.now()) {
+    return join(this.root, safeDeviceId(deviceId), `${dayStamp(ms)}.jsonl`)
+  }
+
+  /**
+   * 收一批并落盘。
+   *
+   * @returns {{accepted: number, lastSeq: number, dropped: number}}
+   *   `accepted` 是真正写下去的条数；被水位挡掉的重复条目不计入。
+   */
+  append(deviceId, entries, { full = false } = {}) {
+    const result = { accepted: 0, lastSeq: this.watermarks.get(deviceId) ?? 0, dropped: 0 }
+    if (!Array.isArray(entries) || entries.length === 0) return result
+    let bytes = 0
+    const byDay = new Map()
+    for (const raw of entries) {
+      const entry = normalizeEntry(raw)
+      if (!entry) { result.dropped += 1; continue }
+      const seq = Number(entry.seq)
+      const watermark = this.watermarks.get(deviceId) ?? 0
+      // `full` 是"整段重推"（App 冷启动回填或 `dsh://diag export`）：
+      // 水位不参与判断，但仍然照常推进，避免之后的增量重复。
+      if (!full && Number.isFinite(seq) && seq <= watermark) continue
+      const line = `${JSON.stringify({ ...entry, deviceId, full: full || undefined })}\n`
+      if (result.accepted > 0 && bytes + line.length > MAX_BATCH_BYTES) break
+      if (result.accepted >= MAX_BATCH_ENTRIES) break
+      const day = dayStamp(entry.ms)
+      const bucket = byDay.get(day) ?? []
+      bucket.push(line)
+      byDay.set(day, bucket)
+      bytes += line.length
+      result.accepted += 1
+      result.lastSeq = Math.max(result.lastSeq, Number.isFinite(seq) ? seq : result.lastSeq)
+    }
+    if (!byDay.size) return result
+    for (const [day, lines] of byDay) this.#write(deviceId, day, lines)
+    this.watermarks.set(deviceId, result.lastSeq)
+    this.#pruneIfDue()
+    return result
+  }
+
+  #write(deviceId, day, lines) {
+    const path = join(this.root, safeDeviceId(deviceId), `${day}.jsonl`)
+    try {
+      mkdirSync(dirname(path), { recursive: true })
+      appendFileSync(path, lines.join(''))
+    } catch (error) {
+      // 诊断设施不许把链路带崩：写不进去就只报一声。
+      this.logger?.debug?.(`mobile-link: logs spool write failed (${error?.message ?? error})`)
+    }
+  }
+
+  /** 60 秒内最多清理一次；清理本身不许抛。 */
+  #pruneIfDue() {
+    const now = this.now()
+    if (now - this._lastPruneAt < PRUNE_INTERVAL_MS) return
+    this._lastPruneAt = now
+    try {
+      this.prune(now)
+    } catch (error) {
+      this.logger?.debug?.(`mobile-link: logs prune failed (${error?.message ?? error})`)
+    }
+  }
+
+  /**
+   * 清理：先按保留期删整天文件，再按单设备上限删最旧的。
+   * 返回删掉的字节数（测试用；生产只看副作用）。
+   */
+  prune(now = this.now()) {
+    let freed = 0
+    let devices = []
+    try {
+      devices = readdirSync(this.root, { withFileTypes: true }).filter((item) => item.isDirectory())
+    } catch {
+      return 0
+    }
+    for (const device of devices) {
+      const dir = join(this.root, device.name)
+      let files = []
+      try {
+        files = readdirSync(dir).filter((name) => name.endsWith('.jsonl'))
+      } catch {
+        continue
+      }
+      if (!files.length) {
+        try { rmSync(dir, { recursive: true, force: true }) } catch { /* 目录删不掉无所谓 */ }
+        continue
+      }
+      const stats = []
+      for (const name of files.sort()) {
+        const path = join(dir, name)
+        try {
+          const info = statSync(path)
+          stats.push({ path, day: name.slice(0, 8), size: info.size, mtimeMs: info.mtimeMs })
+        } catch { /* 文件刚被删掉 */ }
+      }
+      // 保留期按**文件名里的日**判定，不看 mtime：mtime 会被备份、拷贝、恢复改动，
+      // 而"这是哪一天的日志"只写在名字里，判定必须与名字一致。
+      const cutoff = dayStamp(now - this.retentionMs)
+      for (const file of stats) {
+        if (file.day >= cutoff) continue
+        freed += this.#unlink(file)
+      }
+      let kept = stats.filter((file) => file.day >= cutoff)
+      let total = kept.reduce((sum, file) => sum + file.size, 0)
+      for (const file of kept) {
+        if (total <= this.maxDeviceBytes) break
+        total -= file.size
+        freed += this.#unlink(file)
+      }
+    }
+    return freed
+  }
+
+  #unlink(file) {
+    try {
+      unlinkSync(file.path)
+      return file.size
+    } catch {
+      return 0
+    }
+  }
+
+  /** 某台设备（或全部）的磁盘占用，给人看的。 */
+  usage() {
+    const rows = []
+    let devices = []
+    try {
+      devices = readdirSync(this.root, { withFileTypes: true }).filter((item) => item.isDirectory())
+    } catch {
+      return rows
+    }
+    for (const device of devices) {
+      const dir = join(this.root, device.name)
+      let bytes = 0
+      let files = 0
+      let newest = 0
+      try {
+        for (const name of readdirSync(dir)) {
+          if (!name.endsWith('.jsonl')) continue
+          const info = statSync(join(dir, name))
+          bytes += info.size
+          files += 1
+          newest = Math.max(newest, info.mtimeMs)
+        }
+      } catch { /* 忽略单台设备的读失败 */ }
+      rows.push({ deviceId: device.name, bytes, files, newestMs: newest })
+    }
+    return rows.sort((a, b) => b.bytes - a.bytes)
+  }
+}

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-go/internal/httpapi` 的 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/router.js

@@ -18,6 +18,7 @@ import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 import { isHistoryMethod } from './history.js'
 import { trimRecordsForWire } from './history/records.js'
+import { isJobsMethod } from './jobs-roster.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -26,6 +27,16 @@ import { trimRecordsForWire } from './history/records.js'
 export const FSPUT_BEGIN = 'fsPutBegin'
 export const FSPUT_CHUNK = 'fsPutChunk'
 export const FSPUT_END = 'fsPutEnd'
+/**
+ * relay 叫停一次后台上传（占位型前向兼容）。
+ *
+ * 本仓库两个中转**目前都不发这一帧**：手机掐掉 `PUT /files/up` 时，它们在
+ * `finally` 里只摘掉本地的桥接，既不发取消帧、也不断开 agent 的 WebSocket。
+ * 因此真正兜住句柄的是 `FileInbox` 的空闲清扫与"重传接管暂存路径"；这一帧
+ * 让将来的/第三方中转能提前释放。按 bid 寻址，可以不带 `deviceId`
+ * （与 `fsGetCancel` 同口径，未知 bid 是空操作）。
+ */
+export const FSPUT_CANCEL = 'fsPutCancel'
 
 /**
  * 后台大文件下载的桥接帧（relay → 连接器），同一族的另一半：relay 终结
@@ -96,13 +107,16 @@ export function trimHistoryPageForWire(method, result) {
 }
 
 import { DeviceTimeline } from './diagnostics.js'
-import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest } from './session-digest.js'
+import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest, digestDelta } from './session-digest.js'
+import { DIR_LISTING_METHOD, dirListing } from './dir-listing.js'
 
 /** 慢请求阈值默认值（毫秒）；0 = 关闭逐条慢请求记录。 */
 export const DEFAULT_SLOW_REQUEST_MS = 2000
 
 /** App 把自己那份阶段记录推上来的方法（契约 connector-diagnostics-method.md）。 */
 export const DIAGNOSTICS_METHOD = '_link/diagnostics'
+/** 手机把运行日志推上来的方法；落盘在 `logs.js`，与 journal 分开。 */
+export const LOGS_METHOD = '_link/logs'
 /** 单批上限：超过就截断并如实报 `accepted`，剩下的由 App 下次再推（水位不推进）。 */
 export const DIAGNOSTICS_BATCH_BYTES = 32 * 1024
 /** 单条事件里字符串字段的保留长度。 */
@@ -142,9 +156,11 @@ export class DeviceRouter {
   constructor({
     dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
     eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {}, onEvent = () => {},
-    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true,
+    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true, logs = null,
   } = {}) {
     this.dsh = dsh
+    /** 设备日志落盘（见 logs.js）；null = 不接日志（老配置或单测）。 */
+    this.logs = logs
     this.eventsBacklog = eventsBacklog
     this.slowRequestMs = Number(slowRequestMs) || 0
     this.diagnosticsEnabled = diagnostics !== false
@@ -185,6 +201,21 @@ export class DeviceRouter {
     // 历史窗口/检索（spec 007）：由 index.js 注入宿主 `sessionQuery` 后交给它。
     // 没绑上就回 `link/unsupported`，手机端退回 `session/page`。
     this.history = undefined
+    // 活动名单与 `link/jobs` 推帧（spec 018）。订阅与去抖都在 roster 里，router 只负责
+    // 转交设备生命周期与把帧广播出去。
+    this.jobsRoster = undefined
+  }
+
+  /**
+   * 挂上活动名单（spec 018）。
+   *
+   * 注入可能晚于第一台设备连接（`ctx.inject` 的时序），所以这里要对**已经挂着**的
+   * 设备补报一遍：只在 attach 时通知的话，这台连接会一直到下一次 attach 才开始推帧。
+   */
+  bindJobsRoster(roster) {
+    this.jobsRoster = roster
+    if (roster === undefined) return
+    for (const deviceId of this.devices.keys()) roster.addDevice(deviceId)
   }
 
   #changed() {
@@ -221,6 +252,11 @@ export class DeviceRouter {
       this.handleFsGetCancel(frame)
       return
     }
+    // 上传的取消帧同样是 bid 寻址，可能不带 `deviceId`；放在守卫之前，理由同上。
+    if (frame.t === FSPUT_CANCEL) {
+      this.handleFsPutCancel(frame)
+      return
+    }
     if (!deviceId) return
     const problem = deviceFrameError(frame)
     if (problem) {
@@ -305,6 +341,17 @@ export class DeviceRouter {
     }
   }
 
+  /**
+   * relay 叫停一次上传：立刻关句柄、删 `.part`。
+   *
+   * 不回帧：取消本身不是一次请求，也没有可报的错（与 `handleFsGetCancel` 同）。
+   */
+  handleFsPutCancel(frame) {
+    const bid = String(frame?.bid ?? '')
+    if (!bid) return
+    this.fileInbox.cancel(bid)
+  }
+
   /**
    * 开一次下载。**不 await**：分片要在 relay 读响应体时陆续发出去，一个 await
    * 会把这条 socket 上其它帧全挡住（与上传那条流水线的理由相同）。
@@ -404,6 +451,22 @@ export class DeviceRouter {
     return { ok: true, value: { accepted, lastSeq } }
   }
 
+  /**
+   * 收下手机推来的日志行。
+   *
+   * 与 `acceptDiagnostics` 的区别：这里不产生任何生命周期事件（日志是数据，不是状态），
+   * 也不做批量解释；`logs.js` 只负责按天落盘与 7 天清理。失败一律当无事：
+   * 手机侧把未确认的条目留在自己的环里，下次再推。
+   */
+  acceptLogs(deviceId, args = {}) {
+    if (!this.logs) {
+      return { ok: false, error: errorObject('logs/disabled', 'log intake is disabled on this connector') }
+    }
+    const entries = Array.isArray(args.entries) ? args.entries : []
+    const result = this.logs.append(deviceId, entries, { full: args.full === true })
+    return { ok: true, value: result }
+  }
+
   /** 起一次新的接入计时（回头客也重起：那确实是一次新连接）。 */
   #startTimeline(deviceId) {
     this.timelines.get(deviceId)?.finish()
@@ -428,6 +491,9 @@ export class DeviceRouter {
   async attachDevice(deviceId, info = {}) {
     if (!nonEmptyString(deviceId)) return
     this.#startTimeline(deviceId)
+    // 活动名单（018）：第一台设备连上才订阅宿主任务事件；回头客这里也要补一次
+    // （detach 时它从名单里撤下过）。
+    this.jobsRoster?.addDevice(deviceId)
     const existing = this.devices.get(deviceId)
     if (existing) {
       // 回头客：手机又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
@@ -484,6 +550,9 @@ export class DeviceRouter {
     this.#finishTimeline(deviceId)
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 活动名单（018）：断了就不再往它那儿推任务帧（离线补发旧任务状态没有意义），
+    // 最后一台设备离开时 roster 自己会释放宿主订阅。
+    this.jobsRoster?.removeDevice(deviceId)
     if (reason === 'revoked') {
       await this.#dropDevice(deviceId)
       this.onEvent('device.revoked', { deviceId })
@@ -516,6 +585,7 @@ export class DeviceRouter {
   async #dropDevice(deviceId) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    this.jobsRoster?.removeDevice(deviceId)
     for (const muxId of this.streams.removeDevice(deviceId)) this.dsh.cancelStream(muxId)
     this.devices.delete(deviceId)
     this.logger.info?.(
@@ -555,6 +625,12 @@ export class DeviceRouter {
     // 不该有残留：上面的循环已经逐个收过；这里兜底，防止 attach 之后没进 devices 的路径留下脏项。
     this.timelines.clear()
     this._sentBytes.clear()
+    // 链路断了：在传的上传与下载都不可能再完成。上传要关句柄、删 `.part`；
+    // 下载要停掉还没读完的窗口。
+    this.fileInbox.clear()
+    this.fileFetcher.clear()
+    // 活动名单（018）：设备都没了，宿主任务订阅与排队的帧一起放掉。
+    this.jobsRoster?.releaseAll()
     return muxIds
   }
 
@@ -575,19 +651,66 @@ export class DeviceRouter {
         this.lastError = messageOf(error)
         this.#changed()
       }
-      const payload = result?.ok === true
-        ? { ok: true, value: encodeDigest(digestSessionList(result), args.encoding) }
-        : result
+      let payload = result
+      if (result?.ok === true) {
+        const trimmed = digestSessionList(result)
+        const items = Array.isArray(trimmed?.items) ? trimmed.items : []
+        const since = typeof args.since === 'string' ? args.since : null
+        this.digestCursors ??= new Map()
+        const previous = since ? this.digestCursors.get(deviceId) : null
+        // 版本对得上才发增量；对不上（首次、连接器重启、设备被清理）发全量。
+        const incremental = Boolean(previous && previous.version === since)
+        const delta = digestDelta(incremental ? previous.fingerprints : null, items)
+        this.digestCursors.set(deviceId, { version: delta.version, fingerprints: delta.fingerprints })
+        if (this.digestCursors.size > 32) {
+          const oldest = this.digestCursors.keys().next().value
+          this.digestCursors.delete(oldest)
+        }
+        const value = {
+          ...trimmed,
+          items: incremental ? delta.changed : items,
+          removed: incremental ? delta.removed : [],
+          version: delta.version,
+          full: !incremental,
+        }
+        payload = { ok: true, value: encodeDigest(value, args.encoding) }
+      }
       this.send(deviceId, resultFrame(frame.id, payload, deviceId))
       return
     }
 
+    // 目录清单的本机增强（设计 20261024）：连接器读宿主的 `workspaceFiles/list`，
+    // 在电脑本机对每个条目 `fs.stat` 补一个 `mtimeMs`——宿主没有时间字段，而
+    // `workspaceFiles/stat` 的 `version` 是 opaque token（推不出时间）。
+    // 与 sessionDigest 同款：清单的内容仍是宿主的，连接器只加字段；任何一步出问题
+    // 都退回未增强的原始清单（装饰永不弄坏清单）。
+    if (frame.method === DIR_LISTING_METHOD) {
+      let result
+      try {
+        // `dirListing` 认宿主信封本身（`{ ok, value: { entries } }`）并原样回同形状的值：
+        // 宿主报错时**信封逐字透传**，`resultFrame` 照常把它翻成 `ok:false` + 原错误码。
+        // 这里不能再包一层 `{ ok: true, value }`——那会把宿主的失败塞进 `value` 里，
+        // 帧上反而成了 `ok:true`（手机就会把"目录不存在"读成"空目录"）。
+        result = await dirListing({ dsh: this.dsh, args: frame.args ?? {}, logger: this.logger })
+      } catch (error) {
+        result = { ok: false, error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}) }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     if (frame.method === DIAGNOSTICS_METHOD) {
       const result = this.acceptDiagnostics(deviceId, frame.args ?? {})
       this.send(deviceId, resultFrame(frame.id, result, deviceId))
       return
     }
 
+    if (frame.method === LOGS_METHOD) {
+      const result = this.acceptLogs(deviceId, frame.args ?? {})
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     // Files the phone sends are answered here rather than forwarded: the Host
     // has no upload endpoint, and carrying them on the existing unary frame
     // means neither the relay nor the protocol has to change.
@@ -667,6 +790,22 @@ export class DeviceRouter {
       return
     }
 
+    // 活动名单（spec 018）与 history 同一条短路：连接器自己回答，不转发宿主。
+    // 没挂上宿主 `ctx.jobs` 时回 `link/unsupported`——**不**回空名单，否则手机
+    // 会把"这台连接器不支持"显示成"没有任务在跑"。
+    if (isJobsMethod(frame.method)) {
+      let result
+      try {
+        result = this.jobsRoster === undefined
+          ? { ok: false, error: errorObject('link/unsupported', 'job roster is unavailable on this connector') }
+          : await this.jobsRoster.handle(frame.args ?? {})
+      } catch (error) {
+        result = { ok: false, error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}) }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     let result
     try {
       result = await this.dsh.rpc(frame.method, frame.args ?? {})
@@ -831,12 +970,38 @@ export class DeviceRouter {
       record.readyValue = value
       this.#changed()
     }
+    this.#sendEventItem(deviceId, record, value)
+  }
+
+  /**
+   * 向一台设备投递一条 `$events` 形态的项（item，或未开流时的 event 帧）。
+   *
+   * 抽出来是为了让连接器自造的帧（`link/jobs`，见 `publishEvent`）与宿主事件走**同一段**
+   * 投递口径，帧语义不变：开了 `$events` 的按 dlpId 走 item，没开的按 event 广播。
+   */
+  #sendEventItem(deviceId, record, value) {
     for (const dlpId of record.dlpIds) this.send(deviceId, { t: 'item', id: dlpId, value })
     // Spec §4.1.5: every $events item is broadcast as an `event` frame until the
     // device opens the stream explicitly, so nothing is delivered twice.
     if (record.dlpIds.size === 0) this.send(deviceId, { t: 'event', value })
   }
 
+  /**
+   * 把一条连接器自造的项广播给**每台在线设备**（活动名单的 `link/jobs`，spec 018）。
+   *
+   * 与 `forwardEvent` 的区别是来源：那条项来自某台设备自己的 `$events` 流，只回给它；
+   * 这条是宿主任务事件的产物，没有归属设备，所以每台在线设备各收一份。
+   *
+   * **离线设备不推**：`$events` 还替它留着（见 `detachDevice`），但旧任务状态没有补发
+   * 意义——重连后手机重新问一次 `_link/jobRoster` 即可（契约 §3）。
+   */
+  publishEvent(value) {
+    for (const record of this.devices.values()) {
+      if (record.offlineSince !== undefined) continue
+      this.#sendEventItem(record.deviceId, record, value)
+    }
+  }
+
   /**
    * 要不要为这条 `$events` 项报一声（就是「提醒手机」）。
    *