@louloulinx/metagpt 0.1.3

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@louloulinx/metagpt",
+  "version": "0.1.3",
+  "description": "A TypeScript implementation of MetaGPT",
+  "module": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist",
+    "test": "bun test",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "type-check": "tsc --noEmit",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "prepublishOnly": "bun run lint && bun run build",
+    "publish": "npm publish"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.5",
+    "@typescript-eslint/eslint-plugin": "8.25.0",
+    "@typescript-eslint/parser": "8.25.0",
+    "bun-types": "latest",
+    "eslint": "^9.21.0",
+    "prettier": "^3.5.2",
+    "typedoc": "0.27.9",
+    "typescript": "^5.7.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.1.10",
+    "@ai-sdk/google": "^1.1.17",
+    "@ai-sdk/mistral": "^1.1.13",
+    "@ai-sdk/openai": "^1.1.14",
+    "@jest/types": "^29.6.3",
+    "@qdrant/js-client-rest": "^1.13.0",
+    "@types/jest": "^29.5.14",
+    "@types/lodash": "^4.17.15",
+    "@types/uuid": "^10.0.0",
+    "ai": "^4.1.46",
+    "axios": "^1.7.9",
+    "lodash": "^4.17.21",
+    "openai": "^4.85.4",
+    "qwen-ai-provider": "^0.1.0",
+    "rxjs": "^7.8.2",
+    "ts-jest": "^29.2.6",
+    "uuid": "^11.1.0",
+    "winston": "^3.17.0",
+    "xstate": "^5.19.2",
+    "zod": "^3.24.2"
+  }
+}

package/plan-cn.md

