前言¶
在 DeepSeek Harness (DSH) 的开发场景中，智能体往往需要访问远程服务器进行部署、调试或数据交互。dsh-ssh-tunnel 是一个社区插件，旨在解决多主机 SSH 访问的权限管理、会话维护和交互界面问题。它为 dsh-better-sidebar 提供了 SSHManager 工具，并实现了多主机隧道管理。
插件定位¶
- 名称：dsh-ssh-tunnel
- 类型：DeepSeek Harness 社区插件
- 维护者：thirsty5034
- 定位：多主机 SSH 隧道 + SSHManager 工具
- 兼容性：面向 dsh-better-sidebar (>= 0.12)
核心功能¶
该插件提供了一套完整的 SSH 管理机制，核心能力如下：
- 主机清单与密钥管理：在本地维护主机清单（
hosts.json）和密钥（secrets.json）。这些敏感信息不会暴露给模型，仅用于插件内部处理。 - 项目范围授权：支持基于项目的权限控制。通过
projectPathKey（通常为工作区目录）关联可访问的主机列表，实现细粒度的访问控制。 - 模型工具 SSHManager：为模型提供标准化的工具接口。支持
exec（执行命令）、sftp_list（列出文件）等操作，并支持会话策略（如复用或新建会话）。 - 侧边栏管理：提供侧边栏选项卡，用于管理主机 CRUD、项目授权以及会话的连接/断开。
- 交互式界面：在中心覆盖层提供交互式终端（基于 xterm）和双面板 SFTP 文件管理界面。
- 非侵入式设计：插件不尝试用单一远程磁盘替换全局的
fs或subprocess，保持 DSH 原有的文件系统架构。
安装与启用¶
安装建议通过 CLI 官方源进行，确保版本与 DSH 环境匹配。
export DSH_HOME=${DSH_HOME:-$HOME/.dsh}
dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"
安装完成后，需要重启 DSH Web 进程，并在浏览器中执行硬刷新（Ctrl+Shift+R 或 Cmd+Shift+R）以加载新的插件界面。
典型用法¶
模型通过调用 SSHManager 工具与远程主机交互。以下是标准的工具调用示例：
- 列出所有主机：
SSHManager action=list_hosts
- 在指定主机执行命令：
SSHManager action=exec host_id=<id> command="uname -a"
- 通过 SFTP 列出目录：
SSHManager action=sftp_list host_id=<id> path=/
会话策略：
在调用工具时，可以通过参数指定会话策略：
* reuse_or_create：默认策略，尝试复用已存在的会话，失败则新建。
* new：强制新建会话。
* require_existing：仅使用已存在的会话，不存在则报错。
* session_id：显式指定会话 ID。
数据与安全¶
插件的数据存储在 $DSH_HOME/ssh-tunnel/ 目录下（权限为 0700）：
- hosts.json：存储主机元数据。
- secrets.json：存储密码、PEM 私钥或短语（权限
0600）。 - grants.json：存储项目路径到主机 ID 列表的映射。
- known_hosts.json：存储已验证的主机密钥指纹（SHA256 十六进制格式）。
安全限制：
* 认证方式：仅支持密码或私钥认证。键盘交互 认证已废弃，需编辑主机配置改用密码或私钥。不支持 Bastion Web MFA。
* 文件路径限制：本地上传/下载/列表操作限制在 /workspace 目录，且进行词法路径检查和 realpath 检查，拒绝符号链接。
* API 安全：HTTP API 仅监听本地回环地址，且依赖 trusted-hosts 配置。浏览器 Origin 必须与配置匹配，会话 API 必须提供 projectPathKey。
* 密钥轮换：如果怀疑 secrets.json 泄露，应立即轮换密钥。
注意事项¶
- 不替换全局文件系统：插件提供的是会话级和工具级的 SSH 访问，不会改变 DSH 的全局文件系统权限模型。
- 依赖环境：确保 DSH Web 配置了
dsh-better-sidebar(>= 0.12) 且 Node.js 版本为 18+。 - 会话保活：插件内置了 ssh2 keepalive 机制（30秒间隔），意外掉线后会自动尝试重连，最多重试 3 次。
- 前端依赖：终端依赖的
@xterm/xterm@5.5.0和@xterm/addon-fit@0.11.0通过同源路由加载，无 CDN 回退机制。
总结¶
dsh-ssh-tunnel 为 DSH 生态提供了一套标准化的 SSH 管理方案，通过项目级授权和模型工具接口，解决了多主机远程操作的安全性和易用性痛点。开发者在配置好主机清单和密钥后，可直接在对话中使用 SSHManager 工具进行操作。
- 目录页：SkillHub 插件目录
- 源码仓库：GitHub
