📒 学霸笔记：15｜编程接口：驾驭 Headless 模式，将 AI 能力集成到脚本与 CI

Top Student Notes: 15 | Programming Interface: Mastering Headless Mode to Integrate AI into Scripts and CI

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 15
主题 / Topic: Headless 模式、claude -p、stdin/stdout、--output-format、JSON 输出、stream-json、Shell 集成、GitHub Actions、CI/CD 集成、AI 自动化接口

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

前面几讲，我们已经把 Claude Code 训练成了一个非常强的“交互式开发搭子”：

会记忆规则
会执行命令
会被安全约束
会回退历史
会自动触发 Hooks
会连接外部系统（MCP）
会装配 Skills
会调度 Subagents

但这里还差最后一块拼图：

这些能力目前大多还是在“人坐在终端前，和 AI 对话”的交互模式里使用。

这对探索式开发、重构、设计讨论非常好用。
但在工程实践里，还有大量任务并不是“对话式”的，而是：

周期性执行
无人值守执行
可脚本化执行
可集成进流水线
需要可编程接口

例如：

每天定时分析日志
pre-commit 阶段自动做 AI 风格审查
PR 创建后自动触发 AI 安全审计
CI 中自动生成变更摘要或测试建议

这些都要求 AI 不再只是一个“聊天伙伴”，而是：

一个可以被程序、脚本、流水线直接调用的能力模块。

所以这一讲要解决的问题是：

如何把 Claude Code 从交互式对话工具，变成可编程、可自动化集成的 AI 执行接口。

Claude Code 给出的答案就是：

Headless Mode（无头模式）

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

Headless 模式本质上是把 Claude Code 从“交互式 AI 助手”变成一个可通过 stdin/stdout 调用、可输出结构化结果、可嵌入脚本和 CI/CD 的“AI 函数接口”。

三、什么是 Headless 模式？

What Is Headless Mode?

“Headless” 在软件工程里是个经典词，意思是：

没有图形界面，甚至没有交互式界面的运行模式。

比如：

Headless Chrome
Headless CMS

在 Claude Code 里，Headless 模式的意思是：

不进入一问一答的交互会话，而是直接提交一个任务，拿到结果后退出。

也就是说，它不再像 REPL 那样等你继续聊天，而是更像一次函数调用。

四、为什么 Tony 说它像“可编程函数”？

Why Does Tony Say It Behaves Like a “Programmable Function”?

因为它的调用模式可以抽象为：

f(input) = output

输入（Input）

可以是：

一个 Prompt 参数
一段通过 stdin 管道输入的内容
文件内容
diff
日志
命令结果

函数体（Execution Body）

就是 Claude Code 背后的完整 AI Agent 能力，包括：

上下文加载
工具调用
Skill / Subagent 使用
模型推理
规则遵守
安全机制

输出（Output）

可以是：

普通文本
JSON 结构化结果
流式 JSON

学霸理解

交互模式下，Claude Code 更像：

会聊天、会协作的长期工作伙伴

而 Headless 模式下，它更像：

一个可以写进脚本和流水线的 AI API 包装器

五、这一讲真正的升级是什么？

What Is the Real Upgrade in This Lecture?

这一讲不是教你一个小参数，而是在完成 Claude Code 使用方式的最终升级：

从“手动驾驶”到“自动驾驶接口化”。

前面几讲的形态

你坐在终端前：

输入 Prompt
看 AI 执行
审批工具调用
继续推进工作流

这是“人机互动式”流程。

Headless 之后的形态

你可以：

在 Shell 脚本里调用 AI
在 CI 里调用 AI
在 cron 任务里调用 AI
在 GitHub Actions 里调用 AI
在其他程序里把 AI 当一个命令行处理器来用

这时 AI 真正进入了工程自动化体系。

六、开启 Headless 模式的关键：`-p`

The Key to Headless Mode: `-p`

Headless 模式最核心的开关就是：

claude -p "your prompt"

其中：

-p
或 --print

都表示：

