手机远控 66jiujiu99/dsh-plugin-remote-mobile

dsh-plugin-remote-mobile · 手机同步

把 DSH 桌面版的完整 Web UI 搬到手机上：手机浏览器打开 http://<LAN-IP>:17890/m，看到的就是 PC 上那个界面——工作区分组、会话、插件设置、排队提示，全都在。

所有操作都在 PC 上执行：手机只是远端的遥控器和显示器，模型、工具、文件系统、终端，全部跑在你那台电脑上。

- 对外契约：PROTOCOL.md
- 零第三方依赖：只用 node: 内置模块（http/net/crypto/fs/os/stream），ESM，无构建。

1. 它到底是什么（先看这一节）

手机 ──http://<LAN-IP>:17890/m/──▶ 插件监听器（0.0.0.0:17890） ──WS /m/api/remote.mux────▶ │ ① Host/Origin 栅栏（挡 DNS rebinding） │ ② 设备 cookie 校验（配对过才放行） │ ③ 剥前缀 /m → / │ ④ 注入上游 cookie、抹掉手机凭据 ▼ DSH 自己的 Web 端口（127.0.0.1:<随机>）

它不是「重新实现的移动版」，而是一层反向代理：把 localhost:<port> 上的网站，挂到 0.0.0.0:17890/m/ 上，并加了一道配对门。

这样做的直接好处：DSH 加什么新功能，手机上就有——不用维护第二套界面。

⚠️ 重要：反代只搬「界面」，不搬「能力」

这是使用前必须理解的一条。

手机浏览器里跑的是页面 JavaScript 本身，而不是 PC 的 Electron 渲染进程。
所以任何依赖 Electron / 本机 Node 的功能，到手机上会显示正常但点了会失败：

| 功能 | 手机上 | 原因 |
| 会话、消息、工作区分组 | ✅ 可用 | 纯网络请求，走反代 |
| 发消息、选模型、切换工作区 | ✅ 可用 | 纯网络请求 |
| 插件设置、账号、审批 | ✅ 可用 | 纯网络请求 |
| 文件浏览 / 读工作区文件 | ✅ 可用 | 走 RPC 回 PC 读 |
| Agent 浏览器（webview） | ❌ 不可用 | 需要 Electron 主进程的 webview lease API |
| 终端 | ⚠️ 取决于实现 | 若走 Host RPC 则可用；若依赖本地 pty 则不可用 |
| 选目录 / 打开文件对话框 | ❌ 弹在 PC 上 | 原生对话框由 PC 的 Electron 弹出 |

看到「受控浏览器只在 DSH 桌面版可用」这句提示时，就是这个原因——不是权限问题，是手机浏览器没有那个 API。

想彻底解决「手机上操控网页」，需要另做云浏览器（PC 上跑有头浏览器、截图回传、点击转 CDP 输入）。那是另一个量级的工程，本插件不做。

2. 安装

在 DSH 里（需要 danger-full-access 或逐次批准） plugin_manager install_bundle target=C:\path\to\dsh-plugin-remote-mobile

安装 ≠ 开启。装好之后还要在配置里设 enabled: true（或在设置页的「手机同步」里打开开关）。

配置陷阱：插件重载（set_plugin enabled=false/true）会用运行时状态重写 ~/.dsh/profiles/<profile>/cordis.yml。所以手工改完配置后必须重启 DSH，不要在中间重载插件，否则配置会被覆盖回旧值。

示例配置（cordis.yml 中本插件那一行的 config）：

enabled: true
bindAddress: 0.0.0.0
port: 17890
allowedNetworks: [] # 空 = 只允许私有网段（192.168/10/172.16-31）+ 链路本地 + loopback
deviceOnlineWindowMs: 90000
deviceOfflineTtlMs: 43200000

3. 第一次用

1. 手机连上和 PC 同一个 WiFi / 热点（PC 开热点就是 192.168.137.1）
2. 手机打开 http://<PC-IP>:17890/m
3. 会被跳到配对页，输入 PC 面板上显示的配对码（默认 60 秒有效、5 次尝试）
4. 配对成功后进入完整界面；cookie 有效期 cookieMaxAgeDays（默认 180 天）

找不到 IP？在 PC 上跑：

netstat -ano | findstr :17890

或直接看插件面板，它会列出所有可用 URL。

4. 端点

| 路径 | 谁处理 | 说明 |
| GET /m/ping | 插件 | 健康检查（无鉴权），配对页靠它判断 PC 是否在线 |
| GET /m/pair | 插件 | 配对页 |
| POST /m/pair | 插件 | 配对提交（JSON 或 urlencoded） |
| /m/（其余） | 反代到上游* | 缺尾斜杠会 302 到 /m/，否则相对路径会跳出前缀 |
| WS /m/api/remote.mux | 反代到上游 | 会话流；缺它页面只剩静态外壳 |

尾斜杠是功能要求：上游 index.html 注入 ，资源全是相对路径。
地址栏停在 /m（无斜杠）时 ./assets/x.js 会解析成 /assets/x.js（跳出前缀）→ 整站 404。

