dsh-ssh-hosts

给 DeepSeek Harness（dsh）加一组 SSH 工具：把若干台服务器存成一份主机清单，agent 在会话里用主机名引用它们 —— 执行命令、读文件、写文件、改文件、列目录。

• 凭据只存怎么连（host / user / identityFile / 跳板），不存密码、不存密钥内容；
• 认证、known_hosts、ssh-agent 全部交给系统 OpenSSH，插件不重新实现加密；
• 多机：同时配置 N 台，一次调用指定一台；会话里可以 ssh_use 设默认机；
• 图形界面管理：在 设置 → 插件 → dsh-ssh-hosts（或设置侧栏「SSH 主机」）里新增/编辑/删除主机、测连通性、设默认机；界面写的就是那份 YAML，改完立即生效，不用重启；
• 与本地同名工具语义一致（read 的 offset/limit 是行号，edit 要求 oldString 唯一）。

装

方式零：直接从 GitHub

git clone https://github.com/alfredhuang211/dsh-ssh-hosts.git
dsh plugin --profile web add ./dsh-ssh-hosts      # 桌面版则在「设置 → 插件」里选这个目录

Releases 里也有打包好的 dsh-ssh-hosts-x.y.z.tgz，适合离线安装或内网分发。

方式一：桌面 App / CLI 的插件安装（推荐）

# CLI：把本目录（或 npm pack 出的 tgz）装进某个 profile
dsh plugin --profile web add /绝对路径/plugin-dev/ssh-hosts

装完 dsh web --dump-config | grep -A2 ssh-hosts 应该能看到：

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

桌面版也可以在 设置 → 插件 里安装同一个 tgz / 目录；本插件声明了 dsh.bundle.patch，安装后会自动作为一层 bundle 参与 profile 组装（insert 一行 id: ssh-hosts）。

桌面 App 自己的 desktop profile 由 Electron 独占：dsh plugin --profile desktop ... 会被拒绝（profile "desktop" is managed exclusively by the Electron application）。要装进桌面 App，请从 App 内的插件界面装，或者按 App 写 package.json 的方式加 link:/依赖后由 App 重启加载 —— 别去手改它的 profile 状态。

方式二：手写 patch 行

不想用它自带的 bundle patch、或想在别人的 profile 里手动挂，就在 ~/.dsh/profiles/<name>/cordis.patch.yml（或 ~/.dsh/cordis.patch.yml）里加：

- insert:
  - id: 'ssh-hosts'
    name: 'dsh-ssh-hosts'      # 也可以写 file:///绝对路径/plugin-dev/ssh-hosts/lib/index.js
    config:
      defaultHost: web-01

config 全部字段都有默认值，只写需要覆盖的即可。

配置

主机清单有两条路，用的是同一份数据（ssh-hosts.yaml）：

• 图形界面（推荐）：装好后打开 设置 → 插件 → dsh-ssh-hosts（或设置侧栏的「SSH 主机」），在那里新增/编辑/删除主机、测试连通性、设默认机。界面写的就是下面这个 YAML，写完立即重载，不用重启。
• 手工编辑：直接改 YAML；改完在界面上点「重新读取」，或重启。

窄列下的样子：一台主机一个块，事实在上、操作在下，长路径自己断行。

界面能做的事：

能力	说明
新增 / 编辑 / 删除 / 设默认	字段校验与服务端同一套规则：错了当场红框标出并说明怎么改，不用等一次 400
测试连接	结果就地显示在那台主机下面（成功给耗时与远端首行，失败给 exit code 与原因），不用去翻底部日志
删除二次确认	在块内确认，并说清会连带清掉什么（例如「已存密码也一并清除」），不可撤销
过滤	主机多了按名称 / 地址 / 标签 / 备注 / 认证方式过滤，并显示匹配台数
键盘	Enter 保存、Esc 取消；错误是 role="alert"、日志是 aria-live，读屏能听到
密码	只写不读：显示「已保存（来自哪一层）」或「未设置」，输入可显示/隐藏，清除要再确认一次
空状态	没有主机时直接给「新增主机」按钮 + 手工编辑提示，不用猜下一步做什么

