代理循环 — 代码走读

codex-rs/core/src/session/mod.rs — 会话状态机（3404 行）

Codex struct 是代理循环的核心，实现了事件驱动的队列对模式：

pub struct Codex {
    tx_sub: Sender<Submission>,       // 操作提交通道
    rx_event: Receiver<Event>,         // 事件接收通道
    agent_status: watch::Receiver<AgentStatus>,
    session: Arc<Session>,             // 共享会话状态
    session_loop_termination: SessionLoopTermination,
}

核心方法调用链：

方法	功能	调用链
Codex::spawn(args)	创建 Session	→ 启动事件循环 task
submit(Op)	提交操作	→ tx_sub.send(Submission)
next_event()	获取下一个事件	← rx_event.recv()
steer_input()	运行时中断/引导	→ 修改当前 turn 行为

Session struct（3404 行）是实际的状态管理器，关键方法包括：

impl Session {
    fn build_initial_context()        // 组装完整上下文
    fn handle_submission()            // 处理提交的操作
    fn emit_turn_item_started()       // 发出 turn item 开始事件
    fn emit_turn_item_completed()     // 发出 turn item 完成事件
    fn request_command_approval()     // 请求命令审批
    fn request_patch_approval()       // 请求补丁审批
    fn record_conversation_items()    // 记录对话条目
    fn replace_compacted_history()    // 替换压缩历史
    fn update_token_usage_info()      // 更新 token 用量
    fn persist_execpolicy_amendment() // 持久化策略修改
    fn steer_input()                  // 运行时引导
    fn interrupt_task()               // 中断当前任务
}

codex-rs/core/src/codex_thread.rs — 线程封装

CodexThread 是 Codex 的高级封装，为外部消费者提供更友好的 API：

pub struct CodexThread {
    codex: Codex,
    session_source: SessionSource,
    session_configured: SessionConfiguredEvent,
    rollout_path: Option<PathBuf>,
    out_of_band_elicitation_count: usize,
}

关键方法：

方法	功能
submit(Op)	提交操作到 Session
next_event() -> Event	等待并返回下一个事件
agent_status()	获取当前代理状态
steer_input()	引导/中断当前 turn
token_usage_info()	获取 token 用量信息
config_snapshot()	获取配置快照（ThreadConfigSnapshot）
load_history()	加载对话历史
read_mcp_resource()	读取 MCP 资源
call_mcp_tool()	调用 MCP 工具
apply_thread_settings_overrides()	应用线程级配置覆盖
inject_response_items()	注入响应条目

CodexThreadSettingsOverrides 定义了 per-turn 可修改的设置：

pub struct CodexThreadSettingsOverrides {
    pub cwd: Option<PathBuf>,
    pub workspace_roots: Option<Vec<PathBuf>>,
    pub approval_policy: Option<ApprovalPolicy>,
    pub sandbox_policy: Option<SandboxPolicy>,
    pub permission_profile: Option<PermissionProfileName>,
    pub model: Option<String>,
    pub effort: Option<ReasoningEffort>,
    pub summary: Option<ReasoningSummary>,
    pub service_tier: Option<ServiceTier>,
    pub collaboration_mode: Option<CollaborationMode>,
    pub personality: Option<Personality>,
}

codex-rs/core/src/client.rs — 模型客户端（2254 行）

ModelClient 管理 LLM API 的连接和调用：

pub struct ModelClient {
    state: Arc<ModelClientState>,
    prompt_cache_key_override: Option<String>,
}

传输层级：优先 WebSocket，回退到 HTTP SSE。两者都使用 Responses API（/responses 端点）：

impl ModelClient {
    pub fn new_session(&self) -> ModelClientSession  // 创建 turn-scoped session
    pub fn compact_conversation_history()             // 压缩对话历史
    pub fn create_realtime_call_with_headers()         // 发起实时调用
}

impl ModelClientSession {
    pub async fn stream(&self) -> ResponseStream      // 获取流式响应
    pub async fn prewarm_websocket()                   // 预热 WebSocket
}

ModelClientState 内部字段：

字段	功能
session_id	会话唯一标识
thread_id	线程标识
provider: SharedModelProvider	模型提供商
session_source	会话来源
cached_websocket_session	WebSocket 连接缓存
disable_websockets	禁用 WebSocket 标志

codex-rs/apply-patch/src/lib.rs — 补丁解析与应用

StreamingPatchParser 流式解析 *** Begin Patch 格式的补丁文本：

pub fn parse_patch(patch: &str) -> Result<Vec<Hunk>, ParseError>

pub struct ApplyPatchArgs {
    pub patch: String,
    pub hunks: Vec<Hunk>,
    pub workdir: Option<String>,
    pub environment_id: Option<String>,
}

pub fn verify_apply_patch_args(args: &ApplyPatchArgs) -> Result<(), ApplyPatchError>

错误类型 ApplyPatchError：ParseError（解析失败）、IoError（IO 错误）、ComputeReplacements（替换计算失败）、ImplicitInvocation（隐式调用）。

codex-rs/core/src/rollout/ — Rollout 记录

Rollout 模块负责记录代理循环的完整执行轨迹：

pub struct RolloutRecorder {
    // 记录每个 turn 的模型输入/输出、工具调用、执行结果
}

pub struct RolloutRecorderParams {
    pub cursor: Cursor,
    pub session_meta: SessionMeta,
}

pub struct Cursor { /* 会话位置标记 */ }
pub struct SessionMeta { /* 会话元数据 */ }

ThreadManager 管理多线程的生命周期：

pub struct ThreadManager {
    // 线程创建、恢复、归档、分叉
}

pub struct NewThread { /* 新线程参数 */ }
pub struct StartThreadOptions { /* 启动选项 */ }
pub struct ForkSnapshot { /* 分叉快照 */ }

关键函数索引

函数/模块	文件路径	说明
Codex::spawn()	core/src/session/mod.rs	创建 Session，启动事件循环
Session::build_initial_context()	core/src/session/mod.rs	组装完整 LLM 输入上下文
Session::handle_submission()	core/src/session/mod.rs	处理提交的操作，驱动代理循环
ModelClient::new_session()	core/src/client.rs	创建 turn-scoped 模型会话
ModelClientSession::stream()	core/src/client.rs	发起流式 LLM 调用
CodexThread::submit()	core/src/codex_thread.rs	提交操作到线程
CodexThread::next_event()	core/src/codex_thread.rs	等待下一个事件
parse_patch()	apply-patch/src/lib.rs	解析补丁文本为 Hunk 列表
verify_apply_patch_args()	apply-patch/src/lib.rs	验证补丁参数
compact_conversation_history()	core/src/client.rs	压缩对话历史
RolloutRecorder	core/src/rollout/	执行轨迹记录
ThreadManager	core/src/thread_manager.rs	多线程生命周期管理