实战五:headless 流水线
Q13 讲过 7 个 FrameworkMode,headless 与 ACP、TUI 并列。 本章不再是「读代码」,而是把它接进 CI: 让工具、钩子、技能、MCP 服务器在无人值守时也能跑。
一、headless 是自动判定的,不是配出来的
很多人以为要加 --headless。没有这个标志。
判定在 isHeadlessMode(packages/core/src/utils/headless.ts:45-77),四条触发条件:
| 条件 | 判据 |
|---|---|
| CI 环境 | process.env.CI === 'true' 或 GITHUB_ACTIONS === 'true' |
| 非 TTY | stdin 或 stdout 任一不是 TTY |
| 显式 prompt | --prompt / -p 存在 |
| SDK 模式 | --input-format stream-json 或 --print |
「非 TTY」是其中最容易被忽略的一条。在 CI 里管道重定向了 stdout,
process.stdout.isTTY 就是 undefined,于是自动进 headless——
你甚至不用传任何标志。
这也解释了一个常见困惑:「本地能交互,进 CI 变成一次性执行」。 不是你配错了,是 TTY 没了。
:46-52 还有个反例开关:
if (readBrandEnv(ENV_INTEGRATION_TEST) !== 'true') { const isCI = process.env['CI'] === 'true' || process.env['GITHUB_ACTIONS'] === 'true'; if (isCI) { return true; }}集成测试可以设一个环境变量,让 CI 检测失效。 否则测试在流水线里跑,永远拿不到交互模式,一半用例写不出来。
二、两条输入路径
进去之后分两条路(packages/cli/src/headless/headlessSession.ts:199-203):
if (this.streamJsonInput) { await this.runStreamJsonInput();} else { await this.runTextTurn();}text 路径:读一次性 prompt,跑一轮,把最终结果打到 stdout。 适合「跑完就走」的 CI 任务。
stream-json 路径:从 stdin 流式读多条用户消息,每条都跑, 结果按帧(frame)逐条写到 stdout。适合长会话: 你可以在一个进程里连续问十个问题,不用每次重启(省掉冷启动和上下文重建)。
输入两条路,输出三条(--output-format,见 commands/index.ts:419):
text(纯文本)、json(单个 JSON 对象)、stream-json(逐帧流)。
输入 stream-json 必须配输出 stream-json,否则启动就报参数错误——
因为流式输入需要帧级回执,纯文本无法承载。
路由标签也据此区分(packages/cli/src/startup/options/headless.ts:28-33):
headlessStreamJson 与 headlessText。两个标签在监控里是分开统计的。
三、退出码:CI 唯一能听懂的语言
CI 不读你的漂亮输出,它只看退出码。
headless 的退出码规则写在 nonInteractiveOutput.ts:63-106:
export function getHeadlessResultExitCode(msg: SDKMessage): number | undefined { if (msg.type !== 'result') { return undefined; } return msg.is_error ? 1 : 0;}再看中断的处理(:78-81):
} else if (msg.type === 'result' && msg.subtype !== 'success') { const errorMsg = extractResultErrors(msg); process.exitCode = errorMsg.includes('Operation aborted') ? 130 : 1;}三条规则:
| 情形 | 退出码 |
|---|---|
result.is_error === true |
1 |
被中断(Operation aborted) |
130 |
| 其它非 success 子类型 | 1 |
| 正常 | 0 |
130 是 shell 的惯例值(128 + SIGINT=2)。流水线看到 130 就知道 「有人按了取消」,不是代码有问题;看到 1 才是真失败。 把两者混成一个 1,会让「取消」在报表里显示成「失败」, 排查时白找半天。
text 路径还有三种子类型的分支(:88-105):
success、error_during_execution、error_max_turns。
最后一条尤其重要——回合数用尽也算失败。
Q12 讲过子代理有回合上限;主会话在 headless 下同理,
跑到上限就 exit 1,不会假装成功。
四、没人能点「允许」时,权限怎么办
这是 headless 最实际的问题。TUI 里弹个窗,你点一下就行;
CI 里没人。源码给了四种模式(packages/cli/src/utils/headlessPermissionPrompt.ts):
| 模式 | 触发条件 | 谁来回答 |
|---|---|---|
| stdio 提示 | --permission-prompt-tool stdio |
通过 stdio 问宿主进程 |
| 具名工具 | 传了其它工具名 | 用那个 MCP 工具去问 |
| 默认 | --input-format stream-json 且未指定 |
走 stdio |
| 远程 worker | 远程 worker 模式 | 交给远端控制器 |
优先次序在 :32-40:
const isStdio = isStdioPermissionPromptTool(permissionPromptTool);const isNamedPermissionPromptTool = Boolean(permissionPromptTool) && !isStdio;const namedPermissionPromptTool = isNamedPermissionPromptTool ? permissionPromptTool : undefined;const useStdioPermissionPrompt = isStdio || (!isNamedPermissionPromptTool && inputFormat === 'stream-json');注意 stdio 这个值是特例:它是唯一被硬编码的名字,
其余任何字符串都当「工具名」。所以别给工具起名叫 stdio。
:47-48 那句注释解释了一个容易踩的坑:
// SDK 仅在配置 canUseTool 时显式传入 stdio;未配置时由权限 Hook 决策。installStdioPermissionHandler: useStdioPermissionPrompt && (!isSDKMode() || isStdio),SDK 模式下,如果宿主没配 canUseTool 回调,不安装 stdio 处理器。
否则一个没人接的权限请求会挂在那儿,等到超时才结束。
让权限 Hook 去决策(Q16 写的那种),至少能立刻给出 deny。
实践建议:CI 里最省事的做法不是去实现权限协议, 而是在配置里把「允许什么」写清楚:
- 用
--permission-mode选一个预置模式 - 或用 Q08 的规则文件,白名单精确到命令
- 或给 MCP 服务器加
trust: true(Q18 讲过)
五、异常收敛:一条流不能断在半截
stream-json 的消费者(你的脚本)在逐行解析 stdout。 如果进程中途抛出未捕获异常,输出就断在半个 JSON 上—— 解析器直接崩,你连错误信息都拿不到。
所以 run() 有一段专门处理这件事(headlessSession.ts:204-217):
} catch (error) { if (error instanceof HeadlessStartupAbort) { this.renderStartupFailure(error.failure); } else if ( this.streamJsonOutput && this.openedSessionId && !(error instanceof FatalError) ) { // stream-json 的会话级意外失败以单帧 result 收尾;text 与 FatalError // 仍走入口的错误出口(stderr + 对应退出码)。 this.renderSessionFailure(error); } else { throw error; }} finally { this.permissionChannel?.close();四个条件同时成立才「收敛成 result 帧」: 用了 stream-json 输出、会话已打开、且不是致命错误。 会话没打开就不收敛——因为这时还没有流可断,直接抛出去更清楚。
finally 里三件事也值得看:关权限通道、移除 stdout 错误处理、
finish() 里清工具失败日志。清日志是为了不跨会话泄漏——
长驻进程跑十条消息,第九条的失败不该出现在第十条的报告里。
六、把前面四章接起来:一条真实的 CI 流水线
到这一步,我们手上的东西可以拼成一条完整的审查流水线了。
.qwen/settings.json(权限白名单):
{ "permissions": { "allow": [ "Read", "Bash(npm test:*)", "Bash(git diff:*)" ], "deny": ["Bash(git push:*)", "Bash(rm:*)"] }}.qwen/skills/review/SKILL.md(Q17 写的技能,改一版做审查):
---name: reviewdescription: Review staged changes for bugs and style issues.allowed-tools: Read, Bash---审查 `git diff --staged` 的内容。1. 读 diff,逐文件列出改动意图2. 找逻辑错误、边界条件、未处理的错误路径3. 输出 Markdown 表格:文件 | 问题 | 严重度只报告真实问题,不要凑数。CI 脚本:
#!/usr/bin/env bashset -uo pipefailqwen --prompt "/review" --output-format text > review.mdcode=$?case $code in 0) echo "review ok" ;; 130) echo "cancelled"; exit 0 ;; *) echo "review failed (exit $code)"; exit $code ;;esac三个细节:
set -e换成set -uo pipefail。要自己读$?,就不能让set -e在赋值前把脚本干掉。- 130 当作成功。取消不是失败,别让报表变红。
--output-format text拿到的是纯文本结果,写> review.md直接成文件; 要结构化就换json(单次结果)或stream-json(逐帧)。
七、工程暗坑
1. 没有权限通道时会降级成 isPlainHeadless
源码在 config.ts:1343-1347 判定:非交互且无外部权限处理器时,
隐藏交互类工具、关掉 Plan 模式(isPlanModeRequest(...) && !isPlainHeadless,:1355)。
所以在 CI 里配置不全等于一批能力直接消失,而不是「等着人点」。
2. stdout 只能有协议数据
installStdoutErrorHandler 在 run() 里很早就装上了(:190)。
任何 console.log 都会污染流——包括你加的调试输出。
调试信息一律走 stderr。
3. 回合上限会静默截断长任务
error_max_turns 是真实存在的失败子类型。
一个大重构如果预计要 40 轮,就得把上限调上去,
否则跑一半退出、退出码 1,看起来像「代码有问题」。
4. 超时是外部的责任
headless 自己不设总时长上限。CI 平台通常有 job timeout,
但那会杀掉进程、拿不到 result 帧。
更稳的做法是在脚本里用 timeout 600 qwen ...,
让它先收到中断、走 130 那条路。
5. 非 TTY 下颜色码可能混进输出
即使不用 --output-format,某些库会检测到「不是 TTY」而跳过颜色。
但如果检测写错,ANSI 码就混进 review.md。
看到文件里有一堆 [32m,就是这个问题。
八、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/core/src/utils/headless.ts |
100 | :45-77 四条触发条件 |
:46-52 集成测试豁免 |
||
packages/cli/src/startup/options/headless.ts |
42 | :28-33 两条路由标签 |
packages/cli/src/headless/headlessSession.ts |
954 | :183-229 run() 主流程 |
:199-203 两条输入路径 |
||
:204-227 异常收敛与清理 |
||
packages/cli/src/utils/nonInteractiveOutput.ts |
273 | :63-68 退出码 |
:74-82 中断 130 |
||
:84-106 三种子类型 |
||
packages/cli/src/utils/headlessPermissionPrompt.ts |
54 | :28-53 四种权限模式 |
packages/cli/src/nonInteractiveCliCommands.ts |
351 | 斜杠命令在 headless 下的服务化 |
packages/core/src/engine/headless-projection.ts |
923 | 会话事件投影成 SDK 消息 |
九、自己动手验证
node qw-examples/check/19-headless.mjs预期输出:
headless triggers: 4 -> CI env | not TTY | prompt flag | stream-jsonalso accepts -p: trueGITHUB_ACTIONS env: trueheadless routes: 2 -> headlessStreamJson / headlessTextexit code: is_error -> 1: trueexit code: aborted -> 130: truetext result subtypes handled: success, error_during_execution, error_max_turnswriteHeadlessTextResult cases: 3permission prompt modes: 4 -> stdio | named tool | stream-json→stdio | remote workerrun() steps: 35has runStreamJsonInput: truehas runTextTurn: truesession failure as single result frame: true关键文件行数: 100 core/src/utils/headless.ts 923 core/src/engine/headless-projection.ts 42 cli/src/startup/options/headless.ts 954 cli/src/headless/headlessSession.ts 273 cli/src/utils/nonInteractiveOutput.ts 54 cli/src/utils/headlessPermissionPrompt.ts 351 cli/src/nonInteractiveCliCommands.ts改一处试试:注释掉 headless.ts:58 里的 !!options?.prompt,
然后用 qwen -p "hi" 在一个真终端里跑。
你会看到它没有进 headless——因为 TTY 还在, 而唯一的触发条件被你关了。光标悬在那里等交互输入。 这个实验直接证明:headless 是「环境推断」出来的,不是一个开关。
十、全书收尾
到这里,19 章全部走完。回头看这条路线:
- Part A 给了你一张地图(Q01–Q02)
- Part B 拆开了内核:事件总线、对话回合、请求装配、消息协议、工具、权限
- Part C 讲了上下文怎么攒起来又怎么压下去,技能与子代理怎么复用
- Part D 说清楚了三种前端(ACP、headless、TUI)如何共用一套内核
- Part E 是你亲手写的五个东西:工具、钩子、技能、MCP 服务器、CI 流水线
如果只记三句话:
- 一切皆事件。
query()只有一个输入口,其余全是事件进出。 - 确定性换可靠性。参数替换不用模型、工具 ID 重写保持稳定、 MCP 键名反向映射——凡是能用字符串干的事,都不交给模型。
- 失败要显式。
POLICY_VIOLATION不重试、130 不等于 1、 幽灵 required 剪掉要打 warn——能看见的失败,才是能修的失败。
附录 A 是一份「按问题查」的索引,附录 B 列了全书引用的源码坐标。 之后你该去读真正的源码了——这本书只是带你走到门口。
本章读完你应该能回答: ① headless 是谁判定的,能主动关掉吗? ——
isHeadlessMode()按环境推断,CI 与 TTY 两条最常触发; 集成测试可用环境变量豁免。 ② 退出码 130 和 1 有什么区别? ——130 是被中断(128+SIGINT),1 是真失败。 ③--output-format有几个取值? ——三个:text、json、stream-json。 ④ stream-json 模式下进程崩溃会发生什么? ——会话已打开时会收敛成一帧result收尾,不让流断在半截。 ⑤ 没有权限协议实现时会怎样? ——进入isPlainHeadless:隐藏交互工具、禁用 Plan 模式 (config.ts:1343-1347),因为没有「人」可以做批准。