前言¶

在 DeepSeek Harness（DSH）里让 agent 连远端机器，常见做法是每次在对话里重复 host、用户、跳板信息，或依赖本机 ~/.ssh/config 但模型侧没有稳定、可枚举的主机清单。维护者 alfredhuang211 的客户端插件 dsh-ssh-hosts（GitHub：alfredhuang211/dsh-ssh-hosts，当前 package 版本 0.5.0，MIT 许可证）把多台服务器收成一份主机清单，agent 在会话里按 名称 引用：执行命令、读文件、写文件、改文件、列目录。凭据只描述「怎么连」（host、user、identityFile、跳板），密码与密钥内容不进清单；认证、known_hosts、ssh-agent 交给系统 OpenSSH。

这是什么¶

dsh-ssh-hosts 是 DSH 生态里的客户端插件：图形界面或 YAML 管理主机，向 agent 暴露 ssh_hosts、ssh_run、ssh_read 等工具。分类上属于客户端；在 SkillHub 目录页可检索：https://www.skillhub.cn/plugins/alfredhuang211/dsh-ssh-hosts（社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系）。

与「每次口述 IP」相比，清单里的 name 即会话引用名；与裸 SSH 脚本相比，读写语义与本地 DSH 工具一致（例如 read 的 offset/limit 为行号，edit 要求 oldString 唯一）。

核心功能¶

下面按能力说明，均来自插件 README 与 package.json 声明。

Agent 工具（7 个）¶

主机解析顺序：显式 host → 本会话 ssh_use → 界面设的默认机 → config.defaultHost → 报错并列出可用主机（不会静默猜一台）。

图形界面与清单¶

• 路径：设置 → 插件 → dsh-ssh-hosts，或设置侧栏 「SSH 主机」。
• 新增/编辑/删除、测试连通性、设默认机；界面写入与 ssh-hosts.yaml 同源，改完立即生效，无需重启插件。
• 会话输入框左侧 「+」 → 命令菜单选 ssh，可点选主机设本会话默认机；亦可 /ssh <主机名>、/ssh clear。

登录与安全边界¶

清单禁止写 password: / passphrase: 明文。单台主机可设 readOnly: true 拒绝 ssh_write / ssh_edit。config.allow / config.deny 可对 ssh_run 做命令正则白/黑名单（deny 优先）。

安装与启用¶

引擎要求（package.json）：Node >=22，DSH >=0.2.0-rc.1 <0.3.0。

推荐：CLI / 桌面插件目录¶

将插件目录或 npm pack 得到的 tgz 装进指定 profile：

dsh plugin --profile web add /绝对路径/plugin-dev/ssh-hosts

桌面版可在 设置 → 插件 安装同一 tgz 或目录。插件声明 dsh.bundle.patch，安装后会插入 id: ssh-hosts 参与 profile 组装。

装完后可核对：

dsh web --dump-config | grep -A2 ssh-hosts

期望看到类似：

# == dsh-ssh-hosts
- id: ssh-hosts
  name: dsh-ssh-hosts

注意：dsh plugin --profile desktop ... 会被拒绝（desktop profile 由 Electron 独占）；装进桌面 App 请用 App 内插件界面，或按 App 文档用 link: 依赖后重启加载。

离线 / 内网¶

Releases 提供打包好的 dsh-ssh-hosts-x.y.z.tgz，可用上述 dsh plugin add 指向该包。

手写 patch（可选）¶

在 ~/.dsh/profiles/<name>/cordis.patch.yml 或 ~/.dsh/cordis.patch.yml 增加：

- insert:
  - id: 'ssh-hosts'
    name: 'dsh-ssh-hosts'
    config:
      defaultHost: web-01

config 字段均有默认值，只写需要覆盖的项。

配置主机清单¶

数据文件默认路径：$DSH_HOME/ssh-hosts.yaml（插件 config 字段 hostsFile 可改）。权限须 0600，否则拒绝加载。

手工起步可复制示例并编辑：

cp ssh-hosts.example.yaml ~/.dsh/ssh-hosts.yaml
chmod 600 ~/.dsh/ssh-hosts.yaml
$EDITOR ~/.dsh/ssh-hosts.yaml

示例片段（name / host 必填，未知字段会报错）：

version: 1

hosts:
  - name: web-01
    host: 10.0.0.11
    user: deploy
    identityFile: ~/.ssh/id_ed25519
    defaultWorkdir: /srv/app
    description: 生产 Web（Nginx）
    tags: [prod, web]
    port: 22
    proxyJump: bastion
    readOnly: true

  - name: db-01
    host: 10.0.0.12
    user: root
    passwordRef: DSH_SSH_HOSTS_PASSWORD_DB_01
    tags: [prod, db]

常用插件 config 标量（改后下次工具调用生效，无需重启）：defaultHost、strictHostKeyChecking（默认 accept-new）、connectTimeoutSec、timeoutMs、maxOutputBytes、maxReadBytes、controlPersistSec 等。若 config.hosts 非空，则忽略 hostsFile 且界面只读，改 hosts 需重启。

典型用法¶

自然语言（会话里）¶

在 web-01 上执行 systemctl status nginx
看一下 db-01 的 /etc/mysql/my.cnf
把 web-01 的 /srv/app/.env 里 PORT=8080 改成 PORT=9090

agent 会先 ssh_hosts()，再带 host 调用对应工具。

显式工具调用¶

ssh_hosts()
ssh_use({ host: "web-01" })
ssh_run({ command: "uname -a" })
ssh_run({ host: "db-01", command: "df -h" })
ssh_read({ host: "web-01", path: "/etc/nginx/nginx.conf", offset: 1, limit: 40 })
ssh_write({ host: "web-01", path: "/tmp/hello.txt", content: "hi\n" })
ssh_edit({ host: "web-01", path: "/srv/app/.env", oldString: "PORT=8080", newString: "PORT=9090" })
ssh_ls({ host: "web-01", path: "/srv/app" })

设好 ssh_use 或全局默认机后，ssh_run 等可省略 host。

适用场景与注意¶

适合：需要在 DSH 会话中稳定引用多台 SSH 主机、让 agent 执行运维读写的开发者；已有 OpenSSH 密钥或愿意用 DSH 凭据库存密码引用的环境。

务必注意：

1. 插件以当前 dsh 进程权限调用系统 ssh，安装前请阅读源码与 MIT 许可证，确认组织策略允许。
2. 清单可备份分享，但仍含 host、用户、跳板结构；密码仅存凭据库，删主机会同步清除对应密码条目。
3. 无凭据服务的 profile 无法使用密码登录主机，界面会说明原因。
4. YAML 语法错误、权限过宽等属于装载期硬失败，需修正后才能加载。

结尾¶

dsh-ssh-hosts 把「多台 SSH 服务器」收成可管理的主机清单，并在 agent 侧提供与本地一致的远端命令与文件操作语义；设置页与 ssh-hosts.yaml 同源，会话里可用主机名或「+ → ssh」快速切机。

• 目录页：https://www.skillhub.cn/plugins/alfredhuang211/dsh-ssh-hosts
• 仓库与文档：https://github.com/alfredhuang211/dsh-ssh-hosts