这是一次非交互式调用

Claude Code 会：

接收你的任务
执行
输出结果
结束进程

七、两种输入方式：参数输入 vs stdin 输入

Two Input Modes: Argument Input vs stdin Input

这一讲的第一个实用重点，就是理解 Headless 模式下如何给 Claude Code 输入内容。

八、方式一：直接通过参数传 Prompt

Mode 1: Pass the Prompt Directly as an Argument

例如：

claude -p "Stage我的修改，然后生成一条符合Conventional Commit规范的Message"

适合什么场景？

指令较短
上下文不大
快速单次调用
脚本中直接拼接命令

例子本质

Tony 举的例子其实很好，它展示了：

Prompt 可以直接写在命令行
Claude Code 执行完整动作
最后把最终文本打印到 stdout

学霸理解

这是最像“命令行函数调用”的方式。

九、方式二：通过 stdin 管道输入上下文

Mode 2: Feed Context Through stdin Pipes

这是 Headless 模式真正强大的地方之一。

你可以把任何命令输出，通过管道喂给 Claude Code：

cat nginx-error.log | claude -p "请分析这份Nginx错误日志，总结出最主要的错误类型和可能原因。"

这为什么重要？

因为真实工程里，很多输入都不是一句话，而是：

几千行日志
大段 diff
测试结果
JSON 文件
PR 变更
git diff
tree
构建错误输出

这些内容放在命令行参数里不现实，但通过 stdin 就非常自然。

这与 Unix 工具哲学完美契合

Claude Code 在 Headless 模式下可以像这些工具一样工作：

grep
awk
sed
jq

也就是说，它可以成为 Shell 工具链中的一个智能处理器。

学霸理解

stdin 让 Claude 成为“能理解复杂文本流的智能过滤器”。

十、Headless 的根基：stdin/stdout

The Foundation of Headless Mode: stdin/stdout

这一讲真正要建立的不是命令记忆，而是一个工程化心智模型：

Claude Code Headless 是一个遵循 Unix 输入输出流哲学的 AI 命令行处理器。

stdin 用来接收大规模上下文

文件内容
diff
日志
命令输出

stdout 用来输出结果

普通文本
JSON
JSON 流

这带来的意义

你可以把它嵌入任何现有流程：

Shell pipeline
CI step
cron job
pre-commit hook
GitHub Action
Makefile

十一、结构化输出为什么关键？

Why Is Structured Output So Important?

如果只有纯文本输出，Claude Code 虽然能被脚本调用，但脚本很难稳定处理结果。

因为脚本更喜欢这样的数据：

明确字段
明确状态
可机器解析
可监控
可审计

所以光有 Headless 还不够，还必须有：

结构化输出

这就是 --output-format 的价值。

十二、`--output-format` 的三种格式

The Three `--output-format` Modes

Claude Code 支持：

text（默认）
json
stream-json

十三、`text`：人类友好

`text`: Human-Friendly Output

这是默认格式。

适合：

人直接阅读
快速查看结果
一次性手工调用

但不适合复杂自动化，因为脚本很难稳定抽取信息。

十四、`json`：机器友好的完整执行报告

`json`: A Machine-Friendly Full Execution Report

这一讲最重要的格式就是：

--output-format json

它输出的不是简单答案，而是完整报告

里面通常包含：

任务是否成功
耗时
最终结果
token 消耗
成本
session_id
模型使用情况
权限拒绝情况
UUID 等元数据

Tony 为什么强调它很重要？

因为当你把 AI 集成进 CI / 自动化系统时，你不只是想知道“AI说了什么”，你还想知道：

任务是否真的成功
花了多少钱
用了哪个模型
是否有权限失败
是否超时
最终结果在哪个字段里

学霸理解

json 输出不是“答案”，而是：

一次 AI 调用的可审计执行凭证。

十五、你能从 JSON 里拿到什么？

What Can You Extract from the JSON?

Tony 举了几个非常实用的例子：

审查结果：.result
总成本：.total_cost_usd
成功状态：.subtype

