扩展与规模化

这一课你将能做到

1. 用 headless 模式（claude -p + --output-format）把 Claude Code 嵌入脚本与自动化流程
2. 在 GitHub Actions 中集成 Claude，实现 issue/PR 上的自动 triage、审查与修复
3. 用 git worktrees + 多会话实现并行开发，并了解 Claude Agent SDK 的定位

为什么要学

前面的课程都在「一个人 + 一个终端」的尺度上提效。但团队的真实诉求是：PR 提交后自动来一轮初审、issue 涌入时自动打标分类、几个功能并行开发互不干扰、把内部流程封装成自研 agent 工具。这些都指向同一个方向——把 Claude Code 当基建用：headless 让它能被程序调用，CI 集成让它进协作流程，worktrees 让多份并行不冲突，SDK 让你能自己造轮子。这是从「用户」到「平台建设者」的转变，也是当前面试中 agent 工程化的核心话题。

人话：交互模式是你开车，headless 是把车钥匙交给调度系统，CI 集成是把车编进物流车队，SDK 是直接买底盘自己改装。

先建立图像

触发方式            运行形态                 输出
─────────────────────────────────────────────────────
人在终端交互      → 完整 TUI 会话          → 对话界面
脚本/CI 调用      → headless：跑完即退出    → text / json / stream-json
GitHub 事件       → claude-code-action     → issue/PR 评论与提交
自研应用          → Claude Agent SDK       → 程序化 API

headless 的关键参数：

claude -p "提示词" \
  --output-format text|json|stream-json \
  --allowedTools "Read,Grep,Bash(npm test:*)" \
  --max-turns 20 \
  --model haiku

跟着做

步骤 1：第一个 headless 任务

# 单次问答，输出纯文本
claude -p "用三句话概括这个仓库的架构"

# 要 JSON（便于程序解析）
claude -p "列出 src 下超过 500 行的类，输出 JSON 数组" \
  --output-format json

json 格式包含结果、成本、会话 ID 等元数据；stream-json 则逐条输出事件流，适合边跑边消费。

步骤 2：加安全围栏

headless 无人值守，权限必须预声明：

claude -p "跑通所有单测并总结失败原因" \
  --allowedTools "Read" "Grep" "Bash(mvn test:*)" \
  --max-turns 30

只放行需要的工具与命令前缀；超出白名单的操作直接被拒，模型会基于拒绝信息调整路径。--max-turns 限制最大循环轮数，防止兜圈子烧钱。

步骤 3：接入 GitHub Actions

在仓库 .github/workflows/claude.yml 中使用官方 action：

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

效果：在 issue 或 PR 评论里 @claude 修复这个 bug，机器人会分析上下文、提修改甚至开 PR。也可改为 push 触发做自动初审。注意：action 自己也有一层权限配置（如允许哪些工具），需按官方文档设置，且要警惕「不可信 issue 内容诱导 agent」的提示注入风险。

步骤 4：并行开发——worktrees + 多会话

# 两个功能两份工作区，互不干扰
git worktree add ../proj-feat-a feat-a
git worktree add ../proj-feat-b feat-b

cd ../proj-feat-a && claude    # 终端 1
cd ../proj-feat-b && claude    # 终端 2

每个 worktree 有独立目录与分支，两个 Claude 会话同时改代码不会踩脚。收尾：git worktree remove ../proj-feat-a。

步骤 5：分工协作模式

同一仓库内让多个会话各司其职：

会话 A（主开发）：实现功能
会话 B：你只对它说「review 会话 A 改动的文件，只读模式」

B 用 plan 模式（只读）审查 A 的产出，形成「生产者—审查者」分离，避免自己改自己审的盲区。这本质是用 agent 复刻团队里的 MR 流程。

步骤 6：认识 Claude Agent SDK

当 headless 也无法满足（需要自定义工具循环、嵌入自家产品）时，可用官方 SDK（TypeScript / Python）以库的形式驱动同一套 agent 能力：自定义系统提示、工具集、权限与子代理。定位：Claude Code 是「开箱即用的最佳实践」，SDK 是「同引擎的改装件」。

讲清楚要点

