用 Rust 构建智能命令行工具：从 Agent 调用到流式输出

用 Rust 构建智能命令行工具：从 Agent 调用到流式输出

一、CLI 工具的智能化困境——为什么传统命令行需要 AI

命令行工具是开发者的日常基础设施。从 git 到 docker，从 curl 到 jq，CLI 工具以高效、可组合、可脚本化的特性，构成了现代开发工作流的核心。但传统 CLI 工具有一个根本性局限：它们只能执行预定义的逻辑，无法理解用户的意图。

当开发者输入 git log --oneline -20 时，工具精确执行命令。但当需求变成"帮我找出上周修改最多的文件"时，传统 CLI 就无能为力了——用户需要自己组合多条命令、管道和参数。这就是 AI 驱动 CLI 工具的价值所在：将自然语言意图转化为可执行的操作序列。

然而，将大模型能力嵌入 CLI 工具并非简单的 HTTP 调用。生产环境中需要面对：流式响应的实时渲染、多轮对话的上下文管理、工具调用（Function Calling）的结构化解析、以及网络异常时的重试与降级。本文将用 Rust 从零构建一个具备 Agent 能力的智能 CLI 工具，覆盖上述所有工程挑战。

二、Agent CLI 的架构：从用户输入到工具执行的完整链路

一个 AI 驱动的 CLI 工具，其核心架构可以抽象为三层：交互层、Agent 层和工具层。交互层负责接收用户输入和渲染输出；Agent 层负责与大模型 API 通信、解析工具调用请求、管理对话上下文；工具层则封装了具体的系统能力（如文件操作、命令执行、代码搜索）。

sequenceDiagram
    participant U as 用户终端
    participant I as 交互层 (CLI)
    participant A as Agent 层
    participant LLM as 大模型 API
    participant T as 工具层

    U->>I: 输入自然语言指令
    I->>A: 提交用户消息
    A->>A: 拼接对话上下文 + 工具描述
    A->>LLM: 发送 Chat Completion 请求
    LLM-->>A: 流式返回 (SSE)

    alt 普通文本回复
        A-->>I: 逐 token 渲染到终端
        I-->>U: 实时显示回复
    else 工具调用请求
        A->>A: 解析 function_call 参数
        A->>T: 执行对应工具函数
        T-->>A: 返回工具执行结果
        A->>LLM: 将结果追加到上下文，再次请求
        LLM-->>A: 基于工具结果生成最终回复
        A-->>I: 渲染最终回复
        I-->>U: 显示完整结果
    end

2.1 流式响应的底层机制

大模型的 Chat Completion API 通常以 Server-Sent Events（SSE）协议返回流式数据。每个事件包含一个增量 token，客户端需要逐个接收并拼接。在 Rust 中，reqwest 配合 eventsource-stream 可以高效处理 SSE 流：

use reqwest::Client;
use futures_util::StreamExt;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct ChatDelta {
    content: Option<String>,
}

#[derive(Debug, Deserialize)]
struct ChatChoice {
    delta: ChatDelta,
    finish_reason: Option<String>,
}

#[derive(Debug, Deserialize)]
struct ChatChunk {
    choices: Vec<ChatChoice>,
}