面板 RPC（PC 侧，需要连接凭据）

| op | 作用 |
| status / set.enabled | 状态 / 开关监听 |
| pair.create / pair.cancel | 生成 / 取消配对码 |
| devices. | 列设备、改名、撤销、只读 |
| tunnel.start / tunnel.stop / tunnel.status | 开关公网隧道、查状态 |
| kill / audit.head / selftest | 急停 / 审计 / 自检 |

4.1 公网隧道（可选，默认关闭）

不开隧道时，手机必须和 PC 在同一个 WiFi / 热点。开了隧道，手机可以用任意网络访问。
用的是 Cloudflare Quick Tunnel：匿名、免账号、免服务器、免公网 IP。

怎么装 cloudflared

插件本身不带 cloudflared（55MB，不适合进仓库）。三种方式任选：

1. 放便携版（最简单）：把 cloudflared.exe 丢进本插件的 tools/ 目录，插件会自动找到。
2. 指定路径：配置 tunnel.binaryPath: "C:/path/to/cloudflared.exe"。
3. 装进 PATH：winget install Cloudflare.cloudflared，插件会自动从 PATH 找。

下载地址（官方 Release，建议核对 SHA-256）：

https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe

怎么开

1. 先把「手机同步」开起来（隧道要指向监听端口）
2. 设置页 →「手机同步」→「公网隧道」→ 开启隧道
3. 等 10-60 秒（Cloudflare 分配域名），面板会显示公网地址
4. 用手机打开那个地址 → 配对 → 进入

这个开关是手动的，刻意不跟 enabled 联动：开了监听不等于要开公网。

四条行为约定

| 行为 | 说明 |
| 域名每次都变 | Quick Tunnel 不做持久域名。重连或重启后就是新地址 |
| 空闲自动断开 | tunnel.idleTimeoutSec（默认 1800 秒）内没有请求就自动关。设 0 = 永不主动关 |
| 断开后自动重连 | tunnel.reconnect（默认开）。指数退避重试，reconnectBudgetSec 内一直试 |
| 父死子亡 | DSH 崩溃或被任务管理器结束，隧道会跟着消失（靠管道所有权，不依赖清理代码） |

「链接多久失效」怎么配

Quick Tunnel 的域名由 Cloudflare 分配，cloudflared 进程一退出域名就作废。
所以"有效期"是两层，都能配：

tunnel:
① 我们主动关：多久没请求就关。0 = 永不主动关。
idleTimeoutSec: 0
② 意外断开后自动重连（会换新域名）。不想要就设 false。
reconnect: true
reconnectBudgetSec: 86400 # 重连额度：一天内一直尝试 reconnectMaxDelaySec: 60 # 退避上限

想尽量不失效：idleTimeoutSec: 0 + reconnect: true + 大 reconnectBudgetSec。

面板上也能改：设置 → 手机同步 →「公网隧道」→ 空闲断开下拉框。
改完立即生效，不用重启；选「永不主动关」等于 idleTimeoutSec: 0。
面板改的是运行时值，重启后会回到 cordis.patch.yml 里的配置。

必须知道的硬限制：DSH 一关（或被强杀），域名必然失效。这是 Quick Tunnel 的固有代价，不是本插件的限制——想拿固定域名得用 Cloudflare named tunnel （需要账号与自有域名），本插件不做。

配置项

tunnel:
provider: quick # none | quick（frpc 仍是预留形状，未实现） binaryPath: '' # 空 = 自动找 PATH 与 tools/ idleTimeoutSec: 1800 # 空闲多久自动关（0 = 永不主动关） reconnect: true # 意外断开后自动重连（换新域名） reconnectBudgetSec: 3600 # 重连总时长上限 reconnectMaxDelaySec: 60 # 指数退避上限 startTimeoutSec: 90 # 等域名的最长时间

5. 安全模型（决定要不要开之前读）

核心边界：手机只拿到一个设备 cookie（dshm_d）；DSH 自己的 dsh-auth- 凭据只存在插件内存里，永远不下发给手机。

| 防线 | 做法 |
| 来源网段 | allowedNetworks 为空时只放行私有网段 + 链路本地 + loopback |
| DNS rebinding | Host 必须是本机真实监听地址之一（LAN IP / hostname / localhost） |
| 跨站请求 | Origin 必须与 Host 同 authority；Sec-Fetch-Site: cross-site 一律拒 |
| 凭据隔离 | 上行抹掉手机的 Cookie/Authorization/Sec-Fetch-/X-Forwarded-；下行抹掉 Set-Cookie/HSTS |
| 永久黑名单 | terminal/、credentials/、plugin/、plugin-manager/、settings/ —— 任何设备任何路由都拒 |
| 只读设备 | fail-closed 白名单：只允许读取类端点，未知端点直接 403 |
| 撤权 | 单设备撤销立即断开在途连接；kill 急停但保留设备表，可恢复 |

必须知道的残余风险：

