前言¶

在 DSH（DeepSeek Harness）里让 Agent 连多台 Linux 机器，常见做法是手写脚本或把 SSH 细节塞进提示词。密码和私钥一旦进入模型上下文，就很难收回；rm -rf、sudo 这类命令也缺少统一审批。dsh-plugin-ssh-hosts 把多机 SSH 收成一组 Host 工具：清单、远程执行、文件读写、SFTP 上传下载、按机 sudo 策略、会话级授权与高风险命令审批，凭据 AES-256-GCM 存在本机，工具参数不接受密码或私钥正文。下面介绍它是什么、怎么装、怎么配、怎么用。

这是什么¶

dsh-plugin-ssh-hosts 是可独立安装的 DSH Host-only 插件（dsh.bundle.patch），由 zh-Littlebird 维护，npm 包名 dsh-plugin-ssh-hosts，社区分类 admin-security。实现基于纯 JS 的 ssh2（无需本机 ssh.exe），支持密码、私钥与带口令私钥；传输走 SFTP。插件通过 @deepseek-ai/dsh-tools 的 defineTool 注册到 ctx.tools，不改动 Harness 核心。README 记载已在 DSH 0.2.1-rc.2、Node 24.x、Windows 11 下验证。

核心功能¶

主机清单与认证¶

• 多台主机、别名唯一，支持增删改查与 TOFU 主机密钥。
• 私钥只按路径读取，不复制、不打印；支持 passphrase。
• 每台主机可配置 allowedPaths（读）、editablePaths（写/上传）、deniedPaths（始终拒绝），并对路径做 realpath 校验。
• readOnly: true 时只允许读/下载，拒绝 ssh_exec 与远端写入。

远程命令与 sudo¶

• ssh_exec 返回退出码、stdout、stderr、耗时、超时、截断与原始字节数。
• 每台服务器可配置 sudo：nopasswd（推荐）或 password（密码仅本机加密存储，经 SSH stdin 交给 sudo）。
• 传 privileged: true 或命令前导 sudo 会走插件托管的提权包装。

文件与 SFTP¶

• ssh_read_file / ssh_write_file：文本、UTF-8，拒绝二进制。
• ssh_upload / ssh_download：SFTP 流式传输，临时文件落盘后改名。
• 全局 tempDir 默认 /tmp，自动并入每台主机的可读可写策略，适合 Agent 过程文件；设为空字符串可关闭。

服务目录说明¶

主机记录可声明 services（服务名、目录、启动/日志/端口说明）。Agent 用 ssh_services 直接定位，无需反复 ls 猜路径。

授权、审批与审计¶

• 会话/服务器授权：每个新会话首次访问某台服务器（或操作主机清单）会向用户申请一次；换机或新会话需重新申请。处于「完全权限」的会话可按配置自动放行。
• 人工审批：rm -rf、sudo、shutdown、mkfs、dd、防火墙清空、DROP DATABASE 等命中时请求一次性批准；策略可由 highRiskPolicy 设为 ask / deny / allow。
• 审计：audit.log 记录动作、主机、用户、命令/路径、退出码、耗时、截断、审批结果，不含凭据。
• Web 侧：命令历史抽屉（筛选、约 5 秒刷新）、「SSH 服务器」页面可手动增删改、测试、录入或清除密码/口令（写接口仅接受本机回环）。

凭据隔离¶

任何工具参数均不接收密码、私钥内容；凭据单独加密存储，secretsBackend 可选 file、env 或 none（仅适合无私钥口令、无密码的主机）。

安装与启用¶

前置条件¶

• DeepSeek Harness >=0.2.1-rc.2 且 <0.3.0（package.json 中 engines.dsh）。
• Node.js >=22.19（推荐 24）。
• 能访问 npm registry（安装 ssh2 与 @deepseek-ai/schemastery）。

从源码构建（可选）¶

维护者文档中的构建与测试步骤如下：

cd dsh-plugin-ssh-hosts
npm install --legacy-peer-deps
npm run build
npm test

npm run build 输出到 lib/；npm test 编译测试到 dist-test/ 并运行 54 个用例。

安装到 profile¶

建议先装独立开发 profile，确认无误后再装日常 profile：

# 创建一个独立的 headless profile（只创建一次）
dsh --profile ssh-dev --from-default-profile headless

