# AI 工具使用指南

只按用户的目标和授权范围操作。工具名称、参数及限制以**当前已加载**的 `tools/list` 为准；包内 [tools.json](../schemas/tools.json) 是该发行版的对应参考。无需预读全部工具或所有文档。

## 每个任务按这条顺序

1. 调用 `ssh_list_servers`，找到用户指定的目标，复用返回的 `name`。不要从本机 `.ssh`、旧笔记、猜测的 IP 或其他机器替代它。
2. 按下面的选用表选择工具，读取该工具的用途、`Inputs`、`Result` 和字段说明。
3. 先拿到所需服务器名、路径、设备 ID、当前 revision 或上一步回执，再填写参数。示例值只展示格式，不能直接当作真实目标。
4. 调用后先判断失败、部分成功、排队或未知状态，再决定下一步。不要看到 MCP 请求返回就说业务完成。
5. 完成实际目标验证，关闭这次创建且已经用完的命令上下文和临时隧道。保留用户原有会话、文件、身份和无关配置。

## 按需求选工具

| 用户要做什么 | 选哪个 | 容易选错的边界 |
| --- | --- | --- |
| 查有哪些服务器 | `ssh_list_servers` | 只列目录，不证明 SSH 可登录 |
| 一台机器执行命令 | `ssh_execute` | `server` 是目录名称；命令使用目标系统的 shell |
| 多台机器执行同一命令 | `ssh_execute_group` | 独立任务用 parallel；有依赖才串行；逐台判断结果 |
| 从本机传一个已有文件 | `ssh_upload` | `localPath` 属于运行连接器的电脑 |
| 同一目标传多个已有文件 | `ssh_upload_batch` | 每文件原子替换，整个批次不回滚 |
| 下载到本机保存 | `ssh_download` | `remotePath` 是源；`localPath` 是本机完整目标文件名 |
| 只看远端文本 | `ssh_read` | `offset` 从第 1 行开始；不是字节偏移 |
| 改远端文件中的一段 | `ssh_edit` | 先读取；精确文本匹配；不带显示出来的行号 |
| 创建或覆盖整份文本 | `ssh_write` | `content` 是全文件内容，不是追加片段 |
| 分发目录或双向同步 | `ssh_sync` | 每端明确 `server/root`，先 dryRun；删除默认关闭 |
| 查连接故障或更新状态 | `ssh_connection_status` | 强制 reconnect/disconnect 影响共享池，状态查询优先 |
| 查或修复路径、跳板、受管资源 | `ssh_route_inspect` → `ssh_route_plan` → `ssh_route_apply` | 计划保存不等于已应用；应用失败先查同一 planId 回执 |
| 部署或配对原生节点 | `ssh_node_manage` | inspect 身份后再配权限；保存与加载版本分别检查 |
| 临时 SSH 端口转发 | `ssh_tunnel_create` | 隧道归当前客户端；持久受管转发走节点/路由工具 |
| 集群持续观测或自动选路 | `ssh_cluster_*` | 先配置执行器与观测；自动改路/repair 默认不授权 |

Windows 目标的通用操作使用 `ssh_execute` 配合 PowerShell。`systemctl`、`ps`、`tar`、cron 和数据库 CLI 包装依赖远端 POSIX 环境及已有程序，不能因工具存在就假设 Windows 也能执行。

## 路径、ID 和单位

| 值 | 属于哪一端 / 从哪里取得 |
| --- | --- |
| `localPath` / 部署 `files[].local` | 运行 MCP 连接器的电脑。Windows 示例 `C:/Users/me/file.txt` |
| `remotePath` / `cwd` / 部署 `files[].remote` | `server` 所指的远端机器 |
| 同步端点 `root` | 同一个端点对象的 `server`；必须为绝对目录 |
| `@local` | 仅在明确支持它的节点/同步字段中表示当前连接器；不是通用 SSH 服务器名 |
| `device` / `sourceDevice` | 节点 inspect/discover 返回的设备 UUID；不是服务器显示名 |
| `sessionId` / `id` / `planId` / `jobId` | 对应创建/查询工具的返回值，不能互换或自行编造 |
| `expectedRevision` | 对应对象最近 inspect 或 plan 返回的版本；创建某些对象用 0，按工具说明执行 |
| `timeout` | 毫秒：`10000` = 10 秒，`30000` = 30 秒。普通命令的 0 会关闭命令期限，连接建立仍有独立限制；通常省略以使用默认值 |
| 同步超时 | `options.timeout`，整个同步操作的毫秒期限；不要写到根层；0 无效 |
| 探测 RTT | 微秒；样本时间/周期通常为毫秒，文件授权 `expiresAt` 明确为 Unix 秒 |

中心只协调目录。文件仍沿当前设备配置的直连、跳板或原生路径传输。中心模式下，目录的 `key_path` 在中心一侧解释；不能把新电脑上的文件路径当作中心能读取的路径。`ssh_key` 是旧版路径别名，不是私钥正文。

## 如何判断结果

| 返回状态 | 正确的下一步 |
| --- | --- |
| `isError=true`、`success=false` 或非零 `code` | 看具体错误与已产生的效果；修复该原因，不把 RPC 返回当成功 |
| 批量操作有成功也有失败 | 检查每项，只重试确实失败且状态已明确的目标；成功项可能已经改变 |
| 超时、断开、`unknown` / 结果未知 | 先查远端状态或回执；部署、导入、写入不能盲目重放 |
| `saved` / 安装或配置已写入 | 再查 `loaded`、实际进程/版本和一次真实目标操作 |
| 返回 `planId` | 仅生成计划；审阅后才 apply，不提前宣称路由已变 |
| 返回 `jobId` / `queued` | 去 cluster inspect 的 jobs 查看终态；排队不是执行完成 |
| `deferred` | 更新等待业务空闲；结束自己已用完的上下文/隧道，不强杀用户应用 |
| `stale` / `unknown` 观测 | 缺少新鲜证据；与一次真实失败分开处理 |
| 服务查询 `success=true`，但 output 为 inactive/failed | 查询本身成功，服务没有正常运行 |

`content[].text` 有时是可解析 JSON，有时是普通文本。只有实际存在的字段才可读取；不要假设所有工具都返回同一 JSON 结构。文件写入、服务启动和用户实际功能正常是不同验收层。

## 几项旧接口的实际能力

- `ssh_session_*` 保存服务器和固定工作目录；每次发送是独立 shell 命令，`cd`、变量和交互程序状态不会跨次保留。
- `ssh_monitor` 是一次快照；`ssh_tail` 不支持 `follow=true`；告警工具保存阈值或做一次检查，不安装通知服务。
- `ssh_hooks` 和 `ssh_profile` 只维护旧版元数据。Hook 启用不代表自动执行，Profile switch 不切换原生连接配置。
- `ssh_key_manage` 当前提供 known-hosts 读取，不实现旧动作名暗示的密钥添加、接受或删除。
- 原生备份不支持 full 或自动 retention 清理。数据库恢复须按实际格式处理；PostgreSQL 外层 gzip 和 MongoDB tar 包不能不解包就直接交给对应恢复工具。

原生节点/跨机同步的详细前置读 [NATIVE_SYNC.md](NATIVE_SYNC.md)，集群任务读 [CLUSTERS.md](CLUSTERS.md)，安装和版本更新读 [UPDATES.md](UPDATES.md)。遇到真实 NAT 不可达、缺权限或缺必要资料时，明确说明实际阻塞，不承诺自动穿透或擅自扩大授权。