AI 工具使用指南
只按用户的目标和授权范围操作。工具名称、参数及限制以当前已加载的 tools/list 为准；包内 tools.json 是该发行版的对应参考。无需预读全部工具或所有文档。
每个任务按这条顺序
- 调用
ssh_list_servers，找到用户指定的目标，复用返回的name。不要从本机.ssh、旧笔记、猜测的 IP 或其他机器替代它。 - 按下面的选用表选择工具，读取该工具的用途、
Inputs、Result和字段说明。 - 先拿到所需服务器名、路径、设备 ID、当前 revision 或上一步回执，再填写参数。示例值只展示格式，不能直接当作真实目标。
- 调用后先判断失败、部分成功、排队或未知状态，再决定下一步。不要看到 MCP 请求返回就说业务完成。
- 完成实际目标验证，关闭这次创建且已经用完的命令上下文和临时隧道。保留用户原有会话、文件、身份和无关配置。
按需求选工具
| 用户要做什么 | 选哪个 | 容易选错的边界 |
|---|---|---|
| 查有哪些服务器 | 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，集群任务读 CLUSTERS.md，安装和版本更新读 UPDATES.md。遇到真实 NAT 不可达、缺权限或缺必要资料时，明确说明实际阻塞，不承诺自动穿透或擅自扩大授权。