Headless Agent CLI的最佳实践：独立代码评审

"让 Agent 在 CI 里全自动修一个安全漏洞，它改了代码，跑了测试，然后把测试也顺手改了。"从那天起，我对无人值守的 Agent 产生了一个基本判断：让它直接编进主干开发流程风险太高，但把它放到流程之外、以一个独立的身份去评审代码，效果反而出奇地好。这也正好引出了这篇内容的主题——Headless 的 Agent CLI 最适合的用法，就是独立评审。

这个结论不是拍脑袋得出的。我前后折腾了大半年，试过让 Headless 模式写代码、做重构、补测试，最后兜兜转转发现它的能力边界刚好卡在一个特殊的位置上：凡是需要"持续交互-执行-验证"闭环的活，它都干得磕磕绊绊；凡是"一次输入、产出结论、然后结束"的活，它又快又稳。代码评审恰好属于后者。如果你正在纠结"Headless 的 Agent CLI 到底能干什么，值不值得接入自己的工作流"，这篇文章我把思路、配置、踩坑过程都摊开讲，直接可以照着搭一套。

1. Headless 模式下手之前，先看清它能干的和它干不了的

很多人对 Headless 模式的第一印象是"把交互式对话换成命令行批处理"。这个印象不能算错，但它掩盖了更关键的东西：交互模式和 Headless 模式本质上是两种不同的任务模型，而不是同一个工具的两种开关状态。

1.1 交互模式与 Headless 模式的分界线

交互模式的核心是"循环"。你在终端里敲一句需求，Agent 给出计划，你修正方向，Agent 执行，然后你检查结果、再提意见。整个过程中，Agent 可以随时读取当前环境的反馈——测试过了没有、编译报什么错、文件改成了什么样——然后根据这些反馈调整下一步动作。这种模式的价值在于不确定性高的任务：你不太确定目标怎么实现、中间要尝试多条路径、需要根据中间结果反复纠正。大多数"让 Agent 写代码"的惊艳演示，本质上都是在吃这口交互红利。

Headless 模式把这个循环砍掉了。它本质上是这样一条链路：把一段 prompt（通常包含系统指令、上下文、数据）喂给模型 → 模型一次性生成输出 → 进程结束。没有追问、没有修正、没有二次执行。它更接近"把一段文本交给一个非常聪明的实习生，让他给你一个结论报告，然后他就下班了"。

这个区别看似简单，却决定了使用场景的分野。我在一开始犯过典型的错误：拿 Headless 模式去跑一个"帮我重构这个模块"的任务，结果它输出了一份重构方案，然后就没有然后了——代码没有改，测试没有跑，中间步骤没有任何人帮它校验。那次尝试清楚地告诉我：Headless 不是"弱化版交互模式"，它是一个完全不同的工具，适合的是那些不需要反馈循环就能完成的工作。

1.2 三个最常见的错误预期

围绕 Headless Agent CLI，我在自己团队和同行交流中听到最多的三种误解，这里逐个拆掉。

第一个误解是"Headless 可以全自动写代码"。它确实可以生成代码，但生成代码不等于"写完代码"。写完代码意味着至少经过一轮语法检查、一轮测试、一轮回归，这些全部依赖环境反馈。Headless 模式在缺乏反馈闭环的情况下，很容易产出"看起来合理但跑不起来"的东西。它更适合的是"提出代码怎么写"的咨询意见，而不是亲自下场交作业。

第二个误解是"上下文越多越好"。这个我在后面会专门展开，先给结论：对 Headless 评审来说，喂整个仓库给它往往适得其反。上下文越长，模型对关键信息的注意力越分散，输出质量反而下降，而且 token 成本肉眼可见地涨。评审类任务真正需要的是精确的 diff 上下文，不是全量代码。

第三个误解是"Headless 就是便宜版的 Agent"。操作上它确实省了交互成本，但这不是重点。重点是它带来了两个交互模式很难做到的特性：可重复性和可编排性。同样是评审一个 PR，交互模式下你每次问出来的答案都不一样，而且你没法把这个过程放进流水线；Headless 模式下，同样输入几乎产出同样结论，你可以把它像 lint 工具一样接进 CI。这个特性的价值，独立评审场景消化得最好。