@@ -0,0 +1,321 @@
+# MetaGPT TypeScript
+
+## 1. 项目结构 ✅
+
+```
+metagpt-ts/
+├── src/
+│   ├── actions/      # 动作定义和实现 ✅
+│   ├── roles/        # 角色定义和行为 ✅
+│   ├── utils/        # 工具函数和辅助类 ✅
+│   ├── config/       # 配置管理 ✅
+│   ├── memory/       # 记忆和状态管理 ✅
+│   ├── provider/     # LLM提供商集成 ✅
+│   ├── tools/        # 外部工具集成 ✅
+│   ├── skills/       # 技能实现 ✅
+│   ├── rag/          # 检索增强生成 ✅
+│   ├── document/     # 文档处理和管理 ✅
+│   └── types/        # TypeScript类型定义 ✅
+├── tests/            # 测试文件 ✅
+├── examples/         # 示例实现
+└── package.json      # 项目依赖和脚本 ✅
+```
+
+## 2. 技术选型 ✅
+
+### 核心技术栈 ✅
+1. Runtime & Package Manager
+   - Bun.js: 高性能 JavaScript runtime，内置包管理器 ✅
+   - Node.js 18+ 兼容性支持 ✅
+
+2. 开发语言与框架
+   - TypeScript 5.0+：强类型支持 ✅
+   - Zod：运行时类型验证 ✅
+   - XState：状态机管理 ✅
+   - RxJS：响应式编程 ✅
+
+3. 测试与开发工具
+   - bun:test：单元测试框架 ✅
+   - ESLint + Prettier：代码规范 ✅
+   - TypeDoc：API 文档生成 ✅
+
+4. 核心依赖
+   - Vercel AI SDK ✅
+   - Qdrant Node Client：向量存储 ✅
+   - Winston：日志管理 ✅
+
+### 技术特性
+1. 状态管理
+   - 使用 XState 实现角色状态机 ✅
+   - RxJS 处理异步消息流 ✅
+   - 响应式的内存管理 ✅
+
+2. 类型系统
+   - 严格的 TypeScript 类型 ✅
+   - Zod schema 验证 ✅
+   - 运行时类型检查 ✅
+
+3. 异步处理
+   - 基于 Promise 和 async/await ✅
+   - RxJS Observable 消息流 ✅
+   - 事件驱动架构 ✅
+
+## 3. 核心接口设计 ✅
+
+### 基础消息系统 ✅
+```typescript
+interface Message {
+  id: string;
+  content: string;
+  role: string;
+  causedBy: string;
+  sentFrom: string;
+  sendTo: Set<string>;
+  instructContent?: any;
+}
+
+interface MessageQueue {
+  push(msg: Message): void;
+  pop(): Promise<Message | null>;
+  popAll(): Promise<Message[]>;
+  empty(): boolean;
+}
+```
+
+### 角色系统 ✅
+```typescript
+interface Role {
+  name: string;
+  profile: string;
+  goal: string;
+  constraints: string;
+  actions: Action[];
+  
+  // 核心方法
+  observe(): Promise<number>;
+  think(): Promise<boolean>;
+  act(): Promise<Message>;
+  react(): Promise<Message>;
+  
+  // 状态管理
+  state: number;
+  context: RoleContext;
+}
+
+interface RoleContext {
+  memory: Memory;
+  workingMemory: Memory;
+  state: number;
+  todo: Action | null;
+  watch: Set<string>;
+  reactMode: RoleReactMode;
+}
+```
+
+### 动作系统 ✅
+```typescript
+interface Action {
+  name: string;
+  context: ActionContext;
+  llm: LLMProvider;
+  
+  run(): Promise<ActionOutput>;
+  handleException(error: Error): Promise<void>;
+}
+
+interface ActionOutput {
+  content: string;
+  status: ActionStatus;
+  instruct_content?: any;
+}
+```
+
+### 状态机定义 ✅
+```typescript
+interface RoleStateMachine {
+  states: {
+    idle: {};
+    observing: {};
+    thinking: {};
+    acting: {};
+    reacting: {};
+  };
+  
+  events: {
+    OBSERVE: {};
+    THINK: {};
+    ACT: {};
+    REACT: {};
+    COMPLETE: {};
+  };
+}
+```
+
+## 4. 核心组件迁移优先级
+
+### 第一阶段：基础框架 ✅
+1. 基本项目设置 ✅
+   - 初始化TypeScript项目 ✅
+   - 设置开发环境(ESLint, Prettier, Jest) ✅
+   - 定义基础接口和类型 ✅
+   - 实现核心工具类 ✅
+
+2. 基础组件 ✅
+   - 上下文和配置管理 ✅
+   - 基本LLM提供商集成 ✅
+   - 文档和记忆管理基础 ✅
+
+### 第二阶段：核心功能 ✅
+1. 角色系统 ✅
+   - 基础角色类实现 ✅
+   - 角色生命周期管理 ✅
+   - 消息处理系统 ✅
+
+2. 动作系统 ✅
+   - 动作基类 ✅
+   - 动作执行框架 ✅
+   - 消息和状态管理 ✅
+
+3. 记忆系统 ✅
+   - 工作记忆实现 ✅
+   - 长期记忆实现 ✅
+   - 记忆管理器 ✅
+   - 记忆整合和遗忘 ✅
+   - 单元测试覆盖 ✅
+
+### 第三阶段：高级功能 ✅
+1. 技能和工具 ✅
+   - 技能系统实现 ✅
+   - 工具集成框架 ✅
+   - RAG实现 ✅
+
+2. 团队和管理 ✅
+   - 团队协调 ✅
+   - 任务管理 ✅
+   - 工作流编排 ✅
+
+### 第四阶段：完善和优化
+1. WebSocket支持 ✅
+   - WebSocket服务器实现 ✅
+   - WebSocket客户端实现 ✅
+   - 消息类型和验证 ✅
+   - 流式传输支持 ✅
+   - 错误处理和重连 ✅
+   - 单元测试覆盖 ✅
+2. 浏览器兼容性 ✅
+   - 浏览器WebSocket客户端 ✅
+   - 原生WebSocket API支持 ✅
+   - 跨浏览器兼容性测试 ✅
+   - 单元测试覆盖 ✅
+3. 插件系统 ✅
+   - 插件接口定义 ✅
+   - 插件生命周期管理 ✅
+   - 插件依赖管理 ✅
+   - 插件配置管理 ✅
+   - 钩子系统实现 ✅
+   - 错误处理机制 ✅
+   - 单元测试覆盖 ✅
+4. 监控和可观测性 ✅
+   - [x] 指标收集（计数器、仪表盘、直方图、摘要）
+   - [x] 分布式追踪（跨度、事件、错误跟踪）
+   - [x] 结构化日志（级别、上下文）
+   - [x] 单元测试覆盖
+
+## 5. 技术决策 ✅
+
+### TypeScript配置 ✅
+- 目标: ES2020+ ✅
+- 启用严格类型检查 ✅
+- ESM模块 ✅
+- Node.js 18+支持 ✅
+
+### 依赖 ✅
+- OpenAI API客户端 ✅
+- 向量存储(Milvus/Qdrant客户端) ✅
+- 文档处理库 ✅
+- 测试框架(Jest) ✅
+- 日志(Winston/Pino) ✅
+
+### 架构改进 ✅
+1. 增强类型安全 ✅
+   - 严格类型定义 ✅
+   - 运行时类型验证 ✅
+   - 接口优先设计 ✅
+
+2. 现代JavaScript特性 ✅
+   - 全面使用async/await ✅
+   - ES模块 ✅
+   - 装饰器用于角色和动作定义 ✅
+
+3. 开发者体验 ✅
+   - 更好的IDE集成 ✅
+   - 改进的错误消息 ✅
+   - 完整的文档 ✅
+
+## 6. 实现策略 ✅
+
+### 步骤1：项目设置 ✅
+1. 初始化package.json ✅
+2. 配置TypeScript ✅
+3. 设置开发工具 ✅
+4. 创建基本项目结构 ✅
+
+### 步骤2：核心实现 ✅
+1. 移植基础工具和辅助函数 ✅
+2. 实现配置系统 ✅
+3. 创建基类和接口 ✅
+4. 设置LLM提供商集成 ✅
+
+### 步骤3：角色系统 ✅
+1. 实现角色基类 ✅
+2. 移植基本角色 ✅
+3. 设置消息处理 ✅
+4. 实现状态管理 ✅
+
+### 步骤4：动作和技能 ✅
+1. 创建动作框架 ✅
+2. 移植基本动作 ✅
+3. 实现技能系统 ✅
+4. 添加工具集成 ✅
+
+### 步骤5：高级功能 ✅
+1. 实现RAG系统 ✅
+2. 添加团队管理 ✅
+3. 创建工作流编排 ✅
+4. 移植剩余功能 ✅
+
+## 7. 测试策略 ✅
+1. 单元测试(Vitest) ✅
+2. 集成测试 ✅
+3. E2E测试 ✅
+4. 性能基准测试 ✅
+
+## 8. 文档
+1. API文档 ✅
+   - TypeDoc配置 ✅
+   - JSDoc注释 ✅
+   - API参考文档生成 ✅
+2. 使用示例
+3. 迁移指南
+4. 最佳实践
+
+## 9. 兼容性考虑
+1. 尽可能保持API兼容性 ✅
+2. 记录破坏性变更 ✅
+3. 提供迁移工具
+4. 支持渐进式采用
+
+## 10. 未来增强
+1. WebSocket支持 ✅
+2. 浏览器兼容性 ✅
+3. 插件系统 ✅
+4. 增强监控和可观察性
+
+## 时间线
+- 第一阶段: 2周 ✅
+- 第二阶段: 2周 ✅
+- 第三阶段: 2周 ✅
+- 测试和文档: 1周
+- 缓冲和完善: 1周
+
+总计预估时间: 8周 

