企业官网建设流程全解析

• 人工智能
• AI 插件
• 代码智能体

/codex:review是 codex-plugin-cc 插件提供的只读代码审查命令，它绕过自定义提示词，直接调用你本机 Codex CLI 的内置评审器（built-in reviewer），让你在 Claude Code 工作流中拿到与在 Codex 里执行/review完全一致的审查质量。读完本文，你将掌握该命令的完整参数语义（--wait、--background、--base、--scope）、前台/后台两种执行流程、审查目标（working-tree / branch）的自动判定规则，以及从 slash 命令到 Codex app-server 的底层调用链，能够在自己项目中稳定地编排"提交前 Codex 审查"这一环节。

命令定位：review-only 的共享内置评审器

/codex:review的定义位于 plugins/codex/commands/review.md，其 YAML frontmatter 明确声明了三条关键约束：

• disable-model-invocation: true：禁止模型直接以对话方式调用，必须走 slash 命令路由；
• allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion：执行期间只允许只读工具（Read/Glob/Grep）、node 与 git 相关 Bash，以及一次性的询问工具；
• argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]'：向用户暴露的合法参数形态。

该命令的核心定位是review-only：文档明确要求"不要修复问题、不要打补丁、不要暗示你即将做出改动"，你的唯一职责是运行审查并把 Codex 的输出逐字（verbatim）返回给用户。这意味着/codex:review是一条安全的、可随时放入 CI 前或提交前流程的只读命令，绝不会触碰工作区。

它与/codex:adversarial-review（见 adversarial-review.md）形成互补：

参数全集：--wait / --background / --base / --scope 的语义

命令的完整语法为：

/codex:review [--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]

各参数的真实行为，从 codex-companion.mjs 的handleReviewCommand（约 L712）可看到严格对应：--base、--scope、--model、--cwd被解析为值参数（value options），--background、--wait、--json被解析为布尔参数，位置参数（positionals）被合并为focusText——但原生 review 不接受任何 focus 文本。

底层参数解析由 args.mjs 的parseArgs完成：支持--key=value内联值与短选项别名（如-m映射到--model）、--透传、引号包裹与反斜杠转义（splitRawArgumentString）。例如--scope=working-tree与--scope working-tree等价。

一个关键差异：--wait/--background由谁处理

文档特别强调：不要自己剥离--wait或--background，原始参数必须原样传给配套脚本。真正让后台运行"脱离"的，是 Claude Code 的Bash(..., run_in_background: true)调用，而不是脚本本身——脚本只是负责解析并执行审查。这也解释了为什么命令文档要求"不要额外添加审查指令、不要改写用户意图"。

执行模式规则：前台、后台，还是先问一次

命令文档定义了严格的分流逻辑（review.md 的 Execution mode rules）：

1. 原始参数包含--wait→不询问，前台运行；
2. 原始参数包含--background→不询问，以 Claude 后台任务运行；
3. 其他情况 →先估计审查规模再决定询问。

审查规模的估计方法

规模估计完全基于只读 git 命令，对应文档给出的三条指令：

• working-tree 审查：先跑git status --short --untracked-files=all，再同时检查git diff --shortstat --cached与git diff --shortstat；
• base-branch 审查：使用git diff --shortstat <base>...HEAD；
• 未跟踪文件（untracked）视为可审查的工作，即使git diff --shortstat为空也不能漏掉；
• 只有相关工作区状态为空、或显式分支差异为空时，才能下结论"没有可审查内容"；
• 仅当审查明显很小（总计约 1-2 个文件、且没有目录级大改动的迹象）时才推荐等待，其余情况一律推荐后台；拿不准时，宁可运行审查也不要宣布"无内容可审"。

在源码侧，git.mjs 的getWorkingTreeState（约 L121）用git diff --cached --name-only、git diff --name-only、git ls-files --others --exclude-standard分别收集暂存、未暂存、未跟踪文件，三组并集非空即判定isDirty——与文档"把 untracked 视为可审查工作"的规则完全吻合。

恰好询问一次（AskUserQuestion）

