目 录
从一句话到一串命令
先看一个最典型的场景。打开程序，输入这样一句话：
「看看 yum-server 这台机器现在的负载和内存情况」
几秒钟后，程序会给出类似这样的回答：CPU 使用率 12%，load average 0.15 / 0.08 / 0.06，内存已用 1.8G / 3.9G......
对使用者来说，这就像跟一个懂行的助手对话。但在背后，这一句话其实经历了一整套「意图 → 命令 → 执行 → 回填 → 汇总」的闭环。本篇就把这条链路拆开，讲清楚它赖以运转的骨架：一个大模型 + 一组工具 + 一条 SSH 通道。
三层骨架：模型、工具、执行
整个程序在架构上可以清晰地分成三层，每一层各管一件事：
|-----------|---------------------------|------------------------|
| 层 | 职责 | 对应模块 |
| 模型层 | 听懂人话，决定「下一步该调用哪个工具、传什么参数」 | llm.py（LLMClient） |
| 工具层 | 定义 AI 能用的全部能力，并执行对应操作 | tools.py（ToolExecutor） |
| 执行层 | 建立真正的 SSH 会话，在远端跑命令、取回结果 | ssh.py（SSHConnection） |
这三个角色围绕一个核心循环协作------agent.py 里的 Agent。你可以把它理解成一位「调度员」：它负责把用户的意图喂给模型，把模型想调的工具转交给执行层，再把结果回传给模型，如此往复，直到模型认为任务完成、给出最终回答。
一句话是怎么变成命令的
Agent 的运行是一个循环，而不是一次性的「问 → 答」。用伪代码可以这样概括：
- 把用户输入（user）追加进消息列表 2. 循环（最多 50 轮）： a. 把全部消息发给大模型，附上工具清单 b. 模型返回：要么是最终回答，要么是一组「工具调用」请求 c. 若是工具调用 → 执行它 → 把结果作为 tool 消息回填 d. 若是最终回答 → 返回给用户，结束
回到开头的例子，「看看负载和内存」这句话进入循环后，模型层会判断：这需要用 run_command 工具。于是它生成一个结构化的调用请求：
工具：run_command 参数：command = "top -bn1 | head -5 && free -h"
执行层拿到这条命令，通过 SSH 在 yum-server 上跑起来，把输出回传给模型。模型看到结果后，再决定是继续查、还是直接组织成一段人话回答。这正是它和「写死脚本」的本质区别------工具调用是模型在每一轮动态决定的，不是预先编排好的固定流程。
工具清单长什么样
AI 凭什么知道「该怎么用这个程序」？靠的是一份 TOOLS_SCHEMA------一组用标准格式描述的「能力说明书」。每个工具都写明名称、作用、需要哪些参数。下面是核心工具 run_command 的简化版定义：
工具 run_command： 作用：在当前 SSH 主机上执行一条 shell 命令并返回结果 参数： command（必填）--- 要执行的命令，bash 语法，可用管道和重定向 timeout（可选）--- 超时秒数，长时间任务主动调大
这种「OpenAI 兼容的函数调用（function calling）」格式，是当代大模型普遍支持的协议，也是整个程序能「指挥真实系统」的桥梁。除了 run_command，还有 list_hosts（列出主机）、switch_host（切换目标机）、upload_file（SFTP 上传）等一批工具，共同构成 AI 的「工具箱」。
主机从哪来：配置与密钥分离
执行层要连哪台机器、用什么账号密码，都来自配置文件，且遵循一条重要原则------结构进 YAML，密钥进 .env。
主机清单写在 config/hosts.yml：
default: yum-server hosts: yum-server: host: 10.10.10.10 port: 22 user: root auth: method: password password_env: HOST_PW_YUM note: 内网 yum 源服务器
注意：这里并没有直接写密码，而是写了一个环境变量名 HOST_PW_YUM。真正的密码放在项目根目录的 .env 文件里。这样配置文件可以放心入库、分享，而密钥始终留在本机，不进版本库------这是这套程序对「凭据安全」的基本态度。
凭什么敢让它跑真命令
连接真实服务器这件事，有两点细节直接决定了它「敢不敢用」：
一是 SSH 会话的健壮性。基于 paramiko 建连，内网环境采用首次连接自动信任主机密钥（TOFU）策略；执行命令时用非阻塞轮询 + 超时硬控制------命令跑超时会强制关闭通道终止远端进程，不会让一条卡死的命令挂住整个会话。密码和密钥两种认证方式都支持。
二是并行与汇总。面对多台机器，程序用 run_command_on_hosts 做最多 8 路并行编排，把每台主机的结果汇总回来。这为系列第 6 篇「多机并行与文件传输」埋下了伏笔------你只需要说一次，它就替你跑遍所有机器。
小结
这一篇讲的，是「AI 能跑命令」这个最基础的能力是怎么搭起来的：模型听懂意图 → 工具定义能力 → SSH 落地执行，由 Agent 循环把它们串成闭环。骨架虽然简单，但它是后面一切的基础------安全管控、值守监测、设备接入，全都是在这套「模型指挥工具、工具操纵系统」的机制之上长出来的。