dsh-plugin-mobile-gateway 0.6.0 → 0.6.3

package/PROTOCOL.md

@@ -1,6 +1,6 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.0）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.3）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -405,6 +405,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | `workspaces` | — | 全部工作区（含每个的 `sessionIds`） |
 | `workspace-create` | `path` | 对**已存在目录**创建工作区（已归属→`created:false` 幂等） |
 | `directories` | `path?` | 浏览 server 目录（缺省 = home）；`crumbs` 面包屑 + `entries`（含 `hidden` 标记） |
+| `directory-create` | `path`, `name` | 在父目录下创建一个子文件夹 |
 
 ```json
 { "type": "workspace-create", "path": "/Users/lichaofan/DeepseekHarnessProject" }
@@ -412,6 +413,19 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
     "created": true }
 ```
 
+### 创建文件夹
+
+`path` 是当前父目录的绝对路径，`name` 只传新文件夹名称，不传完整目标路径：
+
+```json
+{ "type": "directory-create", "path": "/Users/lichaofan/DeepseekHarnessProject", "name": "Sources" }
+→ { "kind": "directory-create", "path": "/Users/lichaofan/DeepseekHarnessProject/Sources" }
+```
+
+创建和目录浏览使用同一套宿主 Node 文件系统实现，不依赖 DSH 的 native Directory Picker，因此 macOS native 模式也可远程创建目录。父路径必须是绝对路径且必须指向真实存在的目录；名称去除首尾空白后不能为空、`.`、`..`，也不能包含 `/` 或 `\\`。
+
+创建成功后，iOS 应重新发送对应父目录的 `directories` 请求来刷新列表。请求格式、相对父路径或非法名称返回 `bad-request`；目标已存在返回 `directory-exists`；父目录不存在、不是目录或其他文件系统失败返回 `directory-create-failed`。此操作只创建文件夹，不会自动注册工作区；如果要把新目录作为工作区，再使用返回的 `path` 调用 `workspace-create`。
+
 ---
 
 ## 7. 模型与思考等级
@@ -547,6 +561,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 - `/ws/mobile` 的移动网关默认关闭；本机 WebUI 手动开启后，若 5 分钟内没有设备成功连接会自动关闭
 - 网关开启后仍要求已配对设备凭证；不要把 `requireAuth` 设为 `false` 后暴露到网络
 - `/mgw/*` 是配对/吊销管理面，默认只允许本机访问；公网代理只应转发 `/ws/mobile`
+- `/mgw/public-setup` 仅供本机 WebUI 调用，通过受限 Unix Socket 请求 root Helper；Helper 只接受状态查询以及“公网 IPv4 + 当前 DSH 端口”的固定 Nginx 配置操作，不接受命令或文件路径
 - DSH HTTP Server 本身没有 TLS、认证或 Origin policy；公网必须使用 TLS 反向代理和 `wss://`
 - 长期 token 只保存在 iOS Keychain；服务端磁盘仅保存摘要
 - `set-default` / `save-default-model` 是全局写操作，客户端 UI 应加确认
@@ -574,6 +589,8 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | v0.3.0 | 默认设备鉴权；一次性二维码配对；摘要化凭证存储；WebUI 设备面板；在线状态和即时吊销 |
 | v0.5.0 | Human-in-the-loop：转发 API Gateway question 请求、整批回答/取消、重连重放与多端状态收敛 |
 | v0.6.0 | DSH 0.1.1 图片：WebSocket Base64 上传、实时图片引用、历史附件按会话安全读取 |
+| v0.6.3 | macOS native picker 兼容：目录创建改用与目录浏览一致的宿主文件系统实现，并补齐路径、名称和错误码校验 |
+| v0.6.2 | 目录创建：通过 API Gateway `host.createDirectory` 在工作区目录下创建子文件夹 |
 
 ---
 

package/README.md

@@ -1,279 +1,174 @@
 <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、模型与权限设置。
 
-如果使用 nvm 安装 Node.js，并希望不打开 WebUI、直接从服务器终端生成 iOS 配对字符串，请参照[公网 IP 命令行配对指南](docs/public-ip-deployment-guide.md)。
+<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>
 
-### 1. 安装插件
+## 安装插件
 
-确保本机已经安装并能正常运行 DeepSeek Harness，然后执行：
+前提：已经安装 `dsh` CLI，并能正常启动 `dsh web`。
+
+局域网使用只需安装插件：
 
 ```bash
 dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
-这条命令会在执行时从 npm 获取 `latest` 标签指向的最新插件、安装依赖，并将插件加入 `web` profile 的 bundle 列表。用户不需要 clone 仓库，也不需要运行 `pnpm install`。已经安装的插件不会后台自动升级；重新安装最新版本后需要重启 WebUI。
-
-如果希望固定版本，可以在包名后指定版本号：
+需要公网接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@0.6.0
+npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
-也可以不经过 npm，直接安装 GitHub 版本：
+安装后停止并重新启动 WebUI：
 
 ```bash
-dsh plugin --profile web add github:Clarklevis1995/dsh-plugin-mobile-gateway
+dsh web
 ```
 
-### 2. 重启 Harness WebUI
+打开 WebUI，确认左侧边栏底部出现“移动设备”。
 
-插件组合树只在 WebUI 启动时加载。安装完成后，停止当前的 `dsh web` 进程并重新启动它。刷新浏览器本身不足以加载新安装的服务端插件。
+## 局域网配对
 
-可以在启动前检查插件是否进入组合配置：
+适用于 DSH 电脑和 iPhone 位于同一个可互访的局域网。
 
-```bash
-dsh --profile web --dump-config | grep -A3 mobile-gateway
-```
+1. 打开 WebUI 的“移动设备”。
+2. 开启“允许移动设备连接”。
+3. 保持“设备鉴权”开启。
+4. 确认面板显示 `ws://<电脑局域网 IP>:3081/ws/mobile`。
+5. 填写设备名称并点击“生成配对二维码”。
+6. 在 iOS 客户端打开“设备认证”，扫描二维码。
+7. WebUI 的可信设备显示“在线”后即完成。
 
