dsh-plugin-mobile-gateway 0.4.1 → 0.5.0

package/PROTOCOL.md

@@ -1,8 +1,9 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送消息、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.3.0）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送消息、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.5.0）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
+- **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
 - **公网端点**：必须由 TLS 反向代理提供 `wss://<域名>/ws/mobile`
 - **帧格式**：全部为 JSON 文本帧（UTF-8）
 - **连接即推送**：连上后服务端立刻发送一条 `hello`，之后 agent 输出以 `event` 帧实时推送
@@ -43,12 +44,12 @@ WebUI 中有两个互相独立的开关。它们是本机管理设置，iOS 客
 |---|---|---|
 | 关闭 | 任意 | WebSocket Upgrade 返回 `503 Service Unavailable` |
 | 开启 | 开启（默认） | 必须使用一次性配对码或长期设备 token，否则返回 `401 Unauthorized` |
-| 开启 | 关闭（仅 Debug） | 允许无凭证连接，`hello.authenticated` 为 `false` |
+| 开启 | 关闭（仅 Debug） | 仅 DSH 本机监听允许无凭证连接，`hello.authenticated` 为 `false`；独立局域网监听仍返回 `401` |
 
 - 移动网关默认关闭。手动开启后，默认 5 分钟内没有客户端成功建立连接就自动关闭。
 - 关闭移动网关会关闭现有连接，WebSocket close code 为 `4004`。
 - 从 Debug 模式重新开启鉴权时，所有无凭证连接会被关闭，close code 为 `4003`。
-- Debug 鉴权开关只在当前 DSH 进程中生效；重启后恢复配置中的 `requireAuth: true`。
+- Debug 鉴权开关只影响 DSH 自带的本机监听，并且只在当前 DSH 进程中生效；独立局域网监听始终强制设备鉴权。
 
 #### 首次配对
 
