第十节

Claude Code SDK

以编程方式在应用和脚本中运行 Claude Code

Claude Code SDK 让你能够从自己的应用程序和脚本中以编程方式运行 Claude Code。它适用于 TypeScript、Python 和 CLI，为你提供与终端版本相同的 Claude Code 功能， 但集成到更大的工作流中。

核心特性

SDK 运行的 Claude Code 与你熟悉的完全相同。 它可以访问所有相同的工具，并使用它们来完成你给定的任何任务。这使得它在自动化和集成场景中特别强大。

以编程方式运行

从代码中调用 Claude Code

相同功能

与终端版本功能一致

继承设置

继承目录中 Claude Code 实例的所有设置

只读权限

默认只读，更安全的权限控制

集成友好

最适合作为大型管道或工具的一部分

多语言支持

TypeScript、Python 和 CLI

基础用法

这是一个简单的 TypeScript 示例，要求 Claude 分析代码以查找重复查询：

import { query } from "@anthropic-ai/claude-code";

const prompt = "Look for duplicate queries in the ./src/queries dir";

for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

输出说明：当你运行这段代码时，你会看到本地 Claude Code 和 Claude 语言模型之间的原始对话， 逐条消息显示。最后一条消息包含 Claude 的完整响应。

权限和工具

默认情况下，SDK 只有只读权限。它可以读取文件、搜索目录和执行 grep 操作， 但不能写入、编辑或创建文件。

默认允许

  • • 读取文件
  • • 搜索目录
  • • Grep 操作

默认阻止

  • • 写入文件
  • • 编辑文件
  • • 创建文件

启用写入权限

要启用写入权限，你可以向查询添加 allowedTools 选项：

for await (const message of query({
  prompt,
  options: {
    allowedTools: ["Edit"]
  }
})) {
  console.log(JSON.stringify(message, null, 2));
}

替代方案：或者，你可以在 .claude 目录内的设置文件中配置权限，以实现项目级别的访问。

实战示例

让我们看一个实际的例子，演示如何使用 SDK：

步骤演示：

1
在项目根目录找到 SDK.ts 文件
2
更新顶部的 prompt，要求 Claude 查找重复查询
3
保存文件并在终端执行 npm run sdk
4
查看 Claude Code 和 Claude 语言模型之间的原始对话
5
最后一条消息包含 Claude 的最终响应

允许编辑工具

要让 SDK 能够编辑文件，在 prompt 参数后添加 options：

import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Add a description to package.json",
  options: {
    allowedTools: ["Edit"]
  }
})) {
  console.log(JSON.stringify(message, null, 2));
}

运行后，打开 package.json 文件，你会看到描述已被添加。

实际应用场景

Claude Code SDK 在集成到更大的开发工作流时大放异彩。考虑在以下场景中使用它：

Git hooks

自动审查代码更改

构建脚本

分析和优化代码

辅助命令

代码维护任务

文档生成

自动生成文档

CI/CD 管道

代码质量检查

自定义工具

为工作流添加 AI 智能

核心价值：SDK 本质上让你能够将 AI 驱动的智能添加到开发过程的任何部分， 在这些地方编程访问会很有价值。特别适合在 hooks、辅助命令和脚本中使用。

最佳实践

从只读开始

默认只读权限更安全，仅在需要时启用写入

明确提示词

提供清晰具体的任务描述

处理输出

正确解析和处理返回的消息

错误处理

实现适当的错误处理和重试逻辑

权限最小化

只授予任务所需的最小工具集

集成到工作流

作为更大自动化流程的一部分使用

使用建议：SDK 最适合作为其他工具的一部分使用。考虑在 helper 命令、脚本或 最值得注意的是在你自己项目中的 hooks 里使用它。