package/plan.md

@@ -0,0 +1,154 @@
+# MetaGPT TypeScript Migration Plan
+
+## 1. Project Structure
+
+```
+metagpt-ts/
+├── src/
+│   ├── actions/      # Action definitions and implementations
+│   ├── roles/        # Role definitions and behaviors
+│   ├── utils/        # Utility functions and helpers
+│   ├── config/       # Configuration management
+│   ├── memory/       # Memory and state management
+│   ├── provider/     # LLM providers integration
+│   ├── tools/        # External tools integration
+│   ├── skills/       # Skill implementations
+│   ├── rag/          # Retrieval-augmented generation
+│   ├── document/     # Document processing and management
+│   └── types/        # TypeScript type definitions
+├── tests/            # Test files
+├── examples/         # Example implementations
+└── package.json      # Project dependencies and scripts
+```
+
+## 2. Core Components Migration Priority
+
+### Phase 1: Foundation (Week 1-2)
+1. Basic project setup
+   - Initialize TypeScript project
+   - Setup development environment (ESLint, Prettier, Jest)
+   - Define base interfaces and types
+   - Implement core utilities
+
+2. Essential Components
+   - Context and Configuration management
+   - Basic LLM provider integration
+   - Document and memory management foundation
+
+### Phase 2: Core Functionality (Week 3-4)
+1. Role System
+   - Base Role class implementation
+   - Role lifecycle management
+   - Message handling system
+
+2. Action System
+   - Action base classes
+   - Action execution framework
+   - Message and state management
+
+### Phase 3: Advanced Features (Week 5-6)
+1. Skills and Tools
+   - Skill system implementation
+   - Tool integration framework
+   - RAG implementation
+
+2. Team and Management
+   - Team coordination
+   - Task management
+   - Workflow orchestration
+
+## 3. Technical Decisions
+
+### TypeScript Configuration
+- Target: ES2020+
+- Strict type checking enabled
+- ESM modules
+- Node.js 18+ support
+
+### Dependencies
+- OpenAI API client
+- Vector storage (e.g., Milvus/Qdrant client)
+- Document processing libraries
+- Testing framework (Jest)
+- Logging (Winston/Pino)
+
+### Architecture Improvements
+1. Enhanced Type Safety
+   - Strict typing for all components
+   - Runtime type validation
+   - Interface-first design
+
+2. Modern JavaScript Features
+   - Async/await throughout
+   - ES modules
+   - Decorators for role and action definitions
+
+3. Developer Experience
+   - Better IDE integration
+   - Improved error messages
+   - Comprehensive documentation
+
+## 4. Implementation Strategy
+
+### Step 1: Project Setup
+1. Initialize project with `package.json`
+2. Configure TypeScript
+3. Setup development tools
+4. Create basic project structure
+
+### Step 2: Core Implementation
+1. Port basic utilities and helpers
+2. Implement configuration system
+3. Create base classes and interfaces
+4. Setup LLM provider integration
+
+### Step 3: Role System
+1. Implement Role base class
+2. Port essential roles
+3. Setup message handling
+4. Implement state management
+
+### Step 4: Actions and Skills
+1. Create action framework
+2. Port basic actions
+3. Implement skill system
+4. Add tool integration
+
+### Step 5: Advanced Features
+1. Implement RAG system
+2. Add team management
+3. Create workflow orchestration
+4. Port remaining features
+
+## 5. Testing Strategy
+1. Unit tests for all components
+2. Integration tests for workflows
+3. E2E tests for complete scenarios
+4. Performance benchmarking
+
+## 6. Documentation
+1. API documentation
+2. Usage examples
+3. Migration guide
+4. Best practices
+
+## 7. Compatibility Considerations
+1. Maintain API compatibility where possible
+2. Document breaking changes
+3. Provide migration utilities
+4. Support gradual adoption
+
+## 8. Future Enhancements
+1. WebSocket support for real-time interactions
+2. Browser compatibility
+3. Plugin system
+4. Enhanced monitoring and observability
+
+## Timeline
+- Phase 1: 2 weeks
+- Phase 2: 2 weeks
+- Phase 3: 2 weeks
+- Testing & Documentation: 1 week
+- Buffer & Polish: 1 week
+
+Total estimated time: 8 weeks 

