Headless 与 CI/CD（考点 3.6）· CCAF 备考

本页目录5

这个考点是什么

Headless 模式（也叫 print 模式）是 Claude Code 接入无人值守场景的入口：给交互式命令加一个 -p/--print，它就从「等你输入的 REPL」变成一个读 stdin、写 stdout、跑完自动退出、用退出码报告成败的普通命令行工具，能像 grep、jq 一样接进 CI 流水线、git hook、cron 任务或 npm script。

这条考点的第一层是「怎么正确地非交互执行」——-p 是唯一入口，搭配 --allowedTools/--permission-mode 提前把权限讲清楚，避免脚本卡在等待批权限上。

第二层是「怎么让流水线消费结果」。

默认纯文本适合人看，不适合脚本解析；--output-format json 给出含 result、session_id、total_cost_usd 的结构化对象，进一步配 --json-schema 能让指定字段落在 structured_output 里，由 Claude Code 对输出做校验，从根上替代「拿文本去写正则」的脆弱做法。

第三层是「审查类任务的两个进阶维度」——让审查跑在与写码无关的干净实例里，且报告范围收敛到本次 diff，对应官方 Code Review 功能：

每次审查是一支新的 agent fleet 并行分析、经验证步骤去重去误报后再产出结果；
配合按 push 触发的重跑机制与 REVIEW.md 里的「re-review convergence」规则，可以让同一个 PR 的多轮审查只在问题仍未修复或出现新问题时才继续发声，而不是把已修好或纯风格类的旧意见反复念叨。

GitHub 场景下还有 claude-code-action@v1 这条现成路径，底层同样构建在 Agent SDK 之上，claude_args 是把 CLI flag 透传进去的桥梁。

为什么考

这条考点的出题套路高度集中在「识别真实机制 vs 杜撰机制」：--headless、--ci、--non-interactive、CLAUDE_HEADLESS 环境变量都是常见的编造干扰项，唯一正确答案永远是 -p/--print。

第二类考法是「给定一个脆弱方案，选出更稳健的替代」——纯文本正则解析、要求模型精确复现某种文本格式，都不如 --output-format json + --json-schema 稳健，题目常把「格式漂移导致解析器反复崩」写成具体场景来测这层判断。

第三类围绕 claude-code-action v1 的具体事实（引用方式、@claude 触发、自动模式判断、claude_args 透传、底层是 Agent SDK、API key 必须走 GitHub Secrets）做多选核查题。

第四类是「fully automated / 无人值守」的边界判定——凡是选项里混入交互模式、手动运行、用户批准中的任意一个，该选项就不成立，唯一合规组合是 print mode + 可复用触发单元（slash command/skill）+ CI 或 cron 触发器。

核心辨析

1
-p/--print 是进入非交互模式的唯一标志，--headless、--ci、--non-interactive 这类名字直觉上很像的 flag 以及 CLAUDE_HEADLESS 环境变量在官方 CLI reference 里都不存在——题目里出现这几个词，基本可以直接判假。
2
结构化输出的稳健程度是分层的
纯文本配正则解析最脆弱（输出格式一变解析就崩）；要求 Claude「严格按某种文本格式回答」略好但仍是「生成不保证、解析靠约定」的两段式风险；--output-format json 配 --json-schema 才是官方给出的稳健方案——目标字段落在 structured_output 里，由 Claude Code 对结果做 schema 校验，而非指望模型每次都精确复现同一种纯文本排版。
3
claude-code-action@v1 与手写 claude -p 不是二选一竞争关系，而是场景分工：
- 前者内置 GitHub token 鉴权、PR/issue 上下文、行内评论工具、@claude 触发，并自动判断 interactive（tag）还是 automation 模式（v1 已移除旧版的 mode 输入）；
- 后者是通用管道方案，GitLab/Jenkins/git hook/npm script 等非 GitHub Actions 场景只能走这条路。
两者底层都基于 Agent SDK,claude_args 就是把 CLI flag 透传进 action 的接口，考题里常把这条透传关系单独设问。
4
「独立实例审查」与「增量只报新问题」是 Code Review 功能的两个互补面
官方文档明确每次审查是一支新的专项 agent 并行分析、经验证步骤过滤误报后去重排序；而「After every push」触发模式会在 PR 每次新提交时重新触发一次全新审查，并在问题被修复后自动 resolve 掉对应 thread。

但「只报新问题」不是默认免费获得的——需要在 REVIEW.md 里显式写出 re-review convergence 规则（如「首次审查后只报 Important，压制新的 Nit」），否则同一个 PR 反复小改也可能被反复念叨风格类意见。
5
判定「fully automated（全自动）」的关键是排查整条链路里是否嵌着人工环节
凡出现交互模式、手动运行、需要用户批准中的任意一项，都不满足「无人值守」；真正成立的组合是 print mode（非交互执行）+ 可复用的触发单元（slash command 等）+ CI/cron 触发器，三者缺一不可。
6
API key 的安全边界很明确
GitHub Actions 里必须通过 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} 引用仓库 secret，官方文档专门用 Warning 强调过「不要把 key 硬编码进 workflow 文件」——这是多选题里最容易被单独设成干扰项的一条。

反模式对照

常见做法

认为存在 --headless/--ci/--non-interactive 标志或 CLAUDE_HEADLESS 环境变量能让 Claude Code 进入非交互模式

正确做法

唯一入口是 -p/--print，跑完一轮自动打印结果并退出，不进入交互式 TUI

这几个名字都不在官方 CLI reference 里，题库常用它们做同义混淆型干扰项。

常见做法

拿到纯文本输出后写正则去抠 file/line/comment 这类结构化字段，或者只是要求 Claude「严格按某种文本格式回答」

正确做法

用 --output-format json 配 --json-schema 定义字段，结果落在 structured_output，直接用 jq 取字段

前者本质仍是「生成格式不保证 + 事后正则解析」两段式风险，输出一旦漂移解析就崩；后者由 Claude Code 对输出做 schema 校验，从根上消除格式漂移这一失败模式。

常见做法

以为 PR 每次 push 触发的 Code Review 重跑，会把之前提过的旧问题、风格类 nit 无差别地再念叨一遍

正确做法

在 REVIEW.md 里写明 re-review convergence 规则，并配合 After every push 模式的自动 resolve 机制，让重复审查只在问题仍未解决或出现新问题时才发声

官方文档明确 After every push 模式会在问题修复后自动 resolve 旧 thread，而没有约束的重复审查容易在一次小修改上反复纠结风格问题。

常见做法

判断「完全自动化 / 无人值守」时，只要出现了 print mode 或 cron 触发就直接判定成立，忽略流程里是否还嵌着人工批准或交互确认

正确做法

逐环核对整条链路——非交互执行 + 触发器（cron/CI 事件）+ 全程无人工审批介入，三者同时满足才算 fully automated

题目常把「交互模式」「手动运行」「需要用户批准」中的一个悄悄混进选项，只要命中其一，该选项就不成立。

练这个考点

练习模式支持按考点专练（需 Google 登录，不占用正式考机会）。

专练考点 3.6

该考点的公开题（免登录，含完整解析）：