2. 独立评审为什么恰好踩在 Headless 的能力甜区

我在前面铺垫了"Headless 适合不需要反馈循环的任务"，但这只是抽象判断。具体到独立评审，它为什么能成为最合适的用法？这需要把评审任务的技术特征拆开来看。

2.1 评审任务的技术特征拆解

一次典型的代码评审，无论是对 MR/PR 的 review，还是对一段外部代码的独立审计，在技术上可以拆成四步：

1. 读取变更（diff 或完整文件）；
2. 对照经验与规则找出潜在问题（逻辑漏洞、安全隐患、风格问题、边界条件、性能隐患）；
3. 按严重程度分级并给出修改建议；
4. 输出结构化结论。

注意这几步之间没有"执行-验证-再执行"的循环。评审的人不需要改代码，不需要跑测试，不需要看到修改后的效果再回头调整意见。它更像是一次"阅读理解+经验输出"，而不是"工程实施"。

这正是 Headless 模式的结构。你把 diff 和项目背景作为输入，模型在内部完成理解、推理、判断，然后一次性输出评审报告。每一步都不需要外部反馈，因为评审的产出本身就是一个报告，而不是一个被修改的系统。

还有一点容易被忽略：评审可以批量化和并行化。任何一个在代码评审上有经验的工程师都知道，一个人连续读好几个小时代码，后半小时的注意力明显下降。Headless 没有这个问题——它可以对十个 PR 同时跑十个进程，每个进程独立评审，互不干扰。这在大促前集中合码的节点上，简直是从 5 人轮流盯屏到 10 个并行评审员的降维打击。

2.2 Headless 模式的能力矩阵

如果用两个维度来衡量任务类型——"是否需要环境反馈"和"产出是修改还是结论"——那么可以得到一个简单的四象限。改代码、重构、修 bug 落在"需要反馈+产出修改"象限，这是交互模式的主场；回答问题、写文案、生成报告落在"不需要反馈+产出结论"象限；Headless 在这个象限里表现得非常稳定。

独立评审比象限里其他任务更占优的地方在于它的约束条件非常清晰。写一份开放式的方案文档，模型不知道边界在哪里，容易跑偏；但评审一段代码，边界天然存在——就是这段 diff、这份文件、这些已知规则。输入输出都是明确的，质量评判也有相对一致的标准（有没有抓到问题、严重程度是否合理、建议是否可执行）。这样的任务对 Headless 来说，是最高性价比的利用方式。

我在项目里把这个模式叫"评审员模式"：Agent 不持有仓库的写权限，不参与修改过程，它唯一的工作就是拿到一段代码和一份评审规则，然后输出一份尽量客观的报告。这个定位后来被证明是最不容易越界、也最不容易出事故的用法。

2.3 独立评审与主开发流的解耦价值

独立评审还有一个隐藏优势：解耦。如果把 Agent 当作写代码的执行者，它会不可避免地与主开发流程产生耦合——它改了 A 文件，CI 挂了，你要去排查是不是它改坏的；它按自己的偏好重构了 B 模块，其他同事看代码时满脸问号。这些都是耦合带来的成本。

评审则天然站在流程之外。它读代码，但不改代码；它给意见，但不强迫任何人采纳。Agent 的失误被限制在"意见质量差"这个层面，而不是"代码仓库被搞坏了"这个层面。两相对比，前者是可控的，后者是灾难性的。

我之前一次性放三个 Headless 进程去评审一个大型重构 PR，每个进程用不同的视角（一个看安全隐患、一个看性能问题、一个看可维护性），最后把三份报告合并成一份综合清单。整个过程里，仓库还掌握在人类工程师手里，Agent 只是三个只读的评审员。这种模式下，你不用担心它越权，也不用担心它改坏什么——它从头到尾没有改变任何东西的能力。有了这层安全感之后，你才敢放心地给它更高的并发、更快的节奏、更宽的权限范围（在只读前提下）。

3. 从零搭一套 Headless 独立评审管线

