# 使用手册

接入后直接用自然语言要求 AI 操作，例如“列出服务器”“对 web-a 和 web-b 并行查看 hostname”“把这几个本地文件批量上传到 web-a”。开始远程操作前先调用 ssh_list_servers 选择目录中的目标。

## 添加自己的服务器

本机模式可编辑自己的 TOML；将示例地址和用户替换为真实值：

```toml
[ssh_servers.web-a]
host = "server.example.com"
port = 22
user = "deploy"
key_path = "~/.ssh/id_ed25519"
description = "我的应用服务器"
```

指定跳板：先配置名为 bastion 的服务器，再给目标添加 `proxy_jump = "bastion"`。Windows OpenSSH 目标添加 `platform = "windows"`。密码认证使用你自己的私密配置，不把密码粘贴到公共文档。SSH agent 的使用仅适用于独立本机模式，中心连接器不读取无关本机身份。

目录更新通常无需重启 MCP。也可以使用 ssh_server_manage：

```json
{"action":"add","server":"web-a","host":"server.example.com","port":22,"user":"deploy","key_path":"~/.ssh/id_ed25519","installHelper":false}
```

在集中模式中，工具管理的是中心目录，key_path 必须符合该模式的密钥导入/路径合同；不要直接把新机本地路径当作中心路径。新增真实节点时由 AI 查看实时 schema，并采用用户授权的凭据输入方式。

## 执行命令

```json
{"server":"web-a","command":"hostname","timeout":10000}
```

多机同命令，一次调用：

```json
{"servers":["web-a","web-b"],"command":"hostname","strategy":"parallel","timeout":10000}
```

有依赖时用 sequential；滚动执行用 rolling 和毫秒 delay。stopOnError 不能撤回已经并行发出的请求。远端写入失败后先查看结果，不要无条件重放部署或数据库导入。

## 批量传文件

```json
{
  "server":"web-a",
  "concurrency":4,
  "files":[
    {"localPath":"/absolute/local/app.conf","remotePath":"/home/deploy/app.conf"},
    {"localPath":"/absolute/local/readme.txt","remotePath":"/home/deploy/readme.txt"}
  ]
}
```

Windows 的 localPath 使用本机绝对路径，例如 `C:/Users/you/Documents/app.conf`。所有目标路径必须互不重复。读回或远端计算哈希用于确认传输；批量上传部分失败时查看每项结果，仅重试确实未完成的项目。

ssh_read、ssh_write、ssh_edit 操作远端文件，具体字段查看 tools.json。目录同步使用 ssh_sync，执行前核对方向和目标。创建隧道时优先监听本机回环地址，操作系统和目标 SSH 账号必须允许对应转发。

## 常用检查

- 查看目录：ssh_list_servers。
- 查看连接与重连：ssh_connection_status。集中模式显式 disconnect/reconnect 影响共享池。
- 查看当前客户端会话/隧道：ssh_session_list、ssh_tunnel_list。
- 查看服务或日志：ssh_service_status、ssh_tail；具体能力取决于目标机工具。
- 查看完整参数和返回字段：让 AI 读取实际工具 schema，或包内 schemas/tools.json。