1. 主机清单（界面与手工共用的那份文件）

cp ssh-hosts.example.yaml ~/.dsh/ssh-hosts.yaml
chmod 600 ~/.dsh/ssh-hosts.yaml     # 权限不是 0600 会被拒绝加载
$EDITOR ~/.dsh/ssh-hosts.yaml

文件不存在时插件照常启动、界面照常打开，只是清单为空：在界面上新增第一台主机就会把文件建出来（0600）。文件存在但坏掉（YAML 语法错、hosts 不是数组、权限过宽）仍然是装载期硬失败 —— 那是真配置错误，越早炸越好。

version: 1

hosts:
  - name: web-01                    # ← agent 在会话里引用的名字
    host: 10.0.0.11
    user: deploy
    identityFile: ~/.ssh/id_ed25519 # 密钥登录；必须 0600。省略 = 交给 ssh-agent/默认密钥
    defaultWorkdir: /srv/app
    description: 生产 Web（Nginx）
    tags: [prod, web]
    port: 22
    proxyJump: bastion              # 本清单里的 name，或 user@host:port
    connectTimeoutSec: 15
    keepAliveSec: 30
    readOnly: true                  # 拒绝 ssh_write / ssh_edit

  - name: db-01
    host: 10.0.0.12
    user: root
    passwordRef: DSH_SSH_HOSTS_PASSWORD_DB_01   # 密码登录：只写「凭据名」，不写密码
    tags: [prod, db]

字段全部可选（name / host 必填），未知字段会直接报错，拼错不会被静默忽略。清单里写 password: / passphrase: 会被专门拒绝，并告诉你该怎么放密码。

1.1 登录方式：密钥 / 密码 / ssh-agent

方式	清单里怎么写	怎么设置
密钥（推荐）	identityFile: ~/.ssh/id_ed25519	界面「登录方式 → 密钥文件」，填路径即可（文件必须存在且 0600）
密码	passwordRef: DSH_SSH_HOSTS_PASSWORD_XXX	界面「登录方式 → 密码」，在密码框里填一次；插件把值交给 DSH 凭据库，清单里只留引用名
密钥优先、密码兜底	两个字段都给	界面选「密钥优先，密码兜底」
ssh-agent / 默认密钥	两个字段都不给	界面选「ssh-agent / 默认密钥」，交给 OpenSSH 自己挑

密码不进清单文件：$DSH_HOME/.credentials.yaml（0600，DSH 自己的凭据库）存值，ssh-hosts.yaml 只存名字。所以清单可以安全地备份/分享；界面、HTTP 响应、模型可见的工具输出里都只回报「有没有、来自哪一层」，永远不回显密码。删主机或点「清除已存密码」会顺手把凭据库里的那条删掉，不留孤儿。

密码登录的实现是 OpenSSH 官方路子（SSH_ASKPASS + 一次性 0600 文件）：密码不进命令行参数、不进环境变量、不进日志，ps 里看不到；每次调用前现解析、用完即删，所以改完密码下一次调用就生效，不用重启。没有凭据服务的 profile（极少见）插件照常工作，只是密码主机连不上，界面会说明原因。

2. 图形界面背后的 HTTP 路由

界面（浏览器半边）通过同源路由读写清单，也可以只用 curl（同一个 web server，CSRF/Host 校验与其它 GUI 接口一致）：

方法	路径	作用
GET	/ssh-hosts/hosts	清单 + 文件信息 + 是否可写 + 默认机
POST	/ssh-hosts/hosts	新增/修改一台（{ host: {...}, previousName?, password?, clearPassword? }，改名靠 previousName；password 只进不出，clearPassword: true 清除）
POST	/ssh-hosts/hosts/delete	删除（{ name }）
POST	/ssh-hosts/default	设/清默认机（{ name }，空串清除）
POST	/ssh-hosts/reload	重新读盘（手工改完文件点这个）
POST	/ssh-hosts/test	真实 SSH 连上去跑一条只读命令