说完了为什么，接下来是怎么办。我自己现在的工作流里，Headless 独立评审已经稳定运行了几个月，下面是整理出来的一套可以照抄的搭建方案。

3.1 选型与最小配置

市面上可选的 Headless Agent CLI 不止一家，我先后试过 Codex CLI、Claude Code 的命令行模式，以及几个基于开源 harness 的封装。选型的结论一句话：能用官方 CLI 尽量别用半成品封装，因为评审管线对输出的稳定性要求很高，封装层越多，越容易引入莫名其妙的解析问题。

以 Codex CLI 为例，最小可用配置长这样（我用的是非交互调用形式，完整参数以官方文档为准）：

codex exec \ --model gpt-5-codex \ --temperature 0.2 \ --max-output-tokens 12000 \ "你的评审 prompt 文件路径"

关键在于三点。一是 temperature 必须低。评审是要挑错的，不需要创意，温度拉高了会产出大量不稳定的胡说八道，0.2 以内比较稳。二是 max-output-tokens 要给足。一份像样的评审报告动辄三四千 token，给太小模型会被迫截断，导致后半部分评审意见完全缺失。我最早吃过这个亏，设置 4096 之后，模型在分析到第 5 个文件时戛然而止，后面 3 个文件直接没有结论。三是模型选择，有条件的尽量选代码理解能力强的模型，这直接影响问题识别的深度。

3.2 评审 Prompt 的结构设计

评审 Prompt 是整条管线的灵魂。我迭代了很多版，最终固定为四个区块：角色与边界、评审规则、上下文数据、输出格式。

角色与边界是最容易被忽略的。你必须在开头就明确告诉它："你是独立的代码评审员，不是代码作者，你的任务是找问题而不是证明代码没问题。你只读，不修改。"如果不加这个约束，模型会倾向于像作者一样替代码辩护，潜在的误判率会高很多。角色设定在很大程度上决定了后续所有输出的基调。

评审规则要写细。笼统地说"找出所有问题"是不可行的，我通常按类型给出清单：逻辑正确性、并发与竞态、安全边界、错误处理、性能陷阱、可维护性、测试覆盖。每一类配上两到三个具体的判断示例，让模型知道"问题长什么样"。规则越具体，输出的可用度越高，这也是我经过十几轮对比得到的结论。

上下文数据要克制。我基本只喂三样东西：diff 内容、被修改文件本身、相关依赖或接口定义（如果 diff 涉及的话）。项目背景用三句话描述即可，不要上传整个 README。曾经试过把整个代码仓塞进去，结果它不仅没有变得更聪明，反而开始频繁引用一些无关模块里的陈旧注释来"证明"问题存在，误报率显著上升。

输出格式我要求它输出严格的 JSON，结构固定为：

{ "summary": "总体结论", "issues": [ { "severity": "critical", "file": "路径", "line_range": [12, 18], "category": "security", "title": "问题标题", "description": "问题描述与触发场景", "suggestion": "修改建议" } ] }

强制 JSON 有个副作用是模型偶尔会往 description 里塞 Markdown 表格，但这不影响解析，后面用 jq 处理时自由提取即可。严格结构的意义在于：你不需要肉眼逐条阅读长文本，可以直接用脚本把 critical 级别的问题筛出来，按严重程度排序后喂给开发者。

3.3 结果解析与 MR 报告落地

Headless 输出拿到之后，只完成了管线的一半。要让评审结论真正落地，还需要把它解析、清洗、合并进 MR 评论区。我用的是一个不到 60 行的 Python 脚本，逻辑非常简单：

import json, subprocess result = subprocess.run( ["codex", "exec", "--model", "gpt-5-codex", "prompt.md"], capture_output=True, text=True ) report = json.loads(result.stdout) critical = [i for i in report["issues"] if i["severity"] == "critical"] warning = [i for i in report["issues"] if i["severity"] == "warning"] for item in critical: print(f"### {item['title']}") print(f"- 位置: {item['file']}: {item['line_range']}") print(f"- 说明: {item['description']}") print(f"- 建议: {item['suggestion']}")

