这是「Claude Code 通关手册」系列的第 8 篇，共 10 篇。从这篇开始进入 Level 4（高级篇），解锁 Claude Code 的编程接口。

到今天为止，你跟 Claude Code 的交互方式一直是"对话"——你在终端里打字，它回答。你说"审查这个文件"，它审查。你说"写个组件"，它写。

这种方式很直觉，但它有一个本质限制：你得在场。

你不在键盘前，它就不工作。它不能凌晨 2 点自动扫描代码仓库然后把质量报告发到钉钉群。它不能在每次有人提 PR 的时候自动做一轮审查。它不能批量处理 100 个文件的文档生成。

今天要讲的两个东西，把这个限制彻底打破：

Headless 模式：用命令行参数驱动 Claude Code，不需要交互界面，可以嵌入任何 Shell 脚本和 CI/CD 流水线
Agent SDK：用 TypeScript / Python 代码调用 Claude Code 的全部能力，构建你自己的 AI 驱动工具

从"人驱动 AI"到"代码驱动 AI"——这是认知上的跨越。

一、Headless 模式——一行命令，Claude 自动干活

最简形式

Headless 模式的核心是 -p 参数（prompt 的缩写）：

bash
claude -p "分析 src/app/page.tsx 的性能问题"

就这么简单。Claude Code 收到指令，执行分析，把结果输出到 stdout，然后退出。没有交互界面，没有等待输入——执行完就走。

三种输出格式

bash
# 默认：纯文本输出（适合人类阅读）
claude -p "列出项目中的 TODO 注释" --output-format text

# JSON：结构化输出（适合程序解析）
claude -p "列出项目中的 TODO 注释" --output-format json

# Stream JSON：逐条消息流式输出（适合实时处理）
claude -p "重构 ArticleList 组件" --output-format stream-json

JSON 格式是自动化场景的首选——你可以用 jq 提取字段、用脚本解析结果、存入数据库、发到通知渠道。

bash
# 提取 JSON 中的文本内容
claude -p "检查 package.json 中有没有过期的依赖" \
  --output-format json | jq -r '.result'

关键参数

bash
claude -p "你的指令" \
  --output-format json \        # 输出格式：text / json / stream-json
  --max-turns 3 \               # 最大执行轮次（控制成本）
  --allowedTools Read,Grep \    # 限制可用工具（安全）
  --model sonnet                # 指定模型

--max-turns 在自动化场景中特别重要——它限制 Claude 的"思考轮次"。一个简单的代码审查通常 1-2 轮就够了，设成 3 是安全上限。没有这个限制，Claude 可能在复杂任务上无限循环，Token 费用飙升。

实操：批量代码审查脚本

这是一个实际可用的脚本——审查最近 5 次提交中修改过的所有文件：

bash
#!/bin/bash
# review-recent.sh — 批量审查最近修改的文件

OUTPUT_FILE="review-report.json"
echo "[]" > "$OUTPUT_FILE"