package/src/actions/analyze-task.ts

@@ -0,0 +1,65 @@
+import { BaseAction } from './base-action';
+import type { ActionOutput, ActionConfig } from '../types/action';
+
+/**
+ * 任务分析动作
+ * 使用 LLM 分析任务需求并生成结构化输出
+ */
+export class AnalyzeTask extends BaseAction {
+  constructor(config: ActionConfig) {
+    super({
+      ...config,
+      name: 'analyze_task',
+      description: 'Analyze task requirements and generate structured output',
+    });
+  }
+
+  /**
+   * 执行任务分析
+   * @returns 分析结果
+   */
+  async run(): Promise<ActionOutput> {
+    try {
+      // 获取任务内容
+      const task = this.getArg<string>('task');
+      if (!task) {
+        return this.createOutput('No task provided', 'failed');
+      }
+
+      // 构建提示词
+      const prompt = `
+Please analyze the following task and provide a structured response:
+Task: ${task}
+
+Please provide:
+1. Task objective
+2. Key requirements
+3. Potential challenges
+4. Suggested approach
+5. Required resources
+
+Format your response in a clear, structured manner.
+`;
+
+      // 调用 LLM 进行分析
+      const analysis = await this.llm.generate(prompt);
+
+      return this.createOutput(analysis);
+    } catch (error) {
+      await this.handleException(error as Error);
+      return this.createOutput(
+        `Failed to analyze task: ${(error as Error).message}`,
+        'failed'
+      );
+    }
+  }
+
+  /**
+   * 自定义错误处理
+   */
+  async handleException(error: Error): Promise<void> {
+    await super.handleException(error);
+    // 可以添加特定的错误处理逻辑
+    this.setArg('lastError', error.message);
+  }
+} 

