7.3 Claude Code SDK 集成

如果说 Claude Code CLI 像是一把瑞士军刀，让开发者在终端中快速解决问题，那么 Claude Code SDK 则是工业级的机器人手臂——它允许将 Claude 的自主编程能力嵌入到任何应用程序或工作流中，实现真正的编程自动化。

本节将详细介绍如何使用 Python 和 TypeScript SDK 来构建定制化的 AI 编程工具。

7.3.1 SDK 与 CLI 的区别

在深入 SDK 之前，先厘清它与 CLI 的关系：

维度	Claude Code CLI	Claude Code SDK
使用方式	终端交互，人在回路	程序化调用，可全自动
适用场景	日常开发辅助	CI/CD、IDE 插件、自动化平台
输出控制	实时输出到终端	返回结构化对象，可编程处理
并发能力	单任务	可并行运行多实例

核心价值：SDK 将 Claude Code 从"个人开发助手"升级为"可扩展的编程基础设施"。

7.3.2 安装与配置

Python SDK

pip install anthropic-claude-code

SDK 会自动从环境变量读取 API Key：

export ANTHROPIC_API_KEY="sk-ant-..."

TypeScript/Node.js SDK

npm install @anthropic-ai/claude-code-sdk
# 或
yarn add @anthropic-ai/claude-code-sdk

7.3.3 核心 API 详解

Python 示例：自动化代码重构

from anthropic_claude_code import ClaudeCode

# 初始化客户端
claude = ClaudeCode(
    api_key="sk-ant-...",  # 可选，也可从环境变量读取
    model="claude-4-5-sonnet-20250929"  # 指定模型版本
)

# 执行编程任务
result = claude.run(
    task="将项目中所有的 var 声明改为 const 或 let，并修复 ESLint 错误",
    working_directory="/path/to/project",
    allowed_tools=["read_file", "write_file", "list_files", "run_command"],
    max_iterations=20,  # 最大迭代次数
    timeout=300  # 超时时间（秒）
)

# 处理结果
if result.success:
    print(f"任务完成！共修改 {len(result.modified_files)} 个文件")
    for file in result.modified_files:
        print(f"  - {file}")
else:
    print(f"任务失败：{result.error}")

TypeScript 示例：智能测试生成

import { ClaudeCode, ToolPermission } from '@anthropic-ai/claude-code-sdk';

const claude = new ClaudeCode({
  model: 'claude-4-5-sonnet-20250929',
});

async function generateTests(filePath: string) {
  const result = await claude.run({
    task: `为 ${filePath} 中的所有公共函数生成单元测试，使用 Jest 框架`,
    workingDirectory: process.cwd(),
    allowedTools: [
      ToolPermission.READ_FILE,
      ToolPermission.WRITE_FILE,
      ToolPermission.RUN_COMMAND,
    ],
    maxIterations: 15,
    onProgress: (event) => {
      // 实时监控进度
      console.log(`[${event.type}] ${event.message}`);
    },
  });

  return result;
}

// 使用示例
generateTests('./src/utils/parser.ts').then(console.log);

7.3.4 权限控制：allowed_tools 详解

SDK 的安全模型基于显式授权。必须明确指定 Claude 可以使用哪些工具：

工具名	功能	风险等级
read_file	读取文件内容	🟢 低
write_file	写入/修改文件	🟡 中
list_files	列出目录结构	🟢 低
run_command	执行终端命令	🔴 高
search_code	语义搜索代码库	🟢 低

最佳实践：遵循最小权限原则。如果任务只需要读取和分析代码，就不要授予 write_file 或 run_command 权限。

7.3.5 企业级集成场景

场景一：CI/CD 自动代码审查

在 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 anthropic-claude-code
          python scripts/ai_review.py --pr ${{ github.event.pull_request.number }}

场景二：VS Code 插件后端

将 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 result = await claude.run({
    task: `修复以下问题：${diagnostics.map(d => d.message).join(', ')}`,
    workingDirectory: vscode.workspace.rootPath,
    allowedTools: ['read_file', 'write_file'],
  });
  
  if (result.success) {
    vscode.window.showInformationMessage('问题已修复！');
  }
});

场景三：批量代码迁移

将遗留代码库从 Python 2 迁移到 Python 3：

import os
from anthropic_claude_code import ClaudeCode

claude = ClaudeCode()

for root, dirs, files in os.walk("./legacy_project"):
    for file in files:
        if file.endswith(".py"):
            filepath = os.path.join(root, file)
            result = claude.run(
                task=f"将 {filepath} 从 Python 2 迁移到 Python 3，保持功能不变",
                working_directory="./legacy_project",
                allowed_tools=["read_file", "write_file"],
            )
            print(f"{'✓' if result.success else '✗'} {filepath}")

7.3.6 错误处理与重试

健壮的 SDK 集成需要处理各种边缘情况：

from anthropic_claude_code import ClaudeCode, ClaudeCodeError, RateLimitError

claude = ClaudeCode()

try:
    result = claude.run(task="...", working_directory=".", allowed_tools=["read_file"])
except RateLimitError:
    print("触发速率限制，请稍后重试")
except ClaudeCodeError as e:
    print(f"SDK 错误：{e.message}")

---

掌握了 SDK，你已经能够构建自己的编程自动化平台。但大多数开发者的日常工作并不在命令行或脚本中，而是在 IDE 里。

接下来，将展示 Claude 如何在最熟悉的编辑器中大显身手。

➡️ IDE 集成与工作流