无头模式：使用 Python 和 TypeScript SDK 进行自动化

走向无头：使用 Python 和 TypeScript SDK 实现自动化

尽管 Claude Code 的交互式 CLI 是一个强大的结对编程工具，但当您以编程方式利用其功能时，它真正的潜力才能被释放。适用于 Python 和 TypeScript 的 Claude Code SDK 允许您进入“无头模式”——将其推理引擎直接集成到您自己的脚本、后端服务和 CI/CD 流水线中，无需任何用户界面。

无头模式：自动化的引擎

“无头模式”简单来说，就是以非交互方式运行 Claude Code，其中输入由程序提供，输出被捕获供另一个程序使用。这是自动化的基础。脚本发送提示，而不是由人工输入；结果以数据结构的形式返回，供您的应用程序处理，而不是在终端中显示。

无头自动化常见的用例包括：

CI/CD 流水线：为每次拉取请求（pull request）自动生成文档、运行代码审查或提出优化建议。
自定义开发工具：构建您自己的命令行工具，利用 Claude Code 完成项目特定任务，例如搭建（scaffolding）新的微服务或迁移旧代码。
后端服务：将 Claude Code 集成到更大的应用程序中，以提供智能功能，例如可以诊断和报告生产问题的机器人。

最简单的无头模式形式是使用带有 --print (-p) 标志的 CLI。SDK 提供了更强大、更灵活的接口来实现这些相同的功能。

Python SDK 指南

Python SDK 非常适合后端开发、数据科学工作流和脚本编写。它允许您使用熟悉的 Python 语法与 Claude Code 交互。

1. 安装

# 首先确保您已安装 Claude Code
# 然后，安装 Python SDK
pip install claude-code

2. 实际示例

让我们编写一个简单的 Python 脚本，使用 SDK 为 Git 仓库中当前暂存的更改生成提交信息。这是一个经典的无头自动化任务。

import subprocess
from claude_code import claude_code

def generate_commit_message():
    """使用 Claude Code 为暂存的更改生成提交信息。"""
    try:
        # 获取暂存的 Git diff
        diff = subprocess.check_output(['git', 'diff', '--cached']).decode('utf-8')

        if not diff:
            print("没有暂存的更改可提交。")
            return

        prompt = f"""根据以下 Git diff，请撰写一条简洁且符合规范的提交信息。

{diff}
"""

        # 使用 SDK 从 Claude Code 获取响应
        # run_headless 方法是 SDK 无头模式的核心
        response = claude_code.run_headless(prompt)

        commit_message = response.result
        print("建议的提交信息：")
        print("------------------------")
        print(commit_message)

        # 您可以扩展此功能以自动使用此信息进行提交
        # subprocess.run(['git', 'commit', '-m', commit_message])

    except subprocess.CalledProcessError:
        print("错误：不是 Git 仓库或没有暂存的更改。")
    except Exception as e:
        print(f"发生错误：{e}")

if __name__ == "__main__":
    generate_commit_message()

TypeScript SDK 指南

对于 Node.js 后端、JavaScript 生态系统中的自定义工具或 Web 应用程序，TypeScript SDK 提供了一种健壮且类型安全的方式来集成 Claude Code。

1. 安装

# 首先确保您已安装 Claude Code
# 然后，在您的 Node.js 项目中安装 TypeScript SDK
npm install @anthropic-ai/claude-code

2. 实际示例

让我们创建一个 TypeScript 工具，它读取一个源代码文件，并请求 Claude Code 为其添加解释性注释。此脚本演示了如何读取文件并请求有针对性的编辑。

import * as fs from 'fs/promises';
import { claudeCode } from '@anthropic-ai/claude-code';

async function addCommentsToFile(filePath: string): Promise<void> {
  try {
    const fileContent = await fs.readFile(filePath, 'utf-8');

    const prompt = `Please add clear and concise comments to the following code to explain its functionality. Return only the fully commented code block.

${fileContent}

`;

    // runHeadless 方法是异步的，并返回一个 Promise
    console.log('正在请求 Claude Code 添加注释...');
    const response = await claudeCode.runHeadless(prompt);

    const commentedCode = response.result;

    const newFilePath = `${filePath}.commented.ts`;
    await fs.writeFile(newFilePath, commentedCode);

    console.log(`已成功创建带注释的文件：${newFilePath}`);

  } catch (error) {
    console.error('发生错误：', error);
  }
}

// 从命令行参数获取文件路径
const filePath = process.argv[2];
if (!filePath) {
  console.error('请提供文件路径作为参数。');
  process.exit(1);
}

addCommentsToFile(filePath);

要运行此脚本，您需要将其保存为 commenter.ts，编译它（tsc commenter.ts），然后使用 Node.js 运行它：node commenter.js ./path/to/your/file.ts。这个无头脚本执行了一个有用的自动化任务，展示了将 Claude Code 直接集成到您的开发工具中的强大能力。