在需要询问的情况下，使用AskUserQuestion恰好一次，提供两个选项，且推荐项在前、标签后缀(Recommended)：

• Wait for results
• Run in background

这是命令文档对执行代理（Claude Code 模型）的硬性指令，确保交互路径可预期：要么阻塞等结果，要么转后台，不存在第三种静默行为。

审查目标解析：auto 模式下如何自动选择

无论是否显式传--scope，最终都会落到resolveReviewTarget（git.mjs 约 L134）的判定逻辑。结合命令文档与源码，目标解析规则如下：

1. 显式传--base <ref>→ 直接进入branch模式，标签为branch diff against <baseRef>；
2. 显式传--scope working-tree→ 进入working-tree模式；
3. 显式传--scope branch→ 自动探测默认分支（detectDefaultBranch依次尝试refs/remotes/origin/HEAD、main、master、trunk），再进入branch模式；
4. --scope为非法值→ 抛错提示使用auto/working-tree/branch或--base <ref>；
5. 默认auto：工作区有改动（staged/unstaged/untracked 任一非空）→working-tree；否则自动探测默认分支 →branch。

分支审查的差异计算在buildBranchComparison（约 L68）：先git merge-base HEAD <baseRef>求合并基点，用<mergeBase>..HEAD作为提交区间与 diff 区间，用<baseRef>...HEAD作为审查标签区间。也就是说，分支审查只针对你分支相对基准分支引入的提交，不包含基准分支上别人的改动。

需要特别留意的是，原生 review 的目标被映射为两类（buildNativeReviewTarget，codex-companion.mjs 约 L259）：

• working-tree模式 →{ type: "uncommittedChanges" }
• branch模式 →{ type: "baseBranch", branch: <baseRef> }

其余目标会被validateNativeReviewRequest拒绝并提示改用/codex:adversarial-review。这与命令文档的声明一致：/codex:review是 native-review only，不支持 staged-only 审查、unstaged-only 审查或额外 focus 文本——需要自定义审查指令或更强的对抗性框架时，应切换到/codex:adversarial-review。

前台流程：一条命令原样返回 stdout

前台执行的完整命令（来自 review.md 的 Foreground flow）：

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review "$ARGUMENTS"

其中CLAUDE_PLUGIN_ROOT由 Claude Code 注入，指向插件根目录；$ARGUMENTS是用户传给 slash 命令的原始参数字符串。命令文档对输出处理有三条铁律：

• 返回命令 stdout，逐字原样（as-is）；
• 前后不做改写、总结或评论；
• 不修复输出中提到的任何问题。

从源码看，handleReview（codex-companion.mjs 约 L755）会创建一条jobClass: "review"的作业记录（createCompanionJob，前缀review），再经runForegroundCommand执行executeReviewRun，最终把rendered结果直接写到 stdout。渲染层 render.mjs 的renderNativeReviewResult（约 L288）只是把 Codex 的审查文本封装成 Markdown 标题（# Codex Review）与Target:行，随后原样嵌入 stdout 正文，并附上 reasoning summary 与 stderr——这保证了"逐字返回 Codex 输出"这一约束在执行层被严格落地。

后台流程：run_in_background 与状态轮询

后台执行在命令文档中给出的是 TypeScript 形态的 Bash 调用：

