Skip to content

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 里手工改,界面上不再显示。

首次配置

  1. 重启 DSH 后打开 设置 → 远程访问(侧边栏,排在「插件」之后)。
  2. 「账号」卡片(未登录时):
    • 插件默认就用作者维护的公共实例 https://dshmos.zerorigin.cn(手机 App 里也是默认值),不需要先填服务器地址,直接填邮箱即可;
    • 想换服务器点地址行右侧的「更换」:自建线上填 wss://你的域名,本机联调填 ws://127.0.0.1:18099;换了地址要重新登录一次;
    • 邮箱 → 点「发送验证码」→ 填收到的验证码 → 点「登录并连接」。
    • 登录成功后插件会自动拉起隧道进程;之后每次 DSH 启动、18090 绑定成功后也会自动接上(前提:已登录 + agent 可执行文件可用)。
    • 服务器地址平时收成一行小字(只有空地址时才是输入框),避免在截图/投影里露出来;要换服务器点「更换」。
  3. 「这台电脑」卡片:填电脑名,这是手机「选择电脑」里显示的名字;留空 = 用系统主机名。改名会自动重启隧道,手机端会短暂显示「电脑离线」,随后换成新名字。
  4. 手机 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 下次启动加载不到插件:

  1. profile 的 node_modules 下那条链接(junction);
  2. profile package.json 的 dependencies 里指向仓库的 link: 绝对路径;
  3. profile pnpm-lock.yaml 里对应的 link: 路径。

外加 dsh.profile.bundles 里要有包名。

开发时的生效规则:

  • 只改 lib/client.js(设置页浏览器半侧):刷新页面即可,bundle 的 rev 由文件 mtime/size 派生;
  • 改其它 lib/*.js 或 cordis.patch.yml:必须重启 DSH;
  • 仓库里的 relay/、app/ 只用于本机联调,不包含在 npm 包里。