dsh-plugin-mobile-gateway 0.6.9 → 0.7.1

package/PROTOCOL.md

@@ -1,6 +1,6 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.9）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.7.1）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -77,7 +77,7 @@ const pairingText = Buffer.from(JSON.stringify(payload), 'utf8').toString('base6
 ```json
 { "kind": "paired", "token": "<长期设备 token>",
   "device": { "id": "...", "name": "iPhone", "createdAt": 1787111700000 } }
-{ "kind": "hello", "protocol": 3, "capabilities": ["images", "file-downloads"], "authenticated": true,
+{ "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "file-downloads"], "authenticated": true,
   "device": { "id": "...", "name": "iPhone" }, "port": 3080, "clients": 1 }
 ```
 
@@ -162,11 +162,11 @@ Human-in-the-loop 分为两条独立通道：
 - **提问**：Agent 的 `ask_user_question` 工具向用户收集答案。
 - **审批**：高风险工具操作（例如沙箱升权）请求一次性允许或拒绝。
 
-二者都是 API Gateway 的临时请求，不属于持久化的 `session/event`，且都必须以其原始 `rpcId` 通过专用响应帧回答，不能作为普通 `message` 发送。
+二者都是 Host waterfall 的临时请求，不属于持久化的 `session/event`，且都必须以插件为该次请求生成的 `rpcId` 通过专用响应帧回答，不能作为普通 `message` 发送。该内部实现不改变移动端帧格式。
 
 ### 3.1 提问与回答
 
-Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway 的 `events.mux()` 收到临时的待回答请求，并推送给移动端。
+Agent 调用 DSH 的 `ask_user_question` 工具时，插件直接接入 Host 的 `user-questions/request` waterfall，并把临时请求投影给移动端。若没有可处理该 Session 的移动连接，插件调用 `next()`，由 WebUI 或后续 Host answerer 处理。
 
 #### `question-requested` — 服务端推送问题
 
@@ -191,7 +191,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 }
 ```
 
-- `rpcId`：API Gateway 为这一整批问题生成的稳定 ID。回答或取消时必须原样返回，客户端不得自行生成。
+- `rpcId`：移动网关为这一整批问题生成的不透明稳定 ID。回答或取消时必须原样返回，客户端不得自行生成或解析。
 - `questions`：一次工具调用中的完整问题批次；可能包含多题。
 - `id`：问题 ID，必须在对应答案中原样返回。
 - `header` / `detail`：可选展示信息。
@@ -226,7 +226,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 }
 ```
 
-提交规则由 API Gateway 严格校验：
+提交规则由移动网关在进入 Host waterfall 前严格校验：
 
 - 必须一次提交这一批中的全部问题，`answers` 数量、顺序和 `id` 必须与 `questions` 一致。
 - `selected` 中的值必须与原始 `options[].label` 完全一致，且不能重复。
@@ -264,13 +264,13 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "outcome":"answered" }
 ```
 
-`outcome` 为 `answered` 或 `cancelled`。WebUI、iOS 或其他客户端中的第一个合法响应获胜；所有移动连接都会收到最终状态并应关闭对应选择界面。移动端断线重连后，API Gateway 会重放仍待回答的问题；DSH 进程重启则会取消这些仅存在于运行时的问题。
+`outcome` 为 `answered` 或 `cancelled`。存在匹配 Session 的移动连接时，移动网关优先认领请求，多台移动设备中的第一个合法响应获胜；若没有匹配连接或连接全部断开，则通过 `next()` 回退给 WebUI/后续 Host answerer。所有移动连接都会收到由移动端完成的最终状态并应关闭对应选择界面。重连时网关会重放仍由它持有的问题；DSH 进程重启则会取消这些仅存在于运行时的问题。
 
 ---
 
 ### 3.2 操作审批
 
-当 DSH 的工具管线要求人工授权时，插件会从 API Gateway 收到一次 `approval/requested`。这正是 Web UI 中“等待审批”卡片对应的事件：`reason` 是面向用户的审批说明，`toolName` 标识请求操作的工具，`callId` 可用于与实时工具调用轨迹关联。
+当 DSH 的工具管线要求人工授权时，插件会接入一次 Host `approval/request` waterfall，并向移动端投影为 `approval-requested`。这正是 Web UI 中“等待审批”卡片对应的能力：`reason` 是面向用户的审批说明，`toolName` 标识请求操作的工具，`callId` 可用于与实时工具调用轨迹关联。
 
 #### `approval-requested` — 服务端推送待审批操作
 
@@ -288,7 +288,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 ```
 
 - `rpcId`：本次可回答请求的稳定 RPC ID；提交决定时必须原样返回。
