@gongfu/claude-integration/README.md

Claude Code integration toolkit for Gongfu workflow system

# @gongfu/claude-integration

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

## 特性

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

## 安装

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

## 使用示例

### 基础使用

```typescript
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);
```

### 进程管理

```typescript
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();
```

### 活动监控

```typescript
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 服务器集成

```typescript
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 配置

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

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

## API 文档

### ClaudeController

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

```typescript
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 进程。

```typescript
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 活动和日志。

```typescript
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 活动处理器。

```typescript
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>;
}
```

## 类型定义

```typescript
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 客户端断开时触发

## 高级用法

### 自定义输出解析器

```typescript
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 扩展

```typescript
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 无法启动

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

# 检查环境变量
echo $PATH

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

### 输出捕获失败

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

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

### SSE 连接问题

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

## 开发计划

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

## 贡献

欢迎贡献！请查看 [贡献指南](../../CONTRIBUTING.md)。

## 许可证

MIT © Foundation