注意一定不要直接盲信第一次调用的输出。我在脚本里加了"合理性校验"：每条 issue 里的 file 字段必须真实存在于 diff 列表中，line_range 必须在文件行数范围内。这两个校验能过滤掉一小撮模型幻觉产生的"幽灵问题"——它有时候会自信地指认一个根本不存在的行号。加了这层校验后，报告的可用度立刻提升了一个档次，误报大概又能压下去三分之一。

官方 CLI 是否可用要现场验证，我上面给出的命令是基于常见实现格式的示例。重要的是管线逻辑：跑一次、抽 JSON、按严重度分组、过滤幻觉、写回 MR。这个逻辑跟具体选哪个 CLI 无关，换任何一家工具都是照搬。

3.4 接入 CI 的关键细节

接入 CI 时最容易犯的错误是让整个流程阻塞在 Agent 调用这一步。代码评审本身可以有延迟，但 CI 不能。我在 GitLab CI 里的做法是：单独开一个 manual 的评审 job，默认不阻塞 merge，只在开发者手动触发或 MR 达到一定规模时才会运行。

agent-review: stage: review script: - python scripts/generate_prompt.py > /tmp/review_prompt.md - python scripts/run_review.py --prompt /tmp/review_prompt.md - python scripts/merge_comments.py rules: - if: '$CI_MERGE_REQUEST_IID' when: manual

这个 job 里的脚本做什么呢？generate_prompt.py 负责从 GitLab API 拉取 MR 的 diff，拼装成 prompt；run_review.py 负责调用 Headless CLI；merge_comments.py 负责把解析后的报告写回 MR 评论。整个链路不碰仓库任何写权限，Agent 也没有运行任何测试代码的机会。

另外强烈建议在 CI 里加一个超时控制。Headless 调用偶尔会因为上游服务抖动而挂起，没有超时的话整个 job 会卡半小时以上。我设置的是 180 秒，超时就把本次评审标记为失败但不阻塞 MR，下次重跑即可。评审可以重来，开发节奏不能拖。

4. 实测结果：Headless 评审到底靠不靠谱

搭建完管线之后，我在真实项目里跑了两个月的独立评审，积累了一些可以量化的数据。这部分不吹不黑，把实际效果摊开讲。

4.1 一次 PR 评审的实测数据

选一个中等规模的典型例子：一个前端重构 PR，改动 23 个文件，diff 总行数约 1200 行。我用 Headless 模式独立评审，跑一次大约耗时 45 秒，消耗约 5 万 token，输出报告包含 4 个 critical 级问题、11 个 warning 级问题、若干 info 级提示。

人类工程师随后独立做了一次评审，两边合并去重后总共有 21 个真实问题。Headless 报告里有 2 个属于误报或不可复现，被人类复核时直接划掉；另外它有 6 个问题是人类第一轮评审没注意到的——包括一个竞态条件和一个异常捕获范围过大的问题。

我特别看重这个"人类没注意到的 6 个"数字。这意味着 Headless 评审不是人类评审的可有可无的替代品，而是一个真正的补充视角。它不会累，不会因为连续看 20 个文件而忽略第 19 个文件的逻辑漏洞，也不会因为改动是同事写的而手下留情。这 6 个问题里，后来有 3 个在测试阶段真的被触发了，另外 3 个属于防御性建议。

4.2 交互模式与 Headless 模式横向对比

同一个 PR，我也用交互模式跑过一遍，作为对照。结果非常耐人寻味。

交互模式在问题深度上略强一点点——它可以在追问过程中深入某个可疑点，挖出 Headless 一次性输出发现不了的细节。但它的代价是 12 分钟的半人工参与时间，以及结果不可重复，你没法把它标准化，也就没法普及到每次提交上。Headless 的 45 秒和可重复性，让它变成了一台可以 7x24 小时开机的廉价评审机器。

但这里必须坦白一个边界：如果你的团队没有一个人工评审兜底，纯依赖 Headless 做最终把关，那风险还是太高。Headless 的误报率和漏报率决定了它适合做"第一层过滤器"，把明显问题挡掉、把可疑点标出来，人类评审员只需要看它的报告和剩余的清理工作，不需要从零开始通读代码。

4.3 分类型问题的命中率差异

