dsh-plugin-mobile-gateway 0.6.1 → 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

@@ -13,7 +13,7 @@
 
 ## 配套 iOS 客户端
 
-[DeepSeek Harness Mobile](https://github.com/Clarklevis1995/dsh-mobile) 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop、模型与权限设置。
+[DeepSeek Harness Mobile](https://github.com/Clarklevis1995/dsh-mobile) 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、工作区内创建文件夹、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop、模型与权限设置。
 
 <table>
   <tr>
@@ -32,10 +32,18 @@
 
 前提：已经安装 `dsh` CLI，并能正常启动 `dsh web`。
 
+局域网使用只需安装插件：
+
 ```bash
 dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
+需要公网接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：
+
+```bash
+npx --yes dsh-plugin-mobile-gateway@latest init
+```
+
 安装后停止并重新启动 WebUI：
 
 ```bash
@@ -72,15 +80,13 @@ dsh web
 
 ### 2. 配置公网入口
 
-把示例 IP 替换为云厂商控制台中的实际公网 IPv4：
+执行一次初始化（已经执行过可跳过）：
 
 ```bash
-sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest setup \
-  --ip 203.0.113.10 \
-  --port 3080
+npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
-安装器完成后，重新启动：
+然后启动或重新启动：
 
 ```bash
 dsh web
@@ -91,24 +97,23 @@ dsh web
 如果 WebUI 运行在远程服务器，在自己的电脑执行：
 
 ```bash
-ssh -N -L 3080:127.0.0.1:3080 <服务器用户名>@<服务器公网 IP>
+ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服务器公网 IP>
 ```
 
 然后在本地浏览器打开：
 
 ```text
-http://127.0.0.1:3080
+http://127.0.0.1:<本地端口>
 ```
 
 ### 4. 使用 WebUI 配对
 
-1. 打开“移动设备”。
-2. 开启“允许移动设备连接”。
-3. 保持“设备鉴权”开启。
-4. 确认 WebSocket 地址为 `wss://<公网 IP>/ws/mobile`。
-5. 填写设备名称并点击“生成配对二维码”。
-6. iPhone 打开“设备认证”，扫描二维码；也可以复制 Base64URL 配对字符串手动连接。
-7. WebUI 的可信设备显示“在线”后即完成。
+1. 打开“移动设备”，在“公网接入”中填写云厂商控制台提供的公网 IPv4。
+2. 点击“配置公网接入”。Helper 会自动使用当前 `dsh web` 端口配置 Nginx 和证书。
+3. 开启“允许移动设备连接”，保持“设备鉴权”开启。
+4. 填写设备名称并点击“生成配对二维码”。
+5. iPhone 打开“设备认证”并扫描二维码。
+6. WebUI 的可信设备显示“在线”后即完成。
 
 二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。
 
@@ -128,10 +133,10 @@ sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove
 
 ## 更新插件
 
-重新安装 npm 最新版本：
+重新运行初始化命令会同时更新插件和系统 Helper：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
+npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
 随后停止并重新启动 `dsh web`。
@@ -142,6 +147,12 @@ dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 dsh plugin --profile web remove dsh-plugin-mobile-gateway
 ```
 
+如需同时移除系统 Helper（不会删除现有 Nginx 公网配置）：
+
+```bash
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove-helper
+```
+
 ## 常见问题
 
 | 现象 | 处理方式 |

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.1",
+  "version": "0.6.3",
   "description": "update readme",
   "main": "lib/index.mjs",
   "files": [
     "bin",
+    "helper",
     "lib",
     "docs",
     "cordis.patch.yml",