dsh-plugin-mobile-gateway 0.10.3 → 0.11.0

package/docs/agent-team-app-integration.md

@@ -0,0 +1,945 @@
+# APP 智能体团队与子智能体会话接入指南
+
+本文是本仓库当前源码的实现契约，面向 APP 网络层、数据层、聊天页和看板开发。按本文实现后，APP 可以展示 Lead 和子智能体、查看共享任务板与每个成员的任务、在成员间切换聊天视图，并向可继续对话的成员发送消息。
+
+- 编写日期：2026-10-21。
+- 网关：0.11.0 当前源码，新增能力尚未发布；运行时仍以 capability 判断是否支持。
+- 已核对的 Host：DSH **0.2.1-rc.2**，Session format **4**。
+- WebSocket：`/ws/mobile`，子协议仍为 `dsh-mobile-v1`，`hello.protocol` 仍为 `3`。
+- 新能力：`agent-team-v1`、`subagent-conversations-v1`。
+- 本次只改网关与协议文档，APP 页面需按本文接入。
+
+## 1. 能力边界与页面目标
+
+| APP 功能 | 本次网关支持方式 |
+|---|---|
+| 团队成员面板，包含 Lead | `agent-team` 读取 `agentTeam.members` |
+| 共享任务看板 | 同一响应中的 `agentTeam.tasks` |
+| 成员任务筛选 | 用任务 `ownerName` 匹配成员 `name`，不要匹配标题 |
+| 待处理 / 进行中 / 已完成分栏 | 用任务 `status` 分组 |
+| 任务详情、依赖、写入范围、冲突提示 | 完整透传任务投影字段 |
+| 查看所有层级的普通子智能体 | 从根开始逐级查询 `subagents`，支持展开树或有界遍历 |
+| 切换 Lead、团队成员或普通子智能体 | 使用该视图的地址重新 `subscribe` |
+| 独立历史、分页、执行轨迹、实时输出 | 复用 `history`、`session-snapshot`、`event`、`assistant-stream` |
+| 与团队成员继续对话、发送图片 | `message` 携带直接父会话 ID 和 `continuable` 模式 |
+| 停止成员当前生成 | `session-cancel` 携带同样的父子地址 |
+| 成员自己的待办与 Goal | 子地址请求 `tasks` / `goal`，或读取该成员的历史投影 |
+| 查看别的成员时仍同步团队任务 | control 连接上的全局团队投影更新 |
+| 创建团队、分配任务、修改共享任务 | 在 Lead 对话中向智能体提出要求，由 Host 的团队工具处理 |
+
+本次没有新增直接创建成员、直接增删改共享任务的移动 RPC。不要发送未经实现的 `team-task-create`、`team-task-update`、`agent-spawn` 等请求，也不要把 `command-execute` 当作任意工具调用器。共享任务分配是 Host 团队工具的职责；APP 可以向 Lead 发送明确的自然语言指令，并以新的任务投影作为执行结果。
+
+有两类“任务”，必须在产品和数据中分开：
+
+1. **团队共享任务**：`agentTeam.tasks`，有 `id`、`revision`、`ownerName`、依赖与写入范围，属于 Lead。
+2. **成员内部待办**：`todos`，来自 `tasks` / `tasks-updated` 或成员历史投影，属于具体成员会话。它没有共享任务的身份和归属语义，不能拼入共享任务板。
+
+## 2. 身份与地址：必须先实现
+
+建议 APP 保存以下逻辑模型，字段名可按平台编码习惯转换：
+
+```text
+ConversationTarget {
+  gatewayId: String
+  sessionId: String          // 当前聊天视图的会话 ID
+  parentSessionId: String?   // 直接父会话，仅子智能体视图填写
+  subagentMode: String?      // continuable / one-shot / unknown
+}
+TeamContext {
+  gatewayId: String
+  leadSessionId: String      // 切换团队成员时始终保留
+}
+```
+
+三个 ID 的区别：
+
+| 名称 | 含义 | 示例 |
+|---|---|---|
+| `leadSessionId` | APP 保留的团队根会话 ID；不是本次请求新增的顶层字段 | `session-lead` |
+| `sessionId` | 本次请求操作的当前会话 | `session-scout` |
+| `parentSessionId` | 当前子智能体的**直接**父会话 | `session-lead` |
+
+团队成员是 Lead 的直接子会话。如果成员又创建了普通子智能体，孙节点的 `parentSessionId` 必须填该成员 ID；不能填 Lead ID。
+
+Lead 请求：
+
+```json
+{"type":"history","sessionId":"session-lead"}
+```
+
+团队成员请求：
+
+```json
+{"type":"history","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable"}
+```
+
+孙节点请求示例：
+
+```json
+{"type":"history","sessionId":"session-frame-reviewer","parentSessionId":"session-scout","subagentMode":"one-shot"}
+```
+
+地址规则：
+
+- 普通会话只发 `sessionId`。不要把普通 fork 会话的父 ID 当成子智能体地址；普通 fork 与子智能体不是同一种会话。
+- 子会话必须同时带 `parentSessionId`、`subagentMode`；`sessionId` 始终填写子会话 ID。
+- `parentSessionId` 必须非空，且不同于 `sessionId`。
+- `subagentMode` 用独立字段表示生命周期；`message.mode` 继续表示 `queue` / `steer`。
+- `external` 不是本地会话，不能用于 `history`、`subscribe` 或 `message`。
+- 不要从 ID 格式猜父子关系，不要把成员名字当成会话 ID。
+- 所有缓存和请求路由都必须包含 `gatewayId`，不同电脑可能有同名任务或相同 ID。
+
+可复用子地址的移动请求为：`history`、`subscribe`、`message`、`session-cancel`、`tasks`、`goal`。其他现有请求是否适用于子会话，不能仅凭本次 capability 推断；本期成员聊天页的模型、模式、重命名、fork 等按钮不要直接照搬普通会话操作。
+
+## 3. 连接、鉴权和能力发现
+
+复用 APP 已有设备配对和 token，不新增团队鉴权流程。建议使用两条已鉴权连接：
+
+```text
+control:      X-DSH-Channel: control
+conversation: X-DSH-Channel: conversation
+Authorization: Bearer <已配对设备 token>
+```
+
+也可沿用现有子协议 token 方式；握手、设备 ID 和配对详情见 [主协议](../PROTOCOL.md)。连接地址和 token 来自同一网关的配对信息。
+
+`hello` 中相关字段示意，capabilities 仅列出与本文相关的部分：
+
+```json
+{
+  "kind":"hello",
+  "protocol":3,
+  "historyFormatVersion":4,
+  "capabilities":["split-channels","assistant-stream-v1","projection-baseline","agent-team-v1","subagent-conversations-v1"],
+  "authenticated":true
+}
+```
+
+| 能力 | APP 含义 |
+|---|---|
+| `agent-team-v1` | 网关理解团队查询、团队投影和成员状态帧 |
+| `subagent-conversations-v1` | 网关理解显式父子地址，并能路由子会话历史、订阅、发送和停止 |
+| `assistant-stream-v1` | 可以使用 `assistantStream:true` 订阅 |
+| `projection-baseline` | control 建连后接收投影基线 |
+
+能力公布表示网关实现了协议；Host 是否启用实验性团队插件，要看查询的 `projectionState`。普通子智能体浏览也可以在没有团队插件的场景使用。
+
+- 缺少 `agent-team-v1`：隐藏团队看板或提示升级网关。
+- 缺少 `subagent-conversations-v1`：不要把子 ID 填进普通消息接口。
+- `projectionState: unavailable`：表示当前读取没有该投影，不能据此断言会话不存在或清空为“0 个任务”。
+- 非法 channel 返回 `wrong-channel`。下面各请求须发送到正确连接。
+- 不指定 channel 的 legacy 单连接仍兼容；新 APP 建议使用 split channels，保持看板与聊天订阅独立。
+
+## 4. 首次进入团队页面的完整流程
+
+1. 建立 control 和 conversation，分别等待 `hello` 并检查能力。
+2. control 开始消费 `projection-baseline` 和实时更新。不要等用户展开看板才建立 control。
+3. control 发 `sessions`，读取会话摘要和初始 `running`；不要从 `sessions.items[].projections` 取团队数据，该接口故意只保留标题投影。
+4. control 发 `agent-team`，`sessionId` 填 Lead ID。
+5. control 发 `subagents`，`sessionId` 填 Lead ID；根据需要展开后继续查询下一级。
+6. conversation 发 Lead 或当前成员的 `subscribe`，设置 `assistantStream:true`。
+7. 收到 `session-snapshot` 后安装该视图的聊天基线和实时状态；任务看板从团队缓存渲染。
+8. 用户选择成员时执行第 9 节的切换流程。共享任务仍然从原 `leadSessionId` 读取。
+
+建议首次查询都带唯一 `requestId`，重入页面后丢弃上一页面仍在途的响应。`subscribe` 的代际判断使用服务端 `subscriptionId`，不能用 `requestId` 替代。
+
+## 5. 团队查询：`agent-team`
+
+**连接：control**。请求：
+
+```json
+{"type":"agent-team","sessionId":"session-lead","requestId":"team-load-001"}
+```
+
+| 请求字段 | 类型 | 必填 | 含义 |
+|---|---|---|---|
+| `type` | string | 是 | 固定 `agent-team` |
+| `sessionId` | string | 是 | Lead 会话 ID |
+| `requestId` | string | 建议 | 原样回显，用于关联在途请求 |
+
+完整响应示例：
+
+```json
+{
+  "kind":"agent-team",
+  "sessionId":"session-lead",
+  "requestId":"team-load-001",
+  "projectionState":"ready",
+  "asOfSeq":120,
+  "agentTeam":{
+    "members":[
+      {"id":"session-lead","name":"lead","role":"lead","phase":"active"},
+      {"id":"session-scout","name":"footage-scout","role":"teammate","phase":"active"},
+      {"id":"session-music","name":"music-producer","role":"teammate","phase":"active"},
+      {"id":"session-graphics","name":"graphics-designer","role":"teammate","phase":"active"}
+    ],
+    "tasks":[
+      {
+        "id":"task-1",
+        "revision":3,
+        "subject":"素材勘察：11 段录屏逐帧分析 + 镜头切点",
+        "description":"读取制作要求，逐帧分析录屏，输出可用于剪辑的切点清单。",
+        "status":"completed",
+        "ownerName":"footage-scout",
+        "blockedBy":[],
+        "writeScopes":["promo/analysis"],
+        "ready":false,
+        "writeScopeWarnings":[]
+      },
+      {
+        "id":"task-2",
+        "revision":2,
+        "subject":"原创配乐与音效",
+        "description":"制作 48 秒配乐，输出音频文件。",
+        "status":"in_progress",
+        "ownerName":"music-producer",
+        "blockedBy":[],
+        "writeScopes":["promo/audio"],
+        "ready":false,
+        "writeScopeWarnings":[]
+      },
+      {
+        "id":"task-3",
+        "revision":1,
+        "subject":"视觉资产",
+        "description":"生成标题卡和结尾 CTA。",
+        "status":"pending",
+        "blockedBy":["task-1"],
+        "writeScopes":["promo/graphics"],
+        "ready":true,
+        "writeScopeWarnings":[]
+      }
+    ]
+  }
+}
+```
+
+`task-3` 的依赖列表非空但依赖已完成，因此 `ready:true`；不能以 `blockedBy.length > 0` 代替 `ready`。
+
+响应字段：
+
+| 字段 | 类型 | 语义 |
+|---|---|---|
+| `projectionState` | string | `ready` / `unavailable` / `migration-required` |
+| `asOfSeq` | integer，可缺省 | 当前精确投影的会话日志切点；迁移提示响应没有它 |
+| `agentTeam` | object 或 null | 当前团队完整值，原样透传 |
+| `agentTeam.failure` | string，可缺省 | Host 读取持久化团队记录出现错误；成员和任务停在最后有效状态 |
+
+三种状态必须分别处理：
+
+```json
+{"kind":"agent-team","sessionId":"session-lead","projectionState":"unavailable","asOfSeq":10,"agentTeam":null}
+```
+
+显示“团队数据暂不可用”，提供重试。网关 capability 存在不表示该 Host profile 安装了团队投影。
+
+```json
+{"kind":"agent-team","sessionId":"session-lead","projectionState":"migration-required","agentTeam":{"members":[],"tasks":[]}}
+```
+
+这是 Host 返回的迁移前缓存提示，示例内容仅为示意；可以只读展示并标注待刷新，不能把它安装成带 seq 的权威基线。打开对应会话取得新基线；如果 Host 拒绝旧格式，提示在桌面端处理或升级，停止无限重试。
+
+```json
+{"kind":"error","requestType":"agent-team","requestId":"team-load-001","sessionId":"session-lead","code":"session/not-found","message":"session not found"}
+```
+
+这是会话未找到，与“没有团队投影”不同。
+
+### 5.1 成员字段与界面规则
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `id` | string | 成员持久会话 ID，作为选择与缓存主键 |
+| `name` | string | 团队内成员名字，也是任务 `ownerName` 的匹配依据 |
+| `role` | string | `lead` / `teammate` |
+| `phase` | string | `provisioning` / `active` / `failed`，持久生命周期 |
+| `error` | string，可缺省 | 成员创建失败原因 |
+
+`phase` 不是运行状态。成员 UI 状态按以下规则计算：
+
+```text
+phase == provisioning → 正在创建；禁用进入和发送
+phase == failed       → 创建失败；展示 error，禁用进入和发送
+phase == active       → 结合 session-status / sessions.running 显示运行中或未运行
+running 尚未知         → 显示状态未知/同步中
+```
+
+Lead 行也出现在成员数组中；成员总数包括 Lead，子智能体数只统计 `role == teammate`。保留 Host 数组顺序，不假设只有三名成员。当前选中高亮按 `member.id == currentTarget.sessionId` 判断。
+
+点击 Lead：切回普通会话地址。点击 active teammate：构造 `{sessionId:member.id,parentSessionId:leadSessionId,subagentMode:"continuable"}`。
+
+`ready` 且只有 Lead、没有任务也是合法数据；实验性投影可能对普通会话生成 Lead 行，不能仅凭存在 `agentTeam` 就显示“已有多人团队”。
+
+### 5.2 共享任务字段与看板规则
+
+| 字段 | 类型 | 必有 | 含义 |
+|---|---|---|---|
+| `id` | string | 是 | 团队内任务身份；不同团队都可能出现 `task-1` |
+| `revision` | integer | 是 | 此任务版本，变更后递增 |
+| `subject` | string | 是 | 卡片标题 |
+| `description` | string | 是 | 完整任务说明，展开显示 |
+| `status` | string | 是 | `pending` / `in_progress` / `completed`；解码应兼容 `deleted` 和未来未知值 |
+| `ownerName` | string | 否 | 当前负责人名字；缺省表示未分配 |
+| `blockedBy` | string[] | 是 | 前置任务 ID，保留 Host 顺序 |
+| `writeScopes` | string[] | 是 | 建议写入路径/范围，作为说明展示 |
+| `ready` | boolean | 是 | Host 计算的可领取状态：仅 pending 且依赖全部完成时为 true |
+| `writeScopeWarnings` | string[] | 是 | Host 计算的潜在写入冲突说明 |
+
+产品规则：
+
+- 三列显示：待处理 `pending`、进行中 `in_progress`、已完成 `completed`；不要用成员是否运行来覆盖任务状态。
+- 对 `pending && !ready` 标记“受阻”，详情列出 `blockedBy`。已开始或已完成的任务 ready 为 false，不能因此标记受阻。
+- 任务 ID 在当前快照中找不到时，保留原 ID；不要推断为已完成。
+- 当前投影通常排除 `deleted`；客户端解码保留兼容，收到后从可见列表移除。
+- `writeScopes` 是建议范围，不是权限控制；不能在 APP 中称为“强制隔离目录”。
+- `writeScopeWarnings` 非空时显示可展开提示，不替代任务状态。
+- 负责人：`members.first(name == task.ownerName)`，找不到时仍显示原 `ownerName`；不要丢弃这条任务。
+- 缺省 owner 的任务显示“未分配”，不自动归给 Lead。
+- “当前成员任务”只筛选该成员 `name`；团队看板始终能切回“全部成员”。
+- 点击任务的负责人，可进入对应 active 成员会话；点击任务卡片主体展开详情，避免混淆两个动作。
+- 共享任务完整快照是权威值，不能只追加任务；任务移除、负责人变更、完成后重开都要反映。
+- 缓存任务主键使用 `(gatewayId, leadSessionId, task.id)`，禁止只用 `task.id`。
+
+## 6. 普通子智能体目录：`subagents`
+
+**连接：control**。每次返回指定父节点的**直接子节点**：
+
+```json
+{"type":"subagents","sessionId":"session-lead","requestId":"children-lead-001"}
+```
+
+```json
+{
+  "kind":"subagents",
+  "sessionId":"session-lead",
+  "requestId":"children-lead-001",
+  "projectionState":"ready",
+  "asOfSeq":120,
+  "subagentCatalog":[
+    {"id":"session-scout","mode":"continuable","label":"逐帧分析 11 段录屏","createdAt":1792550400000},
+    {"id":"session-review","mode":"one-shot","label":"检查分镜","createdAt":1792550401000},
+    {"id":"remote-run","mode":"external","label":"远程执行","createdAt":1792550402000},
+    {"id":"session-old","mode":"unknown","createdAt":1792550403000}
+  ]
+}
+```
+
+`projectionState` 和 `asOfSeq` 语义与第 5 节相同；不可用是 `null`，确实没有子节点是 `[]`，两者不能混淆。
+
+| 模式 | 可查看历史 | 可发送/停止 | APP 行为 |
+|---|---|---|---|
+| `continuable` | 是 | 是 | 点击进入，显示输入框；能否成功发送仍由 Host 校验 |
+| `one-shot` | 是 | 本次接口不支持 | 只读会话、轨迹与结果 |
+| `external` | 无本地子会话 | 否 | 展示目录元信息，禁用本地聊天导航 |
+| `unknown` | 可按 unknown 地址尝试读取 | 否，直到身份明确 | 先只读，读取历史中 `projections.values.subagent` 后确认实际模式 |
+
+目录字段 `label` 是创建任务标签；只有 continuable 保证存在。它不同于团队成员 `name`。`createdAt` 是毫秒时间戳，不能当排序序号或 seq。
+
+`subagents` 不提供 `hasChildren`，也不自动递归。实现“全部子智能体”可以使用以下策略：
+
+1. 对根调用 `subagents`。
+2. 显示所有返回行。为非 external 的行提供展开按钮。
+3. 展开行时，以该行 `id` 为父节点继续调用 `subagents`。
+4. 要一次展开全部，APP 做有界的广度遍历，例如最多 4 个并发读取，并维护 visited 集合；这是客户端策略，不是协议限制。
+5. 每个分支保留 loading/error/ready 状态；一个分支失败不能清空整棵树。
+6. 不要把所有层级都挂到根下面。构造导航地址时，直接父 ID 就是该次目录响应的 `sessionId`。
+7. 接到某父节点 `subagents-updated` 后整体替换该父节点子列表。未返回的旧节点从该目录移除，不等于用户会话被删除。
+
+普通子智能体的任务标签来自目录 `label`，其内部待办来自该子会话 `todos`；不要捏造共享任务。团队成员面板和普通子智能体树可以共用目标模型，但各自的数据来源要保留。
+
+## 7. 全局实时团队同步
+
+### 7.1 基线
+
+control 连接初始化会收到：
+
+```json
+{
+  "kind":"projection-baseline",
+  "projections":{
+    "session-lead":{
+      "asOfSeq":120,
+      "values":{
+        "todos":null,
+        "goal":null,
+        "turnOutline":[],
+        "agentTeam":{"members":[{"id":"session-lead","name":"lead","role":"lead","phase":"active"}],"tasks":[]},
+        "subagentCatalog":[],
+        "subagent":null,
+        "subagentTiming":null
+      }
+    }
+  }
+}
+```
+
+示例展示一个仅 Lead 的团队。真实基线可以同时包含很多会话，其中也可能包含当前正在查看的子会话。
+
+新增控制投影键：
+
+| 键 | 值 | 更新帧 kind |
+|---|---|---|
+| `agentTeam` | 团队完整值 / null | `agent-team-updated` |
+| `subagentCatalog` | 直接子目录数组 / null | `subagents-updated` |
+| `subagent` | 子身份对象 / null | `subagent-identity-updated` |
+| `subagentTiming` | 子执行耗时对象 / null | `subagent-timing-updated` |
+
+控制基线只覆盖 Host 当前控制集合。基线没出现一个冷会话，不代表它被删除。对冷会话仍需第 5、6 节查询或打开历史。
+
+Host 控制流重新建立时，网关发送新 `projection-baseline`，并为原控制集合里失效的值发送 null 更新。APP 应替换本次控制流的基线集合，保持冷会话查询缓存单独管理；null 更新使对应控制值失效。
+
+### 7.2 增量是完整值替换
+
+```json
+{
+  "kind":"agent-team-updated",
+  "sessionId":"session-lead",
+  "asOfSeq":121,
+  "agentTeam":{
+    "members":[
+      {"id":"session-lead","name":"lead","role":"lead","phase":"active"},
+      {"id":"session-scout","name":"footage-scout","role":"teammate","phase":"active"}
+    ],
+    "tasks":[]
+  }
+}
+```
+
+这里 `tasks:[]` 表示当前可见共享任务为空，应替换旧任务数组，不是“没有改任务”。
+
+其他帧结构：
+
+```json
+{"kind":"subagents-updated","sessionId":"session-lead","asOfSeq":122,"subagentCatalog":[{"id":"session-scout","mode":"continuable","label":"逐帧分析","createdAt":1792550400000}]}
+```
+
+```json
+{"kind":"subagent-identity-updated","sessionId":"session-scout","asOfSeq":2,"subagent":{"mode":"continuable","label":"逐帧分析","seq":1}}
+```
+
+```json
+{"kind":"subagent-timing-updated","sessionId":"session-scout","asOfSeq":20,"subagentTiming":{"settledMs":3200,"active":{"since":1792550400000,"through":1792550400600}}}
+```
+
+`subagentTiming` 字段：
+
+- `settledMs`：已结束轮次累计耗时，毫秒。
+- `active`：可选，当前开放轮次的 `since` / `through` 时间边界，毫秒。
+- `lastTurnCompleted`：可选，最近已关闭轮次是否正常完成；轮次开放时可能缺省。
+- 不要用耗时投影推断 `running`，以成员状态通知为准。
+
+失效例子：
+
+```json
+{"kind":"agent-team-updated","sessionId":"session-lead","asOfSeq":121,"agentTeam":null}
+```
+
+失效应显示“待同步/数据暂不可用”，重新查询需要的会话；不能把 null 解释成已完成或空板。重建失效通知可能沿用旧水位，因此同 seq 的 null 也必须处理。
+
+这些团队、目录、身份、耗时更新发往 control/legacy，**不受当前 conversation 的订阅会话过滤**。成员自己的 `tasks-updated` 则按原有交互通道规则处理；split control 不需要切换订阅。
+
+### 7.3 成员运行状态
+
+新帧：
+
+```json
+{"kind":"session-status","sessionId":"session-scout","running":true}
+```
+
+```json
+{"kind":"session-status","sessionId":"session-scout","running":false}
+```
+
+该帧发送到所有 control/legacy，不受聊天订阅过滤。它是进程内状态通知，没有 seq 或历史重放保证。
+
+- 初始状态从 `sessions.items[].running` 获取；缺行时保持未知，不能伪造运行状态。
+- 重连或 APP 回前台后重新查询 `sessions`。
+- 查询期间缓存新到的 `session-status`，先安装列表结果，再覆盖查询期间收到的状态，避免较早列表快照覆盖较新通知。
+- Host 创建/释放成员 Agent 或移除驻留 Session 时网关也会同步状态；`running:false` 只表示当前没有运行，不表示任务完成、成员删除或无法恢复。
+- `phase:failed`、`phase:provisioning` 优先于运行状态展示。
+
+### 7.4 顺序、缓存与版本
+
+建议至少维护：
+
+```text
+teamByLead[(gatewayId, leadSessionId)]
+catalogByParent[(gatewayId, parentSessionId)]
+statusBySession[(gatewayId, sessionId)]
+projectionCut[(gatewayId, sessionId, projectionKey)]
+conversationByTarget[ConversationTarget]
+```
+
+处理规则：
+
+1. 持久日志 seq 只在同一会话内可比。Lead 的 121 和成员的 20 没有大小关系。
+2. 同一会话不同投影分别记录水位，不能收到 `subagentTiming` 的 200 就丢弃晚到的 `agentTeam` 199。
+3. 同一键收到较旧查询响应，不覆盖已收到的较新精确实时值；使用 `requestId` 丢弃过期页面查询。
+4. 一次控制重建基线是新的控制代际；基线替换必须允许相同 seq 的 null 失效，不能使用简单的 `incomingSeq <= cachedSeq` 全部过滤。
+5. `migration-required` 没有权威 seq，只作为提示缓存，不覆盖已有精确投影。
+6. `agentTeam.failure` 表示投影停在最后有效状态。保留画面并显示异常，停止把它标成持续更新成功。
+7. 未识别的新 JSON 字段应忽略或保留；未知枚举显示兜底状态，不让整个连接解码失败。
+
+## 8. 子会话历史与分页
+
+**连接：conversation**。首次历史请求：
+
+```json
+{"type":"history","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","requestId":"history-scout-001","maxMessages":12,"view":"conversation"}
+```
+
+响应示意：
+
+```json
+{
+  "kind":"history",
+  "requestId":"history-scout-001",
+  "sessionId":"session-scout",
+  "parentSessionId":"session-lead",
+  "subagentMode":"continuable",
+  "historyFormatVersion":4,
+  "cursor":80,
+  "hasMore":true,
+  "nextBeforeSeq":50,
+  "view":"conversation",
+  "bytes":1200,
+  "events":[],
+  "projections":{"asOfSeq":80,"values":{"subagent":{"mode":"continuable","label":"逐帧分析","seq":1},"todos":[],"turnOutline":[]}}
+}
+```
+
+示例仅突出元数据，`events` 实际按历史分页返回，事件结构沿用 V4 规范。`cursor` 是 Host 开启快照时的持久水位，不是当前展示列表最后一条 seq；对话过滤后 events 可能为空，仍需处理分页游标。
+
+更早一页：
+
+```json
+{"type":"history","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","requestId":"history-scout-page-002","beforeSeq":50,"historyFormatVersion":4,"maxMessages":12,"view":"conversation"}
+```
+
+- 用上次响应的 `nextBeforeSeq`，不要自己 `seq - 1`。
+- 只在 `hasMore:true` 时继续分页；空 events 但带有效下一游标仍可翻页。
+- `beforeSeq` 必须同时携带 `historyFormatVersion:4`。
+- 历史与消息体可按字节裁剪；APP 不得假设每页恰好 12 条消息。
+- 对话视图使用 `view:"conversation"`；完整历史/轨迹需要时不传该字段，沿用已有解码器。
+- 分页响应只补旧正文，不替换新快照的实时 active attempt，不倒退当前持久 cursor。
+- 更多正文、工具结果和轮次大纲语义见 [rc.2 接入说明](dsh-rc2-mobile-integration.md) 和 [轮次导航说明](turn-outline-app-integration.md)。
+
+通常首次进入直接使用下一节的原子订阅基线即可，不需要先 history 再 subscribe；history 主要用于更早分页、单独只读预览和恢复补查。
+
+## 9. 切换智能体视图与实时输出
+
+**连接：conversation**。切入子成员：
+
+```json
+{"type":"subscribe","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","assistantStream":true}
+```
+
+确认帧：
+
+```json
+{
+  "kind":"subscribed",
+  "sessionId":"session-scout",
+  "parentSessionId":"session-lead",
+  "subagentMode":"continuable",
+  "subscriptionId":"subscription-scout-1",
+  "assistantStream":true
+}
+```
+
+随后原子基线示意：
+
+```json
+{
+  "kind":"session-snapshot",
+  "sessionId":"session-scout",
+  "parentSessionId":"session-lead",
+  "subagentMode":"continuable",
+  "subscriptionId":"subscription-scout-1",
+  "streamId":"stream-scout-1",
+  "replace":true,
+  "historyFormatVersion":4,
+  "cursor":80,
+  "hasMore":false,
+  "events":[],
+  "bytes":0,
+  "view":"conversation",
+  "projections":{"asOfSeq":80,"values":{"todos":[],"turnOutline":[]}},
+  "assistantStream":{"revision":0}
+}
+```
+
+`assistantStream` 可以包含正在输出的 `activeAttempt`。这是同一个快照切点的原子基线，客户端必须连同历史一起安装。完整 token 帧见 [实时流协议](dsh-rc2-mobile-integration.md)。
+
+持久事件与 token 示意：
+
+```json
+{"kind":"event","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","subscriptionId":"subscription-scout-1","streamId":"stream-scout-1","seq":81,"time":1792550401000,"event":{"type":"turn/start","turn":2}}
+```
+
+```json
+{"kind":"assistant-stream","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","subscriptionId":"subscription-scout-1","streamId":"stream-scout-1","frame":{"type":"start","attemptId":"attempt-1","revision":1,"startedAfterSeq":81,"turn":2,"step":0}}
+```
+
+```json
+{"kind":"assistant-stream","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","subscriptionId":"subscription-scout-1","streamId":"stream-scout-1","frame":{"type":"chunk","attemptId":"attempt-1","revision":2,"index":0,"time":1792550401100,"chunk":{"type":"text-delta","index":0,"text":"已完成素材分析"},"turn":2,"step":0}}
+```
+
+这些是已启用 assistant stream 的 follower 帧。普通 legacy 持久事件可以只有 sessionId，不能要求所有旧事件都有父子地址字段。
+
+### 9.1 切换流程
+
+1. 立即保存旧目标草稿、滚动位置、已加载正文和分页状态。
+2. 设置新的 `desiredTarget`，显示该成员缓存或 loading；输入框草稿同步切换。
+3. conversation 对新目标发送 `subscribe`。新订阅自动取消旧 follower，无须先 unsubscribe。
+4. 等待新 `subscribed`，安装新的 `subscriptionId`；再等待对应 `session-snapshot`。
+5. 接受快照后设置新的 `streamId`，替换该视图的当前历史窗口与 token 基线；已有更早分页可按 seq 去重保留。
+6. 此后的事件只交给匹配当前 target、subscriptionId、streamId 的聊天 reducer。
+7. control 继续接收原 Lead 看板、所有成员状态与目录变化。
+8. 切回 Lead 时重新发送普通地址：
+
+```json
+{"type":"subscribe","sessionId":"session-lead","assistantStream":true}
+```
+
+停止浏览所有会话时：
+
+```json
+{"type":"unsubscribe"}
+```
+
+此操作只停止订阅，不停止智能体执行。离开某成员页面也不会停止它的任务；停止执行必须显式调用 `session-cancel`。
+
+### 9.2 快速点击与代际隔离
+
+- 一条 conversation 连接同一时刻只有一个活动订阅。切换不等于同时打开多个 token 流。
+- `subscribed` 不回显请求 ID。建议订阅命令单飞：等待本次确认后再发下一次订阅，等待期间把用户意图合并为最后一个目标。
+- 确认到达时若目标已经不是最新 `desiredTarget`，不把它展示成当前页，继续发送最新目标。
+- 只按 sessionId 过滤不够；A → B → A 时第一次 A 的延迟帧可能污染第二次 A。必须使用 `subscriptionId` 和 `streamId`。
+- 服务端已取消旧 follower 并阻止过期异步开流继续发布；APP 仍需过滤已经进入网络缓冲或自身任务队列的旧帧。
+- 对陌生 streamId，只有新 `session-snapshot` 可以安装它，不能用一个 token chunk 建立新代际。
+- assistant revision/index 与持久 seq 是两套时钟，token 不消耗持久 seq。
+- `session-stream-reset` 后丢弃该 stream 的临时 token 状态，等待自动重新打开的快照；明确的地址错误需要修正，不应无限重发。
+
+## 10. 对子智能体发送消息
+
+**连接：conversation**。与 Lead 一样仍使用 `message`，新增父子地址：
+
+```json
+{
+  "type":"message",
+  "requestId":"human-scout-001",
+  "sessionId":"session-scout",
+  "parentSessionId":"session-lead",
+  "subagentMode":"continuable",
+  "mode":"queue",
+  "text":"请把第二段录屏的切点再提前半秒，并说明原因。",
+  "clientTimeZone":"Asia/Shanghai"
+}
+```
+
+成功：
+
+```json
+{
+  "kind":"sent",
+  "requestId":"human-scout-001",
+  "sessionId":"session-scout",
+  "parentSessionId":"session-lead",
+  "subagentMode":"continuable",
+  "mode":"queue",
+  "messageId":"accepted-message-123"
+}
+```
+
+| 字段 | 规则 |
+|---|---|
+| `requestId` | 建议 APP 在发送前生成唯一 ID 并保存；子消息会传递给官方接口，响应回显 |
+| `text` | 非空文本，或者提供至少一张有效图片 |
+| `images` | 沿用现有格式 `[{mediaType,data,name?}]`，data 为 Base64 |
+| `mode` | `queue` 默认：排到后续轮次；`steer`：尝试注入最近步骤，Host 可按其执行状态回退 |
+| `clientTimeZone` | 可选，合法 IANA 名称或 UTC，沿用现有时间语义 |
+| `messageId` | 成员 inbox 接受的消息 ID，不是 Session ID，也不是工具调用 ID |
+
+发送图片示例结构：
+
+```json
+{"type":"message","requestId":"human-scout-image-002","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","mode":"queue","text":"请比较这帧画面","images":[{"mediaType":"image/png","data":"<实际图片的Base64>","name":"frame.png"}]}
+```
+
+上例 Base64 是占位符，联调时必须替换为实际图片。图片类型、大小与数量限制继续遵守 [主协议的图片输入规则](../PROTOCOL.md)，由网关和 Host 的附件校验共同执行。
+
+发送状态：
+
+```text
+草稿 → 发送中 → sent（已被 inbox 接受）→ 实际消息/输出事件
+         ↘ 明确 error：展示错误，保留草稿
+         ↘ 断线且未收到回执：标为发送结果未知，恢复后核对历史与队列
+```
+
+- `sent` 只表示接受，不表示该任务已完成或已有回复。
+- 不要收到 sent 就把其他成员的输入框清空；按发送时固定的 target 和 requestId 更新。
+- 子消息的 `messageId` 可与实时 `user/message.event.raw.id` 或历史 `user/message.data.id` 对照；消息仍在队列时还没有对应的已执行正文。
+- 不保证自动重试去重。没有回执时，不要重连后盲目自动重发，以免对成员重复下达任务；先查询历史和队列，再提供用户可控的重试。
+- one-shot、unknown 不能发送，网关返回 `subagent/not-resumable`。
+- 即使 active，父 Agent 不在场、恢复容量不足、模型不能接收图片等情况也可能失败，按第 15 节处理。
+- 不要为子会话携带 `workspaceId`、`cwd` 或 `agentPreset` 来创建新会话；成员对话必须有明确 sessionId 与父地址。
+
+### 10.1 用户把任务交给不同成员
+
+APP 可以提供两个入口，语义要明确：
+
+1. **继续沟通**：进入某成员会话发送要求，该消息只路由给该成员。
+2. **创建/调整共享任务**：在 Lead 会话发送要求，如“请把 task-2 重新分配给 music-producer，其他任务不变”。由 Lead 调用团队工具处理，APP 等待 `agent-team-updated`。
+
+给成员发送一段文本不会由网关自动新建共享任务，也不会自动改变 owner。APP 可以预填指令，但要让用户看到实际发送给哪个会话。
+
+创建新团队前先查询现有 `agent-presets`，由用户选择 Host 实际返回的团队模式 ID，再使用现有 `session-create` / 空会话 `select-agent-preset` 流程。不要硬编码实验性 preset ID；模式选择细节见 [会话模式接入](session-agent-preset-app-integration.md)。
+
+## 11. 停止与继续
+
+**连接：control**。停止成员：
+
+```json
+{"type":"session-cancel","requestId":"stop-scout-001","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable"}
+```
+
+```json
+{"kind":"session-cancelled","requestId":"stop-scout-001","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","accepted":true}
+```
+
+- accepted 表示已接受取消请求，执行方可能稍后才停止；以 `session-status` 和轮次事件更新界面。
+- 已空闲、已结束或不在驻留运行中的目标，官方接口可能接受为空操作。
+- 不自动清空成员排队消息，不删除成员，不把它拥有的共享任务改成 completed。
+- 恢复使用同一成员地址重新发送一条 `queue` 消息，比如“继续处理当前任务”；是否能恢复由 Host 校验。
+- 不要对成员调用缺少父地址的普通 `session-cancel`，Host 会拒绝普通会话路由。
+
+## 12. 成员待办、审批与轨迹
+
+### 12.1 成员自己的待办
+
+**连接：control**：
+
+```json
+{"type":"tasks","requestId":"todos-scout-001","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable"}
+```
+
+```json
+{"kind":"tasks","requestId":"todos-scout-001","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","asOfSeq":80,"todos":[{"content":"整理镜头切点","status":"in_progress"}]}
+```
+
+`goal` 同样支持父子地址，返回该会话自己的 Goal。历史和订阅快照中的 `projections.values.todos` / `goal` 也可直接初始化。实时 `tasks-updated` / `goal-updated` 用它们自己的 sessionId 路由，禁止覆盖团队共享任务。
+
+### 12.2 审批和用户提问
+
+- 复用 `question-requested`、`approval-requested`、对应响应和 resolved 帧，不新增团队审批协议。
+- 请求中的 `sessionId` 可能是任何成员或更深子会话。按 `rpcId` 去重并保存真实 sessionId。
+- 切入子会话时网关会按现有机制重放仍待处理的卡片，split 模式的卡片发到 control。
+- 不要把子成员审批发送给 Lead，也不要仅显示当前页而丢掉后台其他成员的待处理卡片。
+- 用户点击后台审批通知，可按目录/团队缓存定位该成员；若地址暂不可得，先保留卡片并刷新目录。
+
+### 12.3 对话与执行轨迹
+
+子会话复用现有 V4 消息与工具轨迹渲染器。轨迹数据属于该成员会话，不能拼接进 Lead 的 seq 空间。`assistant-stream`、持久 `event`、历史原始事件的结构不同，继续使用已有转换层。
+
+## 13. APP 数据层与状态机建议
+
+建议拆为三个可独立更新的状态：
+
+```text
+TeamStore      : Lead 的成员与共享任务、每个父节点的目录
+SessionStore   : 各会话摘要、运行状态、独立 todos / goal / outline
+ConversationUI : 当前 target、订阅代际、当前正文窗口、stream、草稿与滚动位置
+```
+
+事件路由示意：
+
+```text
+onControl(frame):
+  projection-baseline     → 安装/替换该控制代际的投影集合
+  agent-team              → 按 requestId 和该键水位更新指定 Lead
+  agent-team-updated      → 按 sessionId 替换对应 agentTeam
+  subagents               → 更新指定父节点目录
+  subagents-updated       → 替换指定父节点目录
+  subagent-identity-updated → 更新该子会话身份
+  subagent-timing-updated → 更新该子会话耗时
+  session-status          → 更新该会话 running
+  tasks-updated           → 更新该会话内部待办
+  question/approval       → 按真实 sessionId 和 rpcId 保存
+
+onConversation(frame):
+  subscribed              → 关联当前单飞切换请求，记录 subscriptionId
+  session-snapshot        → 仅接受最新目标的 subscription，安装 streamId 与基线
+  event / assistant-stream → 仅当前 target + subscriptionId + streamId 可以进入当前聊天 reducer
+  history                 → 按 requestId 找原始 target，仅补该会话旧正文
+  sent                    → 按 requestId 找原始发送目标，更新该次发送状态
+```
+
+业务层计算：
+
+```text
+currentMember = team.members.find(id == currentTarget.sessionId)
+currentMemberTasks = team.tasks.filter(ownerName == currentMember.name)
+unassignedTasks = team.tasks.filter(ownerName 缺省)
+memberStatus = phase != active ? phase : running已知 ? running/inactive : unknown
+```
+
+实现时 `currentMember == null` 要有兜底，可能正在看普通子智能体或旧成员数据。点击任务 owner 找不到成员时只展示名字，不构造不存在的导航地址。
+
+不要把当前选中的成员写成所有请求的隐式全局变量。发送、分页、停止等异步请求发出前，复制并固定完整 target，之后即使用户切换页面也不能改变该次请求的目的地。
+
+## 14. 断线、后台和恢复
+
+1. 连接断开时保留成员、任务和正文缓存，标记可能过期。停止认为当前 token 流仍有效。
+2. 重连两条连接，检查新的 capabilities；网关可能已切换版本或 Host 配置。
+3. control 接收新的 `projection-baseline`，并重查 `sessions`、当前 Lead 的 `agent-team` 和已展开分支的 `subagents`。
+4. conversation 使用当前完整 target 重新 subscribe；新快照会恢复进行中的输出。
+5. 新 streamId 是新代际，不能接着旧的 revision/index 拼接。快照是替换型基线。
+6. 按真实子 sessionId 恢复审批和提问卡片。
+7. 对发送结果未知的消息核对历史/队列，不自动重发。
+8. 恢复不了的分支保持错误态，允许返回 Lead 或切其他成员；不要清空整个团队页面。
+9. APP 回前台时执行同样的轻量刷新；不能假定后台期间运行状态通知全部收到。
+
+网关本身会在 Host control 流或会话 follower 中断后重开，并发送新基线；客户端不需要为每条 token 再查询团队。团队插件状态、会话持久数据迁移等永久问题要显示给用户。
+
+## 15. 错误处理表
+
+常见错误统一使用 `kind:"error"`，包含 `code`、`message`，查询通常还带 `requestType`、`sessionId` 和原 `requestId`。本次新增的查询、历史、停止及正常子发送路径会保留关联信息；兼容旧输入校验错误时应容忍可选字段缺省。
+
+| code / 情况 | 含义 | APP 动作 |
+|---|---|---|
+| `bad-request` | 地址缺字段、相同父子 ID、非法模式等 | 保留草稿，修正 APP 参数；不要无限重试 |
+| `wrong-channel` | 发到另一条连接 | 修正网络分发，不提示用户重新建任务 |
+| `session/not-found` | 指定会话不存在 | 刷新目录，允许返回 Lead |
+| `session/agent-busy` | 子会话误走普通会话路由等 | 检查是否丢失 parentSessionId / subagentMode |
+| `subagent/unauthorized` | 父子不匹配、模式不匹配 | 停止该错误地址订阅，刷新目录，不尝试绕过关系校验 |
+| `subagent/not-found` | 子会话不可用 | 展示分支不可用并允许重试/返回 |
+| `subagent/catalog-diagnostic` | 子身份缺失或目录损坏 | 显示诊断，不伪造 continuable 地址 |
+| `subagent/not-resumable` | 该模式不能继续 | 只读展示，禁用发送和停止 |
+| `subagent/parent-unavailable` | 直接父 Agent 当前不可用 | 提示父会话暂不可用，用户可回父会话打开后再试；网关不自动重建父身份 |
+| `subagent/delivery-unavailable` | 成员 inbox 或冷恢复当前无法接受 | 保留草稿，允许稍后重试 |
+| `subagent/attachment-invalid` | 图片或模型能力校验失败 | 提示更换图片/改为文本 |
+| `subagent/invalid-time-zone` | clientTimeZone 非法 | 修正客户端时区编码 |
+| `history-format-mismatch` | 分页未带 V4 或旧缓存游标 | 清理该会话旧格式游标，重取基线 |
+| `unsupported-session-format` | 会话格式不支持 | 停止自动循环，提示处理 Host 会话格式 |
+| `SESSION_QUERY_PERSISTENCE_FAILED` | 持久化读取失败；可能是旧格式拒绝迁移 | 展示实际错误，旧格式拒绝时不要无限重开 |
+| `gateway/invocation-unavailable` | Host 没挂载官方接口或版本不匹配 | 提示检查 Host 插件与版本 |
+| `agentTeam.failure` | 投影发现错误记录，保持最后有效值 | 显示“团队数据异常”，保留可见内容并建议检查桌面端 |
+| `projectionState:unavailable` | 没有投影 | 显示不可用，不当成网络失败或空团队 |
+| `projectionState:migration-required` | 迁移前提示 | 只读提示，重新打开会话获取权威值 |
+
+Host 的错误码可能扩展，未识别错误也要展示 message 并允许用户返回其他会话。服务端的 `session-stream-reset` 是独立帧，不能只在 `kind:error` 分支处理。
+
+## 16. 推荐界面结构
+
+与用户提供的 WebUI 对齐，可按以下页面实现：
+
+1. **聊天顶部团队按钮**：展示子成员数量。当前普通会话只存在 Lead 时可收起入口。
+2. **团队面板**：上半部成员列表，显示 name、运行/创建状态、当前会话标记；下半部共享任务。
+3. **共享看板**：全部/当前成员/未分配筛选，三状态分栏；卡片显示标题、负责人、写入范围、状态。
+4. **任务详情**：完整描述、依赖、ready、写入范围、警告、任务 ID 与 revision。失败数据保持可读。
+5. **成员聊天页**：面包屑保留 Lead 标题与成员名，输入框明确目标，运行时提供停止。
+6. **普通子智能体树**：展示 label、mode，展开加载后代；外部节点和只读模式标识清楚。
+7. **后台交互提示**：其他成员等待提问或审批时提供可定位入口。
+
+成员自己的内部待办可以放在该成员聊天页的“待办”面板，不混入共享看板。切换成员不切换 TeamContext，不关闭 control，不清除其他成员草稿。
+
+## 17. 最小联调脚本顺序
+
+以下为客户端应发送的 JSON 顺序，A/B 两条连接使用同一个已配对设备身份：
+
+```text
+A(control)       建连 → hello → projection-baseline
+B(conversation)  建连 → hello
+A → {"type":"sessions"}
+A → {"type":"agent-team","sessionId":"session-lead","requestId":"t1"}
+A → {"type":"subagents","sessionId":"session-lead","requestId":"c1"}
+B → {"type":"subscribe","sessionId":"session-lead","assistantStream":true}
+B ← subscribed / session-snapshot
+
+用户点 footage-scout：
+B → {"type":"subscribe","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","assistantStream":true}
+B ← 新 subscribed / 新 session-snapshot
+A → {"type":"tasks","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","requestId":"todos1"}
+B → {"type":"message","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","mode":"queue","text":"继续细化切点","requestId":"m1"}
+B ← sent / 后续成员事件
+A ← session-status / agent-team-updated 等（具体到达顺序不固定）
+
+用户点停止：
+A → {"type":"session-cancel","sessionId":"session-scout","parentSessionId":"session-lead","subagentMode":"continuable","requestId":"stop1"}
+A ← session-cancelled
+
+用户回 Lead：
+B → {"type":"subscribe","sessionId":"session-lead","assistantStream":true}
+B ← 新 subscribed / 新 session-snapshot
+```
+
+用真实响应中的 ID 替换示例 ID；团队只有一个 Lead 时，先在 Lead 请求创建团队成员和共享任务，再重复读取面板。
+
+## 18. APP 验收清单
+
+| 场景 | 预期 |
+|---|---|
+| Lead + 3 名成员 + 3 条共享任务 | 成员总数 4，子成员数 3，owner 与任务正确匹配 |
+| 点击任一成员 | 聊天目标、标题、正文、输入草稿和轨迹同时切换 |
+| 切到成员后任务在后台完成 | 看板实时更新，无需先返回 Lead |
+| 成员运行中/空闲 | 状态变化，不改变共享任务的持久 status |
+| 同一成员有两项共享任务 | 成员筛选展示两项，不只取第一项 |
+| 任务未分配 / owner 暂找不到 | 仍然展示，不自动归属 Lead |
+| 依赖未完成 | pending 且 !ready 显示受阻 |
+| 任务被删除、重开、重新分配 | 完整替换正确，无旧 owner 或重复任务残留 |
+| 成员正在创建/创建失败 | 按 phase 展示，禁用不可进入的目标 |
+| 子会话发文本和图片 | 路由给正确成员，Lead 不收到误发文本 |
+| 成员 queue / steer | 回执正确，实际执行由 Host 事件体现 |
+| 停止后继续 | 停止保留成员与任务，再发消息可按 Host 条件继续 |
+| Lead → A → B → A 快速切换 | 旧 token、旧历史和旧回执不污染新页面 |
+| 切换时仍有分页请求在途 | 响应只补原 target 缓存 |
+| 层级 Lead → A → C | C 用 A 做直接父，不误用 Lead |
+| one-shot / external / unknown | 按模式限制交互，unknown 先解析身份 |
+| 控制连接重连 / Host 控制流重建 | 新基线正确安装，null 失效正确处理 |
+| token 过程中断线 | 新快照恢复，旧 attempt 不重复拼接 |
+| App 后台再回前台 | 刷新 running、团队板和当前订阅 |
+| 发送后断线无回执 | 标记结果未知，不自动重复发送 |
+| 子成员出现提问/审批 | 正确关联其真实 sessionId，重放不重复 |
+| 无团队插件 / 没有子节点 | unavailable 与空数组有不同空态 |
+| 团队记录损坏 / 旧格式迁移失败 | 显示错误并保留数据，不无限重试 |
+| 两个网关都有 task-1 | 缓存互不覆盖 |
+| 旧网关缺 capability | APP 可继续使用原普通对话，并提示团队能力需升级 |
+
+## 19. 网关实现与验证入口
+
+| 内容 | 仓库位置 |
+|---|---|
+| 地址校验及移动地址映射 | `lib/session-target.mjs` |
+| 官方 Host 端点与参数适配 | `lib/dsh-host-adapter.mjs` |
+| 查询、消息、状态帧与控制投影转发 | `lib/index.mjs` |
+| 子会话实时订阅与切换隔离 | `lib/session-follower.mjs` |
+| 查询、路由和 WebSocket 回归 | `test/agent-team.test.mjs` |
+| 官方严格描述符 / Gateway / Peer 契约验证 | `test/agent-team-official.test.mjs` |
+
+网关自测：
+
+```bash
+npm test
+```
+
+用本机已安装的官方 DSH 验证生成描述符与参数契约，不启动真实用户会话：
+
+```bash
+DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/agent-team-official.test.mjs
+```
+
+该契约测试使用官方 Gateway、Connection 和生成的严格描述符，业务服务为测试替身；不能替代 APP 与真实团队运行的人工联调。最终按第 18 节逐项验收。
+
+## 20. 交给 APP 开发者的实施顺序
+
+1. 增加 capability 识别与 ConversationTarget 模型，保留多网关身份。
+2. 在现有历史、订阅、发送、停止、tasks/goal 请求中编码子地址。
+3. 增加团队/目录查询和四类投影更新解码；接入 control 基线。
+4. 实现 TeamStore、目录树与 per-session running 状态。
+5. 实现团队成员面板、任务详情和看板筛选。
+6. 实现成员视图切换、单飞订阅、subscriptionId/streamId 过滤。
+7. 接通子成员输入、图片、停止、发送结果未知与审批恢复。
+8. 实现重连刷新、错误降级和全部验收用例。
+
+本期完成后，APP 的团队浏览、成员聊天与共享看板可以与 WebUI 使用同一份 Host 数据；后续若需要原生拖拽分配、直接编辑任务等操作，需要另外设计并实现 Host 有授权语义的变更接口，不能由 APP 本地修改投影来冒充执行成功。