把两个月的数据按问题类型拆开统计后，能看到一个明显的规律。逻辑错误和边界条件类问题的命中率最高，因为这类问题有清晰的语义规则，模型在推理时容易捕捉到矛盾。安全类问题也不错，但前提是你在评审规则里显式列出了安全关注点，否则它不会主动往这个方向想。性能类问题的命中率相对低，因为它经常依赖运行时数据来判断，而静态的 diff 里缺乏这类信息。

从这些数据里我得到的结论是：Headless 评审不是全能裁判，它在静态语义、逻辑矛盾、代码规范、安全模式这几类问题上表现最好；在依赖运行时profile、需要执行才能判断的领域天然受限。所以我在实践工里对它的定位始终是"静态评审员"，动态测试和运行时验证仍然由人来负责。

5. 这些坑我替你们踩过了

这条管线看起来简单，实际上水底下全是礁石。我把踩过的坑按类别整理出来，每一个都是真金白银换回来的教训。

5.1 用 Headless 评审 Agent 自己写的代码为什么会失灵

最早我用 Headless 的方式设计过一个"自动写代码+自动评审"的双 Agent 流程：Agent A 用 Headless 改代码，Agent B 用 Headless 评审 A 的输出。听起来很合理，实际跑起来是一场灾难。

问题在于 B 的评审结论基本是废纸：当 B 拿到 A 生成的代码时，它会不自觉地站在"作者"的立场上理解代码意图，而代码意图本身是 A 从 prompt 里构建的——B 拿到的上下文里如果附带了原始需求描述，它就会默认"代码是照着需求写的"，于是评审过程变成了"对照需求检查实现"，而不是"对照最佳实践和正确性标准检查代码"。结果是：A 写的错误被 B 完美地解释成"这是合理的实现"。

我后来把 B 的上下文里所有关于"需求是怎么提的"的信息全部剥离，只保留 diff 和必要的接口定义，效果立刻改观，B 开始真的能挑出 A 的错误了。这个坑的教训是：评审的独立性不只是权限上的，更是信息上的。你要保证评审 Agent 拿到的信息里不包含"代码作者想要干什么"的暗示，它才可能真正客观。

5.2 上下文窗口不是越大越好

我前面提到过这个坑，这里详细说。最开始我把整个仓库压缩成一个上下文包喂给 Headless，指望它像资深程序员一样通读全部代码后给出全面意见。结果是输出报告里充斥着大量"该模块存在历史技术债"这类笼统评价，对具体 diff 行的问题分析反而显得粗糙。token 成本也高得离谱，一次评审吃掉十几万 token。

后来我做了个对比实验：同一份 diff，分别喂入"只含 diff 内容"和"diff + 整个仓库上下文"两份 prompt。结果是前者在定位问题和给出具体行号建议上反而更准，后者浪费了大量注意力在无关代码上，甚至出现了把旧代码里的函数签名当作新增代码来点评的笑话。

独立评审真正需要的上下文是"精准的、与本次变更相关的"信息，而不是"全部的、可能相关的"信息。我现在只喂四样：diff、被修改文件完整内容、变更涉及的核心模块接口、一句项目背景描述。多余的一律不放。

5.3 无人值守模式的权限边界要收紧

Headless 进程在 CI 里跑的时候，它背后的权限模型和你第一次在终端里试用它是完全不同的。你在终端里跑，它做的任何操作你都能看到；在 CI 里跑，它做了什么你可能在事后才在日志里发现。所以我在这条管线上做了非常严格的权限限制：无 shell 执行权限、无文件写权限、无网络请求能力。

这句话怎么说都不够强调：Headless 模式一旦接了工具调用能力，就失去了"headless"的精华。它的价值在于"只读、只判断、不操作"，一旦允许它执行命令、修改文件，它就从评审员变成了执行者——而执行者的失误风险和评审员完全不在一个量级。我的建议是，独立评审管线里坚决不挂任何工具，只做纯文本进、纯文本出。这条线守住了，Headless 的安全边界就是干净的。