for file in $(git diff --name-only HEAD~5 -- '*.ts' '*.tsx'); do
  echo "🔍 审查: $file"
  
  result=$(claude -p "审查 $file 的代码质量。关注：
    1. TypeScript 类型安全
    2. React 最佳实践
    3. 性能隐患
    输出 JSON：{\"file\": \"文件名\", \"issues\": [{\"severity\": \"high/medium/low\", \"line\": 行号, \"message\": \"描述\"}]}" \
    --output-format json \
    --max-turns 2 \
    --allowedTools Read,Grep,Glob 2>/dev/null)
  
  # 追加到报告
  echo "$result" >> "$OUTPUT_FILE"
done

echo "✅ 审查完成，报告: $OUTPUT_FILE"

注意 --allowedTools Read,Grep,Glob——只给了只读权限。批量脚本里绝对不要给写权限，万一 Claude 理解错了意图自动改了你的代码，100 个文件全改错，你哭都来不及。

另一个实用场景：自动生成 Changelog

bash
#!/bin/bash
# 从 Git 提交记录自动生成 Changelog

git log --oneline origin/main...HEAD | \
claude -p "基于这些 Git 提交记录，生成一份结构化的 Changelog。
分类为：✨ 新功能、🐛 Bug修复、🔧 优化、📝 文档。
用 Markdown 格式输出。" \
--output-format text \
--max-turns 1 > CHANGELOG.md

echo "✅ Changelog 已生成"

这个脚本可以直接放到 release 流程里——每次发版前自动跑一次，Changelog 就有了。

二、Agent SDK——用代码获得 Claude Code 的全部能力

Headless 模式适合简单的"一问一答"场景。但如果你需要更复杂的控制——多轮对话、自定义工具、流式处理、会话恢复——就需要 Agent SDK。

重要说明：名称变更

Claude Code SDK 已正式更名为 Claude Agent SDK。包名从 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-agent-sdk。如果你看到网上的旧教程用的还是老包名，知道是同一个东西就行。

安装

bash
# TypeScript / JavaScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

环境变量：

bash
export ANTHROPIC_API_KEY="your-api-key"

核心概念：query() 函数

Agent SDK 的核心就一个函数——query()。它接收一个 prompt，返回一个异步迭代器，你可以逐条消息处理 Claude 的输出。

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

// 最简用法
for await (const message of query({ prompt: "分析当前目录的项目结构" })) {
  if (message.type === "assistant") {
    // Claude 的回复
    for (const block of message.message.content) {
      if (block.type === "text") {
        console.log(block.text);
      }
    }
  }
  
  if (message.type === "result") {
    // 最终结果
    console.log("完成:", message.result);
  }
}

query() 不是简单的"发请求→收回复"。它内部运行着一个完整的 Agent 循环——Claude 会自动调用工具（读文件、执行命令、搜索代码），观察结果，决定下一步，直到任务完成。你只需要消费这个流就行了。

配置项

typescript
const result = query({
  prompt: "审查 src/app/api/ 下的所有 API 路由",
  options: {
    // 模型选择
    model: "sonnet",
    
    // 权限模式
    permissionMode: "bypassPermissions",  // CI 环境用这个
    // 其他选项："default"（正常交互）、"acceptEdits"（自动同意编辑）
    
    // 限制可用工具
    allowedTools: ["Read", "Grep", "Glob"],
    
    // 最大执行轮次
    maxTurns: 5,
    
    // 自定义系统提示
    systemPrompt: "你是一个严格的代码审查专家...",
    
    // 设置来源（是否加载本地配置文件）
    settingSources: ["project"],  // 只加载项目级配置
    // 默认 [] 表示不加载任何文件配置，完全由代码控制
  }
});

几个关键配置解读：

permissionMode 决定了 Claude 执行操作时的权限策略。在 CI/CD 里用 "bypassPermissions" 跳过所有权限确认（因为没人在终端前点"同意"）。在本地开发工具里用 "acceptEdits" 自动同意文件编辑。

settingSources 控制是否加载 .claude/settings.json 等配置文件。默认值是空数组——SDK 模式下一切由代码控制，不依赖文件系统。如果你想复用项目里已有的子代理和 Hooks 配置，设成 ["project"]。

allowedTools 限制 Claude 可以使用的工具。这是安全的第一道防线——审查任务只给 Read，生成任务可以给 Read + Write。

三、实操项目：DevPulse 文档自动生成器

现在用 Agent SDK 构建一个实际的工具——自动为 DevPulse 项目中的每个组件生成文档。

项目结构

code
devpulse-doc-gen/
├── package.json
├── tsconfig.json
└── src/
    └── index.ts        ← 主逻辑

完整代码

typescript
// src/index.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import * as fs from "fs";
import * as path from "path";
import { glob } from "glob";

// ========== 配置 ==========
const COMPONENTS_DIR = "../devpulse/src/components";
const OUTPUT_DIR = "../devpulse/docs/components";
const MODEL = "sonnet";

// ========== 核心函数：为单个组件生成文档 ==========
async function generateDocForComponent(filePath: string): Promise<string> {
  const fileName = path.basename(filePath, path.extname(filePath));
  let docContent = "";

  for await (const message of query({
    prompt: `阅读组件文件 ${filePath}，生成 Markdown 格式的组件文档。

要求：
1. 组件概述（一句话说明用途）
2. Props 表格（名称、类型、是否必填、默认值、说明）
3. 使用示例（至少 2 个：基础用法 + 高级用法）
4. 注意事项（常见错误、性能考虑）
5. 相关组件

输出纯 Markdown，不要代码块包裹。`,
    options: {
      model: MODEL,
      allowedTools: ["Read", "Grep", "Glob"],
      maxTurns: 3,
      permissionMode: "bypassPermissions",
    },
  })) {
    if (message.type === "result") {
      docContent = message.result;
    }
  }

  return docContent;
}

// ========== 主流程 ==========
async function main() {
  // 1. 找到所有组件文件
  const componentFiles = await glob(`${COMPONENTS_DIR}/**/*.tsx`, {
    ignore: ["**/*.test.tsx", "**/__tests__/**"],
  });

  console.log(`📦 找到 ${componentFiles.length} 个组件文件`);

  // 2. 确保输出目录存在
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });

  // 3. 逐个生成文档
  for (const file of componentFiles) {
    const componentName = path.basename(file, ".tsx");
    console.log(`📝 生成文档: ${componentName}`);

    try {
      const doc = await generateDocForComponent(file);
      const outputPath = path.join(OUTPUT_DIR, `${componentName}.md`);
      fs.writeFileSync(outputPath, doc, "utf-8");
      console.log(`  ✅ 完成 → ${outputPath}`);
    } catch (err) {
      console.error(`  ❌ 失败: ${componentName}`, err);
    }
  }

  console.log(`\n🎉 文档生成完成，共 ${componentFiles.length} 个组件`);
}

