远程 SSH 工具 Sycada/dsh-remote-ssh-tools

dsh-remote-ssh-tools

为 DeepSeek Harness（含 DSH Desktop）而生的 SSH 会话管理插件：集中保存连接档案，让 Agent 能一键连服务器执行命令、开交互终端、传文件——所有秘密只存 DSH 凭据中心，界面与对话中永不出现明文。

版本：0.1.2 · License：MIT · 更新日志见 CHANGELOG.md

功能一览

- 连接档案管理集中维护 SSH 档案（名称/分组/主机/端口/用户/认证方式/私钥路径/备注），随开随用。
- Agent 一键执行（ssh_run）对话里说“连生产服务器跑 df -h”，Agent 自动选档案执行并返回输出；支持退出码、stderr、超时、输出截断、主机密钥校验。
- 交互式终端在设置页点“打开终端”，或在对话里让 Agent 用 ssh_session_open 打开——浏览器内 xterm 终端直连远端 shell，支持窗口缩放，会话跨页面刷新保活，关闭即结束远端会话。
- 文件传输（SFTP） ssh_sftp_upload / ssh_sftp_download / ssh_sftp_list，上传可自动创建远端目录，下载默认防覆盖。
- 凭据安全密码与私钥口令只以引用名写入 DSH 凭据中心（~/.dsh/.credentials.yaml）；档案、工具参数、系统提示词与输出中均不出现密钥值，密码也绝不进进程命令行。
- 主机密钥指纹缓存首次连接自动记录指纹（accept-new），支持 strict 模式；指纹不符直接拒绝并提示（防中间人）。
- 即插即用的系统提示词插件会向每个会话宣告可用工具与已存主机清单，Agent 无需任何配置即可在需要远程操作时自动选用。

安装

方式一：GitHub 依赖安装（推荐）

本插件通过 GitHub 仓库（Sycada/dsh-remote-ssh-tools）发布，包名 dsh-remote-ssh-tools，未发布到 npm。
注意：npm 上另有名为 dsh-remote-ssh 的包（0.1.0–0.2.4，Apache-2.0），属于另一个项目（Yan-Zero/dsh-remote-ssh），与本插件无关，请勿混淆。

在 DSH profile 的 package.json 中引用 GitHub 依赖并加入 bundle：

