dsh-remote-ssh

@zhangfengshun/dsh-remote-ssh

English | 中文

类 VSCode Remote-SSH 的 DSH 插件：通过 SSH 连接远程超算 / 服务器，在 DSH 内置「文件」「终端」页签中直接操作远程文件和终端。

目录：功能 · 截图 · 安装 · 使用 · 代码示例 · 模型工具 · 命令超时与恢复 · 兼容性 · 故障排查 · 原理 · 缓存与一致性 · 许可证

功能

截图

设置 → 远程连接：连接配置（密钥 / 密码 / ProxyJump 跳板机）· 连接测试 · 从 ~/.ssh/config 一键导入

内置「文件」页签：直接浏览远程主机文件（右侧文件树即远程目录，编辑保存直写远程）

内置「终端」页签：自动 SSH 到远程超算（图为 SLURM 作业调度环境）；左侧会话即模型免填调用 remote_ssh_* 工具

安装

前置要求

一条命令安装（无需 token、API Key 或额外配置）：

dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.44

安装后重启 DSH。@zhangfengshun/dsh-remote-ssh 必须在 bundles 列表中排在 dsh-better-sidebar 之后。

只装本插件、不装 dsh-better-sidebar（或它加载失败）会怎样？ 2.4.18 起可以正常启动：客户端只把内核服务（slots/locale）声明为硬依赖，better-sidebar 改走子 fiber 软注入 —— 装了才注册远程文件编辑器页签，没装就静默降级。此时能用：设置页「远程连接」（SSH 连接与远程工作区）、模型工具（remote_ssh_*）、远程终端集成、@ 远程文件补全；不能用：「文件」页签的远程读写与编辑器页签 —— 那套 /sidebar/api/fs.* 通道属于 better-sidebar（内核原生侧边栏走的是它自己的 /api/*，本插件不接管）。1.0.0 之前的旧版插件在这里会永久 pending，前端直接报 web boot: 1 entry did not activate / pending (waiting for service: betterSidebar)（issue #18）。另外 better-sidebar 缺席时宿主会打一条 patch: entry "better-sidebar" not found 的 warn —— dsh-app-boot 对缺席的 patch 目标无条件告警，属正常，可忽略。

DSH 0.2.0-rc.1 起：装不上 / 插件列表里不出现？ 新版 harness 会按插件自己声明的 DSH peer 版本范围判定兼容性，范围覆盖不到当前运行时版本时会拒绝安装/激活（提示 Plugin … is incompatible with dsh <版本>），并在插件管理器里给你一个「接受风险」的逐版本豁免。2.4.16 起本插件的 peer 范围已显式列出所有已验证版本线（^0.1.0-rc.6 || ^0.1.5-rc.1 || ^0.1.7-rc.2 || ^0.2.0-rc.1），不需要任何豁免即可安装。若你用的是更早的插件版本，请升级而不是点"接受风险"。（判定是严格 semver：预发布运行时只被"版本线显式列出"的范围覆盖 —— 这也是为什么范围里要逐条列 0.1.5-rc.1 这类版本。）

卸载：

dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh

⚠️ dsh-better-sidebar 版本兼容性（2026-09 实测）：0.18.1 / 0.19.0 / 0.19.1 在 DSH Desktop v2.0.9（DSH 0.1.5-rc.1）上主机半边无法加载（它们以值方式导入 SessionLogOffset，桌面版模块面只提供该类型声明）→ 侧边栏文件页签显示「这类内容还没有可用的查看方式。」。请使用 0.18.0，或使用已修复该导入的构建；本插件对 0.18（4 端点）与 0.19（6 端点，含 fs.rename/fs.remove）两套契约均已适配。

使用

三步上手

1. 设置 → 远程连接 → 添加连接（主机 / 端口 / 用户 / 密钥）→ 点「测试连接」验证；已有 ~/.ssh/config 可直接一键导入
2. 添加工作区 → 选「选择远程目录…」→ 选连接 → 浏览并选择远程目录（该目录会成为原生 DSH 工作区）；目录还不存在时点「📁 新建目录」就地创建（本地 / 远程 tab 均支持），创建后自动进入新目录
3. 进入该工作区会话：内置「文件」页签直接显示远程文件（编辑保存直写远程），「终端」页签自动 SSH 到该工作区的远程目录（仅密钥认证）

会话内直接对模型说（远程工作区会话中免填连接参数）：

看看 /home/user/project 下有什么，然后把 train.py 的第 20 行改掉
跑一下 squeue -u $USER，把排队情况整理成表格
把这个目录的 *.log 里含 ERROR 的行抓出来

代码示例

示例 1 · 执行远程命令（remote_ssh_exec，默认 120s 超时）：

{
  "command": "sinfo -h -o '%P %a %D %t %N' | head -20",
  "timeoutMs": 30000
}

返回 { ok, exitCode, stdout, stderr, error, truncated, isTimeout }——例如：

{ "ok": true, "exitCode": 0, "stdout": "cpu* up 12 idle 8 ...\n", "stderr": "", "error": "", "truncated": false, "isTimeout": false }

示例 2 · 文件读写（无需同步）：

{ "path": "~/project/config.yaml", "content": "lr: 0.001\nepochs: 50\n" }

{ "path": "~/project/train.py" }

remote_ssh_cat 走 base64 传输（二进制安全），remote_ssh_write 为原子写入（写临时文件再 rename）。

示例 3 · 长时任务与挂起恢复（构建 / 训练显式放宽，卡住可强杀会话）：

{ "command": "cd ~/project && bash run_train.sh", "timeoutMs": 0 }

{ "all": true }

timeoutMs: 0 禁用本次超时；环境变量 DSH_REMOTE_SSH_CMD_TIMEOUT_MS=600000 可改全局默认。超时后池化会话自动丢弃重建，remote_ssh_kill 是随时可用的手动兜底。

远端语义（2.4.44 起写清）：timeoutMs 只是本地等待预算 —— 到点只放弃等待并丢弃会话，不会终止远端命令（远端进程可能继续运行，输出不再回传；断开连接 / 退出 DSH 同理）。需要远端硬时限请用远端自己的 timeout <秒> <命令>。按停止键取消与 remote_ssh_kill 才代表「终止」：插件会给远端 shell 所在的进程组发 SIGHUP（最多等 4s；与关终端同义，nohup / setsid 起的任务不受影响）。

示例 4 · 远程工作区内的工具调用（免填 profileId，相对路径基于工作区远程目录）：

{ "path": "configs/exp1.yaml" }

示例 5 · 从 ~/.ssh/config 导入连接：设置 → 远程连接 → 「导入 SSH config」→ 勾选主机 → 自动填充 host / user / port / keyPath / ProxyJump。

示例 6 · 本地镜像同步与回推（离线批改后再一次性上传）：

{ "workspaceId": "w_xxx" }

{ "workspaceId": "w_xxx" }

remote_ssh_sync 把远端拉进本地镜像目录，remote_ssh_push 把镜像改动推回远端（tar over ssh，批量高效）。

2.4.20 起同步是「有门槛的整树操作」，顺序固定为 体积哨兵 → 解包到临时目录 →（整树时）比对「只存在于镜像的文件」→ 原子替换，任何一步失败都不碰旧镜像：

在 GitHub 閱讀完整 README →