/// 流式调用大模型 API，逐 token 回调
/// 采用回调模式而非收集全部结果，避免长回复占用过多内存
async fn stream_chat<F>(
    client: &Client,
    api_url: &str,
    api_key: &str,
    messages: &[Message],
    on_token: F,
) -> Result<String, Box<dyn std::error::Error>>
where
    F: Fn(&str),
{
    let body = serde_json::json!({
        "model": "gpt-4o-mini",
        "messages": messages,
        "stream": true,
    });

    let response = client
        .post(api_url)
        .header("Authorization", format!("Bearer {}", api_key))
        .json(&body)
        .send()
        .await?;

    // 检查 HTTP 状态码，避免静默失败
    if !response.status().is_success() {
        let status = response.status();
        let body = response.text().await?;
        return Err(format!("API 请求失败 [{}]: {}", status, body).into());
    }

    let mut stream = response.bytes_stream();
    let mut full_content = String::new();
    let mut buffer = String::new();

    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        buffer.push_str(&String::from_utf8_lossy(&chunk));

        // 按行解析 SSE 事件
        while let Some(pos) = buffer.find('\n') {
            let line = buffer[..pos].trim().to_string();
            buffer = buffer[pos + 1..].to_string();

            if line.starts_with("data: ") {
                let data = &line[6..];
                if data == "[DONE]" {
                    return Ok(full_content);
                }
                if let Ok(chunk) = serde_json::from_str::<ChatChunk>(data) {
                    if let Some(choice) = chunk.choices.first() {
                        if let Some(content) = &choice.delta.content {
                            on_token(content);
                            full_content.push_str(content);
                        }
                    }
                }
            }
        }
    }

    Ok(full_content)
}

2.2 工具调用的结构化解析

Agent 的核心能力在于工具调用。大模型返回的 function_call 需要被解析为结构化的工具调用请求，执行后将结果反馈给模型：

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// 工具定义：描述给大模型的可调用能力
#[derive(Debug, Serialize, Clone)]
struct ToolDefinition {
    name: String,
    description: String,
    parameters: serde_json::Value,
}

/// 工具调用请求：大模型返回的结构化指令
#[derive(Debug, Deserialize)]
struct ToolCall {
    id: String,
    function: FunctionCall,
}

#[derive(Debug, Deserialize)]
struct FunctionCall {
    name: String,
    arguments: String, // JSON 字符串，需二次解析
}

/// 工具执行器：注册与分发工具调用
struct ToolExecutor {
    handlers: HashMap<String, Box<dyn Fn(&str) -> String + Send + Sync>>,
}

impl ToolExecutor {
    fn new() -> Self {
        Self {
            handlers: HashMap::new(),
        }
    }

    /// 注册工具处理函数
    /// name 必须与 ToolDefinition 中的 name 一致
    fn register<F>(&mut self, name: &str, handler: F)
    where
        F: Fn(&str) -> String + Send + Sync + 'static,
    {
        self.handlers.insert(name.to_string(), Box::new(handler));
    }

    /// 执行工具调用，返回结果字符串
    /// 若工具未注册，返回错误提示而非 panic
    fn execute(&self, call: &ToolCall) -> String {
        match self.handlers.get(&call.function.name) {
            Some(handler) => handler(&call.function.arguments),
            None => format!(
                "错误：未注册的工具 '{}'",
                call.function.name
            ),
        }
    }
}

/// 构建文件读取工具的定义
fn file_read_tool() -> ToolDefinition {
    ToolDefinition {
        name: "read_file".to_string(),
        description: "读取指定路径的文件内容".to_string(),
        parameters: serde_json::json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "文件的绝对路径"
                }
            },
            "required": ["path"]
        }),
    }
}

三、生产级 Agent 循环：上下文管理与错误恢复

Agent 的核心是一个循环：发送消息 → 解析响应 → 如果有工具调用则执行并追加结果 → 再次发送。这个循环需要处理多种边界情况：

use tokio::time::{timeout, Duration};

/// Agent 对话消息
#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(tag = "role")]
enum Message {
    #[serde(rename = "system")]
    System { content: String },
    #[serde(rename = "user")]
    User { content: String },
    #[serde(rename = "assistant")]
    Assistant { content: String, tool_calls: Option<Vec<ToolCall>> },
    #[serde(rename = "tool")]
    Tool { tool_call_id: String, content: String },
}

