dsh-plugin-mobile-link 0.6.0 → 0.6.5

package/lib/session-digest.js

@@ -0,0 +1,117 @@
+/**
+ * `_link/sessionDigest`：`session/list` 的精简同形副本（spec 021）。
+ *
+ * 为什么要有它：`session/list` 占经中转下行字节的 **96%**，一次固定 714 KB，而中转出口实测只有
+ * 16–112 KB/s（2026-10-13 现场诊断）。其中 **58.8% 的字节是 App/DSHKit 从来不读的字段**
+ * （逐字段扫 79 个源文件核对，清单见 `contracts/session-digest.md` §4）。
+ *
+ * 三条硬约束：
+ *   1. **不动 `session/list`**：老 App 只认它，字段删掉就没有回退路径。
+ *   2. **不改入参**：宿主返回什么就基于它生成新对象，方便"同一份数据两条路径"逐字节对比。
+ *   3. **只删名单里的**：名单之外的字段（包括以后宿主新增的）一律原样透传，避免"裁剪"变成"猜"。
+ */
+
+import { deflateRawSync } from 'node:zlib'
+
+/** 方法名（设备发起，中转不校验方法名，所以不需要中转改动）。 */
+export const SESSION_DIGEST_METHOD = '_link/sessionDigest'
+
+/** 会话项里剔掉的字段：零读取点（`agentAvailable` 1.8%）。 */
+export const DROPPED_ITEM_KEYS = Object.freeze(['agentAvailable'])
+
+/**
+ * 投影键里剔掉的字段（合计 56.7%）。
+ *
+ * 每一条都能在 App/DSHKit 里复查"零读取点"：
+ * `turnOutline` 33.4%（每轮 prompt/response 原文）、`imageLimits` 6.2%（上传限制）、
+ * `sessionStats` 4.2%、`todos` 2.6%、`subagentCatalog` 2.6%、`contextBreakdown` 2.5%、
+ * `sessionListMetadata` 1.9%（唯一被读的 `blank` 在顶层已有同名字段）、
+ * `subagentTiming` 1.5%、`agentPreset` 0.8%（`SessionCreateRequest.agentPreset` 是请求字段）。
+ */
+export const DROPPED_PROJECTION_KEYS = Object.freeze([
+  'turnOutline', 'imageLimits', 'sessionStats', 'todos', 'subagentCatalog',
+  'contextBreakdown', 'sessionListMetadata', 'subagentTiming', 'agentPreset',
+])
+
+/**
+ * 只接受的压缩编码；其它一律按不压缩处理（保守，不因为多写一个字段就让调用方失败）。
+ *
+ * `deflate-raw` = RFC1951 原始 DEFLATE，**不带** gzip/zlib 包装。选它而不是 gzip 的原因是
+ * 手机侧：Apple 的 `Compression` 框架（`COMPRESSION_ZLIB`）一行 `compression_decode_buffer`
+ * 就能解开原始 DEFLATE，而 gzip 包装它不认，得引 libz 的 `inflateInit2(MAX_WBITS+16)` 做 C 互操作。
+ * 两者压缩比实测相同（239 KiB → 36.8 KiB）。
+ */
+export const DEFLATE_ENCODING = 'deflate-raw'
+export const IDENTITY_ENCODING = 'identity'
+
+/** 按原键序复制并跳过剔除名单：键序稳定才能做"逐字节对比"。 */
+function omit(source, dropped) {
+  const out = {}
+  for (const key of Object.keys(source)) {
+    if (dropped.has(key)) continue
+    out[key] = source[key]
+  }
+  return out
+}
+
+/**
+ * 裁剪一份会话列表的**值**（`{ items: [...] }`）。
+ *
+ * 认两种输入（与 `trimHistoryPageForWire` 同款）：宿主信封 `{ ok, value: { items } }`，
+ * 以及直接给的 `{ items }`。**返回的始终是列表值本身**，调用方不需要再猜信封在哪一层
+ * （曾经因为这里保留信封、外面又包一层，响应成了 `{encoding, value:{ok, value:{items}}}`）。
+ *
+ * 结构不是预期的样子就**原样返回入参**——裁剪不许把"看不懂"变成"删掉"。
+ *
+ * @param {unknown} result 宿主响应或其 `value`
+ * @returns {unknown} 裁剪后的列表值；不合法时原样返回入参
+ */
+export function digestSessionList(result) {
+  if (result === null || typeof result !== 'object') return result
+  const container = Array.isArray(result.items) ? result : result.value
+  if (container === null || typeof container !== 'object' || !Array.isArray(container.items)) {
+    return result
+  }
+  return { ...container, items: container.items.map(digestItem) }
+}
+
+/** 单条会话：剔顶层字段与投影键；`projections` 缺失或形状不对就原样留着。 */
+function digestItem(item) {
+  if (item === null || typeof item !== 'object') return item
+  const out = omit(item, new Set(DROPPED_ITEM_KEYS))
+  const projections = item.projections
+  if (projections === null || typeof projections !== 'object') return out
+  // `kind: "sequenced"` 是信封常量，App 侧模型没解码它（1.3%）。
+  const envelope = omit(projections, new Set(['kind']))
+  const values = projections.values
+  if (values !== null && typeof values === 'object') {
+    envelope.values = omit(values, new Set(DROPPED_PROJECTION_KEYS))
+  }
+  out.projections = envelope
+  return out
+}
+
+/**
+ * 按调用方要求编码裁剪后的值。
+ *
+ * **只在应用层压**：中转的 `WebSocketResponse(compress=False)`，手机侧
+ * `URLSessionWebSocketTask` 也不支持 permessage-deflate，所以 WS 层压缩救不了手机那一跳。
+ * 压缩后的字节 base64 放进 JSON 文本帧（与 `_link/diagnostics` 同款），中转不需要任何改动。
+ *
+ * `rawBytes` 是**解压后的字节长度**：Apple 的 `compression_decode_buffer` 必须预先给足输出缓冲区，
+ * 带上它调用方就能一次分配到位，不必"猜容量、失败再翻倍重试"。
+ *
+ * @param {unknown} value 裁剪后的值
+ * @param {unknown} encoding 调用方要求；只认 `"deflate-raw"`
+ * @returns {{encoding: string, value: unknown, rawBytes?: number}} 带回执，调用方据此决定解不解压
+ */
+export function encodeDigest(value, encoding) {
+  if (encoding !== DEFLATE_ENCODING) return { encoding: IDENTITY_ENCODING, value }
+  const json = JSON.stringify(value ?? null)
+  const raw = Buffer.from(json, 'utf8')
+  return {
+    encoding: DEFLATE_ENCODING,
+    value: deflateRawSync(raw).toString('base64'),
+    rawBytes: raw.length,
+  }
+}