-启动 WebUI 后，左侧边栏底部应出现“移动设备”入口。
+如果系统防火墙拦截连接，只允许私有网络访问 TCP `3081`。不要把 3081 开放到公网。
 
-### 3. 局域网直接连接（无需域名、证书或反向代理）
+## 公网 IP 配对
 
-插件安装并重启 `dsh web` 后，会额外创建一个仅用于移动端的局域网监听：
+适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器（其他发行版本可自行尝试）。Node.js 通过 nvm 安装时，也使用下面的命令。
 
-```text
-ws://<运行 DSH 的电脑局域网 IP>:3081/ws/mobile
-```
+### 1. 配置端口
 
-打开 WebUI 的“移动设备”面板时，插件会自动检测电脑的私有 IPv4，并优先把可用地址填入“WebSocket 地址”。开启移动网关、生成二维码并用 iOS 客户端扫码即可。电脑和手机需要位于可互访的同一局域网；如果系统防火墙询问是否允许 Node 接收入站连接，请允许私有网络访问 TCP `3081`。
+从云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP `80` 和 `443`。
 
-该端口只接受来自本机或私有网络地址的 `/ws/mobile` WebSocket Upgrade，不提供 WebUI，也不暴露 `/mgw/*` 管理接口。局域网监听始终要求设备配对鉴权，WebUI 中的 Debug 鉴权开关不会关闭它的鉴权。
+不要开放 TCP `3080` 和 `3081`！！！
+不要开放 TCP `3080` 和 `3081`！！！
+不要开放 TCP `3080` 和 `3081`！！！
 
-### 4. 一条命令配置公网 IP（推荐，无需域名）
+### 2. 配置公网入口
 
-如果 Harness 部署在带固定公网 IPv4 的腾讯云 Ubuntu/Debian 服务器上，先在腾讯云安全组中放行入站 TCP `80` 和 `443`，然后在服务器执行：
+执行一次初始化（已经执行过可跳过）：
 
 ```bash
-sudo npx --yes dsh-plugin-mobile-gateway setup
+npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
-安装器会自动从腾讯云实例元数据读取公网 IPv4，并完成：
-
-- 安装 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`，插件启动时自动读取
-
-因此 DSH 仍然只需监听 `127.0.0.1:3080`，不需要把 3080 端口暴露到公网，也不需要 Tunnel、域名或手写 Nginx 配置。
-
-邮箱是可选项；希望接收 Let's Encrypt 账户通知时可追加 `--email you@example.com`。如果无法从腾讯云元数据识别公网地址，或 DSH 使用了其他本地端口：
+然后启动或重新启动：
 
 ```bash
-sudo npx --yes dsh-plugin-mobile-gateway setup \
-  --ip 203.0.113.10 \
-  --port 3080 \
-  --email you@example.com
+dsh web
 ```
 
-执行完成后重启 `dsh web`，打开 WebUI 的“移动设备”面板。公网 WebSocket 地址会自动显示为 `wss://公网IP/ws/mobile`；开启移动网关并生成二维码即可。
+### 3. 打开远程 WebUI（使用端口转发，VSCode等IDE自带）
 
-查看状态或移除安装器生成的公网入口：
+如果 WebUI 运行在远程服务器，在自己的电脑执行：
 
 ```bash
-sudo npx --yes dsh-plugin-mobile-gateway status
-sudo npx --yes dsh-plugin-mobile-gateway remove
+ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服务器公网 IP>
 ```
 
-`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)。
-
-#### 已有域名或反向代理
-
-打开“移动设备”面板：
-
-1. 开启“允许移动设备连接”。
-2. 保持“设备鉴权”开启。
-3. 在“WebSocket 地址”中填写手机可以访问的地址。
-
-本机浏览器调试可以使用：
-
-```text
-ws://127.0.0.1:3080/ws/mobile
-```
-
-真机不能使用 `127.0.0.1`，因为它在手机上指向手机自身。同一私有局域网可使用插件自动提供的 `ws://局域网IP:3081/ws/mobile`；公网连接则应通过 TLS 反向代理提供：
+然后在本地浏览器打开：
 
 ```text
-wss://gateway.example.com/ws/mobile
+http://127.0.0.1:<本地端口>
 ```
 
-只有 localhost、`.local` 主机名及 RFC 1918/链路本地私有地址允许使用 `ws://`。其他地址会强制要求 `wss://`，以免一次性配对信息和长期连接暴露在公网明文网络中。
-
-### 5. 配对 iOS 客户端
+### 4. 使用 WebUI 配对
 
-1. 在 WebUI 中填写设备名称，例如 `iPhone`。
-2. 点击“生成配对二维码”。
-3. 在 iOS 客户端首页点击认证按钮：
-   - 选择“扫描二维码”，扫码后自动连接；或
-   - 选择“手动输入配对信息”，粘贴 WebUI 中复制的 Base64URL 配对 Token，再点击连接。
-4. iOS 首次连接成功后会把长期设备凭证保存到 Keychain。配对二维码只能使用一次，并会在 5 分钟后过期。
-5. WebUI 的可信设备列表显示“在线”，iOS 首页连接状态变为绿色，即表示连接完成。
+1. 打开“移动设备”，在“公网接入”中填写云厂商控制台提供的公网 IPv4。
+2. 点击“配置公网接入”。Helper 会自动使用当前 `dsh web` 端口配置 Nginx 和证书。
+3. 开启“允许移动设备连接”，保持“设备鉴权”开启。
+4. 填写设备名称并点击“生成配对二维码”。
+5. iPhone 打开“设备认证”并扫描二维码。
+6. WebUI 的可信设备显示“在线”后即完成。
 
