前言¶
DeepSeek Harness (DSH) 的设计理念是「一切皆插件」。在智能体开发场景中，经常需要同时操作多台服务器。传统的 SSH 客户端或直接调用 subprocess 会破坏上下文隔离，而自行管理 SSH 隧道较为繁琐。这里介绍的是 DSH 的社区插件 dsh-ssh-tunnel，它将多台 SSH 主机收进一个主机库，并提供按项目的授权机制。
这是什么¶
dsh-ssh-tunnel 是一个挂在 DSH 官方右侧栏的插件，由 OMSociety 维护。它提供了一个主机库、按项目授权功能，并在侧栏集成了 SSHManager 工具与双栏 SFTP面板。
插件的核心逻辑是：模型用 SSHManager 工具执行命令或传文件，你在侧栏管理主机与授权。远端操作只发生在你显式调用的工具与面板里，本地文件与远端文件始终是两侧分明的东西。配套插件是 dsh-git-forge（Git 凭据与 push 策略）。
核心功能¶
- 主机库：管理多台主机，支持密码或私钥（含口令）。密钥只存宿主侧，不进入模型上下文。
- 按项目授权：授权 key 是 DSH 会话工作区（
projectPathKey）。连接前必须先授权，Connect 不会自动写入授权。 - SSHManager 工具：提供远端 exec、SFTP 列举/读写/增删改、上传下载、交互式会话读写等功能。
- 中央面板：交互式终端（xterm）与双栏 SFTP：左侧是项目工作区，右侧是远端，可直接上传下载。
- 断线可续：掉线会话留作墓碑，可重连（同一 id）或关闭。意外断开自动重连最多 3 次，ssh2 keepalive 30s × 3。
- 主机密钥指纹：以 SHA256 hex 存入
known_hosts.json。首次连接或指纹变更时在侧栏确认并展示指纹。 - 本地路径守卫：上传/下载/列举/删除的本机路径限制在项目工作区根内，词法 与 realpath 双重校验。
- 界面双语：侧栏与面板随 DSH 界面语言在中文 / 英文间即时切换。
安装与启用¶
从 npm 安装：
# 先停掉正在运行的 DSH（运行中的服务会锁住依赖，装完再起）
dsh plugin --profile <profile> add "dsh-ssh-tunnel"
安装完成后，刷新一下浏览器页面，「SSH 隧道」入口才会出现在右侧栏——只重启宿主不够，客户端产物是页面加载时取的。
典型用法¶
- 打开右侧栏「SSH 隧道」→ 主机库 添加一台主机（密码或私钥）。
- 切到 项目授权，给当前项目勾上这台主机并保存（不授权连不上，这是有意为之）。
- 回 隧道会话 点 Connect；首次连接会提示确认主机密钥指纹。
- 点 终端 得到一个交互式 shell，或点 SFTP 打开双栏面板。
- 让模型用
SSHManager action=exec跑条命令、用sftp_list看目录、sftp_upload/sftp_download传文件，验证整条链路。
安全与注意事项¶
- 信任边界：插件的 HTTP API 挂在 DSH 宿主的本地 web 服务上，只接受本机回环与配置的可信主机，并校验浏览器
Origin。API 没有鉴权 token——能在本机访问该端口的进程都被视为已授权用户。会话 API 必须带projectPathKey，跨项目不可见。 - 认证方式：只有密码或私钥。键盘交互式认证（含堡垒机网页 MFA）不支持。
- 路径守卫 fail-closed：上传/下载/列举/建目录/删除的本机路径限制在项目工作区根内，词法 与 realpath 双重校验，越界路径与指向工作区外的符号链接一律拒绝。
- 授权撤销即时生效：写类操作在发起前与结果回报前各复检一次授权。撤销后输出被丢弃并以
not authorized失败，下载中的本地文件被删除，受影响的存活会话被关闭。 - 工具结果：工具结果与列表 API 不返回 password / PEM / 口令。优先使用密钥登录；若
secrets.json可能泄露请立即轮换凭据。
生态背景¶
DSH 理念是「一切皆插件」。社区目录与 DeepSeek / 幻方无官方从属关系。插件遵循 MIT 许可证。