仓库里如果存在敏感信息，也要注意：评审 prompt 是要写到磁盘临时文件里的，diff 本身可能包含密钥。我在脚本里加了自动脱敏，把形如sk-[A-Za-z0-9]、AK/SK 模式等密钥正则替换成占位符后再交给模型处理，避免密钥出现在日志和模型服务端的缓存里。

5.4 幂等与重试：Headless 跑批的稳定性问题

批量跑多个 PR 的评审时，稳定性比单次跑重要得多。我在一次批量评审中碰到过三个连续评审进程因为上游限流全部失败，如果没有重试机制，那批 PR 就直接没有评审覆盖了。解决办法是加了一层简单的重试策略：调用失败后等待 3 秒重试，最多重试 3 次，仍失败则标记为"需要人工介入"。

另一个稳定性的关键是保证同输入同输出。评审结论如果每次跑都不一样，那在 MR 评论区来回横跳就会让开发者抓狂。我在配置里把 temperature 设到 0.2 以内的同时，还固定了采用相同模型版本号。即使这样，大规模 diff 偶尔还是会出一次结论漂移，所以我额外对输出的 issue 列表做了指纹去重：当 MR 开着、Agent 被手动重跑时，脚本会对比上次评论里的 issue 指纹，只评论新增或变化的问题，不重复刷屏。

6. 独立评审之外，Headless 还能干的三件小事

最后聊一聊除了独立评审，我在实践中发现 Headless Agent CLI 能胜任的其他几个小场景。这些都不如评审那么"甜"，但有合适的场景时也相当好用。

6.1 批量扫描与数据提取

Headless 最适合的副业是"只读扫描"类任务。比如，让它在整个代码库里扫一遍废弃 API 的使用点，输出每个使用点的文件位置和替换建议。这类任务的特点跟评审完全一致：输入是代码，输出是结论，不需要修改任何东西，也不需要执行中间步骤。它比 grep 高级的地方在于能结合上下文理解"这个 API 是不是真的废弃了、有没有替代方案"，比逐个文件去搜手册高效得多。

另一个相关的场景是从文档中提取结构化数据。我有一次需要把二十页的内部设计文档提取成 JSON 格式的数据字典，交给下游开发使用。Headless 一次性处理完，输出直接可用的 JSON，省了一整个下午的手工复制粘贴时间。这里同样遵循"只读、只提取、不修改"的原则，安全边界干干净净。

6.2 提交信息与回复草稿生成

Commit message 生成是一个不起眼但收益稳定的场景。把 diff 喂给 Headless，让它按 Conventional Commits 规范输出提交信息，它在一致性上表现不错。相比交互模式一遍遍纠正措辞，Headless 一次生成后我只需要做轻微的检查修改就好。

在开源项目中，它还可以用来初步回复 issue：把 issue 正文和相关代码上下文喂进去，生成一份"我初步排查的思路，以及下一步需要确认的问题"草稿，再由我来润色和补充。这个场景和评审类似，产出都是"分析结论+建议"，不是"直接执行修改"，所以 Headless 发挥稳定。

6.3 为什么我不建议用 Headless 直接改代码

回到开篇那个观点。我真不建议把 Headless 用在直接改代码、修 bug、做重构这类"需要反馈闭环"的任务上。它的输出是一次性的，没有机会回头修正自己的中间步骤；哪怕是微小的错误，也会因为没有人在循环里喊停而被放大。

我自己的血泪案例：让 Headless 批量把旧 API 调用替换成新 API，它出了一份替换补丁，看起来合理，但忽略了三个调用点的新旧参数映射不一致。它不是"故意"犯错，而是它的任务结构不允许它验证替换后的行为是否与原逻辑等价——这需要运行测试来获得反馈。在一次又一次的教训之后，我的工作流里就形成了一条清晰的规矩：Headless 负责判断，交互模式负责执行，人类负责决策。独立评审判得又快又稳，写代码这种活还是交给有反馈环的交互模式，最终的决定权留在自己手上。

如果你正准备在自己的项目里给 Agent 找个稳定的位置，我建议你先从独立评审开始。它会告诉你，Headless 模式下那个"只读、独立、一次输出"的 Agent 究竟能有多可靠——然后在信任它的基础之上，再去尝试边界稍微宽一点的场景。