这意味着什么？

你可以在脚本里：

判断 AI 是否执行成功
统计成本
记录耗时
将结果写入数据库
决定后续分支逻辑

这正是自动化系统需要的。

十六、`stream-json`：实时获取 AI 的“心跳”

`stream-json`: Real-Time AI Heartbeats

如果 json 是任务完成后的总结报告，那么：

--output-format stream-json

就是实时直播。

它的特点

每一步执行都会实时输出一个 JSON 对象
按行输出（jsonl 风格）
常与 --verbose 一起使用

适合什么场景？

1. 长任务实时反馈

避免 CI 日志长时间静默

2. 构建交互式界面

你的程序可以实时消费这些事件并渲染 UI

3. 调试与可观察性

你能看到：

AI 思考过程
工具调用
工具结果
中间步骤状态

学霸理解

json 是“最终审计单”，
stream-json 是“过程事件流”。

十七、实战一的本质：把 AI 封装成 Shell 命令行工具

The Essence of Practical Example 1: Encapsulating AI as a Shell Utility

Tony 第一个实战是一个日志分析脚本 analyze_log.sh。

这个例子非常重要，因为它体现了 Headless 的典型工程用法：

把复杂的 AI 调用，封装成一个可复用的命令行脚本。

这个脚本体现了哪些关键能力？

1. AI 调用被工具化

原本要交互式输入的操作，现在变成：

./analyze_log.sh my.log

2. 输入通过管道传递

大日志也能优雅处理

3. 输出通过 JSON 精确提取

借助 jq 获取 .result

4. 结果落入文件系统

形成报告文件，进入已有工程流程

学霸理解

这说明 Headless 模式不仅能自动化，还能：

把 AI 变成团队自己的 Unix 风格命令工具。

十八、实战二的本质：把 AI 接进 CI/CD 流水线

The Essence of Practical Example 2: Connecting AI into CI/CD

这是这一讲最激动人心的部分。

Tony 用 GitHub Actions 做了一个自动 PR 审查工作流。

这标志着：

AI 不再只是开发者本地工具，而成为团队工程基础设施的一部分。

十九、这个 GitHub Actions 工作流的核心链路

The Core Flow of the GitHub Actions Workflow

这个工作流大致做了以下事情：

PR 打开或更新时触发
checkout 仓库代码
安装 Claude Code
配置 API / 环境
用 git diff 提取本次 PR 增量
将 diff 管道给 Claude Code
用 --output-format json 获取结果
解析 .result
回评论到 PR

这是一个什么闭环？

代码变更
→ AI 获取精准上下文
→ AI 做审查
→ 结果结构化输出
→ CI 程序化处理
→ 评论回开发流程

这就是 AI 原生 CI 工作流的雏形。

二十、为什么说这个工作流“上下文精准”？

Why Is This Workflow’s Context “Precise”?

因为它并没有把整个仓库一股脑扔给 AI，而是：

通过 git diff 提供本次 PR 的增量上下文。

这样有几个好处：

降低 token 消耗
聚焦本次变更
审查更准确
更适合 CI 这种频繁运行场景

二十一、为什么 JSON 输出在 CI 中尤其重要？

Why Is JSON Output Especially Important in CI?

因为 CI 不只是“展示信息”，而是：

要根据结果做后续程序逻辑。

例如：

决定工作流是否通过
决定是否发评论
决定是否阻塞 merge
记录审查成本
统计运行耗时
标记 issue severity

如果只是文本输出，很难稳定实现这些逻辑。

二十二、Headless 模式最重要的三个工程价值

The Three Most Important Engineering Values of Headless Mode

1. 标准化调用

Claude Code 从“会话系统”变成“命令行接口”。

2. 标准化输入输出

stdin / stdout + JSON，让它可以接入任何自动化链路。

3. 标准化可观察性

耗时、成本、状态、模型用量都能被采集与审计。

二十三、这一讲和前面所有扩展能力是什么关系？

How Does This Lecture Relate to All Earlier Capabilities?