# 安装进该 profile
dsh plugin --profile ssh-dev add dsh-plugin-ssh-hosts

# 确认 bundle 层已出现
dsh --profile ssh-dev --dump-config | Select-String ssh-hosts

# 确认模块可导入且 Config schema 可读
dsh --profile ssh-dev --dump-config-schema

Web/Desktop 日常 profile 将 ssh-dev 换成 desktop：

dsh plugin --profile desktop add dsh-plugin-ssh-hosts

也可在 Web 侧栏 Plugins 页面安装，或由 Agent 调用 plugin_manager 的 install_bundle，target 传包名 dsh-plugin-ssh-hosts 或本地目录绝对路径。

安装后若 Desktop 已在运行，需重启 Harness 进程，Host 插件才会加载。卸载：

dsh plugin --profile desktop remove dsh-plugin-ssh-hosts

插件数据默认在 $DSH_HOME/ssh-hosts（Windows：C:\Users\<你>\.dsh\ssh-hosts）；卸载不会自动删除该目录。

配置¶

cordis.patch.yml 自带默认可用片段，例如：

- insert:
    - id: ssh-hosts
      name: dsh-plugin-ssh-hosts
      config:
        maxOutputBytes: 131072
        timeoutMs: 60000
        maxTimeoutMs: 300000
        highRiskPolicy: ask
        sessionConsent: ask
        trustFullAccess: true
        audit: true
        tempDir: /tmp
        debug: false

常用字段包括：dataDir（可用环境变量 DSH_SSH_HOSTS_DATA_DIR 覆盖）、timeoutMs / maxTimeoutMs、highRiskPolicy、sessionConsent、trustFullAccess、audit、tempDir、guardCommandEdits、strictCommandPaths 等。修改方式：编辑 profile 的 cordis.patch.yml，或在 Web 插件设置里改 config。不要把密码写进 YAML。

典型用法¶

添加服务器¶

让 Agent 调用 ssh_host_add（示例字段如下；不接受 password、privateKey、passphrase）：

{
  "name": "ssh_host_add",
  "arguments": {
    "alias": "web-1",
    "host": "10.0.0.10",
    "port": 22,
    "username": "deploy",
    "authType": "password",
    "defaultCwd": "~/app",
    "allowedPaths": ["~/app", "/tmp"],
    "editablePaths": ["~/app"],
    "services": [
      {
        "name": "api",
        "directory": "~/app/api",
        "description": "对外 HTTP API，构建后由 systemd 启动",
        "startCommand": "sudo systemctl restart api",
        "logPath": "~/app/logs/api.log",
        "port": 8080
      }
    ],
    "tags": ["prod", "web"],
    "fingerprintPolicy": "accept-new"
  }
}

添加成功后通常会得到 credentialStatus: "missing"，需在下一步在本机录入凭据。

在本机录入密码或口令¶

1. Web：「SSH 服务器」→ 编辑目标主机 → 填写密码/口令后保存。
2. 本机终端（非 Agent 会话），在插件目录执行：

node scripts/dsh-ssh.mjs set web-1 --password
node scripts/dsh-ssh.mjs set web-1 --passphrase

经上述步骤后，Agent 即可调用 ssh_exec、ssh_read_file、ssh_upload 等工具，具体工具名以安装后 dump-config-schema 为准。

适用场景与注意¶

适合：需要在 DSH 会话里对多台 Linux 做运维排查、读日志、受限目录内改配置、SFTP 传文件，且希望凭据与高风险命令与模型隔离的团队或个人。

注意：

• 插件以当前 DSH 进程的权限访问本机数据目录与网络；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证。
• 默认 /tmp 全局可读，勿把敏感内容直接写在共享临时路径；可按任务建私有子目录并在结束后删除。
• 社区目录 skillhub.cn 插件页 与 DeepSeek / 幻方无官方从属关系；DSH 生态主张「一切皆插件」，本介绍事实以仓库 README 与 package.json（当前版本 1.2.0）为准。

链接¶

• 社区目录：https://www.skillhub.cn/plugins/zh-Littlebird/dsh-plugin-ssh-hosts
• 源码与完整说明：https://github.com/zh-Littlebird/dsh-plugin-ssh-hosts