Codex AI 工程化落地：把编程智能体嵌入代码审查流水线

Codex 的定位常被简化为“代码生成工具”，但从工程视角看，这种理解会掩盖它真正的价值。Codex CLI 的核心是一套智能体循环：接收用户输入，调用模型推理，模型可能返回工具调用请求（读文件、运行命令、修改代码），智能体执行后将结果追加回上下文，再次提交模型，循环往复，直到模型生成面向用户的最终消息。这意味着 Codex 的输出不只是“一段建议代码”，而可以是对工作区中文件的真实修改、命令的真实执行，以及结构化结果的真实产出。本文从这一机制出发，给出一个可运行的 Codex 代码审查智能体，并讨论工程落地中容易被忽视的边界与约束。

一、先划边界：Codex 适合做什么，不适合做什么

Codex 不是“更大的 Copilot”。Copilot 工作在输入光标处，提供实时补全；Codex 工作在任务边界，自主读取仓库、修改文件、执行测试、提交 PR。这决定了它更适合三类场景：可被清晰描述的重复性工程任务（重构、修复失败测试、生成文档）、需要跨多文件推理的工作（迁移、接口对齐）、以及可以定义“完成标准”的审查与验证任务。

但它不适合替代人的判断。Codex 在沙箱中运行，默认模式限制文件写入范围并关闭网络访问。这种限制不是缺陷，而是工程上的必要约束——一个能任意写文件和访问网络的智能体，在没有门禁的情况下是不可控的。下面的代码审查智能体同样遵循这一原则：审查阶段使用只读沙箱，输出结构化结果，由外部系统决定是否采纳。

二、可运行骨架：用 Codex SDK 构建代码审查智能体

安装 openai-codex-sdk 后，可以通过 Python 以线程方式驱动 Codex。下面的 review_agent.py 完成一次完整的代码审查：读取 diff，在只读沙箱中让 Codex 审查，输出符合预定义 schema 的 JSON 结果。

# review_agent.py
import json, subprocess, pathlib
from openai_codex_sdk import Codex

SCHEMA = {
    "type": "object",
    "properties": {
        "verdict": {"type": "string", "enum": ["correct", "incorrect"]},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "findings": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "severity": {"type": "string", "enum": ["high", "medium", "low"]},
                    "file": {"type": "string"},
                    "line_start": {"type": "integer"},
                    "line_end": {"type": "integer"},
                    "message": {"type": "string"},
                },
                "required": ["severity", "file", "line_start", "line_end", "message"],
            },
        },
    },
    "required": ["verdict", "confidence", "findings"],
}

def get_diff(base: str = "main") -> str:
    return subprocess.check_output(
        ["git", "diff", f"{base}...HEAD"], text=True
    )

def review(diff: str) -> dict:
    prompt = f"""你是代码审查者。只标记由本次变更引入的、影响正确性、性能、安全或可维护性的问题。
每条问题给出文件、行号和一句直接说明。严重问题优先，不要 nit 级别评论。
输出必须严格匹配给定的 JSON schema。

diff：
{diff[:24000]}
"""
    with Codex() as codex:
        thread = codex.thread_start(sandbox="read_only")
        turn = thread.run(prompt, output_schema=SCHEMA)
        return turn.structured_output

if __name__ == "__main__":
    result = review(get_diff())
    pathlib.Path("review.json").write_text(
        json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
    )
    print(f"verdict={result['verdict']} findings={len(result['findings'])}")

这段代码的三个设计决策值得展开。第一，sandbox="read_only"：审查者不需要写入权限。Codex SDK 支持在每次 turn 上覆盖沙箱预设，只读模式是审查任务最自然的边界。第二，output_schema 强制结构化输出：自由文本的审查意见无法被 CI 系统消费，而结构化 JSON 可以直接映射为 PR 行内评论或质量门禁的输入。Codex 的 GitHub Action 正是通过 output-schema-file 参数接收 schema，再把 JSON 结果交给后续步骤创建评论。第三，diff 截断：diff[:24000] 是一个朴素的长度保护，实际工程中应配合更精细的上下文预算策略（见第四节）。

