Rust AI 工具链：从命令行到 Agent，用 Rust 构建智能开发工具

Rust AI 工具链：从命令行到 Agent，用 Rust 构建智能开发工具

一、为什么用 Rust 写 AI 工具？不只是性能

AI 工具的开发语言选择，Python 是默认答案。但当工具需要分发给非技术用户、需要作为 CLI 嵌入到 CI/CD 流水线、或者需要在资源受限的环境中运行时，Python 的运行时依赖和启动开销就成了问题。

Rust 在 AI 工具开发中的优势不只是"快"。编译为单一二进制意味着零依赖分发，用户不需要安装 Python、不需要配置虚拟环境、不需要担心版本冲突。启动时间在毫秒级，对于 CLI 工具来说体验差距明显。内存安全保证在长时间运行的 Agent 进程中尤为重要——内存泄漏和段错误是 Python 工具在 7x24 运行时的常见故障。

但 Rust 写 AI 工具的代价也很明确：AI 生态远不如 Python 丰富，调用大模型 API 需要自己封装 HTTP 客户端，处理 JSON 响应需要手写反序列化，流式输出需要手动解析 SSE。这些在 Python 里几行代码搞定的事，在 Rust 里需要更多样板代码。

二、Rust AI 工具的架构模式

一个 Rust AI 工具的典型架构包含四个层次：用户交互层、任务编排层、AI 调用层和工具执行层。

graph TD
    A[用户交互层 CLI/REPL] --> B[任务编排层 Agent Loop]
    B --> C[AI 调用层 LLM API Client]
    B --> D[工具执行层 Shell/文件/网络]
    C --> E[构建 Prompt]
    E --> F[发送请求]
    F --> G[解析响应]
    G --> B
    D --> B

    subgraph 外部依赖
        H[LLM API OpenAI/Claude]
        I[本地文件系统]
        J[Shell 命令]
    end

    F --> H
    D --> I
    D --> J

用户交互层负责接收输入和展示输出。CLI 模式用 clap 解析参数，REPL 模式用 rustyline 提供行编辑和历史记录。流式输出需要处理 ANSI 转义和终端宽度。

任务编排层是 Agent 的核心。它维护对话历史，根据 LLM 的响应决定下一步动作（调用工具、继续对话、或结束）。这个循环是所有 Agent 工具的基本模式。

AI 调用层封装了与 LLM API 的交互。核心挑战是流式响应的处理——SSE（Server-Sent Events）格式的流式输出需要增量解析，部分 JSON 需要在未完成的情况下提取结构化信息。

工具执行层提供 LLM 可以调用的外部能力。文件读写、Shell 命令执行、网络请求——每个工具需要定义输入输出 schema，供 LLM 在 function calling 时使用。

三、用 Rust 构建一个最小可用的 AI CLI 工具

以下代码实现了一个支持流式输出的 AI CLI 工具核心模块：

use reqwest::Client;
use serde::{Deserialize, Serialize};
use std::io::{self, Write};

/// LLM API 请求体
#[derive(Serialize)]
struct ChatRequest {
    model: String,
    messages: Vec<Message>,
    stream: bool,
}

/// 对话消息
#[derive(Serialize, Deserialize, Clone)]
struct Message {
    role: String,
    content: String,
}

/// 流式响应的增量数据
#[derive(Deserialize)]
struct StreamDelta {
    choices: Vec<Choice>,
}

#[derive(Deserialize)]
struct Choice {
    delta: Delta,
}

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

/// AI CLI 工具
struct AiCli {
    client: Client,
    api_key: String,
    model: String,
    base_url: String,
    history: Vec<Message>,
}

impl AiCli {
    /// 创建新的 AI CLI 实例
    fn new(api_key: String, model: String) -> Self {
        Self {
            client: Client::new(),
            api_key,
            model,
            base_url: "https://api.openai.com/v1".to_string(),
            history: Vec::new(),
        }
    }