main().catch(console.error);

运行

bash
npx tsx src/index.ts

code
📦 找到 12 个组件文件
📝 生成文档: ArticleCard
  ✅ 完成 → ../devpulse/docs/components/ArticleCard.md
📝 生成文档: ArticleList
  ✅ 完成 → ../devpulse/docs/components/ArticleList.md
📝 生成文档: Header
  ✅ 完成 → ../devpulse/docs/components/Header.md
...
🎉 文档生成完成，共 12 个组件

12 个组件的文档，全自动生成。你可以把这个脚本挂到 Git hook 上——每次有组件文件变更，自动更新文档。

关键设计决策

为什么用 maxTurns: 3？ 生成文档需要 Claude 读取源文件（1 轮）、可能再 grep 一些引用关系（1 轮）、然后生成输出（1 轮）。3 轮足够了，超过说明 Claude 在做无用功。

为什么只给 Read/Grep/Glob？ 文档生成器只需要"看"代码，不需要"改"代码。限制工具 = 限制风险。

为什么逐个处理而不是并行？ Agent SDK 的每个 query() 调用都会启动一个完整的 Agent 进程。并行跑 12 个会消耗大量资源和 Token。逐个处理更可控，也更便宜。

四、Python SDK 简介

前端读者可以跳过这节，但了解一下也不吃亏——很多自动化场景混合使用 TypeScript 和 Python。

