@zhangfengshun/dsh-remote-ssh
DSH Web 插件：类似 VSCode Remote-SSH 的远程开发功能（通过 SSH 连接超级计算机/服务器、远程工作区、文件资源管理器、集成终端），与 dsh-better-sidebar 和 DSH 设置集成。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @zhangfengshun/dsh-remote-ssh@2.4.12
Remote Ssh 以 @zhangfengshun/dsh-remote-ssh 发布，当前版本为 2.4.12。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
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 一键导入
内置「文件」页签：直接浏览远程主机文件（右侧文件树即远程目录，编辑保存直写远程）
内置「终端」页签：自动 SSH 到远程超算（图为 SLURM 作业调度环境）；左侧会话即模型免填调用 remote_ssh_* 工具
前置要求
| 项 | 要求 |
|---|---|
| DSH | ≥ 0.1.5-rc.1（0.1.2 稳定线请用 v0.18.1 时代的插件版本） |
| dsh-better-sidebar | ≥ 0.15（本插件依赖其 /sidebar/api/fs.* 文件 API） |
| 本机 SSH 客户端 | Windows：系统自带 OpenSSH（%SystemRoot%\System32\OpenSSH\ssh.exe）；Linux/macOS：openssh-client |
| 远程主机 | 任意标准 sshd（超算 / 服务器 / 跳板机均可） |
一条命令安装（无需 token、API Key 或额外配置）：
dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.12
安装后重启 DSH。@zhangfengshun/dsh-remote-ssh 必须在 bundles 列表中排在 dsh-better-sidebar 之后。
卸载：
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）两套契约均已适配。
三步上手
~/.ssh/config 可直接一键导入会话内直接对模型说（远程工作区会话中免填连接参数）：
看看 /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 是随时可用的手动兜底。
示例 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，批量高效）。
| 工具 | 用途 |
|---|---|
remote_ssh_profiles | 列出连接配置 + 当前会话远程工作区上下文 |
remote_ssh_exec | 执行远程命令（默认 120s 命令级超时，timeoutMs 可放宽/禁用） |
remote_ssh_kill | 强制关闭池化 SSH 会话（挂起命令的兜底恢复） |
remote_ssh_ls | 列举远程目录 |
remote_ssh_cat | 读取远程文件 |
remote_ssh_write | 写入远程文件 |
remote_ssh_grep | 搜索远程文件内容 |
remote_ssh_glob | 查找远程文件 |
remote_ssh_mkdir | 创建远程目录 |
remote_ssh_delete | 删除远程文件/目录 |
remote_ssh_move | 移动/重命名 |
remote_ssh_sync | 远端同步到本地镜像 |
remote_ssh_push | 本地镜像推送回远端 |
远程工作区会话中调用工具可免填 profileId 等连接参数；全部文件/命令类工具走持久 SSH 会话池 + 结果缓存，remote_ssh_exec 单命令实测 ≈15× 提速。
@ 文件引用补全远程工作区会话里输入 @，候选来自远端（与「文件」页签的树一致），而不是本地镜像目录：
git ls-files --cached --others --exclude-standard（尊重 .gitignore、含未跟踪文件；真实超算实测 0.117s / 137 条），非 git 目录回退有界 find（maxdepth 5 + 剪枝，实测 1.57s / 3121 条）；git ls-files --cached --others 的输出不是全局字典序（未跟踪文件按 readdir 顺序先输出），node_modules/ 这类目录可能占满前两万行把配额吃光——因此排除目录由远端 grep -vE 在 head 之前完成（与 -prune 同源，正则由同一份排除表生成），客户端过滤仅作双保险；索引达到上限时会打一条 warn 提示可能漏文件；@ 与 @src/ 走远端目录列举；@read 走索引模糊匹配（同名 > 前缀 > 名称子串 > 路径子串 > 子序列，目录加权 +25）；所有 SSH 命令默认 120 秒超时（issue #5）：一条挂起的远端命令（网络卡顿、远端进程僵死、等待 stdin 的 cat）不会再永久占用会话、拖死后续命令。
remote_ssh_exec 传 timeoutMs（毫秒）覆盖单次预算，0 禁用超时（长时构建/训练）；环境变量 DSH_REMOTE_SSH_CMD_TIMEOUT_MS 覆盖全局默认；remote_ssh_kill（或 all: true）强制关闭某个/全部池化会话，挂起命令随时可清理；remote_ssh_kill 或换命令重试。实测矩阵（2026-09-12，均为真机验证）：
| 组件 | 版本 | 状态 |
|---|---|---|
| DSH | 0.1.5-rc.1（DSH Desktop v2.0.9） | ✅ 主机服务 / settings / tools / slot / 上传下载拦截全部咬合 |
| DSH | 0.1.2-rc.1 稳定线 | ✅（插件 2.3.x 时代基线） |
| dsh-better-sidebar | 0.15.0 – 0.18.0 | ✅ fs.tree/fs.read/fs.write + fs.search（{ matches: cwd 相对 '/'-分隔路径, truncated } 契约，2.4.11 起；此前只回 entries 会让「按文件名搜索」崩掉整块页签） |
| dsh-better-sidebar | 0.19.x | ⚠️ 插件侧已适配 6 端点（含 fs.rename/fs.remove）；但 0.19.0/0.19.1 自身在 DSH Desktop 上主机半边无法加载，需等上游修复（见安装的警告） |
| 远程主机 sshd | 标准 OpenSSH（Linux / 超算 / Windows） | ✅ 密钥认证；密码认证需本机 sshpass（POSIX） |
插件不修改 DSH 源码、不注入 profile 依赖树，全部能力经官方 cordis.patch.yml + profile 机制挂载。
| 现象 | 原因与解法 |
|---|---|
「测试连接」报 Permission denied (publickey) | ① 私钥带口令：插件以批处理模式运行（BatchMode=yes），无法交互输口令——先用 ssh-add 加载，或去掉密钥口令；② Windows host 且用户在 Administrators 组时，公钥须写入 C:\ProgramData\ssh\administrators_authorized_keys；③ 用户名的写法（user / .\user / user@domain）要与手动连接一致 |
从 git-bash 启动 dsh web 后密钥认证失败 | 2.3.9 起已修复：Windows 下 ssh 解析固定为系统 OpenSSH 绝对路径（此前会误用 Git 自带的 MSYS2 ssh） |
| 侧边栏文件页签显示「这类内容还没有可用的查看方式。」 | dsh-better-sidebar 主机半边未加载：0.18.1 / 0.19.0 / 0.19.1 在 DSH Desktop 上会因 SessionLogOffset 运行时导入失败——降到 0.18.0 或使用修复版（上游 PR #641） |
| 内置「终端」页签连不上 | 终端为 ssh -tt 交互式通道，仅支持密钥认证；密码认证的连接会回退为本地 shell 并打印一行提示（避免把本地 shell 误认为已连上远程），密码认证请改用「文件」页签与模型工具 |
终端落在远程 $HOME 而不是工作区目录 | 2.4.5 起已修复（wrapper 会 cd 到工作区 remotePath，目录不存在时回退 $HOME）；若仍停在 $HOME，确认 2.4.5 已装入并重启 DSH |
「文件」页签树根显示镜像目录 ID（如 wmirror3） | 2.4.6 起已修复：树根改为显示远程目录名（如 my-project），悬停可见完整远程路径；该标签不经过 fs.* 路由，由客户端渲染层替换 |
@ 补全只搜到镜像里那几个文件 | 2.4.7 起已修复：远程工作区会话的 @ 补全改列远端文件（索引缓存 60s + 900ms 查询预算）；若仍只有镜像文件，确认 2.4.7 已装入并重启 DSH |
大仓里 @ 搜不到真实文件（如根目录 AGENTS.md、src/**） | 2.4.8 起已修复：此前排除目录发生在截断之后，node_modules/ 这类目录会吃光索引配额；现在排除由远端 grep/-prune 在截断前完成，并会在索引达上限时打 warn 提示 |
| 想加的远程目录还不存在，「添加工作区」里没法创建 | 2.4.9 起「目录选择器」底部有「📁 新建目录」（本地 / 远程 tab 均有）：输入名字即可就地创建并自动进入 |
| 从局域网 / 另一台设备访问时插件文件能力全部报 403 | 2.4.10 起已修复：信任判定改用宿主 ctx.webRuntime.trustedHosts（与 /api 网关同源）。把访问地址加进 DSH 信任列表即可：启动时加 --trusted-host <host[:port]>（或经配对设备访问）；未配置时行为与之前一致（仅本机 loopback） |
「文件」页签的「按文件名搜索」一输入就报 Cannot read properties of undefined (reading 'length') | 2.4.11 起已修复：fs.search 拦截此前只返回 entries，而 better-sidebar 客户端契约是 ；现在补上 （cwd 相对、 分隔，与上游自带实现一致）并保留 |
插件注册 6 个 exact 路由（/sidebar/api/fs.tree、fs.read、fs.write、fs.search，以及 better-sidebar 0.19 新增的 fs.rename、fs.remove），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 .remote-ssh.json 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
远程读取采用单往返合并读：一条池化命令同时返回 size/mtime 帧与文件内容（文本类扩展名优先 raw 直传，字节长 + U+FFFD 双校验失败自动回退 base64，结果逐字节一致）；配合主机侧结果缓存与变更失效（见下节）。
Shell wrapper（~/.dsh/remote-ssh/dsh-remote-shell[.cmd]）检测工作区 .remote-ssh.json，自动 ssh -tt 连接远程，使内置「终端」页签透明接入。
远程读取与目录列举结果在主机侧缓存（读 LRU 32 条 + 列举 LRU 64 条，TTL 5 秒；单条 >1MiB 不缓存、总量 32MB 字节预算，防止大文件驻留拖慢宿主）：TTL 内重复打开或切回页签 0 网络往返；过期后先做一次轻量 mtime+size 复验，未变化则免重传。写、删除、移动、建目录、上传、推送（push）、成功的远端 exec 与变更类 git 子命令（add/reset/commit/checkout/revert/cherry-pick）会自动失效相关缓存，并以每 profile 缓存代（epoch）兜底「同秒同 size 写」等粒度盲区。
已知限制：
ssh -tt）与远端其它进程改动的文件依赖 TTL + 复验兜底，最多 5 秒陈旧；/sidebar/file 下载池化路径有效上限约 6.29MB，更大文件自动退回一次性连接下载（可成功，多一次重连开销）；本项目是送给 zhangyi 的七夕礼物。
愿它像连接起一台台远方的超算一样，也把我们紧紧连在一起。七夕快乐 ❤️
—— 2026 年 8 月 18 日
版本历史与每版修复细节见 CHANGELOG.md（最近：2.4.3 适配 better-sidebar 0.19 端点、2.4.2 修复设置图标闪现、2.4.0 命令级超时与 remote_ssh_kill）。
如果这个插件帮到了你，欢迎在 GitHub 上点个 ⭐ Star，或到 DSH Market 收藏——这会帮助更多需要远程超算开发的人找到它。
{ matches, truncated }matches/entries| 远程工作区里「按文件名搜索」一直转圈（大工作区） | 2.4.11 起已修复：改为浅层优先（-maxdepth 3，实测冷 0.68s / 热 0.11s）且有命中就立即返回（深挖转后台预热缓存，浅层零命中才同步等深挖 -maxdepth 8），遍历前剪噪声目录、去掉会阻塞短路的 sort，并加远端墙钟预算——到点返回已收集的部分结果并标记不完整。实测某大型远程项目工作区：旧实现 5 分钟零输出 → 现在 0.96s 返回 43 条 |
远程会话里 @文件名 没有候选，但单独输入 @ 有 | 2.4.11 起已修复：模糊查询依赖索引，而索引首选 git ls-files --cached --others（--others 要遍历整棵工作树，巨型项目上跑不完 → 索引为空）。现在三级降级（完整 git 6s → 仅索引 git 3s → 有界 find maxdepth 3 + 5s），并在索引未就绪时用有界 find 即时兜底（实测 0.65s），不再出现「全空」 |
安装时提示 minimumReleaseAge 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
| 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 timeoutMs: 0，随时可用 remote_ssh_kill 强杀 |
| 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 remote_ssh_exec + head/tail 分段处理 |