dsh-tool-ssh
SSH 工具插件 for DeepSeek Harness(dsh)。
让 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#<完整commit-sha>
方式二:本地开发挂载(临时 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 标记。
License
MIT
