rust-cli-agent-style

OpenAI Codex Rust CLI Agent 最佳实践

本技能将教你按照 OpenAI Codex 代码库的风格编写 Rust 代码——这是一个生产级 CLI/Agent 系统，包含 50 个 crate 和 787 个 Rust 文件。

主要特点

• Edition 2024，并采用严格的 Clippy 配置
• 非测试代码中不使用 unwrap/expect（在工作区级别强制执行）
• Tokio 异步运行时，并正确设置 Send + Sync 约束
• 库错误使用 thiserror，应用程序代码使用 anyhow
• 采用扁平工作区结构，集中管理依赖项

适用场景

在以下场景中应用此技能：

• 使用 Rust 构建 CLI 工具或 Agent 系统
• 使用 Tokio 编写 Rust 异步代码
• 设计 Rust 工作区组织结构
• 实现错误处理模式
• 开发生产级 Rust 代码库

快速参考

关键规则（必须遵守）

规则	说明
err-no-unwrap	非测试代码中绝不使用 unwrap()
err-no-expect	库代码中避免使用 expect()
err-thiserror-domain	使用 thiserror 处理领域错误
err-context-chain	使用 .context() 为错误添加上下文

错误处理

规则	说明
err-anyhow-application	入口点使用 anyhow::Result
err-from-derive	使用 #[from] 进行错误转换
err-transparent	对包装错误使用 #[error(transparent)]
err-structured-variants	在错误变体中包含相关数据
err-io-result	I/O 函数使用 std::io::Result
err-map-err-conversion	使用 map_err 进行错误转换
err-doc-errors	说明错误条件

组织结构

规则	说明
org-workspace-flat	使用 utils 子目录的扁平工作区
org-crate-naming	目录使用 kebab-case，并添加项目名称前缀
org-module-visibility	内部 API 使用 pub(crate)
org-test-common-crate	使用共享测试工具 crate
org-integration-tests-suite	在 suite 目录中存放测试
org-feature-modules	按功能组织模块
org-handlers-subdir	在专用子目录中存放处理器
org-errors-file	在专用文件中存放错误定义

组件模式

规则	描述
mod-derive-order	统一 derive 宏的顺序
mod-async-trait-macro	对异步 trait 使用 #[async_trait]
mod-trait-bounds	并发 trait 使用 Send + Sync + 'static
mod-extension-trait-suffix	扩展 trait 使用 Ext 后缀
mod-builder-pattern	复杂配置使用 Builder 模式
mod-type-alias-complex	复杂泛型使用类型别名
mod-impl-block-order	统一 impl 块的顺序
mod-generic-constraints	复杂约束使用 Where 子句
mod-newtype-pattern	使用 Newtype 确保类型安全
mod-struct-visibility	字段私有，构造函数公开
mod-serde-rename	为线格式使用 Serde rename
mod-jsonschema-derive	API 类型使用 JsonSchema

命名约定

规则	描述
name-async-no-suffix	异步函数不使用 _async 后缀
name-try-prefix-fallible	可失败的构造函数使用 try_ 前缀
name-with-prefix-builder	Builder 方法使用 with_ 前缀
name-handler-suffix	处理器使用 Handler 后缀
name-error-suffix	错误类型使用 Error 后缀
name-result-type-alias	Crate 专用的 Result 别名
name-const-env-var	环境常量使用 _ENV_VAR 后缀
name-request-response	Request/Response 类型配对
name-options-suffix	配置集合使用 Options 后缀
name-info-suffix	只读数据使用 Info 后缀
name-provider-suffix	服务使用 Provider 后缀
name-client-suffix	API 客户端使用 Client 后缀
name-manager-suffix	生命周期管理使用 Manager 后缀
name-bool-is-prefix	布尔值使用 is_/has_/should_ 前缀
name-plural-collections	集合使用复数名称

风格

规则	描述
style-import-granularity	每条 use 语句导入一个项目
style-deny-stdout	库中禁止使用 stdout/stderr
style-inline-format-args	内联 format 参数
style-module-docs	模块级文档
style-expect-reason	使用 #[expect] 时注明 lint 原因
style-cfg-test-module	在 mod tests 中编写单元测试

跨 Crate

规则	描述
cross-workspace-lints	工作区级 lint 配置
cross-workspace-deps	集中管理依赖版本

示例：正确处理错误

use thiserror::Error;
use anyhow::Context;

// Domain error with thiserror
#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("failed to read config file: {path}")]
    ReadFailed {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error(transparent)]
    Parse(#[from] toml::de::Error),
}

// Library function returns domain error
pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)
        .map_err(|source| ConfigError::ReadFailed {
            path: path.to_owned(),
            source,
        })?;
    toml::from_str(&content).map_err(Into::into)
}

// Application code uses anyhow with context
fn main() -> anyhow::Result<()> {
    let config = load_config(Path::new("config.toml"))
        .context("failed to load configuration")?;
    run(config).await
}

来源

模式提取自 OpenAI Codex（codex-rs/ 子目录）——一个用于生产环境的 Rust 代码库，包含 50 个 crate 和 787 个 Rust 文件。