让 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还是对一段外部代码的独立审计在技术上可以拆成四步读取变更diff 或完整文件对照经验与规则找出潜在问题逻辑漏洞、安全隐患、风格问题、边界条件、性能隐患按严重程度分级并给出修改建议输出结构化结论。注意这几步之间没有执行-验证-再执行的循环。评审的人不需要改代码不需要跑测试不需要看到修改后的效果再回头调整意见。它更像是一次阅读理解经验输出而不是工程实施。这正是 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_outputTrue, textTrue ) 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拼装成 promptrun_review.py 负责调用 Headless CLImerge_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 分钟人工轮次等待45 秒输出稳定性同一问题前后描述不一致同一输入几乎相同输出发现的 critical 数5 个4 个额外发现人类漏掉3 个6 个是否适合流水线不适合需人工值守天然适合可自动触发交互模式在问题深度上略强一点点——它可以在追问过程中深入某个可疑点挖出 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 究竟能有多可靠——然后在信任它的基础之上再去尝试边界稍微宽一点的场景。