1. 为什么我要用 Rust 重写一个 TypeScript 写的 CLI 工具先说背景。我手上有一个自己维护了一年多的命令行工具叫 Pi定位是一个轻量级的 AI Agent 编排器。它的核心工作很明确接收用户输入的自然语言指令拆解成若干步骤调用不同的模型接口和本地工具最后把结果拼装成可读的输出。整个工具大概有 8000 行 TypeScript 代码依赖 Node 运行时通过 npm 全局安装。这个工具在日常使用中没什么大问题功能也稳定。但有一个痛点一直困扰我启动速度。每次执行pi 帮我整理一下这个目录下的日志这样的命令从按下回车到看到第一个字符输出平均要等 1.2 到 1.8 秒。如果机器负载高一点或者 npm 全局包多了之后这个数字能飙到 2.5 秒以上。你可能觉得一两秒不算什么但对于一个 CLI 工具来说这个延迟是致命的。CLI 的使用场景就是高频、短平快。我一天可能要调用它几十次每次等两秒累积起来就是几分钟的纯等待。更关键的是这种延迟会让人产生这个工具很重的心理暗示久而久之就不想用了。于是我决定用 Rust 重写。结果冷启动时间从平均 1.5 秒降到了 150 毫秒左右快了整整 10 倍。这篇文章我会把整个重写过程拆开讲包括技术选型、架构设计、踩过的坑、性能优化的具体手段以及最终的效果对比。如果你也在维护一个 TypeScript 写的 CLI 工具或者正在考虑用 Rust 做 Agent 相关的开发这篇内容应该能给你不少参考。2. 先搞清楚TypeScript CLI 的启动时间到底花在哪了在动手重写之前我做了一件事量化分析启动耗时。不搞清楚时间花在哪重写就是盲目的。2.1 用 Node 内置的 profiler 定位瓶颈Node 提供了--cpu-prof参数可以生成 CPU 性能分析文件。我用它跑了一次 Pi 的启动过程node --cpu-prof --cpu-prof-dir./profiles ./dist/cli.js test然后用 Chrome DevTools 打开生成的.cpuprofile文件看到了启动阶段的时间分布。结果和我预想的差不多主要耗时集中在三个地方耗时环节平均耗时占比Node 运行时初始化约 80ms6%模块加载与解析约 620ms42%依赖库初始化约 450ms30%业务逻辑执行约 320ms22%模块加载是大头。Pi 依赖了不少 npm 包包括命令行参数解析、HTTP 客户端、JSON 处理、日志库等等。每个包都有自己的依赖树Node 的require机制需要逐个读取文件、解析、执行。虽然 V8 有编译缓存但首次加载或者缓存失效时这个开销非常明显。2.2 依赖库初始化为什么这么慢更隐蔽的问题在依赖库初始化。我用了某个流行的 HTTP 客户端库它在模块加载时会做一堆事情检测运行环境、初始化连接池配置、注册全局拦截器、加载 TLS 证书列表。这些操作在服务端场景下是合理的但在 CLI 场景下完全是浪费——我可能只是执行一个本地文件操作根本不需要 HTTP 功能。还有一个日志库它在初始化时会读取环境变量、检测终端颜色支持、加载配置文件。这些操作单个看起来不慢但累积起来就是几百毫秒。2.3 一个容易被忽略的细节TypeScript 编译产物Pi 是用 TypeScript 写的编译目标是 CommonJS。编译后的代码里充满了__importDefault、__createBinding这样的辅助函数每个模块文件都会生成一遍。虽然单个函数的执行时间可以忽略但几千个模块累积起来也是不可忽视的开销。另外TypeScript 的esModuleInterop和allowSyntheticDefaultImports这些选项会让编译产物多一层包装。对于 CLI 这种对启动速度敏感的场景这些包装都是成本。这里给一个实操建议如果你维护的 TypeScript CLI 工具启动慢先用node --cpu-prof跑一次看看时间到底花在哪。不要凭感觉优化数据会告诉你真相。3. Rust 重写的整体架构设计搞清楚瓶颈之后我开始设计 Rust 版本。核心目标很明确把启动时间压到 200ms 以内同时保持功能完整。3.1 为什么选 Rust 而不是 Go在决定用 Rust 之前我也考虑过 Go。Go 的编译速度快、部署简单、标准库丰富对于 CLI 工具来说是很务实的选择。但最终选 Rust有几个原因第一启动速度。Rust 编译出的二进制是原生机器码没有运行时初始化开销。Go 虽然也编译成原生二进制但它的运行时需要初始化 goroutine 调度器、垃圾回收器等组件启动时间通常在几毫秒到几十毫秒。Rust 没有 GC没有运行时启动就是操作系统加载二进制、跳转到入口点几乎零开销。第二内存占用。Rust 的零成本抽象意味着我可以精确控制内存分配。对于 Agent 这种需要处理大量文本、维护会话状态的场景内存效率很重要。第三生态。Rust 的 CLI 生态已经非常成熟clap做参数解析、tokio做异步运行时、serde做序列化、reqwest做 HTTP 客户端。这些库的质量和性能都经过大规模验证。当然Rust 也有代价开发速度比 TypeScript 慢学习曲线陡编译时间长。但对于一个已经想清楚架构的工具来说这些代价是值得的。3.2 模块划分与依赖选型Rust 版本的 Pi 我划分了这几个核心模块cli 模块负责参数解析、命令路由、帮助信息生成。用clap的 derive 模式编译期生成解析代码运行时几乎没有反射开销。agent 模块核心编排逻辑负责任务拆解、步骤调度、状态管理。provider 模块模型接口的抽象层支持不同的后端。tool 模块本地工具的注册与调用包括文件操作、命令执行、文本处理。config 模块配置加载支持文件、环境变量、命令行参数三级覆盖。依赖选型上我遵循一个原则能不用异步就不用异步。CLI 工具的很多操作是顺序执行的引入异步运行时反而增加复杂度。最终只有网络请求部分用了tokio其他都是同步代码。[dependencies] clap { version 4, features [derive] } serde { version 1, features [derive] } serde_json 1 reqwest { version 0.12, features [json, rustls-tls], default-features false } tokio { version 1, features [rt-multi-thread, macros] } anyhow 1注意reqwest我关掉了默认特性只启用json和rustls-tls。默认特性会引入一堆用不到的东西比如原生 TLS、gzip 解压等增加二进制体积和编译时间。3.3 二进制体积优化Rust 默认编译出的二进制文件比较大因为包含了调试符号和标准库的完整实现。我在Cargo.toml里加了发布配置[profile.release] opt-level z lto true codegen-units 1 strip true panic abort这几个配置的作用分别是opt-level z优化体积而非速度对 CLI 来说体积更重要、lto true开启链接时优化、codegen-units 1减少并行编译单元以换取更好的优化、strip true去掉符号信息、panic abort在 panic 时直接终止而不是展开栈。最终二进制从默认的 12MB 压到了 3.8MB启动速度也有小幅提升。4. 核心模块的 Rust 实现细节架构定下来之后就是具体的编码。这部分我挑几个关键模块讲讲实现思路和踩过的坑。4.1 参数解析clap 的 derive 模式怎么用TypeScript 版本用的是commander运行时解析参数。Rust 版本用clap的 derive 模式在编译期生成解析代码。use clap::{Parser, Subcommand}; #[derive(Parser)] #[command(name pi, version, about AI Agent 编排器)] struct Cli { /// 要执行的指令 #[arg(short, long)] prompt: OptionString, /// 配置文件路径 #[arg(short, long, default_value ~/.pi/config.toml)] config: String, #[command(subcommand)] command: OptionCommands, } #[derive(Subcommand)] enum Commands { /// 初始化配置 Init, /// 列出可用工具 Tools, /// 执行单步任务 Run { task: String }, }这种写法的好处是类型安全参数解析结果直接映射到结构体字段编译期就能发现类型错误。而且clap生成的解析代码非常高效没有反射没有动态查找。实操心得clap的 derive 模式虽然方便但遇到复杂的参数依赖关系时还是需要手写Arg和Command。我的建议是先用 derive 快速搭出骨架遇到搞不定的场景再局部改成 builder 模式。4.2 Agent 编排状态机 vs 链式调用Agent 的核心是把用户指令拆解成步骤然后按顺序执行。TypeScript 版本用的是链式调用每个步骤是一个 Promise通过then串联。这种写法在 JS 里很自然但在 Rust 里会很别扭因为 Rust 的异步生态和所有权模型对链式调用不太友好。我改用了状态机模式。每个任务是一个状态状态之间的转移由执行结果决定enum TaskState { Pending, Running { step: usize }, WaitingForTool { tool: String, args: VecString }, Completed { result: String }, Failed { error: String }, } struct Agent { state: TaskState, steps: VecStep, context: HashMapString, String, } impl Agent { fn next(mut self) - Result() { match self.state { TaskState::Pending { self.state TaskState::Running { step: 0 }; } TaskState::Running { step } { let current self.steps[*step]; // 执行当前步骤根据结果决定下一个状态 } // ... } Ok(()) } }状态机的好处是逻辑清晰每个状态的转移条件都显式写在代码里调试时很容易定位问题。而且 Rust 的match表达式对枚举的处理非常优雅编译器会强制你处理所有分支。4.3 工具调用如何安全地执行本地命令Pi 需要调用本地工具比如读取文件、执行 shell 命令、处理文本。这部分是安全敏感区域TypeScript 版本用的是child_process.execRust 版本我用std::process::Command。关键点是参数传递方式。绝对不要用字符串拼接的方式构造命令那样会有注入风险。正确做法是把命令和参数分开传递use std::process::Command; fn run_tool(name: str, args: [String]) - ResultString { let output Command::new(name) .args(args) .output()?; if !output.status.success() { let stderr String::from_utf8_lossy(output.stderr); return Err(anyhow!(工具执行失败: {}, stderr)); } Ok(String::from_utf8_lossy(output.stdout).to_string()) }Command::new接收的是程序名args接收的是参数数组操作系统会正确处理参数边界不存在注入问题。另外我加了一个工具白名单机制。只有注册在配置里的工具才能被调用防止 Agent 执行任意命令。这个白名单在配置加载时校验不在白名单里的工具直接拒绝。4.4 配置加载三级覆盖的实现配置加载我设计了三层默认配置、配置文件、命令行参数。优先级从低到高后面的覆盖前面的。#[derive(Deserialize, Default)] struct Config { model: OptionString, api_base: OptionString, max_steps: Optionusize, tools: OptionVecString, } impl Config { fn load(path: str, cli_args: Cli) - ResultSelf { let mut config Config::default(); // 第一层默认值 config.max_steps Some(10); // 第二层配置文件 if let Ok(content) fs::read_to_string(path) { let file_config: Config toml::from_str(content)?; config.merge(file_config); } // 第三层命令行参数 if let Some(model) cli_args.model { config.model Some(model.clone()); } Ok(config) } }merge方法的逻辑是如果新配置的字段是Some就覆盖旧值如果是None保留旧值。这样每一层只需要关心自己显式设置的字段。踩坑记录配置文件路径我一开始用了~展开但 Rust 标准库不自动展开波浪号。需要手动处理HOME环境变量或者用dirs这个 crate。我最后用了dirs::home_dir()跨平台兼容性更好。5. 性能优化的关键手段与实测数据代码写完之后就是性能调优。这部分我做了几轮迭代每一轮都有明确的优化目标和测量数据。5.1 启动路径的懒加载策略Rust 虽然没有运行时初始化开销但如果入口函数里做了太多事情启动一样会慢。我的优化原则是入口函数只做参数解析和命令路由其他一切按需加载。具体来说配置文件读取、工具注册、模型客户端初始化这些操作都延迟到真正需要的时候才执行。比如用户执行pi --help就只走参数解析路径不加载任何配置和工具。fn main() - Result() { let cli Cli::parse(); match cli.command { Some(Commands::Init) init_config(), Some(Commands::Tools) list_tools(), Some(Commands::Run { task }) { // 只有执行任务时才加载完整配置 let config Config::load(cli.config, cli)?; run_task(task, config) } None { if let Some(prompt) cli.prompt { let config Config::load(cli.config, cli)?; run_task(prompt, config) } else { Cli::command().print_help()?; Ok(()) } } } }这个改动让--help和--version的响应时间降到了 20ms 以内几乎无感。5.2 减少二进制体积的编译配置前面提到的Cargo.toml发布配置实际效果很明显。我做了对比测试配置项默认 release优化后 release二进制体积12.3 MB3.8 MB冷启动时间210ms150ms内存占用峰值18 MB9 MB体积减小带来的启动提升主要是因为操作系统加载更少的页面减少了磁盘 I/O 和内存映射开销。5.3 实测数据冷启动与热启动对比最终的性能数据我用hyperfine做了基准测试。测试环境是一台 2021 款的笔记本SSD16GB 内存。hyperfine --warmup 3 pi --version node ./dist/cli.js --version结果命令平均耗时标准差Rust 版本pi --version18ms2msTypeScript 版本node cli.js --version180ms15msRust 版本完整任务152ms12msTypeScript 版本完整任务1520ms180ms完整任务的对比更明显从 1.5 秒降到 150 毫秒正好 10 倍。这个提升主要来自三个方面没有 Node 运行时初始化、没有模块加载开销、没有依赖库的冗余初始化。5.4 内存占用的意外收获除了启动速度内存占用也大幅下降。TypeScript 版本运行时内存峰值在 45MB 左右Rust 版本只有 9MB。对于在资源受限环境下运行 Agent 的场景这个差异很有意义。内存优化的主要来源是没有 V8 堆、没有垃圾回收器、字符串处理用str切片避免拷贝、集合类型预分配容量。6. 重写过程中踩过的坑与排查技巧这部分是我觉得最有价值的内容。Rust 重写不是一帆风顺的我踩了不少坑有些坑花了大半天才定位到。6.1 异步运行时的初始化开销一开始我在main函数上直接加了#[tokio::main]结果发现即使执行--version这样的命令启动时间也有 80ms 左右。排查后发现tokio的多线程运行时在初始化时会创建线程池这个开销对于不需要异步的命令来说是浪费。解决方案是按需初始化运行时。只在真正需要网络请求的地方创建运行时fn run_async_taskF, T(future: F) - T where F: std::future::FutureOutput T, { tokio::runtime::Builder::new_current_thread() .enable_all() .build() .unwrap() .block_on(future) }用new_current_thread而不是new_multi_thread因为 CLI 工具的异步任务通常是顺序的不需要多线程调度。这个改动让需要网络请求的命令启动时间从 80ms 降到了 15ms。6.2 字符串处理的性能陷阱Rust 的字符串处理很灵活但如果不注意很容易产生不必要的拷贝。我一开始写代码时习惯性地用String接收所有文本结果发现处理大文件时内存占用很高。后来改成了str和Cowstruse std::borrow::Cow; fn process_text(input: str) - Cowstr { if input.contains(需要替换的内容) { Cow::Owned(input.replace(需要替换的内容, 替换后的内容)) } else { Cow::Borrowed(input) } }Cow的意思是写时复制如果不需要修改就借用原始数据如果需要修改才分配新内存。这个模式在处理文本时非常实用。6.3 常见问题速查表我把重写过程中遇到的问题整理成了表格方便快速查阅问题现象可能原因排查方法解决方案启动时间超过 200ms入口函数做了太多初始化在入口函数各阶段打时间戳延迟加载按需初始化二进制体积超过 10MB未开启 LTO 和 stripls -lh target/release/pi配置 release profile异步命令启动慢tokio 多线程运行时初始化对比同步和异步命令的启动时间改用 current_thread 运行时内存占用高字符串频繁拷贝用valgrind或heaptrack分析改用str和Cow编译时间过长codegen-units 过多观察cargo build输出开发时用默认配置发布时再优化独家避坑技巧Rust 的编译时间在开发阶段很影响体验。我的做法是开发时用cargo check而不是cargo build只做类型检查不生成二进制速度快很多。需要实际运行时再用cargo run。6.4 跨平台兼容性的注意事项Pi 需要在多个操作系统上运行跨平台兼容性是个绕不开的问题。我遇到的主要是路径处理和命令调用的差异。路径处理上Windows 用反斜杠Unix 用正斜杠。Rust 的std::path::Path会自动处理这些差异但字符串拼接路径时容易出错。我的做法是统一用PathBuf和join方法use std::path::PathBuf; let config_path dirs::home_dir() .unwrap() .join(.pi) .join(config.toml);命令调用上Windows 的cmd和 Unix 的sh行为不同。如果 Agent 需要执行 shell 命令需要根据平台选择不同的解释器。我封装了一个函数处理这个差异fn shell_command(cmd: str) - Command { if cfg!(target_os windows) { let mut c Command::new(cmd); c.args([/C, cmd]); c } else { let mut c Command::new(sh); c.args([-c, cmd]); c } }7. 从 TypeScript 迁移到 Rust 的经验总结最后聊聊迁移策略。8000 行 TypeScript 代码不是小数目不可能一次性重写。我采用的是渐进式迁移。7.1 渐进式迁移的步骤第一步先重写 CLI 入口和参数解析。这部分逻辑独立改动风险小而且能立刻看到启动速度的提升。Rust 版本先只支持--version和--help其他命令转发给 TypeScript 版本。第二步重写配置加载和工具注册。这部分是纯逻辑不涉及网络请求迁移难度低。第三步重写 Agent 编排核心。这是最复杂的部分需要仔细设计状态机和错误处理。第四步重写模型接口调用。这部分涉及异步和网络放在最后。每一步都保证 Rust 版本可以独立运行通过环境变量控制走哪个版本。这样即使 Rust 版本有问题也能快速回退。7.2 哪些场景适合用 Rust 重写 CLI不是所有 TypeScript CLI 都值得用 Rust 重写。我的判断标准是高频使用如果工具每天被调用几十次以上启动速度的提升能明显改善体验。性能敏感如果工具需要处理大量数据、执行复杂计算Rust 的性能优势更明显。分发需求如果需要分发给不熟悉 Node 环境的用户单个二进制文件比 npm 包更方便。长期维护如果工具会长期维护Rust 的类型系统和错误处理能减少运行时问题。反过来如果工具只是内部偶尔使用、逻辑经常变动、团队不熟悉 Rust那继续用 TypeScript 更务实。7.3 给准备重写的朋友几条建议第一先测量再优化。不要凭感觉认为 TypeScript 慢用 profiler 找到真正的瓶颈。第二不要追求一次性重写。渐进式迁移风险更低而且能持续看到收益。第三重视错误处理。Rust 的Result和anyhow让错误处理更清晰但需要改变写 TypeScript 时的思维习惯。第四善用社区 crate。CLI 领域的常见需求比如参数解析、配置加载、进度条、颜色输出都有成熟的 crate不要重复造轮子。第五保持功能对等。重写过程中容易忍不住加新功能但这会让迁移复杂度失控。先把现有功能完整迁移再考虑新特性。我在实际迁移中发现最耗时的不是写 Rust 代码而是理解原有 TypeScript 代码的隐含逻辑。很多行为没有文档只能通过读代码和测试来推断。所以如果你的 TypeScript 项目缺少测试建议先补测试再迁移这样能保证行为一致性。另外一个小技巧迁移过程中保留 TypeScript 版本作为参考实现遇到不确定的行为时跑一下 TypeScript 版本看输出然后让 Rust 版本对齐。这个双跑对比的方法能省很多调试时间。