Bash({ command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" review "$ARGUMENTS"`, description: "Codex review", run_in_background: true })

配套行为约束同样明确：

• 本回合不得调用BashOutput，也不得等待完成；
• 启动后立即告知用户："Codex review started in the background. Check /codex:status for progress."

这正好与配套的状态命令闭环：status.md 让/codex:status [job-id]展示当前仓库运行中/最近的 Codex 作业（无 job-id 时渲染为紧凑 Markdown 表格，含 job ID、kind、status、phase、耗时、summary 与后续命令）；作业完成后可用 result.md 的/codex:result [job-id]查看存储的完整输出；不再需要时可参考 cancel.md 的/codex:cancel [job-id]中断运行中的任务。

一个典型的一键三连：

/codex:review --background /codex:status /codex:result

底层调用链：从 slash 命令到 Codex app-server 的 review/start

理解这条命令的可靠性，需要看它最终如何驱动 Codex。executeReviewRun（codex-companion.mjs 约 L358）的流程为：

1. ensureCodexAvailable(cwd)：检查全局codex二进制存在且支持app-server高级运行时（codex.mjs 的getCodexAvailability约 L886）；
2. ensureGitRepository(cwd)：git rev-parse --show-toplevel确认当前目录在 Git 仓库内；
3. resolveReviewTarget：按上文规则解析目标；
4. validateNativeReviewRequest(target, focusText)：拒绝任何 focus 文本、拒绝非原生目标；
5. runAppServerReview(cwd, { target, model, onProgress })：真正发起审查。

runAppServerReview（codex.mjs 约 L1002）是核心：它通过withAppServer建立与 Codex app-server 的客户端连接，然后：

• thread/start：以sandbox: "read-only"、ephemeral: true启动一个临时线程（model 可选传入，可被覆盖）；
• review/start：向该线程发起内置评审请求，delivery: "inline"（默认），target即前面解析出的uncommittedChanges或baseBranch目标；
• captureTurn：通过 app-server 通知流捕获整个 turn——enteredReviewMode（"Reviewer started"）、exitedReviewMode（捕获item.review作为reviewText）、reasoning（汇总推理摘要）等事件都会被记录；
• 返回reviewText、reasoningSummary、threadId、turnId、status等，交由上层渲染。

关键设计点是只读双保险：命令层禁止修改（review-only 约束），app-server 线程层也用sandbox: "read-only"兜底，审查过程不可能写回工作区。同时withAppServer还实现了 broker 降级重连：当共享会话（broker）繁忙（BROKER_BUSY_RPC_CODE）或不可达时，自动回退到直接启动一个 app-server 实例，保证审查不因共享运行时忙碌而失败。

另外值得一提的是--model覆盖能力：handleReviewCommand支持--model（别名-m），并经由normalizeRequestedModel把spark映射为gpt-5.3-codex-spark。不传时，模型与推理力度完全由你的 Codex 配置决定（见下节）。

如何配置审查使用的模型与推理力度

/codex:review复用你本机 Codex CLI 的全部配置，不引入独立运行时。想调整默认模型或 reasoning effort，只需在项目根目录的.codex/config.toml（或用户级~/.codex/config.toml）中设置：

model = "gpt-5.4-mini" model_reasoning_effort = "high"

配置加载顺序为：用户级~/.codex/config.toml→ 项目级.codex/config.toml（仅在项目受信任时加载）。这样你在 Claude Code 里敲/codex:review时，Codex 会使用与命令行直接使用完全一致的模型与推理策略，审查质量与在 Codex TUI 中执行/review一致。

实战建议与边界条件

基于命令文档与源码实现，总结几条可直接套用的实战经验：

• 多文件改动优先--background：多文件审查耗时较长，后台运行后配合/codex:status轮询、/codex:result取最终输出是最省心的组合；
• 提交前对比基准：/codex:review --base main只审查你分支相对main引入的提交，适合 PR 前的定向检查；
• 有未跟踪文件时别急：新文件会被计入可审查工作（ls-files --others会被收集），审查前记得确认这些确实是你要评审的内容；
• 需要引导时切换命令：想针对 auth、数据丢失、回滚、竞态等风险区域做定向挑战，或想给审查加 focus 文本，请改用/codex:adversarial-review；
• read-only 保证：命令层约束 +sandbox: "read-only"双保险，审查过程不会修改任何文件，可以放心纳入常规提交流程。

总结

/codex:review把 Codex 的原生评审器以一条 slash 命令的形式接入 Claude Code：参数层支持前台/后台/自动询问与--base/--scope目标控制，执行层严格保持 review-only 与 stdout 逐字返回，实现层则通过 app-server 的review/startRPC 以只读沙箱驱动 Codex 内置评审器。配合/codex:status、/codex:result、/codex:cancel，你可以把"提交前 Codex 审查"编排成完整、可中断、可回溯的开发闭环——而这一切都复用于你本机已有的 Codex 安装、登录态与配置。

• 人工智能
• AI 插件
• 代码智能体