dsh-plugin-mobile-gateway 0.5.0 → 0.6.1

package/PROTOCOL.md

@@ -1,11 +1,11 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送消息、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.5.0）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.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）
+- **帧格式**：全部为 JSON 文本帧（UTF-8）；图片字节使用标准 Base64
 - **连接即推送**：连上后服务端立刻发送一条 `hello`，之后 agent 输出以 `event` 帧实时推送
 
 ---
@@ -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": 2, "authenticated": true,
+{ "kind": "hello", "protocol": 3, "capabilities": ["images"], "authenticated": true,
   "device": { "id": "...", "name": "iPhone" }, "port": 3080, "clients": 1 }
 ```
 
@@ -265,6 +265,48 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 - `sessionId`：可选。省略时**自动创建新会话**（可用 `workspaceId` 或 `cwd` 指定归属工作区，至多一个，workspaceId 优先）
 - `mode`：`"queue"`（排队，默认）/ `"steer"`（打断当前回合）
 - `text` 以 `/` 开头会被当作**斜杠命令**（如 `/permission ask`），宿主直接执行、**绝不发给模型**
+- `text` 与 `images` 至少提供一项；因此支持纯图片消息
+- `clientTimeZone`：可选 IANA 时区，例如 `Asia/Shanghai`，宿主会校验后记录到这条用户消息
+
+### 发送图片
+
+iOS 将本地图片原始文件数据编码成**标准 Base64**，不要包含 `data:image/...;base64,` 前缀：
+
+```json
+{
+  "type": "message",
+  "sessionId": "session-abc",
+  "text": "请描述这两张图片",
+  "clientTimeZone": "Asia/Shanghai",
+  "images": [
+    {
+      "mediaType": "image/jpeg",
+      "data": "/9j/4AAQSkZJRgABAQ...",
+      "name": "IMG_1024.JPG"
+    },
+    {
+      "mediaType": "image/png",
+      "data": "iVBORw0KGgoAAA...",
+      "name": "diagram.png"
+    }
+  ]
+}
+```
+
+支持的 `mediaType`：`image/png`、`image/jpeg`、`image/webp`、`image/gif`。宿主会验证 Base64、文件签名、格式、尺寸、像素数、单图大小、图片数量和总大小；声明 MIME 与真实字节不一致会拒绝整条消息，且不会产生部分附件。
+
+当前 DSH 默认最多 20 张图片、单图约 3.5 MiB、单条消息图片总计 100 MiB，实际值以最近一次 `history.projections.values.imageLimits` 为准。WebSocket 单帧上限默认 144 MiB，用于容纳 100 MiB 图片经 Base64 后的 JSON 请求；反向代理也必须允许相应大小的 WebSocket 帧。
+
+Swift 编码示例：
+
+```swift
+let data = try Data(contentsOf: imageURL)
+let image = [
+    "mediaType": "image/jpeg",
+    "data": data.base64EncodedString(),
+    "name": imageURL.lastPathComponent
+]
+```
 
 ```json
 → { "kind": "sent", "sessionId": "session-abc", "mode": "queue" }
@@ -279,6 +321,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 |---|---|---|
 | `sessions` | — | 会话列表（`updatedAt/running/blank/cwd/agentPreset`） |
 | `history` | `sessionId`, `beforeSeq?`, `maxMessages?`, `maxBytes?`, `view?` | 历史事件页（见下） |
+| `attachment` | `sessionId`, `attachmentId` | 读取历史中属于该会话的图片字节 |
 | `search` | `query` | 会话全文搜索 |
 | `session-stats` | `sessionId` | 执行统计投影（输入框统计条数据源） |
 | `context-usage` | `sessionId` | token 用量 + 上下文占用投影 |
@@ -288,6 +331,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 { "type": "history", "sessionId": "session-abc", "maxMessages": 60, "maxBytes": 4194304, "view": "conversation" }
 ```
 - 返回**原始 SessionEvent**（`{type, seq, time, data}`，方案A），可选裁剪
+- 图片不会内联进历史页。`user/message.data.content[]` 中的图片块为 `{ "type":"image", "attachment": ImageAttachmentRef }`；iOS 使用其中的 `attachmentId` 请求图片数据
 - `maxBytes`：单帧字节预算，默认 **4 MiB**；超预算保留最新部分并给出 `nextBeforeSeq` 续页（客户端 16 MiB 上限的安全余量）
 - `view: "conversation"`：**对话裁剪模式**——丢弃 `assistant/chunk`（token 回放）与 `request/header`（system prompt），`tool/result` 嵌套文本截断到 2000 字符
 - 分页：`hasMore` 为真时用 `beforeSeq: nextBeforeSeq` 请求更早一页
@@ -298,6 +342,48 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
     "projections": { "asOfSeq": 127, "values": { "tokenUsage": {...}, "contextPressure": {...}, "permissions": {...}, "sessionStats": {...} } } }
 ```
 