package/src/actions/base-action.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import type { Action, ActionContext, ActionOutput, ActionConfig } from '../types/action';
+import type { LLMProvider } from '../types/llm';
+import { ActionContextSchema, ActionOutputSchema } from '../types/action';
+
+/**
+ * 动作基类
+ * 提供动作系统的基础功能实现
+ */
+export abstract class BaseAction implements Action {
+  name: string;
+  context: ActionContext;
+  llm: LLMProvider;
+
+  constructor(config: ActionConfig) {
+    // 验证配置
+    const validConfig = z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      args: z.record(z.any()).optional(),
+      llm: z.any(),
+      memory: z.any().optional(),
+      workingMemory: z.any().optional(),
+    }).parse(config);
+
+    this.name = validConfig.name;
+    this.llm = validConfig.llm;
+
+    // 构建上下文
+    this.context = ActionContextSchema.parse({
+      name: validConfig.name,
+      description: validConfig.description || '',
+      args: validConfig.args || {},
+      llm: validConfig.llm,
+      memory: validConfig.memory,
+      workingMemory: validConfig.workingMemory,
+    });
+  }
+
+  /**
+   * 执行动作
+   * 子类必须实现此方法
+   */
+  abstract run(): Promise<ActionOutput>;
+
+  /**
+   * 处理异常
+   * @param error 错误对象
+   */
+  async handleException(error: Error): Promise<void> {
+    console.error(`Action ${this.name} failed:`, error);
+    // 子类可以覆盖此方法以提供自定义错误处理
+  }
+
+  /**
+   * 验证动作输出
+   * @param output 动作输出
+   * @returns 验证后的输出
+   */
+  protected validateOutput(output: ActionOutput): ActionOutput {
+    return ActionOutputSchema.parse(output);
+  }
+
+  /**
+   * 生成动作输出
+   * @param content 输出内容
+   * @param status 动作状态
+   * @param instructContent 指令内容（可选）
+   * @returns 动作输出
+   */
+  protected createOutput(
+    content: string,
+    status: 'completed' | 'failed' | 'blocked' = 'completed',
+    instructContent?: any
+  ): ActionOutput {
+    return this.validateOutput({
+      content,
+      status,
+      instructContent,
+    });
+  }
+
+  /**
+   * 获取动作参数
+   * @param key 参数键
+   * @returns 参数值
+   */
+  protected getArg<T>(key: string): T | undefined {
+    return this.context.args?.[key] as T;
+  }
+
+  /**
+   * 设置动作参数
+   * @param key 参数键
+   * @param value 参数值
+   */
+  protected setArg<T>(key: string, value: T): void {
+    if (!this.context.args) {
+      this.context.args = {};
+    }
+    this.context.args[key] = value;
+  }
+}