AI 驱动的命令行工具：从 CLI 到智能 Agent 的构建实践

AI 驱动的命令行工具：从 CLI 到智能 Agent 的构建实践

一、命令行工具的"智能升级"：为什么 CLI 需要 AI

传统命令行工具是"指令-执行"模式：用户输入精确命令，工具返回结果。但实际使用中，用户经常记不住命令参数、不知道该用什么选项、面对报错信息手足无措。一个典型的场景：find . -name "*.rs" -type f -mtime -7 | xargs grep "TODO"——这条命令组合了 find、管道、xargs、grep，新手根本写不出来。

AI 驱动的 CLI 工具解决的是"意图到命令"的翻译问题：用户用自然语言描述想做什么，AI 将其翻译为精确的命令行操作。更进一步，智能 Agent 可以自主执行多步操作——分析报错、搜索文档、尝试修复，而不只是翻译命令。

二、AI CLI 工具的技术架构与 Agent 循环

flowchart TB
    A[用户意图<br/>自然语言描述] --> B[意图解析<br/>LLM 翻译为命令]
    B --> C[命令执行<br/>沙箱环境运行]
    C --> D{执行结果}
    D -->|成功| E[返回结果]
    D -->|失败| F[错误分析<br/>LLM 解读报错]
    F --> G{可自动修复?}
    G -->|是| H[生成修复命令<br/>重新执行]
    G -->|否| I[返回错误分析<br/>建议手动操作]

    H --> C

    subgraph Agent 循环
        J[观察 Observe<br/>读取执行输出]
        K[思考 Think<br/>LLM 分析下一步]
        L[行动 Act<br/>生成并执行命令]
    end

    J --> K --> L --> J

Agent 循环是智能 CLI 的核心模式：观察（读取命令输出）→ 思考（LLM 分析下一步）→ 行动（生成并执行命令）。循环持续进行直到任务完成或遇到无法解决的问题。关键约束：每一步都需要用户确认，避免 Agent 执行破坏性操作。

三、AI CLI Agent 的 Rust 实现

Agent 核心循环

use std::process::Command;
use std::io::{self, Write};

/// Agent 执行上下文
struct AgentContext {
    /// 对话历史（用于 LLM 上下文）
    history: Vec<Message>,
    /// 最大循环次数（防止无限循环）
    max_iterations: usize,
    /// 是否需要用户确认每步操作
    require_confirmation: bool,
}

/// 消息类型
enum Message {
    User(String),
    Assistant(String),
    System(String),
    ToolResult { command: String, output: String, exit_code: i32 },
}

/// Agent 执行结果
struct AgentResult {
    success: bool,
    final_output: String,
    steps_taken: usize,
    commands_executed: Vec<String>,
}

impl AgentContext {
    fn new() -> Self {
        AgentContext {
            history: vec![Message::System(
                "你是一个命令行助手。用户会用自然语言描述需求，\
                 你需要生成合适的 shell 命令。\
                 规则：1. 只生成安全的命令，不执行 rm -rf 等危险操作 \
                 2. 每次只生成一条命令 3. 如果命令失败，分析原因并重试 \
                 4. 不确定时询问用户".to_string()
            )],
            max_iterations: 10,
            require_confirmation: true,
        }
    }

    /// Agent 主循环：观察 → 思考 → 行动
    async fn run(&mut self, user_intent: &str) -> AgentResult {
        self.history.push(Message::User(user_intent.to_string()));

        let mut steps = 0;
        let mut commands = Vec::new();

        while steps < self.max_iterations {
            steps += 1;

            // 1. 思考：调用 LLM 生成下一步命令
            let llm_response = self.call_llm().await;

            // 解析 LLM 输出，提取命令
            let command = match self.extract_command(&llm_response) {
                Some(cmd) => cmd,
                None => {
                    // LLM 没有生成命令，可能是在询问用户或任务完成
                    return AgentResult {
                        success: true,
                        final_output: llm_response,
                        steps_taken: steps,
                        commands_executed: commands,
                    };
                }
            };

            // 2. 安全检查：拒绝危险命令
            if self.is_dangerous_command(&command) {
                self.history.push(Message::Assistant(
                    format!("拒绝执行危险命令: {}", command)
                ));
                return AgentResult {
                    success: false,
                    final_output: format!("拒绝执行危险命令: {}", command),
                    steps_taken: steps,
                    commands_executed: commands,
                };
            }

            // 3. 用户确认（如果启用）
            if self.require_confirmation {
                println!("将执行: {}", command);
                print!("确认执行? [y/N] ");
                io::stdout().flush().unwrap();

                let mut input = String::new();
                io::stdin().read_line(&mut input).unwrap();
                if !input.trim().eq_ignore_ascii_case("y") {
                    println!("已取消");
                    return AgentResult {
                        success: false,
                        final_output: "用户取消执行".to_string(),
                        steps_taken: steps,
                        commands_executed: commands,
                    };
                }
            }

            // 4. 行动：执行命令
            let result = self.execute_command(&command).await;
            commands.push(command.clone());

            // 5. 观察：将执行结果加入上下文
            self.history.push(Message::ToolResult {
                command,
                output: result.output.clone(),
                exit_code: result.exit_code,
            });

            // 6. 判断是否完成
            if result.exit_code == 0 && self.is_task_complete(&result.output) {
                return AgentResult {
                    success: true,
                    final_output: result.output,
                    steps_taken: steps,
                    commands_executed: commands,
                };
            }
        }

        AgentResult {
            success: false,
            final_output: "达到最大循环次数，任务未完成".to_string(),
            steps_taken: steps,
            commands_executed: commands,
        }
    }

