/// Codex CLI // 文档注释：说明这是多合一 CLI，无子命令时选项转发给交互式 TUI#[derive(Debug, Parser)] // clap derive：自动生成参数解析代码#[clap( // clap 属性块开始：下面逐条配置顶层 parser 的行为    author, // 帮助信息里带上作者字段    version, // 支持 --version 输出构建版本    subcommand_negates_reqs = true, // 给了子命令就豁免默认参数的必填约束——exec 不需要 TUI 的必填项    bin_name = "codex", // 即使二进制被改名（如 codex-x86_64-unknown-linux-musl），帮助里也显示通用名 codex    override_usage = "codex [OPTIONS] [PROMPT]\n       codex [OPTIONS] <COMMAND> [ARGS]" // 手写用法行：两种形态——直接给 PROMPT，或给子命令)]struct MultitoolCli { // 顶层 CLI 结构体，名字直白：多工具合一    #[clap(flatten)] // flatten：把 CliConfigOverrides 的所有字段摊平到本层，-c key=value 覆盖配置    pub config_overrides: CliConfigOverrides, // -c key=value 覆盖项的容器，后面会前置合并到各子命令    #[clap(flatten)] // --enable/--disable feature flag 也摊平进来，后面统一折叠成配置覆盖    pub feature_toggles: FeatureToggles, // --enable/--disable 开关的原始值，稍后折叠成配置覆盖    #[clap(flatten)] // --remote 等远程 app-server 选项    remote: InteractiveRemoteOptions, // --remote 端点与 token env，指向远程 app-server    #[clap(flatten)] // TUI 交互模式的全部选项（prompt、model、sandbox-mode…）    interactive: TuiCli, // prompt/model/sandbox-mode 等交互模式选项的集合    #[clap(subcommand)] // 子命令是 Option：None = 直接进交互式 TUI，Some(cmd) = 走对应分支    subcommand: Option<Subcommand>, // None=进 TUI，Some(cmd)=路由到对应子命令} // MultitoolCli 定义结束：四个 flatten 组 + 一个可选子命令

#[derive(Debug, clap::Subcommand)] // clap 子命令 derive：每个变体自动成为一条子命令enum Subcommand { // 20+ 变体的路由表，每个变体携带自己的参数结构体    /// Browse all agent sessions on the shared local app-server daemon. // agents：浏览共享本地守护进程上的所有会话    Agents(AgentsCommand), // agents 子命令的参数结构体（含 --remote/cwd/no-alt-screen）    /// Run Codex non-interactively. // exec：非交互执行，CI/脚本场景的主力入口    #[clap(visible_alias = "e")] // 可见别名 e——codex e 等价 codex exec，但帮助里会显示出来    Exec(ExecCli), // exec 参数结构体，定义在 exec/src/cli.rs    /// Run a code review non-interactively. // review：对当前仓库跑一次代码审查    Review(ReviewCommand), // review 参数：--uncommitted/--base/--commit 三选一    /// Manage login. // login：OAuth/凭证管理入口（第 6 讲细讲）    Login(LoginCommand), // login 子命令（status 等），凭证管理入口    /// Remove stored authentication credentials. // logout：清掉本地存的凭证    Logout(LogoutCommand), // logout：清除本地存储的认证凭证    /// Manage external MCP servers for Codex. // mcp：MCP server 的增删查登出    Mcp(McpCli), // mcp 参数结构体，含 list/get/add/remove/login/logout 子命令    /// Manage Codex plugins. // plugin：插件与 marketplace 管理    Plugin(PluginCli), // plugin 参数结构体：add/list/marketplace/remove    /// [experimental] Run the app server or related tooling. // app-server：RPC 网关（第 42 讲）    AppServer(AppServerCommand), // app-server 参数：可带 daemon/proxy/generate-ts 等子命令

