@zhangfengshun/dsh-remote-ssh

English | 中文

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

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

功能

能力	说明
🔌 SSH 连接	密钥 / 密码认证，ProxyJump 跳板机，~/.ssh/config 一键导入
📂 远程文件	内置「文件」页签直接 SSH 读写远程文件，无需同步
💻 远程终端	内置「终端」页签自动检测远程工作区，SSH 交互式终端，落在工作区对应的远程目录（与 VSCode Remote-SSH 一致）
🌐 远程工作区	选择远程目录创建原生工作区，一键进入远程环境
🤖 模型工具	13 个 remote_ssh_* 工具，会话感知免填连接参数；命令级超时 + remote_ssh_kill 兜底恢复
🗂️ @ 引用补全	远程工作区会话里 @ 补全列远端文件（git 仓库走 git ls-files，实测 0.1s；非 git 用有界 find；索引缓存 + 900ms 查询预算，超时降级不卡输入框）
⚡ 打开提速	单往返合并读 + raw 文本快路径 + 结果缓存（LRU + 5s TTL）：首开 ≈1.31×，TTL 内重复打开 0 往返，过期复验 ≈5×（真实超算实测）；remote_ssh_exec 连接复用 ≈15×

截图

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

<p align="center"><img src="assets/settings-remote-connections.png" width="420" alt="设置：远程连接"></p>

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

<p align="center"><img src="assets/remote-files-tab.webp" width="820" alt="内置文件页签直接浏览远程文件"></p>

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

<p align="center"><img src="assets/remote-terminal.webp" width="820" alt="内置终端页签自动 SSH 远程超算"></p>

安装

前置要求

项	要求
DSH	≥ 0.1.5-rc.1，含 0.2.0-rc.1（最新官方线；0.1.2 稳定线请用 v0.18.1 时代的插件版本）。插件声明的 peer 范围显式列出每条已验证版本线，因此新版 harness 的兼容性门（见安装）不会拦住它
dsh-better-sidebar	≥ 0.15（本插件依赖其 /sidebar/api/ 文件 API 与 0.24 的 open.external「打开方式」端点；0.23 起文件树改为批量 fs.trees 并新增 fs.mkdir，2.4.18 起已适配）。可以只装本插件：2.4.18 起未安装它时不再卡住 web boot（见下方说明），但「文件」页签的远程读写与编辑器页签也随之不可用
本机 SSH 客户端	Windows：系统自带 OpenSSH（%SystemRoot%\System32\OpenSSH\ssh.exe）；Linux/macOS：openssh-client
远程主机	任意标准 sshd（超算 / 服务器 / 跳板机均可）

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

dsh plugin --profile <name> add @zhangfengshun/[email protected]

安装后重启 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

…