/// Agent 主循环
/// max_turns 限制工具调用轮次，防止无限循环
async fn agent_loop(
    client: &Client,
    api_url: &str,
    api_key: &str,
    executor: &ToolExecutor,
    messages: &mut Vec<Message>,
    max_turns: usize,
) -> Result<String, Box<dyn std::error::Error>> {
    let mut turns = 0;

    loop {
        turns += 1;
        if turns > max_turns {
            return Ok("已达到最大工具调用轮次，终止 Agent 循环".to_string());
        }

        let mut full_response = String::new();

        // 带超时的流式请求，防止单次调用无限挂起
        let result = timeout(
            Duration::from_secs(60),
            stream_chat(client, api_url, api_key, messages, |token| {
                print!("{}", token);
                full_response.push_str(token);
            }),
        )
        .await
        .map_err(|_| "API 请求超时（60秒）")??;

        // 检查是否有工具调用（简化示例，实际需从 SSE 中解析）
        // 此处假设 full_response 中包含工具调用标记
        if let Some(tool_call) = try_parse_tool_call(&full_response) {
            println!("\n[工具调用] {}({})", tool_call.function.name, tool_call.function.arguments);

            let tool_result = executor.execute(&tool_call);

            // 将助手消息和工具结果追加到上下文
            messages.push(Message::Assistant {
                content: full_response.clone(),
                tool_calls: Some(vec![tool_call.clone()]),
            });
            messages.push(Message::Tool {
                tool_call_id: tool_call.id,
                content: tool_result,
            });

            println!("[工具结果] 已反馈给模型，继续生成...");
        } else {
            // 无工具调用，Agent 循环结束
            return Ok(full_response);
        }
    }
}

/// 尝试从响应中解析工具调用
/// 实际项目中应从 SSE 事件的 tool_calls 字段解析
fn try_parse_tool_call(response: &str) -> Option<ToolCall> {
    // 简化实现：实际应解析大模型返回的 tool_calls 结构
    None
}

四、智能 CLI 的工程权衡：延迟、成本与可靠性

将大模型嵌入 CLI 工具，在获得智能化的同时，引入了三重工程代价。

延迟问题是首要挑战。大模型的首 token 延迟通常在 500ms 到 3s 之间，远超传统 CLI 工具的毫秒级响应。流式输出可以缓解用户感知延迟，但总延迟不变。对于需要多轮工具调用的复杂任务，累计延迟可能达到 10s 以上。工程上的缓解方案包括：使用更小的模型（如 GPT-4o-mini）降低延迟、缓存常见意图的映射结果、以及预加载模型响应。

成本控制不容忽视。每次 Agent 交互都消耗 API Token，而工具调用需要将完整上下文（包括工具结果）反复发送给模型。一个涉及 5 轮工具调用的任务，Token 消耗可能是单次对话的 5-10 倍。生产环境中必须设置 Token 预算上限，并在接近上限时主动截断。

可靠性降级是必须面对的现实。大模型的输出是非确定性的——相同的输入可能产生不同的工具调用参数，甚至生成无法解析的格式。这意味着工具调用解析必须有容错机制：JSON 解析失败时回退到正则提取，参数缺失时使用默认值，以及设置最大重试次数防止死循环。

此外，Agent 模式下的安全性需要特别关注。工具执行层必须实施严格的权限控制——文件操作限制在指定目录、命令执行使用白名单机制、网络请求限制目标域名。大模型生成的工具调用参数不可信，必须经过校验后再执行。

五、总结

AI 驱动的 CLI 工具将自然语言理解能力注入了传统命令行，核心架构由交互层、Agent 层和工具层构成。Agent 层的循环机制——发送消息、解析工具调用、执行工具、反馈结果——是整个系统的运转核心。

生产级实现需要重点解决三个工程问题：流式响应的 SSE 解析与实时渲染、工具调用的结构化解析与容错、以及 Agent 循环的上下文管理与超时控制。在延迟、成本和可靠性三个维度上，需要根据具体场景做出权衡——轻量任务使用小模型降低延迟，复杂任务允许更多工具调用轮次但设置预算上限，所有工具执行必须经过权限校验。

落地路线建议：先用 reqwest + tokio 实现基本的流式 Chat Completion 调用；再添加工具定义与解析逻辑；最后实现完整的 Agent 循环，加入超时、重试和权限控制。从单轮对话到多轮工具调用，逐步迭代。