如果说 Claude Code CLI 像是一把瑞士军刀，让开发者在终端中快速解决问题，那么 Claude Code SDK 则是工业级的机器人手臂——它允许将 Claude 的自主编程能力 嵌入到任何应用程序或工作流 中，实现真正的编程自动化。
本节将详细介绍如何使用 Python 和 TypeScript SDK 来构建定制化的 AI 编程工具。
在深入 SDK 之前，先厘清它与 CLI 的关系：
| 维度 | Claude Code CLI | Claude Code SDK |
|---|---|---|
| 使用方式 | 终端交互，人在回路 | 程序化调用，可全自动 |
| 适用场景 | 日常开发辅助 | CI/CD、IDE 插件、自动化平台 |
| 输出控制 | 实时输出到终端 | 返回结构化对象，可编程处理 |
| 并发能力 | 单任务 | 可并行运行多实例 |
核心价值：SDK 将 Claude Code 从“个人开发助手”升级为“可扩展的编程基础设施”。
pip install claude-agent-sdk注意：早期版本使用
claude-code-sdk包名，该包已弃用。请使用claude-agent-sdk，它提供与 Claude Code 相同的工具、Agent 循环和上下文管理能力。
SDK 会自动从环境变量读取 API Key：
export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"不要把真实 API Key 写入可复用脚本、仓库文件或会被长期保留的命令历史。
npm install @anthropic-ai/claude-agent-sdk
# 或
yarn add @anthropic-ai/claude-agent-sdkimport asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# 使用异步流式 API 执行编程任务
async for event in query(
prompt="将项目中所有的 var 声明改为 const 或 let，并修复 ESLint 错误",
options=ClaudeAgentOptions(
model="claude-sonnet-4-6", # 指定模型版本
allowed_tools=["Read", "Edit", "Bash"], # 允许的工具
cwd="/path/to/project", # 工作目录
max_turns=20 # 最大对话轮次
),
):
# 生产日志不要直接输出完整 event，避免泄露 prompt、工具参数或文件片段
print({"type": getattr(event, "type", None)})
asyncio.run(main())import { query } from "@anthropic-ai/claude-agent-sdk";
async function generateTests(filePath: string) {
const events = [];
for await (const event of query({
prompt: `为 ${filePath} 中的所有公共函数生成单元测试，使用 Jest 框架`,
options: {
model: "claude-sonnet-4-6",
cwd: process.cwd(),
allowedTools: ["Read", "Edit", "Bash"],
maxTurns: 15,
},
})) {
events.push(event);
// 生产日志不要直接输出完整 event，避免泄露 prompt、工具参数或文件片段
console.log({ type: event.type });
}
return events;
}
// 使用示例
generateTests("./src/utils/parser.ts").then((events) => {
console.log({ eventCount: events.length });
});SDK 的安全模型基于 显式授权。必须明确指定 Claude 可以使用哪些工具：
| 工具名 | 功能 | 风险等级 |
|---|---|---|
Read |
读取文件内容 | 🟢 低 |
Edit |
写入/修改文件（首选；如需整文件覆写用 Write） |
🟡 中 |
Glob |
列出/匹配目录结构 | 🟢 低 |
Bash |
执行终端命令 | 🔴 高 |
Grep |
语义搜索代码库 | 🟢 低 |
最佳实践：遵循 最小权限原则。如果任务只需要读取和分析代码，就不要授予 Edit/Write 或 Bash 权限。
在 GitHub Actions 中集成 Claude Code，自动审查每个 PR：
# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
pip install claude-agent-sdk
python scripts/ai_review.py --pr ${{ github.event.pull_request.number }}将 SDK 集成到 IDE 插件中，提供“一键修复”功能：
// VS Code Extension 示例
vscode.commands.registerCommand('claude.fixIssue', async () => {
const editor = vscode.window.activeTextEditor;
const diagnostics = vscode.languages.getDiagnostics(editor.document.uri);
const events = [];
for await (const event of query({
prompt: `修复以下问题：${diagnostics.map(d => d.message).join(', ')}`,
options: {
cwd: vscode.workspace.rootPath,
allowedTools: ['Read', 'Edit'],
},
})) {
events.push(event);
}
if (events.length > 0) {
vscode.window.showInformationMessage('问题已修复！');
}
});将遗留代码库从 Python 2 迁移到 Python 3：
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions
async def migrate_file(filepath: str):
async for event in query(
prompt=f"将 {filepath} 从 Python 2 迁移到 Python 3，保持功能不变",
options=ClaudeAgentOptions(
cwd="./legacy_project",
allowed_tools=["Read", "Edit"],
),
):
print(event)
async def main():
for root, dirs, files in os.walk("./legacy_project"):
for file in files:
if file.endswith(".py"):
await migrate_file(os.path.join(root, file))
asyncio.run(main())健壮的 SDK 集成需要处理各种边缘情况：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
try:
async for event in query(
prompt="...",
options=ClaudeAgentOptions(cwd=".", allowed_tools=["Read"]),
):
print(event)
except Exception as e:
print(f"SDK 调用失败：{e}")
asyncio.run(main())掌握了 SDK，你已经能够构建自己的编程自动化平台。但大多数开发者的日常工作并不在命令行或脚本中，而是在 IDE 里。
接下来，将展示 Claude 如何在最熟悉的编辑器中大显身手。
➡️ IDE 集成与工作流