-- `approvalId`：审批审计 ID；同样必须原样返回，并用于将最终状态关联到本地审批卡片。
+- `approvalId`：移动网关生成的本次审批关联 ID；同样必须原样返回，并用于将最终状态关联到本地审批卡片。
 - `toolName`：请求审批的工具名。
 - `callId` / `reason`：可选。前者可关联工具调用，后者应直接显示为待审批原因。
 - `replay: true`：表示当前仍未决定的审批在移动端连接或切换 Session 后重放。客户端应按 `rpcId` 去重。
@@ -321,7 +321,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "approvalId":"approval-1", "outcome":"allowed-once", "accepted":true }
 ```
 
-如果 Web UI 或另一台移动设备已经先作出决定，则回执为 `accepted:false`，并附带 `reason:"not-pending"`。收到错误帧或未被接受的回执时，客户端应保留当前状态，等待最终状态或重新打开事件流。
+如果另一台移动设备已经先作出决定，或请求已经回退给 WebUI/后续 answerer，则回执为 `accepted:false`，并附带 `reason:"not-pending"`。收到错误帧或未被接受的回执时，客户端应保留当前状态，等待最终状态或重新打开事件流。
 
 #### `approval-resolved` — 服务端广播最终状态
 
@@ -330,7 +330,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "approvalId":"approval-1", "outcome":"allowed-once" }
 ```
 
-`outcome` 为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。所有移动连接都会收到最终状态并关闭对应审批卡片。移动端断线重连后，API Gateway 会重放仍待决定的审批；已决审批不会重放。
+`outcome` 为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。所有移动连接都会收到由移动网关完成的最终状态并关闭对应审批卡片。移动端断线重连后，网关会重放仍由它持有的审批；已决或已回退的审批不会重放。
 
 ---
 