返回统一是 { ok: true, value } 或 { ok: false, error: { code, message } }；400 参数/文件内容有误、409 清单来自 config 不可写、404 主机不存在、501 当前 profile 没有凭据服务（存不了密码）、403/401 未过 Host/来源/登录校验。写入顺序是先校验、再原子写、再重载，重载失败会把文件回滚成写之前的字节 —— 界面上一次误操作不会让正在跑的会话失去目标机。

3. 插件 config

字段	默认	说明
hostsFile	$DSH_HOME/ssh-hosts.yaml	清单路径；相对路径按 $DSH_HOME 解析
defaultHost	空	没指定 host、本会话也没 ssh_use 过时用的默认机
knownHostsFile	空（OpenSSH 默认）	自定义 known_hosts 路径
strictHostKeyChecking	accept-new	accept-new / yes / no
connectTimeoutSec	10	建连超时
timeoutMs	60000	单条命令默认超时
maxOutputBytes	262144	stdout/stderr 各自保留上限（超出保尾并标记截断）
maxReadBytes	8388608	单文件读取上限
controlPersistSec	300	连接复用时长；0 = 每次重建连
allow / deny	[]	ssh_run 命令正则白/黑名单（deny 优先）
hosts	[]	就地声明主机（非空时忽略 hostsFile）

这些标量字段都是 DSH 的 volatile 字段：在设置页改完不用重启插件，下一次工具调用就用新值（插件每次读配置都解包 volatile 引用）。hosts 例外 —— 它是部署方声明，改了要重启；而且它非空时界面变成只读，避免「设置页改一半、YAML 改一半」。

用：添加完主机，怎么引用

在会话窗口里直接选（新增，最快）：点输入框左边的 「+」，在命令菜单里选 ssh → 弹出主机列表（带 user@host、标签、认证方式，并标出本会话当前在用哪台）→ 点一台即可。它设的是本会话默认主机（和 ssh_use 同一条路径、同一份状态），之后你在这个会话里说「执行 uname -a」就直接落到那台机器。也可以手打 /ssh <主机名>，/ssh clear 清除。

一个平台规则：输入框里已经有内容时，「+」菜单只列不带参数的命令（ssh 带参数提示，所以那时不显示）—— 这是 DSH 对斜杠菜单的统一约定，/permission 等命令同样如此。想在已有草稿上换机器，先选中草稿前的空白再点「+」，或直接手打 /ssh <主机名>。

在会话里直接说人话也行（最常用）：

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

agent 会先 ssh_hosts() 看清单，再带上 host: "web-01" 调用对应工具。主机名就是你在界面里填的「名称」。

显式调用（想知道底层发生了什么时）：

ssh_hosts()                                        → 列主机（含 auth 方式、tags、默认目录）
ssh_use({ host: "web-01" })                        → 设为本会话默认机，之后可以省略 host
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" })

主机解析优先级：显式 host 参数 → 本会话 ssh_use → 界面设的默认机 → config.defaultHost → 报错并列出可用主机（绝不再猜一台）。界面上点「设为默认」写的就是第三档；默认机是全局的，ssh_use 是本会话的。

模型看到的 7 个工具：

工具	作用
ssh_hosts	列出可用主机（含 tags / 说明 / 默认目录 / 认证方式），可按 tag 过滤；defaultHost + defaultSource 告诉你本次调用实际会用哪台
ssh_use	读/设本会话默认主机，之后其它工具可省略 host
ssh_run	执行命令，返回 exitCode / stdout / stderr（非零退出是正常结果）
ssh_read	读文本文件，可给行号区间
ssh_write	整文件写入（远端临时文件 + rename 原子替换，保留原权限）
ssh_edit	精确字符串替换（要求唯一匹配，除非 replaceAll）
ssh_ls	列目录（类型/权限/大小/时间）