三、从脚本到流水线：CI 集成的最小步骤

上面的脚本可以在本地运行，但 Codex 工程化的真正价值出现在 CI 中。GitHub Actions 场景下，核心步骤只有四步：检出代码、安装 Codex CLI、以 exec 模式运行审查、解析 JSON 并反馈。

codex exec 是 CLI 的非交互模式，天然适合脚本和流水线：提示词作为参数传入，执行完毕即退出，结果可以通过 --json 输出为机器可解析的格式。一个最小的工作流片段如下：

# .github/workflows/codex-review.yml（片段）
- name: Run Codex review
  run: |
    codex exec \
      --sandbox read-only \
      --output-schema codex-review-schema.json \
      --json \
      "review diff against main" > codex-review.json
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

注意这里同样使用了只读沙箱。CI 环境中的智能体不应该拥有写入仓库的权限——审查和修复是两件事，审查者只读，修复者另起一个受控的写入任务。OpenAI 的 Codex SDK 示例也明确建议：将审查与发布反馈的权限分离，只读沙箱本身并不保护密钥，凭据和权限布局需要单独设计。这是很多“让 Codex 在 CI 里自动修 PR”的方案容易踩进去的坑：把审查、修改、提交合并到一个权限过大的 job 里，一旦模型行为偏离预期，后果无法收敛。

四、被低估的工程问题：上下文预算是审查质量的第一约束

代码审查的质量不取决于模型“有多聪明”，而取决于它在这一轮对话中看到了什么。Codex 每次启动会扫描工作区，如果没有引导文件，光读文件就可能消耗数十万 token，真正留给推理的预算被严重压缩。AGENTS.md 是解决这一问题的第一层工具：用几百 token 的精准说明，替代 Codex 自行探索项目结构消耗的几万 token。

一个用于代码审查场景的 AGENTS.md 不需要面面俱到，但至少应包含三件事：

<!-- AGENTS.md -->
## 审查范围
- 只审查 `src/` 和 `packages/` 下的变更
- 忽略 `dist/`、`node_modules/`、`*.lock`
- 不要读取 `migrations/`，迁移文件不在审查范围内

## 审查标准
- 正确性优先于风格
- 安全相关问题标记为 high
- 性能问题仅在可量化时标记

## 输出约定
- 行号必须与 diff 中的位置一致
- 每条 finding 附带一句可直接作为 PR 评论的说明

更深一层的控制是 .codexignore：从文件扫描阶段直接排除不应进入上下文的内容，而不是让模型“先读了再忽略”。OpenAI 内部一个 7 人团队在 5 个月内用 Codex 完成 100 万行代码、合并 1500 个 PR 的实践也指向同一结论：上下文管理是工程纪律，不是模型参数。审查智能体的失败模式中，很大一部分不是“模型没发现 bug”，而是“模型在无关文件上消耗了推理预算，然后在关键 diff 上给出了浅层结论”。

五、工程视角下的三条结论

第一，沙箱模式是架构决策，不是可选项。 审查用只读，修复用工作区写入，部署用完全隔离的运行时。把不同风险等级的动作放进同一个沙箱边界，是自动化流水线中最危险的设计捷径。

第二，结构化输出是“可集成”的前提。 自然语言的审查意见可以给人看，但不能给 CI 看。Codex 的 output_schema 和 CLI 的 --output-schema 把智能体的输出约束为可验证的数据契约，这才使得“审查结果自动触发门禁或行内评论”成为可能。

第三，上下文治理的投入回报高于提示词调优。 一份写对的 AGENTS.md 加上合理的 .codexignore，对审查质量的影响远大于反复打磨审查提示词的措辞。Codex 的智能体循环每一轮都把完整的对话历史和工具输出带回模型，上下文的质量直接决定推理的质量。

Codex 在代码审查场景中的角色，本质上是一个受约束的推理执行器：它读取你允许它读取的东西，在你自己选择的沙箱边界内推理，输出你事先定义好结构的结果，然后退出。工程化的全部工作，就是把这个“约束”设计得足够精确——精确到它既能发现人容易漏掉的问题，又不会在失控时造成无法回滚的后果。