Claude Code CLI 代码集成完整攻略

概述

本攻略提供了在Node.js应用中直接调用Claude Code CLI的完整解决方案，基于对Claude Code Base Action的深度分析，提取了所有核心技术要点。

为什么需要直接调用

灵活性: 在任何Node.js环境中使用，不限于GitHub Actions
集成性: 可以整合到现有的应用程序和工作流中
可控性: 完全控制执行参数、输出处理和错误处理
扩展性: 可以根据需求自定义功能和输出格式

前置准备

1. 环境要求

2. Node.js依赖

{
  "dependencies": {
    "@types/node": "^20.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

3. 系统要求

Unix/Linux/macOS (支持mkfifo命令)
Node.js 18+
已安装jq命令行工具 (用于JSON处理)

核心实现

关键技术要点

工作目录管理: Claude必须在正确的项目目录下运行
Named Pipes通信: 使用命名管道避免stdin/stdout复杂性
流式输出处理: 实时解析结构化JSON输出
进程生命周期管理: 超时控制和优雅终止
错误处理和资源清理: 确保系统稳定性

接口设计

export interface ClaudeExecutionOptions {
  prompt: string;                    // 执行的prompt
  model?: string;                    // 模型名称
  maxTurns?: number;                 // 最大对话轮数
  allowedTools?: string[];           // 允许的工具列表
  disallowedTools?: string[];        // 禁用的工具列表
  systemPrompt?: string;             // 系统提示词
  appendSystemPrompt?: string;       // 追加系统提示词
  mcpConfig?: string;                // MCP配置路径
  timeoutMinutes?: number;           // 超时时间(分钟)
  outputFile?: string;               // 输出文件路径
  workingDirectory?: string;         // 工作目录(关键!)
}

export interface ClaudeExecutionResult {
  success: boolean;                  // 执行是否成功
  exitCode: number;                  // 退出代码
  output: string;                    // 原始输出
  executionLog?: any[];              // 结构化执行日志
  outputFile?: string;               // 输出文件路径
}

完整代码

import { spawn, exec } from 'child_process';
import { promisify } from 'util';
import { writeFile, unlink, mkdir } from 'fs/promises';
import { createWriteStream } from 'fs';
import path from 'path';

const execAsync = promisify(exec);

export class ClaudeCodeRunner {
  private tempDir: string;
  
  constructor(tempDir: string = '/tmp/claude-runner') {
    this.tempDir = tempDir;
  }

  /**
   * 执行Claude Code命令
   */
  async runClaude(options: ClaudeExecutionOptions): Promise<ClaudeExecutionResult> {
    // 保存原始工作目录
    const originalCwd = process.cwd();
    
    try {
      // 1. 切换到指定工作目录(关键步骤!)
      if (options.workingDirectory) {
        console.log(`🔄 Changing to working directory: ${options.workingDirectory}`);
        process.chdir(options.workingDirectory);
      }
      
      // 2. 确保临时目录存在
      await mkdir(this.tempDir, { recursive: true });
      
      const promptPath = path.join(this.tempDir, `prompt-${Date.now()}.txt`);
      const pipePath = path.join(this.tempDir, `claude_pipe-${Date.now()}`);
      const outputFile = options.outputFile || 
        path.join(this.tempDir, `claude-output-${Date.now()}.json`);
      
      try {
        // 3. 准备prompt文件
        await writeFile(promptPath, options.prompt);
        console.log(`📝 Prompt written to: ${promptPath}`);
        
        // 4. 创建命名管道
        await this.createNamedPipe(pipePath);
        console.log(`🔗 Named pipe created: ${pipePath}`);
        
        // 5. 构建Claude命令参数
        const claudeArgs = this.buildClaudeArgs(options);
        console.log(`⚙️  Claude args: ${claudeArgs.join(' ')}`);
        
        // 6. 执行Claude进程
        const result = await this.executeClaudeProcess(
          claudeArgs,
          promptPath,
          pipePath,
          outputFile,
          options
        );
        
        return result;
      } finally {
        // 7. 清理临时文件
        await this.cleanup([promptPath, pipePath]);
      }
    } finally {
      // 8. 恢复原始工作目录
      process.chdir(originalCwd);
    }
  }

  /**
   * 创建命名管道
   */
  private async createNamedPipe(pipePath: string): Promise<void> {
    try {
      await unlink(pipePath);
    } catch (e) {
      // 忽略文件不存在的错误
    }
    await execAsync(`mkfifo "${pipePath}"`);
  }

  /**
   * 构建Claude命令行参数
   */
  private buildClaudeArgs(options: ClaudeExecutionOptions): string[] {
    const args = ['-p', '--verbose', '--output-format', 'stream-json'];
    
    if (options.model) {
      args.push('--model', options.model);
    }
    if (options.maxTurns) {
      args.push('--max-turns', options.maxTurns.toString());
    }
    if (options.allowedTools?.length) {
      args.push('--allowedTools', options.allowedTools.join(','));
    }
    if (options.disallowedTools?.length) {
      args.push('--disallowedTools', options.disallowedTools.join(','));
    }
    if (options.systemPrompt) {
      args.push('--system-prompt', options.systemPrompt);
    }
    if (options.appendSystemPrompt) {
      args.push('--append-system-prompt', options.appendSystemPrompt);
    }
    if (options.mcpConfig) {
      args.push('--mcp-config', options.mcpConfig);
    }
    
    return args;
  }

  /**
   * 执行Claude进程
   */
  private async executeClaudeProcess(
    claudeArgs: string[],
    promptPath: string,
    pipePath: string,
    outputFile: string,
    options: ClaudeExecutionOptions
  ): Promise<ClaudeExecutionResult> {
    return new Promise((resolve) => {
      let output = '';
      let resolved = false;
      
      console.log(`🚀 Starting Claude process...`);
      
      // 启动Claude进程 - 继承当前工作目录
      const claudeProcess = spawn('claude', claudeArgs, {
        stdio: ['pipe', 'pipe', 'inherit'],
        // 不需要显式设置cwd，会继承process.cwd()
        env: {
          ...process.env,
          // 可以在这里添加其他环境变量
        }
      });

      // 设置超时
      const timeoutMs = (options.timeoutMinutes || 10) * 60 * 1000;
      const timeoutId = setTimeout(() => {
        if (!resolved) {
          console.error(`⏰ Claude process timed out after ${timeoutMs / 1000} seconds`);
          claudeProcess.kill('SIGTERM');
          setTimeout(() => claudeProcess.kill('SIGKILL'), 5000);
          resolved = true;
          resolve({
            success: false,
            exitCode: 124,
            output,
            outputFile
          });
        }
      }, timeoutMs);

      // 处理输出
      claudeProcess.stdout.on('data', (data) => {
        const text = data.toString();
        output += text;
        
        // 实时输出处理
        this.processStreamOutput(text);
      });

      // 处理进程退出
      claudeProcess.on('close', async (code) => {
        if (!resolved) {
          clearTimeout(timeoutId);
          resolved = true;
          
          console.log(`✅ Claude process completed with exit code: ${code}`);
          
          // 处理输出并保存到文件
          const executionLog = await this.processOutputToJson(output, outputFile);
          
          resolve({
            success: code === 0,
            exitCode: code || 0,
            output,
            executionLog,
            outputFile
          });
        }
      });

      claudeProcess.on('error', (error) => {
        if (!resolved) {
          console.error('❌ Claude process error:', error);
          clearTimeout(timeoutId);
          resolved = true;
          resolve({
            success: false,
            exitCode: 1,
            output,
            outputFile
          });
        }
      });

      // 通过命名管道发送prompt
      this.sendPromptThroughPipe(promptPath, pipePath, claudeProcess);
    });
  }

  /**
   * 处理流式输出
   */
  private processStreamOutput(text: string): void {
    const lines = text.split('\n');
    lines.forEach((line) => {
      if (line.trim() === '') return;
      
      try {
        const parsed = JSON.parse(line);
        console.log('📊', JSON.stringify(parsed, null, 2));
      } catch (e) {
        console.log('📝', line);
      }
    });
  }

  /**
   * 通过命名管道发送prompt
   */
  private async sendPromptThroughPipe(
    promptPath: string, 
    pipePath: string, 
    claudeProcess: any
  ): Promise<void> {
    // 启动cat进程发送prompt到管道
    const catProcess = spawn('cat', [promptPath], {
      stdio: ['ignore', 'pipe', 'inherit']
    });
    
    const pipeStream = createWriteStream(pipePath);
    catProcess.stdout.pipe(pipeStream);

    // 从管道读取并发送到Claude
    const pipeProcess = spawn('cat', [pipePath]);
    pipeProcess.stdout.pipe(claudeProcess.stdin);

    // 错误处理
    catProcess.on('error', (error) => {
      console.error('❌ Cat process error:', error);
      pipeStream.destroy();
    });

    pipeProcess.on('error', (error) => {
      console.error('❌ Pipe process error:', error);
      claudeProcess.kill('SIGTERM');
    });
  }

  /**
   * 处理输出为JSON格式
   */
  private async processOutputToJson(output: string, outputFile: string): Promise<any[]> {
    try {
      // 将输出保存到临时文件
      const tempFile = outputFile.replace('.json', '.txt');
      await writeFile(tempFile, output);
      
      // 使用jq处理为JSON数组
      const { stdout: jsonOutput } = await execAsync(`jq -s '.' "${tempFile}"`);
      await writeFile(outputFile, jsonOutput);
      
      console.log(`💾 Execution log saved to: ${outputFile}`);
      return JSON.parse(jsonOutput);
    } catch (e) {
      console.warn(`⚠️  Failed to process output to JSON: ${e}`);
      return [];
    }
  }

  /**
   * 清理临时文件
   */
  private async cleanup(paths: string[]): Promise<void> {
    for (const path of paths) {
      try {
        await unlink(path);
      } catch (e) {
        // 忽略清理错误
      }
    }
    console.log('🧹 Temporary files cleaned up');
  }

  /**
   * 便捷方法：将结果输出到Markdown文件
   */
  async runAndSaveToMarkdown(
    options: ClaudeExecutionOptions,
    markdownPath: string
  ): Promise<ClaudeExecutionResult> {
    const result = await this.runClaude(options);
    
    // 创建Markdown内容
    const markdownContent = this.formatResultAsMarkdown(result, options);
    await writeFile(markdownPath, markdownContent);
    
    console.log(`📄 Results saved to Markdown: ${markdownPath}`);
    return result;
  }

  /**
   * 格式化结果为Markdown
   */
  private formatResultAsMarkdown(
    result: ClaudeExecutionResult,
    options: ClaudeExecutionOptions
  ): string {
    const timestamp = new Date().toISOString();
    
    return `# Claude Code Execution Result

## Execution Info
- **Timestamp**: ${timestamp}
- **Success**: ${result.success ? '✅' : '❌'}
- **Exit Code**: ${result.exitCode}
- **Model**: ${options.model || 'default'}
- **Max Turns**: ${options.maxTurns || 'unlimited'}
- **Working Directory**: ${options.workingDirectory || process.cwd()}

## Prompt
\`\`\`
${options.prompt}
\`\`\`

## Output
\`\`\`
${result.output}
\`\`\`

## Execution Log
${result.executionLog ? '```json\n' + JSON.stringify(result.executionLog, null, 2) + '\n```' : 'No execution log available'}

---
*Generated by Claude Code Runner at ${timestamp}*
`;
  }
}

使用示例

1. 基本使用

import { ClaudeCodeRunner } from './claude-code-runner';

async function basicExample() {
  const runner = new ClaudeCodeRunner();
  
  try {
    const result = await runner.runClaude({
      prompt: "分析当前项目的结构，生成一个项目概述",
      model: "claude-3-5-sonnet-20241022",
      maxTurns: 5,
      allowedTools: ["Read", "Glob", "Grep", "Bash"],
      timeoutMinutes: 15,
      workingDirectory: process.cwd() // 明确指定项目目录
    });
    
    console.log('✅ Execution completed:', result.success);
    if (result.success) {
      console.log('📊 Output preview:', result.output.substring(0, 500) + '...');
    } else {
      console.error('❌ Execution failed with exit code:', result.exitCode);
    }
  } catch (error) {
    console.error('❌ Error:', error);
  }
}

2. 保存到Markdown文件

async function markdownExample() {
  const runner = new ClaudeCodeRunner();
  
  try {
    const result = await runner.runAndSaveToMarkdown({
      prompt: "帮我优化这个函数的性能，并解释优化原理",
      model: "claude-3-5-sonnet-20241022",
      systemPrompt: "你是一个性能优化专家，专注于提供详细的代码分析和优化建议。",
      maxTurns: 3,
      allowedTools: ["Read", "Edit", "Grep"],
      timeoutMinutes: 10,
      workingDirectory: "/path/to/your/project"
    }, './claude-optimization-result.md');
    
    console.log('📄 Results saved to: ./claude-optimization-result.md');
  } catch (error) {
    console.error('❌ Error:', error);
  }
}

3. 批量处理

async function batchProcessing() {
  const runner = new ClaudeCodeRunner();
  const tasks = [
    {
      name: "代码审查",
      prompt: "审查src目录下的所有TypeScript文件，找出潜在问题",
      outputFile: "./reviews/code-review.md"
    },
    {
      name: "文档生成",
      prompt: "为主要的API函数生成文档",
      outputFile: "./docs/api-docs.md"
    },
    {
      name: "测试建议",
      prompt: "分析测试覆盖率，提供测试改进建议",
      outputFile: "./reports/test-suggestions.md"
    }
  ];

  for (const task of tasks) {
    console.log(`🔄 Processing: ${task.name}`);
    
    try {
      const result = await runner.runAndSaveToMarkdown({
        prompt: task.prompt,
        model: "claude-3-5-sonnet-20241022",
        maxTurns: 5,
        allowedTools: ["Read", "Glob", "Grep"],
        timeoutMinutes: 20,
        workingDirectory: process.cwd()
      }, task.outputFile);
      
      console.log(`✅ ${task.name} completed: ${result.success}`);
    } catch (error) {
      console.error(`❌ ${task.name} failed:`, error);
    }
  }
}

最佳实践

1. 工作目录管理

// ✅ 推荐：明确指定工作目录
const result = await runner.runClaude({
  workingDirectory: "/absolute/path/to/project",
  // ... 其他选项
});

// ❌ 避免：依赖当前目录
const result = await runner.runClaude({
  // workingDirectory 未指定
});

2. 工具权限控制

// ✅ 推荐：明确指定允许的工具
const result = await runner.runClaude({
  allowedTools: ["Read", "Glob", "Grep"], // 只读操作
  prompt: "分析代码结构"
});

// ⚠️  谨慎：允许写入操作
const result = await runner.runClaude({
  allowedTools: ["Read", "Write", "Edit", "Bash"], // 包含写入操作
  prompt: "优化代码"
});

3. 超时和资源管理

// ✅ 推荐：设置合理的超时时间
const result = await runner.runClaude({
  timeoutMinutes: 15, // 根据任务复杂度调整
  maxTurns: 5,        // 限制对话轮数
});

4. 错误处理

async function robustExecution() {
  const runner = new ClaudeCodeRunner();
  
  try {
    const result = await runner.runClaude(options);
    
    if (!result.success) {
      console.error(`Claude execution failed with exit code: ${result.exitCode}`);
      console.error(`Output: ${result.output}`);
      return;
    }
    
    // 处理成功结果
    console.log('Success!', result.output);
    
  } catch (error) {
    if (error.code === 'ENOENT') {
      console.error('❌ Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code');
    } else if (error.code === 'EACCES') {
      console.error('❌ Permission denied. Check file permissions.');
    } else {
      console.error('❌ Unexpected error:', error);
    }
  }
}

故障排除

常见问题及解决方案

1. Claude CLI未找到

Error: spawn claude ENOENT

解决方案:

npm install -g @anthropic-ai/claude-code@latest
which claude  # 验证安装路径

2. 权限问题

Error: EACCES: permission denied

解决方案:

# 检查临时目录权限
ls -la /tmp/claude-runner/
chmod 755 /tmp/claude-runner/

# 或使用不同的临时目录
const runner = new ClaudeCodeRunner('./temp/claude');

3. Named Pipe创建失败

Error: mkfifo command not found

解决方案:

确保在Unix/Linux/macOS系统上运行
Windows用户需要使用WSL或Docker

4. jq命令未找到

Error: jq: command not found

解决方案:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL
sudo yum install jq

调试技巧

1. 启用详细日志

// 在环境变量中启用调试
process.env.DEBUG = 'claude-runner:*';

2. 保留临时文件

class DebugClaudeCodeRunner extends ClaudeCodeRunner {
  private async cleanup(paths: string[]): Promise<void> {
    console.log('🐛 Debug mode: Skipping cleanup');
    console.log('📁 Temp files:', paths);
    // 不删除临时文件，便于调试
  }
}

3. 输出分析

const result = await runner.runClaude(options);

// 分析原始输出
console.log('Raw output length:', result.output.length);
console.log('Exit code:', result.exitCode);
console.log('Execution log entries:', result.executionLog?.length || 0);

// 保存调试信息
await writeFile('./debug-output.txt', result.output);

总结

这个完整攻略提供了在Node.js中直接调用Claude Code CLI的所有必要信息：

核心实现: 基于Named Pipes的稳定进程间通信
工作目录管理: 确保Claude在正确的项目上下文中运行
完整的错误处理: 超时控制、资源清理和异常处理
灵活的输出处理: 支持实时输出和结构化日志
便捷的集成接口: 易于集成到现有应用中

通过遵循这个攻略，你可以在任何Node.js项目中稳定地使用Claude Code的强大功能。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Claude Code CLI 代码集成完整攻略

目录

概述

为什么需要直接调用

前置准备

1. 环境要求

2. Node.js依赖

3. 系统要求

核心实现

关键技术要点

接口设计

完整代码

使用示例

1. 基本使用

2. 保存到Markdown文件

3. 批量处理

最佳实践

1. 工作目录管理

2. 工具权限控制

3. 超时和资源管理

4. 错误处理

故障排除

常见问题及解决方案

1. Claude CLI未找到

2. 权限问题

3. Named Pipe创建失败

4. jq命令未找到

调试技巧

1. 启用详细日志

2. 保留临时文件

3. 输出分析

总结

FilesExpand file tree

integration-guide.md

Latest commit

History

integration-guide.md

File metadata and controls

Claude Code CLI 代码集成完整攻略

目录

概述

为什么需要直接调用

前置准备

1. 环境要求

2. Node.js依赖

3. 系统要求

核心实现

关键技术要点

接口设计

完整代码

使用示例

1. 基本使用

2. 保存到Markdown文件

3. 批量处理

最佳实践

1. 工作目录管理

2. 工具权限控制

3. 超时和资源管理

4. 错误处理

故障排除

常见问题及解决方案

1. Claude CLI未找到

2. 权限问题

3. Named Pipe创建失败

4. jq命令未找到

调试技巧

1. 启用详细日志

2. 保留临时文件

3. 输出分析

总结