fn main() -> anyhow::Result<()> { // 进程入口：返回 Result，错误统一走 anyhow    codex_build_info::initialize!(); // 宏展开：初始化构建信息（版本、commit），供 --version/遥测用    let remote_control_disabled = codex_app_server::take_remote_control_disabled_env(); // 取走环境变量并清空——一次性消费，避免子进程继承    arg0_dispatch_or_else(move |arg0_paths: Arg0DispatchPaths| async move { // argv[0] 分发：先判断自己是不是"隐藏身份"（第四节细讲）        cli_main(arg0_paths, remote_control_disabled).await?; // 不是特殊身份才走真正的 CLI 主流程        Ok(()) // cli_main 成功返回，整个进程以 Ok 收尾    }) // arg0_dispatch_or_else 闭包结束：非特殊身份才走到这里} // main() 函数体结束

let open_agents_overview = matches!(&subcommand, Some(Subcommand::Agents(_))); // 提前判断：是否要打开 agents 总览界面match subcommand { // 路由大 match：Option<Subcommand>，None 和 Agents 都走交互式 TUI    None | Some(Subcommand::Agents(_)) => { // 无子命令 = 直接进 TUI；agents = 带总览的 TUI        prepend_config_flags( // 把根级 -c 覆盖前置到 interactive 自己的覆盖列表里——根选项优先级更高            &mut interactive.config_overrides, // 目标：interactive 自己的覆盖列表            root_config_overrides.clone(), // 源：根级 -c/--enable 折叠出的覆盖项        ); // 合并完成，根选项优先级更高        let exit_info = run_interactive_tui( // 启动 TUI（第 45-46 讲细讲），返回退出信息            interactive, // TUI 的全部解析结果            root_remote.clone(), // 远程端点（agents 模式必填）            root_remote_auth_token_env.clone(), // token 所在环境变量名            arg0_paths.clone(), // argv[0] 分发得到的辅助可执行文件路径        )        .await?; // 异步启动 TUI，错误用 ? 上抛        handle_app_exit(exit_info)?; // 统一处理退出：fatal 报错、执行挂起的 update action    }    Some(Subcommand::Exec(mut exec_cli)) => { // exec 分支：非交互执行        reject_remote_mode_for_subcommand( // exec 是本地执行的，和 --remote 互斥——提前 fail loud            root_remote.as_deref(), // exec 与 --remote 互斥：传了就直接报错            root_remote_auth_token_env.as_deref(), // token env 同样不允许出现在 exec 上            "exec", // 错误信息里指明是哪个子命令触发的冲突        )?; // 校验失败立即退出，fail loud        exec_cli.shared.inherit_exec_root_options(&interactive.shared); // 继承根级共享选项（model、sandbox-mode…）        exec_cli.strict_config |= root_strict_config; // 根级 --strict-config 对子命令同样生效        prepend_config_flags( // 同样的"根覆盖前置"合并逻辑            &mut exec_cli.config_overrides, // exec 自己的覆盖列表            root_config_overrides.clone(), // 根级覆盖项前置合并（与 TUI 分支同一套路）        );        codex_exec::run_main(exec_cli, arg0_paths.clone()).await?; // 真正交给 codex-exec crate（exec/src/lib.rs）    }

if exe_name == CODEX_LINUX_SANDBOX_ARG0 { // 以 codex-linux-sandbox 名字启动 → 直接进 Linux 沙箱主流程    // Safety: [`run_main`] never returns. // run_main 内部会 exec bwrap，永不返回——所以这里不用 else    codex_linux_sandbox::run_main(); // 进入 bwrap/landlock 沙箱主流程，内部 exec 后永不返回} else if exe_name == APPLY_PATCH_ARG0 || exe_name == MISSPELLED_APPLY_PATCH_ARG0 { // apply_patch（连拼错的 applypatch 也认）→ 补丁工具模式    codex_apply_patch::main(); // 补丁工具模式：读 stdin 的 patch 并应用}let argv1 = args.next().unwrap_or_default(); // 再看第一个参数：有些"身份"藏在 argv[1] 的魔法标志里#[cfg(unix)] // 仅 unix 平台存在 exec-helperif argv1 == CODEX_ARG0_EXEC_HELPER_ARG1 { // --codex-run-as-arg0-exec-helper → exec-server 的执行助手进程    codex_exec_server::run_arg0_exec_helper_main(); // 执行助手：在沙箱外代跑命令并回传结果}if argv1 == CODEX_FS_HELPER_ARG1 { // --codex-run-as-fs-helper → exec-server 的文件系统助手（跨沙箱读写）    codex_exec_server::run_fs_helper_main(); // fs helper：跨沙箱边界的文件读写代理}

std::fs::create_dir_all(&codex_home)?; // 确保 ~/.codex 存在let temp_root = codex_home.join("tmp").join("arg0"); // 别名目录放在 CODEX_HOME/tmp/arg0 下，不污染顶层std::fs::create_dir_all(&temp_root)?; // 确保 ~/.codex/tmp/arg0 存在#[cfg(unix)] // unix 分支：用符号链接做别名{    use std::os::unix::fs::PermissionsExt; // 引入 PermissionsExt 才能调 from_mode    std::fs::set_permissions(&temp_root, std::fs::Permissions::from_mode(0o700))?; // 0o700：只有当前用户能访问——别名目录是敏感面}let temp_dir = tempfile::Builder::new() // 每次启动建一个 codex-arg0-* 会话目录，进程退出自动清理    .prefix("codex-arg0") // 目录名带前缀，便于识别和清理    .tempdir_in(&temp_root)?; // 建在 arg0 根目录下；TempDir guard 退出时自动删除...for filename in &[APPLY_PATCH_ARG0, MISSPELLED_APPLY_PATCH_ARG0, CODEX_LINUX_SANDBOX_ARG0] { // 逐个创建别名    let exe = std::env::current_exe()?; // 目标就是当前这个 codex 二进制本身    #[cfg(unix)]    {        let link = path.join(filename); // 别名完整路径，如 ~/.codex/tmp/arg0/codex-arg0-xxx/apply_patch        symlink(&exe, &link)?; // apply_patch → codex：符号链接，名字不同身份就不同    }}

/// Print events to stdout as JSONL. // --json：事件流以 JSONL 打到 stdout——机器可读，管道友好#[arg(long = "json", alias = "experimental-json", default_value_t = false, global = true)] // --json 带旧别名兼容；global=true 让子命令层也能用pub json: bool, // JSONL 事件流开关，默认关（人类可读输出）/// Specifies file where the last message from the agent should be written. // -o/--output-last-message：把最终回复写文件，方便脚本取结果#[arg(long = "output-last-message", short = 'o', value_name = "FILE", global = true)] // -o 短选项：最终回复落盘路径pub last_message_file: Option<PathBuf>, // None=不写文件，stdout 即唯一输出通道/// Initial instructions for the agent. If not provided as an argument (or if `-` is used), // PROMPT 位置参数：不给或给 - 就从 stdin 读instructions are read from stdin. // stdin 管道 + prompt 同时存在时，stdin 作为 <stdin> 块附加#[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)] // 位置参数 PROMPT；hint=Other 让补全不当成文件路径pub prompt: Option<String> // None 或 "-" 时从 stdin 读指令,

impl From<ResumeArgsRaw> for ResumeArgs { // Raw → 正式结构体的转换：在这里做语义重解释    fn from(raw: ResumeArgsRaw) -> Self { // Raw→正式结构体：在这里做条件语义重解释        // When --last is used without an explicit prompt, treat the positional as the prompt        let (session_id, prompt) = if raw.last && raw.prompt.is_none() { // 开了 --last 且没给显式 prompt → 位置参数其实是 prompt            (None, raw.session_id) // session_id 置空（--last 会选最近会话），原位置值挪去当 prompt        } else { // 常规路径：没开 --last，位置参数就是 session id            (raw.session_id, raw.prompt) // 常规路径：位置参数就是 session id        };        Self { // 组装正式结构体            session_id, // --last 模式下为 None，由运行时选最近会话            last: raw.last, // 是否取最近一次会话            all: raw.all, // true=跨 cwd 列出所有会话            images: raw.images, // 恢复后附带的图片（逗号分隔多张）            prompt, // 重解释后的 prompt（可能来自原位置参数）        }    }}

async fn build_report( // 构建诊断报告：按依赖顺序串起所有检查项    command: &DoctorCommand, // doctor 自己的选项：--json/--summary 等    root_config_overrides: CliConfigOverrides, // 根级 -c 覆盖，load_config 时生效    interactive: &TuiCli, // TUI 选项里含 cwd/remote，诊断时要一并检查    arg0_paths: &Arg0DispatchPaths, // argv[0] 辅助路径：sandbox 可用性检查要用) -> DoctorReport { // 返回聚合报告，含每项状态与耗时    let progress = doctor_progress(command.json); // 进度上报器：json 模式下静默，人类模式打点    let mut checks = Vec::new(); // 检查结果收集器：按执行顺序 push    checks.push(run_sync_check("system", progress.clone(), system_check)); // ① 系统信息（OS/架构/终端）——无依赖，最先跑    checks.push(run_async_check("endpoint protection", progress.clone(), security::check()).await); // ② 端点防护状态    checks.push(run_sync_check("installation", progress.clone(), || installation_check(!command.summary))); // ③ 安装形态（npm/standalone）    checks.push(run_sync_check("runtime", progress.clone(), runtime_check)); // ④ 运行时健康    checks.push(run_sync_check("search", progress.clone(), search_check)); // ⑤ ripgrep 等搜索工具可用性    let config_result = load_config(root_config_overrides, interactive, arg0_paths).await; // 加载配置——后面一堆检查都依赖它    ...    checks.push(run_sync_check("disk", progress.clone(), || disk::check(config_result.as_ref().ok(), &cwd))); // ⑥ 磁盘空间：拿不到 config 就传 None，降级而非崩溃

pub enum McpSubcommand { // MCP server 管理：六个动词，覆盖完整生命周期    List(ListArgs),   // list [--json]：列出已配置 server    Get(GetArgs),     // get <NAME> [--json]：看单个 server 的配置    Add(AddArgs),     // add <NAME> (--url <URL> | -- <COMMAND>...)：注册 streamable-http 或 stdio server    Remove(RemoveArgs), // remove <NAME>：删除配置    Login(LoginArgs),   // login：OAuth 登录（MCP server 需要鉴权时）    Logout(LogoutArgs), // logout：登出}

启动路径（argv[0] → 业务 crate）

▼

▼

▼

▼