Claude Code 评测：Headless+Agent SDK 自主工作

Claude Code 不只会聊天：Headless 模式 + Agent SDK，让它自动运转

一个核心困境

坦白说，直到现在，你和 Claude Code 的协作模式本质仍是“对话”——你在终端输入，它响应。你说“检查这个文件”，它检查。你说“创建个组件”，它创建。

这种方式直观，但有一个致命限制：你必须一直守在终端前。

• 它无法在凌晨 2 点自动扫描代码库，并将质量报告推送至钉钉群。
• 它无法在每次有人提交 PR 时，悄然执行一轮代码审查。
• 它也无法一次性批量处理 100 个文件的文档生成任务。

换句话说，你是驾驶员，它只是副驾。那么，如何打破这种束缚？Claude Code 提供了两种“脱离终端”的路径：Headless 模式和 Agent SDK。

一、Headless 模式——一条命令，Claude 自主执行

实现起来并不复杂。最直接的方法，就是通过命令行向 Claude 发送一条指令：

claude -p "分析 src/app/page.tsx 的性能瓶颈"

无需交互界面，不用你在旁等待，执行完毕直接输出结果。

三种输出格式

# 纯文本——便于人工阅读claude -p "列出项目中所有 TODO 标记" --output-format text# JSON——方便程序解析输出claude -p "列出项目中所有 TODO 标记" --output-format json# Stream JSON——逐条流式返回，适合实时处理claude -p "重构 ArticleList 组件" --output-format stream-json

关键参数一览

实战：批量审核近期修改的文件

#!/bin/bash# review-recent.shfor file in $(git diff --name-only HEAD~5 -- '*.ts' '*.tsx'); doecho "???? 正在审查: $file"claude -p "审查 $file 的代码质量，重点关注类型安全与性能隐患" --output-format json --max-turns 2 --allowedTools Read,Grep,Globdone

另一个实用场景：自动生成改动日志

git log --oneline origin/main...HEAD | claude -p "根据这些提交记录生成更新日志，分类为：✨新功能 / ????Bug修复 / ⚡优化 / ????文档" --output-format text --max-turns 1 > CHANGELOG.md

看到了吗？一行命令，一份清晰的更新日志即刻生成。将其挂载到 CI 中，每次发布前自动产出，省时省力。

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

先说明一点：Claude Code SDK 现已正式更名为 Claude Agent SDK，包名从 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-agent-sdk。

安装

# TypeScriptnpm install @anthropic-ai/claude-agent-sdk# Pythonpip install claude-agent-sdk

核心只有一个函数：query()

query() 接收一个 prompt，返回一个异步迭代器。你可以逐条处理 Claude 的输出：

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 会自动调用工具（读取文件、执行命令、搜索代码），观察反馈，决定下一步行动，直至任务结束。你的代码只需消费这个流即可。

关键配置项

const result = query({prompt: "审查 src/app/api/ 下的所有 API 路由",options: {model: "sonnet",permissionMode: "bypassPermissions",// CI 环境自动跳过权限确认allowedTools: ["Read", "Grep", "Glob"],// 限定可用工具maxTurns: 5,// 最大执行轮次systemPrompt: "你是一名严格的代码审查专家...",// 自定义系统提示词settingSources: ["project"],// 加载项目级配置}});

几个要点梳理如下：

• permissionMode：CI/CD 环境使用 bypassPermissions（无人值守场景）；本地开发使用 acceptEdits（自动同意编辑）
• settingSources：默认为空数组，SDK 模式下一切由代码掌控；若要复用项目配置和 Hooks，设为 ["project"]
• allowedTools：安全的第一道防线——审查任务仅给 Read，生成任务可给 Read + Write

实战：批量组件文档生成器

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 = "./src/components";const OUTPUT_DIR = "./docs/components";async function generateDoc(filePath: string) {const name = path.basename(filePath, ".tsx");let docContent = "";for await (const msg of query({prompt: `阅读 ${filePath}，生成 Markdown 格式的组件文档，包含：概述、Props 表格、使用示例、注意事项。输出纯 Markdown。`,options: {model: "sonnet",allowedTools: ["Read", "Grep", "Glob"],maxTurns: 3,permissionMode: "bypassPermissions",},})) {if (msg.type === "result") docContent = msg.result;}return docContent;}async function main() {const files = await glob(`${COMPONENTS_DIR}/**/*.tsx`, {ignore: ["**/*.test.tsx"],});fs.mkdirSync(OUTPUT_DIR, { recursive: true });for (const file of files) {const name = path.basename(file, ".tsx");console.log(`???? 正在处理: ${name}`);try {const doc = await generateDoc(file);fs.writeFileSync(path.join(OUTPUT_DIR, `${name}.md`), doc, "utf-8");console.log("✅ 完成");} catch (err) {console.error("❌ 失败:", err);}}}main();

运行效果如下：

???? 正在处理: ArticleCard✅ 完成???? 正在处理: ArticleList✅ 完成???? 正在处理: Header✅ 完成???? 文档生成完成

你可以把这个脚本挂载到 Git hook 上——一旦组件文件有变更，文档就会自动更新。

为什么这样设计？逻辑很清楚：

• maxTurns: 3：读取文件（1轮）→ grep 引用（1轮）→ 生成输出（1轮），3 轮足够
• 只给 Read/Grep/Glob：文档生成器只需“读取”代码，无需“修改”代码
• 逐个处理而非并行：每个 query() 都会启动一个完整的 Agent 进程，并行过多会消耗大量资源和 Token

三、如何选择？

选择建议非常直接：

• 能用 Headless 解决的，就用 Headless。简单即高效。
• Headless 不够用时，再升级到 Agent SDK。
• 两者完全可以混合使用——Shell 脚本调用 claude -p，复杂逻辑使用 SDK。

四、两条铁律：安全与成本

将 Claude Code 接入自动化流程，就必须正视一个现实：它可能在无人值守的情况下运行。因此，安全和成本的控制优先级需要高于交互模式。

铁律一：按任务类型限制工具

永远不要做的事：

• ❌ bypassPermissions 搭配不限制 allowedTools
• ❌ 在没有版本控制的目录中运行写入任务
• ❌ 给自动化脚本授予生产数据库的访问权限

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

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

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

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

总结

三个核心要点：

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

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

3. 从对话驱动到代码驱动，是一次质变。 你可以构建自己的 AI 开发工具——文档生成器、代码质量看板、自动化审查系统——Claude Code 成为你工具箱中一个可编程的组件。

不再是“你问它答”，而是“你定规则，它自主运行”。

这才是 AI 编程助手的正确用法。