dsh-vps-hub

DeepSeek Harness 的 VPS Hub 插件 —— 在本地维护云服务器 SSH 台账,让 Agent 能够发现、测试、执行命令、传输文件,并提供可选的设置页 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/keys 私有文件(0600)并以路径引用 —— 绝不存入台账。
• 密码永不落盘(对标 Orca):密码仅存在于进程内存(插件生命周期内),通过 SSH_ASKPASS 协议经子进程环境交给 ssh —— 不进 argv、不进文件,重启即失。
• 代理支持:每台服务器可带 ProxyJump(-J)与 ProxyCommand,覆盖跳板机与 SOCKS/HTTP 代理。

---

安装

📖 完整中文图文安装指南(验证输出、常见问题、升级/卸载):docs/INSTALL.zh.md

环境要求(Prerequisites)

• macOS / Linux,系统 ssh、scp;Windows 支持密钥认证(OpenSSH Client;密码认证仅 POSIX —— SSH_ASKPASS 桥接为 shell 脚本)。动态插件示例仅 POSIX。
• DSH 0.1.0-rc.x,使用 web profile
• 可写的 DSH profile 目录(如 ~/.dsh/profiles/web)
• 至少一台可用 SSH 登录的服务器(密钥认证,或按会话提供密码)

方式 A —— npm 包(正式安装,Agent 工具面)

第 1 步:安装到你的 DSH profile:

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 是 一个空列表,由补丁层组合而成 —— 请编辑补丁文件,不要动根文件。

配置项:

字段	类型	默认值	说明
dataFile	string	~/.dsh/vpshub-targets.json	台账 JSON 路径覆盖
maxOutputBytes	number	100000	返回给模型的单条命令输出上限
connectTimeoutSec	number	8	ssh/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),可加载已验证的示例动态插件:

1. 打开 examples/dynamic-plugin/ —— host.js(工具 + RPC)与 client.js(设置页 UI)。
2. 调用 cordis_define:把 host.js 中 apply() 的函数体粘贴进 code.host(return { name: 'vps-hub', apply: <函数体> }),把 client.js 的函数体粘贴进 code.client(return { name: 'vps-hub-ui', apply: <函数体> })。
3. cordis_run 并批准 client 半部分(一次性 UI 授权)。
4. 打开 设置 → VPS Hub —— 8 个工具同时在本会话生效。

动态插件是会话级的:DSH 重启后消失(台账文件保留)。

已安装 npm 包?用 UI-only 叠加版 —— ui-only-host.js + client.js 只增加设置页(不注册工具,与正式包工具不冲突)。客户端需一次性批准;若部署禁用了审批,请临时将会话权限模式切到 workspace-write/ask,批准后再切回。

完整说明见 examples/dynamic-plugin/README.md。

验证安装

方式 A 安装完成后,任选一种方式确认:

# 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 说:

你说	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_download	scp 双向文件传输(可选 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/<pid>/environ —— 请把密码视为对以你身份运行的一切进程可见。密码模式仅 POSIX(Windows 会明确报错)。
• 密码仅存内存、永不落盘;askpass 桥接脚本位于 ~/.dsh/.vpshub-askpass.sh(0700),从子进程环境读取密码。重启 DSH 即清空全部缓存密码。
• 粘贴密钥是权衡:identityKeyContent 会经过模型调用(工具参数),条件允许时优先使用密钥路径。保存的内容位于 ~/.dsh/keys/<id>.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 全流程(发现 → 测试连接 → 添加 → 删除 → 别名预填)。

安全

见 SECURITY.md:安全模型、加固建议与漏洞报告方式。

更新日志

见 CHANGELOG.md。

版本历史

• 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

MIT