-后续启动 iOS 客户端时会使用 Keychain 中的长期凭证重新连接，不需要再次扫码。重新配对同一套 iOS 安装也会复用其设备身份，不会重复创建可信设备。
+二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。
 
-## 日常使用
+## 公网入口管理
 
-连接成功后，移动客户端可以：
+查看状态：
 
-- 浏览工作区、未分组会话和服务端目录
-- 创建工作区与新会话
-- 加载历史消息与轨迹
-- 从历史消息安全加载图片，并把 iOS 本地图片发送给 Agent
-- 实时接收思考、工具调用和最终回答
-- 向远端 Agent 发送任务
-- 查询或切换会话模型、推理等级和访问权限
-- 查看上下文用量与会话统计
-
-关闭“允许移动设备连接”会立即断开移动端，但不会影响普通 Harness WebUI。网关开启后，如果默认 5 分钟内没有可信设备成功连接，会自动关闭。
-
-## 可信设备管理
-
-长期设备凭证只在首次配对成功时返回一次，移动端应保存在 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`，需要重新配对。
+```bash
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove
+```
 
-## 更新插件（无需源码）
+## 更新插件
 
-插件会被安装到 profile 中，不会自动更新。升级时重新安装最新 npm 版本并重启 WebUI：
+重新运行初始化命令会同时更新插件和系统 Helper：
 
 ```bash
-dsh plugin --profile web remove dsh-plugin-mobile-gateway
-dsh plugin --profile web add dsh-plugin-mobile-gateway
+npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
-然后停止并重新启动 `dsh web`。
+随后停止并重新启动 `dsh web`。
 
-## 卸载
+## 卸载插件
 
 ```bash
 dsh plugin --profile web remove dsh-plugin-mobile-gateway
 ```
 
-如果旧版 DSH 没有自动清理 bundle，再从 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 中删除 `dsh-plugin-mobile-gateway`，随后重启 WebUI。
-
-卸载插件不会自动删除 `~/.dsh/mobile-gateway-devices.json`。
-
-## 手动公网部署
-
-不使用一键安装器时，公网入口应由 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";
-}
-```
+如需同时移除系统 Helper（不会删除现有 Nginx 公网配置）：
 
-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
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove-helper
 ```
 
-后置 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/bin/setup-ip.mjs

@@ -18,10 +18,17 @@ const CERTBOT_HOME = '/opt/dsh-mobile-gateway/certbot'
 const CERTBOT = path.join(CERTBOT_HOME, 'bin/certbot')
 const RENEW_SERVICE = '/etc/systemd/system/dsh-mobile-gateway-cert-renew.service'
 const RENEW_TIMER = '/etc/systemd/system/dsh-mobile-gateway-cert-renew.timer'
