dsh-plugin-mobile-gateway 0.10.2 → 0.10.4

package/PROTOCOL.md

@@ -1,6 +1,8 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现。当前源码适配 DSH 0.2.0-rc.2 / Session format 4；移动端实时流接入见 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md)，插件管理见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+移动端通过经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现。当前源码适配 DSH 0.2.1-rc.2 / Session format 4；移动端实时流接入见 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md)，插件管理见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+
+DSH Remote 要求的 `peer` 由网关在 Host 内部创建并注入，身份沿用已配对设备的本机用户权限，生命周期随插件释放；移动端请求帧不增加 `peer` 字段，`dsh-mobile-v1` 协议不变。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -661,6 +663,21 @@ let image = [
 | `tasks` | `sessionId` | 当前任务列表（`todos` projection） |
 | `goal` | `sessionId` | 当前目标及其 CAS 版本（`goal` projection） |
 
+### 会话列表投影
+
+`sessions.items[]` 保留 Host 返回的会话元信息（包括 `sessionId`、`updatedAt`、`running`、`blank`、`cwd`、`agentPreset`、`parentSessionId` 和 `origin`）。每项 `projections` 仅保留原有的 `asOfSeq` 和 `values.title`，不随列表下发大纲、任务、上下文等完整投影，避免大量会话导致公网隧道传输超时。标题仍从 `projections.values.title` 读取，缺失或 `null` 时沿用客户端的默认标题规则。
+
+```json
+{ "type": "sessions" }
+→ { "kind": "sessions", "items": [
+    { "sessionId": "session-abc", "updatedAt": 1786937352, "running": false, "blank": false,
+      "cwd": "/workspace", "agentPreset": "standard",
+      "projections": { "asOfSeq": 200, "values": { "title": "排查网关连接" } } }
+  ] }
+```
+
+此裁剪仅用于 `sessions` 响应，不修改 Host 数据；`history`、`session-snapshot`、控制投影基线及实时投影通知继续提供各自原有的详情。现有客户端无需修改请求或标题解析方式。
+
 ### Session 归档与重命名
 
 在 App 端归档 Session：
@@ -706,9 +723,26 @@ WebUI、App 或其他客户端造成的变化通过以下帧主动推送：
 - `view: "conversation"`：**对话裁剪模式**——隐藏系统消息与 request/header、request/context，移除 Assistant 事件的内嵌 `data.stream`，同时保留 `data.finish`（结束类型和结构化失败原因）；`tool/result` 原始文本块截断到 2000 字符，另用 `data.output/outputTruncated` 保留最多约 16000 字符的首尾输出
 - 分页：`hasMore` 为真时用 `beforeSeq: nextBeforeSeq, historyFormatVersion: 4` 请求更早一页
 
+### 会话轮次大纲
+
+`hello.capabilities` 的 `turn-outline-v1` 表示支持完整轮次大纲传输；不要求 Host 开启全文搜索，也不保证自定义 Host profile 挂载了大纲插件。App 可从 `history` / `session-snapshot` 的 `projections.values.turnOutline` 读取数组，每项为 `{turn, seq, prompt, response}`；`seq` 指向 `turn/start`，提示词和回复分别最多 50 / 120 个 UTF-16 code unit，回复在轮次结束后提交。正文分页和字节裁剪不会裁掉大纲。
+
+控制连接（兼容 legacy 单连接）的 `projection-baseline.projections[sessionId].values` 新增 `turnOutline`，缺少该投影时为 `null`。Host 大纲变化时发送完整替换值：
+
+```json
+{ "kind": "turn-outline-updated", "sessionId": "s1", "asOfSeq": 40,
+  "turnOutline": [{ "turn": 1, "seq": 10, "prompt": "调整输入框阴影", "response": "已减轻阴影。" }] }
+```
+
+该通知不受 `subscribe.sessionId` 过滤，不发往 conversation 连接。`[]` 为有效空大纲；`null` 使旧控制大纲失效并降级到已加载轮次。Host 控制流重建会整体替换基线，并为被移除会话发送 `null` 失效通知，沿用其旧缓存水位。控制基线只覆盖 Host 当前控制集合，缺少冷会话不表示会话被删除；进入冷会话仍从其历史快照读取大纲。新控制连接会获得最近缓存的大纲。
+
+`asOfSeq` 是投影切点，不是连续通知序列。数组整体替换，不能 append；App 需处理控制基线代际与历史响应乱序。完整帧示例、触屏交互、分页跳转、版本重建和验收步骤见 [App 会话轮次导航接入指南](docs/turn-outline-app-integration.md)。
+
+### `history` 响应示例
+
 ```json
 → { "kind": "history", "sessionId": "session-abc", "events": [ ...原始事件... ],
-    "historyFormatVersion": 3, "cursor": 200,
+    "historyFormatVersion": 4, "cursor": 200,
     "bytes": 3521, "view": "conversation", "hasMore": true, "nextBeforeSeq": 128,
     "projections": { "asOfSeq": 200, "values": { "tokenUsage": {...}, "contextPressure": {...}, "permissions": {...}, "sessionStats": {...} } } }
 ```
@@ -1108,6 +1142,8 @@ Control/旧单连接接收全局模式状态增量，不受所订阅会话过滤
 | `session-archives` | Host 的完整 Session 归档集合在连接初始化或 WebUI/App 归档后变化 |
 | `session-title-changed` | 任意客户端写入新的持久化 Session 名称 |
 | `tasks-updated` / `goal-updated` | 当前会话的任务列表或目标 projection 发生变化 |
+| `projection-baseline` | 控制投影集合，含 `todos/goal/turnOutline`；连接初始化及 Host 控制流重建时发送 |
+| `turn-outline-updated` | 指定 Session 的完整轮次大纲替换值或 `null` 失效通知；仅控制/legacy 连接 |
 | `schedule-changed` | Host 定时任务目录已变化；无载荷，重新请求 `schedule-catalog` 或当前 Session 的 `schedule-list` |
 | `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
 | `approval-requested` / `approval-resolved` | Human-in-the-loop 操作审批请求与最终状态 |
@@ -1175,7 +1211,9 @@ DSH Web 的“深度求索中，用时 22 秒 ···”是客户端文案，不
 
 | 版本 | 新增 |
 |---|---|
-| v0.10.2（当前源码） | 补齐 `deliverables/presented` 文件卡片实时字段；新增 `file-references-v1` 能力与 `file-resolve` 安全文件引用解析；复用现有分块下载支持移动端预览接入 |
+| v0.10.4（当前源码） | 精简 `sessions` 列表投影，仅保留 `asOfSeq` 和 `values.title`，修复大量会话通过公网隧道传输时超时的问题；保留会话元信息和历史完整投影，现有移动客户端无需配套修改 |
+| v0.10.3 | 适配 DSH 0.2.1-rc.2；为 Remote 请求及实时订阅补齐 Connection Peer，修复读取 `signal` 时的空值报错，并随网关停止释放 Peer；移动端协议保持不变 |
+| v0.10.2 | 补齐 `deliverables/presented` 文件卡片实时字段；新增 `file-references-v1` 能力与 `file-resolve` 安全文件引用解析；复用现有分块下载支持移动端预览接入 |
 | v0.10.1 | 新增官方 speech Remote 语音输入桥接；模型准备与状态同步；移动端音频转文字与取消转写；连接关闭时清理语音任务 |
 | v0.10.0 | 响应式居中控制面板与主题同步；自定义下拉菜单；独立配对模态窗口与缩放动画；按运行实例关闭重启提醒；在线设备折叠列表与移动端设备名称上报；Tunnel 配置交互优化 |
 | v0.9.0 | DSH 0.2.0-rc.2 插件管理；PC 端 Cloudflare Quick / 命名 Tunnel 及独立重启；插件私有 `cloudflared` 缓存及校验；配对入口选择指引；网关重启与 DSH Web 停止工具 |

package/README.md

@@ -6,11 +6,15 @@
 
 DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排队消息同步及编辑/删除/Steer、Session 归档和重命名的双向同步、停止当前生成并稍后继续、任务列表和当前 Goal 同步及管理、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
 
-> 当前源码以 **DSH 0.2.0-rc.2** 为适配基线，使用 Session format 4；旧版历史游标需重新取得基线。
+> 当前源码以 **DSH 0.2.1-rc.2** 为适配基线，需要 Connection Peer 接口，使用 Session format 4；旧版历史游标需重新取得基线。
 >
 > 实时流已改为独立 `assistant-stream` 帧，移动端需要按 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md) 更新订阅、缓存与分页处理。当前修改尚未发布。
 >
-> v0.10.2（当前源码）：新增文件卡片事件透传与安全文件引用解析，复用现有分块下载，为移动端文件卡片和正文文件链接预览提供协议支持。App 接入方式见 [文件卡片与预览接入说明](docs/file-cards-mobile-integration.md)。
+> v0.10.4（当前源码）：精简会话列表投影，仅保留标题与投影切点，修复大量会话通过公网隧道传输时超时的问题；保留会话元信息和历史完整投影，现有移动客户端无需配套修改。
+>
+> v0.10.3：适配 DSH 0.2.1-rc.2，为 Remote 请求及实时订阅补齐 Connection Peer，修复 `Cannot read properties of undefined (reading 'signal')` 报错，并在网关停止时释放 Peer。移动端协议保持不变。
+>
+> v0.10.2：新增文件卡片事件透传与安全文件引用解析，复用现有分块下载，为移动端文件卡片和正文文件链接预览提供协议支持。App 接入方式见 [文件卡片与预览接入说明](docs/file-cards-mobile-integration.md)。
 >
 > v0.10.1：新增官方语音输入接入，支持语音模型准备与状态同步、移动端音频转文字、取消转写及连接关闭后的任务清理。通过官方 speech Remote 处理识别，移动网关无需打包 ASR 模型。
 >
@@ -24,7 +28,15 @@ DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排
 
 ## 协议与 DSH 兼容层
 
-移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH 0.2.0-rc.2 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals、Schedule、Permission Presets、Plugin Manager 等 namespace 和严格参数只存在于该适配层。插件管理的请求帧及 DSH Mobile 页面方案见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH 0.2.1-rc.2 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals、Schedule、Permission Presets、Plugin Manager 等 namespace 和严格参数只存在于该适配层。插件管理的请求帧及 DSH Mobile 页面方案见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+
+DSH 0.2.1-rc.2 要求每次 Remote 调用携带 `peer`。网关通过 `ctx.connection.createPeer()` 创建一个随插件释放的本机用户 Peer，普通请求、首帧读取和实时订阅都由 Host Adapter 注入它；移动端不能设置调用方身份。问答与审批继续由网关的 Host 监听器处理。旧网关漏传此字段时会出现 `Cannot read properties of undefined (reading 'signal')`，升级 DSH 后需重新安装本源码版本并重启 `dsh web`，手机无需更改协议。
+
+可用本机已安装的官方 DSH 验证此契约（真实 Gateway / Connection，业务服务使用测试数据，不读写用户会话）：
+
+```bash
+DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/host-official.test.mjs
+```
 
 配对鉴权和 `dsh-mobile-v1` / `hello.protocol = 3` 保持不变。新版实时 token 不占用持久事件的 `seq`：客户端显式订阅 `assistantStream: true`，接收原子的 `session-snapshot` 和独立增量；普通 `event` 只携带持久事件。未接入新订阅的客户端只能收到持久消息。
 
@@ -38,6 +50,8 @@ DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排
 
 当前源码新增会话模式选择：App 创建空白 Session 后，可查询并修改该 Session 的 Agent preset；首次对话后锁定。通过 `session-agent-preset` 能力发现接入，详见 [App 接入说明](docs/session-agent-preset-app-integration.md)。App 界面需按此说明接入，本次源码尚未发布。
 
+当前源码新增 `turn-outline-v1`：透传 WebUI 使用的完整轮次大纲及实时更新，支持 App 在未加载全部正文时展示会话刻度、问答预览并按需分页跳转。控制连接重建和新设备连接会恢复大纲基线；Host 未提供大纲时可降级为已加载轮次导航。详见 [App 会话轮次导航接入指南](docs/turn-outline-app-integration.md)。App 界面需单独接入，本次源码尚未发布。
+
 ## 多网关第一阶段（当前源码）
 
 插件提供稳定 `gatewayId`、可配置 `gatewayName`、配对候选地址列表，以及可持久化的“关闭 / 临时开启 / 常驻开启”运行模式。一个 App 可以分别配对不同机器上的网关；客户端多网关管理仍需按 [App 对接说明](docs/multi-gateway-app-integration.md) 实现。本次源码尚未发布新的 npm 版本。

package/docs/turn-outline-app-integration.md

@@ -0,0 +1,196 @@
+# App 会话轮次导航接入指南
+
+## 接入目标
+
+使用 DSH 的 `turnOutline` 投影，实现 WebUI 的会话刻度导航、问答预览和点击跳转。服务端提供整场会话的大纲，App 只加载当前需要的正文；无需先下载全部历史，也不依赖全文搜索或 WCDB。WCDB 可以用于后续离线缓存。
+
+适用基线为 DSH 0.2.1-rc.2、`dsh-mobile-v1`、`hello.protocol: 3`、Session format 4。本次是向后兼容的协议扩展；App 界面和本地存储需要单独实现。
+
+## 能力发现与数据结构
+
+检查 `hello.capabilities` 是否包含 `turn-outline-v1`。它表示网关支持大纲快照和控制流更新的传输，不保证 Host 已挂载 `@deepseek-ai/dsh-session-turn-outline`。官方 Web profile 已组合此插件，自定义 profile 可能没有。
+
+投影值为按 `turn` 严格递增的完整数组：
+
+```json
+[
+  { "turn": 1, "seq": 10, "prompt": "调整输入框阴影", "response": "已减轻阴影，保留轻微悬浮感。" },
+  { "turn": 2, "seq": 30, "prompt": "再缩小一点", "response": "" }
+]
+```
+
+| 字段 | 语义 |
+|---|---|
+| `turn` | Host 分配的非负轮次号；不要假定必须从 1 开始或连续 |
+| `seq` | 该轮 `turn/start` 的持久事件序号，用于向前补齐历史 |
+| `prompt` | 首条来源为 `user` 的人类文本预览，文本块以空格连接并折叠空白，最多 50 个 UTF-16 code unit，截断带省略号 |
+| `response` | 最后一条有文本的助手消息预览，最多 120 个 UTF-16 code unit，在 `turn/end` 后提交 |
+
+预览直接来自正文，不是 AI 摘要。注入上下文和工具结果不填充提示词预览；同轮后续 steering 不覆盖首条提示词。纯图片输入可以没有提示词文本，应显示“第 N 轮”等本地化占位。空回复可能表示轮次仍在运行或该轮没有助手文本，不能只据此推断生成状态。
+
+建议共享模型中的 `turn`、`seq`、`asOfSeq` 使用 `Long`。JSON 数值按非负安全整数校验，`asOfSeq` 另允许空日志切点 `-1`。按网关 ID、会话 ID 和历史格式版本隔离缓存，不把其他网关相同 session ID 的记录混用。
+
+## 快照与实时更新
+
+### 当前会话快照
+
+沿用对话连接的现有原子订阅：
+
+```json
+{ "type": "subscribe", "sessionId": "s1", "assistantStream": true }
+```
+
+`session-snapshot` 中读取 `projections.values.turnOutline`：
+
+```json
+{
+  "kind": "session-snapshot",
+  "sessionId": "s1",
+  "subscriptionId": "sub-1",
+  "streamId": "stream-1",
+  "replace": true,
+  "historyFormatVersion": 4,
+  "cursor": 35,
+  "events": [],
+  "hasMore": true,
+  "nextBeforeSeq": 30,
+  "projections": {
+    "asOfSeq": 35,
+    "values": {
+      "turnOutline": [
+        { "turn": 1, "seq": 10, "prompt": "调整输入框阴影", "response": "已减轻阴影。" },
+        { "turn": 2, "seq": 30, "prompt": "再缩小一点", "response": "" }
+      ]
+    }
+  },
+  "assistantStream": { "revision": 0 }
+}
+```
+
+示例省略正文内容。`events` 和大纲是两份独立数据：首帧正文限制为最新窗口，大纲仍包含全部已开始的轮次，不随正文预算裁剪。普通 `history` 响应也保留相同的投影。
+
+不建立实时订阅、只需要查询大纲时，可以在控制连接发送现有请求：
+
+```json
+{ "type": "history", "sessionId": "s1", "maxMessages": 1, "view": "conversation" }
+```
+
+这会返回少量最新正文和当前投影，不会加载全部历史。它不是无正文专用接口；不要用这样的响应替换已安装的完整聊天窗口，只提取投影即可。
+
+### 控制连接基线
+
+控制连接和 legacy 单连接初始化时收到 `projection-baseline`；Host 控制流重建后再次收到完整基线：
+
+```json
+{
+  "kind": "projection-baseline",
+  "projections": {
+    "s1": {
+      "asOfSeq": 35,
+      "values": {
+        "todos": [],
+        "goal": null,
+        "turnOutline": [
+          { "turn": 1, "seq": 10, "prompt": "调整输入框阴影", "response": "已减轻阴影。" }
+        ]
+      }
+    }
+  }
+}
+```
+
+这是 Host 当前控制流所覆盖会话的集合，通常为已附着的会话，不是磁盘上所有历史会话的目录。冷会话进入页面后仍需从自身的 `history` 或 `session-snapshot` 取得投影。基线中缺少某个 session 不表示删除该会话或其本地正文。
+
+App 应整体替换来自控制流的基线集合。首次连接时网关可能先发送空的缓存集合，稍后再发送上游基线；不能把首个空集合视为“没有历史会话”。重建后不在集合内的旧控制状态应失效，必要时为当前页面重新取得会话快照。
+
+### 大纲更新通知
+
+```json
+{
+  "kind": "turn-outline-updated",
+  "sessionId": "s1",
+  "asOfSeq": 40,
+  "turnOutline": [
+    { "turn": 1, "seq": 10, "prompt": "调整输入框阴影", "response": "已减轻阴影。" },
+    { "turn": 2, "seq": 30, "prompt": "再缩小一点", "response": "已缩小阴影范围。" }
+  ]
+}
+```
+
+- 通知携带完整数组，整体替换对应会话的大纲，不能 append 或按数组下标拼接。
+- 发往控制连接和 legacy 单连接，不发往 conversation 连接，也不受该连接的 `subscribe.sessionId` 过滤。必须按 `sessionId` 分发，不能直接写入当前页面。
+- 新控制连接的 `projection-baseline` 包含网关最近收到的大纲；其他投影更新不会覆盖它。
+- `asOfSeq` 是上游投影对应的持久日志切点，不是独立通知流水号，不能要求连续或用它推进对话事件游标。
+- Host 每轮通常至多更新三次大纲：开轮、首条提示词、落定回复；流式 token 不会触发大纲逐字更新。已加载轮次可以使用本地消息提供即时预览。
+
+大纲值的清空与缺省规则：
+
+| 值或情形 | App 行为 |
+|---|---|
+| `[]` | 有效的空大纲，整体替换旧数组 |
+| `null` | 当前控制源不提供该大纲，清除其旧值，退回已加载轮次导航 |
+| 控制基线中的投影缺失 | 网关会规范化为 `turnOutline: null` |
+| 会话快照中该键缺失 | Host 不提供此投影，使用已加载轮次；不要伪造完整历史 |
+| 重建基线不再包含旧 session | 控制状态失效；网关另发送该 session 的 `turn-outline-updated`，值为 `null` |
+
+会话从控制基线消失时发出的 `null` 是失效通知，使用旧缓存的水位，不代表新的日志事件。它与新基线一起处理，不应用普通增量的水位规则忽略失效。冷会话可重新读取自己的快照恢复大纲。
+
+## App 状态与乱序处理
+
+建议将以下状态放在 KMM 共享层，由 Android 和 iOS 分别渲染：
+
+- `TurnOutlineStore`：服务器大纲、来源、投影水位及连接代际。
+- `TurnNavigationIndex`：合并服务器大纲与已加载轮次，生成有正文锚点的 `loaded` 项及只有 `seq` 的 `unloaded` 项。
+- `TurnJumpCoordinator`：目标轮次、目标 `seq`、加载状态、可取消的跳转代际。
+
+合并规则与 WebUI 一致：以 `turn` 为键取两侧并集并升序排列；有已加载节点则优先使用其正文锚点，非空的本地预览覆盖服务端预览，本地预览为空时回退服务端。没有可见正文节点时保留服务端 `seq`，标为未加载。渲染锚点应是稳定节点 ID，不是易变的列表下标。
+
+在同一连接代际内，对每个会话的 `turnOutline` 单独记录 `asOfSeq`，忽略水位更小的普通快照或更新，相同水位重复值幂等处理。不要把任务或 Goal 的水位作为大纲水位：不同投影可能更新于不同事件。
+
+收到新 `projection-baseline` 时开启新的控制基线代际并替换其集合；这是权威重建，可能使旧缓存失效。控制连接与对话连接各有代际，切网关、断线重连、订阅替换后应丢弃属于旧代际的回调。会话快照必须匹配当前 `sessionId/subscriptionId/streamId`，跨通道的旧历史响应不能覆盖新大纲或当前聊天窗口。
+
+历史格式改变或出现 `history-format-mismatch` 时，清理该会话旧大纲的 `seq`、分页游标、跳转任务及旧格式消息缓存，再取得新基线；不能只把旧坐标的版本号改成 4 后重试。
+
+## 点击轮次与加载历史
+
+已加载项直接滚动到该轮用户消息；无用户节点时滚动到该轮第一个可见节点。历史分页插入头部、图片或 Markdown 改变高度时，应保持语义锚点及其偏移，避免页面跳动。
+
+未加载项按以下步骤处理：
+
+1. 记录目标 `turn/seq` 和新的跳转代际，暂停自动跟随底部，显示该轮的加载状态。
+2. 复用当前历史窗口的 `nextBeforeSeq` 向前分页。请求示例：
+
+   ```json
+   { "type": "history", "sessionId": "s1", "beforeSeq": 300, "historyFormatVersion": 4, "maxMessages": 200, "view": "conversation" }
+   ```
+
+3. 按 `sessionId + seq` 合并、去重更早页，更新分页游标。目标 `turn/start` 进入连续补齐的历史覆盖范围后，再解析该轮消息锚点；不能仅凭本地最小 seq 判断已覆盖，因为重连缓存可能有缺口。
+4. 未到达目标且 `hasMore: true` 时继续，必须确认 `nextBeforeSeq` 严格减小。即使可见 `events` 为空，仍使用服务端返回的有效游标继续，不以数组为空判断结束。
+5. 布局提交后滚动到目标锚点，清除加载状态。用户再次选轮次时，只允许最新跳转执行滚动；已有历史请求可以完成并缓存，但不能把页面拉回旧目标。
+6. 会话切换、网络错误、历史到头或游标不前进时结束循环并允许重试。未能恢复目标节点时，不显示“跳转成功”。
+
+历史响应目前不提供独立请求 ID 的关联保证。同一会话的普通上拉加载与跳转加载需要串行协调，不要为同一 session 并发启动多个无法区分的 `history` 请求。已安装实时快照后，历史页只补充历史区域，不替换实时消息。
+
+网关当前只开放 `maxMessages`，未开放 WebUI 内部的 `turnWindow` 参数，也没有任意锚点附近直接读取的新接口。`200` 是 App 的起始批量建议，不是协议固定值；需要服从响应实际 `hasMore/nextBeforeSeq` 和字节预算。远距离跳转可能需要多次请求。
+
+## 触屏交互与降级
+
+WebUI 使用固定间距刻度和虚拟列表，悬停或键盘焦点显示一行提示词与至多三行回复；点击才跳转。它在窄屏隐藏导航，App 应独立适配触屏：扩大触摸区域，按住或拖动时显示预览，松手确认跳转，并允许取消。轮次较多时虚拟化刻度，不必同时创建全部消息视图。
+
+没有 `turn-outline-v1`、Host 缺少投影或收到 `null` 时，只展示已加载轮次。纯图片轮次使用编号；隐藏的工具轨迹不填充问答预览。书签持久化、全文搜索、智能摘要与本功能独立，不由本协议扩展提供。
+
+完整大纲每次整值传输，大小随轮次数增长。正文预算不限制投影大小，大量会话或数千轮历史应关注客户端帧上限及内存，后续再根据实测引入大纲分页；不要把当前方案描述成恒定大小。
+
+## 验收与源码入口
+
+- 正文只加载尾部窗口时，仍显示全部已知轮次及问答预览。
+- 新轮次开轮、提示词落日志、回复落定后均能更新；流式期间没有逐 token 的整大纲写入。
+- 已加载轮次立即定位；未加载轮次连续补页到目标，期间阅读位置稳定。
+- 连续点击不同轮次、切会话、断线重连和历史版本改变后，旧回调不能触发错误滚动。
+- `[]` 清空，`null` 降级，控制基线缺键或移除 session 后旧控制大纲失效；会话正文和磁盘冷会话不被误删。
+- 控制连接收到更新，对话连接只接收自己的快照；新设备恢复最近的大纲，旧客户端忽略新增字段和帧仍可对话。
+- 中文、表情、纯图片、无助手文本、steering 和中断轮次的占位与截断正确。
+
+网关自动测试覆盖 Host Adapter 的快照与历史分页投影保留、正文裁剪不裁掉大纲、能力发现、真实 WebSocket 的更新分流与订阅过滤、新连接恢复、空值及控制基线重建。App 触屏和滚动验收需在客户端实现后执行。
+
+DSH 0.2.1-rc.2 的源码入口：`dsh-session-turn-outline` 的 `projection` 定义；`dsh-client-ui-chat` 的 `TurnNavigator`、`mergeTurnRailItems`、`ChatNavigation`；`dsh-api-session-controller` 的 `Session.loadThrough`。网关对应 [Host Adapter](../lib/dsh-host-adapter.mjs)、[控制流处理](../lib/index.mjs) 和 [协议说明](../PROTOCOL.md)。

package/lib/dsh-host-adapter.mjs

@@ -13,7 +13,7 @@ function requireArray(value, endpoint) {
   return value
 }
 
-export const DSH_VERSION = '0.2.0-rc.2'
+export const DSH_VERSION = '0.2.1-rc.2'
 export const SESSION_FORMAT_VERSION = 4
 
 export function readHistoryRecords(records) {
@@ -44,12 +44,12 @@ export function readSessionSnapshot(frame, sessionId) {
   }
 }
 
-async function firstStreamFrame(gateway, namespace, method, args, signal) {
+async function firstStreamFrame(stream, namespace, method, args, signal) {
   const ownedAbort = new AbortController()
   const streamSignal = signal ? AbortSignal.any([signal, ownedAbort.signal]) : ownedAbort.signal
   let iterator
   try {
-    const iterable = await gateway.stream({ namespace, method, args, signal: streamSignal })
+    const iterable = await stream(namespace, method, args, streamSignal)
     const iteratorFactory = iterable?.[Symbol.asyncIterator] ?? iterable?.[Symbol.iterator]
     if (typeof iteratorFactory !== 'function') throw new Error(`${namespace}/${method} returned an invalid stream`)
     iterator = iteratorFactory.call(iterable)
@@ -78,21 +78,28 @@ function sessionListArgs(request) {
  * descriptors. Its public methods intentionally match mobile-gateway domain
  * operations, not the upstream transport envelope.
  */
-export function createDshHostAdapter(typertGateway) {
+export function createDshHostAdapter(typertGateway, peer) {
   if (!typertGateway || typeof typertGateway.invoke !== 'function' || typeof typertGateway.stream !== 'function') {
     throw new Error('mobile-gateway requires the DSH Remote Gateway host service')
   }
+  if (!peer || !(peer.signal instanceof AbortSignal)) {
+    throw new Error('mobile-gateway requires a DSH Connection Peer (DSH 0.2.1-rc.2 or later)')
+  }
 
   const invoke = (namespace, method, args, signal) => typertGateway.invoke({
     namespace,
     method,
     args,
+    peer,
     ...(signal === undefined ? {} : { signal }),
   })
+  const stream = (namespace, method, args, signal) => typertGateway.stream({
+    namespace, method, args, peer, signal,
+  })
 
   const sessionSnapshot = async (request, signal) => {
     const frame = requireRecord(await firstStreamFrame(
-      typertGateway,
+      stream,
       'session',
       'follow',
       requestArgs(request),
@@ -200,7 +207,7 @@ export function createDshHostAdapter(typertGateway) {
   return {
     speech: {
       catalog: (signal) => invoke('speech', 'catalog', {}, signal),
-      follow: (signal) => typertGateway.stream({ namespace: 'speech', method: 'follow', args: {}, signal }),
+      follow: (signal) => stream('speech', 'follow', {}, signal),
       configure: (patch, signal) => invoke('speech', 'configure', { patch }, signal),
       prepare: (providerId, options, signal) => invoke('speech', 'prepare', {
         providerId, ...(options === undefined ? {} : { options }),
@@ -248,7 +255,7 @@ export function createDshHostAdapter(typertGateway) {
     },
     workspace: {
       async list(_payload = {}, signal) {
-        const frame = requireRecord(await firstStreamFrame(typertGateway, 'workspace', 'follow', {}, signal), 'workspace/follow')
+        const frame = requireRecord(await firstStreamFrame(stream, 'workspace', 'follow', {}, signal), 'workspace/follow')
         if (frame.type !== 'baseline') throw new Error('workspace/follow returned an invalid opening baseline')
         return requireRecord(frame.value, 'workspace/follow baseline')
       },
@@ -371,18 +378,17 @@ export function createDshHostAdapter(typertGateway) {
       if (event.type === 'turn/start') admittedPrompts.delete(sessionId)
     },
     openSessionStream(sessionId, signal) {
-      return typertGateway.stream({
-        namespace: 'session', method: 'follow',
+      return stream('session', 'follow',
         // Bound the opening window at the Host; older records remain available via session.page.
-        args: requestArgs({ address: { kind: 'session', sessionId }, maxMessages: 12, assistantStream: true }),
+        requestArgs({ address: { kind: 'session', sessionId }, maxMessages: 12, assistantStream: true }),
         signal,
-      })
+      )
     },
     openControlStream(signal) {
-      return typertGateway.stream({ namespace: 'session', method: 'control', args: {}, signal })
+      return stream('session', 'control', {}, signal)
     },
     openWorkspaceStream(signal) {
-      return typertGateway.stream({ namespace: 'workspace', method: 'follow', args: {}, signal })
+      return stream('workspace', 'follow', {}, signal)
     },
   }
 }

package/lib/index.mjs

@@ -116,6 +116,7 @@ import { assistantFinish, failureDetails, toolResultDetails, turnReasonDetails }
 //                     { "kind": "goal-clear", "sessionId", "cleared": true }
 //                     { "kind": "tasks-updated", "sessionId", "asOfSeq", "todos" }
 //                     { "kind": "goal-updated", "sessionId", "asOfSeq", "goal" }
+//                     { "kind": "turn-outline-updated", "sessionId", "asOfSeq", "turnOutline": [...] | null }
 //                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
 //                     { "kind": "question-response", "rpcId", "sessionId", "action", "accepted", "reason"? }
 //                     { "kind": "question-resolved", "rpcId", "sessionId", "outcome" }
@@ -1433,7 +1434,18 @@ async function handleQuery(api, host, agentDefaultModel, msg, pluginContext) {
     return proxyQuery(api, 'workspaces', api.workspace.list.bind(api.workspace), {})
   }
   if (msg.type === 'sessions') {
-    return proxyQuery(api, 'sessions', api.sessions.list.bind(api.sessions), {})
+    const frame = await proxyQuery(api, 'sessions', api.sessions.list.bind(api.sessions), {})
+    if (frame.kind !== 'sessions' || !Array.isArray(frame.items)) return frame
+    // Lists need only titles; full projections can make tunnel frames many MiB.
+    // Copy at the mobile boundary so Host data and history projections stay intact.
+    return { ...frame, items: frame.items.map(item => {
+      if (!item?.projections) return item
+      const { asOfSeq, values } = item.projections
+      return { ...item, projections: {
+        ...(asOfSeq === undefined ? {} : { asOfSeq }),
+        values: values && Object.hasOwn(values, 'title') ? { title: values.title } : {},
+      } }
+    }) }
   }
   if (msg.type === 'history') {
     const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
@@ -2193,13 +2205,19 @@ const plugin = {
   // Hard dependencies: the gateway registers on the host web server and
   // admits mobile messages through the Host Remote Gateway. Cordis must not
   // activate this row before either service exists.
-  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'connection', 'agentDefaultModel'],
   // exported for local tests; Cordis ignores unknown plugin fields
   admitMessage,
   handleQuery,
   apply(ctx, config) {
     const webServer = ctx.webServer
-    const api = createDshHostAdapter(ctx.typertGateway)
+    if (typeof ctx.connection?.createPeer !== 'function') {
+      throw new Error('mobile-gateway requires DSH 0.2.1-rc.2 or later with Connection.createPeer')
+    }
+    // 已配对设备沿用本机用户权限；身份只由 Host 创建，不能由移动端参数指定。
+    // 问答与审批仍由本插件的 Host 监听器处理，无需另开 Remote 交互流。
+    const peer = ctx.connection.createPeer({ principal: { kind: 'owner' }, interactions: 'none' })
+    const api = createDshHostAdapter(ctx.typertGateway, peer)
     const host = api
     const agentDefaultModel = ctx.agentDefaultModel
     const options = {
@@ -3090,6 +3108,7 @@ const plugin = {
               'assistant-stream-v1',
               'history-format-version',
               'projection-baseline',
+              'turn-outline-v1',
               'images',
               'session-create',
               'session-agent-preset',
@@ -3387,10 +3406,22 @@ const plugin = {
       log(`session queue forwarded: session=${sessionId} items=${items.length}`)
     }
 
+    const projectionKinds = {
+      todos: 'tasks-updated',
+      goal: 'goal-updated',
+      turnOutline: 'turn-outline-updated',
+    }
+    const projectionValues = (values = {}) => Object.fromEntries(
+      Object.keys(projectionKinds).map(key => [key, values[key] ?? null]),
+    )
     const projectionFrame = (sessionId, key, value, seq) => ({
-      kind: key === 'todos' ? 'tasks-updated' : 'goal-updated', sessionId, asOfSeq: seq,
+      kind: projectionKinds[key], sessionId, asOfSeq: seq,
       [key]: value,
     })
+    const broadcastProjection = (sessionId, key, value, seq) => {
+      const broadcast = key === 'turnOutline' ? broadcastSessionMetadataFrame : broadcastInteractionFrame
+      broadcast(projectionFrame(sessionId, key, value, seq))
+    }
 
     const installProjectionBaseline = value => {
       if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid projection baseline')
@@ -3400,16 +3431,17 @@ const plugin = {
           throw new Error('invalid session projection baseline')
         }
         Object.defineProperty(next, sessionId, { enumerable: true, configurable: true, writable: true,
-          value: { asOfSeq: baseline.asOfSeq, values: { todos: baseline.values.todos ?? null, goal: baseline.values.goal ?? null } } })
+          value: { asOfSeq: baseline.asOfSeq,
+            values: projectionValues(baseline.values) } })
       }
       const previous = sessionProjectionBaselines
       sessionProjectionBaselines = next
       broadcastSessionMetadataFrame({ kind: 'projection-baseline', projections: next })
       for (const sessionId of new Set([...Object.keys(previous), ...Object.keys(next)])) {
         const baseline = Object.hasOwn(next, sessionId) ? next[sessionId] : null
-        for (const key of ['todos', 'goal']) {
-          broadcastInteractionFrame(projectionFrame(sessionId, key, baseline?.values[key] ?? null,
-            baseline?.asOfSeq ?? previous[sessionId].asOfSeq))
+        for (const key of Object.keys(projectionKinds)) {
+          broadcastProjection(sessionId, key, baseline?.values[key] ?? null,
+            baseline?.asOfSeq ?? previous[sessionId].asOfSeq)
         }
       }
     }
@@ -3446,12 +3478,13 @@ const plugin = {
               installSessionQueueBaseline(frame.value?.projections)
             } else if (frame?.type === 'projection' && frame.key === 'inbox') {
               installSessionQueue(frame.sessionId, frame.value)
-            } else if (frame?.type === 'projection' && (frame.key === 'todos' || frame.key === 'goal')) {
+            } else if (frame?.type === 'projection' && Object.hasOwn(projectionKinds, frame.key)) {
               const sessionId = String(frame.sessionId)
               const previous = Object.hasOwn(sessionProjectionBaselines, sessionId) ? sessionProjectionBaselines[sessionId] : null
+              const value = frame.value ?? null
               Object.defineProperty(sessionProjectionBaselines, sessionId, { enumerable: true, configurable: true, writable: true,
-                value: { asOfSeq: frame.seq, values: { ...previous?.values, [frame.key]: frame.value } } })
-              broadcastInteractionFrame(projectionFrame(sessionId, frame.key, frame.value, frame.seq))
+                value: { asOfSeq: frame.seq, values: { ...projectionValues(previous?.values), [frame.key]: value } } })
+              broadcastProjection(sessionId, frame.key, value, frame.seq)
               log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
             }
           }
@@ -3471,6 +3504,9 @@ const plugin = {
       if (waitTimer) clearTimeout(waitTimer)
       clearInterval(fileTransferExpiryTimer)
       backgroundStreamAbort.abort()
+      peer.dispose().catch((error) => {
+        log(`Host peer disposal failed: ${error && error.message ? error.message : String(error)}`)
+      })
       speechInput.dispose()
       for (const pending of [...pendingQuestions.values()]) fallbackQuestion(pending)
       for (const pending of [...pendingApprovals.values()]) fallbackApproval(pending)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.10.2",
-  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、插件管理、官方语音输入、局域网及 Cloudflare Tunnel，以及自适应深浅色控制面板。0.10.2 新增文件卡片事件透传与安全文件引用解析，复用分块下载为移动端文件卡片和正文文件链接预览提供协议支持。",
+  "version": "0.10.4",
+  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、插件管理、官方语音输入、文件卡片与安全文件预览、局域网及 Cloudflare Tunnel，以及自适应深浅色控制面板。0.10.4 精简会话列表投影，仅保留标题与投影切点，修复大量会话通过公网隧道传输时超时的问题；保留会话元信息和历史完整投影，现有移动客户端无需配套修改。",
   "main": "lib/index.mjs",
   "files": [
     "bin",