@gongfu/claude-integration

Claude Code 集成工具包，为 Gongfu 工作流系统提供与 Claude Code 的深度集成。

特性

• 🚀 进程管理: 使用 node-pty 实现完整的终端控制
• 📊 活动监控: 实时监控 Claude Code 的活动和输出
• 🎯 任务分配: 向 Claude Code 分配任务并跟踪执行
• 🔄 双向通信: 支持向 Claude Code 发送命令和接收输出
• 📡 SSE 流式传输: 提供 Server-Sent Events 实时推送
• 🪝 Hook 系统: 增强的 Hook 配置支持全面的事件捕获
• 📝 日志解析: 智能解析 Claude Code 输出和日志

安装

npm install @gongfu/claude-integration
# 或
pnpm add @gongfu/claude-integration
# 或
yarn add @gongfu/claude-integration

使用示例

基础使用

import { 
  ClaudeController, 
  ClaudeMonitor, 
  ClaudeProcessManager 
} from '@gongfu/claude-integration';

// 创建控制器
const controller = new ClaudeController({
  projectRoot: process.cwd(),
  logOutput: true
});

// 分配任务
const taskId = await controller.assignTask('实现用户登录功能', {
  priority: 'high'
});

// 获取状态
const status = await controller.getStatus();
console.log('Claude 状态:', status);

进程管理

const processManager = new ClaudeProcessManager({
  projectRoot: process.cwd(),
  usePty: true,
  captureOutput: true
});

// 启动 Claude Code
await processManager.start(['--verbose']);

// 发送命令
await processManager.sendCommand('help');

// 监听输出
processManager.on('parsed-output', (parsed) => {
  console.log('解析的输出:', parsed);
});

// 停止进程
await processManager.stop();

活动监控

const monitor = new ClaudeMonitor({
  projectRoot: process.cwd()
});

// 启动监控
await monitor.start();

// 监听活动
monitor.on('activity', (activity) => {
  console.log('Claude 活动:', activity);
});

// 启动 SSE 服务器
const server = await monitor.startSSEServer(3001);

MCP 服务器集成

import { ClaudeActivityHandler } from '@gongfu/claude-integration';
import express from 'express';

const app = express();
const handler = new ClaudeActivityHandler(process.cwd());

// 启动处理器
await handler.start();

// 设置 SSE 端点
handler.setupSSEEndpoints(app);

// 访问端点:
// GET /mcp/claude/stream - SSE 活动流
// GET /mcp/claude/summary - 活动摘要
// GET /mcp/claude/current-task - 当前任务
// POST /mcp/claude/log - 记录活动

Hook 配置

// 设置增强的 Hook
await controller.setupHooks(true);

// 这将配置以下 Hook:
// - PreToolUse: 工具使用前记录
// - PostToolUse: 工具使用后记录  
// - Start: 会话开始记录
// - Stop: 会话结束记录
// - 文件变更自动同步

API 文档

ClaudeController

管理 Claude Code 实例和任务分配。

class ClaudeController extends EventEmitter {
  constructor(options?: ClaudeControllerOptions);
  assignTask(taskDescription: string, options?: TaskOptions): Promise<string>;
  startInBackground(): Promise<void>;
  getStatus(): Promise<ClaudeStatus>;
  setupHooks(enhanced?: boolean): Promise<void>;
  stop(): Promise<void>;
}

ClaudeProcessManager

使用 node-pty 管理 Claude Code 进程。

class ClaudeProcessManager extends EventEmitter {
  constructor(options?: ClaudeProcessOptions);
  start(args?: string[]): Promise<void>;
  sendInput(input: string): Promise<void>;
  sendCommand(command: string): Promise<void>;
  stop(): Promise<void>;
  getRecentOutput(lines?: number): ClaudeOutput[];
  searchOutput(pattern: string | RegExp): ClaudeOutput[];
  getInfo(): ProcessInfo;
}

ClaudeMonitor

监控 Claude Code 活动和日志。

class ClaudeMonitor extends EventEmitter {
  constructor(options?: ClaudeMonitorOptions);
  start(): Promise<void>;
  stop(): Promise<void>;
  startSSEServer(port?: number): Promise<Server>;
  getActivities(limit?: number): ClaudeActivity[];
  getActivitySummary(): ActivitySummary;
}

