dsh-plugin-mobile-gateway 0.10.3 → 0.11.0

package/PROTOCOL.md

@@ -663,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：
@@ -708,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": {...} } } }
 ```
@@ -1110,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 操作审批请求与最终状态 |
@@ -1177,7 +1211,8 @@ DSH Web 的“深度求索中，用时 22 秒 ···”是客户端文案，不
 
 | 版本 | 新增 |
 |---|---|
-| v0.10.3（当前源码） | 适配 DSH 0.2.1-rc.2；为 Remote 请求及实时订阅补齐 Connection Peer，修复读取 `signal` 时的空值报错，并随网关停止释放 Peer；移动端协议保持不变 |
+| 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 配置交互优化 |
@@ -1360,3 +1395,41 @@ history. Older gateways without the capability continue using one connection.
 取消回执只表示已发出取消信号；原转写随后返回 `speech/cancelled`，资源清理完成前仍占并发名额。断线、网关停止会中止该连接的活动转写和状态订阅。其他连接不能取消这个转写，即使属于同一设备。客户端上滑取消、切换页面或替换草稿后必须忽略旧请求的迟到结果。
 
 错误统一为 `kind:error`，包含 `requestType`, `requestId`, `code`, `message`。网关错误包括 `authentication-required`, `wrong-channel`, `bad-request`, `speech/unavailable`, `speech/busy`, `speech/request-in-progress`, `speech/request-not-found`, `speech/invalid-audio`, `speech/cancelled`, `speech/timeout`, `speech/invalid-response`, `speech/stream-ended`；官方插件的 `speech/transcription-failed` 等错误代码保留。
+
+## 智能体团队与子会话（agent-team-v1 / subagent-conversations-v1）
+
+当前源码新增两个协议 3 可选能力，Host 适配基线为 DSH 0.2.1-rc.2、Session format 4。完整 APP 实施规范见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)，包含成员与任务完整字段、目录树、视图切换、消息和停止、投影缓存、恢复流程及验收清单。
+
+| 连接 | 请求/推送 | 说明 |
+|---|---|---|
+| control | `agent-team` | 请求 `sessionId` 为 Lead ID，`requestId?` 回显；响应 `agentTeam` 完整值及 `projectionState`、精确值的 `asOfSeq` |
+| control | `subagents` | 请求 `sessionId` 为父节点 ID，`requestId?` 回显；响应 `subagentCatalog` 直接子节点数组及相同投影状态字段 |
+| control | `agent-team-updated` | `{sessionId,asOfSeq,agentTeam}`，团队完整值替换，null 表示失效 |
+| control | `subagents-updated` | `{sessionId,asOfSeq,subagentCatalog}`，父节点直接子目录完整替换，null 表示失效 |
+| control | `subagent-identity-updated` | `{sessionId,asOfSeq,subagent}`，该子会话身份完整值或 null |
+| control | `subagent-timing-updated` | `{sessionId,asOfSeq,subagentTiming}`，该子会话耗时完整值或 null |
+| control | `session-status` | `{sessionId,running}`，全局进程内运行状态；初始/重连用 sessions 刷新 |
+
+两个查询都返回 `projectionState: ready | unavailable | migration-required`。没有投影是 null，空目录是 `[]`，空任务板是团队对象中的 `tasks:[]`；迁移提示没有 `asOfSeq`，不能当作精确基线。未找到会话返回 `session/not-found`。查询不激活 Agent、不调用模型。capability 仅表示网关理解协议，不保证 Host 已启用实验性团队插件。
+
+新增投影键 `agentTeam/subagentCatalog/subagent/subagentTiming` 同时出现在 `projection-baseline`。上述更新与运行状态不受当前聊天 subscribe 过滤，仅发往 control/legacy。Host control 重建会发送替换基线及失效通知；基线未包含冷会话不表示会话删除。各投影按 `(gatewayId, sessionId, projectionKey)` 管理水位，不能跨会话或跨键比较 seq。初始运行状态从 sessions 查询取得，实时状态不具备持久 seq。
+
+子会话沿用现有 `sessionId` 为当前视图 ID，增加 `parentSessionId`（直接父会话）和 `subagentMode`（`continuable | one-shot | unknown`）；这两个字段必须一起提供。普通会话不带它们，external 节点没有本地子会话地址。
+
+```json
+{"type":"subscribe","sessionId":"child","parentSessionId":"lead","subagentMode":"continuable","assistantStream":true}
+{"type":"history","sessionId":"child","parentSessionId":"lead","subagentMode":"continuable","requestId":"h1","beforeSeq":20,"historyFormatVersion":4}
+{"type":"message","sessionId":"child","parentSessionId":"lead","subagentMode":"continuable","requestId":"m1","mode":"queue","text":"继续处理当前任务"}
+{"type":"session-cancel","sessionId":"child","parentSessionId":"lead","subagentMode":"continuable","requestId":"stop1"}
+{"type":"tasks","sessionId":"child","parentSessionId":"lead","subagentMode":"continuable","requestId":"todos1"}
+```
+
+- conversation：`history/subscribe/message`；control：`session-cancel/tasks/goal`。`goal` 同样支持子地址。其他操作不能仅凭此能力推定支持子地址。
+- `subscribed`、follower 的 snapshot/event/assistant-stream/reset 回显父子地址；切换使用新 `subscriptionId/streamId`。旧 legacy 持久事件可能只有 sessionId。
+- history、tasks、goal、session-cancel 的正常响应及查询失败回显原请求 requestId（如果提供）。`sent` 对子消息额外返回 `messageId`、父子地址以及原 requestId。
+- 子消息内部使用官方专用 continuation 接口；`message.mode` 仍是 queue/steer，不表示生命周期。只有 continuable 能发送与停止。
+- 共享任务来自 Lead 的 `agentTeam.tasks`，负责人字段是 `ownerName`；成员 `todos` 仍是独立内部待办。
+- 普通子目录包含 continuable/one-shot/external/unknown；按父节点逐级读取，不自动递归。
+- 子会话父子关系由 Host 校验，非法关系返回 `subagent/unauthorized` 等错误；无法继续的模式返回 `subagent/not-resumable`。
+- 发送回执只表示 inbox 接受，不保证执行完成，也不提供自动重试去重保证。断线无回执应核对历史/队列，不能盲目重发。
+- 本次不提供直接创建成员或变更共享任务的移动 RPC；由用户在 Lead 对话中提出要求，Host 团队工具执行，APP 等待权威投影更新。

package/README.md

@@ -10,7 +10,11 @@ DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排
 >
 > 实时流已改为独立 `assistant-stream` 帧，移动端需要按 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md) 更新订阅、缓存与分页处理。当前修改尚未发布。
 >
-> v0.10.3（当前源码）：适配 DSH 0.2.1-rc.2，为 Remote 请求及实时订阅补齐 Connection Peer，修复 `Cannot read properties of undefined (reading 'signal')` 报错，并在网关停止时释放 Peer。移动端协议保持不变。
+> v0.11.0（当前源码，尚未发布）：新增智能体团队与子会话协议，支持团队成员、共享任务看板、多层子智能体目录和运行状态实时同步，以及子智能体独立历史、视图切换、继续对话、图片输入与停止执行。APP 需按能力发现接入，详见 [智能体团队 APP 详细接入指南](docs/agent-team-app-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)。
 >
@@ -48,6 +52,10 @@ DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/host-official.test
 
 当前源码新增会话模式选择：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 界面需单独接入，本次源码尚未发布。
+
+当前源码新增 `agent-team-v1`、`subagent-conversations-v1`：支持团队成员与共享任务板查询、各层子智能体目录、团队投影和成员运行状态实时同步，以及子会话独立历史、订阅、继续对话与停止执行。APP 的目标地址、完整 JSON 示例、看板规则、切换与重连状态机、错误处理和验收清单见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。本次只提供网关能力，APP 页面需单独接入，源码尚未发布。
+
 ## 多网关第一阶段（当前源码）
 
 插件提供稳定 `gatewayId`、可配置 `gatewayName`、配对候选地址列表，以及可持久化的“关闭 / 临时开启 / 常驻开启”运行模式。一个 App 可以分别配对不同机器上的网关；客户端多网关管理仍需按 [App 对接说明](docs/multi-gateway-app-integration.md) 实现。本次源码尚未发布新的 npm 版本。