+图片引用结构：
+
+```json
+{
+  "type": "image",
+  "attachment": {
+    "attachmentId": "sha256-opaque-id",
+    "mediaType": "image/jpeg",
+    "bytes": 184320,
+    "width": 1200,
+    "height": 900,
+    "name": "IMG_1024.JPG"
+  }
+}
+```
+
+iOS 发现尚未缓存的 `attachmentId` 后发送：
+
+```json
+{ "type":"attachment", "sessionId":"session-abc", "attachmentId":"sha256-opaque-id" }
+```
+
+服务端在确认该会话历史确实引用了这张图片后返回：
+
+```json
+{
+  "kind": "attachment",
+  "sessionId": "session-abc",
+  "attachment": {
+    "attachmentId": "sha256-opaque-id",
+    "mediaType": "image/jpeg",
+    "bytes": 184320,
+    "width": 1200,
+    "height": 900,
+    "name": "IMG_1024.JPG"
+  },
+  "data": "/9j/4AAQSkZJRgABAQ..."
+}
+```
+
+iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建议以 `attachmentId` 为缓存键。不要把 Base64 长期保存在对话模型对象里。并发同步历史时可限制为 2～4 个附件请求，优先加载当前可见消息。
+
 ### `session-stats` 详细（输入框统计条）
 ```json
 { "type": "session-stats", "sessionId": "session-abc" }
@@ -423,7 +509,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 | kind | 触发时机 |
 |---|---|
 | `paired` | 首次配对成功；仅此一次返回长期设备 token |
-| `hello` | 连接成功：`{ "kind":"hello", "protocol":2, "authenticated":true, "port":3080, "clients":1 }` |
+| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images"], "authenticated":true, "port":3080, "clients":1 }` |
 | `event` | 任意会话的 agent 输出（见下） |
 | `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
 | `pong` / `subscribed` / `sent` | 对应请求的回复 |
@@ -434,7 +520,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "event": { "type": "assistant/chunk", "turn": 1, "step": 0, "chunkType": "text-delta", "text": "正在" } }
 ```
 `event.type` 覆盖（精炼字段）：
-- `user/message` → `{text, source}`
+- `user/message` → `{text, source, images?: ImageAttachmentRef[]}`
 - `assistant/chunk` → `{turn, step, chunkType: text-delta|reasoning-delta|tool-call-delta|usage|finish, text?/tool?/usage?/finish?}`
 - `assistant/message` → `{turn, step, text, reasoning, toolCalls[]}`
 - `tool/call` → `{turn, step, callId, name, arguments}`
@@ -487,6 +573,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 | v0.1.17 | models 支持无 sessionId 全局目录；新增 providers |
 | v0.3.0 | 默认设备鉴权；一次性二维码配对；摘要化凭证存储；WebUI 设备面板；在线状态和即时吊销 |
 | v0.5.0 | Human-in-the-loop：转发 API Gateway question 请求、整批回答/取消、重连重放与多端状态收敛 |
+| v0.6.0 | DSH 0.1.1 图片：WebSocket Base64 上传、实时图片引用、历史附件按会话安全读取 |
 
 ---
 

package/README.md

@@ -1,276 +1,163 @@
 <p align="center">
-  <img src="docs/assets/whale-girl-ios-app-promo-16x9.png" alt="鲸鱼娘展示 DeepSeek Harness Mobile 与移动网关" width="100%">
+  <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 实时输出、处理 Human-in-the-loop 选择、发送任务，以及调整会话模型与权限。
+让 iPhone 通过经过设备鉴权的 WebSocket 连接 DeepSeek Harness。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
 
-![DeepSeek Harness 移动设备管理面板](docs/assets/mobile-device-management.png)
+- WebSocket：`/ws/mobile`
+- 局域网：`ws://<局域网 IP>:3081/ws/mobile`
+- 公网：`wss://<公网 IP>/ws/mobile`
+- 协议文档：[PROTOCOL.md](PROTOCOL.md)
 