- 插件跑在宿主进程内、工作区沙箱之外，和你的用户权限相同。
- 开了监听就等于同一网络里的人可以探测到这个端口（虽然有配对门）。
在公共 WiFi 下建议关掉，或把 allowedNetworks 收紧到你家网段。
- 开了隧道 = 全球可达。这时候「同一 WiFi」这道天然边界没有了，只剩配对码。所以：配对码是 8 位（31 字符表，≈39.6 bit，已排除 0/O/1/I/L 等易混字符），并且按 IP 限流（10 次/分钟）+ 单码 5 次错误即锁 60 秒。在公网暴露期间请勿把配对码发到会被转发的渠道。
- 隧道用的是匿名 Quick Tunnel，流量经 Cloudflare 边缘。不要通过它传你不想让第三方看见的内容。
- Cloudflare 不保证 Quick Tunnel 的可用性；本插件会在空闲超时后主动关闭，减少暴露窗口。

6. 已知限制

1. 隧道只有 Quick Tunnel：域名每次重启都变（不做持久域名，那需要 Cloudflare 账号与 named tunnel）。frpc 仅在配置里预留形状，未实现。
2. 手机上的「能力」降级：见 §1 的表格。
3. 布局不专门适配手机：DSH Web UI 是给宽屏设计的，手机上侧栏会挤。目前"能用"，但没有专门的移动端 CSS。
4. webview 类插件在手机上不可用：架构限制，不是配置问题。

7. 实测状态（2026-10-23 / 24）

| 项 | 状态 | 证据 |
| 整站反代 | ✅ | 手机打开 /m/ 看到完整 UI，会话内容正常渲染 |
| 工作区分组 | ✅ | 补齐 remoteAccess/follow 流后，会话从「未分组」回到正确归属 |
| 账号/登录态显示 | ✅ | 补齐 account/watch 流后恢复正常 |
| 设备配对 | ✅ | 真机 Android，配对码 → 设备 cookie → 免密进入 |
| WebSocket | ✅ | /m/api/remote.mux 剥前缀转发，会话流实时更新 |
| 公网隧道 | ✅ | 真 cloudflared 起隧道 → 公网 302 到配对页 → 配对 → 200 且前缀正确剥离 |
| Host 栅栏放行 | ✅ | 隧道域名可过；无关域名仍 400（开隧道不放宽边界） |
| 父死子亡 | ✅ | 强杀父进程后 8 秒内 cloudflared 自行消失，零孤儿 |
| 空闲超时 | ✅ | 到点自动关；持续 touch 可保活 |
| 单元 + 集成测试 | ✅ | 92 / 92 通过 |
| Agent 浏览器 | ❌ | 预期失败：需要 Electron 主进程 API |

验证方式：

全部单测 + 集成测试（用桌面自带的 Electron Node，PATH 里通常没有 node）
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" --test test/.test.mjs

真实隧道端到端（会真的连 Cloudflare，需要 tools/cloudflared.exe）
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" _probe/tunnel-e2e.mjs
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" _probe/full-chain.mjs
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" _probe/tunnel-ownership.mjs

8. 排障

| 现象 | 原因 / 处理 |
| 连不上、端口没监听 | enabled 还是 false。改了配置要重启 DSH，不要用插件重载 |
| 页面白板但 UI 在 | 某个 WebSocket 流被拒。看 ~/.dsh/remote-mobile/debug.jsonl 里的 ws-frame-denied |
| 会话全在「未分组」 | 同上，通常是 remoteAccess/follow 被拦 |
| 资源 404 | 地址少了尾斜杠，确认是 /m/ 不是 /m |
| 被弹回配对页 | 设备 cookie 过期或被撤销，重新配对 |
| 点「Agent 浏览器」报错 | 预期行为，见 §1 的能力表 |
| 开隧道报 rm/tunnel-no-binary | 找不到 cloudflared。放进 tools/，或配 tunnel.binaryPath，或装进 PATH |
| 开隧道报 rm/tunnel-no-listener | 手机同步没开。先开监听再开隧道 |
| 开隧道报 rm/tunnel-timeout | 90 秒内没拿到域名。多半是网络到 Cloudflare 不通，或被安全软件拦 |
| 公网打开是 400 | 隧道域名没进 Host 白名单。确认隧道状态是 running（面板上显示公网地址） |
| 公网打开超时 | 边缘还没铺开，等 30-60 秒重试；或隧道已因空闲超时关闭 |

日志位置：~/.dsh/remote-mobile/
- audit.jsonl —— 谁在什么时候访问了什么（只记元数据）；隧道开关记为 kind: "tunnel"
- debug.jsonl —— 路由、WS 帧、cookie 交换、cloudflared 输出等细节
- devices.json —— 设备表（只有哈希，没有明文 secret）

9. 开发

语法检查
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" --check lib/net/listener.js

单元测试
ELECTRON_RUN_AS_NODE=1 "C:\Data\APP\dsh\DeepSeek Harness.exe" --test test/.test.mjs

改 Host 代码之后：重启 DSH（不要只重载插件，见 §2 的配置陷阱）。

License

MIT