dsh-remote-control

dsh-remote-control

DeepSeek Harness（DSH）的远程控制插件：手机扫码、在电脑上确认后，用手机浏览器继续自己电脑上的会话、处理审批、查看文件和管理设置。电脑上的桌面应用和 dsh web 界面保持原样。

功能

安装

DSH 桌面版：插件 → 添加插件，输入 @copylee/dsh-remote-control，安装后启用。

命令行（dsh web 等其他 profile）：

dsh plugin --profile web add @copylee/dsh-remote-control@latest

桌面应用和 dsh web 使用各自的 profile，需要分别安装。

要求：自插件 0.2.8 起，DSH 最低版本为 0.2.1-rc.2，Node.js 22.19+ 或 24+。“任意网络”需要电脑能访问 Cloudflare；手机不需要代理。

手机默认界面可在「设置 → 远程控制 → 手机连接后使用的界面」选择，刷新手机页面后生效，无需重新配对。自定义界面的设置页及错误提示提供「打开原生界面」。也可在已配对的网关地址后加 /?ui=native 临时打开原生界面，或用 /?ui=custom 返回自定义界面；临时切换不修改默认选项，两种界面使用相同的配对和撤销权限。

使用

点击左侧栏底部的手机图标，或打开 设置 → 远程控制。

1. 选择“同一 Wi‑Fi”或“任意网络”，点击“开启远程连接”。“任意网络”首次开启会下载 Cloudflare 的连接组件，并在确认公网地址可用后才显示二维码。
2. 用手机扫描二维码，或打开复制的链接。
3. 电脑上弹出配对请求，确认设备名称后点“允许连接”。
4. 手机进入远程界面。

二维码只用于配对新设备，有效期 5 分钟，点击二维码可以刷新；已配对的手机不受二维码过期影响。

配对后是否需要重新扫码：

• “同一 Wi‑Fi”：授权保存在手机浏览器里，电脑重启连接后会尽量沿用上次的端口，手机打开原地址即可继续使用；连续 30 天不使用后授权过期。
• “任意网络”：每次开启都会换一个新地址，浏览器不会把旧地址的授权带到新地址，所以需要重新扫码并在电脑上确认。关闭连接时，这类设备记录会自动清除。

“关闭远程连接”会断开所有手机并保留“同一 Wi‑Fi”设备的授权；“撤销”立即断开对应设备并使其授权失效。已连接时改用另一种连接方式会先询问，确认后才断开当前连接。

连接不上时

• “任意网络”开不起来：先确认电脑能访问 Cloudflare。面板的“电脑访问外网的代理”默认不使用代理；直连不通时可改为“自动检测系统代理”或手动填写 HTTP(S) 代理地址（不接受带用户名密码的地址）。走代理反而连不上时改回“不使用”。仍不行可把线路换成 localhost.run。
• “同一 Wi‑Fi”打不开：确认手机与电脑在同一网络、路由器没有开启客户端隔离、手机没有开 VPN。Windows 防火墙可能拦截网关端口，需要在“Windows Defender 防火墙（高级安全）→ 入站规则”里手动允许面板显示的端口（TCP，建议限制为专用网络）。插件不会修改系统防火墙。

设置

安全说明

• 已授权的设备与电脑本机权限相同，可以管理设置、凭据和插件。只批准自己信任的设备。
• “任意网络”的 HTTPS 在 Cloudflare 边缘终止，本插件不提供端到端加密。“同一 Wi‑Fi”使用 HTTP，应只在可信网络中使用。
• 手机访问的是插件自己的认证网关，而不是 DSH 的端口。未配对的设备只能打开配对页，读不到任何宿主数据；网关在内部换用宿主凭据，原始凭据不会发给手机。
• 最多保存 32 台设备，超出时淘汰最久未使用且不在线的一台；同时最多等待 16 个配对请求。
• 关闭连接或撤销设备会立即中断对应的 HTTP、WebSocket 和 SSE 连接。

数据与隐私

• 授权与偏好保存在 $DSH_HOME/dsh-remote-control/<profile>/（未设置 DSH_HOME 时为 ~/.dsh）。设备文件只保存随机密钥的 SHA-256 校验值、设备名称和时间，不保存密钥本身。
• “任意网络”的流量经过 Cloudflare（或 localhost.run）的服务器转发；“同一 Wi‑Fi”的流量不出局域网。
• 插件不收集、不上传使用数据。

工作原理

手机浏览器
   │  HTTPS（任意网络：Cloudflare Quick Tunnel / localhost.run）或 HTTP（同一 Wi‑Fi）
   ▼
认证网关（本插件，独立端口）  配对、设备 cookie、来源检查、限速
   │  回环地址，换用宿主凭据
   ▼
DSH Host 的 Web 服务  /api/remote.mux（WebSocket）、/plugins/*、文件接口

• 手机界面是随插件发布的独立前端：它启动宿主的客户端服务来读写会话和设置，界面本身由插件渲染。
• Cloudflare Quick Tunnel 不支持 SSE，远程引导脚本把宿主的 /plugins/events 事件流改由 WebSocket 传输，保留事件顺序、Last-Event-ID 和重连。
• 第三方插件的设置页通过兼容容器显示，涉及 DSH 内部渲染接口；宿主升级改变该接口时，对应页面会提示不可用，其余功能不受影响。0.2.8 的客户端运行时及内置原生前端已对齐 0.2.1-rc.2。

更多细节见 功能对应清单、验证记录、调研记录 和 UI 规格。

开发

pnpm install
pnpm typecheck
pnpm test          # vitest：网关、配对、宿主集成
pnpm build
node scripts/check-package.mjs   # 检查打包内容

pnpm qa:host 在仓库的 .qa/ 目录里启动一个隔离的 DSH Web profile，不触碰日常使用的 DSH 配置；pnpm qa:browser 用本机 Chrome 跑完整回归（配对、会话、文件、设置、撤销）。回归使用的测试模型只返回固定内容，不发出外部请求。

本地联调：DSH 桌面版“添加插件”里填本仓库目录路径（以 link 方式安装），pnpm build 后重启 DSH 生效。

致谢

实现时参考了 dsh-remote-web-ui、DSH Remote 和 untun。本项目为独立实现，不使用这些项目作者的中继服务。

许可证

MIT