AI 驱动的命令行工具：用 Rust 构建智能 Agent 的工程实践

最新推荐文章于 2026-06-27 13:39:30 发布

原创最新推荐文章于 2026-06-27 13:39:30 发布 · 168 阅读

6 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#rust #github #python

AI 驱动的命令行工具：用 Rust 构建智能 Agent 的工程实践

cover

一、从脚本到智能体：命令行工具的进化困境

传统的命令行工具遵循"输入-处理-输出"的线性模式。用户必须精确记住每个参数和选项，任何模糊需求都只能靠人工排查。当 AI 能力注入命令行后，工具从"被动执行器"进化为"主动理解者"——用户可以用自然语言描述意图，工具自动解析、规划并执行。

但工程落地的痛点随之而来：大模型 API 调用的延迟如何与命令行的即时响应预期协调？流式输出（Streaming）如何与终端渲染配合？多轮对话的上下文如何在进程间持久化？这些问题不是简单的 API 调用就能解决的，需要从架构层面进行设计。

Rust 在这个场景下有独特优势：零成本抽象保证了工具的启动速度，强类型系统确保了 API 交互的可靠性，异步运行时天然适配流式响应。

二、智能 Agent 的架构设计与数据流

2.1 核心架构分层

一个 AI 驱动的命令行工具，至少需要四个核心层：

graph LR
    A[用户输入层<br/>自然语言/命令混合] --> B[意图解析层<br/>LLM API 调用]
    B --> C[任务编排层<br/>Tool Call 解析与调度]
    C --> D[执行层<br/>本地命令/文件操作/网络请求]
    D --> E[结果聚合层<br/>格式化输出/流式渲染]
    E -->|反馈循环| B
    C -->|Tool Call| F[工具注册表<br/>函数签名与描述]
    F --> C

2.2 流式响应与终端渲染

大模型的响应延迟通常在 500ms 到数秒之间。如果等到完整响应再输出，用户体验极差。流式输出（Server-Sent Events）是必须的，但终端环境下的流式渲染有特殊要求：

Markdown 实时渲染：代码块、表格等格式化内容需要增量解析
中断处理：用户按 Ctrl+C 时需要优雅终止流式请求
进度指示：等待首个 token 时显示 spinner 动画

2.3 Tool Call 协议

OpenAI 的 Function Calling 和 Anthropic 的 Tool Use 是当前主流的 Agent 工具调用协议。核心流程是：LLM 返回结构化的工具调用请求，客户端解析后执行本地操作，再将结果回传给 LLM 继续推理。

三、生产级代码实现

3.1 流式请求与终端渲染

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

#[derive(Deserialize)]
struct StreamDelta {
    choices: Vec<Choice>,
}

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

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

/// 流式请求大模型 API，逐 token 输出到终端
async fn stream_chat(
    client: &Client,
    api_url: &str,
    api_key: &str,
    messages: Vec<serde_json::Value>,
) -> Result<String, Box<dyn std::error::Error>> {
    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))
        .header("Content-Type", "application/json")
        .json(&body)
        .send()
        .await?;

    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();

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

        // SSE 格式：data: {...}\n\n
        for line in text.lines() {
            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);
                        full_content.push_str(content);
                    }
                }
            }
        }
    }

    Ok(full_content)
}

3.2 Tool Call 解析与调度

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

#[derive(Debug, Serialize, Deserialize)]
struct ToolDefinition {
    name: String,
    description: String,
    parameters: serde_json::Value, // JSON Schema
}

#[derive(Debug, Deserialize)]
struct ToolCall {
    id: String,
    function: FunctionCall,
}

#[derive(Debug, Deserialize)]
struct FunctionCall {
    name: String,
    arguments: String, // JSON 字符串
}

/// 工具注册表：维护所有可用工具的签名和执行函数
struct ToolRegistry {
    tools: HashMap<String, Box<dyn Fn(serde_json::Value) -> Result<String, String> + Send + Sync>>,
    definitions: Vec<ToolDefinition>,
}

impl ToolRegistry {
    fn new() -> Self {
        ToolRegistry {
            tools: HashMap::new(),
            definitions: Vec::new(),
        }
    }

    fn register<F>(&mut self, def: ToolDefinition, handler: F)
    where
        F: Fn(serde_json::Value) -> Result<String, String> + Send + Sync + 'static,
    {
        self.definitions.push(def.clone());
        self.tools.insert(def.name, Box::new(handler));
    }

    fn execute(&self, call: &ToolCall) -> Result<String, String> {
        let handler = self
            .tools
            .get(&call.function.name)
            .ok_or_else(|| format!("未知工具: {}", call.function.name))?;

        let args: serde_json::Value =
            serde_json::from_str(&call.function.arguments)
                .map_err(|e| format!("参数解析失败: {}", e))?;

        handler(args)
    }
}

3.3 上下文持久化

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
struct ChatMessage {
    role: String,
    content: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    tool_calls: Option<Vec<ToolCall>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    tool_call_id: Option<String>,
}

/// 对话上下文管理器：支持持久化到本地文件
struct ContextManager {
    messages: Vec<ChatMessage>,
    max_tokens: usize, // 上下文窗口上限，超出时截断早期消息
}

impl ContextManager {
    fn new(max_tokens: usize) -> Self {
        ContextManager {
            messages: Vec::new(),
            max_tokens,
        }
    }

    fn add_message(&mut self, msg: ChatMessage) {
        self.messages.push(msg);
        self.truncate_if_needed();
    }

    /// 简易截断策略：保留系统提示 + 最近 N 轮对话
    fn truncate_if_needed(&mut self) {
        // 估算 token 数（粗略：中文约 1.5 字/token，英文约 4 字符/token）
        let estimated_tokens: usize = self
            .messages
            .iter()
            .map(|m| m.content.len() / 2)
            .sum();

        if estimated_tokens > self.max_tokens {
            // 保留第一条（系统提示）和最后 10 条
            if self.messages.len() > 11 {
                self.messages.drain(1..self.messages.len() - 10);
            }
        }
    }

    fn save_to_file(&self, path: &str) -> Result<(), Box<dyn std::error::Error>> {
        let json = serde_json::to_string_pretty(&self.messages)?;
        std::fs::write(path, json)?;
        Ok(())
    }

    fn load_from_file(path: &str) -> Result<Self, Box<dyn std::error::Error>> {
        let json = std::fs::read_to_string(path)?;
        let messages: Vec<ChatMessage> = serde_json::from_str(&json)?;
        Ok(ContextManager {
            messages,
            max_tokens: 8192,
        })
    }
}