这讲非常像“总集成出口”。

因为前面你学的所有能力：

Skills
Subagents
MCP
Hooks 规则
权限控制
项目规范

都还可以在 Headless 模式里继续使用。

这意味着什么？

Headless 模式不是一个孤立新功能，而是：

把前面所有 AI 能力，打包成一个可脚本化调用的编程接口。

所以它是“最后一公里”

你前面构建的是能力体系，
这一讲构建的是：

能力的自动化接入方式。

二十四、这一讲最值得建立的心智模型

The Most Important Mental Model from This Lecture

请把 Claude Code Headless 理解成：

一个遵循 Unix 哲学、可通过 stdin 输入、可通过 stdout 输出、可返回 JSON 报告的 AI 命令行函数。

如果你建立了这个模型，很多集成方式就自然了：

Shell 脚本
Git Hook
GitHub Actions
Jenkins
cron
Makefile
Python / Go 程序里 exec 调用
监控告警系统回调

二十五、对 DevOps 的真正意义

The Real Meaning for DevOps

Tony 思考题其实已经点出了关键方向：

AI 不只是写代码，它还可以参与流程控制。

例如：

如果 AI 审查出高危问题，则 CI fail
如果只是建议性问题，则 CI pass 但评论提醒
如果成本超预算，则记录监控
如果日志分析发现异常模式，则触发告警

这意味着 AI 将开始从：

生成器
审查员

进一步变成：

自动化流水线中的智能决策节点

二十六、如何把 AI 审查结果升级成“可失败的 CI 规则”？

How Can AI Review Results Be Upgraded into Fail/Pass CI Logic?

这是思考题方向，也是非常重要的工程延伸。

如果你想让 AI 审查结果影响 CI 是否通过，就必须让 AI 输出：

有结构
有优先级
有可解析字段

两种思路

思路 1：让 Prompt 要求固定 JSON 结构

例如让 AI 返回：

{
  "summary": "...",
  "high_priority_issues": 2,
  "medium_priority_issues": 3,
  "should_fail": true
}

然后 CI 中解析它。

思路 2：在 `result` 文本中强约束格式，再用脚本解析

例如要求 AI 用固定 Markdown 标题输出：

High Priority
Medium Priority
Low Priority

然后 github-script 或 shell 去判断有没有高危项。

最稳妥的实践

通常是：

在 Prompt 中明确要求机器可解析结构 + 外层 --output-format json

这样你得到的是双层结构：

Claude 执行报告 JSON
其中 .result 又是你定义好的业务 JSON

这会非常强。

二十七、使用 Headless 的设计原则

Design Principles for Using Headless Mode

原则 1：把输入上下文控制在刚好够用

不要一股脑喂整个仓库。
优先喂：

diff
单文件
特定日志片段
特定错误输出

原则 2：自动化里优先用 JSON 输出

只给人看的时候用 text，给程序用时优先 json。

原则 3：在 Prompt 中进一步约束业务结果结构

仅有外层 JSON 不够，必要时让 AI 的 .result 自己也是结构化的。

原则 4：把成本、耗时、成功率纳入监控

因为 Headless 调用已经是基础设施，应该可观测。

原则 5：让 Headless 复用你前面定义的 Skills / Subagents / 项目规范

不要把已有体系浪费掉。

二十八、本讲知识结构图

Knowledge Structure of This Lecture

Claude Code 之前主要以交互式方式使用
        ↓
工程中仍有大量无人值守、重复性、可脚本化任务
        ↓
需要把 AI 变成可编程接口
        ↓
Headless Mode
        ↓
核心开关
└── claude -p
        ↓
输入方式
├── 参数直接传 Prompt
└── stdin 管道传大规模上下文
        ↓
输出方式
├── text
├── json
└── stream-json
        ↓
json 价值
├── 结果可编程
├── 可审计
├── 可监控
└── 可驱动 CI 分支逻辑
        ↓
