用 Rust 和 GLM-5 做一个流式翻译 CLI

这几个依赖基本是这类工具的标配：

• tokio 负责异步运行时，HTTP 请求和流式读取都靠它撑着。
• reqwest 处理 HTTP，json 和 stream 两个 feature 都用得上。
• serde / serde_json 用来序列化请求、解析返回。
• clap 做命令行参数解析，子命令结构比较自然。
• anyhow 用来统一错误处理，写工具时省心很多。
• colored 负责终端颜色输出，主要是提升交互感。
• bytes 和 futures-util 则是流式处理时的辅助组件。

核心实现

项目结构保持简单一点：main.rs 负责入口，cli.rs 解析命令行，api.rs 处理请求，translator.rs 放业务逻辑。这个拆法不花哨，但够用。

入口文件 main.rs

mod api;
mod cli;
mod translator;
use anyhow::Result;
use clap::Parser;
use cli::{Cli, Commands};

#[tokio::main]
async fn main() -> Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Commands::Text(args) => {
            translator::translate_text(args).await?;
        }
        Commands::File(args) => {
            translator::translate_file(args).await?;
        }
    }
    Ok(())
}

这里最关键的是 #[tokio::main]。它把异步 main 包起来，运行时初始化也一起做了。然后用 Clap 把参数解析出来，再按子命令分发到不同处理函数。逻辑很直，不需要绕。

命令行定义 cli.rs

use clap::{Parser, Subcommand, Args};

#[derive(Parser, Debug)]
#[command(name = "ai-translator", ...)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,
}

#[derive(Subcommand, Debug)]
pub enum Commands {
    Text(TextArgs),
    File(FileArgs),
}
// ... TextArgs 和 FileArgs 的定义

子命令分成 Text 和 File，对应直接输入文本和翻译文件两种场景。Args 负责具体参数，比如 --lang、--output。这种结构在 CLI 里很常见，后续要扩展别的能力也不别扭。

请求和流式解析 api.rs

这部分是整个工具最容易写'看着能跑，实际一堆边界问题'的地方。重点不是发请求，而是把 SSE 流处理稳。

先定义请求和响应结构：

use anyhow::{Context, Result};
use bytes::Bytes;
use futures_util::StreamExt;
use reqwest::Client;
use serde::{Deserialize, Serialize};

const MODEL_ID: &str = "glm-5";
const BASE_URL: &str = "https://api.example.com/v1/chat/completions";
const API_KEY: &str = "xxxxxxxxxxx";

#[derive(Debug, Serialize)]
pub struct ChatRequest {
    pub model: String,
    pub messages: Vec<ChatMessage>,
    pub stream: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChatMessage {
    pub role: String,
    pub content: String,
}

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

#[derive(Debug, Deserialize)]
pub struct Choice {
    pub message: Option<ChatMessage>,
    pub delta: Option<Delta>,
}

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

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

pub struct ApiClient {
    client: Client,
}

impl ApiClient {
    pub fn new() -> Result<Self> {
        let client = Client::builder()
            .timeout(std::time::Duration::from_secs(120))
            .build()
            .context("Failed to build HTTP client")?;
        Ok(Self { client })
    }

    pub async fn chat_stream<F>(&self, messages: Vec<ChatMessage>, mut on_chunk: F,) -> Result<String>
    where
        F: FnMut(&str),
    {
        let request = ChatRequest {
            model: MODEL_ID.to_string(),
            messages,
            stream: true,
            max_tokens: Some(4096),
            temperature: Some(0.3),
        };

        let response = self.client
            .post(BASE_URL)
            .header("Authorization", format!("Bearer {}", API_KEY))
            .header("Content-Type", "application/json")
            .json(&request)
            .send()
            .await
            .context("请求失败")?;

        if !response.status().is_success() {
            let status = response.status();
            let body = response.text().await.unwrap_or_default();
            anyhow::bail!("API 错误 {}: {}", status, body);
        }

        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: Bytes = chunk.context("流读取错误")?;
            let text = String::from_utf8_lossy(&chunk);
            buffer.push_str(&text);

            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["data: ".len()..];
                    if data == "[DONE]" {
                        break;
                    }
                    if let Ok(chunk_data) = serde_json::from_str::<StreamChunk>(data) {
                        for choice in chunk_data.choices {
                            if let Some(delta) = choice.delta {
                                if let Some(content) = delta.content {
                                    on_chunk(&content);
                                    full_content.push_str(&content);
                                }
                            }
                        }
                    }
                }
            }
        }
        Ok(full_content)
    }
}

SSE 这块的坑主要在分片，不是每次读到的数据都能正好对齐到一整行，所以要留一个 buffer。先拼接，再按换行拆。这个处理方式不花哨，但比'读到就直接解析'靠谱得多。

on_chunk 用闭包回调出来也挺实用：网络层只管接收，UI 层负责打印，两个职责分开，后面想改成写文件或者走别的输出方式都不用动底层。

业务逻辑 translator.rs

翻译任务本身不复杂，关键是把提示词说清楚，把输入输出路径处理好。

