dsh-ssh-plugin: SSH 执行与持久化连接管理

前言¶

DeepSeek Harness (DSH) 是一个基于插件的智能体开发框架。在使用 DSH 构建代理时，经常需要让模型直接操作远程 Linux 服务器。虽然可以通过模型调用 shell 工具，但直接执行远程命令需要额外的配置。dsh-ssh-plugin 插件提供了原生的 ssh_exec 工具，允许模型通过系统自带的 SSH 客户端直接在远程服务器上运行命令。

插件介绍¶

该插件由维护者 YOLO-LZL 开发。它主要解决两个问题：一是提供 ssh_exec 模型工具，允许直接在远程 Linux 服务器上运行命令；二是支持持久化 SSH 连接，可以在工作区中保存连接配置，供后续调用使用。

核心功能¶

插件核心功能包括：
1. 模型工具集成：为模型提供 ssh_exec 工具，支持自然语言指令（如 “ssh to root@10.0.0.5 and show disk usage”）或显式参数调用。
2. 持久化连接管理：提供 ssh_connections 工具，支持保存、列出、删除连接，并将连接绑定到工作区作为默认连接。
3. 基于密钥认证：仅支持 Key-based auth (BatchMode=yes)，没有密码/私钥提示，避免因认证失败导致的程序挂起。
4. 无远程 Shell 引用层：远程命令直接通过 bash -s 传递，不经过额外的 Shell 转义层。
5. 会话沙箱感知：根据当前会话的安全策略运行，在 danger-full-access 策略下可不受限制运行。
6. 本地配置识别：自动识别并读取本地的 ~/.ssh/config 文件，无需手动保存配置别名。
7. 双端包设计：同时支持宿主端和浏览器端。
8. 优雅降级：当 Harness 的某些服务（如 settings 或 workspaceRegistry）缺失时，插件仍能正常工作。

安装与启用¶

从 npm 安装插件：

dsh plugin --profile <name> add dsh-ssh-plugin

安装后启动 Harness 即可使用：

dsh --profile <name>

典型用法¶

插件为模型提供了 ssh_exec 和 ssh_connections 两个工具。

ssh_exec¶

模型可以直接使用自然语言，或传递显式参数执行命令。

参数	必填	说明
`host`	是	远程主机地址 `[user@]host`，或 `~/.ssh/config` 中定义的别名。
`command`	是	在远程主机上通过 `bash -s` 运行的命令。
`port`	否	SSH 端口，默认 22。
`key_path`	否	私钥的绝对路径。省略则使用 `~/.ssh` 默认或 ssh-agent。
`timeout_ms`	否	前台超时时间（毫秒），默认 30000。
`connection`	否	已保存连接的标签，用于填充 host/port/user/keyPath。

ssh_connections¶

用于管理持久化连接，连接数据保存在 Harness 设置中，重启后依然存在。

save: 保存连接（需提供 label、host，可选 port、user、keyPath）。
list: 列出已保存的连接，以及从 ~/.ssh/config 发现的只读主机。
delete: 通过标签删除连接。
use: 将当前工作区绑定到指定连接标签，后续调用 ssh_exec 可省略 host 参数。

适用场景与注意¶

目标环境：目标 Linux 服务器必须安装 bash 并配置好基于密钥的 SSH 访问（~/.ssh/authorized_keys）。
Windows 环境：在 Windows 上运行时，会话的沙箱策略必须是 danger-full-access，否则受限令牌可能拒绝启动 ssh.exe。
安全性：插件仅存储密钥路径，密钥内容不会离开本地磁盘。
许可证：插件采用 MIT 许可证。

短结尾¶

该插件通过封装 SSH 客户端调用，简化了代理对远程服务器的操作。配合持久化连接功能，可以减少重复配置。相关代码位于 GitHub。