应用场景
├── Shell 脚本日志分析
├── pre-commit AI 审查
├── GitHub Actions PR Review
└── 任何 CI/CD / cron / 自动化管道
        ↓
最终升级
Claude Code 从对话伙伴
变成脚本和流水线可调用的 AI 函数接口

二十九、学霸速记表

Quick Revision Table

知识点	结论
Headless 模式是什么	非交互式调用 Claude Code 的模式
核心开关	`claude -p` / `--print`
最核心心智模型	Claude Code 变成一个可编程函数
参数输入	适合短 Prompt
stdin 输入	适合日志、diff、长文本等大上下文
stdout 输出	返回文本或结构化结果
默认输出格式	`text`
结构化输出格式	`json` / `stream-json`
`json` 的作用	提供完整执行报告，适合脚本和审计
`stream-json` 的作用	实时输出执行过程，适合长任务与可视化
Shell 集成价值	AI 可封装成命令行工具
CI 集成价值	AI 可接入 PR 审查、日志分析、自动化流程
关键工程意义	AI 从交互工具升级为自动化基础设施接口
最佳实践	精准输入、JSON 输出、结构化结果、监控成本、复用已有 Skills/Subagents

三十、学霸自检题

Self-Check Questions

基础题

什么是 Claude Code 的 Headless 模式？
claude -p 和交互式会话最大的区别是什么？
为什么 stdin/stdout 对 Headless 模式如此重要？

进阶题

json 和 stream-json 分别适合什么场景？
为什么说 --output-format json 是严肃自动化流程的关键？
在 GitHub Actions 中，为什么用 git diff 作为 AI 输入比整个仓库更合理？

思辨题

如果你要做一个 pre-commit 的 AI 风格审查脚本，你会如何设计输入和输出？
如果你希望 AI 审查结果能阻塞 PR 合并，你会如何设计结果结构？
你所在团队有哪些自动化流程最值得首先接入 Headless 模式？

三十一、学霸总结

Top-Student Summary

这一讲讲的是 Claude Code 在工程自动化体系中的终极形态：Headless 模式。
它解决的核心问题是：

如何让 Claude Code 脱离交互式会话，成为一个可被脚本、程序和 CI/CD 流水线直接调用的 AI 接口。

前面几讲中，我们已经为 Claude Code 配备了完整的能力体系——记忆、规则、安全边界、Hooks、MCP、Skills、Subagents——但这些能力大多还是在“人与 AI 对话”的使用模式中发挥作用。而在真实软件工程里，还有大量任务需要：

无人值守
周期执行
脚本调用
流水线集成
可监控、可审计、可编程处理

Headless 模式正是为此而生。
通过 claude -p，Claude Code 不再进入交互式对话，而是像一个函数一样接受输入、执行任务、输出结果并退出。它的工程本质可以概括为：

f(input) = output

其中输入既可以是命令行参数，也可以是通过 stdin 管道传入的大规模上下文；输出既可以是文本，也可以是适合脚本处理的结构化 JSON。

这一讲的两个关键接口思想是：

stdin/stdout
使 Claude Code 融入 Unix 风格工具链，像 grep、awk、jq 一样成为命令行处理器的一环。
--output-format
尤其是 json 和 stream-json，使 AI 输出不再只是“给人看”，而是“给程序处理”。

其中：

json 提供完整执行报告，适合审计、成本记录和自动化逻辑判断
stream-json 提供实时事件流，适合长任务反馈和可视化集成

两个实战例子充分说明了 Headless 的威力：

日志分析脚本
把 AI 封装成一个可复用命令行工具
GitHub Actions 自动 PR Review
把 AI 纳入团队的 CI/CD 基础设施，实现自动获取 diff、自动审查、自动回评论的完整闭环

因此，这一讲的真正意义并不是“学一个参数”，而是：

Claude Code 从“开发者对话助手”正式升级为“可编程、可自动化、可嵌入工程系统的 AI 执行引擎”。