package/lib/status.js

@@ -33,8 +33,7 @@ export const HOST_HINTS = {
   unknown: { hint: '无法识别当前宿主；若连不上，请按"排查"一节处理', docAnchor: '排查：连不上时看这里' },
 }
 
-/** 本机 DSH 侧的诊断块（老字段一个不少，新字段只增）。 */
-function dshBlock(agent) {
+/** 本机 DSH 侧的诊断块（老字段一个不少，新字段只增）。 */function dshBlock(agent) {
   const errorKind = agent.dshError ? (agent.dsh?.errorKind ?? 'unreachable') : null
   const entry = errorKind ? DSH_HINTS[errorKind] : undefined
   return {
@@ -51,6 +50,31 @@ function dshBlock(agent) {
   }
 }
 
+/**
+ * 生命周期流水的读法（只增字段）。
+ *
+ * 为什么状态接口要给这一块：`lastError` 只有最后一条，而"手机为什么连不上"往往要
+ * 看**之前**发生过什么（拆了几次链、每次什么原因、设备是不是同时开了两条）。
+ *
+ * 读法要说清楚：`recent` / `recorded` / `dropped` 都是**当前这个实例**的（热更会换实例，
+ * 换完这几个数从零开始）；跨实例的完整历史只在 `path` 指的 JSONL 文件里——两者互补，
+ * 别拿 `recorded` 当"这台机器一共连过几次"。没有流水对象（老调用方、单测的假 agent）
+ * 时给空块，不是 `undefined`——读者不用做判空。
+ */
+function journalBlock(agent) {
+  const journal = agent.journal
+  return {
+    path: journal?.path ?? null,
+    recorded: journal?.recorded ?? 0,
+    dropped: journal?.dropped ?? 0,
+    fileErrors: journal?.fileErrors ?? 0,
+    recent: journal?.recent?.(STATUS_JOURNAL_ENTRIES) ?? [],
+  }
+}
+
+/** `/status` 里随每次轮询带出的流水条数。完整历史读 `journal.path` 那个文件。 */
+const STATUS_JOURNAL_ENTRIES = 20
+
 /**
  * @param {import('./link.js').MobileLinkAgent} agent
  * @returns {Record<string, unknown>} 可直接序列化给 `/status` 的对象
@@ -97,5 +121,7 @@ export function statusSnapshot(agent) {
     startedAt: agent.startedAt ?? null,
     connectedAt: agent.connectedAt ?? null,
     reconnectAttempts: agent.reconnectAttempts,
+    // 新增（只增不改）：生命周期流水的摘要与最近若干条，见上面的 journalBlock。
+    journal: journalBlock(agent),
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.6.0",
+  "version": "0.6.5",
   "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",

package/lib/history/probe.js

@@ -1,195 +0,0 @@
-import { HOST_CALL_TIMEOUT_MS, withTimeout, messageOf } from './shared.js'
-import { bytesOf, summarizeEvents } from './records.js'
-
-/**
- * 只读测量（spec 007 T008/T047）：`GET /mobile-link/history-probe` 用，锁定映射之后删。
- *
- * 它只读、不改任何状态；`getQuery` 是个取值函数而不是服务对象本身，因为宿主注入
- * （`ctx.inject(['sessionQuery'])`）可能在服务建好之后才发生。
- */
-export function createProbeRunner({ getQuery, logger }) {
-  return async function probe(args = {}) {
-  const sessionId = args.sessionId
-  if (typeof sessionId !== 'string' || sessionId.length === 0) {
-    return { ok: false, error: 'sessionId is required' }
-  }
-  if (getQuery() === undefined) {
-    return { ok: false, error: 'ctx.getQuery() is not mounted in this Host' }
-  }
-  const limit = Number.isFinite(Number(args.n)) && Number(args.n) > 0 ? Number(args.n) : 60
-  const out = { ok: true, sessionId, limit }
-
-  // 1. Whole log: how many events, and is log position == seq?
-  const t0 = Date.now()
-  try {
-    const records = await withTimeout(getQuery().listEvents(sessionId), HOST_CALL_TIMEOUT_MS, 'listEvents')
-    const mismatches = []
-    records.forEach((record, index) => {
-      if (record.seq !== index && mismatches.length < 5) mismatches.push({ index, seq: record.seq })
-    })
-    out.listEvents = {
-      ...summarizeEvents(records),
-      ms: Date.now() - t0,
-      offsetEqualsSeq: mismatches.length === 0,
-      firstMismatches: mismatches,
-    }
-  } catch (error) {
-    out.listEvents = { ms: Date.now() - t0, error: messageOf(error) }
-  }
-
-  // 2. Exact window read around a seq (`readEvent`): raw events, contiguous.
-  const targetSeq = Number.isFinite(Number(args.seq)) ? Number(args.seq) : out.listEvents?.lastSeq
-  if (Number.isInteger(targetSeq) && targetSeq >= 0) {
-    const t1 = Date.now()
-    try {
-      const window = await withTimeout(
-        getQuery().readEvent({ sessionId, seq: targetSeq, before: limit, after: 0 }),
-        HOST_CALL_TIMEOUT_MS,
-        'readEvent',
-      )
-      out.readEvent = {
-        requested: { seq: targetSeq, before: limit, after: 0 },
-        ...summarizeEvents(window.events),
-        startSeq: window.startSeq ?? null,
-        endSeq: window.endSeq ?? null,
-        rawEventCount: window.events?.length ?? 0,
-        bytes: bytesOf(window.events),
-        ms: Date.now() - t1,
-      }
-    } catch (error) {
-      out.readEvent = { requested: { seq: targetSeq, before: limit }, ms: Date.now() - t1, error: messageOf(error) }
-    }
-  }
-
-  // 3. Seq-range filter (`filterEvents`): message-aligned semantic documents.
-  if (Number.isInteger(targetSeq) && targetSeq >= 0) {
-    const from = Math.max(0, targetSeq - limit + 1)
-    const t2 = Date.now()
-    try {
-      const docs = await withTimeout(
-        getQuery().filterEvents(sessionId, [{ kind: 'seq', from, to: targetSeq }]),
-        HOST_CALL_TIMEOUT_MS,
-        'filterEvents(seq)',
-      )
-      out.filterEventsSeq = {
-        requested: { from, to: targetSeq },
-        ...summarizeEvents(docs),
-        bytes: bytesOf(docs),
-        sample: docs.slice(0, 2).map((doc) => ({ seq: doc.seq, type: doc.type, textLen: doc.text?.length ?? 0 })),
-        ms: Date.now() - t2,
-      }
-    } catch (error) {
-      out.filterEventsSeq = { requested: { from, to: targetSeq }, ms: Date.now() - t2, error: messageOf(error) }
-    }
-  }
-
-  // 4. Literal text scan (`filterEvents(text)`): the fallback for search when
-  //    the full-text index is closed (base bundle ships `openAt: never`).
-  if (typeof args.text === 'string' && args.text.length > 0) {
-    const t3 = Date.now()
-    try {
-      const docs = await withTimeout(
-        getQuery().filterEvents(sessionId, [{ kind: 'text', text: args.text }]),
-        HOST_CALL_TIMEOUT_MS,
-        'filterEvents(text)',
-      )
-      out.filterEventsText = {
-        query: args.text,
-        ...summarizeEvents(docs),
-        sample: docs.slice(0, 3).map((doc) => ({
-          seq: doc.seq,
-          type: doc.type,
-          textLen: doc.text?.length ?? 0,
-          head: (doc.text ?? '').slice(0, 60),
-        })),
-        ms: Date.now() - t3,
-      }
-    } catch (error) {
-      out.filterEventsText = { query: args.text, ms: Date.now() - t3, error: messageOf(error) }
-    }
-  }
-
-  // 5. Indexed search (`searchEvents`): expected to fail while the SQLite
-  //    index is closed, which is why step 4 must be able to carry search.
-  if (typeof args.text === 'string' && args.text.length > 0) {
-    const t4 = Date.now()
-    try {
-      const page = await withTimeout(
-        getQuery().searchEvents({ sessionId, query: args.text, limit: 20 }),
-        HOST_CALL_TIMEOUT_MS,
-        'searchEvents',
-      )
-      out.searchEvents = {
-        query: args.text,
-        count: page.items?.length ?? 0,
-        hasMore: page.hasMore ?? null,
-        first: page.items?.[0] ? { seq: page.items[0].seq, type: page.items[0].type } : null,
-        ms: Date.now() - t4,
-      }
-    } catch (error) {
-      out.searchEvents = { query: args.text, ms: Date.now() - t4, error: messageOf(error) }
-    }
-  }
-
-  // 7. Chunked literal scan: `filterEvents(text)` returns every match with its
-  //    full text, so the connector must bound each call by a seq range and
-  //    stop at the requested hit count. This measures that shape.
-  if (typeof args.text === 'string' && args.text.length > 0 && Number.isInteger(out.listEvents?.lastSeq ?? null)) {
-    const chunk = Number.isFinite(Number(args.chunk)) && Number(args.chunk) > 0 ? Number(args.chunk) : 2000
-    const wanted = Number.isFinite(Number(args.hits)) && Number(args.hits) > 0 ? Number(args.hits) : 50
-    const lastSeq = out.listEvents.lastSeq
-    const t6 = Date.now()
-    const hits = []
-    let calls = 0
-    let to = lastSeq
-    try {
-      while (to >= 0 && hits.length < wanted && calls < 50) {
-        const from = Math.max(0, to - chunk + 1)
-        const docs = await withTimeout(
-          getQuery().filterEvents(sessionId, [
-            { kind: 'seq', from, to },
-            { kind: 'text', text: args.text },
-          ]),
-          HOST_CALL_TIMEOUT_MS,
-          `filterEvents(chunk ${from}-${to})`,
-        )
-        calls++
-        for (const doc of docs) {
-          if (hits.length >= wanted) break
-          hits.push({ seq: doc.seq, type: doc.type, textLen: doc.text?.length ?? 0 })
-        }
-        to = from - 1
-      }
-      out.chunkedText = {
-        query: args.text,
-        chunk,
-        calls,
-        hits: hits.length,
-        firstSeq: hits[0]?.seq ?? null,
-        lastSeq: hits[hits.length - 1]?.seq ?? null,
-        scannedFrom: to + 1,
-        ms: Date.now() - t6,
-      }
-    } catch (error) {
-      out.chunkedText = { query: args.text, calls, hits: hits.length, ms: Date.now() - t6, error: messageOf(error) }
-    }
-  }
-
-  // 6. Cold read: no Agent activation. `readSession` returns the log snapshot.
-  const t5 = Date.now()
-  try {
-    const snapshot = await withTimeout(getQuery().readSession(sessionId), HOST_CALL_TIMEOUT_MS, 'readSession')
-    out.readSession = {
-      events: snapshot.events?.length ?? null,
-      startSeq: snapshot.startSeq ?? null,
-      endSeq: snapshot.endSeq ?? null,
-      headerKeys: snapshot.session ? Object.keys(snapshot.session).slice(0, 8) : [],
-      ms: Date.now() - t5,
-    }
-  } catch (error) {
-    out.readSession = { ms: Date.now() - t5, error: messageOf(error) }
-  }
-
-  return out
-  }
-}