@@ -546,6 +546,8 @@ let image = [
 | `search` | `query` | 会话全文搜索 |
 | `session-stats` | `sessionId` | 执行统计投影（输入框统计条数据源） |
 | `context-usage` | `sessionId` | token 用量 + 上下文占用投影 |
+| `tasks` | `sessionId` | 当前任务列表（`todos` projection） |
+| `goal` | `sessionId` | 当前目标及其 CAS 版本（`goal` projection） |
 
 ### `history` 详细
 ```json
@@ -659,7 +661,93 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 6. 工作区与目录
+## 6. 任务列表与目标
+
+WebUI 中的“任务”与“进行中的目标”分别对应 DSH 的 `todos` 和 `goal` session projection。移动端进入会话后应请求 `tasks` 与 `goal` 取得基线；随后以 `tasks-updated` / `goal-updated` 实时更新 UI。
+
+### 任务列表
+
+```json
+{ "type": "tasks", "sessionId": "session-abc" }
+→ {
+  "kind": "tasks",
+  "sessionId": "session-abc",
+  "asOfSeq": 42,
+  "todos": [
+    { "content": "检查 Android SDK", "status": "completed" },
+    { "content": "创建项目", "status": "in_progress" },
+    { "content": "构建 APK", "status": "pending" }
+  ]
+}
+```
+
+- `todos: null` 表示该会话尚未写入过任务列表；客户端可隐藏任务卡片。
+- 任务由 Agent 的 `todo_write` 更新；移动端只读展示，不能直接改写。
+
+### 当前目标
+
+```json
+{ "type": "goal", "sessionId": "session-abc" }
+→ {
+  "kind": "goal",
+  "sessionId": "session-abc",
+  "asOfSeq": 42,
+  "goal": {
+    "goal": {
+      "id": "goal-opaque-id",
+      "revision": 7,
+      "objective": "初始化一个 Android app",
+      "phase": "active",
+      "maxGoalRounds": 12
+    },
+    "roundsStarted": 3,
+    "createdAt": 1787111700000,
+    "updatedAt": 1787111800000
+  }
+}
+```
+
+`goal: null` 表示没有当前目标。所有目标写操作必须携带刚读取到的 `{id, revision}`。这是 DSH 的 compare-and-set 保护：当 WebUI 或另一台设备已经修改目标时，宿主拒绝陈旧 revision，移动端应重新请求 `goal` 后再提示用户重试。
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `goal-edit` | `sessionId`, `ref`, `objective?`, `maxGoalRounds?` | 修改目标名称（`objective`）或轮数上限，至少提供一项 |
+| `goal-pause` | `sessionId`, `ref` | 暂停当前目标 |
+| `goal-resume` | `sessionId`, `ref` | 继续已暂停/阻塞的目标 |
+| `goal-clear` | `sessionId`, `ref` | 删除当前目标 |
+
+更改目标名称：
+
+```json
+{ "type": "goal-edit", "sessionId": "session-abc",
+  "ref": { "id": "goal-opaque-id", "revision": 7 },
+  "objective": "完成 Android app 初始化" }
+→ { "kind": "goal-edit", "sessionId": "session-abc",
+    "ref": { "id": "goal-opaque-id", "revision": 8 } }
+```
+
+暂停、继续和删除只替换 `type`：
+
+```json
+{ "type": "goal-pause", "sessionId": "session-abc", "ref": { "id": "goal-opaque-id", "revision": 8 } }
+→ { "kind": "goal-pause", "sessionId": "session-abc", "ref": { "id": "goal-opaque-id", "revision": 9 } }
+
+{ "type": "goal-clear", "sessionId": "session-abc", "ref": { "id": "goal-opaque-id", "revision": 9 } }
+→ { "kind": "goal-clear", "sessionId": "session-abc", "cleared": true }
+```
+
+### 实时更新
+
+```json
+{ "kind": "tasks-updated", "sessionId": "session-abc", "asOfSeq": 43, "todos": [ ... ] }
+{ "kind": "goal-updated", "sessionId": "session-abc", "asOfSeq": 44, "goal": { ... } }
+```
+
+服务端只转发 `todos` 与 `goal` projection；客户端按 `asOfSeq` 做高序号覆盖，避免较早推送回写较新的查询结果。
+
+---
+
+## 7. 工作区与目录
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -689,7 +777,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 7. 模型与思考等级
+## 8. 模型与思考等级
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -721,7 +809,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 8. 权限控制
+## 9. 权限控制
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -736,7 +824,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 9. 新会话默认配置
+## 10. 新会话默认配置
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -754,7 +842,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 10. 分支（fork）
+## 11. 分支（fork）
 
 ```json
 { "type": "fork", "sessionId": "session-abc", "atSeq": 42 }
@@ -765,7 +853,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 11. 宿主信息
+## 12. 宿主信息
 
 | type | 返回 |
 |---|---|
@@ -779,13 +867,14 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 12. 服务端主动推送
+## 13. 服务端主动推送
 
 | kind | 触发时机 |
 |---|---|
 | `paired` | 首次配对成功；仅此一次返回长期设备 token |
-| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images","file-downloads"], "authenticated":true, "port":3080, "clients":1 }` |
+| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images","commands","tasks","goals","file-downloads"], "authenticated":true, "port":3080, "clients":1 }` |
 | `event` | 任意会话的 agent 输出（见下） |
+| `tasks-updated` / `goal-updated` | 当前会话的任务列表或目标 projection 发生变化 |
 | `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
 | `approval-requested` / `approval-resolved` | Human-in-the-loop 操作审批请求与最终状态 |
 | `pong` / `subscribed` / `sent` | 对应请求的回复 |
@@ -805,7 +894,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 13. 端到端示例（Postman）
+## 14. 端到端示例（Postman）
 
 1. Connect → 收到 `hello`
 2. `{"type":"sessions"}` → 挑 `sessionId`（或直接下一步自动建）
@@ -818,7 +907,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 14. 安全注意
+## 15. 安全注意
 
 - `/ws/mobile` 的移动网关默认关闭；本机 WebUI 手动开启后，若 5 分钟内没有设备成功连接会自动关闭
 - 网关开启后仍要求已配对设备凭证；不要把 `requireAuth` 设为 `false` 后暴露到网络
@@ -833,7 +922,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 
 ---
 
-## 15. 版本历史（插件）
+## 16. 版本历史（插件）
 
 | 版本 | 新增 |
 |---|---|
@@ -859,6 +948,8 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | v0.6.7 | 订阅已有 Session 时重放待处理 Human-in-the-loop 请求，并增加 Approval 端到端诊断日志与安装版本标记 |
 | v0.6.8 | 会话工作目录受限的文件列表与分块下载：支持图片、文档、IPA、APK 等普通文件，含连接归属、路径越界防护、取消、超时和 SHA-256 完整性校验 |
 | v0.6.9 | 服务端驱动的命令与技能目录：支持本地化 Hint、通用二级选项、专用命令执行，以及 command/compaction 生命周期事件；Host 命令不再作为用户 Prompt 发送 |
+| v0.7.0 | 任务与 Goal 对齐：任务/Goal 基线查询、`todos`/`goal` 实时投影、Goal 改名、暂停、继续与删除 |
+| v0.7.1 | DSH v0.1.2-rc.1 兼容：内部迁移至 Remote Gateway 与 Host waterfall，移除 APIProxy 依赖；`dsh-mobile-v1` 保持不变 |
 
 ---
 

package/README.md

@@ -4,7 +4,17 @@
 
 # dsh-plugin-mobile-gateway
 
-DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
+DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、任务列表和当前 Goal 同步及管理、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
+
+> v0.7.1：适配 DSH v0.1.2-rc.1 Remote Gateway，移除 APIProxy 依赖；移动端协议和现有功能保持兼容。
+
+## 协议与 DSH 兼容层
+
+移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH v0.1.2-rc.1 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals 等 namespace 和严格参数只存在于该适配层。
+
+因此本次从旧 APIProxy 迁移到 Remote Gateway 不要求现有移动端修改：WebSocket 子协议、`hello.protocol = 3`、配对鉴权和已有请求/响应字段保持不变。以后 DSH 调整 Remote API 时，优先只更新插件适配层及契约测试；只有移动协议本身发生不可兼容变化时，才会新增并并行支持新的移动端协议版本。
+
+详细实施边界见 [Remote Gateway 重构实施计划](docs/remote-gateway-refactor-plan.md)。
 
 - WebSocket：`/ws/mobile`
 - 局域网：`ws://<局域网 IP>:3081/ws/mobile`

package/cordis.patch.yml

@@ -1,7 +1,7 @@
 # dsh-plugin-mobile-gateway bundle patch.
 # Applied after dsh-base and dsh-web-app: inserts the persistent /ws/mobile
-# gateway row into the host plane (it consumes the host `webServer` service
-# and the host `session/event` feed, and publishes no service of its own).
+# gateway row into the host plane (it consumes `webServer`, the Host Remote
+# Gateway and the `session/event` feed, and publishes no service of its own).
 - insert:
     - id: mobile-gateway
       name: 'dsh-plugin-mobile-gateway'

package/docs/blog-mobile-gateway.md

@@ -379,7 +379,7 @@ DSH 用 Cordis 的依赖注入容器编排"服务行"。插件通过 `package.js
 const plugin = {
   name: 'mobile-gateway',
   Config,
-  inject: ['webServer', 'apiProxy', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
   apply(ctx, config) { /* ... */ },
 }
 ```

package/docs/remote-gateway-refactor-plan.md

@@ -0,0 +1,52 @@
+# Remote Gateway 重构实施计划
+
+## 目标
+
+在保持移动端 `dsh-mobile-v1`、配对流程和现有消息字段不变的前提下，移除对 DSH `APIProxy` 的依赖，改为只通过 Host 侧 `typertGateway` 访问 DSH v0.1.2-rc.1 Remote API。所有上游协议差异集中在插件内部适配层，后续 DSH 发生破坏性更新时不要求移动端同步升级。
+
+## 稳定边界
+
+- 对移动端：继续协商 `dsh-mobile-v1`，`hello.protocol` 保持 `3`，已有请求和响应帧保持兼容。
+- 对 DSH：仅 `lib/dsh-host-adapter.mjs` 知道 Remote namespace、method、严格参数名、stream opening frame 和错误形态。
+- 对业务编排：`lib/index.mjs` 只调用语义化 Host Adapter，不拼装 Remote 描述符。
+- 对错误：上游带 `code/message` 的错误映射为既有移动端错误帧；未知异常稳定映射为 `internal`。
+- 对历史：适配层把 RC 版压缩的 `chunkrow/*` 记录还原为 v1 已支持的 `assistant/chunk` 事件。
+
+## 实施阶段
+
+### 1. Host Adapter 与普通 RPC
+
+- 封装 `invoke()` / `stream()`，校验关键返回值。
+- 迁移 Session、Workspace、Settings、Commands、Skills、Agent Presets、LLM、Goals。
+- Session 历史通过 `session.follow` 获取快照游标和 projections；旧页通过 `session.page` 读取。
+- Workspace 列表通过 `workspace.follow` 的 baseline 获取。
+- Host 信息由插件本地能力和 Remote catalog 合成，不再依赖已删除的 `host.describe`。
+
+### 2. 实时与 Human-in-the-loop
+
+- 普通实时会话事件继续使用 Host 内部 `session/event`，保持移动端事件帧不变。
+- projection 更新从 `session.control` stream 转发，替代旧 `api.events.mux()` 中的投影帧。
+- approval/question 改为 Cordis waterfall listener；生成插件自有不透明 `rpcId`，等待移动端回答。
+- 只有存在匹配会话的已认证移动连接时才认领 waterfall；否则立即 `next()`，保留 WebUI 回退路径。
+- 连接断开、请求 signal 取消或插件卸载时释放等待者并回退/取消，禁止悬挂 Promise。
+
+### 3. 兼容性测试与门禁
+
+- 使用假的 `typertGateway`，按 RC 的精确 namespace/method/args 测试，不再模拟 APIProxy。
+- 添加 Host Adapter 单元测试，覆盖 direct value、throw、stream baseline、历史 chunk 展开和严格参数形状。
+- 保留现有 WebSocket v1 端到端用例，验证移动端请求/响应字段没有改变。
+- 增加静态门禁：生产代码不得出现 `apiProxy`、旧 `{ rpcId, payload }` Remote 调用或 `api.events.mux()`。
+
+### 4. 配置与文档
+
+- 删除 `apiProxy` 注入声明。
+- 更新 README、PROTOCOL 和 bundle patch 注释，明确移动协议与 DSH Remote 的分层。
+- 保留 `session-query-sqlite` 的按需搜索配置，但将其标记为可选能力，避免它成为插件启动前提。
+
+## 验收标准
+
+1. 插件可在 DSH v0.1.2-rc.1 组合中加载，且不请求 `apiProxy`。
+2. 当前移动端无需修改即可完成配对、会话列表、历史、发送消息、命令、模型、设置、任务、Goal、文件和交互审批。
+3. 全量测试通过；Remote 调用参数均由适配层测试锁定。
+4. 上游 namespace 或数据结构未来变化时，改动范围原则上限定于 Host Adapter 及对应契约测试。
+