---
name: use-gssh
description: "Manage SSH sessions with gssh CLI for agents"
allowed-tools: Read, Write, Glob, Grep, Bash
version: 1.0.0
---
**设计原则：完全非交互、纯脚本化。所有密码和参数通过命令行传递，不支持交互式操作。**

## 安装

```bash
npm install -g @zzzwy/gssh
# 更新
gssh update
```

## 启动

```bash
# 放后台启动
gssh-daemon &

# 推荐使用pm2 管理
pm2 start gssh-daemon --name gssh
```

## 连接认证

```bash
# 使用密码
gssh connect -u user -h host -p port -P "password"

# SSH 密钥
gssh connect -u user -h host -i ~/.ssh/id_ed25519
```

## 核心命令

| 命令            | 说明             |
| --------------- | ---------------- |
| `connect`       | 建立 SSH 连接    |
| `exec`          | 执行命令         |
| `scp` / `sync`  | 文件传输与同步   |
| `sftp`          | SFTP 操作        |
| `forward`       | 端口转发         |
| `forwards`      | 列出所有端口转发 |
| `forward-close` | 关闭端口转发     |
| `list`          | 列出 session     |
| `use`           | 切换默认 session |

## 执行命令

```bash
# 普通命令
gssh exec "ls -la"

# 指定 session
gssh exec -s <session_id> "pwd"

# 带超时命令（秒）
gssh exec -t 10 "ls -la"

# 后台运行（推荐格式）
gssh exec "nohup python3 app.py > /dev/null 2>&1 &"

# sudo 命令
gssh exec --sudo --sudo-password "your-password" "sudo systemctl restart nginx"

# sudo 以其他用户运行
gssh exec --sudo --sudo-password "your-password" --sudo-user "www-data" "whoami"

# sudo login shell
gssh exec --sudo --sudo-password "your-password" --sudo-login "whoami"
```

## 文件传输

```bash
# 上传本地文件/文件夹 -> 远程
gssh scp -put local.txt /remote/path/
gssh sync -put local_dir /remote/path/

# 下载远程文件/文件夹 -> 本地
gssh scp -get /remote/file.txt ./
gssh sync -get /remote/dir ./

# SFTP 目录操作
gssh sftp -c ls -p /home/user
gssh sftp -c mkdir -p /home/user/newdir
gssh sftp -c rm -p /home/user/file.txt
```

## 端口转发

```bash
# 本地转发: localhost:8080 -> remote:80
gssh forward -l 8080 -r 80

# 远程转发: remote:9000 -> localhost:3000
gssh forward -R -l 9000 -r 3000

# 列出所有端口转发
gssh forwards

# 关闭端口转发
gssh forward-close <forward_id>
```

## Session 管理

```bash
gssh list                    # 列出所有 session
gssh use <session-id>        # 切换默认 session
gssh disconnect             # 断开
gssh reconnect -s <id>     # 重连
```

## 选项汇总

| 选项              | 说明                   |
| ----------------- | ---------------------- |
| `-s`              | session ID             |
| `-u`              | 用户名                 |
| `-h`              | 主机地址               |
| `-p`              | 端口（默认 22）        |
| `-P`              | SSH 密码               |
| `-i`              | SSH 密钥               |
| `-l`              | 本地端口               |
| `-r`              | 远程端口               |
| `-R`              | 远程端口转发           |
| `-put/-get`       | 上传/下载              |
| `-t`              | 超时（秒）             |
| `--sudo`          | 启用 sudo 模式         |
| `--sudo-password` | sudo 密码              |
| `--sudo-user`     | 以指定用户运行 sudo    |
| `--sudo-login`    | sudo login shell（-i） |

## 限制与注意事项

### sudo 限制

- **密码不能包含单引号**：`--sudo-password` 中包含单引号会破坏 shell 语法
- **交互式命令不支持**：`sudo vim`、`sudo less`、`sudo -i`（无密码）等需要 TTY 的命令不支持
- **sudo 缓存**：sudo 有默认 15 分钟的密码缓存，相同 session 内后续 sudo 命令无需重复输入密码

### exec 命令限制

- **不支持交互式命令**：vim、less、top、nano 等需要终端的交互式程序无法使用
- **密码暴露**：密码通过命令行传递，在 `ps aux` 等命令中可能可见，请确保系统安全
- **管道命令需加引号**：含 `|`、`&&`、`||`、`>`、`<`、换行等特殊字符的命令需整体加引号

## 可靠性说明

- **超时机制**：`-t` 超时触发后，远端进程会被 SIGKILL 终止，当前连接立即可用于下一条命令，不需要重启 daemon
- **自动重连**：连接断开后每 5 秒自动检测并重连，死连接（含网络分区场景）5 秒内可感知
- **大命令支持**：exec 命令长度无 4096 字节限制，传输文件路径、长脚本均可正常工作