hcyinnn/dsh-tool-ssh

dsh-tool-ssh

用于 DeepSeek Harness(dsh)的 SSH 工具插件。

让 dsh Agent 通过 OpenSSH 在远程主机上执行命令、上传/下载文件,无需在目标机器上安装任何 Agent 组件——只要它能用 ssh 登录即可。

功能

| 工具 | 说明 |
| --- | --- |
| ssh_run | 在远程主机上执行一条 shell 命令,返回 stdout / stderr / exit code |
| ssh_upload | 用 scp 把本地文件/目录上传到远程主机 |
| ssh_download | 用 scp 把远程文件/目录下载到本地 |

环境要求

- DeepSeek Harness(dsh)已安装
- 本机有 OpenSSH 客户端(ssh、scp,macOS / Linux 自带,Windows 可用 OpenSSH for Windows 或 Git Bash)
- 能访问目标主机,并已配置好认证方式(默认用 ~/.ssh 下的密钥;推荐密钥认证)

安装

方式一:从 GitHub 安装(源码,首次需构建授权)

固定到某个 commit 更安全,见下
dsh plugin add github:/dsh-tool-ssh
dsh --profile web --dump-config   # 确认 tool-ssh 已挂载

由于 Git 安装拉取的是源码,pnpm ≥ 10 首次安装会在该 profile 的
pnpm-workspace.yaml 里提示加入 allowBuilds 授权(按报错提示复制 key 即可),
包内的 prepare 脚本会自动构建出 lib/。

建议锁定 commit 再安装,避免后续推送改变实际运行的代码:

dsh plugin add github:/dsh-tool-ssh#

方式二:本地开发挂载(临时 overlay)

my-overlay.yml
- insert:
- id: tool-ssh
name: '/绝对路径/dsh-tool-ssh/lib/index.js'

dsh --profile headless --patch ./my-overlay.yml "在远程服务器上查一下 nginx 状态"

方式三:发布到 npm 后

npm publish          # 作者侧先 build
dsh plugin add dsh-tool-ssh

用法示例

Agent 侧自然语言即可触发,例如:

- “在生产服务器 10.0.0.5 上执行 systemctl status nginx”
- “把本地的 dist/ 目录上传到 10.0.0.5:/var/www/app”
- “从 web-1 下载 /var/log/app.log 到本地”

工具参数(host / user / port / identityFile / workdir / env / timeoutMs
/ recursive)都是可选的连接覆盖项,优先级:工具参数 > 配置中的主机别名 > 默认值。

配置

在 profile 的 cordis.patch.yml(或 bundle patch 覆盖)中配置:

- id: tool-ssh
name: 'dsh-tool-ssh'
config:
命名主机:Agent 可以直接用别名引用
hosts:
prod-web:
host: 10.0.0.5
user: deploy
port: 22
identityFile: ~/.ssh/deploy_key
db:
host: db.internal
user: root
单次命令默认超时(毫秒),默认 30000
defaultTimeoutMs: 30000
连接超时(毫秒),默认 15000
connectTimeoutMs: 15000
ssh / scp 二进制路径,默认取 PATH 中的 ssh / scp
sshBinary: ssh
scpBinary: scp
-o BatchMode=yes:失败即停,不弹密码/主机密钥交互,默认 true
batchMode: true

安全建议:不要在配置里写死密码;插件默认启用 BatchMode=yes(避免在无人值守时挂起),
认证请使用密钥。各部署允许访问哪些主机、是否允许上传等策略,属于部署策略,
建议用 tools/pre-execute / ctx.tools.guard() 在外部实现,而不是写进本插件。

开发

npm install        # 安装依赖并触发 prepare 构建
npm run typecheck  # 类型检查
npm run build      # 构建到 lib/
npm test           # 单元测试(node --test)

端到端测试(可选)

仓库内带一个用 asyncssh 起的本地 SSH 服务器(测试辅助,非插件依赖):

python3 -m venv /tmp/sshenv && /tmp/sshenv/bin/pip install asyncssh
生成测试密钥并启动服务器(默认监听 127.0.0.1:2222)
ssh-keygen -t ed25519 -f /tmp/sshtest/hostkey -N ''
ssh-keygen -t ed25519 -f /tmp/sshtest/userkey -N ''
/tmp/sshenv/bin/python test/e2e_server.py &
node test/e2e.mjs

设计要点

- 全部通过 child_process.spawn(argv) 调用系统 ssh / scp,不经本地 shell,
host / user / port / 路径都是独立 argv,杜绝本地参数注入;我们自行拼接的远程片段
(workdir、env)均做单引号转义。
- 工具返回单一规范化 JSON 值;远程命令非零退出码是领域内正常结果(放进返回值),
基础设施失败(二进制缺失等)才抛错——符合 dsh 工具契约。
- 遵循 exec.signal:工具调用被取消时会杀掉 ssh/scp 子进程。
- 输出做了每流上限(默认 2 MiB),避免长输出撑爆内存,并返回 truncated 标记。

许可证

MIT