    /// 发送用户消息并流式打印响应
    async fn chat(&mut self, user_input: &str) -> anyhow::Result<String> {
        // 将用户消息加入历史
        self.history.push(Message {
            role: "user".to_string(),
            content: user_input.to_string(),
        });

        let request = ChatRequest {
            model: self.model.clone(),
            messages: self.history.clone(),
            stream: true,
        };

        // 发送流式请求
        let response = self.client
            .post(format!("{}/chat/completions", self.base_url))
            .header("Authorization", format!("Bearer {}", self.api_key))
            .json(&request)
            .send()
            .await?;

        // 检查 HTTP 状态码
        if !response.status().is_success() {
            let status = response.status();
            let body = response.text().await?;
            anyhow::bail!("API 请求失败 [{}]：{}", status, body);
        }

        // 逐行解析 SSE 流
        let mut full_response = String::new();
        let mut stream = response.bytes_stream();
        use futures_util::StreamExt;

        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 let Some(data) = line.strip_prefix("data: ") {
                    if data == "[DONE]" {
                        break;
                    }
                    if let Ok(delta) = serde_json::from_str::<StreamDelta>(data) {
                        if let Some(content) = delta.choices.first()
                            .and_then(|c| c.delta.content.as_ref())
                        {
                            print!("{}", content);
                            io::stdout().flush()?;
                            full_response.push_str(content);
                        }
                    }
                }
            }
        }

        println!(); // 换行

        // 将助手响应加入历史
        self.history.push(Message {
            role: "assistant".to_string(),
            content: full_response.clone(),
        });

        Ok(full_response)
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let api_key = std::env::var("OPENAI_API_KEY")
        .map_err(|_| anyhow::anyhow!("请设置 OPENAI_API_KEY 环境变量"))?;

    let mut cli = AiCli::new(api_key, "gpt-4o-mini".to_string());

    // 简单的 REPL 循环
    println!("AI CLI 已启动，输入消息开始对话，输入 :quit 退出");
    loop {
        print!("> ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input == ":quit" {
            break;
        }
        if input.is_empty() {
            continue;
        }

        match cli.chat(input).await {
            Ok(_) => {}
            Err(e) => eprintln!("错误：{}", e),
        }
    }

    Ok(())
}

这段代码的关键点在于 SSE 流的增量解析。bytes_stream() 返回的字节流可能在不完整的 UTF-8 边界处分割，所以需要用 buffer 缓存未处理的片段。每收到一行 data: {...} 格式的 SSE 数据，解析出增量内容并立即打印，实现流式输出效果。

四、Rust AI 工具的工程挑战与权衡

API 兼容性：不同 LLM 提供商的 API 格式不完全一致。OpenAI、Claude、Gemini 的请求和响应结构各有差异。一个务实的做法是定义统一的内部消息格式，各提供商实现各自的适配器。这增加了代码量，但避免了供应商锁定。

错误处理与重试：LLM API 调用可能因为网络问题、速率限制、服务端错误而失败。流式请求的重试比普通请求复杂——需要记录已接收的增量，重试后从断点续传。大多数情况下，简单的全量重试更可靠，代价是用户可能看到重复输出。

Token 计数与上下文管理：对话历史超过模型上下文窗口时，需要截断或摘要。Rust 中没有现成的 tokenizer 库覆盖所有模型，通常需要调用 Python 的 tiktoken 或使用 WASM 编译的 tokenizer。这增加了依赖复杂度。

Function Calling 的类型安全：LLM 返回的 function call 参数是 JSON 字符串，需要反序列化为 Rust 结构体。serde_json 可以处理，但如果 LLM 返回的 JSON 格式不符合预期（这在实际使用中经常发生），反序列化会失败。需要在反序列化失败时给 LLM 反馈，让它修正参数格式。

五、总结

Rust 在 AI 工具开发中的核心优势是零依赖分发、快速启动和内存安全。架构上，AI 工具分为用户交互、任务编排、AI 调用和工具执行四个层次。SSE 流式输出的增量解析是 AI 调用层的关键技术点。主要工程挑战包括 API 兼容性、流式重试、Token 计数和 Function Calling 的类型安全。Rust AI 工具的开发成本高于 Python，但在分发体验和运行稳定性上有明显优势。适合需要分发给终端用户、嵌入 CI/CD 或长时间运行的 Agent 场景。