ClaudeActivityHandler

MCP 服务器的 Claude 活动处理器。

class ClaudeActivityHandler extends EventEmitter {
  constructor(projectRoot: string);
  start(): Promise<void>;
  stop(): Promise<void>;
  setupSSEEndpoints(app: express.Application): void;
  logActivity(type: string, data: any): void;
  getActivitySummary(): any;
  getCurrentTask(): Promise<any>;
}

类型定义

interface ClaudeActivity {
  id: string;
  timestamp: string;
  type: 'tool-use' | 'file-change' | 'command' | 'session' | 'thinking' | 'task-update';
  data: any;
  source: 'hook' | 'file' | 'monitor';
}

interface ClaudeStatus {
  isActive: boolean;
  processId?: number;
  currentTask?: {
    id: string;
    content: string;
    startedAt: string;
  };
  recentActivity: Activity[];
}

interface ClaudeOutput {
  timestamp: string;
  type: 'stdout' | 'stderr' | 'system';
  content: string;
  parsed?: any;
}

事件

ClaudeController 事件

• task-assigned: 任务被分配时触发
• tool-use: 检测到工具使用时触发
• file-change: 检测到文件变更时触发
• thinking: 检测到思考过程时触发
• process-exit: Claude Code 进程退出时触发

ClaudeProcessManager 事件

• started: 进程启动时触发
• output: 收到输出时触发
• parsed-output: 输出被解析时触发
• input: 发送输入时触发
• exit: 进程退出时触发
• error: 发生错误时触发

ClaudeMonitor 事件

• activity: 检测到新活动时触发
• connected: SSE 客户端连接时触发
• disconnected: SSE 客户端断开时触发

高级用法

自定义输出解析器

import { ClaudeOutputParser } from '@gongfu/claude-integration';

class CustomParser extends ClaudeOutputParser {
  parse(output: string): any {
    // 自定义解析逻辑
    const result = super.parse(output);
    
    // 添加自定义模式匹配
    if (output.includes('Custom Pattern')) {
      return {
        type: 'custom',
        data: extractCustomData(output)
      };
    }
    
    return result;
  }
}

集成到 VSCode 扩展

import * as vscode from 'vscode';
import { ClaudeController } from '@gongfu/claude-integration';

export function activate(context: vscode.ExtensionContext) {
  const controller = new ClaudeController({
    projectRoot: vscode.workspace.rootPath || process.cwd()
  });

  // 注册命令
  const assignTaskCommand = vscode.commands.registerCommand(
    'gongfu.assignTaskToClaude',
    async () => {
      const task = await vscode.window.showInputBox({
        prompt: '输入要分配给 Claude 的任务'
      });
      
      if (task) {
        const taskId = await controller.assignTask(task);
        vscode.window.showInformationMessage(`任务已分配: ${taskId}`);
      }
    }
  );

  context.subscriptions.push(assignTaskCommand);
}

最佳实践

1. 错误处理: 始终包装异步调用在 try-catch 块中
2. 资源清理: 确保在应用退出时调用 stop() 方法
3. 日志管理: 定期清理日志文件以避免磁盘空间问题
4. 性能优化: 对于大型项目，考虑限制监控的文件范围
5. 安全性: 谨慎处理 Claude Code 的输出，避免执行不受信任的命令

故障排查

Claude Code 无法启动

# 检查 Claude Code 是否已安装
claude --version

# 检查环境变量
echo $PATH

# 验证权限
ls -la ~/.claude/

输出捕获失败

如果使用标准 spawn 无法捕获输出，尝试使用 PTY 模式：

const processManager = new ClaudeProcessManager({
  usePty: true,
  captureOutput: true
});

SSE 连接问题

确保防火墙允许指定端口的连接，并检查 CORS 设置。

开发计划

• [ ] 支持更多 Claude Code 命令和参数
• [ ] 添加输出的机器学习分析
• [ ] 实现任务队列和并发控制
• [ ] 支持远程 Claude Code 实例
• [ ] 添加 WebSocket 传输支持
• [ ] 实现插件系统

贡献

欢迎贡献！请查看 贡献指南。

许可证

MIT © Foundation