前言¶
在 DSH（DeepSeek Harness）里做智能体开发时，工具和上下文多半落在本机工作区；真正要改的服务、跑命令的环境往往在另一台 SSH 可达的机器上。常见做法是再开一个终端和 SFTP 客户端，或在编辑器里装 Remote SSH，但那些界面与 DSH 的会话、better-sidebar 并不天然连在一起。
下面介绍社区插件 dsh-remote-ssh（维护者 LinHao100076，MIT 许可）。它在 DSH 右侧边栏（或与 dsh-better-sidebar 联动的「远程 SSH」标签页）里提供远端文件树、终端、按方向配置的编辑同步、SFTP 传输，以及本地 -L、动态 -D、反向 -R 转发与多跳跳板链路。README 将当前重点版本写为 0.7.3（无密钥首次建连、堡垒机多跳、密码与 2FA 等）；仓库 package.json 中版本号为 0.7.4，安装时以你拿到的发布包为准。
插件在 SkillHub 分类为「客户端」，GitHub 星标约 3。目录页：https://www.skillhub.cn/plugins/LinHao100076/dsh-remote-ssh；源码与说明：https://github.com/LinHao100076/dsh-remote-ssh。
这是什么¶
一句话定位：这不是独立的通用 SSH 客户端，而是「本地 DSH 工作区旁挂一条远端通道」——文件、终端、同步和转发都收在同一个 Workspace 面板里（主机头 + 文件 / 终端 / 同步 / 转发 / 设置 + 状态栏）。
设计文档（docs/design.md）里的核心判断是：agent 与 better-sidebar 的执行世界在本地，因此 v0.x 走「本地镜像 + 旁挂远端」，而不是把整个 harness 搬到远端。主机配置与映射状态落在插件自己的 ~/.dsh/storages/dsh-remote-ssh/state.json；密码和口令不落盘，只在浏览器内存里、连接时现取。
核心功能¶
入口与界面¶
两种入口互斥，面板是同一套组件：
| 装了什么 | 出现在哪 | 怎么打开 |
|---|---|---|
有 dsh-better-sidebar |
better-sidebar 侧栏里名为「远程 SSH」的一个标签页 | 侧栏点「远程 SSH」 |
| 没有 / 停用了 better-sidebar | DSH 自带右侧边栏 | 会话头部右上角服务器图标 |
界面宽度跟随右侧栏；可先本地打开 ui/prototype.html 对照布局（转发视图晚于原型，改 UI 以 client/forward-view.jsx 为准）。
文件与传输¶
- 侧边栏浏览远端目录：单击展开、双击进入；面包屑与「上传位置」表示当前目录；回到文件页会刷新，页面可见时每约 4 秒刷新当前目录与已展开子目录。
- 上传按 256 KB 分块，避免大块文件塞进 JSON；支持取消（发布阶段不可取消）；空闲 15 分钟任务自动清理。
- 下载可填本机绝对路径（含文件名），也可「下载到映射目录」；此处的「本地」是 DSH 宿主所在机器（桌面版即当前电脑，远程 Web 部署则是跑 DSH 的服务器）。
- 0.5.0 起支持 SFTP 断点续传；0.7.2 起加强覆盖与自动同步边界（不完整传输、源变化时保留目标；OpenSSH 原子 rename 等，详见 CHANGELOG）。
远端搜索¶
放大镜默认在当前目录及子目录按文件名包含关键词查找；可切到「文件内容」模式，在远端执行 rg（无则 grep -r），不把整库拉到本地索引。内容模式支持 smart-case 与有限正则；结果上限 200 条并在远端截断。
终端与 tmux¶
远端有 tmux 时执行 tmux new -A -s dsh-<host>，刷新或断线后可接回同一会话；没有 tmux 则用普通 shell，并提示刷新后会话进程会结束。新建终端标签对应独立 tmux 会话。
同步（镜像编辑）¶
「同步」标签页按映射配置方向（本地 ↔ 远端）做文件镜像与 watcher；与 agent 在本地改动上传、远端文件下载等流程配合。相对映射路径按会话目录解析；下载不能越过本地映射目录。具体冲突策略与 0.7.2 的变更见 README 与 CHANGELOG。
端口转发与跳板¶
| 方式 | 监听端 | 典型用途 |
|---|---|---|
本地 -L |
DSH 宿主 | 经 SSH 主机访问其可达的内网服务（如 B:22、数据库、Web） |
动态 -D |
宿主 SOCKS5 | 支持 SOCKS5 的客户端访问多个内网目标 |
反向 -R |
SSH 主机侧 | 让服务器访问宿主上的服务 |
| 跳板链路（推荐连内网 B） | 无额外固定监听 | 在主机 B 的设置里串起 A→B，插件完成 本机 → A → B，文件与终端属于 B |
经 A 连 B 时：跳板链路会替你完成到 B 的 SSH 登录；仅开 -L 到 B 的 22 端口只提供 TCP 隧道，仍要再用 B 的地址与凭据建主机，且 A 的连接须保持运行。远程 Web 部署时，表中的「宿主」指运行 DSH 的服务器，不是打开浏览器的电脑。
0.6.0 起补充 SOCKS5 动态转发与 -R；0.7.0 起支持密码 / keyboard-interactive（2FA）与多跳跳板；0.7.0 起强调无密钥也能首次建连。
认证与依赖¶
Node ≥ 20（CI 在 20 / 22 / 24 上跑测试）；宿主端 lib/server.mjs 将 ssh2、ws、chokidar 等打进 bundle，发布包无运行期 npm 依赖（0.3.1 起）。客户端通过 @deepseek-ai/dsh-client-ui-slots 等注入 Web 侧栏。
安装与启用¶
不要使用裸包名 dsh plugin add dsh-remote-ssh：npm 上存在同名但归属不同的包，会占同一 node_modules/dsh-remote-ssh 目录。安装须用 GitHub Release 的 tgz 完整路径或按仓库说明取用；认准仓库 LinHao100076/dsh-remote-ssh。
推荐用发布包安装（DSH 会写入 profile 的 dsh.profile.bundles）：
npm run pack:rel # 生成 dist/dsh-remote-ssh-<版本>.tgz
dsh plugin --profile <profile> add -w "/path/to/plugin.tgz"
-w 不能省略：profile 含 pnpm-workspace.yaml 时，不带 -w 可能报 ERR_PNPM_ADDING_TO_ROOT。
不要解压 tgz 后把目录当路径装进去（pnpm 可能写成 link:，历史上会导致宿主端 import 缺依赖）；当前发布包已把依赖打进 lib/server.mjs，用 tgz 路径即可。
CLI 启动示例（app 参数直接跟在后面，不要写 web）：
dsh --profile <name> --no-open --port 4987
desktop profile 由桌面应用独占，CLI 会拒绝；应在应用内插件页安装，或手工改 package.json 的 bundles 与 cordis.patch.yml 后重启。桌面版升级插件后请完全退出再启动，只关侧栏可能仍加载旧客户端代码。
开发期也可仅在 cordis.patch.yml 插入插件 id（需已构建 lib/client.js），见 README「装到 profile 里」一节。
典型用法¶
1. 第一次连上主机¶
- 打开「远程 SSH」面板，新建连接，填写地址、端口、用户与认证（密钥、密码或 2FA）。
- 若目标在内网，在「跳板链路」里按顺序添加堡垒机卡片（支持多跳；
~/.ssh/config的ProxyJump会展开为多跳）。 - 连接成功后，在「文件」页浏览、预览、上传或下载；在「终端」页执行命令。
2. 经堡垒机访问内网 B（推荐跳板）¶
- 新建主机 B：填 B 内网地址、端口、用户与 B 的认证。
- 在 B 的跳板链路中添加 A，填 A 的 SSH 地址与认证。
- 连接后文件树与终端即 B 的环境，无需先手动配
-L再二次建连。
若必须用转发：先在 A 上添加本地 -L 监听 127.0.0.1:2222，目标为 A 能访问的 B:22；再建主机 B，地址 127.0.0.1、端口 2222，用户与认证仍填 B 的，并保持 A 连接与转发运行。
3. 搜索与编辑¶
- 在文件视图选目录，用搜索默认可查文件名；切「文件内容」则在远端
rg/grep。 - 在「同步」页配置映射方向，让本地 agent 改动按规则上传到远端或拉取远端文件；注意映射目录边界与冲突说明（见 0.7.2 README 段落）。
4. 端口转发¶
在「转发」页为已连接主机添加 -L、-D 或 -R 规则，在宿主（或 Web 部署时的 DSH 服务器）上监听，把流量导向 SSH 对端可达的服务。
适用场景与注意¶
适合谁：已经在用 DSH 做本地智能体开发，需要频繁在侧边栏看远端目录、开 shell、同步一小段映射目录，或临时做 SSH 隧道，又不想在 DSH 外再维护一套 Remote 工具链的人。
权限与安全：插件在当前 DSH 宿主进程权限下执行 SSH、读写本地映射路径与转发监听；安装前应阅读源码、SECURITY.md 与 MIT 许可证，确认凭据存储模型是否符合你的环境。社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，插件属社区贡献。
其他注意：
- 与 dsh-better-sidebar 联动时侧栏更集中；无 better-sidebar 时用原生右侧栏入口即可。
- 远端 Web 部署时，下载目标路径、
-L/-D监听端都在 DSH 服务器上，不是浏览器所在电脑。 - 上传中断或异常可能留下远端
.dsh-tmp-*临时文件；大文件上传请留意分块与取消行为。
结尾¶
经过上面的步骤，可以把 dsh-remote-ssh 理解成：在 DSH 里给远端机器做一块固定的「影子工作区」——文件、终端、定向同步和三种转发收在同一面板，并支持多跳与无密钥首次建连。细节与版本差异以仓库 README、CHANGELOG 和 ROADMAP 为准。
