# Ssh

> SSH 远程服务器管理。用于连接远程服务器、执行命令、SFTP 文件传输。支持会话管理、自动重连、历史记录存储。当用户需要 SSH 连接、远程执行命令、传输文件时触发。

- Skill: `erixwong/ssh` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add erixwong/ssh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erixwong/ssh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: erixwong (https://skillmd.com/u/erixwong)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erixwong/ssh

---


# Status

Frozen draft. This skill is intentionally not discoverable by `scanSkillsDirectory()` because it has no `index.js` / `index.py` entrypoint.

Do not register or enable it until the resident-process contract, permission boundary, credential handling, and user-facing audit trail are reviewed. See `STATUS.md`.

# 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 操作）：**
```json
{ "success": true, "operation": "connect", "session_id": "sess_abc123..." }
```

**返回（disconnect 操作）：**
```json
{ "success": true, "operation": "disconnect", "message": "Disconnected" }
```

### exec

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

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

**返回：**
```json
{
  "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 操作）：**
```json
{
  "success": true,
  "operation": "list",
  "path": "/home/user",
  "entries": [
    { "filename": "example.txt", "type": "file", "size": 1234, "mode": "0644" }
  ]
}
```

**返回（download/upload 操作）：**
```json
{
  "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 包（项目已安装）