dsh-remote-go
Manifest validDSH plugin: Use a remote DSH (thin client) in a full-page local DSH global panel over SSH
dsh-remote-go
在本地 DeepSeek Harness(DSH)里,通过 SSH 使用服务器上的 DSH:接管时远端界面铺满整个窗口,本地侧边栏让位;本地与远端的侧边栏顶部都有同一条主机条——列出「本地」和每台远端主机,点哪个就切到哪个。本地只负责连接与状态。
English — dsh-remote-go opens a remote DSH from your local DSH over SSH: the desktop shell renders the remote web UI as a full-window browser guest, the browser build carries the same UI in a same-origin frame fed by a local reverse proxy, and one host switcher ("Local" + every host) sits at the top of the sidebar on both sides; no iframe on desktop, no second window. Current version 0.1.0 (unpublished).
文档
设计 docs/design.md(职责边界、界面、连接生命周期、运行时与安全)· 代码地图 docs/implementation.md · API 契约 docs/api.md(v2.8)· 发布流程 docs/publish.md · 远端测试环境 e2e/remote/README.md · 变更记录 CHANGELOG.md
它是什么
- 一个 DSH 插件,主机入口只有侧边栏顶部的主机条(设置面板不注册入口):状态点 + 当前目标名,点开是「本地」+ 每台远端主机的列表。它用页面自己的主题变量绘制,跟随字体、hover 与弹层遮罩;侧边栏收起成窄条时自动隐藏。本地页面与远端页面各有一份:本地那份列全部主机;远端页面里的那份只列「本地」+ 当前主机,跨主机切换要先点「本地」。
- 接管后看到的是远端 DSH 自己的完整 Web 界面,桌面端与浏览器端都能用:桌面端用 Chromium guest 铺满整个窗口(远端页面自己让出桌面标题栏那一条,与本地同一套栅格,行高、留白与浮层位置一致);浏览器端(
dsh web)用一个同源 iframe,由本机 DSH 上一条只服务已连接主机的反向代理喂页面。本地侧边栏在接管期间隐藏,窗口里只有远端那一条侧边栏;没有第二个浏览器窗口、没有浮层胶囊或「在新窗口打开」。 - 已连接的远端前面是绿色发光的点;没连接的点一下浮出连接窗口:上半是分阶段进度(指纹确认、密码也在这里),下半是这台连接的日志(SSH / npx / 远端启动逐行打印,自动跟随,可往上翻);连上就自动接管整窗,失败时错误和日志留在窗口里。已连接的主机行悬停时右侧出现「断开」,只断那一台。
- 切回已打开过的远端不重新加载:每台主机的远端窗口保持热态(不设数量上限),切走只是隐藏;断开或删除主机才真正释放。本地只做连接与承载:主机清单、SSH 连接与隧道、整窗接管、连接状态与诊断,以及用户手势触发的远端文件 SFTP 转发。
- 远端文件与文件夹下载:在远端 Files 面板右键文件选「下载」;文件夹右键菜单会多出「下载到本地」。点击后先选一个本机保存目录,Host 用同一条 SSH/SFTP 连接流式写入:文件写入
<目录>/<文件名>,文件夹新建同名目录后逐个文件写入;同名文件或文件夹自动加(2)。不打包 ZIP、不限文件大小或数量;右下角显示可拖动的进度卡(标题栏拖动、可取消)。
用法(本地 ↔ 远端)
- 进远端:点主机条 → 选一台已连接的主机(绿点发光)→ 远端界面接管整个窗口。
- 换远端 / 连新的:在本地页面的主机条里直接点另一台,没连接的会先浮出连接窗口显示进度与连接日志,连上后自动接管;如果人已经在远端界面里,先点「本地」再选(远端那份行只显示「本地」+ 当前主机)。点列表最下面的「添加主机」填一次 SSH 信息:点「连接」保存并立即连上去,点「保存」只把配置记下来;没有单独的「连接测试」步骤。
- 管主机:点「管理界面」浮出主机清单,编辑 / 诊断 / 重连 / 删除都在那里;已连接的卡片上还有「重启远端 DSH」与「关闭远端 DSH」。两者都是浮窗,远端开着时背景仍是远端,关掉回到原来那一页。
- 断开 / 回本地:悬停已连接的主机点「断开」,只断那一台;点「本地」回到本地页面,SSH 连接与远端任务都不停,随时可以再切回去。
- 下载远端文件或文件夹:在远端 DSH 的 Files 面板右键文件 →「下载」,或右键文件夹 →「下载到本地」;先选择本机保存目录,Host 会流式写入文件或新建同名文件夹(重名自动加
(2)),不经过 Blob 或 ZIP。 - 重启远端 DSH:主机清单里点已连接卡片上的「重启远端 DSH」,Host 用同一条 SSH 会话停掉自己拉起的远端进程、重新
npx启动,再按新端口重建隧道并把界面接回去——不重跑 SSH / 探测 / 自举,不会再次索要密码或主机指纹;远端开着时承载方会在完成后自动重新导航。旧 token 与地址随之失效。只会在「进程确实是本连接启动的」前提下停止它(registry 命名 + 本连接启动过 +/proc启动时刻未变);重挂发现的进程、pid 复用与alongside保留的进程都不会被自动 kill,手工实例走冲突提示。 - 关闭远端 DSH:主机卡片上的「关闭远端 DSH」会先弹确认框(这是破坏性操作),确认后 Host 在同一条 SSH 会话上停掉本连接绑定的那一个远端进程(同样要求 registry 命名 +
/proc启动时刻未变,重挂接管的实例也可以关,alongside保留的进程不杀),然后关隧道、释放 SSH,主机回到「断线」——配置与凭据都保留,不会自动重连,点「重连」就会起一个全新的实例(新端口、新 token)。远端run/web.json随停止一起清掉,所以重连不会误弹「远端已有手工启动的 DSH」。
远端自己重启(例如在远端插件市场更新插件):启动命令固定
--port 0,所以重启后端口一定变化。插件会对已连接主机做轻量探活(默认 30s,可在设置里关闭,保存即生效),代理/隧道失败也只当作「疑似」;连续两次探活失败才判定远端确实不可用,然后重读远端真实状态(新的dsh web:行或该进程在/proc的监听端口),并要求「同一 profile、同一~/.dsh、端口属于该 pid、最新就绪行给出新的 launch token」同时成立才接管——拿不到 token 不会假装成功。接管会刷新远端run/web.json、关旧隧道并按新端口重建、重新换 token,最后静默重载界面。重挂期间显示「远端 DSH 正在重启」,不会弹「连接断开」;确实没有可重挂实例时停在可解释的remote-unreachable错误上,主机与配置保留,可点「重启远端 DSH」或「重连」(这一状态会保留 SSH 会话,所以重启不需要重新认证)。远端健康而只是隧道的本地监听坏了时,插件先直接请求本地 listener:仍应答就不动,不应答才重建(先建新、再关旧,失败退避),重建后界面承载方会按新的本地端口重新导航(现有 WebSocket/下载会短暂断开);重挂发现的监听进程没有 kill 权,点「重启远端 DSH」会先弹 stop/alongside/cancel 提示,不会静默启动第二个实例。
AI 工具(在本地会话里查看主机)
本地 DSH 的 LLM 会话能直接看到已配置的主机与它们的连接状态,不必让用户先去点主机条。插件在 Host 半端 注册一个工具;远端 DSH 不加载本插件,所以远端会话看不到它,也没有新增任何 HTTP 路由。
| 工具 | 类型 | 参数 → 返回 |
|---|---|---|
remote_hosts_list | 只读 | includeDisconnected(默认 true)→ {ok, hosts[], count, connected, truncated?, error?}(最多 500 行),每行 id / label / state / connected / address / lastError / progressCode / remoteVersion |
- 只读:工具没有增删改与连接动作,维护主机仍然在主机条的「添加主机 / 管理界面」里。因为它不改变任何
状态,也就不需要审批或
confirm门。 - 返回值不含凭证:只做字段白名单投影(
redactText脱敏 + 按字段截断),密码、token、cookie、指纹原文和 私钥路径都不会出现在结果里——连接失败的原因原文里带的SHA256:…指纹与密钥文件路径(.ssh下路径,以及.pem/.key/.ppk或id_*命名的密钥文件)会被替换成<fingerprint redacted>/<private-key path>;output.schema声明additionalProperties: false,投影里多一个字段会让调用失败而不是 漏出去。投影先按字段上限切输入再脱敏,超长字段不会拖慢宿主。 - 缺
tools服务的宿主不受影响:工具是可选注册(ctx.inject,服务被替换后会重新注册),取不到tools就只少这一个工具,主机条与本地 API 照常工作。 - 结果里的主机名、远端版本与错误文本属于不可信数据:只当数据引用,不要当成指令执行。
安装与首次连接
dsh plugin --profile web add /absolute/path/to/dsh-remote-go # 本地目录(开发 / 自用)
pnpm pack && dsh plugin --profile web add ./dsh-remote-go-0.1.0.tgz # 按发布物验证
发布到 npm 后可用 dsh plugin --profile web add dsh-remote-go(当前尚未发布);也可在 Settings → Plugins 里以插件包目录安装。安装后刷新页面,侧边栏顶部出现主机条。
- 点主机条 →「添加主机」→ 向导浮在当前页面上;填 SSH 地址或
~/.ssh/config别名,选私钥文件(默认已填~/.ssh/id_rsa,可点「选择文件…」浏览)或一次性密码;可选跳板机。存活策略与指纹策略在底部的「高级选项」里。 - 点「连接」:首次连接在连接窗口里确认主机指纹(可「接受并记住」),下面的日志会实时显示正在做什么。
- 插件探测远端环境,在
~/.dsh/remote-go/node准备自己用的 Node(缺失或版本不符时自动下载安装),再用npx固定本机版本启动远端 DSH(首次运行还会把 DSH 下载进 npx 缓存,进度会显示在连接进度里),等待进入「已连接」。 - 点主机条里的那台主机:远端 DSH 接管整个窗口,本地侧边栏让位,同一个主机条出现在远端侧边栏顶部;点「本地」回来。远端那份行只列「本地」+ 当前主机,换主机先回本地。关闭视窗只关闭本地承载,远端任务继续(按主机的存活策略)。
远端运行时与兼容
远端运行时只有一种形态:插件自带的 Node + npx 拉起与本机完全相同版本的 DSH。远端系统里有没有 Node、装的是哪个版本都不影响它——插件只用自己的那一份,避免和远端其他项目、nvm 或包管理器互相干扰。
| 前提 | 说明 |
|---|---|
| Linux 远端 | 只支持 Linux;Windows / macOS 远端待后续版本 |
| 能访问 nodejs.org(或 npmmirror.com)与 npm registry | 首次连接下载 Node 官方 Linux 构建(.tar.gz,约 50 MB),解压到 ~/.dsh/remote-go/node/v<version>;第一次运行把 @deepseek-ai/dsh@<本机版本> 下载进 npx 缓存,之后走缓存 |
| 约 400 MB 可用磁盘 | tarball、解压后的 Node 与临时目录 |
| curl 或 wget | 下载 Node,以及启动后对 127.0.0.1:<port> 的界面探活 |
连接时实际执行的命令是固定的:
env DSH_HOME=~/.dsh PATH=~/.dsh/remote-go/node/v<version>/bin:"$PATH" \
~/.dsh/remote-go/node/v<version>/bin/npx -y @deepseek-ai/dsh@<本机版本> --profile <profile> --no-open --port 0
- 托管 Node 固定版本:要装的版本 = 本机 DSH 自己声明的
engines.node下限(当前>=24.9.0→ Node 24.9.0),随插件读取、不追最新补丁, 已装同一版本就复用;下载前校验官方SHASUMS256.txt的 SHA-256 才解压,nodejs.org 不可达时回退 npmmirror.com 的同一版本。永远不修改系统 Node、不需要 root;没有系统 Node 兜底。 ~/.dsh是远端用户真实的 DSH 主目录:凭据、会话、插件配置就是该用户自己的那一份,插件不复制、不隔离。插件自己的文件固定在~/.dsh/remote-go/(不是设置项):logs/web.log、run/web.json、node/、downloads/。profile可配:设置项bootstrap.profile(默认web);desktop留给桌面端,不能选。- 连接前先预检:托管 Node 就绪后,用它的
npx -y @deepseek-ai/dsh@<本机版本> --version在前台跑一次(冷缓存下载就发生在这里),回读版本必须与本机一致, 否则直接version-mismatch失败。下载不到 Node(网络 / 磁盘 / 架构 / musl / glibc 过低,官方构建要求 glibc ≥ 2.28)、npx 拉不到本机版本、回读版本不一致,都会停在可解释、可重试的错误上。 - 兼容性由
package.json的engines.dsh(>=0.2.2-rc.3:界面统一注册在shell.overlay插槽)与engines.node(>=24)声明。远端一律由npx按本机版本拉起,所以本机 DSH 版本必须已发布到 npm,插件与 远端 DSH 版本恒等。变更记录见 CHANGELOG.md。
安全
- 远端界面只绑
127.0.0.1,经 SSH 隧道访问;本地也不监听公网。 - 浏览器端的同源代理只服务
connected主机的回环隧道,只接受同源请求;远端的 session cookie 只存在 Host 的 per-host cookie jar 里,不交给浏览器,本地 DSH 的 cookie 也不会转发给远端。 - SSH 密码默认只用于本次连接(内存);勾选保存后写入 DSH 凭据存储(插件自有记录空间,不进
hosts.json),其保护强度由 DSH 的凭据实现决定,插件不额外加密。 - 主机指纹首次确认、变化强提示;诊断导出默认脱敏(token / 密码 / 私钥 / 家目录)。
- 本地 HTTP API 与同源代理的每条请求都先过本机 DSH 自己的准入(
Host/Origin栅栏 + 浏览器会话), 与 DSH 自带路由一致;之后再要求同源 + 自定义请求头(x-dsh-remote-go)。Host必须是本机 origin, 所以 DNS rebinding 的页面(Host是攻击者域名)和任何跨站请求都被拒绝。 - 操作都在远端执行;首次进入提示「你正在操作远端服务器」,关闭时提示「远端任务会继续运行」。
发现安全问题请不要公开提交 issue,通过 GitHub Security Advisory 私密报告。
开发与测试
前置:Node ≥ 24、pnpm ≥ 11(版本见 packageManager 字段)。
pnpm install --frozen-lockfile --ignore-scripts # 不执行生命周期脚本
pnpm run verify # 仓库规范 + 格式 + 语法 + workflow + 市场条目 + 打包 + 覆盖率 + 单测 + 集成
| 命令 | 作用 |
|---|---|
pnpm run test:unit | 单元测试(Host + Client + 同源远端代理),不需要网络 / SSH |
pnpm run test:integration | 全量集成 / E2E(本地开发用;缺 harness 时跳过,DSH_E2E_STRICT=1 下改为失败) |
pnpm run test:integration:local | 无外部依赖组:模拟远端、重启、关闭远端(CI / release 共用) |
pnpm run test:integration:external | 需 harness + 浏览器组:同源代理、dsh web、浏览器载体、guest 工具、关闭远端的浏览器流程(CI / release 共用) |
pnpm run test:coverage | 覆盖率门禁:src/ 聚合阈值 85 / 70 / 80(不含 vendor/ 与 test/),外加 client.js 与 local-ssh / local-download 的 per-file 下限 |
pnpm run test:web / test:desktop | 打包产物验收:隔离 dsh web / 真实桌面端安装 tarball、打开管理浮窗、浅/深色对比度与第三方主题 |
pnpm run sim:remote | 模拟远端主机自检(探针 → 隧道 → HTTP 200) |
模拟远端主机(e2e/sim,不需要真实服务器):
pnpm run sim:remote
node e2e/sim/simulated-remote.mjs --serve --state-file <file>
它用 ssh2 在本机起一个真实 SSH 端点(回环地址、默认凭据,可用 --ssh-user / --ssh-password 覆盖),并只允许转发到自己的端口。运行参数见 e2e/sim/simulated-remote.mjs 开头的用法说明。
test:integration 聚合所有集成 / E2E 文件;缺 harness / 浏览器时它们默认跳过。PR 的 ci.yml 与 release.yml
都用 package.json 里的两个显式清单(test:integration:local / test:integration:external)并把
DSH_E2E_STRICT 置为 1,所以门禁上不会静默跳过:无外部依赖组(sim / remote-restart / stop-remote)直接跑,
外部依赖组(remote-proxy / web / browser-carrier / guest-tools / stop-remote.browser)在安装 DSH harness
与 Chrome 后跑;桌面端 E2E 需要真实 Electron 安装包,只在夜间 acceptance.yml 跑。
*.md 在 .prettierignore 中有意排除:文档是手工折行的,交给 Prettier 会整体重排;CI 仍校验代码、YAML 与 JSON
的格式。提交前可启用仓库自带的 hook(运行仓库规范与格式检查):
git config core.hooksPath .githooks
CI 与发布
| 工作流 | 触发 | 内容 |
|---|---|---|
ci.yml | push main / PR / 手动 | PR 门禁:Verify(仓库规范 + 格式 + PR 标题 + 覆盖率 + 严格模式 E2E + tarball)、Tests(Windows 规范/格式/语法/workflow + 单测 + 无外部依赖集成);CodeQL 是独立必需检查(codeql.yml) |
acceptance.yml | 夜间定时 / 手动 | 真实浏览器验收:dsh web、同源 iframe / 桌面载体、真实桌面端(非门禁),失败上传截图与日志 |
release.yml | push release 分支 / 手动 | 与 PR 相同的 gate + 严格集成两组(装 harness / Chrome)→ 打包 → 发布 npm → 创建 GitHub Release |
发布前请本地跑一遍 pnpm run verify;完整步骤见 docs/publish.md。
已知限制
- 不做沉浸模式、本机通知、多窗口分屏、远端设置 diff / 备份管理。
- AI 工具只有只读的主机列表:增删改、连接 / 断开、重启或关闭远端 DSH 都要用户在界面里操作。
- 不修改远端 DSH 的配置、插件、凭据与会话:它们都由远端自己维护,本插件只负责连接与呈现;插件自己的运行文件固定在远端的
~/.dsh/remote-go/(日志、run registry、托管 Node、下载暂存),不复制、不隔离远端 DSH 的数据目录。 - 远端仅支持 Linux,首次连接需要能访问 nodejs.org(或 npmmirror.com)与 npm registry,没有离线包;官方 Node 构建要求 glibc ≥ 2.28,musl(如 Alpine)会明确失败。
- 托管 Node 是唯一运行时:系统 Node 永远不参与,装不上时连接明确失败、不会降级;远端 DSH 版本恒等于本机版本(本机版本必须已发布到 npm)。
- 不迁移旧版的独立状态目录(
~/.dsh-remote-go):升级后插件文件固定在~/.dsh/remote-go。插件只收养自己启动的远端实例;远端已有手工启动的 DSH 时连接会暂停并列出这些进程,由你选择「停止它并启动受管实例」「保留它,另起一个」或「取消连接」。 - 远端界面只能整窗接管:桌面端用 Chromium guest,浏览器端(
dsh web)用同源 iframe + 本地反向代理; 页面经file://加载且没有桌面桥时没有远端呈现方式。多台远端在同一时刻只能呈现一台。 - 浏览器端的远端文件夹下载需要页面能拿到本机目录(DSH 的目录选择器);拿不到时在下载入口提示,不静默改写到别处。
- 浏览器端依赖远端页面使用相对路径;远端第三方插件若硬编码根路径资源,可能只在桌面端完整可用。
- 刷新本地页面后主机条会重新出现,点那台主机即可再次接管(远端任务不受影响);修改 Host 插件代码需重启本地 DSH 生效(Client 半端随页面刷新加载)。
License
MIT © dsh-remote-go contributors
Comments
Loading…