+const HELPER_SOURCE = fileURLToPath(new URL('../helper/dsh_mobile_gateway_helper.py', import.meta.url))
+const HELPER_INSTALL = '/usr/local/libexec/dsh-mobile-gateway-helper'
+const HELPER_SERVICE = '/etc/systemd/system/dsh-mobile-gateway-helper.service'
+const HELPER_SOCKET = '/run/dsh-mobile-gateway/helper.sock'
 
 function printHelp() {
   console.log(`Usage:
   dsh-plugin-mobile-gateway setup [--ip <public IPv4>] [--port 3080] [--email <address>] [--yes]
+  dsh-plugin-mobile-gateway init
+  dsh-plugin-mobile-gateway setup-helper
+  dsh-plugin-mobile-gateway remove-helper [--yes]
   dsh-plugin-mobile-gateway status
   dsh-plugin-mobile-gateway remove [--yes]
 
@@ -74,6 +81,111 @@ function writeManagedFile(file, content, mode = 0o644) {
   fs.chmodSync(file, mode)
 }
 
+function writeInstalledHelper(source, destination) {
+  if (fs.existsSync(destination)) {
+    const existing = fs.readFileSync(destination, 'utf8')
+    if (!existing.slice(0, 256).includes(MARKER)) {
+      throw new Error(`refusing to overwrite unmanaged file: ${destination}`)
+    }
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 })
+  const temporary = `${destination}.tmp-${process.pid}`
+  fs.copyFileSync(source, temporary)
+  fs.chmodSync(temporary, 0o755)
+  fs.renameSync(temporary, destination)
+}
+
+function helperService(uid) {
+  return `${MARKER}
+[Unit]
+Description=DSH mobile gateway privileged configuration helper
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/python3 ${HELPER_INSTALL} --uid ${uid} --socket ${HELPER_SOCKET}
+Restart=on-failure
+RestartSec=2s
+RuntimeDirectory=dsh-mobile-gateway
+RuntimeDirectoryMode=0755
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=full
+ReadWritePaths=/etc/nginx /etc/dsh-mobile-gateway /etc/letsencrypt /var/lib/dsh-mobile-gateway /var/lib/letsencrypt /var/log/letsencrypt /run/dsh-mobile-gateway
+
+[Install]
+WantedBy=multi-user.target
+`
+}
+
+function invokingUserId() {
+  const value = Number(process.env.SUDO_UID)
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error('setup-helper must be run with sudo from the user that runs dsh web')
+  }
+  return value
+}
+
+async function init() {
+  if (typeof process.getuid === 'function' && process.getuid() === 0) {
+    throw new Error('init must run as the normal DSH user, without sudo')
+  }
+  if (!commandExists('dsh') || !commandExists('sudo')) {
+    throw new Error('init requires dsh and sudo on PATH')
+  }
+  run('dsh', ['plugin', '--profile', 'web', 'add', 'dsh-plugin-mobile-gateway@latest'])
+  const script = fileURLToPath(import.meta.url)
+  run('sudo', ['env', `PATH=${process.env.PATH || ''}`, process.execPath, script, 'setup-helper'])
+  console.log('\nInitialization completed. Start or restart DSH with: dsh web')
+}
+
+function setupHelper() {
+  assertRoot()
+  const uid = invokingUserId()
+  if (!commandExists('apt-get') || !commandExists('systemctl')) {
+    throw new Error('helper installation currently supports systemd-based Ubuntu/Debian servers only')
+  }
+  run('apt-get', ['update'])
+  run('apt-get', ['install', '-y', 'nginx', 'python3', 'python3-venv'])
+  if (!fs.existsSync(CERTBOT)) {
+    run('python3', ['-m', 'venv', CERTBOT_HOME])
+    run(path.join(CERTBOT_HOME, 'bin/pip'), ['install', '--upgrade', 'pip'])
+  }
+  run(path.join(CERTBOT_HOME, 'bin/pip'), ['install', '--upgrade', 'certbot>=5.4,<6'])
+  for (const directory of [CONFIG_DIR, WEBROOT, '/etc/letsencrypt', '/var/lib/letsencrypt', '/var/log/letsencrypt']) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o755 })
+  }
+  writeInstalledHelper(HELPER_SOURCE, HELPER_INSTALL)
+  writeManagedFile(HELPER_SERVICE, helperService(uid))
+  writeManagedFile(RENEW_SERVICE, renewalService())
+  writeManagedFile(RENEW_TIMER, renewalTimer())
+  run('systemctl', ['daemon-reload'])
+  run('systemctl', ['enable', '--now', path.basename(HELPER_SERVICE)])
+  run('systemctl', ['restart', path.basename(HELPER_SERVICE)])
+  run('systemctl', ['enable', '--now', path.basename(RENEW_TIMER)])
+  console.log(`\nHelper installed for uid ${uid}. Public access can now be configured from the Mobile Devices panel.`)
+}
+
+async function removeHelper(options) {
+  assertRoot()
+  if (!await confirm('Remove the privileged mobile gateway helper? Existing Nginx configuration will be kept.', options.yes)) {
+    console.log('Cancelled.')
+    return
+  }
+  if (commandExists('systemctl')) {
+    try { run('systemctl', ['disable', '--now', path.basename(HELPER_SERVICE)]) } catch {}
+  }
+  for (const file of [HELPER_SERVICE, HELPER_INSTALL]) {
+    if (!fs.existsSync(file)) continue
+    const existing = fs.readFileSync(file, 'utf8')
+    if (!existing.slice(0, 256).includes(MARKER)) throw new Error(`refusing to remove unmanaged file: ${file}`)
+    fs.rmSync(file)
+    console.log(`Removed ${file}`)
+  }
+  if (commandExists('systemctl')) run('systemctl', ['daemon-reload'])
+}
+
 function metadataPublicIp() {
   return new Promise((resolve) => {
     const request = http.get({
@@ -310,6 +422,7 @@ export {
   nginxHttpConfig,
   nginxTlsConfig,
   parseArgs,
+  helperService,
   renewalService,
   renewalTimer,
 }
@@ -329,6 +442,9 @@ if (isMainModule(process.argv[1])) {
   try {
     const options = parseArgs(process.argv.slice(2))
     if (options.command === 'help') printHelp()
+    else if (options.command === 'init') await init()
+    else if (options.command === 'setup-helper') setupHelper()
+    else if (options.command === 'remove-helper') await removeHelper(options)
     else if (options.command === 'setup') await setup(options)
     else if (options.command === 'status') status()
     else if (options.command === 'remove') await remove(options)

package/helper/dsh_mobile_gateway_helper.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+# Managed by dsh-plugin-mobile-gateway
+"""Root-only, deliberately narrow system helper for the mobile gateway."""
+
+import argparse
+import ipaddress
+import json
+import os
+import pathlib
+import re
+import shutil
+import socketserver
+import subprocess
+import sys
+
+
+VERSION = 1
+MARKER = "# Managed by dsh-plugin-mobile-gateway"
+SOCKET_PATH = "/run/dsh-mobile-gateway/helper.sock"
+CONFIG_DIR = pathlib.Path("/etc/dsh-mobile-gateway")
+PUBLIC_URL_FILE = CONFIG_DIR / "public-url"
+NGINX_CONFIG = pathlib.Path("/etc/nginx/conf.d/dsh-mobile-gateway.conf")
+WEBROOT = pathlib.Path("/var/lib/dsh-mobile-gateway/acme")
+CERTBOT_HOME = pathlib.Path("/opt/dsh-mobile-gateway/certbot")
+CERTBOT = CERTBOT_HOME / "bin/certbot"
+
+
+def run(args):
+    subprocess.run(args, check=True)
+
+
+def atomic_managed_write(target, content, mode=0o644):
+    target = pathlib.Path(target)
+    if target.exists() and not target.read_text(encoding="utf-8").startswith(MARKER):
+        raise RuntimeError(f"refusing to overwrite unmanaged file: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = target.with_name(f"{target.name}.tmp-{os.getpid()}")
+    temporary.write_text(content, encoding="utf-8")
+    os.chmod(temporary, mode)
+    os.replace(temporary, target)
+
+
+def validate_public_ip(value):
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError as error:
+        raise ValueError("publicIp must be a valid IPv4 address") from error
+    if address.version != 4 or not address.is_global:
+        raise ValueError("publicIp must be a public IPv4 address")
+    return str(address)
+
+
+def validate_port(value):
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1 or value > 65535:
+        raise ValueError("backendPort must be an integer between 1 and 65535")
+    return value
+
+
+def certificate_name(public_ip):
+    return f"dsh-mobile-gateway-{public_ip.replace('.', '-')}"
+
+
+def nginx_http_config(public_ip):
+    return f"""{MARKER}
+server {{
+    listen 80;
+    server_name {public_ip};
+
+    location ^~ /.well-known/acme-challenge/ {{
+        root {WEBROOT};
+        default_type text/plain;
+    }}
+
+    location / {{ return 404; }}
+}}
+"""
+
+
+def nginx_tls_config(public_ip, backend_port):
+    live = f"/etc/letsencrypt/live/{certificate_name(public_ip)}"
+    return nginx_http_config(public_ip) + f"""
+server {{
+    listen 443 ssl;
+    server_name {public_ip};
+    server_tokens off;
+    access_log off;
+
+    ssl_certificate {live}/fullchain.pem;
+    ssl_certificate_key {live}/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    location = /ws/mobile {{
+        if ($args != \"\") {{ return 404; }}
+        proxy_pass http://127.0.0.1:{backend_port};
+        proxy_http_version 1.1;
+        proxy_set_header Host 127.0.0.1:{backend_port};
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection \"upgrade\";
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_buffering off;
+    }}
+
+    location / {{ return 404; }}
+}}
+"""
+
+
+def current_status():
+    public_url = None
+    if PUBLIC_URL_FILE.exists():
+        public_url = next((line.strip() for line in PUBLIC_URL_FILE.read_text(encoding="utf-8").splitlines()
+                           if line.strip().startswith("wss://")), None)
+    backend_port = None
+    if NGINX_CONFIG.exists():
+        match = re.search(r"proxy_pass http://127\.0\.0\.1:(\d+);", NGINX_CONFIG.read_text(encoding="utf-8"))
+        if match:
+            backend_port = int(match.group(1))
+    return {
+        "installed": True,
+        "version": VERSION,
+        "configured": bool(public_url and backend_port),
+        "publicUrl": public_url,
+        "backendPort": backend_port,
+    }
+
+
+def ensure_dependencies():
+    if not shutil.which("nginx") or not CERTBOT.exists():
+        raise RuntimeError("helper dependencies are missing; rerun init to repair the installation")
+
+
+def configure(public_ip, backend_port):
+    public_ip = validate_public_ip(public_ip)
+    backend_port = validate_port(backend_port)
+    previous = NGINX_CONFIG.read_bytes() if NGINX_CONFIG.exists() else None
+    if previous is not None and not previous.decode("utf-8").startswith(MARKER):
+        raise RuntimeError(f"refusing to overwrite unmanaged file: {NGINX_CONFIG}")
+
+    ensure_dependencies()
+    (WEBROOT / ".well-known/acme-challenge").mkdir(parents=True, exist_ok=True)
+    try:
+        atomic_managed_write(NGINX_CONFIG, nginx_http_config(public_ip))
+        run(["nginx", "-t"])
+        run(["systemctl", "enable", "--now", "nginx"])
+        run(["systemctl", "reload", "nginx"])
+
+        args = [
+            str(CERTBOT), "certonly", "--non-interactive", "--agree-tos",
+            "--preferred-profile", "shortlived", "--webroot", "--webroot-path", str(WEBROOT),
+            "--ip-address", public_ip, "--cert-name", certificate_name(public_ip),
+            "--keep-until-expiring", "--register-unsafely-without-email",
+        ]
+        run(args)
+        atomic_managed_write(NGINX_CONFIG, nginx_tls_config(public_ip, backend_port))
+        atomic_managed_write(PUBLIC_URL_FILE, f"{MARKER}\nwss://{public_ip}/ws/mobile\n")
+        run(["nginx", "-t"])
+        run(["systemctl", "reload", "nginx"])
+    except Exception:
+        if previous is None:
+            NGINX_CONFIG.unlink(missing_ok=True)
+        else:
+            NGINX_CONFIG.write_bytes(previous)
+        if shutil.which("nginx"):
+            subprocess.run(["nginx", "-t"], check=False)
+            subprocess.run(["systemctl", "reload", "nginx"], check=False)
+        raise
+    return current_status()
+
+
+def dispatch(message):
+    action = message.get("action")
+    if action == "status":
+        return current_status()
+    if action == "configure":
+        return configure(message.get("publicIp"), message.get("backendPort"))
+    raise ValueError("unsupported helper action")
+
+
+class Handler(socketserver.StreamRequestHandler):
+    def handle(self):
+        try:
+            raw = self.rfile.readline(65537)
+            if not raw or len(raw) > 65536:
+                raise ValueError("invalid helper request")
+            message = json.loads(raw.decode("utf-8"))
+            if not isinstance(message, dict):
+                raise ValueError("helper request must be an object")
+            response = {"ok": True, "result": dispatch(message)}
+        except Exception as error:  # Return a typed error; never expose a traceback.
+            response = {"ok": False, "error": str(error)}
+        self.wfile.write((json.dumps(response, separators=(",", ":")) + "\n").encode("utf-8"))
+
+
+class Server(socketserver.UnixStreamServer):
+    allow_reuse_address = True
+
+
+def serve(uid, socket_path):
+    if os.geteuid() != 0:
+        raise RuntimeError("helper must run as root")
+    path = pathlib.Path(socket_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.unlink(missing_ok=True)
+    with Server(str(path), Handler) as server:
+        os.chown(path, uid, -1)
+        os.chmod(path, 0o600)
+        server.serve_forever()
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--uid", type=int, required=True)
+    parser.add_argument("--socket", default=SOCKET_PATH)
+    options = parser.parse_args()
+    if options.uid < 1:
+        raise ValueError("uid must identify a non-root user")
+    serve(options.uid, options.socket)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        print(f"dsh-mobile-gateway-helper: {error}", file=sys.stderr)
+        raise SystemExit(1)

package/lib/client.js

@@ -116,6 +116,9 @@ window.__ModuleLoader__.load({
       const [devices, setDevices] = React.useState(null)
       const [status, setStatus] = React.useState(null)
       const [publicUrl, setPublicUrl] = React.useState('')
+      const [publicIp, setPublicIp] = React.useState('')
+      const [publicSetup, setPublicSetup] = React.useState(null)
+      const [publicSetupBusy, setPublicSetupBusy] = React.useState(false)
       const [deviceName, setDeviceName] = React.useState('iPhone')
       const [qr, setQr] = React.useState(null)
       const [error, setError] = React.useState(null)
@@ -175,10 +178,40 @@ window.__ModuleLoader__.load({
       React.useEffect(() => {
         let active = true
         refresh()
+        request('/mgw/public-setup').then((data) => {
+          if (!active) return
+          setPublicSetup(data)
+          if (data.publicUrl) {
+            const match = /^wss:\/\/([^/]+)\/ws\/mobile$/.exec(data.publicUrl)
+            if (match) setPublicIp(match[1])
+          }
+        }).catch((cause) => active && setPublicSetup({ installed: false, configured: false, error: cause.message }))
         const timer = window.setInterval(refresh, 3000)
         return () => { active = false; window.clearInterval(timer) }
       }, [refresh])
 
+      const configurePublicAccess = async () => {
+        if (publicSetupBusy) return
+        setPublicSetupBusy(true)
+        setError(null)
+        try {
+          const data = await request('/mgw/public-setup', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ publicIp }),
+          })
+          setPublicSetup(data)
+          if (data.publicUrl) {
+            automaticUrlRef.current = data.publicUrl
+            setPublicUrl(data.publicUrl)
+          }
+        } catch (cause) {
+          setError(cause.message)
+        } finally {
+          setPublicSetupBusy(false)
+        }
+      }
+
       const createPairing = async (endpoint) => request('/mgw/pair', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -331,6 +364,37 @@ window.__ModuleLoader__.load({
             status && !status.requireAuth
               ? React.createElement('p', { style: { ...styles.error, margin: '12px 0 0' } }, 'Debug 模式：本机 DSH 入口将跳过设备凭证校验；独立局域网入口仍强制鉴权。')
               : null),
+          React.createElement('section', { style: styles.card },
+            React.createElement('strong', null, '公网接入'),
+            publicSetup === null
+              ? React.createElement('p', { style: styles.muted }, '正在检查系统组件…')
+              : publicSetup.installed
+                ? React.createElement(React.Fragment, null,
+                    React.createElement('div', { style: { ...styles.muted, margin: '5px 0 12px' } }, publicSetup.configured
+                      ? publicSetup.backendPort && status && status.webPort && publicSetup.backendPort !== status.webPort
+                        ? `端口需要更新：Nginx 当前为 ${publicSetup.backendPort}，DSH 当前为 ${status.webPort}`
+                        : `已配置${publicSetup.backendPort ? `，Nginx 转发至 DSH 端口 ${publicSetup.backendPort}` : ''}`
+                      : `Helper 已就绪，将自动使用当前 DSH 端口${status && status.webPort ? ` ${status.webPort}` : ''}`),
+                    React.createElement('label', { style: styles.label }, '服务器公网 IPv4'),
+                    React.createElement('input', {
+                      style: styles.input,
+                      value: publicIp,
+                      onChange: (event) => setPublicIp(event.target.value.trim()),
+                      placeholder: '203.0.113.10',
+                      inputMode: 'decimal',
+                      spellCheck: false,
+                    }),
+                    React.createElement('button', {
+                      style: { ...styles.button, ...styles.primary, opacity: publicSetupBusy || !publicIp ? .65 : 1 },
+                      disabled: publicSetupBusy || !publicIp,
+                      onClick: configurePublicAccess,
+                    }, publicSetupBusy ? '正在配置 Nginx 与证书…' : publicSetup.configured ? '更新公网配置' : '配置公网接入'),
+                    publicSetup.publicUrl
+                      ? React.createElement('div', { style: { ...styles.muted, marginTop: 9, overflowWrap: 'anywhere' } }, publicSetup.publicUrl)
+                      : null)
+                : React.createElement(React.Fragment, null,
+                    React.createElement('p', { style: { ...styles.muted, marginBottom: 8 } }, '尚未安装系统 Helper。请在服务器执行一次初始化：'),
+                    React.createElement('code', { style: { display: 'block', fontSize: 10, lineHeight: 1.5, overflowWrap: 'anywhere', userSelect: 'all' } }, 'npx --yes dsh-plugin-mobile-gateway@latest init'))),
           React.createElement('section', { style: styles.card },
             React.createElement('label', { style: styles.label }, 'WebSocket 地址'),
             React.createElement('input', { style: styles.input, value: publicUrl, onChange: (event) => { automaticUrlRef.current = ''; setPublicUrl(event.target.value) }, placeholder: 'ws://192.168.1.10:3081/ws/mobile', spellCheck: false }),

package/lib/index.mjs

@@ -38,6 +38,7 @@
 //                     { "type": "default-model" }                   -> agentDefaultModel.currentSelection()
 //                     { "type": "save-default-model", "provider", "model", "reasoningEffort"? }
 //                     { "type": "directories", "path"? }           -> server dir listing (fs-based)
+//                     { "type": "directory-create", "path", "name" } -> create one child directory
 //                     { "type": "workspace-create", "path" }       -> create workspace over a dir
 //                     { "type": "fork", "sessionId", "atSeq"? }    -> branch a new session from a completed turn
 //                     { "type": "models", "sessionId"? }           -> per-session catalog (with sessionId) or global (without)
@@ -68,6 +69,7 @@
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import http from 'node:http'
+import net from 'node:net'
 import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
@@ -87,6 +89,7 @@ const PLUGIN_VERSION = (() => {
 })()
 const MAX_PREVIEW = 400
 const LOG_FILE = '/tmp/mobile-gateway.log'
+const HELPER_SOCKET = '/run/dsh-mobile-gateway/helper.sock'
 const DEFAULT_WS_PATH = '/ws/mobile'
 const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000
 const DEFAULT_GATEWAY_WAIT_TIMEOUT_MS = 5 * 60 * 1000
@@ -380,6 +383,56 @@ async function listServerDirectory(target) {
   }
 }
 
+function directoryCreateError(code, message) {
+  return { kind: 'error', code, message, requestType: 'directory-create' }
+}
+
+// Create one child directory directly on the host filesystem. This deliberately
+// shares the same backend as `directories`: macOS native Directory Picker only
+// exposes its system dialog and does not implement remote createDirectory RPCs.
+async function createServerDirectory(parentPath, directoryName) {
+  if (typeof parentPath !== 'string' || parentPath.trim() === '') {
+    return directoryCreateError('bad-request', 'directory-create requires an absolute parent path')
+  }
+  const parent = path.resolve(parentPath.trim())
+  if (!path.isAbsolute(parentPath.trim())) {
+    return directoryCreateError('bad-request', 'directory-create path must be absolute')
+  }
+
+  if (typeof directoryName !== 'string') {
+    return directoryCreateError('bad-request', 'directory-create requires a folder name')
+  }
+  const name = directoryName.trim()
+  if (!name || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+    return directoryCreateError('bad-request', 'directory-create name must be a single non-empty folder name')
+  }
+
+  try {
+    const stat = await fsp.stat(parent)
+    if (!stat.isDirectory()) {
+      return directoryCreateError('directory-create-failed', 'parent path is not a directory')
+    }
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error)
+    log(`query failed: directory-create -> ${message}`)
+    return directoryCreateError('directory-create-failed', message)
+  }
+
+  const target = path.join(parent, name)
+  try {
+    await fsp.mkdir(target)
+    log(`query ok: directory-create (${target})`)
+    return { kind: 'directory-create', path: target }
+  } catch (error) {
+    if (error && error.code === 'EEXIST') {
+      return directoryCreateError('directory-exists', 'directory already exists')
+    }
+    const message = error && error.message ? error.message : String(error)
+    log(`query failed: directory-create -> ${message}`)
+    return directoryCreateError('directory-create-failed', message)
+  }
+}
+
 // Validate one sessionId field; returns { value } or { error }.
 function requireSessionId(msg) {
   const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
@@ -578,6 +631,9 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
   if (msg.type === 'directories') {
     return listServerDirectory(typeof msg.path === 'string' && msg.path.trim() !== '' ? msg.path.trim() : undefined)
   }
+  if (msg.type === 'directory-create') {
+    return createServerDirectory(msg.path, msg.name)
+  }
   if (msg.type === 'models') {
     const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
     if (sessionId) {
@@ -888,6 +944,54 @@ function sendJson(res, status, value) {
   res.end(body)
 }
 
+function callSystemHelper(message, timeoutMs = 2_000) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    let body = ''
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      if (error) reject(error)
+      else resolve(value)
+    }
+    const socket = net.createConnection(HELPER_SOCKET)
+    socket.setEncoding('utf8')
+    socket.setTimeout(timeoutMs)
+    socket.on('connect', () => socket.write(`${JSON.stringify(message)}\n`))
+    socket.on('data', (chunk) => {
+      body += chunk
+      if (body.length > 1024 * 1024) return finish(new Error('system helper response is too large'))
+      const newline = body.indexOf('\n')
+      if (newline < 0) return
+      try {
+        const response = JSON.parse(body.slice(0, newline))
+        if (!response || response.ok !== true) throw new Error(response && response.error ? response.error : 'system helper request failed')
+        finish(null, response.result)
+      } catch (error) {
+        finish(error)
+      }
+    })
+    socket.on('timeout', () => finish(new Error('system helper request timed out')))
+    socket.on('error', (error) => finish(error))
+    socket.on('end', () => {
+      if (!settled) finish(new Error('system helper closed without a response'))
+    })
+  })
+}
+
+async function systemHelperStatus() {
+  try {
+    return await callSystemHelper({ action: 'status' })
+  } catch (error) {
+    return {
+      installed: false,
+      configured: false,
+      error: error && error.message ? error.message : String(error),
+    }
+  }
+}
+
 const plugin = {
   name: 'mobile-gateway',
   Config,
@@ -1101,6 +1205,7 @@ const plugin = {
               gatewayEnabled,
               waitExpiresAt,
               connectedClients: clients.size,
+              webPort: webServer.port,
               wsPath,
               publicUrl: configuredPublicUrl() || null,
               lan: {
@@ -1115,6 +1220,18 @@ const plugin = {
               pairingTtlMs: options.pairingTtlMs,
               queryTokenAllowed: !!options.allowQueryToken,
             })
+          } else if (req.method === 'GET' && p === '/mgw/public-setup') {
+            sendJson(res, 200, await systemHelperStatus())
+          } else if (req.method === 'POST' && p === '/mgw/public-setup') {
+            const body = await readBody(req)
+            if (typeof body.publicIp !== 'string' || !body.publicIp.trim()) throw badRequest('publicIp is required')
+            const result = await callSystemHelper({
+              action: 'configure',
+              publicIp: body.publicIp.trim(),
+              backendPort: webServer.port,
+            }, 15 * 60 * 1000)
+            log(`public endpoint configured: ${result.publicUrl} -> 127.0.0.1:${result.backendPort}`)
+            sendJson(res, 200, result)
           } else if (req.method === 'POST' && p === '/mgw/gateway') {
             const body = await readBody(req)
             if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
@@ -1269,7 +1386,7 @@ const plugin = {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
             } 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 === 'search' || msg.type === 'host' || msg.type === 'directories' || msg.type === 'directory-create' ||
                        msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'select-model' ||
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
                        msg.type === 'agent-presets' || msg.type === 'defaults' || msg.type === 'set-default' ||

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.6.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.3",
+  "description": "update readme",
   "main": "lib/index.mjs",
   "files": [
     "bin",
+    "helper",
     "lib",
     "docs",
     "cordis.patch.yml",

package/docs/public-ip-deployment-guide.md

@@ -1,135 +0,0 @@
-# 公网 IP 命令行配对指南
-
-适用于通过 nvm 安装 Node.js、已经可以直接使用 `dsh` 命令的 Ubuntu/Debian 服务器。服务器端不需要打开 WebUI：终端会直接输出 iOS 所需的 Base64URL 配对字符串。
-
-## 1. 放行公网端口
-
-先在云安全组中放行 TCP `80` 和 `443`。不要开放 `3080`、`3081` 或 `/mgw/*`。
-
-如果服务器启用了 UFW：
-
-```bash
-sudo ufw allow 80/tcp
-sudo ufw allow 443/tcp
-```
-
-## 2. 安装插件和辅助命令
-
-```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
-sudo apt-get update
-sudo apt-get install -y jq tmux
-```
-
-## 3. 配置公网 WSS
-
-获取服务器公网 IPv4：
-
-```bash
-PUBLIC_IP="$(curl -4 -fsS https://ifconfig.me)"
-printf 'Public IP: %s\n' "$PUBLIC_IP"
-```
-
-如果显示的不是服务器实际公网 IPv4，请手动执行 `PUBLIC_IP="实际公网IP"`。
-
-因为 Node.js 来自 nvm，运行安装器时需要把当前 `PATH` 传给 `sudo`：
-
-```bash
-sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest setup \
-  --ip "$PUBLIC_IP" \
-  --port 3080
-```
-
-安装成功后检查：
-
-```bash
-sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest status
-```
-
-应显示：
-
-```text
-wss://<公网IP>/ws/mobile
-```
-
-## 4. 启动 DSH
-
-```bash
-tmux new -s dsh
-dsh web
-```
-
-看到 `dsh web: http://127.0.0.1:3080` 后，按 `Ctrl+B`，再按 `D`，让 DSH 在后台继续运行。
-
-## 5. 在终端生成配对字符串
-
-重新读取公网地址，并明确开启设备鉴权和移动网关：
-
-```bash
-PUBLIC_IP="$(curl -4 -fsS https://ifconfig.me)"
-PUBLIC_URL="wss://$PUBLIC_IP/ws/mobile"
-
-curl -fsS -X POST http://127.0.0.1:3080/mgw/auth \
-  -H 'Content-Type: application/json' \
-  -d '{"enabled":true}'
-
-curl -fsS -X POST http://127.0.0.1:3080/mgw/gateway \
-  -H 'Content-Type: application/json' \
-  -d '{"enabled":true}'
-```
-
-生成一次性 Base64URL 配对字符串：
-
-```bash
-PAIRING_TEXT="$(
-  jq -nc --arg name 'iPhone' --arg url "$PUBLIC_URL" \
-    '{name:$name,publicUrl:$url}' \
-  | curl -fsS -X POST http://127.0.0.1:3080/mgw/pair \
-      -H 'Content-Type: application/json' \
-      --data-binary @- \
-  | jq -r '.qrPayload'
-)"
-
-if [ -z "$PAIRING_TEXT" ] || [ "$PAIRING_TEXT" = 'null' ]; then
-  echo '生成配对字符串失败，请检查 DSH 和插件日志'
-else
-  printf '\n复制下面这一整行到 iPhone：\n\n%s\n\n' "$PAIRING_TEXT"
-fi
-```
-
-配对字符串只能使用一次，并在 5 分钟后过期。如果超时，重新执行本节最后两段命令。
-
-## 6. 在 iPhone 完成绑定
-
-1. 打开 iOS 客户端的“设备认证”。
-2. 把终端输出的整行内容粘贴到“手动输入配对信息”。
-3. 点击“配对并连接”或“重新配对并连接”。
-4. 状态显示“已连接”后点击“完成”。
-
-iOS 会把长期设备凭证保存到 Keychain，之后启动时会自动重新连接，不需要再次执行配对。
-
-## 7. 检查结果
-
-服务器查看可信设备：
-
-```bash
-curl -fsS http://127.0.0.1:3080/mgw/devices | jq
-```
-
-查看插件日志：
-
-```bash
-tail -f /tmp/mobile-gateway.log
-```
-
-常见结果：
-
-- `503`：移动网关未开启，重新执行第 5 节的网关开启命令。
-- `401`：配对字符串过期、已使用或客户端凭证无效，重新生成配对字符串。
-- 公网连接超时：检查云安全组、UFW、Nginx，以及 TCP `80/443`。
-
-查看后台 DSH：
-
-```bash
-tmux attach -t dsh
-```