Codex CLI 源码拆解：OpenAI 的 Rust Agent 运行时——为什么重写能解决 Node.js 的"生死问题"

codex-main/
├── codex-cli/bin/codex.js     # TypeScript 薄壳：平台检测 → 启动原生二进制
├── codex-rs/                  # Rust Workspace（60+ crate）
│   ├── cli/                   # CLI 参数解析
│   ├── tui/                   # TUI（ratatui + crossterm）
│   ├── exec/                  # 无交互模式
│   ├── core/                  # ★ Agent 大脑：Session/Turn/Context/ModelClient
│   ├── protocol/              # Op/Event 核心协议
│   ├── app-server/            # IDE/桌面宿主
│   ├── app-server-protocol/   # JSON-RPC v1/v2
│   ├── tools/                 # 工具注册表
│   ├── sandboxing/            # 跨平台沙箱抽象层
│   ├── linux-sandbox/         # Landlock + bubblewrap
│   ├── windows-sandbox-rs/    # 受限 token + ACL + WFP
│   ├── core-skills/           # 技能系统
│   ├── core-plugins/          # 插件系统
│   └── thread-store/          # 线程/会话持久化
└── sdk/                       # Python / TypeScript SDK

Submission Queue (Op)        →  用户提交操作
  UserTurn                    →  发起对话轮次
  Interrupt                   →  中断当前执行
  ConfigureSession            →  修改会话配置
Event Queue (EventMsg)       ←  Agent 推送事件
  TurnStarted                 ←  轮次开始
  AgentMessageDelta           ←  流式文本增量
  ExecCommandBegin            ←  开始执行命令
  ToolCallRequest             ←  请求工具调用
  PermissionRequest           ←  请求权限审批

// codex-rs/core/src/session/turn.rs
pub async fn run_turn(session: &mut Session) -> Result<AgentMessage> {
    // 0. 创建 ModelClientSession（每 turn 独立，不跨 turn 复用）
    let client_session = create_model_client_session(session).await?;
    // 1. 上下文过长 → 先压缩
    run_pre_sampling_compact_if_needed(session).await?;
    // 2. 构建上下文：AGENTS.md + 技能 + 插件 + 工具声明 + 环境信息
    let context = build_context(session)?;
    // 3. 执行 hooks + 记录输入
    run_pre_turn_hooks(session).await?;
    // 4. 进入循环
    loop {
        let output = run_sampling_request(&client_session, &context).await?;
        if output.needs_tool_follow_up {
            // 模型请求工具调用 → 执行 → 结果注入历史 → 继续
            execute_tools_and_record(&output.tool_calls).await?;
            continue;
        }
        if has_pending_interrupt().await {
            // 有中断信号 → 处理 → 继续
            continue;
        }
        // 模型返回普通文本 → 记录 → 结束 turn
        return Ok(output.last_agent_message);
    }
}

// tools/registry.rs
pub trait ToolHandler: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> serde_json::Value;
    async fn execute(&self, input: serde_json::Value) -> Result<ToolOutput>;
}

// 只读工具共享读锁，有副作用的工具拿写锁
let lock = if tool.is_read_only() {
    RwLock::read(&self.parallel_state)
} else {
    RwLock::write(&self.parallel_state)
};

// sandboxing/src/lib.rs
pub struct SandboxCommand {
    pub executable: PathBuf,
    pub args: Vec<String>,
    pub env: HashMap<String, String>,
    pub working_dir: PathBuf,
    pub network_access: NetworkPolicy,      // None | LocalOnly | Full
    pub filesystem_access: FilesystemPolicy, // ReadOnly | WorkspaceWrite | Full
}

发现顺序（从当前目录向上到 .git 根）：
  ./AGENTS.md
  ../AGENTS.md
  ../../AGENTS.md
  ...直到 .git 根目录
覆盖规则：
  AGENTS.override.md 覆盖同目录的 AGENTS.md
  （Claude Code 用 .local.md 实现类似效果）

用户输入 "Refactor auth module"
  │
  ▼
┌──────────────────────────────────────┐
│ 1. codex-cli/bin/codex.js            │  TypeScript 壳
│    检测平台 → spawn Rust 二进制       │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│ 2. cli/ 解析命令                      │  Rust
│    codex exec "Refactor auth module"  │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│ 3. core/ 创建 Session + Thread        │
│    加载 AGENTS.md ×3                  │
│    加载 Skills / Plugins              │
│    初始化 ModelClientSession           │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│ 4. run_turn 主循环                     │
│    ┌─ build_context()                │
│    ├─ run_sampling_request()         │
│    │   └─ OpenAI Responses API       │
│    │       (WebSocket prewarm)       │
│    ├─ [工具调用?] → execute_tools()  │
│    │   ├─ sandboxing::sandbox_cmd()  │
│    │   ├─ Seatbelt/Landlock/ACL      │
│    │   └─ 结果写入历史               │
│    └─ [文本?] → 记录 → 结束 turn     │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│ 5. protocol/ 推送 Event 给所有宿主    │
│    AgentMessageDelta → TUI 流式显示   │
│    PermissionRequest → IDE 弹窗       │
└──────────────────────────────────────┘