deepseek-harness-desktop/packages/dsh-ssh

一句话定位

为 dsh Web GUI 加入一套完整的 SSH 运维能力：在 Web 端集中管理多台远程主机（增删改查、搜索、连接测试、一键导入 ~/.ssh/config），在 host 进程内复用持久 ssh2 连接池执行命令、跑 Web 终端、SFTP 传文件、开本地端口转发隧道，并能在多台主机上并发跑同一条命令；同时为 Agent 提供 6 个工具调用同一份主机配置。

核心能力

主机增删改查、搜索、连接测试；支持密钥 / 密码认证、passphrase 密钥、ProxyJump 多级跳板机
一键导入 ~/.ssh/config：解析 Host / HostName / User / Port / IdentityFile / ProxyJump 等字段，已有别名自动跳过
持久 ssh2 连接池：每台主机复用一条长连接（不每次重连），空闲 30 分钟自动断开，断线自动重连（最多 3 次）
命令执行：单主机 exec 带超时（默认 60s，可覆盖）、stdout/stderr 分离、单次输出 2MB 截断保护；集群并发执行（默认并发 8，可按 alias/环境/标签过滤）
Web 终端（xterm.js + WebSocket PTY，背压自动暂停/恢复）、SFTP 文件传输（上传走 NDJSON 进度流，下载返回二进制流）、本地端口转发隧道（仅 127.0.0.1 监听，访问远程数据库 / 内网服务）、Linux 主机实时监控（CPU / 内存 / 磁盘 / 负载 / 进程 / systemd 异常，3 秒刷新）
Agent 工具 ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster，GUI 与 Agent 共享同一份主机配置

技术实现

语言: TypeScript
关键依赖: ssh2（Node 端 SSH 客户端）、@xterm/xterm + @xterm/addon-fit（浏览器终端）、ws（WebSocket 升级以承载 PTY）、@deepseek-ai/dsh-tools（Agent 工具定义）
架构模式: 双半区 cordis 插件——host 半区（src/index.ts）启动 SshEngine、注册 /api/dsh-ssh/* 路由与 WebSocket 终端、注册 6 个 Agent 工具、注入系统提示词；client 半区（src/client/index.ts）通过 DOM 注侧边栏入口 + 挂载 React 面板（六个标签页）。通过 cordis.patch.yml 在 web profile 注入 id: ssh 的 bundle 行，仅修改 DSH 服务发现，不改 DSH 源码。
入口文件: packages/dsh-ssh/src/index.ts（host 半区），packages/dsh-ssh/src/client/index.ts（browser 半区）

适用场景

当用户在 dsh Web GUI 里需要同时管多台远程服务器时，这个插件能把 SSH 主机配置、远程命令、Web 终端、文件传输、端口转发全部集中到浏览器里，配合 Agent 工具让 AI 也能在同一份主机配置上做远程操作。典型场景：运维同学一次性导入已有 ~/.ssh/config，在浏览器里就能跨多台机器完成服务状态巡检、批量脚本下发、文件分发、内网数据库端口转发。

前置依赖与兼容性

依赖	最低版本	说明
Node.js	^22.19.0 \|\| >=24.0.0	来自 package.json engines 字段
DSH（官方 SDK）	通过 devDependencies 锁到 ^0.1.0-rc.7	package.json 未声明 dsh.engines，需 DSH 0.1.0-rc.7+ 才能解析所有运行时注入
React	^18.2.0（peerDependencies）	浏览器半区面板运行环境
平台	跨平台	host 半区跑 Node.js；client 半区跑浏览器；ssh2 是纯 JS 库，无原生模块限制
原生模块	无	运行时无原生 Node 模块；ssh2 是纯 JS 的 SSH 客户端，不引入 native 绑定

安装方式

dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-ssh

配置项

配置	类型	说明	默认值
`enabled`	开关	总开关：关闭后所有路由、Agent 工具、系统提示词声明全部停止挂载	true
`announceToAgent`	开关	是否在系统提示词里向 Agent 声明本插件的能力与限制；关闭后 Agent 看不到 SSH 工具	true
主机别名	字符串	openpanel/侧边栏/Agent 都按这个别名调用，规则：字母开头的字母/数字/点/中划线/下划线	用户在 GUI 中配置
`~/.ssh/config` 导入	一次性操作	在主机管理页一键导入；已有别名自动跳过	—

引擎自身还有 8 个运行时常量（空闲超时 30 分钟、连接超时 15s、keepalive 15s、最大输出 2MB、exec 默认超时 60s、集群默认并发 8、SFTP 并发 8、keepalive 失败 3 次断开），这些是 host 内部硬编码，不暴露给用户设置。

常见问题

Q: 在局域网里别人能访问我的 SSH 控制台吗？

A: 不能。所有 /api/dsh-ssh/* 路由都做了 loopback 校验（socket 必须是 127/8 或 ::1，再加同源 Host/Origin 头校验），LAN 邻居直接访问会被拒绝；本地端口转发隧道也只监听 127.0.0.1，不会暴露到外网。

Q: 密码是怎么保存的？会被别人看到吗？

A: 以明文存于 ~/.dsh/dsh-ssh.json（文件权限 0600、目录 0700，原子写入），与 ssh-skill 在 ssh-config 注释里写密码同一信任模型。设计上不做额外加密，理由是加密反而引入新密钥管理负担；用户应保证本机账户安全。

Q: Agent 会不会跑去我没配置的主机上执行命令？

A: 不会。Agent 只能操作 GUI 已配置或从 ~/.ssh/config 导入的主机别名；别名未配置时工具调用直接报错，不会臆造主机——这一点在系统提示词里被显式声明。

Q: 远程命令超时或者输出很大怎么办？

A: exec 默认超时 60 秒（可覆盖），超时后会向远端 stream 发送 KILL 并强制收尾；单次 stdout/stderr 累计超过 2MB 会自动截断并标记 [output truncated]，避免一条命令挤出几 GB 把进程撑爆。

Q: 跳板机和集群执行怎么用？

A: 主机配置里填 proxyJump 数组（每一跳必须是本插件已配置的主机别名），引擎会按顺序 forwardOut 链式连接。集群执行在「集群」标签或 ssh_cluster 工具里按 alias / 环境 / 标签过滤，标签用 ALL 语义全匹配，默认并发 8 可调整。

Q: 卸载插件会清掉我配置的主机吗？

A: 不会自动删除。~/.dsh/dsh-ssh.json 是用户数据文件，插件装卸只影响引擎、路由、Agent 工具的挂载与注销；想清干净需手动删除或重命名该文件。

上手难度

进阶 — 配置主机、密钥、跳板机要懂 SSH 基础；GUI 内的主机管理、终端、文件传输都很直接，但是 Agent 工具与系统提示词的协作模型需要花点时间理解。

已知问题与限制

上传文件的远程目标路径必须是绝对路径（相对路径会在上传入口直接报错）。
下载暂不支持整个目录（逐文件下载）；上传支持目录递归（walk 本地目录逐文件传）。
exec 断线自动重连（最多 3 次）可能重放非幂等命令，长任务（部署、数据库迁移）使用前请确认幂等性。
ProxyJump 跳板机的每一跳必须是本插件已配置的主机别名，不能直接写 IP / 域名。
断点续传（resume）暂未实现。
Agent 工具的 ssh_upload / ssh_download 路径是宿主机器本地路径（不经 bash 沙箱），与 ssh-skill 相同的语义，注意该权限面。
exec / cluster 的远程输出原样返回（不脱敏），命令如 env 可能把远端环境中的密钥带回对话记录。

Install