deepseek-harness-desktop/packages/dsh-ssh

156Star5Fork6Issue0Watching

为 dsh Web GUI 增加完整 SSH 运维能力:主机管理、持久连接池、命令执行、Web 终端、SFTP 文件传输、本地端口转发、集群并发执行,以及 6 个共享主机配置的 Agent 工具。

机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科

此插件是大仓库 ningbainb/deepseek-harness-desktop 的子包,星数与活跃度统计的是整个仓库。

语言
TypeScript
License
BSD-3-Clause
分支
main
ai-agentai-coding-assistantcodexdeepseekdeepseek-harnessdesktop-appdshdsh-plugin

安装

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

在终端中运行以上命令,通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh?看这篇新手教程

对话式安装

帮我安装 DeepSeek Harness 插件 ningbainb/deepseek-harness-desktop/packages/dsh-ssh:先查看仓库 https://github.com/ningbainb/deepseek-harness-desktop.git 确认安全性,然后执行安装命令并验证插件加载成功。

把这段指令粘贴给 DSH Web GUI 里的助手,由它代你完成安装与验证。

一句话定位

为 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.7package.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 可能把远端环境中的密钥带回对话记录。

收录徽章

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-ssh)

把这段 markdown 粘贴到你的 GitHub README,链接回本插件详情页。徽章只声明已被本站收录,不代表安全认证。

返回插件目录