dsh-remote
Verified@zerorigin-studio/dsh-remote · v0.1.3 · MIT · Web UI
DSH desktop 插件:把进程内 Web GUI 反代到本机端口,配合 Go 隧道 agent 与 relay 服务器,让手机 App 远程操作电脑上的 DeepSeek Harness。
Install
dsh plugin add @zerorigin-studio/dsh-remote Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Readme
@zerorigin-studio/dsh-remote
在手机上远程操作电脑上的 DeepSeek Harness(DSH desktop)。
装进 DSH desktop 之后,插件在 DSH 进程内把 loopback 上的 Web GUI 反代出一个端口,电脑侧的隧道 agent 主动外连 relay 服务器,手机(或浏览器)经 relay 就能连回这台电脑。DSH 重启后自动恢复,不需要额外守护进程,电脑也不需要开放任何入站端口。
适用人群:在电脑上用 DSH 跑长任务、想离开工位后继续查看进度或发指令的 DSH desktop 用户。
架构
手机 App / 浏览器
│ HTTPS(邮箱验证码登录)
▼
relay 服务器(Go 二进制,公网,独立进程)
│ 反向隧道(WebSocket,电脑主动外连,心跳 25s)
▼
电脑侧 agent(插件按平台自动安装的二进制)
│ HTTP → 127.0.0.1:18090
▼
DSH 插件(本包,跑在 DSH desktop 进程内)
│ 改写 Host/Origin + 注入自签 cookie
▼
DSH desktop 的 webServer(127.0.0.1:<随机端口>)
三段各管一段:
- relay:账号体系、邮箱验证码、反向隧道入口和反代。支持多账号(SQLite
users表),一个账号可以挂多台电脑,在手机上切换。生命周期与 DSH 无关,跑在服务器上(或本机联调)。 - agent:电脑侧进程,由插件托管。主动外连 relay,把转来的请求发给本机插件;断了会重连。
- 插件(本包):在 DSH 进程内监听
127.0.0.1:18090,把请求转给 DSH 自己的 webServer,并为每个请求注入 browser-session cookie。
为什么必须是插件:DSH desktop 启动 webServer 时硬编码了 --host 127.0.0.1 --port 0,端口随机、只绑 loopback、launch token 只存在进程内存里。插件和 webServer 跑在同一个 Host 进程里,可以直接读到 ctx.webServer.port,因此不需要端口发现,桌面端重启换端口也不会失效。
插件同时是一个客户端插件:package.json 的 dsh.client 与 exports["./client"] 让 DSH 把 lib/client.js 注入 Web GUI,在设置 → 远程访问里多出一个条目。
前提条件
| 项 | 要求 |
|---|---|
| DSH | DSH desktop(插件跑在 DSH 进程内;CLI 的 dsh web 不适用) |
| 运行时 | Node >= 22.19(DSH desktop 自带;插件是纯 JS,无构建步骤、无第三方运行时依赖) |
| 服务器 | 一个可用的 relay。默认直接填作者维护的公共实例 https://dshmos.zerorigin.cn(手机 App 里也是默认值),用邮箱验证码登录即可;连不上、或想让数据完全由自己掌控,就用仓库 relay/ 自建(systemd 二进制部署包,或 docker compose) |
| 端口 | 本机 18090 空闲(可在 cordis.patch.yml 改) |
手机端用本项目的鸿蒙客户端(app/,需自行构建安装);也可以直接用浏览器打开 relay 域名,登录同一账号操作,效果一样。
安装
dsh plugin --profile desktop add @zerorigin-studio/dsh-remote
命令会把包装进 desktop profile,并自动把包名写进 profile 的 dsh.profile.bundles,不需要手工改 profile 的 package.json。
装完必须重启 DSH:cordis 不热重载 JS,插件条目只在 DSH 启动时装配。升级到新版本同理。
隧道 agent 二进制
电脑侧 agent 不放进主包,而是 5 个按平台区分的可选依赖包(见「平台支持」)。安装时 npm 会按当前 os / cpu 自动装一个,其余自动跳过——这是正常行为,不需要手动挑。
如果 agent 没装上(例如安装时用了 --no-optional,或在非常规环境里装),重装一次插件就会按当前平台补上。实在找不到(比如不在支持列表里的平台):自己编译一个 agent,把绝对路径写进 ~/.dsh/mobile-bridge/settings.json 的 agentCommand,改完重启 DSH。插件解析顺序是 agentCommand → 已装的平台包 → 仓库内 relay/bin,三者都没有才会报「没有找到 agent 可执行文件」。
设置页只留「这台电脑」和「账号」两张卡片;
agentCommand属于兜底配置,只在settings.json里手工改,界面上不再显示。
首次配置
- 重启 DSH 后打开 设置 → 远程访问(侧边栏,排在「插件」之后)。
- 「账号」卡片(未登录时):
- 插件默认就用作者维护的公共实例
https://dshmos.zerorigin.cn(手机 App 里也是默认值),不需要先填服务器地址,直接填邮箱即可; - 想换服务器点地址行右侧的「更换」:自建线上填
wss://你的域名,本机联调填ws://127.0.0.1:18099;换了地址要重新登录一次; - 邮箱 → 点「发送验证码」→ 填收到的验证码 → 点「登录并连接」。
- 登录成功后插件会自动拉起隧道进程;之后每次 DSH 启动、18090 绑定成功后也会自动接上(前提:已登录 + agent 可执行文件可用)。
- 服务器地址平时收成一行小字(只有空地址时才是输入框),避免在截图/投影里露出来;要换服务器点「更换」。
- 插件默认就用作者维护的公共实例
- 「这台电脑」卡片:填电脑名,这是手机「选择电脑」里显示的名字;留空 = 用系统主机名。改名会自动重启隧道,手机端会短暂显示「电脑离线」,随后换成新名字。
- 手机 App 用同一服务器 + 同一邮箱登录,选这台电脑开始用。
插件自己的数据落在 ~/.dsh/mobile-bridge/(设置了 DSH_HOME 时是 $DSH_HOME/mobile-bridge):
| 文件 | 内容 |
|---|---|
settings.json |
relayUrl / agentCommand / name(电脑名)/ bridgeToken(自动生成过入口 token 时才有) |
agent.json |
账号设备凭证(权限 0600,与命令行 agent -login 同构) |
agent.yaml |
每次启动隧道前按设置重新生成(含入口 token,权限 0600) |
这三个文件都是本机私密文件,不进 git,也不要贴到 issue 或截图里。
配置参考
发布版的默认配置(包内 cordis.patch.yml):
- insert:
- id: mobile-bridge
name: '@zerorigin-studio/dsh-remote'
config:
host: 127.0.0.1 # 只绑 loopback
port: 18090
token: '' # loopback 下默认空 token
| 字段 | 默认 | 说明 |
|---|---|---|
host |
127.0.0.1 |
发布版只绑 loopback:局域网、公网都连不进来,唯一入口是 relay 的反向隧道(agent 从本机连 18090)。要让同局域网设备直连,改成 0.0.0.0(或某块网卡的地址) |
port |
18090 |
插件监听端口。冲突就换一个;agent 侧的上游端口由插件自动写进 agent.yaml,不用手改 |
token |
空 | 入口 token。host 不是 loopback 时必须设一个随机长字符串(如 openssl rand -base64 32);空 token 只允许出现在 loopback 场景 |
文件位置:装好后在 <profile>/node_modules/@zerorigin-studio/dsh-remote/cordis.patch.yml(desktop profile 默认在 ~/.dsh/profiles/desktop/ 下)。注意这个文件属于 npm 包,升级会覆盖;改过的话升级后要重新改。
0.1.0 在检测到「非 loopback + 空 token」时会自动生成一个随机 token 并持久化到
settings.json,避免裸奔;但仍建议显式填写,方便自己掌握和更换。
改完重启 DSH 生效。
安全说明
默认只绑 loopback:电脑不开任何入站端口,外部唯一能进来的是 relay 反向隧道。这是默认推荐形态,不需要额外配置。
token 是第二道边界:token 非空时,除
/__bridge/health外的所有请求(包括 WebSocket upgrade)都要带下面任意一种,否则 401:Authorization: Bearer <token> ?token=<token> Cookie: dsh-bridge-auth=<token>转发给 DSH 之前会删掉
Authorization,入口 token 不会泄漏给 DSH 进程;上游的set-cookie也会被丢弃。手机端不需要 token:请求经 relay → agent,agent 转发时注入;手机只填服务器地址 + 邮箱。token 只存在于电脑本地,丢手机不等于丢电脑入口。
不要外泄凭证:
~/.dsh/mobile-bridge/agent.json(设备令牌)、agent.yaml(含入口 token)、settings.json都不要提交到 git、不要贴进聊天或截图。relay 的SESSION_SECRET/ SMTP 密码同理。把
host改成0.0.0.0等于在局域网里多开一个入口:谁能连上 18090 并拿到 token,谁就拥有这台电脑的远程执行权。不确定就别改;改了务必设 token,并确认所在网络可信。
故障排查
先做健康检查:
curl http://127.0.0.1:18090/__bridge/health
# {"ok":true,"auth":"open","upstream":"127.0.0.1:56295","listen":"127.0.0.1:18090"}
返回字段的含义:
| 字段 | 含义 |
|---|---|
ok |
插件和反代在跑 |
auth |
open = token 为空(loopback 默认,正常);required = 配了 token,但这次请求没带对(加 -H "Authorization: Bearer <token>" 再试);ok = token 校验通过 |
upstream |
DSH 自己 webServer 的真实端口(每次启动随机,不是错误信息) |
listen |
插件实际监听的地址,应与 cordis.patch.yml 的 host:port 一致 |
没有 auth 字段 |
跑的是没有鉴权的旧版代码:升级后重启 DSH |
常见问题:
| 现象 | 原因与处理 |
|---|---|
| 设置里没有「远程访问」 | 包没装上(profile 的 dsh.profile.bundles 里没有包名),或装完没重启 DSH |
| 连不上 18090(connection refused) | DSH 没启动;18090 被别的进程占用(换 port 后重启 DSH);插件加载失败(看 DSH 日志) |
| 手机登录后看不到这台电脑 / 一直「离线」 | 隧道没起来:账号未登录、没配服务器地址、agent 可执行文件缺失。看设置页账号状态;curl <relay>/__relay/status 里 agent.online 应为 true |
| 隧道反复断开 | settings.json 里的 agentCommand 路径不对;relay 地址写错;wss:// 证书无效(先用浏览器访问 relay 域名确认证书正常) |
| 手机打开页面 401 / 白屏 | 先看 /__bridge/health 的 auth;再确认手机登录的账号就是电脑上登录的账号 |
改了配置或 lib/*.js 不生效 |
重启 DSH(cordis 不热重载 JS)。只改 lib/client.js 时刷新页面即可(开发场景) |
| 端口被占用 | Windows:`netstat -ano |
日志在哪:
- 插件与隧道 agent:走 DSH 自己的日志输出(前缀
[mobile-bridge]/[agent]); - 自建的 relay:本机联调看
relay/data/relay.log;systemd 部署看journalctl -u dsh-relay -f;docker 部署看docker compose logs -f relay; - agent 最近 60 行:
curl http://127.0.0.1:18090/__mobile-bridge/status的agentLog字段(配了入口 token 时加?token=<token>)。
平台支持
电脑侧 agent 覆盖 5 个平台,各自一个可选依赖包:
| 平台 | 包 | 二进制 |
|---|---|---|
| Windows 10/11 x64 | @zerorigin-studio/dsh-remote-agent-win32-x64 |
agent.exe |
| macOS Intel | @zerorigin-studio/dsh-remote-agent-darwin-x64 |
agent |
| macOS Apple Silicon | @zerorigin-studio/dsh-remote-agent-darwin-arm64 |
agent |
| Linux x64 | @zerorigin-studio/dsh-remote-agent-linux-x64 |
agent |
| Linux arm64 | @zerorigin-studio/dsh-remote-agent-linux-arm64 |
agent |
主包通过 optionalDependencies 引入这 5 个包,npm 按当前 os / cpu 只装匹配的那一个,其余自动跳过(不是错误)。每个平台包只有一个 Go 静态编译的 agent 二进制(各平台 7–8 MB,npm 压缩包约 3 MB)。
没有对应包的平台:用仓库 relay/ 里的 cmd/agent 自行编译(CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -o agent ./cmd/agent),再把绝对路径写进 ~/.dsh/mobile-bridge/settings.json 的 agentCommand(界面没有这个输入框),重启 DSH 生效。
与官方 dsh-mobile-bridge 的区别
npm 上还有一个 dsh-mobile-bridge(发布者 dshapp),跟本包不是同一个实现,包名、配置和协议都不通用:
本包(@zerorigin-studio/dsh-remote) |
官方 dsh-mobile-bridge(dshapp) |
|
|---|---|---|
| 隧道 | 自有 relay + Go agent 反向隧道(WebSocket) | Noise 加密隧道 |
| 服务器 | 作者维护的公共实例 https://dshmos.zerorigin.cn,也可自建 relay(仓库 relay/,Go) |
官方方案自带/托管 |
| 手机端 | 本项目的鸿蒙客户端,或浏览器 | 官方客户端 |
| 组成 | 主包 + 5 个平台 agent 包 | 另一套 |
两个包不要同时装:它们各自会监听入口端口、各自拉起隧道,混装只会让排查变复杂。用哪个就只装哪个。
附录:本地开发模式(仅开发用)
线上安装一律走 npm。只有改插件源码时才用 link 安装:
dsh plugin --profile desktop add link:<仓库路径>/plugin
Windows 开发机上通常还会把插件目录 junction 到 profile 的 node_modules:
<profile>/node_modules/@zerorigin-studio/dsh-remote
→ <仓库路径>/plugin (desktop profile 默认 ~/.dsh/profiles/desktop)
以下三处要一起改,否则 DSH 下次启动加载不到插件:
- profile 的
node_modules下那条链接(junction); - profile
package.json的dependencies里指向仓库的link:绝对路径; - profile
pnpm-lock.yaml里对应的link:路径。
外加 dsh.profile.bundles 里要有包名。
开发时的生效规则:
- 只改
lib/client.js(设置页浏览器半侧):刷新页面即可,bundle 的rev由文件 mtime/size 派生; - 改其它
lib/*.js或cordis.patch.yml:必须重启 DSH; - 仓库里的
relay/、app/只用于本机联调,不包含在 npm 包里。