python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def review_code():
    async for message in query(
        prompt="审查 src/app/api/posts/route.ts 的安全问题",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep"],
            permission_mode="bypassPermissions",
            max_turns=3,
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(review_code())

Python SDK 和 TypeScript SDK 的 API 几乎一一对应，核心都是 query() 函数，区别只是语言语法。

什么时候选 Python？ 如果你的自动化流程涉及数据分析（Pandas）、ML Pipeline（PyTorch/TensorFlow）、或者团队的 CI 工具链是 Python 生态的。

什么时候选 TypeScript？ 如果你是前端开发者、项目本身是 Node.js 生态、或者你要构建 Web 服务。

五、三种方式对比

code
┌──────────────────────────────────────────────────────────┐
│     Headless vs TypeScript SDK vs Python SDK              │
├──────────────┬─────────────────┬─────────────────────────┤
│ 维度          │ Headless (CLI)   │ Agent SDK (TS / Python) │
├──────────────┼─────────────────┼─────────────────────────┤
│ 使用方式      │ claude -p "..."  │ query({ prompt: "..." })│
├──────────────┼─────────────────┼─────────────────────────┤
│ 适合场景      │ Shell 脚本       │ 复杂工具、Web 服务、     │
│              │ 简单自动化       │ 多轮对话、会话恢复       │
│              │ CI/CD 流水线     │                         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 学习成本      │ 低（就是命令行） │ 中（需要了解异步迭代器） │
├──────────────┼─────────────────┼─────────────────────────┤
│ 灵活度        │ 中              │ 高（完全编程控制）       │
├──────────────┼─────────────────┼─────────────────────────┤
│ 输出控制      │ text/json/      │ 逐条消息流式处理         │
│              │ stream-json     │ 完整的类型系统           │
├──────────────┼─────────────────┼─────────────────────────┤
│ 多轮对话      │ 不支持          │ 支持（会话管理）         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 自定义工具    │ 不支持          │ 支持（MCP 集成）         │
├──────────────┼─────────────────┼─────────────────────────┤
│ 推荐起步场景  │ PR 审查脚本     │ 文档生成器               │
│              │ Changelog 生成  │ 代码质量仪表盘           │
│              │ 批量格式检查    │ 自定义 AI 开发工具       │
└──────────────┴─────────────────┴─────────────────────────┘

选择建议：
• 能用 Headless 解决的 → 用 Headless（简单就是好）
• Headless 不够用了 → 上 Agent SDK
• 两者可以混用——Shell 脚本调 claude -p，复杂逻辑用 SDK

六、安全和成本：两条铁律

把 Claude Code 接入自动化流程，意味着它可能在没人看着的情况下运行。所以安全和成本控制比交互模式更重要。

铁律一：自动化场景永远限制权限

code
┌──────────────────────────────────────────────────────────┐
│          自动化场景的权限策略                                │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  只读任务（审查、分析、文档生成）：                         │
│  --allowedTools Read,Grep,Glob                           │
│                                                          │
│  写入任务（代码生成、重构）：                               │
│  --allowedTools Read,Write,Edit,Grep,Glob                │
│  ⚠️ 必须有 Git 版本控制，方便回滚                         │
│                                                          │
│  执行任务（运行测试、构建）：                               │
│  --allowedTools Read,Bash,Grep,Glob                      │
│  ⚠️ 搭配 PreToolUse Hook 拦截危险命令                    │
│                                                          │
│  永远不要：                                                │
│  ❌ permissionMode: "bypassPermissions"                  │
│     + allowedTools 不限制                                 │
│  ❌ 在没有版本控制的目录里运行写入任务                     │
│  ❌ 给自动化脚本访问生产数据库的权限                      │
│                                                          │
└──────────────────────────────────────────────────────────┘

铁律二：用 --max-turns 控制成本

每一轮 Agent 循环都消耗 Token。一个失控的任务可能在你不知情的情况下烧掉大量费用。

bash
# ❌ 危险：不限制轮次
claude -p "重构整个项目的类型系统"

# ✅ 安全：限制 5 轮
claude -p "重构整个项目的类型系统" --max-turns 5

经验值：简单审查 1-2 轮，文档生成 2-3 轮，复杂重构 5-8 轮。超过 10 轮的任务建议拆分成多个小任务。

本篇小结

三个核心收获：

第一，Headless 模式（claude -p）让 Claude Code 变成一个可以嵌入任何脚本和流水线的命令行工具。三种输出格式（text/json/stream-json）覆盖了从人类阅读到程序解析的所有需求。--max-turns 和 --allowedTools 是自动化场景的两个必设参数。

第二，Agent SDK（@anthropic-ai/claude-agent-sdk）提供了完整的编程接口。核心函数 query() 返回异步迭代器，你可以逐条消息处理 Claude 的输出。TypeScript 和 Python 两个版本 API 几乎一致，选你项目的主语言就行。

第三，从"对话驱动"到"代码驱动"是一次质变。你可以构建自己的 AI 开发工具——文档生成器、代码质量仪表盘、自动化审查系统——Claude Code 变成了你工具箱里的一个可编程组件。

通关检查清单

用 claude -p 成功执行过一次 Headless 模式
理解三种输出格式的适用场景（text / json / stream-json）
写过一个包含 claude -p 的 Shell 脚本
安装了 @anthropic-ai/claude-agent-sdk
用 query() 函数成功执行过一次 SDK 调用
理解 permissionMode、allowedTools、maxTurns 的作用
理解自动化场景的安全原则（限制权限 + 限制轮次）

全部打勾？Level 4 第一关通过。

下篇预告

第 9 篇：Claude Code 通关手册（九）—— GitHub Actions 实战：让 AI 住进你的 CI/CD

Headless 模式和 SDK 给了你"代码驱动 AI"的能力。但这些脚本目前还是在你本地运行的。

下一篇，我们把它搬到云端——在 GitHub Actions 里运行 Claude Code。每次有人提 PR，自动触发 AI 代码审查；每次合并到 main，自动生成 Changelog 和文档更新。CI/CD 流水线里住进一个 AI 工程师，7×24 全年无休。

今日话题

如果你能用代码驱动 Claude Code 构建一个工具，你会构建什么？自动文档生成？代码质量仪表盘？还是一个能自动修 Bug 的机器人？评论区分享你的想法——最有创意的那个，我可能会在后续文章里实现它。

如果这篇文章让你意识到 Claude Code 不只是"聊天工具"，欢迎点赞、在看、转发三连——帮更多开发者看到 AI 自动化的可能性。

关注「前端达人」，Level 4 继续推进，我们下篇见。

如果这篇对你有帮助，欢迎关注公众号「前端达人」，每周更新实用前端干货。

Claude Code 通关手册（八）：你还在跟 AI 聊天？高手早就用代码驱动了