ssh

name	ssh
description	SSH 远程服务器管理。用于连接远程服务器、执行命令、SFTP 文件传输。支持会话管理、自动重连、历史记录存储。当用户需要 SSH 连接、远程执行命令、传输文件时触发。
is_resident	1
argument-hint	[session|exec|sudo|sftp] --session ID
user-invocable	false
allowed-tools	[]

SSH - 远程服务器管理

基于会话的 SSH 客户端，支持同步命令执行和 SFTP 文件传输。

核心工具（4 个）

工具	说明	关键参数
session	会话管理（连接/断开）	operation, host, username, session_id
exec	执行命令（同步）	session_id, command
sudo	sudo 执行	session_id, command, password
sftp	SFTP 文件传输	session_id, operation, remote_path, local_path

工具详情

session

会话管理（连接/断开）。

参数：

• operation (string, required): 操作类型 - connect | disconnect
• host (string, optional): 主机地址（IP 或主机名）- connect 操作需要
• username (string, optional): SSH 用户名 - connect 操作需要
• port (number, optional): SSH 端口，默认 22 - connect 操作需要
• password (string, optional): 密码认证 - connect 操作需要
• private_key (string, optional): 私钥文件路径（支持 ~ 展开）- connect 操作需要
• passphrase (string, optional): 加密私钥的密码 - connect 操作需要
• session_id (string, optional): 会话 ID - disconnect 操作需要

返回（connect 操作）：

{ "success": true, "operation": "connect", "session_id": "sess_abc123..." }

返回（disconnect 操作）：

{ "success": true, "operation": "disconnect", "message": "Disconnected" }

exec

在远程服务器上执行命令（同步阻塞，直接返回输出）。

参数：

• session_id (string, required): 会话 ID
• command (string, required): 要执行的命令
• timeout (number, optional): 超时时间（毫秒），默认 60000

返回：

{
  "success": true,
  "exit_code": 0,
  "stdout": "命令输出...",
  "stderr": ""
}

sudo

使用 sudo 权限执行命令。

参数：

• session_id (string, required): 会话 ID
• command (string, required): 要执行的命令（不含 sudo 前缀）
• password (string, required): sudo 密码
• timeout (number, optional): 超时时间（毫秒），默认 120000

安全特性：

• 密码在输出中被掩码（替换为 ********）
• 支持自动密码提示检测

sftp

SFTP 文件传输（支持 list/download/upload 操作）。

参数：

• session_id (string, required): 会话 ID
• operation (string, required): 操作类型 - list | download | upload
• remote_path (string, optional): 远程文件路径
• local_path (string, optional): 本地文件路径
• path (string, optional): 远程目录路径（用于 list 操作）

返回（list 操作）：

{
  "success": true,
  "operation": "list",
  "path": "/home/user",
  "entries": [
    { "filename": "example.txt", "type": "file", "size": 1234, "mode": "0644" }
  ]
}

返回（download/upload 操作）：

{
  "success": true,
  "operation": "download",
  "remote_path": "/remote/file.txt",
  "local_path": "/local/file.txt",
  "bytes_transferred": 1234
}

典型工作流程

1. ssh_session (connect) → 保存返回的 session_id
2. ssh_exec → 执行命令，直接获取输出（同步）
3. ssh_sudo → 执行需要提权的命令
4. ssh_sftp → 文件传输（operation: list|download|upload）
5. ssh_session (disconnect) → 关闭连接

安全说明

Session ID 是能力令牌，请像密码一样对待！

• 知道 Session ID = 拥有该连接的完全控制权
• LLM 必须在对话上下文中保存 Session ID
• 丢失 Session ID = 丢失访问权限（出于安全考虑无会话列表功能）
• 不要在公开场合暴露完整 Session ID（仅显示前 8 个字符用于识别）

存储

使用 JSON 文件存储，无需数据库依赖：

data/
├── sessions.json           # 会话索引
└── sessions/
    ├── sess_xxx.json       # 主文件（最近 50 条命令）
    ├── sess_xxx.1.json     # 归档文件 #1（~100KB）
    └── sess_xxx.2.json     # 归档文件 #2

安全特性：

• 密码不会保存到磁盘（仅私钥认证会话可恢复）
• 归档文件自动管理，每个文件最大 100KB
• 主文件自动循环，保留最近 50 条命令

依赖

• Node.js 18+
• ssh2 包（项目已安装）