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