这也意味着，我们前面学过的所有能力——规则、Skills、Subagents、MCP 等——都可以通过 Headless 模式进入脚本和流水线，从而真正完成 AI 原生开发工作流的最后一公里。

三十二、一句话记忆

One-Sentence Memory Hook

Headless 模式的本质，是把 Claude Code 变成一个能吃 stdin、吐 JSON、可被脚本和 CI/CD 调用的 AI 函数接口。

【AI生成】学霸笔记：15｜编程接口：驾驭 Headless 模式，将 AI 能力集成到脚本与 CI

📒 学霸笔记：15｜编程接口：驾驭 Headless 模式，将 AI 能力集成到脚本与 CI

Top Student Notes: 15 | Programming Interface: Mastering Headless Mode to Integrate AI into Scripts and CI

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

三、什么是 Headless 模式？

What Is Headless Mode?

四、为什么 Tony 说它像“可编程函数”？

Why Does Tony Say It Behaves Like a “Programmable Function”?

输入（Input）

函数体（Execution Body）

输出（Output）

学霸理解

五、这一讲真正的升级是什么？

What Is the Real Upgrade in This Lecture?

前面几讲的形态

Headless 之后的形态

六、开启 Headless 模式的关键：-p

The Key to Headless Mode: -p

七、两种输入方式：参数输入 vs stdin 输入

Two Input Modes: Argument Input vs stdin Input

八、方式一：直接通过参数传 Prompt

Mode 1: Pass the Prompt Directly as an Argument

适合什么场景？

例子本质

学霸理解

九、方式二：通过 stdin 管道输入上下文

Mode 2: Feed Context Through stdin Pipes

这为什么重要？

这与 Unix 工具哲学完美契合

学霸理解

十、Headless 的根基：stdin/stdout

The Foundation of Headless Mode: stdin/stdout

stdin 用来接收大规模上下文

stdout 用来输出结果

这带来的意义

十一、结构化输出为什么关键？

Why Is Structured Output So Important?

十二、--output-format 的三种格式

The Three --output-format Modes

十三、text：人类友好

text: Human-Friendly Output

十四、json：机器友好的完整执行报告

json: A Machine-Friendly Full Execution Report

它输出的不是简单答案，而是完整报告

Tony 为什么强调它很重要？

学霸理解

十五、你能从 JSON 里拿到什么？

What Can You Extract from the JSON?

这意味着什么？

十六、stream-json：实时获取 AI 的“心跳”

stream-json: Real-Time AI Heartbeats

它的特点

适合什么场景？

1. 长任务实时反馈

2. 构建交互式界面

3. 调试与可观察性

学霸理解

十七、实战一的本质：把 AI 封装成 Shell 命令行工具

The Essence of Practical Example 1: Encapsulating AI as a Shell Utility

这个脚本体现了哪些关键能力？

1. AI 调用被工具化

2. 输入通过管道传递

3. 输出通过 JSON 精确提取

4. 结果落入文件系统

学霸理解

十八、实战二的本质：把 AI 接进 CI/CD 流水线

The Essence of Practical Example 2: Connecting AI into CI/CD

十九、这个 GitHub Actions 工作流的核心链路

The Core Flow of the GitHub Actions Workflow

这是一个什么闭环？

二十、为什么说这个工作流“上下文精准”？

Why Is This Workflow’s Context “Precise”?

二十一、为什么 JSON 输出在 CI 中尤其重要？

Why Is JSON Output Especially Important in CI?

二十二、Headless 模式最重要的三个工程价值

The Three Most Important Engineering Values of Headless Mode

六、开启 Headless 模式的关键：`-p`

The Key to Headless Mode: `-p`

十二、`--output-format` 的三种格式

The Three `--output-format` Modes

十三、`text`：人类友好

`text`: Human-Friendly Output

十四、`json`：机器友好的完整执行报告

`json`: A Machine-Friendly Full Execution Report

十六、`stream-json`：实时获取 AI 的“心跳”

`stream-json`: Real-Time AI Heartbeats

思路 2：在 `result` 文本中强约束格式，再用脚本解析