Claude Code SDK：开发者构建智能体指南

Claude Code SDK 将 Claude Code 从交互式编程助手升级为完全可编程的智能体运行时。如果你一直在交互式地使用 Claude Code，SDK 将为你开启一套全新的可能性——自动化流水线、自定义 UI、多智能体编排以及 CI/CD 集成。

什么是 Claude Code SDK？

Claude Code SDK 是一个编程接口，让你能够：

• 从脚本和流水线中以非交互方式运行 Claude Code
• 控制上下文中包含的文件、目录和工具
• 解析结构化输出以供下游处理
• 在自动化工作流中将 Claude Code 与其他工具串联
• 在 Claude Code 的推理能力之上构建自定义 UI

以 Node.js 包的形式提供：

npm install @anthropic-ai/claude-code

或通过 CLI 以非交互模式调用：

claude -p "你的提示词" --output-format json

SDK 核心概念

非交互模式

最基础的 SDK 用法：传入提示词，运行 Claude Code，获取输出，完成。

# CLI 非交互模式
claude -p "检查 src/auth.ts 中的安全漏洞" \
  --output-format json \
  --max-turns 5

// SDK
const { query } = require('@anthropic-ai/claude-code');

const result = await query({
  prompt: "检查 src/auth.ts 中的安全漏洞",
  options: {
    maxTurns: 5,
    outputFormat: 'json'
  }
});

工具配置

控制 SDK 调用中 Claude Code 可访问的工具：

const result = await query({
  prompt: "为 src/utils.ts 生成测试套件",
  options: {
    allowedTools: ['Read', 'Write', 'Bash'],
    // 禁用不需要的工具：
    // disallowedTools: ['WebSearch', 'mcp__custom_tool']
  }
});

自定义系统提示词

覆盖 Claude Code 默认系统提示词，实现专属行为：

const result = await query({
  prompt: "重构这个模块",
  options: {
    systemPrompt: `你是一位专注于函数式编程模式的 TypeScript 专家。
    始终优先使用不可变数据结构。使用 Result 类型处理错误。
    绝不使用 any 或 unknown 类型。`,
  }
});

实用 SDK 模式

1. CI 中的自动化代码审查

// .github/workflows/code-review.js
const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

const diff = execSync('git diff main...HEAD').toString();

const review = await query({
  prompt: `审查这个 PR diff，关注：安全问题、性能问题和缺失的测试。
  以 JSON 格式输出，包含以下键：security[]、performance[]、testing[]。
  
  Diff：
  ${diff}`,
  options: {
    outputFormat: 'json',
    allowedTools: ['Read'],  // CI 中仅读取
    maxTurns: 3
  }
});

console.log(JSON.parse(review.result));

2. 自动化文档生成

const fs = require('fs');
const { query } = require('@anthropic-ai/claude-code');

async function generateDocs(srcPath) {
  const result = await query({
    prompt: `为 ${srcPath} 中所有导出函数生成完整的 JSDoc 文档。
    添加参数说明、返回类型和使用示例。
    写入更新后的文件，包含所有文档注释。`,
    options: {
      allowedTools: ['Read', 'Write'],
      cwd: process.cwd()
    }
  });
  return result;
}

3. 结合外部能力的多智能体流水线

这正是 AnyCap 集成展现威力的地方。在这条流水线中，Claude Code 负责代码推理，AnyCap 负责媒体生成和发布：

const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

async function buildAndPublishDocs(repoPath) {
  // 第一步：Claude Code 生成文档
  const docsResult = await query({
    prompt: "为该项目生成完整的 README，包含安装说明、API 参考和示例",
    options: {
      cwd: repoPath,
      allowedTools: ['Read', 'Write', 'Bash']
    }
  });

  // 第二步：AnyCap 生成封面图
  execSync(`anycap image generate \
    --prompt "开发者工具的技术架构图，简洁极简风格" \
    --model nano-banana-2 \
    -o ${repoPath}/docs/architecture.png`);

  // 第三步：AnyCap 发布为网页
  const pageResult = execSync(`anycap page deploy ${repoPath}/docs/`).toString();
  
  return { docs: docsResult, page: JSON.parse(pageResult) };
}

SDK 身份验证

SDK 使用与 Claude Code 相同的身份验证方式。设置 API 密钥：

export ANTHROPIC_API_KEY=你的密钥

或在团队环境中使用特定环境配置：

const { query } = require('@anthropic-ai/claude-code');

// SDK 自动读取 ANTHROPIC_API_KEY
// 或显式传入：
process.env.ANTHROPIC_API_KEY = await getSecretFromVault('anthropic-api-key');

输出格式

SDK 支持三种输出格式：

// JSON 输出包含元数据
{
  "result": "该函数存在潜在的 SQL 注入漏洞...",
  "is_error": false,
  "session_id": "sess_xxxx",
  "cost_usd": 0.0043,
  "num_turns": 2
}

SDK 工作流中的速率限制与费用管理

基于 SDK 的自动化比交互式使用消耗 token 的速度更快。内置限制措施：

const result = await query({
  prompt: "...",
  options: {
    maxTurns: 5,        // 限制推理迭代次数
    timeoutMs: 30000,   // 长时间任务的超时设置
  }
});

// 生产环境中务必检查费用
if (result.cost_usd > 0.10) {
  logger.warn(`高费用会话：$${result.cost_usd}`);
}

对于能力密集型任务（图像生成、视频创建、网络搜索），建议卸载给 AnyCap，而不是让 Claude Code 在上下文中处理。这样可以保持 SDK 费用的可预测性，并避免在非推理任务上触碰 Claude 的速率限制。

快速开始

# 安装 SDK
npm install @anthropic-ai/claude-code

# 安装 AnyCap 以扩展功能
curl -fsSL https://anycap.ai/install.sh | sh

# 将 AnyCap 技能添加到 Claude Code
npx -y skills add anycap-ai/anycap -y

→ 适用于 Claude Code 的 AnyCap → 为 Claude Code 添加工具指南