"dependencies": {
"dsh-remote-ssh-tools": "https://github.com/Sycada/dsh-remote-ssh-tools.git#v0.1.2"
},
"dsh": { "profile": { "bundles": [ /* ...原有项... , "dsh-remote-ssh-tools" ] } }

在 profile 目录执行 pnpm install 后重启 DSH。

方式二：本地文件依赖（开发/预发布验证）

将源码解压到本地目录，在 profile 的 package.json 中使用：

"dsh-remote-ssh-tools": "file:D:/path/to/dsh-remote-ssh-tools"

pnpm install 后重启；迭代改代码后需重跑 pnpm install 同步到安装副本。

1. 编辑 ~/.dsh/profiles//package.json：
- dependencies 增加："dsh-remote-ssh-tools": ""
- dsh.profile.bundles 增加："dsh-remote-ssh-tools"
2. 在 profile 目录执行 pnpm install
3. 重启 / 重载该 profile（新增 bundle 属组合变更，重启最稳）

客户端模块由 DSH 自动发现并按内容哈希提供，无需重建 Harness 的 Web 壳。

安装后：设置左侧导航出现 Remote SSH 页面；Settings → Plugins 出现可折叠的 Remote SSH 卡片。

快速开始

1. 打开 Settings → Remote SSH → 新建档案：填名称、主机、端口(默认22)、用户、认证方式。
2. 保存后，在下方 设置凭据 中为该档案保存密码/私钥口令（值进入 DSH 凭据中心，不回显）。
3. 点 测试 验证连通。
4. 三种用法随你选：
- Agent：对话里说“用 test 档案跑 uptime”，或让 Agent ssh_sftp_upload 传文件；
- 终端：点“打开终端”，或让 Agent 执行 ssh_session_open 后用 sidebar_open 把终端页开进侧边栏；
- SFTP：让 Agent 列出远端目录、上传/下载文件。

Agent 工具（共 13 个）

| 工具 | 作用 |
| ssh_profile_list / add / update / remove | 档案增删改查 |
| ssh_profile_test | 连通性 + 认证快速探测 |
| ssh_secret_status | 只报告凭据引用是否已设置（永不显示值） |
| ssh_run | 远程执行一条命令并返回 stdout/stderr/退出码/耗时 |
| ssh_session_open / list / close | 交互会话：打开、列出、关闭 |
| ssh_sftp_list / upload / download | SFTP：列目录、上传（可自动建目录）、下载（默认防覆盖） |

约定：
- 目标优先用已保存的 profile id；也可直接给 host（+user/port/auth 引用）。
- 绝不要求用户把密码/密钥贴进对话：只接受 passwordRef 等引用，值在凭据中心。
- 交互长任务（编辑器/tmux/服务日志）用 ssh_session_open；单条命令用 ssh_run。

凭据与安全设计

- 档案 JSON 不含任何秘密；密码/口令经 DSH 凭据中心保存（~/.dsh/.credentials.yaml，属主权限）。
- 密码引用（passwordRef）是引用名而非密码本身；合法命名：字母/数字/下划线，以字母或下划线开头（如 DSH_REMOTE_SSH_TOOLS_TEST_PASSWORD）。非法命名在保存/写入前即被拒绝。
- 删除档案时可选“同时清除其凭据”；同一引用被多个档案共用时自动跳过，避免误删。
- ssh2 通道内认证（密码/私钥），密钥不进 argv/日志/工具输出；交互终端为纯 JS PTY 仿真（xterm），跨平台。
- 主机密钥：默认 accept-new 并缓存；hostKeyPolicy: strict 时未知主机拒绝、指纹不符报错。
- 全部 HTTP/WS 路由受 DSH 浏览器信任围栏保护；会话以不可猜 token 校验；卸载插件即断开全部会话。
- 命令超时、输出上限、并发会话数均有默认约束并可配置。

配置（cordis.patch.yml 中插件 config）

| 键 | 默认 | 说明 |
| sshPath | "" | 自定义 ssh 二进制路径（仅展示用；执行引擎为内置 ssh2） |
| connectTimeoutMs | 15000 | 连接超时 |
| keepaliveMs | 30000 | keepalive 间隔 |
| runTimeoutMs | 120000 | ssh_run 单命令超时 |
| runOutputLimit | 1048576 | stdout/stderr 上限（超出截断并标记） |
| maxSessions | 8 | 并发交互会话上限 |
| terminalScrollback | 5000 | 终端回滚行数（页面参数） |
| hostKeyPolicy | accept-new | accept-new | strict |
| trustedHosts | [] | 额外信任来源（LAN 部署时） |
| defaultUser | "" | 档案未指定用户时的默认用户 |

数据位置

- ~/.dsh/dsh-remote-ssh-tools/store.json：连接档案 + 主机密钥指纹缓存（原子写入）。
- ~/.dsh/.credentials.yaml：凭据中心（各档案的密码/口令值，引用式）。
- 删除档案不会自动删除凭据，除非在删除确认中选择“删除并清除凭据”。

卸载

在插件管理中移除 bundle 并 pnpm install；如需彻底清理，再删除上面两个数据文件中的相关条目。

FAQ

- 提示 “no password available … set credential”：该档案密码尚未在凭据中心/环境变量中设置——到 Remote SSH 设置页的“设置凭据”区填写，或设置同名环境变量。
- 终端一直打不开/白屏：请确保重启过 profile（客户端与宿主端代码随重启加载）；仍异常时把该窗口 DevTools 控制台报错发来。
- agent 转发（ssh -A）：v0.1 交互引擎暂不支持，后续可作为可选模式。
- 能否连跳板机/做端口转发：规划中（v0.2+）。

兼容性

- 依赖 DSH（含 Desktop）≥ 0.1.1-rc.1；Node ≥ 20。
- 执行引擎为纯 JS ssh2 + xterm，Windows / macOS / Linux 均可运行交互终端。

License

MIT