1. headless 三要素：单次提示、声明式权限、结构化输出。它是把「交互会话」压扁成「一次函数调用」，适用于目标明确、路径可预测的任务。
2. CI 场景的安全三原则：最小 --allowedTools、专用低权限密钥（独立于个人账号）、产物必须走 PR 审核而非直推主干。
3. worktree 是并行的物理隔离：比「同一目录多会话」安全得多——后者会出现编辑互相覆盖、git 状态串味的问题。
4. 自动化任务选低档模型 + 明确输出格式：批量类任务用 haiku 控成本；要求 JSON 输出便于下游解析，别让下游去 grep 自然语言。
5. 失败要可见：headless 退出码非零即失败，CI 中据此让流水线报错；stream-json 便于记录完整轨迹做审计。

你可能会懵的地方

• CI 里权限确认没人点怎么办？ 没人点，也不该绕过——正确做法是白名单预声明（--allowedTools / --permission-mode acceptEdits），其余操作自然拒绝。永远不要在 CI 用 bypass 全开关，等价于给流水线 root 权限。

• @claude 会不会被恶意 issue 玩坏？ 有提示注入风险（issue 正文诱导 agent 执行恶意操作）。缓解：action 层限制可用工具、限制可修改范围、敏感仓库要求人工确认后才会提交 PR、密钥用最小权限专用 token。

• headless 和 SDK 怎么选？ 目标能用「一条提示 + 工具白名单」表达 → headless（零代码）；需要自定义工具、多步编排、嵌入产品 UI → SDK。先 headless 后 SDK，避免过度工程。

• 多会话并行的成本怎么估？ 每个会话独立计费（订阅各自占额度 / API 各自计 token）。用 --model haiku 跑并行机械任务、限制 --max-turns，是控制并行成本的两个主阀。

• worktree 与分支有什么区别？ 分支是「版本线」，worktree 是「工作目录」。一个仓库可以多个 worktree 同时检出不同分支，让「切换上下文」不用提交半成品代码。

错法对照

错法	问题	正解
CI 里 --dangerously-skip-permissions	流水线被 agent 全权操控	最小化工具白名单 + 专用密钥 + PR 审查
headless 输出 text 再用正则抠结果	脆弱、易碎	--output-format json，程序化解析
多个会话共用同一工作目录	编辑覆盖、git 操作互相干扰	git worktree 物理隔离
自动化任务用最强模型跑批	成本不可控	批量用 haiku，复杂任务才升档
headless 不设 --max-turns	模型兜圈时无限烧钱	设上限 + 退出码校验

卡点急救

1. GitHub Action 不触发：检查触发条件（comment 关键字 @claude）、workflow 文件的 on 配置、secrets 是否注入；看 Actions 运行日志定位。
2. stream-json 解析失败：它是逐行 JSON 事件流（非单个大对象），按行解析并按 type 字段分发处理。
3. worktree 混乱找不到北：git worktree list 盘点；用完即 remove；命名规范（../proj-分支名）从源头防乱。

面试常问

• 如何在 CI/CD 中安全集成 coding agent？ 权限收敛（最小工具白名单、专用最小权限凭证、禁用全放权开关）、输入可信（对用户可控内容做提示注入防护）、输出受控（agent 产出走 PR 由人合并）、可观测（日志与成本留痕）。核心思想：agent 自动化程度越高，人类审查点越要明确保留。

• 设计多智能体协作的思路？ 按职责切分（实现者/审查者/测试者），用独立上下文隔离关注点，主会话做编排与汇总；物理上用 worktree 避免写冲突；通信靠明确的任务描述与结构化报告。避免为并行而并行——协作带来的编排成本必须小于收益。

• headless 模式适合与不适合的场景？ 适合：目标明确、可验证、输入输出可结构化的任务（批量审查、生成摘要、定时巡检）。不适合：需要人工交互决策、探索性强的任务——那些仍应回到交互模式，用 Plan 模式对齐。

自测三问

1. headless 模式的三个关键参数分别解决什么问题？
2. 为什么 CI 集成中 agent 产物必须走 PR 而不是直接提交？
3. git worktree 解决了并行开发的什么痛点？

小结一句话

规模化 = headless 提供调用接口 + CI 提供触发场景 + worktree 提供物理隔离 + SDK 提供定制底座；自动化每前进一步，人类审查点就设计一步。

延伸

• Headless 模式官方文档
• 下一课：内置工具集——拆开引擎盖，看 Read/Edit/Bash/Grep 这些工具如何协同，理解模型「动手」的全部手段。