主机解析优先级：显式 host 参数 → 本会话 ssh_use → 界面设的默认机 → config.defaultHost → 报错并列出可用主机（绝不再猜一台）。

三种方式的作用域要分清：会话窗口的「+ → ssh」和 ssh_use 是「本会话」（互不干扰，换会话就没了）；设置页的「设为默认」是全局（所有没有会话默认的会话都用它）。ssh_hosts 报的 defaultHost 是本次调用实际会用的那台（会话默认 → 全局默认 → config.defaultHost），defaultSource 告诉你是哪一档。

readOnly: true 的主机会拒绝 ssh_write / ssh_edit（ssh_run 不受限，见下面「安全边界」）。命令的 allow / deny 白黑名单由部署方在插件 config 里配，命中 deny 时工具直接拒绝并说明原因。

界面上每张主机卡片下面还有一段「怎么用」，会带着这台机器的名字把上面的引用方式印出来，不用记。

安全边界（重要）

• 秘密与配置分家：ssh-hosts.yaml 里只有路径和凭据名，永远没有密码或密钥内容。密码值存在 DSH 凭据库 $DSH_HOME/.credentials.yaml（0600），只有插件按名字去 ctx.credentials 解析；界面/HTTP/工具输出里从不回显值。密钥的 passphrase 仍由 ssh-agent / 系统钥匙串负责。
• 密码只走 OpenSSH 官方通道：SSH_ASKPASS 指向插件临时生成的助手脚本，密码放在同一 0700 临时目录里的 0600 文件，不进 argv、不进 env、不进日志，调用结束（含异常）立刻整目录删除；NumberOfPasswordPrompts=1 保证密码错了只试一次，不会撞锁。模型侧没有任何能设置或读取密码的工具 —— 只有你在界面里能填。
• 权限即护栏：清单文件 0600、identityFile 必须 0600，否则拒绝加载 —— 这两条是刻意做成硬失败的（界面写文件时自动 0600、目录 0700）。
• 界面就是本机操作员：/ssh-hosts/* 路由先过 connection.requestRejection（Host/来源校验 + 浏览器登录态），过不了直接 403/401；与其它 GUI 接口同一道门。它只在本机 loopback web server 上暴露。
• readOnly 只是给模型的护栏，不是沙箱：它只拦 ssh_write / ssh_edit；ssh_run 里照样能 tee。真正的边界是远端账号权限 + DSH 的审批/日志。
• allow / deny 是部署方的运维约定，同样不是安全边界（正则拦命令永远可以绕过）。
• 断连即失败，不重连不重放：远端是否已执行无法确认，自动重试可能让命令生效两次。
• 输出有上限：ssh_run 超限保尾部并标记 truncated；ssh_read 超限直接拒绝（不把大文件拉回本地）。
• 每条命令都经过 DSH 的审批与日志链路，与本地 Bash 工具同级别。
• /ssh 命令只改「本会话用哪台机器」，不碰清单、不碰凭据：它和 ssh_use 工具写的是同一份会话状态（ssh-hosts.state.json），并且会留下一条持久化的命令节点（command/run + command/done），可审计、可回溯。

测试

npm install
npm test                      # 211 个单测：配置 / 清单 / 会话状态 / 传输层（含密码 askpass）/ 业务逻辑 / 工具契约 / /ssh 命令 / cordis 装载 / 界面链路 / 浏览器半边

真实服务器集成测试（默认跳过）：

DSH_SSH_HOSTS_REMOTE=1 node --test test/remote.test.mjs
# 密码认证那一条要显式给密码（只从环境变量读，不落盘、不进仓库）：
DSH_SSH_HOSTS_REMOTE=1 DSH_SSH_HOSTS_REMOTE_PASSWORD='...' node --test test/remote.test.mjs
node scripts/smoke-remote.mjs            # 把模型会看到的每一步原样打出来
node scripts/smoke-ui.mjs                # 界面链路：路由新增主机 → 真连测试 → 工具立刻能用 → 删除
DSH_SSH_HOSTS_REMOTE_PASSWORD='...' node scripts/smoke-ui.mjs   # 额外跑一遍「界面填密码 → askpass → 真 ssh」

smoke-ui.mjs 走的是「在设置里点一下」的完整路径（HTTP 路由 → service → 写 YAML → 重载 → 工具发起真实 SSH），清单文件用临时目录里的一份，不碰 ~/.dsh/ssh-hosts.yaml。

覆盖目标机可用环境变量覆盖：DSH_SSH_HOSTS_REMOTE_HOST / _USER / _PORT / _KEY / _KNOWN_HOSTS。

测试机准备

只做一次，全程只用密钥：

ssh-keygen -t ed25519 -N '' -f .test-keys/id_ed25519      # 已在仓库里生成过
ssh-copy-id -i .test-keys/id_ed25519.pub ubuntu@your-host # 或手工追加到远端 authorized_keys
ssh -i .test-keys/id_ed25519 -o IdentitiesOnly=yes ubuntu@your-host 'echo KEY_OK'

~/.ssh 不可写、或需要非交互装公钥时（CI / 沙箱里 pty 被禁），用 SSH_ASKPASS 而不是 sshpass：

SSH_ASKPASS=$PWD/.test-keys/askpass.sh SSH_ASKPASS_REQUIRE=force \
  ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no ubuntu@your-host \
  'mkdir -p ~/.ssh; touch ~/.ssh/authorized_keys; cat >> ~/.ssh/authorized_keys; chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys' \
  < .test-keys/id_ed25519.pub

故障排查

现象	处理
主机清单不存在	复制示例文件并 chmod 600，或用 config 里的 hosts: [...]
主机清单权限过于宽松 / identityFile 权限过于宽松	按提示 chmod 600
认证失败（auth）	检查 user / identityFile，或 ssh-add 载入密钥；密码主机看下一条
配置为密码登录，但凭据 … 还没有值	在设置界面「SSH 主机」里给这台机器填一次密码（模型侧故意不能设密码）
界面提示「当前 profile 没有 credentials 服务」	该 profile 没装凭据库：改用密钥/ssh-agent，或在桌面应用里配置
「+」菜单里找不到 ssh	该 profile 的 commands 服务缺失（裁剪过的组合），或命令名被别的插件占了；手打 /ssh <主机名> 同样可用，工具本身不受影响
主机指纹校验失败（hostkey）	目标机重装过：清理对应 known_hosts 条目（或用 knownHostsFile 单独放一份）
超时（timeout）	调大 connectTimeoutSec（建连）或调用参数 timeoutMs（命令）
命令 exit 66	远端 cwd 不存在（插件用 cd ... || exit 66 区分「进不去目录」和「命令失败」）

已知边界

• 传输用系统 ssh/sftp 客户端，因此没有 Windows 支持（Windows 上没有这两个命令行程序）。
• 带 passphrase 的密钥依赖 ssh-agent 预先载入；插件不做交互式输入。
• 文件工具限于 UTF-8 文本；二进制/大文件请用 ssh_run + 远端工具处理。
• 不做端口转发 / 隧道 / 交互式 shell 会话（每次调用一条命令，靠 ControlMaster 摊掉握手成本）。
• 界面卡片按窄列设计（设置侧栏那种宽度）：主机是纵向堆叠的块，字段自动换行，不会出现横向滚动。
• 官方另有一套 provider 形态的 @deepseek-ai/dsh-ssh / dsh-fs-ssh / dsh-subprocess-ssh / dsh-sandbox-ssh：它们把 ctx.fs / ctx.subprocess 整体换到单台远端机，属于「部署组合」而非多机工具。本插件与它们不冲突，也不依赖它们。

许可证

MIT（见 LICENSE）。测试机相关的主机名/用户/密钥路径在仓库里都是占位值，通过 DSH_SSH_HOSTS_REMOTE_* 环境变量传入；真实凭据从不入库。