use anyhow::Result;
use colored::*;
use std::io::{self, Write};
use crate::api::{ApiClient, ChatMessage};
use crate::cli::{FileArgs, TextArgs};

fn build_messages(text: &str, target_lang: &str) -> Vec<ChatMessage> {
    vec![
        ChatMessage {
            role: "system".to_string(),
            content: format!(
                "你是一个专业翻译引擎。请将用户输入的英文内容翻译成{}。\n只输出翻译结果，不要添加任何解释、注释或额外文字。\n保持原文的格式、换行和段落结构。",
                target_lang
            ),
        },
        ChatMessage {
            role: "user".to_string(),
            content: text.to_string(),
        },
    ]
}

pub async fn translate_text(args: TextArgs) -> Result<()> {
    let client = ApiClient::new()?;
    println!("{} 翻译中...", ">>".cyan().bold());
    println!();

    let messages = build_messages(&args.text, &args.target_lang);
    let stdout = io::stdout();
    let mut handle = stdout.lock();

    client
        .chat_stream(messages, |chunk| {
            handle.write_all(chunk.as_bytes()).ok();
            handle.flush().ok();
        })
        .await?;

    drop(handle);
    println!();
    Ok(())
}

pub async fn translate_file(args: FileArgs) -> Result<()> {
    let content = std::fs::read_to_string(&args.input).map_err(|e| anyhow::anyhow!("读取文件 '{}' 失败：{}", args.input, e))?;
    if content.trim().is_empty() {
        anyhow::bail!("文件内容为空");
    }

    println!("{} 正在翻译文件：{}", ">>".cyan().bold(), args.input.yellow());
    println!("{} 文件大小：{} 字符", " ".dimmed(), content.len());
    println!();

    let client = ApiClient::new()?;
    let messages = build_messages(&content, &args.target_lang);

    let result = if let Some(ref output_path) = args.output {
        println!("{}", "--- 翻译结果 ---".green().bold());
        let stdout = io::stdout();
        let mut handle = stdout.lock();
        let translated = client
            .chat_stream(messages, |chunk| {
                handle.write_all(chunk.as_bytes()).ok();
                handle.flush().ok();
            })
            .await?;
        drop(handle);
        println!();
        println!("{}", "--- 结束 ---".green().bold());
        std::fs::write(output_path, &translated).map_err(|e| anyhow::anyhow!("写入文件 '{}' 失败：{}", output_path, e))?;
        println!("\n{} 翻译结果已保存到：{}", "✓".green().bold(), output_path.cyan());
        translated
    } else {
        println!("{}", "--- 翻译结果 ---".green().bold());
        let stdout = io::stdout();
        let mut handle = stdout.lock();
        let translated = client
            .chat_stream(messages, |chunk| {
                handle.write_all(chunk.as_bytes()).ok();
                handle.flush().ok();
            })
            .await?;
        drop(handle);
        println!();
        println!("{}", "--- 结束 ---".green().bold());
        translated
    };

    let _ = result;
    Ok(())
}

这里的提示词没有写得太绕，目的很明确：只翻译，别解释，别加多余输出。翻译工具最怕模型'热心过头'，一旦开始加注释，CLI 体验会立刻变差。

文件模式下，先读内容，再决定是只打印还是边打印边保存。stdout.lock() 这个细节不算大招，但对终端输出还是有帮助，至少不会让输出到处乱跳。

编译和发布

代码写完以后直接构建发布版：

cargo build --release

--release 会打开优化，编译时间长一些，但生成的二进制更适合拿去日常使用。Rust 的优势在这里很直观：最后拿到的是一个干净的可执行文件，不用额外带一堆运行时文件。

构建完成后，产物会落在 target/release 目录下，名字就是 ai-translator。

功能验证

先测最基础的文本翻译：

./target/release/ai-translator text "Hello, this is a test sentence."

如果输出能正常流式打印，说明请求、解析、回调这条链路基本通了。

再试试语言参数：

./target/release/ai-translator text "Hello world" -l "日文"

这一步主要看目标语言有没有被正确塞进 system prompt。只要参数生效，模型输出通常会跟着变。

文件翻译也要跑一遍。假设有个 readme.txt：

./target/release/ai-translator file ./readme.txt

如果要保存到本地：

./target/release/ai-translator file ./readme.txt -o ./readme_cn.txt

最后再组合一次语言切换和输出文件：

./target/release/ai-translator file ./readme.txt -l "日文" -o ./readme_cn.txt

这几个命令覆盖了最常见的使用路径。能跑通它们，工具就算比较完整了。

结尾

这个项目本质上不是在'做一个翻译器'，而是在把 Rust 的异步网络能力、CLI 参数组织能力和大模型接口拼成一个可用的生产工具。它的价值不在于代码多漂亮，而在于结构够稳：命令行入口清楚，流式处理不脆，文件和文本两种场景都能兜住。

如果后面要扩展，方向也很自然：支持更多模型、加批量目录翻译、接入环境变量读取 Key，或者把输出格式再收紧一点。基础骨架已经够了，后面的变化不会太难。