DSH Hub / 插件 / dsh-vps-hub Sdongmaker/vpshub ↗ ★ 0
dsh-vps-hub VPS Hub for DeepSeek Harness: manage your cloud-server SSH ledger, import hosts from ~/.ssh/config, and let agents discover, test, execute commands on, and transfer files to your servers. Private keys stay local as path references only. Optional Settings-page UI via the dynamic-plugin example.
包名 dsh-vps-hub
版本 0.1.3
许可证 MIT
最近更新 2026年8月14日 GitHub ↗ 网站 ↗ 文档 ↗ dsh-vps-hub
DeepSeek Harness 的 VPS Hub 插件发现、测试、执行命令、传输文件 ,并提供可选的设置页 UI ,对标 Orca 的 SSH 远程主机管理体验。
Agent 工具 vps_list vps_import_ssh_config vps_add vps_remove vps_test vps_exec vps_upload vps_download设置页 UI 可选 —— 设置 → "VPS Hub" 页面(服务器卡片、测试连接、~/.ssh/config 别名预填表单、删除) 存储 单一 JSON 台账,Orca 风格:source: ssh-config | manual、删除 tombstone、别名抑制 认证 密钥路径 · 粘贴密钥内容(私有保存到 ~/.dsh/keys,0600)· 密码(仅内存,对标 Orca) 代理 每台服务器支持 ProxyJump 与 ProxyCommand
为什么
Agent 可发现 :vps_list / vps_import_ssh_config 让 Agent 直接找到你的服务器,无需重复录入连接信息;vps_exec / vps_upload / vps_download 让它可以实际操作(部署、巡检、看日志、传文件)。Orca 式管理 :设置页对标 Orca 的 Settings → SSH —— 从 ~/.ssh/config(支持 Include 展开、*/? 通配、Host * 兜底)选一台主机即可自动预填表单;已保存的主机带"已在台账"标记。零新守护进程 :执行直接调用系统 ssh / scp。正式包用 execFile(无 shell 拼接);动态插件版用 DSH shell 服务。密钥留在本机 :台账只存 identityFile 路径引用 ;粘贴的密钥内容 写入
dsh-vps-hub · DSH Hub
~/.dsh/keys
密码永不落盘 (对标 Orca):密码仅存在于进程内存(插件生命周期内),通过 SSH_ASKPASS 协议经子进程环境交给 ssh —— 不进 argv、不进文件,重启即失。
代理支持 :每台服务器可带 ProxyJump(-J)与 ProxyCommand,覆盖跳板机与 SOCKS/HTTP 代理。
安装
环境要求(Prerequisites)
macOS / Linux,系统 ssh、scp 在 PATH 中(暂不支持 Windows)
DSH 0.1.0-rc.x,使用 web profile
可写的 DSH profile 目录(如 ~/.dsh/profiles/web)
至少一台可用 SSH 登录的服务器(密钥认证,或按会话提供密码)
方式 A —— npm 包(正式安装,Agent 工具面) cd ~/.dsh/profiles/web # 你的 profile 目录
npm install dsh-vps-hub # 或: pnpm add dsh-vps-hub
第 2 步:在 cordis.patch.yml 中挂载 (profile 根目录,如 ~/.dsh/profiles/web/cordis.patch.yml):
- insert:
- id: vps-hub
name: 'dsh-vps-hub'
# 以下均为可选配置,缺省即可用:
config: {}
# 可选字段(默认即可用):
# dataFile: '~/.dsh/vpshub-targets.json' # 台账文件路径覆盖
# maxOutputBytes: 100000 # 单条命令输出上限(字节)
# connectTimeoutSec: 8 # ssh/scp 连接超时(秒)
第 3 步:重启(HMR 重载)profile ,然后按下方"验证安装"确认。
为什么改 cordis.patch.yml 而不是 cordis.yml? profile 根 cordis.yml 是
一个空列表,由补丁层组合而成 —— 请编辑补丁文件,不要动根文件。
字段 类型 默认值 说明 dataFilestring ~/.dsh/vpshub-targets.json台账 JSON 路径覆盖 maxOutputBytesnumber 100000返回给模型的单条命令输出上限 connectTimeoutSecnumber 8ssh/scp 连接超时(秒)
npm update dsh-vps-hub # 升级
npm install dsh-vps-hub@latest # 显式升级
npm uninstall dsh-vps-hub # 卸载 —— 同时删除 cordis.patch.yml 中的挂载行
方式 B —— 动态插件(会话级,含设置页 UI) 想要 设置 → VPS Hub 页面 而暂不安装包(或先试用 UI),可加载已验证的示例动态插件:
打开 examples/dynamic-plugin/ —— host.js(工具 + RPC)与 client.js(设置页 UI)。
调用 cordis_define:把 host.js 中 apply() 的函数体粘贴进 code.host(return { name: 'vps-hub', apply: }),把 client.js 的函数体粘贴进 code.client(return { name: 'vps-hub-ui', apply: })。
cordis_run 并批准 client 半部分(一次性 UI 授权)。打开 设置 → VPS Hub —— 8 个工具同时在本会话生效。
验证安装 # 1) Agent 能看到工具 —— 在会话中直接问:"列出我的服务器"
# 2) 仓库冒烟测试(读取你的真实台账,需克隆仓库):
node examples/smoke.mjs
# 3) 首次 vps_add / vps_test 后台账文件出现:
ls -l ~/.dsh/vpshub-targets.json
预期结果:vps_list 返回你的服务器(或空列表);vps_exec 能在服务器上执行只读命令(如 hostname);方式 B 下设置页显示台账。
环境要求
macOS / Linux(需要系统 ssh、scp;暂不支持 Windows)
DSH 0.1.0-rc.x(web profile)
密钥认证,或按会话提供密码(仅内存)
快速开始 你说 Agent 执行 "列出我的服务器" vps_list"导入我的 ssh config" vps_import_ssh_config"把 ssh config 里的 hk-prod 加进来" vps_add { alias: "hk-prod" }"阿里云那台在线吗?" vps_test { id }"在阿里云上跑 df -h" vps_exec { id, command: "df -h" }"把 app.tar.gz 传到 OVH 那台" vps_upload { id, localPath, remotePath }"用我粘贴的这把密钥加一台 VPS" vps_add { host, username, identityKeyContent: "-----BEGIN …" }"用密码测试那台机器 …" vps_test { id, password }(或 vps_add 时设置,仅内存)
工具 工具 用途 vps_list列出台账服务器(不含密钥内容);按标签/文本过滤;可选 withStatus 连通探测(逐台返回延迟) vps_import_ssh_config扫描 ~/.ssh/config(含 Include)列出可导入主机,带 alreadyInLedger 标记 vps_add从 config 别名或手动字段添加(主机/端口/用户/密钥路径/粘贴密钥/密码/跳板/代理命令);可选保存前 test vps_remove删除服务器,保留 tombstone + 别名抑制,便于干净地重新添加 vps_test非交互连通检测(可选 password),返回延迟;更新 lastSeenAt vps_exec在服务器上执行一条 shell 命令(可选 password;输出默认截断到 100KB) vps_upload / vps_downloadscp 双向文件传输(可选 password)
存储 单一 JSON 文档 —— 默认 $DSH_HOME / ~/.dsh/vpshub-targets.json(可用 dataFile 覆盖):
{
"version": 1,
"targets": [
{
"id": "vps-1786641416471-a1b2c3",
"label": "aliyun-prod",
"configHost": "orca", // 从 ~/.ssh/config 导入时的别名
"host": "1.2.3.4",
"port": 22,
"username": "root",
"identityFile": "~/.ssh/id_ed25519", // 仅路径
"source": "ssh-config" | "manual", // ssh-config 来源随导入刷新;manual 永不被覆盖
"tags": ["aliyun", "prod"],
"note": "...",
"lastSeenAt": 1786641416471,
"createdAt": 1786641416471,
"updatedAt": 1786641416471
}
],
"removedTargets": [], // tombstone,便于干净地重新添加
"deletedConfigAliases": [] // 删除后抑制重新导入的别名
}
与 Orca 的 SSH 目标模型(orca-data.json)同构:ssh-config 来源的目标每次导入刷新,manual 目标永不被覆盖;删除主机时记录 tombstone + 别名抑制,重新添加保持干净。
安全说明
密钥认证全程非交互(BatchMode=yes);密码认证使用 NumberOfPasswordPrompts=1 + SSH_ASKPASS_REQUIRE=force。主机密钥默认 accept-new;可在插件配置开启 strictHostKeyChecking: true 严格校验 known_hosts(防 MITM)。
proxyCommand 由 ssh 通过本地 shell 执行(设计如此)%h/%p 占位符;请视为可信代码。密码经子进程环境传递 (VPS_PASSWORD -> SSH_ASKPASS):POSIX 下同用户进程可读 /proc/ /environ —— 请把密码视为对以你身份运行的一切进程可见。密码模式仅 POSIX(Windows 会明确报错)。密码仅存内存、永不落盘;askpass 桥接脚本位于 ~/.dsh/.vpshub-askpass.sh(0700),从子进程环境读取密码。重启 DSH 即清空全部缓存密码。
粘贴密钥是权衡 :identityKeyContent 会经过模型调用(工具参数),条件允许时优先使用密钥路径 。保存的内容位于 ~/.dsh/keys/.key(0600,目录 0700),绝不回显。正式包把远程命令作为单个 argv 元素 传给 execFile —— 远程命令无法注入本地 shell 语法。
台账文件原子写入,权限 0600。请照常保持 identityFile 权限 0600。
远程执行是真正的"强力工具":模型可以在你添加的服务器上执行任意命令。如需确认门槛,请配合 DSH 的权限/审批层使用。
项目结构 dsh-vps-hub/
├── docs/
│ ├── INSTALL.zh.md # full Chinese install guide
│ └── PLUGIN-DEV-GUIDE.md # 插件开发→测试→发布实战指南(本项目真实经验沉淀)
├── src/
│ └── index.js # 正式包 host 插件(execFile 实现)
├── examples/
│ ├── cordis.patch.yml # profile 挂载示例(方式 A)
│ ├── dynamic-plugin/ # 已验证的会话插件:设置页 UI + 工具(方式 B)
│ │ ├── README.md
│ │ ├── host.js
│ │ └── client.js
│ └── smoke.mjs # 冒烟测试(node smoke.mjs,针对真实台账)
├── package.json
├── README.md / README.zh.md
└── LICENSE
开发与测试 npm install # 开发依赖(zod、@deepseek-ai/dsh-tools)
node --check src/index.js
node examples/smoke.mjs # 在假 ctx 上注册工具、读取真实台账、执行只读 vps_exec
核心逻辑已在真实 DSH 会话中对真实服务器做过端到端验证:导入 → 添加 → 列表+状态 → 测试 → 执行 → 上传 → 下载 → 删除,以及设置页 UI 全流程(发现 → 测试连接 → 添加 → 删除 → 别名预填)。
安全
更新日志
版本历史
v0.1.0 → v0.1.1(加载崩溃修复) :v0.1.0 读取 ctx.config 被 Cordis Guard 拒绝,导致 loader entry 失败、整个 Web 进程退出。v0.1.1 改用官方 apply(ctx, config) 签名。若你仍在使用 v0.1.0,请升级:npm install dsh-vps-hub@latest。v0.1.1 → v0.1.2(YAML null 配置修复) :裸 config: 只有注释时 YAML 解析为 null;zod Config 已改为容忍 null(.nullish()),文档示例统一为 config: {}。
已知限制
暂不支持 Windows(依赖系统 ssh/scp)。
密码认证经 SSH_ASKPASS 支持,但密码仅存内存:DSH 重启后需重新输入(Orca 同样如此)。
设置页 UI 目前以动态插件示例形式提供,尚未打进 npm 包 —— 正式包内置 client 需要 Typert Remote 装饰器管线(TypeScript 构建),计划后续版本实现。
~/.ssh/config 解析支持 Include、*/? 通配与 Host * 兜底;更复杂的 OpenSSH 语义(如 Match、hostname 链式解析)未实现 —— 此类主机可用 vps_add 显式字段手动添加。
License 