    /// 执行 shell 命令并捕获输出
    async fn execute_command(&self, command: &str) -> CommandResult {
        // 使用 sh -c 执行命令，支持管道和重定向
        let output = Command::new("sh")
            .arg("-c")
            .arg(command)
            .output();

        match output {
            Ok(output) => CommandResult {
                exit_code: output.status.code().unwrap_or(-1),
                output: String::from_utf8_lossy(&output.stdout).to_string()
                    + &String::from_utf8_lossy(&output.stderr),
            },
            Err(e) => CommandResult {
                exit_code: -1,
                output: format!("命令执行失败: {}", e),
            },
        }
    }

    /// 危险命令检测
    fn is_dangerous_command(&self, command: &str) -> bool {
        let dangerous_patterns = [
            "rm -rf /",
            "rm -rf ~",
            "mkfs",
            "dd if=",
            "> /dev/sd",
            "chmod 777 /",
            ":(){ :|:& };:",  // fork bomb
        ];
        dangerous_patterns.iter().any(|p| command.contains(p))
    }

    /// 从 LLM 响应中提取命令
    fn extract_command(&self, response: &str) -> Option<String> {
        // 查找 ```bash 或 ```sh 代码块
        if let Some(start) = response.find("```bash\n").or_else(|| response.find("```sh\n")) {
            let code_start = start + 8;
            if let Some(end) = response[code_start..].find("```") {
                return Some(response[code_start..code_start + end].trim().to_string());
            }
        }
        // 查找 $ 开头的命令行
        for line in response.lines() {
            let trimmed = line.trim();
            if trimmed.starts_with("$ ") {
                return Some(trimmed[2..].to_string());
            }
        }
        None
    }

    async fn call_llm(&self) -> String {
        // 实际实现中调用 LLM API
        // 这里返回占位符
        "请提供 LLM API 实现".to_string()
    }

    fn is_task_complete(&self, _output: &str) -> bool {
        // 简化判断：需要更复杂的逻辑
        true
    }
}

struct CommandResult {
    exit_code: i32,
    output: String,
}

四、AI CLI Agent 的安全边界与工程妥协

安全是第一优先级：Agent 可以执行任意 shell 命令，这意味着它可以做任何事——包括删除文件、修改系统配置。必须实现：危险命令黑名单、用户确认机制、沙箱执行环境。生产环境中，Agent 应在 Docker 容器或虚拟机中执行命令，限制文件系统和网络访问。

LLM 幻觉的风险：LLM 可能生成不存在的命令或错误的参数组合。Agent 必须验证命令的执行结果，而非盲目信任 LLM 的输出。如果命令返回错误，Agent 应分析错误原因并重试，而非继续执行下一步。

成本控制：Agent 循环的每一步都需要调用 LLM API，10 步循环可能消耗 10 次 API 调用。对于简单任务（单条命令即可完成），应直接翻译而非启动 Agent 循环。Agent 模式应仅在多步骤任务中启用。

五、总结

AI 驱动的 CLI 工具将"指令-执行"模式升级为"意图-翻译-执行-反馈"循环。落地建议：第一，简单翻译任务用单次 LLM 调用，多步骤任务才启动 Agent 循环；第二，危险命令黑名单 + 用户确认是安全底线，不能省略；第三，Agent 在沙箱环境中执行，限制文件系统和网络访问；第四，每步验证执行结果，LLM 幻觉生成的错误命令必须被捕获和纠正。智能 CLI 不是让用户不再学命令行，而是让命令行的学习曲线更平缓。