@@ -150,7 +151,111 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 3. 消息（手机 → agent）
+## 3. Human-in-the-loop 提问与回答
+
+Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway 的 `events.mux()` 收到临时的待回答请求，并推送给移动端。该请求不属于持久化的 `session/event`；回答必须使用本节协议，不能作为普通 `message` 发送。
+
+### `question-requested` — 服务端推送问题
+
+```json
+{
+  "kind": "question-requested",
+  "rpcId": "5ce4f5d1-...",
+  "sessionId": "session-abc",
+  "questions": [
+    {
+      "id": "research-direction",
+      "header": "研究方向",
+      "question": "你想深入研究哪个方向？",
+      "detail": "请选择最感兴趣的方向",
+      "options": [
+        { "label": "核心架构", "description": "DSH CLI、profile、bundle 与 Cordis" },
+        { "label": "移动网关", "description": "研究 iOS 与 WebSocket 插件" }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+- `rpcId`：API Gateway 为这一整批问题生成的稳定 ID。回答或取消时必须原样返回，客户端不得自行生成。
+- `questions`：一次工具调用中的完整问题批次；可能包含多题。
+- `id`：问题 ID，必须在对应答案中原样返回。
+- `header` / `detail`：可选展示信息。
+- `options`：可选列表；每项包含 `label` 和可选 `description`。
+- `multiSelect`：`true` 允许多选，缺省或 `false` 为单选。
+- `intent`：可选展示意图。目前可能为 `{ "kind":"plan-review", "approve":"批准选项标签" }`；未知 intent 应退化为普通选项列表。
+- `replay: true`：可选。表示这是移动端连接后重放的仍待回答问题。iOS 必须按 `rpcId` 去重。
+
+### `question-answer` — 移动端提交整批答案
+
+```json
+{
+  "type": "question-answer",
+  "rpcId": "5ce4f5d1-...",
+  "sessionId": "session-abc",
+  "answers": [
+    {
+      "id": "research-direction",
+      "selected": ["移动网关"]
+    }
+  ]
+}
+```
+
+自由输入使用 `custom`。单选题使用 `custom` 时 `selected` 必须为空；多选题可以同时携带两者：
+
+```json
+{
+  "id": "research-direction",
+  "selected": [],
+  "custom": "我想研究 API Gateway 的安全边界"
+}
+```
+
+提交规则由 API Gateway 严格校验：
+
+- 必须一次提交这一批中的全部问题，`answers` 数量、顺序和 `id` 必须与 `questions` 一致。
+- `selected` 中的值必须与原始 `options[].label` 完全一致，且不能重复。
+- 单选题最多选择一项；单选题的 `custom` 与 `selected` 互斥。
+- `custom` 如果存在，去除首尾空白后不能是空字符串。
+
+插件立即返回交付回执：
+
+```json
+{ "kind":"question-response", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc",
+  "action":"answer", "accepted":true }
+```
+
+如果 WebUI 或另一台移动设备已经先回答：
+
+```json
+{ "kind":"question-response", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc",
+  "action":"answer", "accepted":false, "reason":"not-pending" }
+```
+
+答案结构不合法时 `reason` 为 `bad-response`。这两种情况均不能重发为普通聊天消息。
+
+### `question-cancel` — 跳过/取消整批问题
+
+```json
+{ "type":"question-cancel", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc" }
+```
+
+回执仍为 `question-response`，其中 `action` 为 `cancel`。取消会让等待中的 `ask_user_question` 以 `ASK_CANCELLED` 结束，iOS 应在用户确认后再执行。
+
+### `question-resolved` — 服务端广播最终状态
+
+```json
+{ "kind":"question-resolved", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc",
+  "outcome":"answered" }
+```
+
+`outcome` 为 `answered` 或 `cancelled`。WebUI、iOS 或其他客户端中的第一个合法响应获胜；所有移动连接都会收到最终状态并应关闭对应选择界面。移动端断线重连后，API Gateway 会重放仍待回答的问题；DSH 进程重启则会取消这些仅存在于运行时的问题。
+
+---
+
+## 4. 消息（手机 → agent）
 
 ### `message` — 发送消息（会话不存在则创建）
 ```json
@@ -168,7 +273,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 4. 会话与历史查询
+## 5. 会话与历史查询
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -207,7 +312,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 5. 工作区与目录
+## 6. 工作区与目录
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -223,7 +328,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 6. 模型与思考等级
+## 7. 模型与思考等级
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -255,7 +360,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 7. 权限控制
+## 8. 权限控制
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -270,7 +375,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 8. 新会话默认配置
+## 9. 新会话默认配置
 
 | type | 参数 | 说明 |
 |---|---|---|
@@ -288,7 +393,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 9. 分支（fork）
+## 10. 分支（fork）
 
 ```json
 { "type": "fork", "sessionId": "session-abc", "atSeq": 42 }
@@ -299,7 +404,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 10. 宿主信息
+## 11. 宿主信息
 
 | type | 返回 |
 |---|---|
@@ -313,13 +418,14 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 11. 服务端主动推送
+## 12. 服务端主动推送
 
 | kind | 触发时机 |
 |---|---|
 | `paired` | 首次配对成功；仅此一次返回长期设备 token |
 | `hello` | 连接成功：`{ "kind":"hello", "protocol":2, "authenticated":true, "port":3080, "clients":1 }` |
 | `event` | 任意会话的 agent 输出（见下） |
+| `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
 | `pong` / `subscribed` / `sent` | 对应请求的回复 |
 
 ### `event` 帧（agent 实时输出）
@@ -337,7 +443,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 12. 端到端示例（Postman）
+## 13. 端到端示例（Postman）
 
 1. Connect → 收到 `hello`
 2. `{"type":"sessions"}` → 挑 `sessionId`（或直接下一步自动建）
@@ -350,7 +456,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 
 ---
 
-## 13. 安全注意
+## 14. 安全注意
 
 - `/ws/mobile` 的移动网关默认关闭；本机 WebUI 手动开启后，若 5 分钟内没有设备成功连接会自动关闭
 - 网关开启后仍要求已配对设备凭证；不要把 `requireAuth` 设为 `false` 后暴露到网络
@@ -358,10 +464,11 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 - DSH HTTP Server 本身没有 TLS、认证或 Origin policy；公网必须使用 TLS 反向代理和 `wss://`
 - 长期 token 只保存在 iOS Keychain；服务端磁盘仅保存摘要
 - `set-default` / `save-default-model` 是全局写操作，客户端 UI 应加确认
+- `question-answer` / `question-cancel` 会直接恢复或终止等待中的 Agent 工具调用；只允许经过鉴权的可信设备提交，并按 `rpcId` 防止重复操作
 
 ---
 
-## 14. 版本历史（插件）
+## 15. 版本历史（插件）
 
 | 版本 | 新增 |
 |---|---|
@@ -379,6 +486,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 | v0.1.16 | fork（新对话分支） |
 | v0.1.17 | models 支持无 sessionId 全局目录；新增 providers |
 | v0.3.0 | 默认设备鉴权；一次性二维码配对；摘要化凭证存储；WebUI 设备面板；在线状态和即时吊销 |
+| v0.5.0 | Human-in-the-loop：转发 API Gateway question 请求、整批回答/取消、重连重放与多端状态收敛 |
 
 ---
 

package/README.md

@@ -1,6 +1,10 @@
+<p align="center">
+  <img src="docs/assets/whale-girl-ios-app-promo-16x9.png" alt="鲸鱼娘展示 DeepSeek Harness Mobile 与移动网关" width="100%">
+</p>
+
 # dsh-plugin-mobile-gateway
 
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供经过设备鉴权的持久化 WebSocket 网关，让 iOS 等移动客户端能够查看工作区和历史会话、接收 Agent 实时输出、发送任务，以及调整会话模型与权限。
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供经过设备鉴权的持久化 WebSocket 网关，让 iOS 等移动客户端能够查看工作区和历史会话、接收 Agent 实时输出、处理 Human-in-the-loop 选择、发送任务，以及调整会话模型与权限。
 
 ![DeepSeek Harness 移动设备管理面板](docs/assets/mobile-device-management.png)
 
@@ -24,7 +28,7 @@ dsh plugin --profile web add dsh-plugin-mobile-gateway
 如果希望固定版本，可以在包名后指定版本号：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@0.4.1
+dsh plugin --profile web add dsh-plugin-mobile-gateway@0.5.0
 ```
 
 也可以不经过 npm，直接安装 GitHub 版本：
@@ -45,7 +49,19 @@ dsh --profile web --dump-config | grep -A3 mobile-gateway
 
 启动 WebUI 后，左侧边栏底部应出现“移动设备”入口。
 
-### 3. 一条命令配置公网 IP（推荐，无需域名）
+### 3. 局域网直接连接（无需域名、证书或反向代理）
+
+插件安装并重启 `dsh web` 后，会额外创建一个仅用于移动端的局域网监听：
+
+```text
+ws://<运行 DSH 的电脑局域网 IP>:3081/ws/mobile
+```
+
+打开 WebUI 的“移动设备”面板时，插件会自动检测电脑的私有 IPv4，并优先把可用地址填入“WebSocket 地址”。开启移动网关、生成二维码并用 iOS 客户端扫码即可。电脑和手机需要位于可互访的同一局域网；如果系统防火墙询问是否允许 Node 接收入站连接，请允许私有网络访问 TCP `3081`。
+
+该端口只接受来自本机或私有网络地址的 `/ws/mobile` WebSocket Upgrade，不提供 WebUI，也不暴露 `/mgw/*` 管理接口。局域网监听始终要求设备配对鉴权，WebUI 中的 Debug 鉴权开关不会关闭它的鉴权。
+
+### 4. 一条命令配置公网 IP（推荐，无需域名）
 
 如果 Harness 部署在带固定公网 IPv4 的腾讯云 Ubuntu/Debian 服务器上，先在腾讯云安全组中放行入站 TCP `80` 和 `443`，然后在服务器执行：
 
@@ -90,7 +106,7 @@ sudo npx --yes dsh-plugin-mobile-gateway remove
 
 1. 开启“允许移动设备连接”。
 2. 保持“设备鉴权”开启。
-3. 在“公网 WebSocket 地址”中填写手机可以访问的地址。
+3. 在“WebSocket 地址”中填写手机可以访问的地址。
 
 本机浏览器调试可以使用：
 
@@ -98,15 +114,15 @@ sudo npx --yes dsh-plugin-mobile-gateway remove
 ws://127.0.0.1:3080/ws/mobile
 ```
 
-真机不能使用 `127.0.0.1`，因为它在手机上指向手机自身。局域网或公网真机连接应通过 TLS 反向代理提供：
+真机不能使用 `127.0.0.1`，因为它在手机上指向手机自身。同一私有局域网可使用插件自动提供的 `ws://局域网IP:3081/ws/mobile`；公网连接则应通过 TLS 反向代理提供：
 
 ```text
 wss://gateway.example.com/ws/mobile
 ```
 
-非 localhost 的配对地址会强制要求 `wss://`，以免一次性配对信息和长期连接暴露在明文网络中。
+只有 localhost、`.local` 主机名及 RFC 1918/链路本地私有地址允许使用 `ws://`。其他地址会强制要求 `wss://`，以免一次性配对信息和长期连接暴露在公网明文网络中。
 
-### 4. 配对 iOS 客户端
+### 5. 配对 iOS 客户端
 
 1. 在 WebUI 中填写设备名称，例如 `iPhone`。
 2. 点击“生成配对二维码”。
@@ -196,6 +212,10 @@ TLS 证书、域名、防火墙、访问日志保护和代理层速率限制由
     gatewayWaitTimeoutMs: 300000
     requireAuth: true
     adminLoopbackOnly: true
+    lanEnabled: true
+    lanHost: 0.0.0.0
+    lanPort: 3081
+    lanAdvertiseHost: ''
     publicUrl: wss://gateway.example.com/ws/mobile
     publicUrlFile: /etc/dsh-mobile-gateway/public-url
     pairingTtlMs: 300000
@@ -211,7 +231,8 @@ TLS 证书、域名、防火墙、访问日志保护和代理层速率限制由
 | WebUI 没有“移动设备”入口 | 确认使用 `--profile web` 安装；执行 `--dump-config` 检查组合树，然后完整重启 `dsh web` |
 | iOS 连接提示 `503` | 移动网关尚未开启，回到 WebUI 开启“允许移动设备连接” |
 | iOS 连接提示 `401` | 配对码过期、长期凭证无效或设备已被吊销；删除客户端旧凭证后重新配对 |
-| 真机无法连接 `127.0.0.1` | `127.0.0.1` 在手机上不是电脑；配置手机可访问的 `wss://` 地址 |
+| 真机无法连接 `127.0.0.1` | `127.0.0.1` 在手机上不是电脑；局域网使用面板自动显示的 `ws://私有IP:3081/ws/mobile`，公网使用 `wss://` 地址 |
+| 同一 Wi-Fi 仍无法连接局域网地址 | 确认手机与电脑所在网络允许设备互访，并放行电脑入站 TCP 3081；访客 Wi-Fi 通常会启用客户端隔离 |
 | 一键配置无法识别公网 IP | 确认命令运行在腾讯云 CVM 内，或通过 `--ip <公网 IPv4>` 显式指定 |
 | Certbot 申请或续期失败 | 确认腾讯云安全组和服务器防火墙都允许入站 TCP 80/443，并确认公网 IP 没有变化 |
 | 想检查自动续期 | 执行 `sudo systemctl status dsh-mobile-gateway-cert-renew.timer` 和 `sudo npx --yes dsh-plugin-mobile-gateway status` |
@@ -247,6 +268,9 @@ NODE_PATH=/path/to/dsh/node_modules node test/gateway.test.mjs
 
 # 公网 IP 安装器的参数、Nginx 隔离与续期配置
 node test/setup-ip.test.mjs
+
+# 独立局域网监听、强制鉴权与管理接口隔离
+node test/lan.test.mjs
 ```
 
 版本历史与全部 WebSocket 消息类型见 [`PROTOCOL.md`](PROTOCOL.md)。

package/cordis.patch.yml

@@ -13,6 +13,12 @@
         requireAuth: true
         adminLoopbackOnly: true
         pairingTtlMs: 300000
+        # DSH WebUI remains loopback-only on 3080. The plugin owns this
+        # authenticated, WebSocket-only LAN listener for phones on the same
+        # private network.
+        lanEnabled: true
+        lanHost: 0.0.0.0
+        lanPort: 3081
         # Written automatically by `sudo npx dsh-plugin-mobile-gateway setup`.
         publicUrlFile: /etc/dsh-mobile-gateway/public-url