-- WebSocket 端点：`/ws/mobile`
-- 管理入口：Harness WebUI 左侧边栏底部的“移动设备”
-- 默认安全策略：网关默认关闭、设备鉴权默认开启、管理接口仅允许本机访问
-- 完整通信格式：[`PROTOCOL.md`](PROTOCOL.md)
+## 配套 iOS 客户端
 
-## 直接安装（推荐，无需下载源码）
+[DeepSeek Harness Mobile](https://github.com/Clarklevis1995/dsh-mobile) 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop、模型与权限设置。
 
-### 1. 安装插件
+<table>
+  <tr>
+    <td width="33.33%" align="center"><img src="https://raw.githubusercontent.com/Clarklevis1995/dsh-mobile/main/Docs/images/screenshots/home.png" alt="iOS 工作区首页" width="100%"></td>
+    <td width="33.33%" align="center"><img src="https://raw.githubusercontent.com/Clarklevis1995/dsh-mobile/main/Docs/images/screenshots/conversation-dark.png" alt="iOS 深色对话界面" width="100%"></td>
+    <td width="33.33%" align="center"><img src="https://raw.githubusercontent.com/Clarklevis1995/dsh-mobile/main/Docs/images/screenshots/pairing-dark.png" alt="iOS 设备配对界面" width="100%"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>工作区首页</strong></td>
+    <td align="center"><strong>实时对话</strong></td>
+    <td align="center"><strong>设备配对</strong></td>
+  </tr>
+</table>
 
-确保本机已经安装并能正常运行 DeepSeek Harness，然后执行：
+## 安装插件
 
-```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway
-```
-
-这条命令会直接从 npm 获取插件、安装依赖，并将插件加入 `web` profile 的 bundle 列表。用户不需要 clone 仓库，也不需要运行 `pnpm install`。
-
-如果希望固定版本，可以在包名后指定版本号：
+前提：已经安装 `dsh` CLI，并能正常启动 `dsh web`。
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@0.5.0
+dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
-也可以不经过 npm，直接安装 GitHub 版本：
+安装后停止并重新启动 WebUI：
 
 ```bash
-dsh plugin --profile web add github:Clarklevis1995/dsh-plugin-mobile-gateway
+dsh web
 ```
 
-### 2. 重启 Harness WebUI
+打开 WebUI，确认左侧边栏底部出现“移动设备”。
 
-插件组合树只在 WebUI 启动时加载。安装完成后，停止当前的 `dsh web` 进程并重新启动它。刷新浏览器本身不足以加载新安装的服务端插件。
+## 局域网配对
 
-可以在启动前检查插件是否进入组合配置：
-
-```bash
-dsh --profile web --dump-config | grep -A3 mobile-gateway
-```
-
-启动 WebUI 后，左侧边栏底部应出现“移动设备”入口。
-
-### 3. 局域网直接连接（无需域名、证书或反向代理）
-
-插件安装并重启 `dsh web` 后，会额外创建一个仅用于移动端的局域网监听：
-
-```text
-ws://<运行 DSH 的电脑局域网 IP>:3081/ws/mobile
-```
+适用于 DSH 电脑和 iPhone 位于同一个可互访的局域网。
 
-打开 WebUI 的“移动设备”面板时，插件会自动检测电脑的私有 IPv4，并优先把可用地址填入“WebSocket 地址”。开启移动网关、生成二维码并用 iOS 客户端扫码即可。电脑和手机需要位于可互访的同一局域网；如果系统防火墙询问是否允许 Node 接收入站连接，请允许私有网络访问 TCP `3081`。
+1. 打开 WebUI 的“移动设备”。
+2. 开启“允许移动设备连接”。
+3. 保持“设备鉴权”开启。
+4. 确认面板显示 `ws://<电脑局域网 IP>:3081/ws/mobile`。
+5. 填写设备名称并点击“生成配对二维码”。
+6. 在 iOS 客户端打开“设备认证”，扫描二维码。
+7. WebUI 的可信设备显示“在线”后即完成。
 
-该端口只接受来自本机或私有网络地址的 `/ws/mobile` WebSocket Upgrade，不提供 WebUI，也不暴露 `/mgw/*` 管理接口。局域网监听始终要求设备配对鉴权，WebUI 中的 Debug 鉴权开关不会关闭它的鉴权。
+如果系统防火墙拦截连接，只允许私有网络访问 TCP `3081`。不要把 3081 开放到公网。
 
-### 4. 一条命令配置公网 IP（推荐，无需域名）
+## 公网 IP 配对
 
-如果 Harness 部署在带固定公网 IPv4 的腾讯云 Ubuntu/Debian 服务器上，先在腾讯云安全组中放行入站 TCP `80` 和 `443`，然后在服务器执行：
+适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器（其他发行版本可自行尝试）。Node.js 通过 nvm 安装时，也使用下面的命令。
 
-```bash
-sudo npx --yes dsh-plugin-mobile-gateway setup
-```
+### 1. 配置端口
 
-安装器会自动从腾讯云实例元数据读取公网 IPv4，并完成：
+从云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP `80` 和 `443`。
 
-- 安装 Nginx 和独立 Python 虚拟环境中的 Certbot
-- 为公网 IP 申请受系统信任的短期 TLS 证书
-- 只把 `wss://公网IP/ws/mobile` 代理到 `127.0.0.1:3080`
-- 对普通 HTTP、WebUI、`/mgw/*` 管理接口和其他路径返回 `404`
-- 创建每天两次运行的 systemd 证书续期任务
-- 把公网地址写入 `/etc/dsh-mobile-gateway/public-url`，插件启动时自动读取
+不要开放 TCP `3080` 和 `3081`！！！
+不要开放 TCP `3080` 和 `3081`！！！
+不要开放 TCP `3080` 和 `3081`！！！
 
-因此 DSH 仍然只需监听 `127.0.0.1:3080`，不需要把 3080 端口暴露到公网，也不需要 Tunnel、域名或手写 Nginx 配置。
+### 2. 配置公网入口
 
-邮箱是可选项；希望接收 Let's Encrypt 账户通知时可追加 `--email you@example.com`。如果无法从腾讯云元数据识别公网地址，或 DSH 使用了其他本地端口：
+把示例 IP 替换为云厂商控制台中的实际公网 IPv4：
 
 ```bash
-sudo npx --yes dsh-plugin-mobile-gateway setup \
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest setup \
   --ip 203.0.113.10 \
-  --port 3080 \
-  --email you@example.com
+  --port 3080
 ```
 
-执行完成后重启 `dsh web`，打开 WebUI 的“移动设备”面板。公网 WebSocket 地址会自动显示为 `wss://公网IP/ws/mobile`；开启移动网关并生成二维码即可。
-
-查看状态或移除安装器生成的公网入口：
+安装器完成后，重新启动：
 
 ```bash
-sudo npx --yes dsh-plugin-mobile-gateway status
-sudo npx --yes dsh-plugin-mobile-gateway remove
+dsh web
 ```
 
-`remove` 只删除本插件生成的 Nginx 配置、地址文件和续期任务，不卸载软件，也不删除已有证书。IP 证书有效期约 6 天，必须保持 80 端口可达以便自动续期。相关能力来自 [Let's Encrypt 的短期 IP 地址证书](https://letsencrypt.org/2026/03/11/shorter-certs-certbot/)；公网 IP 自动识别使用[腾讯云实例元数据](https://cloud.tencent.com/document/product/213/17940)。
-
-#### 已有域名或反向代理
+### 3. 打开远程 WebUI（使用端口转发，VSCode等IDE自带）
 
-打开“移动设备”面板：
+如果 WebUI 运行在远程服务器，在自己的电脑执行：
 
-1. 开启“允许移动设备连接”。
-2. 保持“设备鉴权”开启。
-3. 在“WebSocket 地址”中填写手机可以访问的地址。
-
-本机浏览器调试可以使用：
-
-```text
-ws://127.0.0.1:3080/ws/mobile
+```bash
+ssh -N -L 3080:127.0.0.1:3080 <服务器用户名>@<服务器公网 IP>
 ```
 
-真机不能使用 `127.0.0.1`，因为它在手机上指向手机自身。同一私有局域网可使用插件自动提供的 `ws://局域网IP:3081/ws/mobile`；公网连接则应通过 TLS 反向代理提供：
+然后在本地浏览器打开：
 
 ```text
-wss://gateway.example.com/ws/mobile
+http://127.0.0.1:3080
 ```
 
-只有 localhost、`.local` 主机名及 RFC 1918/链路本地私有地址允许使用 `ws://`。其他地址会强制要求 `wss://`，以免一次性配对信息和长期连接暴露在公网明文网络中。
-
-### 5. 配对 iOS 客户端
-
-1. 在 WebUI 中填写设备名称，例如 `iPhone`。
-2. 点击“生成配对二维码”。
-3. 在 iOS 客户端首页点击认证按钮：
-   - 选择“扫描二维码”，扫码后自动连接；或
-   - 选择“手动输入配对信息”，粘贴 WebUI 中复制的 Base64URL 配对 Token，再点击连接。
-4. iOS 首次连接成功后会把长期设备凭证保存到 Keychain。配对二维码只能使用一次，并会在 5 分钟后过期。
-5. WebUI 的可信设备列表显示“在线”，iOS 首页连接状态变为绿色，即表示连接完成。
-
-后续启动 iOS 客户端时会使用 Keychain 中的长期凭证重新连接，不需要再次扫码。重新配对同一套 iOS 安装也会复用其设备身份，不会重复创建可信设备。
-
-## 日常使用
-
-连接成功后，移动客户端可以：
+### 4. 使用 WebUI 配对
 
-- 浏览工作区、未分组会话和服务端目录
-- 创建工作区与新会话
-- 加载历史消息与轨迹
-- 实时接收思考、工具调用和最终回答
-- 向远端 Agent 发送任务
-- 查询或切换会话模型、推理等级和访问权限
-- 查看上下文用量与会话统计
+1. 打开“移动设备”。
+2. 开启“允许移动设备连接”。
+3. 保持“设备鉴权”开启。
+4. 确认 WebSocket 地址为 `wss://<公网 IP>/ws/mobile`。
+5. 填写设备名称并点击“生成配对二维码”。
+6. iPhone 打开“设备认证”，扫描二维码；也可以复制 Base64URL 配对字符串手动连接。
+7. WebUI 的可信设备显示“在线”后即完成。
 
-关闭“允许移动设备连接”会立即断开移动端，但不会影响普通 Harness WebUI。网关开启后，如果默认 5 分钟内没有可信设备成功连接，会自动关闭。
+二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。
 
-## 可信设备管理
+## 公网入口管理
 
-长期设备凭证只在首次配对成功时返回一次，移动端应保存在 Keychain。服务端仅保存凭证的 SHA-256 摘要：
+查看状态：
 
-```text
-~/.dsh/mobile-gateway-devices.json
+```bash
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest status
 ```
 
-在 WebUI 的“可信设备”列表中点击“吊销”会：
-
-- 从可信设备列表删除该设备
-- 立即关闭该设备现有的 WebSocket 连接
-- 使该设备保存的长期凭证永久失效
-
-被吊销的设备再次连接会收到 `401 Unauthorized`，需要重新配对。
-
-## 更新插件（无需源码）
-
-插件会被安装到 profile 中，不会自动更新。升级时重新安装最新 npm 版本并重启 WebUI：
+移除公网入口：
 
 ```bash
-dsh plugin --profile web remove dsh-plugin-mobile-gateway
-dsh plugin --profile web add dsh-plugin-mobile-gateway
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove
 ```
 
-然后停止并重新启动 `dsh web`。
+## 更新插件
 
-## 卸载
+重新安装 npm 最新版本：
 
 ```bash
-dsh plugin --profile web remove dsh-plugin-mobile-gateway
+dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
-如果旧版 DSH 没有自动清理 bundle，再从 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 中删除 `dsh-plugin-mobile-gateway`，随后重启 WebUI。
-
-卸载插件不会自动删除 `~/.dsh/mobile-gateway-devices.json`。
-
-## 手动公网部署
+随后停止并重新启动 `dsh web`。
 
-不使用一键安装器时，公网入口应由 Nginx、Caddy 或其他反向代理提供 HTTPS/WSS，并且只公开 WebSocket 路由，不要公开 `/mgw` 管理接口或整个未鉴权 WebUI。
-
-Nginx 核心配置示例：
-
-```nginx
-location = /ws/mobile {
-    proxy_pass http://127.0.0.1:3080;
-    proxy_http_version 1.1;
-    proxy_set_header Upgrade $http_upgrade;
-    proxy_set_header Connection "upgrade";
-}
-```
+## 卸载插件
 
-TLS 证书、域名、防火墙、访问日志保护和代理层速率限制由部署环境负责。
-
-如需把公网地址写入 profile，可在 `cordis.patch.yml` 的 `mobile-gateway` 配置段覆盖：
-
-```yaml
-- id: mobile-gateway
-  config:
-    path: /ws/mobile
-    gatewayEnabled: false
-    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
-    allowQueryToken: false
+```bash
+dsh plugin --profile web remove dsh-plugin-mobile-gateway
 ```
 
-后置 patch 会替换整个配置段，因此覆盖时应保留所有需要的字段。
-
 ## 常见问题
 
-| 现象 | 原因与处理方式 |
+| 现象 | 处理方式 |
 |---|---|
-| WebUI 没有“移动设备”入口 | 确认使用 `--profile web` 安装；执行 `--dump-config` 检查组合树，然后完整重启 `dsh web` |
-| iOS 连接提示 `503` | 移动网关尚未开启，回到 WebUI 开启“允许移动设备连接” |
-| iOS 连接提示 `401` | 配对码过期、长期凭证无效或设备已被吊销；删除客户端旧凭证后重新配对 |
-| 真机无法连接 `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` |
-| 二维码无法再次使用 | 配对码设计为一次性且 5 分钟过期，重新生成即可 |
-| 修改配置后没有生效 | 插件与 profile composition 在启动时加载，需要重启 WebUI 进程 |
-| 需要排查服务端原因 | 查看 `/tmp/mobile-gateway.log`，其中包含连接、鉴权、查询与错误记录 |
-
-## 安全说明
-
-- 不建议关闭设备鉴权。该开关仅用于本机 Debug，重启后会恢复安全默认值。
-- `/mgw/*` 默认只接受 loopback 请求，不应通过公网反向代理暴露。
-- 长期 token 默认禁止通过 URL query 传输，避免进入代理日志、浏览器历史或监控系统。
-- 配对二维码和长期 token 不会明文写入服务端磁盘。
+| WebUI 没有“移动设备” | 确认安装在 `web` profile，并完整重启 `dsh web` |
+| iOS 收到 `503` | 回到 WebUI 开启“允许移动设备连接” |
+| iOS 收到 `401` | 在 WebUI 重新生成二维码并配对 |
+| 公网连接超时 | 检查云安全组、服务器防火墙和 TCP `80/443` |
+| 公网地址没有自动显示 | 确认已执行 `setup --ip <公网 IP>`，然后重启 `dsh web` |
+| 需要查看服务端日志 | 执行 `tail -f /tmp/mobile-gateway.log` |
 
 ## 源码开发
 
-只有需要修改插件本身时才需要源码安装：
-
 ```bash
 dsh plugin --profile web add file:/absolute/path/to/dsh-plugin-mobile-gateway
+npm test
 ```
 
-`file:` 是复制安装。修改源码后必须先 remove、再 add，并重启 WebUI；不要使用 `link:`，否则依赖可能从源码目录解析而导致 `ws` 等包无法找到。
-
-测试命令：
-
-```bash
-# 鉴权、配对与吊销
-NODE_PATH=/path/to/dsh/node_modules node test/auth.test.mjs
-
-# mock Harness + 真实 WebSocket 客户端的完整协议链路
-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)。
+源码修改后需要重新安装插件并重启 `dsh web`。

package/lib/index.mjs

@@ -18,8 +18,9 @@
 //   client -> server: { "type": "ping" }
 //                     { "type": "subscribe", "sessionId": "..." }  (optional filter)
 //                     { "type": "unsubscribe" }
-//                     { "type": "message", "sessionId"?, "text", "mode"?: "queue"|"steer",
-//                       "workspaceId"?, "cwd"? }
+//                     { "type": "message", "sessionId"?, "text"?, "images"?:
+//                       [{ "mediaType", "data", "name"? }], "mode"?: "queue"|"steer",
+//                       "workspaceId"?, "cwd"?, "clientTimeZone"? }
 //                        sessionId omitted -> a new session is created first; the
 //                        new session can be placed in a workspace via workspaceId
 //                        (or cwd; at most one, workspaceId wins)
@@ -30,6 +31,8 @@
 //                        -> raw SessionEvent page (scheme A), capped at maxBytes
 //                           (default 4 MiB); hasMore + nextBeforeSeq page backward;
 //                           view:"conversation" trims chunk/header events and tool output
+//                     { "type": "attachment", "sessionId", "attachmentId" }
+//                        -> verified image metadata + canonical base64 bytes
 //                     { "type": "search", "query" }                -> session search
 //                     { "type": "host" }                           -> host.describe snapshot (incl. default provider/model)
 //                     { "type": "default-model" }                   -> agentDefaultModel.currentSelection()
@@ -50,11 +53,13 @@
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
 //                     { "type": "question-answer", "rpcId", "sessionId", "answers": [...] }
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
-//   server -> client: { "kind": "hello", "protocol": 2, "authenticated", "device"?, "port", "clients" }
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images"],
+//                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
 //                     { "kind": "sent", "sessionId", "mode", "command"? }
 //                     { "kind": "workspaces" | "sessions" | "history" | "search", ...data }
+//                     { "kind": "attachment", "sessionId", "attachment", "data" }
 //                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
 //                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
@@ -85,7 +90,12 @@ const LOG_FILE = '/tmp/mobile-gateway.log'
 const DEFAULT_WS_PATH = '/ws/mobile'
 const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000
 const DEFAULT_GATEWAY_WAIT_TIMEOUT_MS = 5 * 60 * 1000
+// DSH 0.1.1 allows up to 100 MiB of decoded images in one prompt. Base64 plus
+// the JSON envelope needs roughly 4/3 of that on the wire. Keep this separately
+// configurable so deployments may choose a lower transport ceiling.
+const DEFAULT_MAX_WS_PAYLOAD_BYTES = 144 * 1024 * 1024
 const MAX_MANAGEMENT_BODY_BYTES = 16 * 1024
+const IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
 
 // Cordis validates this schema at plugin load and fills these defaults. Keep
 // the defaults conservative: installing the bundle must never create an
@@ -95,6 +105,7 @@ const Config = Schema.object({
   requireAuth: Schema.boolean().default(true),
   gatewayEnabled: Schema.boolean().default(false),
   gatewayWaitTimeoutMs: Schema.natural().min(30_000).max(30 * 60 * 1000).default(DEFAULT_GATEWAY_WAIT_TIMEOUT_MS),
+  maxPayloadBytes: Schema.natural().min(1024 * 1024).max(160 * 1024 * 1024).default(DEFAULT_MAX_WS_PAYLOAD_BYTES),
   adminLoopbackOnly: Schema.boolean().default(true),
   publicUrl: Schema.string().default(''),
   deviceFile: Schema.string().default(''),
@@ -126,20 +137,40 @@ function textOf(blocks) {
   return text
 }
 
+function imagesOf(blocks) {
+  const images = []
+  for (const block of blocks) {
+    if (!block || block.type !== 'image' || !block.attachment) continue
+    const attachment = block.attachment
+    images.push({
+      attachmentId: attachment.attachmentId,
+      mediaType: attachment.mediaType,
+      bytes: attachment.bytes,
+      width: attachment.width,
+      height: attachment.height,
+      ...(attachment.name ? { name: attachment.name } : {}),
+    })
+  }
+  return images
+}
+
 // Build the small, owned JSON wire record for one session event. Reads only
 // leaf fields of the live SessionEvent — never serializes live objects.
 function buildWireEvent(session, event) {
-  const base = { sessionId: String(session.id), seq: event.seq, time: event.time }
+  const base = { kind: 'event', sessionId: String(session.id), seq: event.seq, time: event.time }
   const d = event.data || {}
   switch (event.type) {
-    case 'user/message':
+    case 'user/message': {
+      const images = imagesOf(d.content || [])
       return Object.assign(base, {
         event: {
           type: 'user/message',
           text: textOf(d.content || []),
           source: d.source && d.source.kind,
+          ...(images.length ? { images } : {}),
         },
       })
+    }
     case 'assistant/chunk': {
       const chunk = d.chunk || {}
       const ev = { type: 'assistant/chunk', turn: d.turn, step: d.step, chunkType: chunk.type }
@@ -154,6 +185,7 @@ function buildWireEvent(session, event) {
       let text = ''
       let reasoning = ''
       const toolCalls = []
+      const images = imagesOf(blocks)
       for (const block of blocks) {
         if (!block) continue
         if (block.type === 'text' && typeof block.text === 'string') text += block.text
@@ -161,7 +193,7 @@ function buildWireEvent(session, event) {
         else if (block.type === 'tool-call') toolCalls.push({ id: block.id, name: block.name, arguments: block.arguments })
       }
       return Object.assign(base, {
-        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls },
+        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls, ...(images.length ? { images } : {}) },
       })
     }
     case 'tool/call':
@@ -203,8 +235,37 @@ function buildWireEvent(session, event) {
 // the wire frame to send back, or null when nothing should be sent.
 async function admitMessage(api, msg) {
   const text = typeof msg.text === 'string' ? msg.text.trim() : ''
-  if (!text) {
-    return { kind: 'error', code: 'bad-request', message: 'text must be a non-empty string' }
+  const images = msg.images === undefined ? [] : msg.images
+  if (!Array.isArray(images)) {
+    return { kind: 'error', code: 'bad-request', message: 'images must be an array' }
+  }
+  if (images.length > 20) {
+    return { kind: 'error', code: 'bad-request', message: 'a message can contain at most 20 images' }
+  }
+  const imageParts = []
+  for (let index = 0; index < images.length; index++) {
+    const image = images[index]
+    if (!image || typeof image !== 'object') {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}] must be an object` }
+    }
+    if (!IMAGE_MEDIA_TYPES.has(image.mediaType)) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].mediaType is unsupported` }
+    }
+    if (typeof image.data !== 'string' || image.data.length === 0) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].data must be a non-empty base64 string` }
+    }
+    if (image.name !== undefined && (typeof image.name !== 'string' || image.name.length > 255)) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].name must be a string of at most 255 characters` }
+    }
+    imageParts.push({
+      type: 'image',
+      mediaType: image.mediaType,
+      data: image.data,
+      ...(image.name ? { name: image.name } : {}),
+    })
+  }
+  if (!text && imageParts.length === 0) {
+    return { kind: 'error', code: 'bad-request', message: 'message requires non-empty text or at least one image' }
   }
   const mode = msg.mode === 'steer' ? 'steer' : 'queue'
 
@@ -231,10 +292,16 @@ async function admitMessage(api, msg) {
 
     const resp = await api.sessions.prompt({
       rpcId: crypto.randomUUID(),
-      payload: { sessionId, mode, content: [{ type: 'text', text }] },
+      payload: {
+        sessionId,
+        mode,
+        // Match the official WebUI ordering: images first, optional text last.
+        content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
+        ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
+      },
     })
     if (resp.result.ok) {
-      log(`mobile message accepted: session=${sessionId} mode=${mode} text="${text.slice(0, 60)}"`)
+      log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
       return {
         kind: 'sent',
         sessionId,
@@ -438,6 +505,20 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     }
     return frame
   }
+  if (msg.type === 'attachment') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const attachmentId = typeof msg.attachmentId === 'string' && msg.attachmentId.trim() !== '' ? msg.attachmentId.trim() : null
+    if (!attachmentId) {
+      return { kind: 'error', code: 'bad-request', message: 'attachment requires an attachmentId', requestType: 'attachment', sessionId: sessionId.value }
+    }
+    const frame = await proxyQuery(api, 'attachment', api.sessions.attachment.bind(api.sessions), {
+      sessionId: sessionId.value,
+      attachmentId,
+    })
+    if (frame.kind === 'attachment') frame.sessionId = sessionId.value
+    return frame
+  }
   if (msg.type === 'search') {
     const query = typeof msg.query === 'string' ? msg.query.trim() : ''
     if (!query) {
@@ -827,6 +908,7 @@ const plugin = {
       requireAuth: true,
       gatewayEnabled: false,
       gatewayWaitTimeoutMs: DEFAULT_GATEWAY_WAIT_TIMEOUT_MS,
+      maxPayloadBytes: DEFAULT_MAX_WS_PAYLOAD_BYTES,
       adminLoopbackOnly: true,
       publicUrl: '',
       deviceFile: '',
@@ -855,7 +937,7 @@ const plugin = {
     const registry = createRegistry(deviceFile, { pairingTtlMs: options.pairingTtlMs })
     const wss = new WebSocketServer({
       noServer: true,
-      maxPayload: 1024 * 1024,
+      maxPayload: options.maxPayloadBytes,
       // Authentication data may ride in requested subprotocols, but a secret
       // must never be echoed as the negotiated protocol.
       handleProtocols(protocols) {
@@ -1186,7 +1268,7 @@ const plugin = {
               admitMessage(api, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
-            } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' ||
+            } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' || msg.type === 'attachment' ||
                        msg.type === 'search' || msg.type === 'host' || msg.type === 'directories' ||
                        msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'select-model' ||
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
@@ -1217,7 +1299,8 @@ const plugin = {
           }
           ws.send(JSON.stringify({
             kind: 'hello',
-            protocol: 2,
+            protocol: 3,
+            capabilities: ['images'],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.5.0",
-  "description": "Persistent WebSocket gateway for dsh: exposes /ws/mobile on the web server and forwards agent session output to connected mobile clients",
+  "version": "0.6.1",
+  "description": "update readme",
   "main": "lib/index.mjs",
   "files": [
     "bin",