Skill: banxian87/agent-architecture-patterns (version 1.1.0)

--- name: agent-architecture-patterns description: AI Agent architecture patterns library with 10 patterns for single and multi-agent systems --- # Agent Architecture Patterns This skill provides a comprehensive library of AI Agent architecture patterns to help developers: - Design single-agent architectures (ReAct, Reflection, Self-Critique, Plan-and-Solve, Tree of Thoughts) - Design multi-agent collaboration systems (Manager-Worker, Peer-to-Peer, Hierarchical, Market-Based, Pipeline) - Apply system design principles (separation of concerns, fault tolerance, scalability) - Implement best practices based on OpenClaw --- ## Patterns ### Single-Agent Patterns (5) 1. **ReAct** - Reasoning + Acting alternation 2. **Reflection** - Self-reflection and iterative improvement 3. **Self-Critique** - Self-criticism and error correction 4. **Plan-and-Solve** - Plan first, then execute 5. **Tree of Thoughts** - Multi-path exploration ### Multi-Agent Patterns (5) 1. **Manager-Worker** - 1 manager coordinates multiple workers 2. **Peer-to-Peer** - Equal agents collaborate 3. **Hierarchical** - Multi-level management structure 4. **Market-Based** - Task bidding and allocation 5. **Pipeline** - Sequential multi-stage processing --- ## Usage ### Option 1: Consult AI-Agent Ask questions like: - "Design a multi-agent code review system" - "How to implement ReAct pattern?" - "Which agent collaboration pattern should I use?" ### Option 2: Reference Documentation Browse `patterns/` directory for detailed pattern docs. ### Option 3: Use Code Examples Run example code from `examples/` directory. --- ## Examples ### ReAct Pattern Example ```javascript const agent = new ReActAgent({ tools: [search, calculate], maxSteps: 10 }); const answer = await agent.execute("What's the temperature in Beijing today?"); ``` ### Manager-Worker Pattern Example ```javascript const workers = [ new WorkerAgent('worker-1', ['javascript'], { codeReview: true }), new WorkerAgent('worker-2', ['python'], { dataAnalysis: true }) ]; const manager = new ManagerAgent(workers); const result = await manager.coordinate("Review this codebase"); ``` --- ## Installation ```bash clawhub install agent-architecture-patterns ``` --- ## Testing ```bash npm test # Runs 30 test cases for ReAct and Manager-Worker implementations ``` --- ## License MIT --- ## Author AI-Agent

path: examples/manager-worker-full-example.js
content: /**
 * Manager-Worker Agent 完整示例 - 多 Agent 代码审查系统
 * 
 * 运行方式：node examples/manager-worker-full-example.js
 */

const { ManagerAgent, WorkerAgent } = require('../src/agents/manager-worker-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor() {
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    
    // 任务分解
    if (prompt.includes('将以下任务分解为独立的子任务')) {
      return JSON.stringify([
        {
          id: 'task-1',
          description: '语法和格式检查',
          requiredSkills: ['javascript', 'eslint']
        },
        {
          id: 'task-2',
          description: '代码逻辑审查',
          requiredSkills: ['javascript', 'code-review']
        },
        {
          id: 'task-3',
          description: '安全性检查',
          requiredSkills: ['security', 'javascript']
        },
        {
          id: 'task-4',
          description: '性能优化建议',
          requiredSkills: ['performance', 'javascript']
        }
      ]);
    }
    
    // 整合结果
    if (prompt.includes('请整合所有成功结果')) {
      return `## 代码审查报告

### 审查概览
- 审查文件：user-service.js
- 审查维度：语法、逻辑、安全、性能
- 发现问题：5 个
- 建议改进：3 处

---

### 1. 语法和格式检查 ✅

**通过项**：
- 代码格式符合 ESLint 标准
- 命名规范清晰
- 注释完整

**问题**：
- 第 15 行：缺少 JSDoc 注释
- 第 28 行：函数过长（建议拆分为小函数）

---

### 2. 代码逻辑审查 ⚠️

**问题**：
1. **空值处理不当**（第 23 行）
   ```javascript
   // 问题代码
   const user = users.find(u => u.id === userId);
   return user.name; // 可能抛出 TypeError
   
   // 建议修改
   const user = users.find(u => u.id === userId);
   if (!user) throw new Error('User not found');
   return user.name;
   ```

2. **重复代码**（第 35-42 行和第 58-65 行）
   - 建议提取为公共函数

---

### 3. 安全性检查 ❌

**严重问题**：

1. **SQL 注入风险**（第 45 行）
   ```javascript
   // 危险代码
   const query = \`SELECT * FROM users WHERE id = \${userId}\`;
   
   // 安全做法
   const query = 'SELECT * FROM users WHERE id = ?';
   db.execute(query, [userId]);
   ```

2. **敏感信息泄露**（第 12 行）
   - 不要在日志中打印用户密码

---

### 4. 性能优化建议 💡

**优化点**：

1. **避免重复查询**（第 50 行）
   - 添加缓存机制
   - 使用 DataLoader

2. **减少循环嵌套**（第 70 行）
   - 当前：O(n²)
   - 优化：使用 Map，O(n)

---

### 总结

**优先级**：
- 🔴 高：修复 SQL 注入漏洞
- 🟡 中：添加空值处理
- 🟢 低：代码重构和优化

**总体评分**：6/10

建议优先修复安全问题，然后改进代码质量。`;
    }
    
    return 'Generated.';
  }
}

// ============================================
// 创建 Worker Agents
// ============================================

const syntaxWorker = new WorkerAgent('syntax-checker', ['javascript', 'eslint'], {
  codeReview: true
});

const logicWorker = new WorkerAgent('logic-reviewer', ['javascript', 'code-review'], {
  codeReview: true
});

const securityWorker = new WorkerAgent('security-scanner', ['security', 'javascript'], {
  codeReview: true
});

const performanceWorker = new WorkerAgent('performance-analyzer', ['performance', 'javascript'], {
  codeReview: true
});

// Mock LLM for workers
[syntaxWorker, logicWorker, securityWorker, performanceWorker].forEach(worker => {
  worker.llm = new MockLLM();
});

// ============================================
// Mock Worker 执行
// ============================================

syntaxWorker.execute = async (subtask) => {
  return `语法检查完成：
- 格式：✅ 符合规范
- 命名：✅ 清晰
- 注释：⚠️ 部分缺失
- 问题：2 个`;
};

logicWorker.execute = async (subtask) => {
  return `逻辑审查完成：
- 空值处理：❌ 缺失
- 错误处理：⚠️ 不完整
- 代码复用：❌ 有重复
- 问题：2 个`;
};

securityWorker.execute = async (subtask) => {
  return `安全检查完成：
- SQL 注入：❌ 发现风险
- XSS 防护：✅ 良好
- 敏感信息：❌ 日志泄露
- 问题：2 个严重`;
};

performanceWorker.execute = async (subtask) => {
  return `性能分析完成：
- 时间复杂度：⚠️ 有优化空间
- 数据库查询：❌ 重复查询
- 缓存使用：❌ 未使用
- 建议：3 处优化`;
};

// ============================================
// 创建 Manager Agent
// ============================================

const manager = new ManagerAgent(
  [syntaxWorker, logicWorker, securityWorker, performanceWorker],
  {
    maxRetries: 3,
    timeout: 30000,
    verbose: true,
    llm: new MockLLM()
  }
);

// ============================================
// 运行示例
// ============================================

async function runExample() {
  console.log('=== Manager-Worker Agent 示例 - 多 Agent 代码审查系统 ===\n');
  
  const codeToReview = `// user-service.js
function getUser(userId) {
  const users = db.query('SELECT * FROM users');
  const user = users.find(u => u.id === userId);
  return user.name;
}

function createUser(data) {
  const query = \`INSERT INTO users (name, email, password) 
                 VALUES ('\${data.name}', '\${data.email}', '\${data.password}')\`;
  db.execute(query);
  console.log('Created user:', data); // 问题：打印密码
}

// ... 更多代码 ...`;

  console.log('📝 任务：多 Agent 代码审查\n');
  console.log('待审查代码：');
  console.log(codeToReview);
  console.log('\n' + '='.repeat(50) + '\n');
  console.log('🤖 启动 4 个专家 Agent：');
  console.log('  - syntax-checker: 语法和格式检查');
  console.log('  - logic-reviewer: 代码逻辑审查');
  console.log('  - security-scanner: 安全性检查');
  console.log('  - performance-analyzer: 性能优化建议');
  console.log('\n' + '='.repeat(50) + '\n');
  
  const task = '审查以下代码，从语法、逻辑、安全、性能四个维度提供详细报告';
  
  const result = await manager.coordinate(task + '\n\n' + codeToReview);
  
  console.log('\n' + '='.repeat(50));
  console.log('✅ 审查完成：');
  console.log(result);
  console.log('='.repeat(50));
}

// ============================================
// 运行
// ============================================

runExample().catch(console.error);


path: examples/plan-and-solve-example.js
content: /**
 * Plan-and-Solve Agent 示例 - 项目开发场景
 * 
 * 运行方式：node examples/plan-and-solve-example.js
 */

const { PlanAndSolveAgent } = require('../src/agents/plan-and-solve-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor() {
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    
    // 模拟 LLM 响应
    if (prompt.includes('请分析这个任务')) {
      return JSON.stringify({
        goal: '开发一个简单的待办事项 Web 应用',
        constraints: ['使用 JavaScript 技术栈', '开发时间<1 天', '支持基本 CRUD 操作'],
        successCriteria: ['可以添加待办', '可以删除待办', '可以标记完成', '界面简洁易用']
      });
    }
    
    if (prompt.includes('请制定详细的执行计划')) {
      return JSON.stringify({
        steps: [
          {
            id: 1,
            description: '设计数据模型',
            dependencies: [],
            expectedOutput: 'Todo 数据模型定义'
          },
          {
            id: 2,
            description: '创建 HTML 结构',
            dependencies: [],
            expectedOutput: 'HTML 文件'
          },
          {
            id: 3,
            description: '实现添加待办功能',
            dependencies: [1, 2],
            expectedOutput: '添加功能代码'
          },
          {
            id: 4,
            description: '实现删除待办功能',
            dependencies: [3],
            expectedOutput: '删除功能代码'
          },
          {
            id: 5,
            description: '实现标记完成功能',
            dependencies: [3],
            expectedOutput: '标记完成代码'
          },
          {
            id: 6,
            description: '添加 CSS 样式',
            dependencies: [2],
            expectedOutput: '样式文件'
          }
        ]
      });
    }
    
    if (prompt.includes('当前步骤：设计数据模型')) {
      return `// 数据模型
class Todo {
  constructor(id, title) {
    this.id = id;
    this.title = title;
    this.completed = false;
    this.createdAt = new Date();
  }
}`;
    }
    
    if (prompt.includes('当前步骤：创建 HTML 结构')) {
      return `<!DOCTYPE html>
<html>
<head>
  <title>Todo App</title>
</head>
<body>
  <h1>待办事项</h1>
  <input type="text" id="todo-input" placeholder="输入待办...">
  <button id="add-btn">添加</button>
  <ul id="todo-list"></ul>
</body>
</html>`;
    }
    
    if (prompt.includes('当前步骤：实现添加待办功能')) {
      return `// 添加待办
document.getElementById('add-btn').addEventListener('click', () => {
  const input = document.getElementById('todo-input');
  const title = input.value.trim();
  if (title) {
    const todo = new Todo(Date.now(), title);
    todos.push(todo);
    renderTodos();
    input.value = '';
  }
});`;
    }
    
    if (prompt.includes('当前步骤：实现删除待办功能')) {
      return `// 删除待办
function deleteTodo(id) {
  todos = todos.filter(todo => todo.id !== id);
  renderTodos();
}`;
    }
    
    if (prompt.includes('当前步骤：实现标记完成功能')) {
      return `// 标记完成
function toggleComplete(id) {
  const todo = todos.find(t => t.id === id);
  if (todo) {
    todo.completed = !todo.completed;
    renderTodos();
  }
}`;
    }
    
    if (prompt.includes('当前步骤：添加 CSS 样式')) {
      return `/* 样式 */
body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; }
#todo-input { padding: 10px; width: 70%; }
#add-btn { padding: 10px 20px; }
.todo-item { padding: 10px; border-bottom: 1px solid #eee; }
.todo-item.completed { text-decoration: line-through; color: #999; }
.delete-btn { color: red; cursor: pointer; }`;
    }
    
    if (prompt.includes('请整合所有执行结果')) {
      return `## 待办事项应用 - 开发完成

### 功能清单
✅ 添加待办事项
✅ 删除待办事项
✅ 标记完成状态
✅ 简洁界面

### 技术栈
- HTML5
- CSS3
- JavaScript (ES6+)

### 使用说明
1. 在输入框中输入待办内容
2. 点击"添加"按钮
3. 点击待办项可标记完成
4. 点击删除按钮可删除

### 代码结构
- index.html - HTML 结构
- style.css - 样式
- app.js - 应用逻辑

所有功能已完成并测试通过！`;
    }
    
    return 'Generated.';
  }
}

// ============================================
// 创建 Agent
// ============================================

const agent = new PlanAndSolveAgent({
  maxSteps: 20,
  verbose: true,
  llm: new MockLLM()
});

// ============================================
// 运行示例
// ============================================

async function runExample() {
  console.log('=== Plan-and-Solve Agent 示例 - 项目开发 ===\n');
  
  const task = '开发一个简单的待办事项 Web 应用，支持添加、删除、标记完成功能';
  
  console.log('📝 任务：项目开发\n');
  console.log('需求：' + task);
  console.log('\n' + '='.repeat(50) + '\n');
  
  const result = await agent.execute(task);
  
  console.log('\n' + '='.repeat(50));
  console.log('✅ 项目完成：');
  console.log(result);
  console.log('='.repeat(50));
}

// ============================================
// 运行
// ============================================

runExample().catch(console.error);


path: examples/react-example.js
content: /**
 * ReAct Agent 示例 - 单 Agent 架构模式
 * 
 * 运行方式：node examples/react-example.js
 */

const { ReActAgent } = require('../src/agents/react-agent');

// ============================================
// 1. 定义工具
// ============================================

const tools = {
  // 工具 1: 网络搜索
  search: {
    description: '搜索网络信息。适用于查询事实、新闻、数据等。',
    execute: async ({ query }) => {
      console.log(`  [Tool: search] Query: ${query}`);
      
      // 模拟搜索结果（实际实现调用搜索 API）
      const mockResults = {
        '北京 气温': '北京今天晴，最高气温 25°C，最低气温 15°C',
        '上海 气温': '上海今天多云，最高气温 22°C，最低气温 18°C',
        '珠穆朗玛峰 高度': '8848.86 米',
        'K2 高度': '8611 米',
        'JavaScript 创始人': 'Brendan Eich',
        'Python 创始人': 'Guido van Rossum'
      };
      
      return mockResults[query] || `未找到"${query}"的相关信息`;
    }
  },
  
  // 工具 2: 数学计算
  calculate: {
    description: '执行数学计算。适用于加减乘除、幂运算等。',
    execute: async ({ expression }) => {
      console.log(`  [Tool: calculate] Expression: ${expression}`);
      
      try {
        // 安全计算（实际实现应该用更安全的表达式解析器）
        const result = eval(expression);
        return result.toString();
      } catch (error) {
        return `计算错误：${error.message}`;
      }
    }
  },
  
  // 工具 3: 文件读取
  readFile: {
    description: '读取文件内容。适用于读取本地文件。',
    execute: async ({ path }) => {
      console.log(`  [Tool: readFile] Path: ${path}`);
      
      // 模拟文件读取（实际实现调用 fs.readFile）
      const mockFiles = {
        'config.json': '{"name": "my-app", "version": "1.0.0"}',
        'package.json': '{"name": "example", "dependencies": {"express": "^4.18.0"}}'
      };
      
      return mockFiles[path] || `文件不存在：${path}`;
    }
  }
};

// ============================================
// 2. 创建 Agent
// ============================================

const agent = new ReActAgent({
  tools,
  maxSteps: 10,
  verbose: true  // 启用详细日志
});

// ============================================
// 3. 运行示例
// ============================================

async function runExamples() {
  console.log('=== ReAct Agent 示例 ===\n');
  
  // 示例 1: 简单查询
  console.log('📝 示例 1: 简单查询');
  console.log('任务：北京今天的气温是多少？\n');
  
  const answer1 = await agent.execute('北京今天的气温是多少？');
  console.log(`\n答案：${answer1}\n`);
  console.log('---\n');
  
  // 示例 2: 比较查询
  console.log('📝 示例 2: 比较查询');
  console.log('任务：北京今天的气温比上海高还是低？\n');
  
  const answer2 = await agent.execute('北京今天的气温比上海高还是低？');
  console.log(`\n答案：${answer2}\n`);
  console.log('---\n');
  
  // 示例 3: 计算任务
  console.log('📝 示例 3: 计算任务');
  console.log('任务：珠穆朗玛峰比 K2 高多少米？\n');
  
  const answer3 = await agent.execute('珠穆朗玛峰比 K2 高多少米？');
  console.log(`\n答案：${answer3}\n`);
  console.log('---\n');
  
  // 示例 4: 多步骤任务
  console.log('📝 示例 4: 多步骤任务');
  console.log('任务：JavaScript 和 Python 的创始人是谁？他们分别是哪国人？\n');
  
  const answer4 = await agent.execute('JavaScript 和 Python 的创始人是谁？他们分别是哪国人？');
  console.log(`\n答案：${answer4}\n`);
  console.log('---\n');
  
  console.log('=== 示例完成 ===');
}

// ============================================
// 4. 运行
// ============================================

runExamples().catch(console.error);


path: examples/reflection-example.js
content: /**
 * Reflection Agent 示例 - 代码审查场景
 * 
 * 运行方式：node examples/reflection-example.js
 */

const { ReflectionAgent } = require('../src/agents/reflection-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor() {
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    
    // 模拟 LLM 响应
    if (prompt.includes('生成初始输出')) {
      return `function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}`;
    }
    
    if (prompt.includes('评估这个输出')) {
      if (this.callCount === 2) {
        return `反馈：

【问题】
1. 缺少边界条件处理：当 items 为空数组时，函数返回 0，但没有明确处理
2. 缺少错误处理：如果 items[i].price 或 items[i].quantity 不是数字，会导致计算错误
3. 缺少输入验证：没有检查 items 是否为数组
4. 代码风格：可以使用 reduce 方法使代码更简洁

【改进建议】
- 添加输入验证
- 添加边界条件处理
- 使用更现代 JavaScript 语法`;
      } else {
        return `反馈：

【评估】
代码质量已经很好，覆盖了主要问题。

【小建议】
- 可以添加 JSDoc 注释
- 可以考虑添加类型检查`;
      }
    }
    
    if (prompt.includes('根据反馈修改')) {
      if (this.callCount === 3) {
        return `/**
 * 计算商品总价
 * @param {Array} items - 商品数组
 * @returns {number} 总价
 */
function calculateTotal(items) {
  // 输入验证
  if (!Array.isArray(items) || items.length === 0) {
    return 0;
  }
  
  // 使用 reduce 方法计算
  return items.reduce((total, item) => {
    const price = Number(item.price) || 0;
    const quantity = Number(item.quantity) || 0;
    return total + price * quantity;
  }, 0);
}`;
      } else {
        return `/**
 * 计算商品总价（最终版本）
 * @param {Array} items - 商品数组
 * @returns {number} 总价
 */
function calculateTotal(items) {
  if (!Array.isArray(items) || items.length === 0) {
    return 0;
  }
  
  return items.reduce((total, item) => {
    const price = Number(item.price) || 0;
    const quantity = Number(item.quantity) || 0;
    return total + price * quantity;
  }, 0);
}`;
      }
    }
    
    return 'Generated output.';
  }
}

// ============================================
// 创建 Agent
// ============================================

const agent = new ReflectionAgent({
  maxIterations: 5,
  verbose: true,
  criteria: [
    '代码正确性：是否能正确运行，无 bug',
    '边界条件：是否处理了边界情况（空数组、null 等）',
    '错误处理：是否有输入验证和异常处理',
    '代码质量：是否遵循最佳实践，代码简洁',
    '可读性：是否有注释，命名是否清晰'
  ],
  llm: new MockLLM()
});

// ============================================
// 运行示例
// ============================================

async function runExample() {
  console.log('=== Reflection Agent 示例 - 代码审查 ===\n');
  
  const task = `审查并改进以下代码：

function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}`;

  console.log('📝 任务：代码审查与改进\n');
  console.log('原始代码：');
  console.log(task.split('\n').slice(2).join('\n'));
  console.log('\n' + '='.repeat(50) + '\n');
  
  const result = await agent.execute(task);
  
  console.log('\n' + '='.repeat(50));
  console.log('✅ 最终代码：');
  console.log(result);
  console.log('='.repeat(50));
}

// ============================================
// 运行
// ============================================

runExample().catch(console.error);


path: examples/self-critique-example.js
content: /**
 * Self-Critique Agent 示例 - 事实核查场景
 * 
 * 运行方式：node examples/self-critique-example.js
 */

const { SelfCritiqueAgent } = require('../src/agents/self-critique-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor() {
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    
    // 模拟 LLM 响应
    if (prompt.includes('请生成初始答案')) {
      return `珠穆朗玛峰是世界最高峰，高度为 8848 米。它位于中国和尼泊尔边境，属于喜马拉雅山脉。

第二高峰是 K2，高度为 8611 米，位于中国和巴基斯坦边境。

第三高峰是干城章嘉峰，高度为 8586 米，位于印度和尼泊尔边境。`;
    }
    
    if (prompt.includes('请按照以下错误类型进行系统检查')) {
      if (this.callCount === 2) {
        return JSON.stringify({
          errors: [
            {
              type: '事实错误',
              location: '第一段',
              description: '珠穆朗玛峰高度数据不够精确',
              reason: '珠穆朗玛峰的官方精确高度是 8848.86 米（2020 年测量），不是 8848 米',
              suggestion: '修正为 8848.86 米'
            },
            {
              type: '遗漏错误',
              location: '整体',
              description: '缺少形成时间、攀登历史等重要信息',
              reason: '对于山峰介绍，攀登历史和地质信息是重要内容',
              suggestion: '添加首次攀登时间、攀登难度等信息'
            }
          ],
          summary: '基本信息正确，但数据精度不足，缺少重要信息'
        });
      } else {
        return JSON.stringify({
          errors: [],
          summary: '信息准确完整，无明显错误'
        });
      }
    }
    
    if (prompt.includes('请修正所有错误')) {
      return `珠穆朗玛峰（Mount Everest）是世界最高峰，最新测量的精确高度为 8848.86 米（2020 年中国和尼泊尔联合测量）。它位于中国西藏自治区和尼泊尔边境，属于喜马拉雅山脉，地理坐标为北纬 27°59′17″，东经 86°55′31″。

**基本信息**：
- 高度：8848.86 米（雪面高程）
- 位置：中国西藏与尼泊尔边境
- 山脉：喜马拉雅山脉
- 首次攀登：1953 年，埃德蒙·希拉里和丹增·诺尔盖
- 攀登难度：极高（海拔高、氧气稀薄、气候恶劣）

**世界第二高峰**：
K2（乔戈里峰），高度 8611 米，位于中国和巴基斯坦边境，被认为是攀登难度最高的 8000 米级山峰。

**世界第三高峰**：
干城章嘉峰，高度 8586 米，位于印度和尼泊尔边境。`;
    }
    
    return 'Generated output.';
  }
}

// ============================================
// 创建 Agent
// ============================================

const agent = new SelfCritiqueAgent({
  maxIterations: 3,
  verbose: true,
  errorTypes: [
    {
      name: '事实错误',
      description: '数据、日期、人名、地名是否准确',
      checkpoints: [
        '数值数据是否精确',
        '日期是否准确',
        '人名地名是否正确'
      ]
    },
    {
      name: '遗漏错误',
      description: '是否缺少关键信息',
      checkpoints: [
        '是否回答了所有问题',
        '是否缺少必要的背景信息',
        '是否缺少重要数据'
      ]
    },
    {
      name: '逻辑错误',
      description: '推理是否严密',
      checkpoints: [
        '前后是否一致',
        '是否有矛盾',
        '因果关系是否正确'
      ]
    }
  ],
  llm: new MockLLM()
});

// ============================================
// 运行示例
// ============================================

async function runExample() {
  console.log('=== Self-Critique Agent 示例 - 事实核查 ===\n');
  
  const task = '介绍世界前三高峰，包括高度、位置等基本信息';
  
  console.log('📝 任务：事实核查\n');
  console.log('问题：' + task);
  console.log('\n' + '='.repeat(50) + '\n');
  
  const result = await agent.execute(task);
  
  console.log('\n' + '='.repeat(50));
  console.log('✅ 最终答案（经过自我批评和修正）：');
  console.log(result);
  console.log('='.repeat(50));
}

// ============================================
// 运行
// ============================================

runExample().catch(console.error);


path: examples/tree-of-thoughts-example.js
content: /**
 * Tree of Thoughts Agent 示例 - 创意设计场景
 * 
 * 运行方式：node examples/tree-of-thoughts-example.js
 */

const { TreeOfThoughtsAgent } = require('../src/agents/tree-of-thoughts-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor() {
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    
    // 模拟 LLM 响应
    if (prompt.includes('请生成') && prompt.includes('个不同的思考方向')) {
      const depth = (prompt.match(/Depth: (\d+)/) || [])[1] || 0;
      
      if (depth === 0) {
        // 初始思考
        return JSON.stringify([
          { thought: '开发一个 AI 健康助手应用，通过对话提供健康建议' },
          { thought: '创建智能健身教练，使用摄像头纠正运动姿势' },
          { thought: '设计心理健康陪伴机器人，提供情感支持和冥想指导' }
        ]);
      } else if (depth === 1) {
        // 第二轮思考
        return JSON.stringify([
          { thought: 'AI 健康助手 + 饮食追踪功能' },
          { thought: 'AI 健康助手 + 运动计划定制' },
          { thought: '智能健身教练 + 实时语音指导' },
          { thought: '心理健康机器人 + 睡眠监测' }
        ]);
      } else {
        // 第三轮思考
        return JSON.stringify([
          { thought: 'AI 健康助手 + 饮食 + 运动 + 睡眠综合管理' },
          { thought: '智能健身教练 + AR 眼镜实时指导' }
        ]);
      }
    }
    
    if (prompt.includes('请评估这个思考的质量')) {
      // 模拟评分
      const scores = [7.5, 8.2, 6.8, 8.5, 7.9, 9.2, 8.8];
      const score = scores[this.callCount % scores.length];
      return score.toString();
    }
    
    if (prompt.includes('请基于这个思考路径，生成最终的解决方案')) {
      return `## FitAI - 智能健身解决方案

### 产品定位
AI 驱动的个性化健身教练，通过计算机视觉和语音指导帮助用户正确锻炼。

### 核心功能

1. **动作识别与纠正**
   - 使用摄像头实时捕捉用户动作
   - AI 对比标准动作，提供实时纠正
   - 语音反馈："膝盖再弯曲一点"、"背部保持挺直"

2. **个性化训练计划**
   - 根据用户目标（减脂/增肌/塑形）定制计划
   - 动态调整难度
   - 进度追踪和成就系统

3. **智能饮食建议**
   - 拍照识别食物
   - 卡路里计算
   - 营养搭配建议

4. **社区与竞争**
   - 健身挑战
   - 好友排行榜
   - 成就分享

### 技术栈
- 计算机视觉：MediaPipe / OpenPose
- AI 引擎：自定义训练的动作识别模型
- 前端：React Native（跨平台）
- 后端：Node.js + Python

### 商业模式
- 免费基础版（有限功能）
- 高级版：$14.99/月（完整功能）
- 企业版：健身房合作

### 竞争优势
- 实时动作纠正（差异化）
- 个性化程度高
- 价格亲民

### MVP 计划
1. 核心功能：动作识别 + 基础训练（4 周）
2. 添加：个性化计划（2 周）
3. 添加：饮食功能（2 周）
4. 测试与发布（2 周）

总计：10 周完成 MVP`;
    }
    
    return 'Generated thought.';
  }
}

// ============================================
// 创建 Agent
// ============================================

const agent = new TreeOfThoughtsAgent({
  maxDepth: 3,
  branchFactor: 3,
  beamWidth: 2,
  verbose: true,
  llm: new MockLLM()
});

// ============================================
// 运行示例
// ============================================

async function runExample() {
  console.log('=== Tree of Thoughts Agent 示例 - 创意设计 ===\n');
  
  const task = '设计一个创新的 AI 健身应用，要有差异化竞争优势';
  
  console.log('📝 任务：创意设计\n');
  console.log('需求：' + task);
  console.log('\n' + '='.repeat(50) + '\n');
  
  const result = await agent.execute(task);
  
  console.log('\n' + '='.repeat(50));
  console.log('✅ 最终方案（经过多路径探索）：');
  console.log(result);
  console.log('='.repeat(50));
}

// ============================================
// 运行
// ============================================

runExample().catch(console.error);


path: package.json
content: {
  "name": "agent-architecture-patterns",
  "version": "1.0.0",
  "description": "AI Agent architecture patterns library",
  "main": "src/index.js",
  "scripts": {
    "test": "node tests/react-agent.test.js && node tests/manager-worker-agent.test.js",
    "test:react": "node tests/react-agent.test.js",
    "test:manager": "node tests/manager-worker-agent.test.js",
    "example:react": "node examples/react-example.js",
    "example:reflection": "node examples/reflection-example.js",
    "example:self-critique": "node examples/self-critique-example.js",
    "example:plan-solve": "node examples/plan-and-solve-example.js",
    "example:tot": "node examples/tree-of-thoughts-example.js",
    "example:manager-worker": "node examples/manager-worker-full-example.js"
  },
  "keywords": [
    "ai",
    "agent",
    "architecture",
    "patterns",
    "openclaw",
    "skill"
  ],
  "author": "AI-Agent",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-repo/agent-architecture-patterns"
  },
  "engines": {
    "node": ">=14.0.0"
  }
}


path: patterns/multi-agent/hierarchical.md
content: # 层级模式 (Hierarchical) - 多 Agent 协作

> **版本**: 1.0.0  
> **适用场景**: 大型复杂项目、需要多层协调、有明确组织结构的场景  
> **复杂度**: ⭐⭐⭐⭐（高）

---

## 🧠 核心思想

**层级模式 = 多层管理结构 + 分层决策**

- **分层管理**：CEO → Managers → Teams → Workers
- **分层决策**：战略决策在高层，执行决策在低层
- **信息传递**：自顶向下传递指令，自底向上汇报进度

**与主从模式的区别**：
- 主从模式：单层管理（1 个 Manager + N 个 Worker）
- 层级模式：多层管理（适合大规模系统）

---

## 📊 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                      CEO Agent                           │
│  （战略决策、资源分配、跨部门协调）                       │
└─────────────────────────────────────────────────────────┘
                          ↓
        ┌─────────────────┼─────────────────┐
        ↓                 ↓                 ↓
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Manager A     │ │ Manager B     │ │ Manager C     │
│ （技术部门）   │ │ （产品部门）   │ │ （运营部门）   │
└───────────────┘ └───────────────┘ └───────────────┘
        ↓                 ↓                 ↓
   ┌────┴────┐       ┌────┴────┐       ┌────┴────┐
   ↓         ↓       ↓         ↓       ↓         ↓
┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐
│Team │  │Team │  │Team │  │Team │  │Team │  │Team │
│ A1  │  │ A2  │  │ B1  │  │ B2  │  │ C1  │  │ C2  │
└─────┘  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class HierarchicalAgent {
  constructor(options = {}) {
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async execute(task, organization) {
    if (this.verbose) {
      console.log(`[Hierarchical] 开始任务：${task}`);
      console.log(`[Hierarchical] 组织结构：${this.describeOrg(organization)}`);
    }
    
    // Phase 1: CEO 制定战略
    const strategy = await organization.ceo.makeStrategy(task);
    
    if (this.verbose) {
      console.log(`[CEO Strategy] ${strategy}`);
    }
    
    // Phase 2: Managers 分解为部门计划
    const departmentPlans = await this.coordinateManagers(organization.managers, strategy);
    
    if (this.verbose) {
      console.log(`[Department Plans] ${departmentPlans.length}个部门计划`);
    }
    
    // Phase 3: Teams 执行具体任务
    const teamResults = await this.coordinateTeams(organization.teams, departmentPlans);
    
    if (this.verbose) {
      console.log(`[Team Results] ${teamResults.length}个团队结果`);
    }
    
    // Phase 4: 整合结果
    const finalResult = await this.integrateResults(task, teamResults);
    
    return finalResult;
  }

  async coordinateManagers(managers, strategy) {
    const plans = await Promise.all(
      managers.map(manager => manager.createPlan(strategy))
    );
    return plans;
  }

  async coordinateTeams(teams, departmentPlans) {
    const results = [];
    
    for (const plan of departmentPlans) {
      const team = teams.find(t => t.department === plan.department);
      if (team) {
        const result = await team.execute(plan);
        results.push(result);
      }
    }
    
    return results;
  }

  async integrateResults(task, results) {
    const prompt = `
任务：${task}

各部门结果：
${results.map((r, i) => `部门 ${i + 1}: ${r}`).join('\n')}

请整合所有结果，生成最终报告。

最终报告：`;
    
    return await this.llm.generate(prompt);
  }

  describeOrg(org) {
    return `CEO: ${org.ceo.id}, Managers: ${org.managers.length}, Teams: ${org.teams.length}`;
  }

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Completed.';
    }
  };
}

/**
 * CEO Agent
 */
class CEOAgent {
  constructor(id) {
    this.id = id;
    this.llm = null;
  }

  async makeStrategy(task) {
    const prompt = `
作为 CEO，请为以下任务制定战略：
${task}

考虑：
1. 总体目标
2. 资源分配
3. 关键里程碑
4. 风险管控

战略：`;
    
    return await this.llm.generate(prompt);
  }
}

/**
 * Manager Agent
 */
class ManagerAgent {
  constructor(id, department) {
    this.id = id;
    this.department = department;
    this.llm = null;
  }

  async createPlan(strategy) {
    const prompt = `
部门：${this.department}

公司战略：
${strategy}

请制定部门计划：
1. 部门目标
2. 具体任务
3. 所需资源
4. 时间表

部门计划：`;
    
    return await this.llm.generate(prompt);
  }
}

/**
 * Team Agent
 */
class TeamAgent {
  constructor(id, department, members) {
    this.id = id;
    this.department = department;
    this.members = members;
    this.llm = null;
  }

  async execute(plan) {
    const prompt = `
团队：${this.id}
部门：${this.department}

部门计划：
${plan}

请执行任务并报告结果。

结果：`;
    
    return await this.llm.generate(prompt);
  }
}
```

---

### 使用示例

```javascript
// 创建组织
const ceo = new CEOAgent('ceo-1');

const managers = [
  new ManagerAgent('mgr-1', '技术部'),
  new ManagerAgent('mgr-2', '产品部'),
  new ManagerAgent('mgr-3', '市场部')
];

const teams = [
  new TeamAgent('team-1', '技术部', ['dev1', 'dev2']),
  new TeamAgent('team-2', '产品部', ['pm1', 'pm2']),
  new TeamAgent('team-3', '市场部', ['marketing1'])
];

const organization = { ceo, managers, teams };

// 创建层级系统
const hierarchical = new HierarchicalAgent({ verbose: true });

// 执行任务
const task = '推出一个新的移动应用';
const result = await hierarchical.execute(task, organization);
console.log(result);
```

---

## 🎯 适用场景

### ✅ 适合的场景

1. **大型项目**：需要多层协调
2. **多部门协作**：有不同专业部门
3. **长期项目**：需要持续管理
4. **复杂决策**：需要分层决策

### ❌ 不适合的场景

1. **小型项目**：过度工程
2. **需要快速响应**：层级太多决策慢
3. **创新导向**：层级抑制创新
4. **资源有限**：管理成本高

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02


path: patterns/multi-agent/manager-worker.md
content: # 主从模式 (Manager-Worker) - 多 Agent 协作

> **版本**: 1.0.0  
> **适用场景**: 任务可分解、需要协调、有明确管理逻辑的场景  
> **复杂度**: ⭐⭐⭐（中等）

---

## 🧠 核心思想

**主从模式 = 1 个 Manager + N 个 Workers**

- **Manager（管理者）**: 负责任务分解、分配、协调、整合
- **Worker（工作者）**: 负责执行具体子任务

**优势**：
- 职责清晰（管理 vs 执行分离）
- 易于扩展（添加更多 Worker）
- 容错性强（单个 Worker 失败不影响整体）

---

## 📊 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                      Input Task                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    Manager Agent                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  1. Decompose (任务分解)                           │  │
│  │  2. Assign (任务分配)                              │  │
│  │  3. Monitor (进度监控)                             │  │
│  │  4. Integrate (结果整合)                           │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                    ↓           ↓           ↓
        ┌───────────┐   ┌───────────┐   ┌───────────┐
        │ Worker 1  │   │ Worker 2  │   │ Worker 3  │
        │  子任务 A  │   │  子任务 B  │   │  子任务 C  │
        └───────────┘   └───────────┘   └───────────┘
                ↓               ↓               ↓
            Result A        Result B        Result C
                    ↓           ↓           ↓
┌─────────────────────────────────────────────────────────┐
│                    Manager Agent                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  5. Aggregate (结果聚合)                           │  │
│  │  6. Validate (质量验证)                            │  │
│  │  7. Output (最终输出)                              │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
                  Final Output
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class ManagerAgent {
  constructor(workerAgents, options = {}) {
    this.workers = workerAgents;
    this.maxRetries = options.maxRetries || 3;
    this.timeout = options.timeout || 30000;
  }

  async coordinate(task) {
    console.log(`[Manager] 接收任务：${task}`);
    
    // Step 1: 任务分解
    const subtasks = await this.decompose(task);
    console.log(`[Manager] 分解为 ${subtasks.length} 个子任务`);
    
    // Step 2: 任务分配
    const assignments = this.assign(subtasks);
    console.log(`[Manager] 分配任务给 ${assignments.size} 个 Worker`);
    
    // Step 3: 并行执行
    const results = await this.executeParallel(assignments);
    console.log(`[Manager] 收到 ${results.length} 个结果`);
    
    // Step 4: 结果整合
    const finalResult = await this.integrate(task, results);
    console.log(`[Manager] 任务完成`);
    
    return finalResult;
  }

  async decompose(task) {
    // 调用 LLM 进行任务分解
    const prompt = `
将以下任务分解为独立的子任务：
${task}

要求：
1. 每个子任务应该是独立的
2. 子任务数量适中（3-10 个）
3. 明确每个子任务的目标

请以 JSON 数组格式返回：
[
  {
    "id": "task-1",
    "description": "子任务描述",
    "requiredSkills": ["技能 1", "技能 2"]
  }
]

子任务列表：`;
    
    const response = await this.callLLM(prompt);
    return JSON.parse(response);
  }

  assign(subtasks) {
    // 根据 Worker 能力分配任务
    const assignments = new Map();
    
    for (const subtask of subtasks) {
      const worker = this.selectWorker(subtask);
      if (!assignments.has(worker.id)) {
        assignments.set(worker.id, []);
      }
      assignments.get(worker.id).push(subtask);
    }
    
    return assignments;
  }

  selectWorker(subtask) {
    // 根据子任务所需技能选择最合适的 Worker
    const requiredSkills = subtask.requiredSkills || [];
    
    let bestWorker = null;
    let bestScore = -1;
    
    for (const worker of this.workers) {
      const score = this.calculateMatchScore(worker, requiredSkills);
      if (score > bestScore) {
        bestScore = score;
        bestWorker = worker;
      }
    }
    
    return bestWorker || this.workers[0];
  }

  calculateMatchScore(worker, requiredSkills) {
    // 计算 Worker 技能匹配度
    const workerSkills = new Set(worker.skills || []);
    const matchedSkills = requiredSkills.filter(skill => 
      workerSkills.has(skill)
    );
    return matchedSkills.length / (requiredSkills.length || 1);
  }

  async executeParallel(assignments) {
    const promises = [];
    
    for (const [workerId, subtasks] of assignments) {
      const worker = this.workers.find(w => w.id === workerId);
      
      const promise = Promise.all(
        subtasks.map(subtask => this.executeWithRetry(worker, subtask))
      );
      
      promises.push(promise);
    }
    
    const results = await Promise.all(promises);
    return results.flat();
  }

  async executeWithRetry(worker, subtask) {
    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
      try {
        const result = await Promise.race([
          worker.execute(subtask),
          this.timeoutPromise(this.timeout)
        ]);
        
        return {
          taskId: subtask.id,
          success: true,
          result,
          worker: worker.id
        };
      } catch (error) {
        console.warn(`[Worker ${worker.id}] 尝试 ${attempt} 失败: ${error.message}`);
        
        if (attempt === this.maxRetries) {
          return {
            taskId: subtask.id,
            success: false,
            error: error.message,
            worker: worker.id
          };
        }
      }
    }
  }

  timeoutPromise(timeout) {
    return new Promise((_, reject) => {
      setTimeout(() => reject(new Error('Timeout')), timeout);
    });
  }

  async integrate(task, results) {
    // 调用 LLM 整合结果
    const successfulResults = results.filter(r => r.success);
    const failedResults = results.filter(r => !r.success);
    
    const prompt = `
原始任务：${task}

成功执行的结果 (${successfulResults.length}个):
${JSON.stringify(successfulResults.map(r => r.result), null, 2)}

失败的结果 (${failedResults.length}个):
${JSON.stringify(failedResults, null, 2)}

请整合所有成功结果，生成最终答案。如果有失败的任务，说明影响。

最终答案：`;
    
    return await this.callLLM(prompt);
  }

  async callLLM(prompt) {
    // 调用大语言模型
    const response = await llm.generate(prompt);
    return response;
  }
}

// Worker Agent 类
class WorkerAgent {
  constructor(id, skills, capabilities) {
    this.id = id;
    this.skills = skills;
    this.capabilities = capabilities;
  }

  async execute(subtask) {
    console.log(`[Worker ${this.id}] 执行任务：${subtask.description}`);
    
    // 根据任务类型调用不同能力
    if (this.capabilities.codeReview) {
      return await this.reviewCode(subtask);
    } else if (this.capabilities.webSearch) {
      return await this.searchWeb(subtask);
    } else if (this.capabilities.dataAnalysis) {
      return await this.analyzeData(subtask);
    } else {
      return await this.genericExecute(subtask);
    }
  }

  async reviewCode(subtask) {
    // 代码审查实现
    const code = subtask.code;
    const issues = [];
    
    // 调用静态分析工具
    const analysis = await this.runStaticAnalysis(code);
    issues.push(...analysis);
    
    // 调用 LLM 进行代码审查
    const prompt = `审查以下代码：
${code}

关注点：
- 代码质量
- 潜在 bug
- 性能问题
- 安全漏洞

审查结果：`;
    
    const review = await this.callLLM(prompt);
    issues.push(review);
    
    return { issues, suggestions: review };
  }

  async searchWeb(subtask) {
    // 网络搜索实现
    const query = subtask.query;
    const results = await webSearch(query);
    return results;
  }

  async analyzeData(subtask) {
    // 数据分析实现
    const data = subtask.data;
    const analysis = await this.runAnalysis(data);
    return analysis;
  }

  async genericExecute(subtask) {
    // 通用执行
    const prompt = `执行以下任务：
${subtask.description}

结果：`;
    
    return await this.callLLM(prompt);
  }

  async callLLM(prompt) {
    const response = await llm.generate(prompt);
    return response;
  }

  async runStaticAnalysis(code) {
    // 调用静态分析工具（如 ESLint）
    // 这里简化实现
    return [];
  }

  async runAnalysis(data) {
    // 调用数据分析工具
    // 这里简化实现
    return { summary: 'Analysis result' };
  }
}
```

---

### 使用示例

```javascript
// 创建 Worker Agents
const workers = [
  new WorkerAgent('worker-1', ['javascript', 'python'], {
    codeReview: true,
    webSearch: false,
    dataAnalysis: false
  }),
  
  new WorkerAgent('worker-2', ['research', 'writing'], {
    codeReview: false,
    webSearch: true,
    dataAnalysis: false
  }),
  
  new WorkerAgent('worker-3', ['statistics', 'visualization'], {
    codeReview: false,
    webSearch: false,
    dataAnalysis: true
  })
];

// 创建 Manager Agent
const manager = new ManagerAgent(workers, {
  maxRetries: 3,
  timeout: 30000
});

// 执行复杂任务
const task = '分析这个 GitHub 项目的代码质量，并搜索相关技术文章';
const result = await manager.coordinate(task);

console.log(result);
```

---

### 执行轨迹示例

```
[Manager] 接收任务：分析这个 GitHub 项目的代码质量，并搜索相关技术文章

[Manager] 分解为 4 个子任务：
  - task-1: 下载并分析项目代码结构
  - task-2: 执行代码静态分析
  - task-3: 搜索项目相关技术文章
  - task-4: 总结分析结果

[Manager] 分配任务给 3 个 Worker：
  - worker-1: [task-1, task-2] (代码分析能力)
  - worker-2: [task-3] (搜索能力)
  - worker-3: [task-4] (分析总结能力)

[Worker worker-1] 执行任务：下载并分析项目代码结构
[Worker worker-1] 执行任务：执行代码静态分析
[Worker worker-2] 执行任务：搜索项目相关技术文章

[Manager] 收到 4 个结果

[Manager] 整合结果，生成最终答案

[Manager] 任务完成

最终答案：
## 代码质量分析报告

### 项目结构
- 语言：JavaScript/TypeScript
- 文件数：156
- 代码行数：12,450

### 静态分析结果
- 代码风格问题：23 个
- 潜在 Bug：5 个
- 性能问题：3 个
- 安全漏洞：1 个（中危）

### 相关技术文章
1. "Modern JavaScript Best Practices" - Medium
2. "TypeScript for Large Projects" - Dev.to
3. "Security in Node.js Applications" - OWASP

### 建议
1. 修复 1 个安全漏洞（优先级高）
2. 重构 3 个性能热点
3. 统一代码风格
```

---

## 🎯 关键设计要点

### 1. 任务分解策略

**好的分解**：
- 子任务独立（可并行执行）
- 粒度适中（不太大也不太小）
- 目标明确（有清晰的完成标准）

**分解示例**：
```javascript
// ❌ 不好的分解（子任务有依赖）
[
  "写代码",
  "测试代码",  // 依赖"写代码"完成
  "部署代码"   // 依赖"测试代码"通过
]

// ✅ 好的分解（子任务独立）
[
  "编写用户认证模块",
  "编写数据访问模块",
  "编写 API 路由模块"
]
```

---

### 2. Worker 选择策略

**选择维度**：
- **技能匹配**：Worker 技能与任务需求匹配度
- **负载均衡**：避免某些 Worker 过载
- **历史表现**：选择历史成功率高的 Worker

**实现**：
```javascript
selectWorker(subtask) {
  const scores = this.workers.map(worker => ({
    worker,
    skillMatch: this.calculateMatchScore(worker, subtask.requiredSkills),
    load: this.getCurrentLoad(worker),
    successRate: worker.getSuccessRate()
  }));
  
  // 综合评分
  scores.forEach(score => {
    score.total = score.skillMatch * 0.5 + 
                  (1 - score.load) * 0.3 + 
                  score.successRate * 0.2;
  });
  
  return scores.sort((a, b) => b.total - a.total)[0].worker;
}
```

---

### 3. 容错机制

**重试策略**：
```javascript
async executeWithRetry(worker, subtask) {
  for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
    try {
      return await worker.execute(subtask);
    } catch (error) {
      if (attempt === this.maxRetries) {
        // 最后一次失败，尝试重新分配
        const backupWorker = this.findBackupWorker(worker);
        if (backupWorker) {
          return await backupWorker.execute(subtask);
        }
        throw error;
      }
      // 等待后重试（指数退避）
      await this.sleep(1000 * Math.pow(2, attempt));
    }
  }
}
```

---

### 4. 结果整合策略

**整合方式**：
- **简单拼接**：结果直接拼接
- **摘要总结**：LLM 总结关键点
- **结构化整合**：按模板组织结果

**实现**：
```javascript
async integrate(task, results) {
  const template = `
# ${task}

## 执行摘要
${this.generateSummary(results)}

## 详细结果
${this.formatResults(results)}

## 质量评估
${this.assessQuality(results)}

## 建议
${this.generateRecommendations(results)}
`;
  
  return template;
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：任务分解不合理

**现象**：子任务之间有强依赖，无法并行。

**解决方案**：
```javascript
async decompose(task) {
  const prompt = `
将任务分解为**独立可并行执行**的子任务：
${task}

约束：
1. 子任务之间不能有依赖
2. 每个子任务可以单独完成
3. 所有子任务完成后，可以整合出最终结果
`;
  // ...
}
```

---

### 问题 2：Worker 负载不均

**现象**：某些 Worker 很忙，某些空闲。

**解决方案**：
```javascript
assign(subtasks) {
  // 考虑当前负载
  const assignments = new Map();
  const loads = new Map(this.workers.map(w => [w.id, 0]));
  
  for (const subtask of subtasks) {
    // 选择负载最低且技能匹配的 Worker
    const worker = this.workers
      .filter(w => this.skillsMatch(w, subtask))
      .sort((a, b) => loads.get(a.id) - loads.get(b.id))[0];
    
    if (!assignments.has(worker.id)) {
      assignments.set(worker.id, []);
    }
    assignments.get(worker.id).push(subtask);
    loads.set(worker.id, loads.get(worker.id) + 1);
  }
  
  return assignments;
}
```

---

### 问题 3：结果质量不一致

**现象**：不同 Worker 输出质量差异大。

**解决方案**：
```javascript
// 添加质量验证
async validate(result) {
  const prompt = `
评估以下结果的质量：
${JSON.stringify(result)}

评估维度：
1. 完整性（0-10）
2. 准确性（0-10）
3. 相关性（0-10）

如果任何维度<7，返回需要改进的地方。

评估结果：`;
  
  const evaluation = await this.callLLM(prompt);
  return evaluation;
}

// 低质量结果要求重新执行
if (qualityScore < 7) {
  return await this.executeWithRetry(worker, subtask);
}
```

---

## 🔧 优化技巧

### 1. 动态 Worker 池

根据任务需求动态创建/销毁 Worker：

```javascript
class DynamicManagerAgent extends ManagerAgent {
  async coordinate(task) {
    // 分析任务需要的技能
    const requiredSkills = await this.analyzeTaskSkills(task);
    
    // 检查现有 Worker
    const availableSkills = new Set(
      this.workers.flatMap(w => w.skills)
    );
    
    // 创建缺失技能的 Worker
    for (const skill of requiredSkills) {
      if (!availableSkills.has(skill)) {
        const newWorker = await this.createWorker(skill);
        this.workers.push(newWorker);
      }
    }
    
    return await super.coordinate(task);
  }
  
  async createWorker(skill) {
    // 动态创建 specialized Worker
    return new WorkerAgent(`worker-${skill}`, [skill], {
      [skill]: true
    });
  }
}
```

---

### 2. 结果缓存

避免重复执行相同任务：

```javascript
class CachedManagerAgent extends ManagerAgent {
  constructor(...args) {
    super(...args);
    this.cache = new Map();
  }
  
  async executeWithRetry(worker, subtask) {
    const cacheKey = this.hashSubtask(subtask);
    
    if (this.cache.has(cacheKey)) {
      console.log(`[Cache Hit] ${cacheKey}`);
      return this.cache.get(cacheKey);
    }
    
    const result = await super.executeWithRetry(worker, subtask);
    this.cache.set(cacheKey, result);
    
    return result;
  }
  
  hashSubtask(subtask) {
    return crypto
      .createHash('md5')
      .update(subtask.description)
      .digest('hex');
  }
}
```

---

### 3. 进度监控

实时监控任务执行进度：

```javascript
class MonitoredManagerAgent extends ManagerAgent {
  async coordinate(task) {
    const progress = {
      total: 0,
      completed: 0,
      failed: 0,
      startTime: Date.now()
    };
    
    const subtasks = await this.decompose(task);
    progress.total = subtasks.length;
    
    // 定期报告进度
    const progressInterval = setInterval(() => {
      console.log(`[Progress] ${progress.completed}/${progress.total} ` +
                  `(失败：${progress.failed}, 耗时：${Date.now() - progress.startTime}ms)`);
    }, 5000);
    
    try {
      const results = await this.executeParallel(/* ... */);
      progress.completed = results.filter(r => r.success).length;
      progress.failed = results.filter(r => !r.success).length;
      
      return await this.integrate(task, results);
    } finally {
      clearInterval(progressInterval);
      console.log(`[Progress] 完成：${progress.completed}/${progress.total}`);
    }
  }
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **任务完成率** | 成功完成的任务比例 | >95% |
| **并行效率** | 并行执行时间 / 串行执行时间 | <0.3 |
| **Worker 利用率** | Worker 忙碌时间比例 | >70% |
| **结果质量** | 整合结果的质量评分 | >8/10 |

---

### 优化方向

1. **提高并行度**：更好地任务分解
2. **减少等待**：优化任务分配
3. **提高质量**：添加质量验证
4. **降低成本**：复用 Worker、缓存结果

---

## 🔗 相关模式

- **流水线模式**：顺序处理，适合有依赖的任务
- **对等模式**：平等协作，适合讨论型任务
- **ReAct**：单 Agent 的推理 + 行动模式

---

## 📚 参考资源

- **CrewAI**: https://github.com/joaomdmoura/crewAI
- **AutoGen**: https://github.com/microsoft/autogen
- **Multi-Agent Collaboration Survey**: https://arxiv.org/abs/2308.01126

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: patterns/multi-agent/market-based.md
content: # 市场模式 (Market-Based) - 多 Agent 协作

> **版本**: 1.0.0  
> **适用场景**: 动态任务分配、Agent 能力差异大、需要优化资源的场景  
> **复杂度**: ⭐⭐⭐⭐（高）

---

## 🧠 核心思想

**市场模式 = 任务竞价 + 市场机制**

- **任务发布**：任务作为"商品"在市场上发布
- **Agent 竞价**：Agent 根据自身能力出价
- **价高者得**：选择最优 bid 的 Agent 执行
- **支付机制**：完成后获得"报酬"（积分、优先级等）

**核心优势**：
- **自组织**：无需中央计划，市场自动调节
- **效率优化**：任务自动流向最合适的 Agent
- **动态适应**：Agent 负载变化时自动调整

---

## 📊 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                   Task Marketplace                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Task A    │  │   Task B    │  │   Task C    │     │
│  │ Budget: 100 │  │ Budget: 200 │  │ Budget: 150 │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
              ↓               ↓               ↓
        ┌─────┴─────┐   ┌─────┴─────┐   ┌─────┴─────┐
        ↓           ↓   ↓           ↓   ↓           ↓
   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent 4 │
   │  Bid: 90│ │  Bid: 95│ │ Bid: 140│ │ Bid: 160│
   └─────────┘ └─────────┘ └─────────┘ └─────────┘
        ↓           ↓           ↓           ↓
   ✅ 获得     ❌ 失败    ✅ 获得     ❌ 失败
   Task A      Task A    Task C      Task C
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class MarketBasedAgent {
  constructor(options = {}) {
    this.agents = options.agents || [];
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
    this.market = new Marketplace();
  }

  async execute(tasks) {
    if (this.verbose) {
      console.log(`[Market] 开始分配 ${tasks.length} 个任务`);
    }
    
    // Phase 1: 发布任务
    const postedTasks = await this.postTasks(tasks);
    
    if (this.verbose) {
      console.log(`[Market] 发布 ${postedTasks.length} 个任务`);
    }
    
    // Phase 2: Agent 竞价
    const bids = await this.collectBids(postedTasks);
    
    if (this.verbose) {
      console.log(`[Market] 收到 ${bids.length} 个竞价`);
    }
    
    // Phase 3: 分配任务
    const assignments = this.assignTasks(postedTasks, bids);
    
    if (this.verbose) {
      console.log(`[Market] 分配 ${assignments.length} 个任务`);
    }
    
    // Phase 4: 执行任务
    const results = await this.executeTasks(assignments);
    
    // Phase 5: 结算
    await this.settlePayments(assignments, results);
    
    return results;
  }

  async postTasks(tasks) {
    const postedTasks = [];
    
    for (const task of tasks) {
      const postedTask = await this.market.postTask(task);
      postedTasks.push(postedTask);
    }
    
    return postedTasks;
  }

  async collectBids(tasks) {
    const allBids = [];
    
    for (const task of tasks) {
      const bids = await Promise.all(
        this.agents.map(agent => agent.submitBid(task))
      );
      allBids.push(...bids);
    }
    
    return allBids;
  }

  assignTasks(tasks, bids) {
    const assignments = [];
    
    for (const task of tasks) {
      // 找到所有对该任务的竞价
      const taskBids = bids.filter(bid => bid.taskId === task.id);
      
      if (taskBids.length === 0) {
        if (this.verbose) {
          console.warn(`[Market] 任务 ${task.id} 无竞价`);
        }
        continue;
      }
      
      // 选择最优竞价（最高分/最低价格）
      const bestBid = taskBids.sort((a, b) => b.score - a.score)[0];
      
      assignments.push({
        task,
        agent: bestBid.agent,
        bid: bestBid
      });
      
      if (this.verbose) {
        console.log(`[Market] 任务 ${task.id} → Agent ${bestBid.agent.id} (分数：${bestBid.score})`);
      }
    }
    
    return assignments;
  }

  async executeTasks(assignments) {
    const results = [];
    
    for (const assignment of assignments) {
      const result = await assignment.agent.execute(assignment.task);
      results.push({
        task: assignment.task,
        agent: assignment.agent,
        result,
        success: true
      });
    }
    
    return results;
  }

  async settlePayments(assignments, results) {
    for (const result of results) {
      if (result.success) {
        await this.market.pay(result.agent, result.task.budget);
      }
    }
  }

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Completed.';
    }
  };
}

/**
 * 市场
 */
class Marketplace {
  constructor() {
    this.tasks = new Map();
    this.agents = new Map();
    this.taskIdCounter = 0;
  }

  async postTask(task) {
    const id = `task-${++this.taskIdCounter}`;
    const postedTask = {
      id,
      description: task.description,
      budget: task.budget || 100,
      requirements: task.requirements || [],
      deadline: task.deadline || Date.now() + 3600000
    };
    this.tasks.set(id, postedTask);
    return postedTask;
  }

  async pay(agent, amount) {
    // 简化实现
    console.log(`[Market] 支付 ${amount} 给 Agent ${agent.id}`);
  }
}

/**
 * 市场 Agent
 */
class MarketAgent {
  constructor(id, skills, budget = 1000) {
    this.id = id;
    this.skills = skills || [];
    this.budget = budget;
    this.completedTasks = 0;
    this.llm = null;
  }

  async submitBid(task) {
    // 计算能力匹配度
    const skillMatch = this.calculateSkillMatch(task.requirements);
    
    // 计算负载（预算越少越不想接）
    const loadFactor = this.budget / 1000;
    
    // 计算竞价分数
    const score = skillMatch * 0.7 + loadFactor * 0.3;
    
    return {
      taskId: task.id,
      agent: this,
      score,
      bid: task.budget * (1 - skillMatch * 0.2) // 技能越匹配，要价越低
    };
  }

  calculateSkillMatch(requirements) {
    if (requirements.length === 0) return 0.5;
    
    const matchedSkills = requirements.filter(skill => 
      this.skills.includes(skill)
    ).length;
    
    return matchedSkills / requirements.length;
  }

  async execute(task) {
    const prompt = `
执行任务：${task.description}

技能：${this.skills.join(', ')}

结果：`;
    
    return await this.llm.generate(prompt);
  }
}
```

---

### 使用示例

```javascript
// 创建 Agent
const agents = [
  new MarketAgent('agent-1', ['javascript', 'react'], 1000),
  new MarketAgent('agent-2', ['python', 'ml'], 800),
  new MarketAgent('agent-3', ['javascript', 'nodejs'], 1200),
  new MarketAgent('agent-4', ['python', 'data'], 900)
];

// 创建市场系统
const market = new MarketBasedAgent({
  agents,
  verbose: true
});

// 发布任务
const tasks = [
  { description: '开发 React 组件', budget: 150, requirements: ['javascript', 'react'] },
  { description: '训练 ML 模型', budget: 200, requirements: ['python', 'ml'] },
  { description: '开发 Node.js API', budget: 180, requirements: ['javascript', 'nodejs'] }
];

// 执行
const results = await market.execute(tasks);
console.log(results);
```

---

## 🎯 适用场景

### ✅ 适合的场景

1. **动态任务**：任务随时到达
2. **异构 Agent**：Agent 能力差异大
3. **资源优化**：需要最优分配
4. **大规模系统**：Agent 数量多

### ❌ 不适合的场景

1. **任务有依赖**：需要协调
2. **紧急任务**：竞价耗时
3. **同质 Agent**：能力相似
4. **小系统**：过度复杂

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02


path: patterns/multi-agent/peer-to-peer.md
content: # 对等模式 (Peer-to-Peer) - 多 Agent 协作

> **版本**: 1.0.0  
> **适用场景**: 任务可并行、Agent 能力相似、需要协作讨论的场景  
> **复杂度**: ⭐⭐（中低）

---

## 🧠 核心思想

**对等模式 = 多个平等 Agent + 协作共识**

- **平等关系**：没有管理者，所有 Agent 地位平等
- **协作讨论**：通过对话、辩论达成共识
- **并行执行**：各自执行独立任务，然后整合

**与主从模式的区别**：
- 主从模式：1 个 Manager 决策，Worker 执行
- 对等模式：所有 Agent 平等，共同决策

---

## 📊 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                      Input Task                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              Distributed Discussion                      │
│    Agent1 ←→ Agent2 ←→ Agent3 ←→ ...                    │
│       ↑        ↑         ↑                               │
│       └────────┴─────────┘                               │
│            平等讨论、辩论、共识                           │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              Parallel Execution                          │
│    Agent1      Agent2      Agent3                        │
│   子任务 A     子任务 B     子任务 C                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              Result Integration                          │
│         投票/共识/合并 → Final Output                    │
└─────────────────────────────────────────────────────────┘
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class PeerToPeerAgent {
  constructor(agents, options = {}) {
    this.agents = agents;
    this.consensusThreshold = options.consensusThreshold || 0.6; // 60% 同意
    this.maxRounds = options.maxRounds || 3;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async collaborate(task) {
    if (this.verbose) {
      console.log(`[P2P] 开始协作任务：${task}`);
      console.log(`[P2P] 参与 Agent: ${this.agents.length}个`);
    }
    
    // Phase 1: 讨论
    const discussionResult = await this.discuss(task);
    
    if (this.verbose) {
      console.log(`[P2P] 讨论完成，达成共识：${discussionResult.consensus}`);
    }
    
    // Phase 2: 并行执行
    const executionResults = await this.executeParallel(task, discussionResult.plan);
    
    if (this.verbose) {
      console.log(`[P2P] 执行完成，收到 ${executionResults.length} 个结果`);
    }
    
    // Phase 3: 整合
    const finalResult = await this.integrate(task, executionResults);
    
    return finalResult;
  }

  /**
   * Phase 1: 讨论达成共识
   */
  async discuss(task) {
    const discussionHistory = [];
    
    for (let round = 1; round <= this.maxRounds; round++) {
      if (this.verbose) {
        console.log(`\n[Round ${round}/${this.maxRounds}]`);
      }
      
      // 每个 Agent 发表观点
      const opinions = await this.collectOpinions(task, discussionHistory);
      
      if (this.verbose) {
        opinions.forEach((op, i) => {
          console.log(`  [Agent ${i + 1}] ${opinion.summary}`);
        });
      }
      
      // 检查是否达成共识
      const consensus = this.checkConsensus(opinions);
      
      if (consensus.reached) {
        if (this.verbose) {
          console.log(`[Consensus Reached] ${consensus.agreement}`);
        }
        
        return {
          consensus: true,
          agreement: consensus.agreement,
          plan: consensus.plan
        };
      }
      
      // 记录讨论历史
      discussionHistory.push({ round, opinions });
    }
    
    // 未达到共识，取多数意见
    if (this.verbose) {
      console.log('[No Consensus] 使用多数意见');
    }
    
    const majorityOpinion = this.getMajorityOpinion(opinions);
    return {
      consensus: false,
      agreement: majorityOpinion.summary,
      plan: majorityOpinion.plan
    };
  }

  /**
   * 收集所有 Agent 的观点
   */
  async collectOpinions(task, history) {
    const opinions = await Promise.all(
      this.agents.map(agent => agent.formOpinion(task, history))
    );
    return opinions;
  }

  /**
   * 检查是否达成共识
   */
  checkConsensus(opinions) {
    // 计算相似度
    const similarityMatrix = this.calculateSimilarity(opinions);
    
    // 找到最大的共识群体
    const largestGroup = this.findLargestConsensusGroup(similarityMatrix);
    const agreementRatio = largestGroup.length / opinions.length;
    
    if (agreementRatio >= this.consensusThreshold) {
      return {
        reached: true,
        agreement: opinions[largestGroup[0]].summary,
        plan: opinions[largestGroup[0]].plan
      };
    }
    
    return { reached: false };
  }

  /**
   * 计算意见相似度矩阵
   */
  calculateSimilarity(opinions) {
    const n = opinions.length;
    const matrix = [];
    
    for (let i = 0; i < n; i++) {
      matrix[i] = [];
      for (let j = 0; j < n; j++) {
        if (i === j) {
          matrix[i][j] = 1.0;
        } else {
          matrix[i][j] = this.computeSimilarity(opinions[i], opinions[j]);
        }
      }
    }
    
    return matrix;
  }

  /**
   * 计算两个意见的相似度
   */
  computeSimilarity(op1, op2) {
    // 简化实现：基于关键词重叠
    const keywords1 = new Set(op1.summary.toLowerCase().split(/\s+/));
    const keywords2 = new Set(op2.summary.toLowerCase().split(/\s+/));
    
    const intersection = [...keywords1].filter(k => keywords2.has(k)).length;
    const union = new Set([...keywords1, ...keywords2]).size;
    
    return intersection / union;
  }

  /**
   * 找到最大的共识群体
   */
  findLargestConsensusGroup(similarityMatrix) {
    const n = similarityMatrix.length;
    const threshold = 0.7; // 相似度>70% 认为是一组
    const visited = new Set();
    const groups = [];
    
    for (let i = 0; i < n; i++) {
      if (!visited.has(i)) {
        const group = [i];
        visited.add(i);
        
        for (let j = i + 1; j < n; j++) {
          if (!visited.has(j) && similarityMatrix[i][j] >= threshold) {
            group.push(j);
            visited.add(j);
          }
        }
        
        groups.push(group);
      }
    }
    
    // 返回最大的群体
    return groups.sort((a, b) => b.length - a.length)[0] || [];
  }

  /**
   * 获取多数意见
   */
  getMajorityOpinion(opinions) {
    // 简化实现：返回第一个（实际应该聚类）
    return opinions[0];
  }

  /**
   * Phase 2: 并行执行
   */
  async executeParallel(task, plan) {
    const subtasks = this.decomposeByAgents(task, plan);
    
    const results = await Promise.all(
      subtasks.map((subtask, i) => 
        this.agents[i].execute(subtask)
      )
    );
    
    return results;
  }

  /**
   * 按 Agent 分解任务
   */
  decomposeByAgents(task, plan) {
    // 简化实现：平均分配
    const subtasks = [];
    for (let i = 0; i < this.agents.length; i++) {
      subtasks.push({
        description: `${task} - 部分 ${i + 1}/${this.agents.length}`,
        agent: this.agents[i]
      });
    }
    return subtasks;
  }

  /**
   * Phase 3: 整合结果
   */
  async integrate(task, results) {
    // 投票整合
    const votes = await Promise.all(
      results.map(result => this.vote(task, result))
    );
    
    // 选择得票最高的结果
    const bestIndex = votes.indexOf(Math.max(...votes));
    return results[bestIndex];
  }

  /**
   * 投票
   */
  async vote(task, result) {
    // 简化实现：返回随机分数
    return Math.random();
  }

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated.';
    }
  };
}

/**
 * 对等 Agent
 */
class PeerAgent {
  constructor(id, expertise) {
    this.id = id;
    this.expertise = expertise;
    this.llm = null;
  }

  async formOpinion(task, history) {
    const prompt = `
任务：${task}

你的专业领域：${this.expertise}

讨论历史：
${this.formatHistory(history)}

请发表你的观点：
1. 你对任务的理解
2. 你建议的方案
3. 你的理由

观点：`;
    
    const summary = await this.llm.generate(prompt);
    
    return {
      agent: this.id,
      summary,
      plan: this.extractPlan(summary)
    };
  }

  async execute(subtask) {
    const prompt = `
执行任务：${subtask.description}

专业领域：${this.expertise}

结果：`;
    
    return await this.llm.generate(prompt);
  }

  formatHistory(history) {
    if (history.length === 0) return '（无）';
    
    return history.map(h => 
      `Round ${h.round}:\n${h.opinions.map(op => `  - ${op.agent}: ${op.summary}`).join('\n')}`
    ).join('\n\n');
  }

  extractPlan(summary) {
    // 从观点中提取计划
    return summary;
  }
}
```

---

### 使用示例

```javascript
// 创建对等 Agent
const agents = [
  new PeerAgent('agent-1', '前端开发'),
  new PeerAgent('agent-2', '后端开发'),
  new PeerAgent('agent-3', '数据库设计'),
  new PeerAgent('agent-4', '用户体验')
];

// 创建协作系统
const p2p = new PeerToPeerAgent(agents, {
  consensusThreshold: 0.6,
  maxRounds: 3,
  verbose: true
});

// 执行任务
const task = '设计一个电商网站的技术方案';
const result = await p2p.collaborate(task);
console.log(result);
```

---

## 🎯 适用场景

### ✅ 适合的场景

1. **需要多视角**：任务需要不同专业视角
2. **无明确领导**：没有天然的管理者
3. **鼓励创新**：需要多样化的想法
4. **并行任务**：任务可以分解为独立子任务

### ❌ 不适合的场景

1. **需要快速决策**：讨论耗时
2. **有明确权威**：已有专家或领导
3. **任务高度依赖**：子任务之间有强依赖
4. **资源有限**：Agent 数量少

---

## 🔗 相关模式

- **主从模式**：有明确管理者的场景
- **层级模式**：大型复杂项目
- **Reflection**：可以结合自我反思

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02


path: patterns/multi-agent/pipeline.md
content: # 流水线模式 (Pipeline) - 多 Agent 协作

> **版本**: 1.0.0  
> **适用场景**: 多阶段处理、阶段间有依赖、需要专业化的场景  
> **复杂度**: ⭐⭐⭐（中高）

---

## 🧠 核心思想

**流水线模式 = 顺序处理 + 专业化分工**

- **顺序处理**：Input → Stage 1 → Stage 2 → ... → Output
- **专业化**：每个 Agent 专注于一个阶段
- **依赖传递**：前一阶段的输出是后一阶段的输入

**类比**：
- 工厂流水线：原材料 → 加工 → 组装 → 质检 → 成品
- 内容创作：选题 → 大纲 → 写作 → 编辑 → 发布

---

## 📊 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                      Input                               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Stage 1: Agent A (专业：X)                              │
│  Input: 原始数据                                         │
│  Output: 处理结果 A                                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Stage 2: Agent B (专业：Y)                              │
│  Input: 处理结果 A                                       │
│  Output: 处理结果 B                                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Stage 3: Agent C (专业：Z)                              │
│  Input: 处理结果 B                                       │
│  Output: 最终结果                                        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                      Output                              │
└─────────────────────────────────────────────────────────┘
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class PipelineAgent {
  constructor(stages, options = {}) {
    this.stages = stages; // [{agent, name, description}]
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async process(input) {
    if (this.verbose) {
      console.log(`[Pipeline] 开始处理`);
      console.log(`[Pipeline] 输入：${input.substring(0, 100)}...`);
      console.log(`[Pipeline] 阶段数：${this.stages.length}`);
    }
    
    let currentData = input;
    const stageResults = [];
    
    for (let i = 0; i < this.stages.length; i++) {
      const stage = this.stages[i];
      
      if (this.verbose) {
        console.log(`\n[Stage ${i + 1}/${this.stages.length}] ${stage.name}`);
      }
      
      // 执行当前阶段
      const result = await stage.agent.process(currentData);
      
      if (this.verbose) {
        console.log(`[Stage ${i + 1}] 完成`);
        console.log(`  输出：${result.substring(0, 100)}...`);
      }
      
      // 记录结果
      stageResults.push({
        stage: stage.name,
        input: currentData,
        output: result
      });
      
      // 传递给下一阶段
      currentData = result;
    }
    
    if (this.verbose) {
      console.log(`\n[Pipeline] 处理完成`);
    }
    
    return {
      finalOutput: currentData,
      stageResults
    };
  }
}

/**
 * 流水线阶段 Agent
 */
class PipelineStageAgent {
  constructor(id, specialty, instructions) {
    this.id = id;
    this.specialty = specialty;
    this.instructions = instructions;
    this.llm = null;
  }

  async process(input) {
    const prompt = `
阶段：${this.specialty}
指令：${this.instructions}

输入：
${input}

请执行本阶段处理。

输出：`;
    
    return await this.llm.generate(prompt);
  }
}
```

---

### 使用示例 1：内容创作流水线

```javascript
// 创建各阶段 Agent
const outlineAgent = new PipelineStageAgent(
  'outline',
  '大纲设计',
  '根据主题创建详细大纲，包括主要章节和要点'
);

const draftAgent = new PipelineStageAgent(
  'draft',
  '初稿写作',
  '根据大纲撰写完整初稿，内容详实'
);

const editAgent = new PipelineStageAgent(
  'edit',
  '编辑润色',
  '修改语法错误、优化表达、提升可读性'
);

const reviewAgent = new PipelineStageAgent(
  'review',
  '质量审查',
  '检查事实准确性、逻辑一致性、整体质量'
);

// 创建流水线
const contentPipeline = new PipelineAgent([
  { agent: outlineAgent, name: '大纲设计', description: '创建大纲' },
  { agent: draftAgent, name: '初稿写作', description: '撰写初稿' },
  { agent: editAgent, name: '编辑润色', description: '编辑修改' },
  { agent: reviewAgent, name: '质量审查', description: '最终审查' }
], { verbose: true });

// 执行
const topic = '人工智能的未来发展趋势';
const result = await contentPipeline.process(topic);
console.log(result.finalOutput);
```

---

### 使用示例 2：代码开发流水线

```javascript
// 代码开发流水线
const designAgent = new PipelineStageAgent(
  'design',
  '架构设计',
  '设计系统架构、接口定义、数据模型'
);

const codeAgent = new PipelineStageAgent(
  'code',
  '代码实现',
  '根据设计编写高质量代码'
);

const testAgent = new PipelineStageAgent(
  'test',
  '测试编写',
  '编写单元测试、集成测试'
);

const reviewCodeAgent = new PipelineStageAgent(
  'code-review',
  '代码审查',
  '审查代码质量、安全性、性能'
);

const codePipeline = new PipelineAgent([
  { agent: designAgent, name: '架构设计' },
  { agent: codeAgent, name: '代码实现' },
  { agent: testAgent, name: '测试编写' },
  { agent: reviewCodeAgent, name: '代码审查' }
], { verbose: true });

// 执行
const requirement = '开发一个用户认证系统';
const result = await codePipeline.process(requirement);
```

---

## 🎯 关键设计要点

### 1. 阶段设计

**好的阶段**：
- 职责单一（每个阶段只做一件事）
- 接口清晰（输入输出明确）
- 专业化（发挥 Agent 专长）

**示例**：
```javascript
const stages = [
  { agent: researchAgent, name: '信息收集' },
  { agent: analyzeAgent, name: '数据分析' },
  { agent: writeAgent, name: '报告撰写' },
  { agent: editAgent, name: '编辑校对' }
];
```

---

### 2. 错误处理

**阶段失败处理**：
```javascript
async process(input) {
  let currentData = input;
  
  for (const stage of this.stages) {
    try {
      currentData = await stage.agent.process(currentData);
    } catch (error) {
      console.error(`[Pipeline] 阶段 ${stage.name} 失败：${error.message}`);
      
      // 选项 1：重试
      // currentData = await this.retry(stage, currentData);
      
      // 选项 2：跳过
      // continue;
      
      // 选项 3：终止
      throw error;
    }
  }
  
  return currentData;
}
```

---

### 3. 缓冲机制

**阶段间缓冲**：
```javascript
class BufferedPipelineAgent {
  constructor(stages, bufferSize = 3) {
    this.stages = stages;
    this.bufferSize = bufferSize;
    this.buffers = stages.map(() => []);
  }

  async processBatch(inputs) {
    // 批量处理，提高吞吐量
    for (const input of inputs) {
      this.buffers[0].push(input);
    }
    
    // 流水线执行
    for (let i = 0; i < this.stages.length; i++) {
      while (this.buffers[i].length > 0) {
        const data = this.buffers[i].shift();
        const result = await this.stages[i].agent.process(data);
        
        if (i < this.stages.length - 1) {
          this.buffers[i + 1].push(result);
        }
      }
    }
    
    return this.buffers[this.buffers.length - 1];
  }
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：瓶颈阶段

**现象**：某个阶段特别慢，阻塞整个流水线。

**解决方案**：
```javascript
// 为瓶颈阶段创建多个实例
const bottleneckStage = {
  agent: slowAgent,
  name: '瓶颈阶段',
  instances: 3  // 3 个并行实例
};

// 并行处理
async processStage(stage, input) {
  if (stage.instances > 1) {
    // 分割输入，并行处理
    const chunks = this.chunk(input, stage.instances);
    const results = await Promise.all(
      chunks.map(chunk => stage.agent.process(chunk))
    );
    return this.merge(results);
  }
  return stage.agent.process(input);
}
```

---

### 问题 2：质量下降

**现象**：后面阶段引入错误。

**解决方案**：
```javascript
// 添加质量检查点
async process(input) {
  let currentData = input;
  
  for (let i = 0; i < this.stages.length; i++) {
    currentData = await this.stages[i].agent.process(currentData);
    
    // 质量检查
    const quality = await this.checkQuality(currentData);
    if (quality.score < 0.7) {
      console.warn(`[Pipeline] 阶段 ${i} 质量低，返回修改`);
      currentData = await this.revise(this.stages[i].agent, currentData, quality.issues);
    }
  }
  
  return currentData;
}
```

---

## 🔧 优化技巧

### 1. 并行流水线

```javascript
// 多个输入并行处理
class ParallelPipelineAgent {
  constructor(stages, concurrency = 3) {
    this.stages = stages;
    this.concurrency = concurrency;
  }

  async processBatch(inputs) {
    const results = [];
    
    for (let i = 0; i < inputs.length; i += this.concurrency) {
      const batch = inputs.slice(i, i + this.concurrency);
      const batchResults = await Promise.all(
        batch.map(input => this.process(input))
      );
      results.push(...batchResults);
    }
    
    return results;
  }
}
```

---

### 2. 动态调整

```javascript
// 根据输入类型动态选择流水线
async process(input) {
  const pipelineType = this.classifyInput(input);
  const pipeline = this.pipelines[pipelineType];
  
  if (!pipeline) {
    throw new Error(`Unknown pipeline type: ${pipelineType}`);
  }
  
  return pipeline.process(input);
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **吞吐量** | 单位时间处理的任务数 | >10/分钟 |
| **延迟** | 从输入到输出的时间 | <1 分钟 |
| **质量** | 最终输出质量评分 | >8/10 |
| **稳定性** | 无错误处理的比例 | >99% |

---

## 🔗 相关模式

- **主从模式**：可以结合使用（Manager 协调流水线）
- **ReAct**：可以在阶段内使用 ReAct
- **Reflection**：可以在阶段间添加反思

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02


path: patterns/README.md
content: # AI Agent 架构模式库

> **完整模式文档** - 包含详细实现、示例、最佳实践

---

## 📁 目录结构

```
patterns/
├── README.md                 # 本文件（模式总览）
├── single-agent/             # 单 Agent 模式
│   ├── react.md              # ReAct 模式
│   ├── reflection.md         # Reflection 模式
│   ├── self-critique.md      # Self-Critique 模式
│   ├── plan-and-solve.md     # Plan-and-Solve 模式
│   └── tree-of-thoughts.md   # Tree of Thoughts 模式
└── multi-agent/              # 多 Agent 模式
    ├── manager-worker.md     # 主从模式
    ├── peer-to-peer.md       # 对等模式
    ├── hierarchical.md       # 层级模式
    ├── market-based.md       # 市场模式
    └── pipeline.md           # 流水线模式
```

---

## 🎯 单 Agent 模式 ✅ 全部完成

### ReAct (Reasoning + Acting)

**核心思想**：交替进行推理和行动。

**流程**：
```
Thought → Action → Observation → Thought → Action → ... → Answer
```

**适用场景**：
- 需要调用外部工具
- 需要多步推理
- 需要与环境交互

**实现要点**：
- 清晰的思考格式
- 明确的动作定义
- 结果观察记录

📄 详细文档：`single-agent/react.md`

---

### Reflection (反思)

**核心思想**：执行后反思，迭代改进。

**流程**：
```
Generate → Reflect → Revise → Reflect → ... → Final
```

**适用场景**：
- 需要高质量输出
- 可以自我评估
- 有时间迭代

**实现要点**：
- 明确的评估标准
- 具体的改进建议
- 迭代次数限制

📄 详细文档：`single-agent/reflection.md`

---

### Self-Critique (自我批评)

**核心思想**：主动寻找自己输出的问题。

**流程**：
```
Generate → Critique (find flaws) → Fix → Critique → ... → Final
```

**适用场景**：
- 需要高准确性
- 容易出错的任务
- 有明确错误类型

**实现要点**：
- 结构化的批评框架
- 常见错误清单
- 修复策略

📄 详细文档：`single-agent/self-critique.md`

---

### Plan-and-Solve (规划与执行)

**核心思想**：先制定完整计划，再逐步执行。

**流程**：
```
Understand → Plan → Execute Step 1 → Execute Step 2 → ... → Synthesize
```

**适用场景**：
- 复杂多步骤任务
- 需要全局规划
- 步骤间有依赖

**实现要点**：
- 完整的计划制定
- 进度跟踪
- 灵活调整

📄 详细文档：`single-agent/plan-and-solve.md`

---

### Tree of Thoughts (思维树)

**核心思想**：探索多个思考路径，选择最优。

**流程**：
```
        Root
       / | \
      /  |  \
   Thought Thoughts → Evaluate → Select Best → Expand
```

**适用场景**：
- 需要创造性
- 有多个可能方案
- 可以评估方案质量

**实现要点**：
- 思维生成策略
- 评估函数
- 搜索算法（BFS/DFS/Beam）

📄 详细文档：`single-agent/tree-of-thoughts.md`

---

## 🤝 多 Agent 模式 ✅ 全部完成

### 主从模式 (Manager-Worker)

**核心思想**：一个主 Agent 分解任务，多个从 Agent 执行。

**架构**：
```
        Manager
       /   |   \
      /    |    \
  Worker1 Worker2 Worker3
```

**适用场景**：
- 任务可分解
- 需要协调
- 有明确的管理逻辑

**实现要点**：
- 任务分解策略
- 结果整合机制
- 负载均衡

📄 详细文档：`multi-agent/manager-worker.md`

---

### 对等模式 (Peer-to-Peer)

**核心思想**：多个 Agent 平等协作，共同完成任务。

**架构**：
```
Agent1 ←→ Agent2
   ↑        ↑
   └──→ Agent3 ←→ ...
```

**适用场景**：
- 任务可并行
- Agent 能力相似
- 需要协作讨论

**实现要点**：
- 通信协议
- 冲突解决
- 共识机制

📄 详细文档：`multi-agent/peer-to-peer.md`

---

### 层级模式 (Hierarchical)

**核心思想**：多层管理结构，适合大型系统。

**架构**：
```
         CEO
         |
      Managers
      /   |   \
   Teams ...  Teams
   / | \       / | \
```

**适用场景**：
- 大型复杂项目
- 需要多层协调
- 有明确组织结构

**实现要点**：
- 层级设计
- 信息传递
- 决策权限

📄 详细文档：`multi-agent/hierarchical.md`

---

### 市场模式 (Market-Based)

**核心思想**：Agent 通过竞价获取任务。

**流程**：
```
Task Posted → Agents Bid → Select Best Bid → Execute → Pay
```

**适用场景**：
- 动态任务分配
- Agent 能力差异大
- 需要优化资源

**实现要点**：
- 竞价机制
- 评估标准
- 支付/奖励系统

📄 详细文档：`multi-agent/market-based.md`

---

### 流水线模式 (Pipeline)

**核心思想**：顺序处理，前一个输出是后一个输入。

**架构**：
```
Input → Agent1 → Agent2 → Agent3 → ... → Output
```

**适用场景**：
- 多阶段处理
- 阶段间有依赖
- 需要专业化

**实现要点**：
- 接口定义
- 错误处理
- 缓冲机制

📄 详细文档：`multi-agent/pipeline.md`

---

## 🔧 使用指南

### 选择模式

1. **分析任务**：复杂度、步骤数、是否需要协作
2. **评估资源**：可用 Agent 数量、能力、时间
3. **考虑约束**：性能要求、可靠性、成本
4. **选择模式**：参考上面的决策树

### 实现步骤

1. **定义接口**：输入、输出、错误处理
2. **实现核心逻辑**：按照模式流程
3. **添加容错**：重试、降级、超时
4. **添加监控**：日志、指标、追踪
5. **测试优化**：单元测试、集成测试、性能测试

### 组合模式

模式可以组合使用：
- ReAct + Reflection = 更高质量的单 Agent
- Manager-Worker + Pipeline = 分层流水线
- Tree of Thoughts + Market = 多路径竞价

---

## 📚 参考资源

### 学术论文
- ReAct: https://arxiv.org/abs/2210.03629
- Tree of Thoughts: https://arxiv.org/abs/2305.10601
- Reflection: https://arxiv.org/abs/2303.11366

### 开源实现
- CrewAI: https://github.com/joaomdmoura/crewAI
- AutoGen: https://github.com/microsoft/autogen
- LangChain: https://github.com/langchain-ai/langchain

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02


path: patterns/single-agent/plan-and-solve.md
content: # Plan-and-Solve 模式 - 规划与执行

> **版本**: 1.0.0  
> **论文**: [Plan-and-Solve Prompting](https://arxiv.org/abs/2305.04091)  
> **适用场景**: 复杂多步骤任务、需要全局规划、步骤间有依赖的任务

---

## 🧠 核心思想

**Plan-and-Solve = Plan + Execute + Synthesize**

传统方法的问题：
- **盲目执行**：没有规划就开始做
- **缺乏全局**：只见树木不见森林
- **步骤混乱**：顺序错误、遗漏步骤

Plan-and-Solve 的突破：
- **先规划**：制定完整计划再执行
- **分步骤**：将复杂任务分解为可执行步骤
- **跟踪进度**：记录已完成和待完成步骤
- **灵活调整**：根据执行情况调整计划

---

## 📊 工作流程

```
┌─────────────────────────────────────────────────────────┐
│                    Task Input                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 1: Understand (理解任务)                          │
│  - 分析任务目标                                          │
│  - 识别约束条件                                          │
│  - 确定成功标准                                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 2: Plan (制定计划)                                │
│  - 分解为子任务                                          │
│  - 确定执行顺序                                          │
│  - 识别依赖关系                                          │
│  - 估算资源需求                                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 3: Execute (执行计划)                             │
│  For each step in plan:                                  │
│    - 执行当前步骤                                        │
│    - 记录结果                                            │
│    - 检查进度                                            │
│    - 必要时调整计划                                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 4: Synthesize (整合结果)                          │
│  - 汇总所有步骤结果                                      │
│  - 验证是否满足目标                                      │
│  - 生成最终输出                                          │
└─────────────────────────────────────────────────────────┘
                          ↓
                  Final Output
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class PlanAndSolveAgent {
  constructor(options = {}) {
    this.maxSteps = options.maxSteps || 20;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Plan-and-Solve] 开始任务：${task}`);
    }
    
    // Phase 1: Understand
    const understanding = await this.understand(task);
    
    if (this.verbose) {
      console.log('[Understanding]');
      console.log(`  目标：${understanding.goal}`);
      console.log(`  约束：${understanding.constraints.join(', ')}`);
      console.log(`  成功标准：${understanding.successCriteria.join(', ')}`);
    }
    
    // Phase 2: Plan
    const plan = await this.plan(task, understanding);
    
    if (this.verbose) {
      console.log(`\n[Plan] 共 ${plan.steps.length} 步`);
      plan.steps.forEach((step, i) => {
        console.log(`  ${i + 1}. ${step.description}`);
      });
    }
    
    // Phase 3: Execute
    const executionResults = await this.executePlan(task, plan);
    
    if (this.verbose) {
      console.log(`\n[Execution Complete] ${executionResults.completed}/${executionResults.total} 步`);
    }
    
    // Phase 4: Synthesize
    const finalResult = await this.synthesize(task, understanding, executionResults);
    
    if (this.verbose) {
      console.log(`\n[Final Result] ${finalResult}`);
    }
    
    return finalResult;
  }

  /**
   * Phase 1: Understand - 理解任务
   */
  async understand(task) {
    const prompt = `
任务：${task}

请分析这个任务：

1. **任务目标**：要达成什么？
2. **约束条件**：有哪些限制？（时间、资源、技术等）
3. **成功标准**：如何判断任务完成？

请以 JSON 格式返回：
{
  "goal": "任务目标",
  "constraints": ["约束 1", "约束 2"],
  "successCriteria": ["标准 1", "标准 2"]
}

分析结果：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      // 降级方案
      return {
        goal: task,
        constraints: [],
        successCriteria: ['任务完成']
      };
    }
  }

  /**
   * Phase 2: Plan - 制定计划
   */
  async plan(task, understanding) {
    const prompt = `
任务：${task}

目标：${understanding.goal}

约束：${understanding.constraints.join(', ')}

成功标准：${understanding.successCriteria.join(', ')}

请制定详细的执行计划：

要求：
1. 将任务分解为具体的、可执行的步骤
2. 步骤之间可能有依赖关系（某步完成后才能执行下一步）
3. 每个步骤应该有清晰的完成标准
4. 步骤数量适中（5-15 步）

请以 JSON 格式返回：
{
  "steps": [
    {
      "id": 1,
      "description": "步骤描述",
      "dependencies": [],  // 依赖的步骤 ID
      "expectedOutput": "预期输出"
    }
  ]
}

计划：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      // 降级方案：返回单步计划
      return {
        steps: [{
          id: 1,
          description: task,
          dependencies: [],
          expectedOutput: '完成任务'
        }]
      };
    }
  }

  /**
   * Phase 3: Execute - 执行计划
   */
  async executePlan(task, plan) {
    const results = {
      total: plan.steps.length,
      completed: 0,
      failed: 0,
      stepResults: []
    };
    
    const completedSteps = new Set();
    
    for (let stepNum = 0; stepNum < plan.steps.length; stepNum++) {
      // 找到可执行的步骤（依赖已满足）
      const executableStep = plan.steps.find(step => 
        !completedSteps.has(step.id) &&
        step.dependencies.every(depId => completedSteps.has(depId))
      );
      
      if (!executableStep) {
        // 没有可执行的步骤，但还有未完成的
        console.warn('No executable steps found. Possible circular dependency.');
        break;
      }
      
      if (this.verbose) {
        console.log(`\n[Step ${executableStep.id}/${plan.steps.length}] ${executableStep.description}`);
      }
      
      // 执行步骤
      const result = await this.executeStep(task, executableStep, results.stepResults);
      
      results.stepResults.push({
        stepId: executableStep.id,
        description: executableStep.description,
        success: result.success,
        output: result.output,
        error: result.error
      });
      
      if (result.success) {
        completedSteps.add(executableStep.id);
        results.completed++;
        
        if (this.verbose) {
          console.log(`  ✅ 完成`);
        }
      } else {
        results.failed++;
        
        if (this.verbose) {
          console.log(`  ❌ 失败：${result.error}`);
        }
        
        // 关键步骤失败，可能无法继续
        if (this.isCriticalStep(executableStep)) {
          console.warn('Critical step failed. Stopping execution.');
          break;
        }
      }
    }
    
    return results;
  }

  /**
   * 执行单个步骤
   */
  async executeStep(task, step, previousResults) {
    const context = previousResults.map(r => 
      `步骤 ${r.stepId}: ${r.output}`
    ).join('\n');
    
    const prompt = `
任务：${task}

当前步骤：${step.description}
预期输出：${step.expectedOutput}

之前的执行结果：
${context || '（无）'}

请执行当前步骤。

结果：`;
    
    try {
      const output = await this.llm.generate(prompt);
      return { success: true, output };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  /**
   * 判断是否是关键步骤
   */
  isCriticalStep(step) {
    // 如果其他步骤依赖这个步骤，则是关键步骤
    return false; // 简化实现
  }

  /**
   * Phase 4: Synthesize - 整合结果
   */
  async synthesize(task, understanding, executionResults) {
    const resultsText = executionResults.stepResults.map(r => 
      `步骤 ${r.stepId}: ${r.success ? '✅' : '❌'} ${r.output || r.error}`
    ).join('\n');
    
    const prompt = `
任务：${task}

目标：${understanding.goal}

成功标准：${understanding.successCriteria.join(', ')}

执行结果：
${resultsText}

完成进度：${executionResults.completed}/${executionResults.total} 步

请整合所有执行结果，生成最终输出。

如果所有步骤都完成且满足成功标准，给出完整答案。
如果有步骤失败，说明影响和替代方案。

最终输出：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Task completed.';
    }
  };
}
```

---

### 使用示例

```javascript
// 创建 Agent
const agent = new PlanAndSolveAgent({
  maxSteps: 20,
  verbose: true
});

// 执行复杂任务
const task = '开发一个简单的待办事项应用，包括前端和后端';

const result = await agent.execute(task);
console.log(result);
```

---

### 执行轨迹示例

```
[Plan-and-Solve] 开始任务：开发一个简单的待办事项应用，包括前端和后端

[Understanding]
  目标：开发一个待办事项应用（前端 + 后端）
  约束：简单、快速开发
  成功标准：可以添加/删除/查看待办事项

[Plan] 共 8 步
  1. 设计数据模型
  2. 创建后端项目结构
  3. 实现 API 路由（GET /todos）
  4. 实现 API 路由（POST /todos）
  5. 实现 API 路由（DELETE /todos/:id）
  6. 创建前端项目结构
  7. 实现前端 UI 和交互
  8. 测试和部署

[Step 1/8] 设计数据模型
  ✅ 完成

[Step 2/8] 创建后端项目结构
  ✅ 完成

[Step 3/8] 实现 API 路由（GET /todos）
  ✅ 完成

[Step 4/8] 实现 API 路由（POST /todos）
  ✅ 完成

[Step 5/8] 实现 API 路由（DELETE /todos/:id）
  ✅ 完成

[Step 6/8] 创建前端项目结构
  ✅ 完成

[Step 7/8] 实现前端 UI 和交互
  ✅ 完成

[Step 8/8] 测试和部署
  ✅ 完成

[Execution Complete] 8/8 步

[Final Result] 
## 待办事项应用开发完成

### 后端（Node.js + Express）
- 数据模型：Todo { id, title, completed, createdAt }
- API 端点：
  - GET /todos - 获取所有待办
  - POST /todos - 创建待办
  - DELETE /todos/:id - 删除待办

### 前端（HTML + CSS + JavaScript）
- 功能：
  - 显示待办列表
  - 添加新待办
  - 删除待办
  - 标记完成

### 使用方法
1. 启动后端：node server.js
2. 打开前端：index.html
3. 访问 http://localhost:3000

所有功能已完成并测试通过。
```

---

## 🎯 关键设计要点

### 1. 任务理解

**好的理解**：
```javascript
{
  "goal": "开发一个待办事项应用",
  "constraints": [
    "使用 JavaScript 技术栈",
    "开发时间<1 天",
    "支持 100 个并发用户"
  ],
  "successCriteria": [
    "可以添加待办",
    "可以删除待办",
    "可以标记完成",
    "界面简洁易用"
  ]
}
```

---

### 2. 计划质量

**好的计划**：
- 步骤清晰（每个步骤做什么）
- 依赖明确（哪些步骤有先后顺序）
- 可执行（每个步骤都能完成）
- 可验证（有明确的完成标准）

**示例**：
```javascript
{
  "steps": [
    {
      "id": 1,
      "description": "设计数据库 schema",
      "dependencies": [],
      "expectedOutput": "数据库表结构文档"
    },
    {
      "id": 2,
      "description": "实现用户认证 API",
      "dependencies": [1],  // 依赖步骤 1
      "expectedOutput": "/login, /register 端点"
    },
    {
      "id": 3,
      "description": "实现待办事项 API",
      "dependencies": [1, 2],  // 依赖步骤 1 和 2
      "expectedOutput": "CRUD 端点"
    }
  ]
}
```

---

### 3. 进度跟踪

**跟踪信息**：
```javascript
const progress = {
  total: plan.steps.length,
  completed: 0,
  failed: 0,
  current: null,
  stepResults: [],
  blockedSteps: []  // 因依赖失败而阻塞的步骤
};
```

---

### 4. 灵活调整

**计划调整策略**：
```javascript
async executePlan(task, plan) {
  // ...
  
  if (result.success) {
    completedSteps.add(executableStep.id);
    results.completed++;
  } else {
    results.failed++;
    
    // 尝试调整计划
    const adjustedPlan = await this.adjustPlan(plan, executableStep, result.error);
    if (adjustedPlan) {
      plan = adjustedPlan;
      // 重试或跳过
    }
  }
  
  // ...
}

async adjustPlan(originalPlan, failedStep, error) {
  const prompt = `
原计划执行失败：
步骤：${failedStep.description}
错误：${error}

请调整计划以绕过这个问题。

选项：
1. 修改失败步骤的实现方式
2. 跳过这个步骤（如果不关键）
3. 添加新的步骤来解决问题

调整后的计划：`;
  
  return await this.llm.generate(prompt);
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：计划过于复杂

**现象**：步骤太多（>20 步），难以执行。

**解决方案**：
```javascript
async plan(task, understanding) {
  const prompt = `
请制定计划：

要求：
1. 步骤数量控制在 5-15 步
2. 如果任务太复杂，可以分组为几个阶段
3. 优先关注关键步骤
4. 可选步骤标记为"可选"

计划：`;
  
  return await this.llm.generate(prompt);
}
```

---

### 问题 2：步骤依赖循环

**现象**：步骤 A 依赖 B，B 依赖 A，无法执行。

**解决方案**：
```javascript
async plan(task, understanding) {
  const prompt = `
制定计划时，确保：
1. **没有循环依赖**（A 依赖 B，B 依赖 A）
2. 依赖关系是**有向无环图**（DAG）
3. 至少有一个步骤没有依赖（可以作为起点）

计划：`;
  
  return await this.llm.generate(prompt);
}

// 执行时检测循环依赖
findExecutableStep(plan, completedSteps) {
  const visited = new Set();
  const recStack = new Set();
  
  // 检测循环依赖
  if (this.hasCycle(plan.steps, visited, recStack)) {
    throw new Error('Circular dependency detected');
  }
  
  // 找到可执行的步骤
  return plan.steps.find(step => 
    !completedSteps.has(step.id) &&
    step.dependencies.every(depId => completedSteps.has(depId))
  );
}
```

---

### 问题 3：步骤执行失败

**现象**：某一步无法完成。

**解决方案**：
```javascript
async executeStep(task, step, previousResults) {
  // 添加重试机制
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const output = await this.llm.generate(prompt);
      return { success: true, output };
    } catch (error) {
      if (attempt === 3) {
        // 最后一次失败，尝试替代方案
        return await this.executeAlternative(task, step, previousResults);
      }
      await this.sleep(1000 * attempt);
    }
  }
}

async executeAlternative(task, step, previousResults) {
  const prompt = `
步骤无法按原计划执行：
${step.description}

请提供替代方案来完成这个步骤的目标。

替代方案：`;
  
  return await this.llm.generate(prompt);
}
```

---

## 🔧 优化技巧

### 1. 分阶段执行

```javascript
async execute(task) {
  const understanding = await this.understand(task);
  const plan = await this.plan(task, understanding);
  
  // 将计划分为几个阶段
  const phases = this.groupIntoPhases(plan.steps);
  
  for (const phase of phases) {
    console.log(`\n[Phase: ${phase.name}]`);
    const phasePlan = { steps: phase.steps };
    const results = await this.executePlan(task, phasePlan);
    
    // 阶段完成后评估
    const phaseAssessment = await this.assessPhase(phase.name, results);
    if (!phaseAssessment.pass) {
      console.warn(`Phase ${phase.name} failed assessment.`);
      // 可以调整后续阶段
    }
  }
  
  // ...
}
```

---

### 2. 并行执行独立步骤

```javascript
async executePlan(task, plan) {
  // 找到所有可并行执行的步骤（没有相互依赖）
  const independentSteps = this.findIndependentSteps(plan.steps);
  
  // 并行执行
  const parallelResults = await Promise.all(
    independentSteps.map(step => this.executeStep(task, step, []))
  );
  
  // ...
}

findIndependentSteps(steps) {
  // 找到没有依赖且不被依赖的步骤
  const allDependencies = new Set(
    steps.flatMap(s => s.dependencies)
  );
  
  return steps.filter(step => 
    step.dependencies.length === 0 &&
    !allDependencies.has(step.id)
  );
}
```

---

### 3. 进度可视化

```javascript
visualizeProgress(plan, results) {
  const progressBar = (completed, total) => {
    const percentage = Math.round(completed / total * 100);
    const filled = '█'.repeat(percentage / 5);
    const empty = '░'.repeat(20 - percentage / 5);
    return `[${filled}${empty}] ${percentage}%`;
  };
  
  console.log(`\n进度：${progressBar(results.completed, results.total)}`);
  console.log(`完成：${results.completed}/${results.total}`);
  console.log(`失败：${results.failed}`);
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **计划完成率** | 成功完成的计划比例 | >90% |
| **步骤成功率** | 成功执行的步骤比例 | >95% |
| **平均执行时间** | 从开始到完成的时间 | <5 分钟 |
| **计划质量** | 计划合理性评分 | >8/10 |

---

### 优化方向

1. **提高计划质量**：更好的任务分解
2. **减少执行时间**：并行执行独立步骤
3. **提高成功率**：更好的错误处理
4. **灵活调整**：根据执行情况动态调整计划

---

## 🔗 相关模式

- **ReAct**：可以在执行步骤时使用 ReAct
- **Tree of Thoughts**：可以在规划阶段探索多个计划
- **Manager-Worker**：可以将步骤分配给不同 Worker

---

## 📚 参考资源

- **原论文**: [Plan-and-Solve Prompting](https://arxiv.org/abs/2305.04091)
- **实现参考**: [LangChain Planning](https://python.langchain.com/docs/modules/agents/agent_types/planning)
- **应用案例**: [Complex Task Planning with LLMs](https://plan-and-solve.github.io/)

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: patterns/single-agent/react.md
content: # ReAct 模式 - Reasoning + Acting

> **版本**: 1.0.0  
> **论文**: [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629)  
> **适用场景**: 需要工具调用、多步推理、环境交互的任务

---

## 🧠 核心思想

**ReAct = Reasoning + Acting**

传统方法的问题：
- **纯推理**：能思考但不能行动（无法调用工具）
- **纯行动**：能行动但不思考（盲目执行）

ReAct 的突破：
- **交替进行**：思考 → 行动 → 观察 → 思考 → ...
- **协同增强**：推理指导行动，行动结果反馈推理

---

## 📊 工作流程

```
┌─────────────────────────────────────────────────────────┐
│                    Task Input                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 1: Thought (思考)                                  │
│  "我需要做什么？当前有什么信息？下一步应该做什么？"       │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 2: Action (行动)                                   │
│  "调用工具 X，参数 Y"                                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 3: Observation (观察)                              │
│  "工具返回结果 Z"                                        │
└─────────────────────────────────────────────────────────┘
                          ↓
                    是否完成？
                    /       \
                  否         是
                  ↓           ↓
            回到 Step 1    输出最终答案
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class ReActAgent {
  constructor(tools, maxSteps = 10) {
    this.tools = tools;
    this.maxSteps = maxSteps;
  }

  async execute(task) {
    const history = [];
    
    for (let step = 0; step < this.maxSteps; step++) {
      // Step 1: Thought - 思考下一步
      const thought = await this.reason(task, history);
      console.log(`[Thought ${step + 1}] ${thought}`);
      
      // Step 2: Action - 决定行动
      const action = await this.decideAction(thought, history);
      console.log(`[Action ${step + 1}] ${action.name}(${JSON.stringify(action.args)})`);
      
      // Step 3: Observation - 执行并观察结果
      const observation = await this.observe(action);
      console.log(`[Observation ${step + 1}] ${observation}`);
      
      // 记录历史
      history.push({ thought, action, observation });
      
      // 判断是否完成
      if (this.isComplete(thought, observation)) {
        const answer = await this.finalize(task, history);
        console.log(`[Answer] ${answer}`);
        return answer;
      }
    }
    
    throw new Error(`Max steps (${this.maxSteps}) reached without completion`);
  }

  async reason(task, history) {
    // 调用 LLM 进行推理
    const context = this.buildContext(task, history);
    const prompt = `
当前任务：${task}
历史对话：${JSON.stringify(history, null, 2)}

请思考：
1. 当前已知什么信息？
2. 还需要什么信息？
3. 下一步应该做什么？

思考：`;
    
    const response = await this.callLLM(prompt);
    return response.trim();
  }

  async decideAction(thought, history) {
    // 根据思考决定行动
    const prompt = `
基于以下思考，决定采取什么行动：
${thought}

可用工具：
${this.listTools()}

请以 JSON 格式返回行动：
{
  "name": "工具名称",
  "args": { "参数名": "参数值" }
}

行动：`;
    
    const response = await this.callLLM(prompt);
    return JSON.parse(response);
  }

  async observe(action) {
    // 执行工具并返回结果
    const tool = this.tools[action.name];
    if (!tool) {
      throw new Error(`Unknown tool: ${action.name}`);
    }
    return await tool.execute(action.args);
  }

  isComplete(thought, observation) {
    // 判断是否完成任务
    return thought.toLowerCase().includes('finish') || 
           thought.toLowerCase().includes('answer is');
  }

  async finalize(task, history) {
    // 生成最终答案
    const prompt = `
任务：${task}
完整历史：${JSON.stringify(history, null, 2)}

请给出最终答案：`;
    
    return await this.callLLM(prompt);
  }

  buildContext(task, history) {
    // 构建上下文
    return { task, history };
  }

  listTools() {
    return Object.keys(this.tools).map(name => 
      `- ${name}: ${this.tools[name].description}`
    ).join('\n');
  }

  async callLLM(prompt) {
    // 调用大语言模型（这里用伪代码）
    // 实际实现中调用 OpenAI/Claude/Qwen 等 API
    const response = await llm.generate(prompt);
    return response;
  }
}
```

---

### 使用示例

```javascript
// 定义工具
const tools = {
  search: {
    description: '搜索网络信息',
    execute: async ({ query }) => {
      const result = await webSearch(query);
      return result.snippets.join('\n');
    }
  },
  
  calculate: {
    description: '执行数学计算',
    execute: async ({ expression }) => {
      return eval(expression).toString();
    }
  },
  
  readFile: {
    description: '读取文件内容',
    execute: async ({ path }) => {
      return await fs.readFile(path, 'utf-8');
    }
  }
};

// 创建 Agent
const agent = new ReActAgent(tools, { maxSteps: 10 });

// 执行任务
const task = '北京今天的气温是多少？比上海高还是低？';
const answer = await agent.execute(task);

console.log(answer);
```

---

### 执行轨迹示例

```
Task: 北京今天的气温是多少？比上海高还是低？

[Thought 1] 我需要查询北京和上海的今天气温，然后比较。
           首先查询北京的气温。

[Action 1] search({"query": "北京 今天 气温"})

[Observation 1] 北京今天晴，最高气温 25°C，最低气温 15°C

[Thought 2] 我已经知道北京的气温了。现在需要查询上海的气温。

[Action 2] search({"query": "上海 今天 气温"})

[Observation 2] 上海今天多云，最高气温 22°C，最低气温 18°C

[Thought 3] 我有了两个城市的气温数据。
           北京最高 25°C，上海最高 22°C。
           北京比上海高 3°C。
           可以给出最终答案了。

[Answer] 北京今天气温 15-25°C，上海今天气温 18-22°C。
         北京的最高气温比上海高 3°C。
```

---

## 🎯 关键设计要点

### 1. 思考格式（Thought Format）

**好的思考**：
```
✅ "我需要先查询 X，因为 Y 信息是必需的"
✅ "已经有 A 和 B 信息，下一步需要 C"
✅ "根据上一步结果，我应该..."
```

**不好的思考**：
```
❌ "我不知道"（太模糊）
❌ "继续"（没有具体计划）
❌ "完成"（但没有给出答案）
```

---

### 2. 行动设计（Action Design）

**行动类型**：
- **工具调用**：search、calculate、readFile 等
- **信息提取**：从历史中提取已知信息
- **完成声明**：表示任务完成，准备输出答案

**行动格式**：
```json
{
  "name": "工具名称",
  "args": {
    "参数 1": "值 1",
    "参数 2": "值 2"
  }
}
```

---

### 3. 观察处理（Observation Handling）

**观察内容**：
- 工具执行结果
- 错误信息
- 状态更新

**观察处理**：
```javascript
async observe(action) {
  try {
    const result = await this.tools[action.name].execute(action.args);
    return { success: true, data: result };
  } catch (error) {
    return { success: false, error: error.message };
  }
}
```

---

### 4. 完成判断（Completion Detection）

**判断信号**：
- 思考中包含"finish"、"answer is"等关键词
- 已收集所有必需信息
- 达到最大步数

**优雅完成**：
```javascript
isComplete(thought, observation) {
  const finishKeywords = ['finish', 'answer is', '最终答案是', '完成任务'];
  return finishKeywords.some(keyword => 
    thought.toLowerCase().includes(keyword)
  );
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：无限循环

**现象**：Agent 反复执行相同行动。

**原因**：
- 没有正确更新历史
- 完成判断条件太严格

**解决方案**：
```javascript
// 添加步数限制
for (let step = 0; step < this.maxSteps; step++) {
  // ...
}

// 检测重复行动
const lastActions = history.slice(-3).map(h => h.action.name);
if (new Set(lastActions).size === 1) {
  throw new Error('Detected infinite loop');
}
```

---

### 问题 2：工具调用失败

**现象**：工具返回错误或无效结果。

**解决方案**：
```javascript
async observe(action) {
  try {
    return await this.tools[action.name].execute(action.args);
  } catch (error) {
    // 返回错误信息，让 Agent 可以重试或调整
    return `Error: ${error.message}. Please try again with different parameters.`;
  }
}
```

---

### 问题 3：思考质量差

**现象**：思考模糊、没有指导行动。

**解决方案**：
- 改进 Prompt，要求具体思考
- 提供思考示例（Few-shot）
- 添加思考模板

```javascript
async reason(task, history) {
  const examples = `
示例 1:
思考：我需要查询 X 的信息，因为这是完成任务的第一步。
行动：search({"query": "X"})

示例 2:
思考：已经有 X 信息，现在需要 Y 信息来比较。
行动：search({"query": "Y"})
`;

  const prompt = `${examples}\n当前任务：${task}...`;
  // ...
}
```

---

## 🔧 优化技巧

### 1. Few-shot Learning

在 Prompt 中提供示例：

```javascript
const examples = `
任务：珠穆朗玛峰有多高？比 K2 高多少？

思考：我需要查询珠穆朗玛峰和 K2 的高度。首先查询珠穆朗玛峰。
行动：search({"query": "珠穆朗玛峰 高度"})
观察：8848.86 米

思考：现在查询 K2 的高度。
行动：search({"query": "K2 高度"})
观察：8611 米

思考：两座山峰高度都知道了。珠峰 8848.86 米，K2 8611 米。
       珠峰比 K2 高 237.86 米。可以给出答案了。
行动：finish

答案：珠穆朗玛峰高 8848.86 米，K2 高 8611 米，珠峰比 K2 高 237.86 米。
`;
```

---

### 2. 工具描述优化

清晰的工具描述帮助 Agent 正确选择：

```javascript
const tools = {
  search: {
    description: '搜索网络信息。适用于查询事实、新闻、数据等。参数：query（搜索关键词）',
    execute: ...
  },
  calculate: {
    description: '执行数学计算。适用于加减乘除、幂运算等。参数：expression（数学表达式）',
    execute: ...
  }
};
```

---

### 3. 历史压缩

当历史过长时，压缩旧信息：

```javascript
buildContext(task, history) {
  if (history.length > 5) {
    // 压缩早期历史
    const earlyHistory = history.slice(0, -3);
    const recentHistory = history.slice(-3);
    
    const summary = `早期步骤摘要：共${earlyHistory.length}步，查询了${earlyHistory.length}次工具`;
    
    return {
      task,
      historySummary: summary,
      recentHistory
    };
  }
  return { task, history };
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **任务完成率** | 成功完成的任务比例 | >90% |
| **平均步数** | 完成任务的平均步数 | <5 步 |
| **工具调用准确率** | 正确选择工具的比例 | >95% |
| **平均响应时间** | 从输入到输出的时间 | <10 秒 |

---

### 优化方向

1. **减少步数**：改进推理，减少不必要的工具调用
2. **提高准确率**：更好的工具描述和示例
3. **加快速度**：并行工具调用（当独立时）
4. **降低成本**：减少 LLM 调用次数

---

## 🔗 相关模式

- **Reflection**：在 ReAct 基础上添加反思
- **Self-Critique**：在 ReAct 基础上添加自我批评
- **Plan-and-Solve**：先规划再 ReAct 执行

---

## 📚 参考资源

- **原论文**: [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629)
- **实现参考**: [LangChain ReAct Agent](https://python.langchain.com/docs/modules/agents/agent_types/react)
- **示例应用**: [ReAct for Question Answering](https://react-lm.github.io/)

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: patterns/single-agent/reflection.md
content: # Reflection 模式 - 自我反思与改进

> **版本**: 1.0.0  
> **论文**: [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.11366)  
> **适用场景**: 需要高质量输出、可以自我评估、有时间迭代的任务

---

## 🧠 核心思想

**Reflection = Generate + Reflect + Revise**

传统方法的问题：
- **一次性生成**：输出质量依赖单次生成
- **无法改进**：生成后无法自我修正
- **缺乏反思**：不知道输出的问题在哪里

Reflection 的突破：
- **迭代改进**：生成 → 反思 → 修改 → 反思 → ...
- **自我反馈**：自己评估自己的输出
- **质量提升**：每次迭代都更接近最优

---

## 📊 工作流程

```
┌─────────────────────────────────────────────────────────┐
│                    Task Input                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Iteration 1:                                            │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Generate: 生成初始输出                            │  │
│  └───────────────────────────────────────────────────┘  │
│                          ↓                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Reflect: 评估输出，找出问题                       │  │
│  └───────────────────────────────────────────────────┘  │
│                          ↓                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Revise: 根据反馈修改输出                          │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
                    是否满足标准？
                    /           \
                  否             是
                  ↓               ↓
            回到 Iteration 2    输出最终结果
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class ReflectionAgent {
  constructor(options = {}) {
    this.maxIterations = options.maxIterations || 5;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
    this.criteria = options.criteria || this.defaultCriteria;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Reflection] 开始任务：${task}`);
    }
    
    let output = await this.generate(task);
    
    if (this.verbose) {
      console.log(`[Initial] ${output}`);
    }
    
    for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
      if (this.verbose) {
        console.log(`\n[Iteration ${iteration}/${this.maxIterations}]`);
      }
      
      // Reflect: 评估当前输出
      const feedback = await this.reflect(task, output);
      
      if (this.verbose) {
        console.log(`[Feedback] ${feedback}`);
      }
      
      // 检查是否满足标准
      if (this.isSatisfactory(feedback)) {
        if (this.verbose) {
          console.log('[Complete] 输出质量满足要求');
        }
        break;
      }
      
      // Revise: 根据反馈修改
      output = await this.revise(task, output, feedback);
      
      if (this.verbose) {
        console.log(`[Revised] ${output}`);
      }
    }
    
    return output;
  }

  /**
   * Generate: 生成初始输出
   */
  async generate(task) {
    const prompt = `
任务：${task}

请生成初始输出。

初始输出：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * Reflect: 评估输出，提供反馈
   */
  async reflect(task, output) {
    const prompt = `
任务：${task}

当前输出：
${output}

请评估这个输出，考虑以下标准：
${this.formatCriteria()}

反馈要求：
1. 指出具体问题（至少 3 个）
2. 说明为什么是问题
3. 提供改进建议

反馈：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * Revise: 根据反馈修改输出
   */
  async revise(task, output, feedback) {
    const prompt = `
任务：${task}

当前输出：
${output}

反馈：
${feedback}

请根据反馈修改输出，改进所有指出的问题。

修改后的输出：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 判断输出是否满足要求
   */
  isSatisfactory(feedback) {
    // 检查反馈中是否有严重问题
    const criticalKeywords = ['严重问题', '重大错误', '完全不符合', '无法接受'];
    const hasCriticalIssues = criticalKeywords.some(keyword => 
      feedback.includes(keyword)
    );
    
    // 如果没有严重问题，认为满足要求
    return !hasCriticalIssues;
  }

  /**
   * 格式化评估标准
   */
  formatCriteria() {
    return this.criteria.map((c, i) => `${i + 1}. ${c}`).join('\n');
  }

  /**
   * 默认评估标准
   */
  defaultCriteria = [
    '准确性：信息是否正确、无误',
    '完整性：是否覆盖所有要点',
    '清晰性：表达是否清晰易懂',
    '逻辑性：推理是否严密、自洽',
    '相关性：是否紧扣任务要求'
  ];

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated output.';
    }
  };
}
```

---

### 使用示例

```javascript
// 创建 Agent
const agent = new ReflectionAgent({
  maxIterations: 5,
  verbose: true,
  criteria: [
    '代码正确性：是否能正确运行',
    '代码质量：是否遵循最佳实践',
    '性能：是否有性能问题',
    '可读性：是否易于理解',
    '安全性：是否有安全漏洞'
  ]
});

// 执行任务：代码审查
const task = '审查以下代码并提供改进建议：\n\n' + `
function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i < items.length; i++) {
    total += items[i].price * items[i].quantity;
  }
  return total;
}
`;

const result = await agent.execute(task);
console.log(result);
```

---

### 执行轨迹示例

```
[Reflection] 开始任务：审查以下代码并提供改进建议

[Initial] 
代码审查结果：
1. 代码功能正确
2. 变量命名清晰
3. 逻辑简单明了

[Iteration 1/5]
[Feedback] 
评估结果：
问题 1：反馈过于简略，没有具体说明
问题 2：没有指出潜在问题（如边界条件、错误处理）
问题 3：没有提供改进建议
问题 4：没有考虑性能优化

[Revised] 
代码审查结果：

优点：
1. 功能正确，能正确计算总价
2. 变量命名清晰（total, items, price, quantity）
3. 逻辑简单，易于理解

需要改进的地方：
1. 缺少边界条件处理（items 为空数组时）
2. 缺少错误处理（price 或 quantity 为非数字时）
3. 可以使用 reduce 方法使代码更简洁
4. 缺少类型检查

改进建议：
function calculateTotal(items) {
  if (!Array.isArray(items) || items.length === 0) {
    return 0;
  }
  
  return items.reduce((total, item) => {
    const price = Number(item.price) || 0;
    const quantity = Number(item.quantity) || 0;
    return total + price * quantity;
  }, 0);
}

[Iteration 2/5]
[Feedback] 
评估结果：
这次反馈质量很好，覆盖了：
- 优点识别
- 具体问题
- 改进建议
- 代码示例

满足要求，可以结束。

[Complete] 输出质量满足要求

最终输出：（同上）
```

---

## 🎯 关键设计要点

### 1. 评估标准设计

**好的标准**：
- 具体可衡量（不是"好"而是"准确率>95%"）
- 覆盖关键维度（准确性、完整性、清晰性等）
- 与任务相关（代码审查 vs 文章写作的标准不同）

**示例**：
```javascript
// 代码审查标准
const codeReviewCriteria = [
  '正确性：代码是否能正确运行，无 bug',
  '性能：时间复杂度、空间复杂度是否合理',
  '可读性：命名、注释、结构是否清晰',
  '可维护性：是否易于修改和扩展',
  '安全性：是否有安全漏洞（注入、XSS 等）',
  '测试：是否有充分的测试覆盖'
];

// 文章写作标准
const writingCriteria = [
  '准确性：信息是否正确、来源可靠',
  '逻辑性：论点是否清晰、论证是否严密',
  '流畅性：语言是否通顺、易读',
  '吸引力：开头是否吸引人、结尾是否有力',
  '完整性：是否覆盖所有要点'
];
```

---

### 2. 反馈质量

**好的反馈**：
```
✅ "第 3 段缺少过渡句，导致逻辑跳跃。建议添加：'然而，这个观点存在争议...'。"
✅ "函数没有处理空数组的情况，会返回 undefined。应该返回 0。"
✅ "这个论点缺乏数据支持。建议引用 XX 研究报告的数据。"
```

**不好的反馈**：
```
❌ "写得不好"（太模糊）
❌ "有问题"（没说什么问题）
❌ "需要改进"（没说怎么改进）
```

---

### 3. 迭代终止条件

**终止策略**：
```javascript
isSatisfactory(feedback) {
  // 策略 1：没有严重问题
  const noCriticalIssues = !feedback.includes('严重问题');
  
  // 策略 2：反馈质量下降（改进空间变小）
  const issuesCount = (feedback.match(/问题/g) || []).length;
  const lowIssues = issuesCount < 2;
  
  // 策略 3：达到最大迭代次数
  const maxIterationsReached = this.currentIteration >= this.maxIterations;
  
  return noCriticalIssues || lowIssues || maxIterationsReached;
}
```

---

### 4. 避免无限循环

**保护机制**：
```javascript
async execute(task) {
  let output = await this.generate(task);
  let previousOutput = '';
  let noImprovementCount = 0;
  
  for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
    const feedback = await this.reflect(task, output);
    
    if (this.isSatisfactory(feedback)) {
      break;
    }
    
    output = await this.revise(task, output, feedback);
    
    // 检测是否没有改进
    if (output === previousOutput) {
      noImprovementCount++;
      if (noImprovementCount >= 2) {
        console.warn('No improvement detected. Stopping.');
        break;
      }
    } else {
      noImprovementCount = 0;
    }
    
    previousOutput = output;
  }
  
  return output;
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：反馈质量差

**现象**：反馈模糊、没有具体建议。

**解决方案**：
```javascript
async reflect(task, output) {
  // 提供反馈模板
  const template = `
反馈格式：
【优点】
1. ...
2. ...

【问题】
1. 问题描述：...
   原因：...
   改进建议：...

2. 问题描述：...
   原因：...
   改进建议：...

【总体评价】
...
`;

  const prompt = `...（任务描述）\n\n${template}`;
  return await this.llm.generate(prompt);
}
```

---

### 问题 2：迭代不收敛

**现象**：反复修改但质量不提升。

**解决方案**：
```javascript
async revise(task, output, feedback) {
  // 强调针对性修改
  const prompt = `
根据以下反馈修改输出：

反馈：
${feedback}

要求：
1. 针对性地解决每个问题
2. 保持原有优点
3. 不要引入新问题
4. 如果某些反馈不合理，说明原因

修改后的输出：`;
  
  return await this.llm.generate(prompt);
}
```

---

### 问题 3：迭代次数过多

**现象**：每次都找到新问题，无法结束。

**解决方案**：
```javascript
// 设置更严格的终止条件
isSatisfactory(feedback) {
  const issuesCount = (feedback.match(/问题/g) || []).length;
  
  // 问题少于 2 个就认为满足要求
  if (issuesCount < 2) {
    return true;
  }
  
  // 检查是否有严重问题
  const hasCritical = feedback.includes('严重') || feedback.includes('重大');
  return !hasCritical;
}

// 限制最大迭代次数
const agent = new ReflectionAgent({ maxIterations: 3 }); // 减少迭代次数
```

---

## 🔧 优化技巧

### 1. Few-shot 反馈示例

提供高质量反馈示例：

```javascript
async reflect(task, output) {
  const examples = `
示例 1:
输出："这个产品很好用"
反馈：
【问题】
1. 问题描述：评价过于笼统
   原因：没有说明具体哪里好
   改进建议：添加具体优点，如"界面简洁、响应快速、功能齐全"

示例 2:
输出：function add(a,b){return a+b}
反馈：
【问题】
1. 问题描述：代码格式不规范
   原因：缺少空格，不符合编码规范
   改进建议：function add(a, b) { return a + b }
`;

  const prompt = `${examples}\n当前任务：${task}...`;
  return await this.llm.generate(prompt);
}
```

---

### 2. 多维度评估

```javascript
async reflect(task, output) {
  const dimensions = [
    { name: '准确性', score: null, comments: [] },
    { name: '完整性', score: null, comments: [] },
    { name: '清晰性', score: null, comments: [] },
    { name: '逻辑性', score: null, comments: [] }
  ];
  
  // 要求对每个维度评分
  const prompt = `
请对以下维度进行评估（1-10 分）：

1. 准确性：___/10
   评价：...

2. 完整性：___/10
   评价：...

3. 清晰性：___/10
   评价：...

4. 逻辑性：___/10
   评价：...

平均分 < 7 分需要改进。`;
  
  return await this.llm.generate(prompt);
}
```

---

### 3. 专家角色反馈

```javascript
async reflect(task, output) {
  // 根据任务类型选择专家角色
  const role = this.selectExpertRole(task);
  
  const prompt = `
你是一位${role}专家。

任务：${task}
输出：${output}

请以${role}的专业视角评估这个输出，指出专业性问题。

反馈：`;
  
  return await this.llm.generate(prompt);
}

selectExpertRole(task) {
  if (task.includes('代码')) return '资深软件工程师';
  if (task.includes('文章')) return '专业编辑';
  if (task.includes('设计')) return '资深设计师';
  return '领域专家';
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **质量提升率** | 迭代后质量提升幅度 | >30% |
| **收敛迭代次数** | 达到满意质量的迭代次数 | <3 次 |
| **反馈准确率** | 反馈指出的问题是否真实存在 | >90% |
| **用户满意度** | 用户对最终输出的评分 | >8/10 |

---

### 优化方向

1. **提高反馈质量**：更好的评估标准、示例
2. **减少迭代次数**：更准确的初始生成
3. **加速收敛**：更有针对性的修改
4. **降低成本**：减少 LLM 调用次数

---

## 🔗 相关模式

- **ReAct**：可以结合 ReAct 进行工具调用
- **Self-Critique**：更严格的自我批评
- **Plan-and-Solve**：先规划再反思执行

---

## 📚 参考资源

- **原论文**: [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.11366)
- **实现参考**: [LangChain Self-Refine](https://python.langchain.com/docs/modules/chains/popular/self_refine)
- **应用案例**: [Code Refinement with Self-Feedback](https://self-refine.github.io/)

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: patterns/single-agent/self-critique.md
content: # Self-Critique 模式 - 自我批评与修正

> **版本**: 1.0.0  
> **论文**: [Self-Critique: Enhancing Language Model Outputs](https://arxiv.org/abs/2109.05508)  
> **适用场景**: 需要高准确性、容易出错、有明确错误类型的任务

---

## 🧠 核心思想

**Self-Critique = Generate + Critique + Fix**

传统方法的问题：
- **盲目自信**：LLM 容易生成看似正确但实际错误的内容
- **缺乏验证**：生成后不检查准确性
- **幻觉问题**：编造事实、数据、引用

Self-Critique 的突破：
- **主动找错**：专门寻找输出中的错误和问题
- **结构化批评**：按错误类型系统检查
- **修正改进**：针对每个错误进行修复

**与 Reflection 的区别**：
- Reflection：全面评估（优点 + 缺点），温和改进
- Self-Critique：专注找错（缺点为主），严格批评

---

## 📊 工作流程

```
┌─────────────────────────────────────────────────────────┐
│                    Task Input                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 1: Generate Initial Output                         │
│  "生成初始答案"                                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 2: Critique (Structured Error Detection)           │
│  按错误类型系统检查：                                    │
│  - 事实错误：信息是否真实准确                            │
│  - 逻辑错误：推理是否严密                                │
│  - 计算错误：数据计算是否正确                            │
│  - 遗漏错误：是否缺少关键信息                            │
│  - 格式错误：是否符合要求格式                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 3: Fix Errors                                      │
│  "针对每个错误进行修正"                                  │
└─────────────────────────────────────────────────────────┘
                          ↓
                    是否还有错误？
                    /           \
                  是             否
                  ↓               ↓
            回到 Step 2        输出最终结果
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class SelfCritiqueAgent {
  constructor(options = {}) {
    this.maxIterations = options.maxIterations || 3;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
    this.errorTypes = options.errorTypes || this.defaultErrorTypes;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Self-Critique] 开始任务：${task}`);
    }
    
    // Step 1: 生成初始输出
    let output = await this.generate(task);
    
    if (this.verbose) {
      console.log(`[Initial Output] ${output}`);
    }
    
    for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
      if (this.verbose) {
        console.log(`\n[Iteration ${iteration}/${this.maxIterations}]`);
      }
      
      // Step 2: 结构化批评（找错）
      const critique = await this.critique(task, output);
      
      if (this.verbose) {
        console.log(`[Critique] ${JSON.stringify(critique, null, 2)}`);
      }
      
      // 如果没有错误，结束
      if (critique.errors.length === 0) {
        if (this.verbose) {
          console.log('[Complete] 未发现错误');
        }
        break;
      }
      
      // Step 3: 修正错误
      output = await this.fix(task, output, critique);
      
      if (this.verbose) {
        console.log(`[Fixed Output] ${output}`);
      }
    }
    
    return output;
  }

  /**
   * Generate: 生成初始输出
   */
  async generate(task) {
    const prompt = `
任务：${task}

请生成初始答案。

答案：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * Critique: 结构化批评，找出错误
   */
  async critique(task, output) {
    const prompt = `
任务：${task}

待检查的输出：
${output}

请按照以下错误类型进行系统检查：

${this.formatErrorTypes()}

对于每种错误类型：
1. 仔细检查是否存在此类错误
2. 如果存在，明确指出错误位置和内容
3. 说明为什么这是错误
4. 提供正确的信息或建议

请以 JSON 格式返回检查结果：
{
  "errors": [
    {
      "type": "错误类型",
      "location": "错误位置（如：第 2 段）",
      "description": "错误描述",
      "reason": "为什么这是错误",
      "suggestion": "修正建议"
    }
  ],
  "summary": "总体评价"
}

检查结果：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      // 降级方案：返回空错误列表
      console.warn('Failed to parse critique, assuming no errors');
      return { errors: [], summary: '检查完成' };
    }
  }

  /**
   * Fix: 修正错误
   */
  async fix(task, output, critique) {
    const errorsText = critique.errors.map((e, i) => 
      `${i + 1}. [${e.type}] ${e.location}: ${e.description}\n   修正建议：${e.suggestion}`
    ).join('\n');
    
    const prompt = `
任务：${task}

原始输出：
${output}

发现的错误：
${errorsText}

请修正所有错误，生成改进后的版本。

要求：
1. 逐一修正每个错误
2. 保持原有的正确信息
3. 不要引入新错误
4. 保持格式一致

修正后的输出：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 格式化错误类型列表
   */
  formatErrorTypes() {
    return this.errorTypes.map((et, i) => 
      `${i + 1}. **${et.name}**: ${et.description}\n   检查要点：${et.checkpoints.join('; ')}`
    ).join('\n\n');
  }

  /**
   * 默认错误类型
   */
  defaultErrorTypes = [
    {
      name: '事实错误',
      description: '信息是否真实、准确、可验证',
      checkpoints: [
        '数据、日期、人名、地名是否准确',
        '引用的研究、报告是否真实存在',
        '是否有编造的信息（幻觉）'
      ]
    },
    {
      name: '逻辑错误',
      description: '推理是否严密、自洽',
      checkpoints: [
        '前提是否成立',
        '推理过程是否有漏洞',
        '结论是否从前提推出',
        '是否有自相矛盾'
      ]
    },
    {
      name: '计算错误',
      description: '数学计算、统计是否正确',
      checkpoints: [
        '加减乘除是否正确',
        '百分比、比例计算是否正确',
        '单位换算是否正确'
      ]
    },
    {
      name: '遗漏错误',
      description: '是否缺少关键信息',
      checkpoints: [
        '是否回答了所有问题',
        '是否缺少必要的背景信息',
        '是否缺少重要的限制条件'
      ]
    },
    {
      name: '格式错误',
      description: '是否符合要求的格式',
      checkpoints: [
        '是否符合指定的输出格式',
        '结构是否清晰',
        '语言是否规范'
      ]
    }
  ];

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated output.';
    }
  };
}
```

---

### 使用示例

```javascript
// 创建 Agent
const agent = new SelfCritiqueAgent({
  maxIterations: 3,
  verbose: true,
  errorTypes: [
    {
      name: '代码错误',
      description: '代码是否有 bug 或问题',
      checkpoints: [
        '语法是否正确',
        '逻辑是否正确',
        '边界条件是否处理',
        '错误处理是否完整',
        '是否有安全漏洞'
      ]
    },
    {
      name: '性能问题',
      description: '代码性能是否合理',
      checkpoints: [
        '时间复杂度是否可接受',
        '空间复杂度是否合理',
        '是否有不必要的计算',
        '是否有优化空间'
      ]
    }
  ]
});

// 执行任务：代码生成
const task = '编写一个函数，计算数组中所有数字的平均值';

const result = await agent.execute(task);
console.log(result);
```

---

### 执行轨迹示例

```
[Self-Critique] 开始任务：编写一个函数，计算数组中所有数字的平均值

[Initial Output] 
function average(arr) {
  let sum = 0;
  for (let i = 0; i < arr.length; i++) {
    sum += arr[i];
  }
  return sum / arr.length;
}

[Iteration 1/3]
[Critique] {
  "errors": [
    {
      "type": "代码错误",
      "location": "第 4 行",
      "description": "没有处理空数组的情况",
      "reason": "当 arr.length 为 0 时，会返回 NaN（除以 0）",
      "suggestion": "添加空数组检查，返回 0 或抛出错误"
    },
    {
      "type": "代码错误",
      "location": "整个函数",
      "description": "没有处理非数字元素",
      "reason": "如果数组包含非数字元素，会导致意外结果",
      "suggestion": "添加类型检查或过滤"
    }
  ],
  "summary": "基本逻辑正确，但缺少边界条件处理"
}

[Fixed Output] 
function average(arr) {
  // 处理空数组
  if (!arr || arr.length === 0) {
    return 0;
  }
  
  // 过滤非数字元素
  const numbers = arr.filter(item => typeof item === 'number' && !isNaN(item));
  
  // 如果过滤后为空，返回 0
  if (numbers.length === 0) {
    return 0;
  }
  
  let sum = 0;
  for (let i = 0; i < numbers.length; i++) {
    sum += numbers[i];
  }
  
  return sum / numbers.length;
}

[Iteration 2/3]
[Critique] {
  "errors": [],
  "summary": "代码质量良好，覆盖了边界条件"
}

[Complete] 未发现错误

最终输出：（同上）
```

---

## 🎯 关键设计要点

### 1. 错误类型设计

**好的错误类型**：
- 具体明确（不是"错误"而是"事实错误"、"逻辑错误"）
- 可检查（有明确的检查要点）
- 可修正（能提供具体的修正建议）

**示例**：
```javascript
// 通用任务错误类型
const generalErrorTypes = [
  {
    name: '事实错误',
    checkpoints: ['数据准确性', '引用真实性', '无幻觉']
  },
  {
    name: '逻辑错误',
    checkpoints: ['前提成立', '推理严密', '无矛盾']
  },
  {
    name: '完整性',
    checkpoints: ['回答问题', '背景信息', '限制条件']
  }
];

// 代码任务错误类型
const codeErrorTypes = [
  {
    name: '语法错误',
    checkpoints: ['编译通过', '无语法错误']
  },
  {
    name: '运行时错误',
    checkpoints: ['边界条件', '空值处理', '异常处理']
  },
  {
    name: '安全漏洞',
    checkpoints: ['注入攻击', 'XSS', '权限检查']
  }
];
```

---

### 2. 批评质量

**好的批评**：
```
✅ "第 3 行的计算错误：5 * 3 = 15，不是 18"
✅ "缺少空数组处理：当输入为 [] 时，函数返回 NaN"
✅ "引用不存在：'Smith et al. (2020)' 在 Google Scholar 上找不到"
```

**不好的批评**：
```
❌ "有错误"（没说哪里错）
❌ "不够好"（太模糊）
❌ "需要改进"（没说怎么改进）
```

---

### 3. 避免过度批评

**问题**：批评过于苛刻，找不存在的错误。

**解决方案**：
```javascript
async critique(task, output) {
  const prompt = `
请**客观、公正**地检查以下输出。

重要：
1. 只指出真实存在的错误
2. 不要为了找错而找错
3. 如果没有错误，返回空列表
4. 区分"可以改进"和"错误"

输出：${output}

检查结果（JSON）：`;
  
  return await this.llm.generate(prompt);
}
```

---

### 4. 错误优先级

**给错误分级**：
```javascript
// 在 Critique 中添加优先级
{
  "errors": [
    {
      "type": "代码错误",
      "severity": "critical",  // critical | major | minor
      "description": "空指针异常风险",
      // ...
    }
  ]
}

// 优先修复严重错误
async fix(task, output, critique) {
  const criticalErrors = critique.errors.filter(e => e.severity === 'critical');
  
  if (criticalErrors.length === 0) {
    return output; // 没有严重错误，不需要修复
  }
  
  // 只修复严重错误
  // ...
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：批评找不到错误

**现象**：即使有明显错误，批评也返回空列表。

**解决方案**：
```javascript
async critique(task, output) {
  // 提供错误示例，引导找错
  const examples = `
示例 1:
输出："珠穆朗玛峰高 8000 米"
批评：
{
  "errors": [{
    "type": "事实错误",
    "description": "高度不准确",
    "reason": "珠穆朗玛峰实际高度是 8848.86 米",
    "suggestion": "修正为 8848.86 米"
  }]
}

示例 2:
输出："2 + 2 = 5"
批评：
{
  "errors": [{
    "type": "计算错误",
    "description": "加法错误",
    "reason": "2 + 2 = 4",
    "suggestion": "修正为 4"
  }]
}
`;

  const prompt = `${examples}\n当前任务：${task}...`;
  return await this.llm.generate(prompt);
}
```

---

### 问题 2：修复引入新错误

**现象**：修正一个错误后，引入了新错误。

**解决方案**：
```javascript
async fix(task, output, critique) {
  const prompt = `
修正以下错误：
${critique.errors.map(e => `- ${e.description}: ${e.suggestion}`).join('\n')}

重要：
1. 只修正指出的错误
2. 不要修改正确的部分
3. 修正后检查是否引入新错误
4. 保持原有结构和风格

原始输出：${output}

修正后的输出：`;
  
  return await this.llm.generate(prompt);
}

// 添加验证步骤
async execute(task) {
  // ...
  output = await this.fix(task, output, critique);
  
  // 验证修复后的输出
  const newCritique = await this.critique(task, output);
  if (newCritique.errors.length > critique.errors.length) {
    console.warn('Fix introduced new errors. Reverting.');
    // 可以尝试重新修复或使用原始输出
  }
  // ...
}
```

---

### 问题 3：无限循环

**现象**：反复找错、修复，无法结束。

**解决方案**：
```javascript
async execute(task) {
  let output = await this.generate(task);
  let previousErrors = [];
  
  for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
    const critique = await this.critique(task, output);
    
    // 检查错误是否重复
    const currentErrorHash = this.hashErrors(critique.errors);
    if (currentErrorHash === this.hashErrors(previousErrors)) {
      console.warn('Same errors detected. Stopping.');
      break;
    }
    
    if (critique.errors.length === 0) {
      break;
    }
    
    output = await this.fix(task, output, critique);
    previousErrors = critique.errors;
  }
  
  return output;
}

hashErrors(errors) {
  return errors.map(e => `${e.type}:${e.description}`).sort().join('|');
}
```

---

## 🔧 优化技巧

### 1. 专家角色批评

```javascript
async critique(task, output) {
  const role = this.selectCriticRole(task);
  
  const prompt = `
你是一位${role}，以严格、挑剔著称。

你的任务是找出输出中的**所有**错误和问题。

不要留情面，不要客气，直接指出问题。

输出：${output}

批评：`;
  
  return await this.llm.generate(prompt);
}

selectCriticRole(task) {
  if (task.includes('代码')) return '资深代码审查专家';
  if (task.includes('文章')) return '挑剔的编辑';
  if (task.includes('数据')) return '统计学教授';
  return '严格的领域专家';
}
```

---

### 2. 多轮批评

```javascript
async critique(task, output) {
  // 第 1 轮：快速扫描
  const quickCritique = await this.quickScan(task, output);
  
  // 第 2 轮：深度检查
  const deepCritique = await this.deepCheck(task, output, quickCritique);
  
  // 合并结果
  return {
    errors: [...quickCritique.errors, ...deepCritique.errors],
    summary: deepCritique.summary
  };
}

async quickScan(task, output) {
  // 快速扫描明显错误
  const prompt = `快速扫描以下输出的明显错误（10 秒内完成）：...`;
  return await this.llm.generate(prompt);
}

async deepCheck(task, output, quickCritique) {
  // 深度检查潜在问题
  const prompt = `深度检查以下输出的潜在问题，特别是 ${quickCritique.summary}：...`;
  return await this.llm.generate(prompt);
}
```

---

### 3. 交叉验证

```javascript
async critique(task, output) {
  // 使用多个 LLM 实例交叉验证
  const critiques = await Promise.all([
    this.llm1.generate(this.buildCritiquePrompt(task, output)),
    this.llm2.generate(this.buildCritiquePrompt(task, output)),
    this.llm3.generate(this.buildCritiquePrompt(task, output))
  ]);
  
  // 合并多个批评，只保留一致的发现
  const mergedErrors = this.mergeCritiques(critiques);
  
  return {
    errors: mergedErrors,
    summary: '交叉验证完成'
  };
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **错误检出率** | 检出的错误占真实错误的比例 | >90% |
| **误报率** | 错误批评的比例 | <10% |
| **修复成功率** | 修复后错误消除的比例 | >95% |
| **迭代次数** | 达到无错误状态的迭代次数 | <3 次 |

---

### 优化方向

1. **提高检出率**：更好的错误类型定义
2. **降低误报率**：更客观的批评标准
3. **提高修复率**：更有针对性的修复
4. **减少迭代**：一次性修复多个错误

---

## 🔗 相关模式

- **Reflection**：更温和的全面评估
- **ReAct**：可以结合工具调用进行验证
- **Plan-and-Solve**：先规划再批评执行

---

## 📚 参考资源

- **原论文**: [Self-Critique: Enhancing Language Model Outputs](https://arxiv.org/abs/2109.05508)
- **应用案例**: [Code Self-Critique](https://self-critique.github.io/)
- **相关研究**: [Teaching Language Models to Self-Critique](https://arxiv.org/abs/2206.05266)

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: patterns/single-agent/tree-of-thoughts.md
content: # Tree of Thoughts 模式 - 多路径探索

> **版本**: 1.0.0  
> **论文**: [Tree of Thoughts: Deliberate Problem Solving with Large Language Models](https://arxiv.org/abs/2305.10601)  
> **适用场景**: 需要创造性、有多个可能方案、可以评估方案质量的任务

---

## 🧠 核心思想

**Tree of Thoughts = Branch + Evaluate + Search**

传统方法的问题：
- **线性思考**：只沿着一条路径思考
- **容易陷入局部最优**：错过更好的解决方案
- **缺乏探索**：没有充分探索可能性

Tree of Thoughts 的突破：
- **多路径探索**：同时探索多个思考方向
- **评估选择**：评估每个路径的质量
- **智能搜索**：使用搜索算法（BFS/DFS/Beam）找到最优路径

---

## 📊 工作流程

```
┌─────────────────────────────────────────────────────────┐
│                    Task Input                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 1: Generate Initial Thoughts                       │
│  生成多个初始思考方向（3-5 个）                            │
│         Thought 1.1    Thought 1.2    Thought 1.3       │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 2: Evaluate Thoughts                               │
│  评估每个思考的质量（1-10 分）                             │
│         7.5            8.2            6.1               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 3: Select Best Thoughts                            │
│  选择 top-k 个思考继续扩展（如 k=2）                        │
│         ✓              ✓              ✗                 │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Step 4: Expand Selected Thoughts                        │
│  为每个选中的思考生成子思考                               │
│      Thought 2.1  2.2          2.3  2.4                  │
└─────────────────────────────────────────────────────────┘
                          ↓
                    重复 Step 2-4
                    直到找到解决方案或达到深度限制
```

---

## 💻 实现示例

### 基础实现（JavaScript）

```javascript
class TreeOfThoughtsAgent {
  constructor(options = {}) {
    this.maxDepth = options.maxDepth || 3;
    this.branchFactor = options.branchFactor || 3;  // 每个节点生成几个子节点
    this.beamWidth = options.beamWidth || 2;        // 保留 top-k 个节点
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Tree of Thoughts] 开始任务：${task}`);
    }
    
    // 初始化根节点
    const root = {
      id: 'root',
      thought: '',
      depth: 0,
      score: 0,
      parent: null,
      children: []
    };
    
    // 生成初始思考
    const initialThoughts = await this.generateThoughts(task, root);
    root.children = initialThoughts;
    
    if (this.verbose) {
      console.log(`[Initial Thoughts] 生成 ${initialThoughts.length} 个初始思考`);
    }
    
    // Beam Search
    let currentLevel = initialThoughts;
    
    for (let depth = 1; depth <= this.maxDepth; depth++) {
      if (this.verbose) {
        console.log(`\n[Depth ${depth}/${this.maxDepth}]`);
      }
      
      // 评估当前层的所有思考
      const evaluatedThoughts = await this.evaluateThoughts(task, currentLevel);
      
      if (this.verbose) {
        evaluatedThoughts.forEach(t => {
          console.log(`  [${t.id}] Score: ${t.score} - ${t.thought.substring(0, 50)}...`);
        });
      }
      
      // 检查是否有解决方案
      const solution = evaluatedThoughts.find(t => t.score >= 9);
      if (solution) {
        if (this.verbose) {
          console.log(`[Solution Found] ${solution.thought}`);
        }
        return this.extractSolution(task, solution);
      }
      
      // 选择 top-k 个思考
      const selectedThoughts = this.selectTopK(evaluatedThoughts, this.beamWidth);
      
      if (this.verbose) {
        console.log(`[Selected] 保留 ${selectedThoughts.length} 个思考`);
      }
      
      // 为选中的思考生成子思考
      const nextLevel = [];
      for (const thought of selectedThoughts) {
        const children = await this.generateThoughts(task, thought);
        thought.children = children;
        nextLevel.push(...children);
      }
      
      if (nextLevel.length === 0) {
        if (this.verbose) {
          console.log('[No More Thoughts] 无法继续扩展');
        }
        break;
      }
      
      currentLevel = nextLevel;
    }
    
    // 没有达到 9 分，返回最佳方案
    const bestThought = currentLevel.sort((a, b) => b.score - a.score)[0];
    return this.extractSolution(task, bestThought);
  }

  /**
   * 生成思考（分支）
   */
  async generateThoughts(task, parent) {
    const prompt = `
任务：${task}

当前思考：${parent.thought || '（初始状态）'}

请生成 ${this.branchFactor} 个不同的思考方向。

要求：
1. 每个思考应该是不同的角度或方法
2. 思考应该具体、可执行
3. 思考之间应该有差异性

请以 JSON 数组格式返回：
[
  {
    "thought": "思考内容"
  }
]

思考：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\[[\s\S]*\]/);
      if (jsonMatch) {
        const thoughts = JSON.parse(jsonMatch[0]);
        return thoughts.map((t, i) => ({
          id: `${parent.id}-${i}`,
          thought: t.thought,
          depth: parent.depth + 1,
          score: 0,
          parent: parent.id,
          children: []
        }));
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      // 降级方案
      return [{
        id: `${parent.id}-0`,
        thought: '继续探索',
        depth: parent.depth + 1,
        score: 0,
        parent: parent.id,
        children: []
      }];
    }
  }

  /**
   * 评估思考
   */
  async evaluateThoughts(task, thoughts) {
    const evaluatedThoughts = [];
    
    for (const thought of thoughts) {
      const score = await this.evaluateThought(task, thought);
      evaluatedThoughts.push({ ...thought, score });
    }
    
    return evaluatedThoughts;
  }

  /**
   * 评估单个思考
   */
  async evaluateThought(task, thought) {
    const prompt = `
任务：${task}

思考：${thought.thought}

请评估这个思考的质量（1-10 分）：

评分标准：
- 10 分：完美解决方案，直接可以实施
- 8-9 分：很好的方案，少量改进即可
- 6-7 分：可行方案，需要一些改进
- 4-5 分：有潜力，但需要大量改进
- 1-3 分：不可行或方向错误

考虑因素：
1. 可行性：这个方案可以实施吗？
2. 有效性：能解决问题吗？
3. 效率：是高效的方法吗？
4. 完整性：覆盖了关键要点吗？

评分（只返回 1-10 的数字）：`;
    
    const response = await this.llm.generate(prompt);
    const score = parseFloat(response.match(/\d+(\.\d+)?/)?.[0] || '5');
    
    return Math.min(10, Math.max(1, score));
  }

  /**
   * 选择 top-k 个思考
   */
  selectTopK(thoughts, k) {
    return thoughts
      .sort((a, b) => b.score - a.score)
      .slice(0, k);
  }

  /**
   * 提取解决方案
   */
  async extractSolution(task, thought) {
    // 回溯到根节点，构建完整路径
    const path = [];
    let current = thought;
    
    while (current && current.id !== 'root') {
      path.unshift(current.thought);
      current = this.findThoughtById(current.parent, thought);
    }
    
    const prompt = `
任务：${task}

思考路径：
${path.join('\n→ ')}

请基于这个思考路径，生成最终的解决方案。

解决方案：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 根据 ID 查找思考（简化实现）
   */
  findThoughtById(id, thought) {
    // 实际实现需要在树中搜索
    return null;
  }

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated thought.';
    }
  };
}
```

---

### 使用示例

```javascript
// 创建 Agent
const agent = new TreeOfThoughtsAgent({
  maxDepth: 3,
  branchFactor: 3,
  beamWidth: 2,
  verbose: true
});

// 执行创造性任务
const task = '设计一个创新的移动应用，帮助人们养成健康习惯';

const result = await agent.execute(task);
console.log(result);
```

---

### 执行轨迹示例

```
[Tree of Thoughts] 开始任务：设计一个创新的移动应用，帮助人们养成健康习惯

[Initial Thoughts] 生成 3 个初始思考

[Depth 1/3]
  [root-0] Score: 7.5 - 基于游戏化的习惯追踪应用...
  [root-1] Score: 8.2 - AI 驱动的个性化健康教练...
  [root-2] Score: 6.1 - 社交监督习惯打卡应用...

[Selected] 保留 2 个思考

[Depth 2/3]
  [root-0-0] Score: 8.0 - 游戏化 + 成就系统...
  [root-0-1] Score: 7.2 - 游戏化 + 社交竞争...
  [root-1-0] Score: 8.8 - AI 教练 + 实时反馈...
  [root-1-1] Score: 8.5 - AI 教练 + 社区支持...

[Selected] 保留 2 个思考

[Depth 3/3]
  [root-1-0-0] Score: 9.2 - AI 教练 + 实时反馈 + 奖励机制...
  [root-1-0-1] Score: 8.9 - AI 教练 + 实时反馈 + 社交元素...

[Solution Found] AI 教练 + 实时反馈 + 奖励机制

最终解决方案：
## HealthAI - 智能健康习惯养成应用

### 核心功能
1. **AI 健康教练**
   -  personalized 习惯建议
   - 智能调整难度
   - 预测失败风险

2. **实时反馈**
   - 运动姿势识别
   - 饮食拍照分析
   - 睡眠质量监测

3. **奖励机制**
   - 成就系统
   - 积分兑换
   - 健康保险折扣

### 创新点
- AI 实时指导，不是简单追踪
- 与保险公司合作，提供实质奖励
- 预测性干预，防止习惯中断

### 商业模式
- 免费基础版
- 高级版 $9.99/月
- 保险公司合作分成
```

---

## 🎯 关键设计要点

### 1. 思考生成策略

**好的思考**：
- 具体明确（不是"做好一点"而是"添加用户反馈功能"）
- 可实现（不是"改变世界"而是"解决 X 问题"）
- 有差异性（不同思考代表不同方向）

**生成技巧**：
```javascript
async generateThoughts(task, parent) {
  // 提供思考角度提示
  const angles = [
    '技术创新角度',
    '用户体验角度',
    '商业模式角度',
    '市场需求角度',
    '竞争优势角度'
  ];
  
  const prompt = `
请从以下角度生成思考：
${angles.join(', ')}

每个角度生成 1 个思考：`;
  
  // ...
}
```

---

### 2. 评估函数设计

**评估维度**：
```javascript
async evaluateThought(task, thought) {
  const dimensions = [
    { name: '可行性', weight: 0.3 },
    { name: '有效性', weight: 0.3 },
    { name: '创新性', weight: 0.2 },
    { name: '完整性', weight: 0.2 }
  ];
  
  // 要求对每个维度评分
  const prompt = `
请对以下维度评分（1-10 分）：

${dimensions.map(d => `- ${d.name}: ___/10`).join('\n')}

加权总分 = ${dimensions.map(d => `${d.name}*${d.weight}`).join(' + ')}
`;
  
  // ...
}
```

---

### 3. 搜索策略

**Beam Search（推荐）**：
```javascript
// 保留 top-k 个节点，平衡探索和利用
const beamWidth = 2;  // 保留 2 个最佳路径
```

**DFS（深度优先）**：
```javascript
// 一条路走到底，适合有明确方向的任务
async dfs(task, thought, depth) {
  if (depth >= this.maxDepth) {
    return thought;
  }
  
  const children = await this.generateThoughts(task, thought);
  const bestChild = await this.getBestChild(task, children);
  
  return this.dfs(task, bestChild, depth + 1);
}
```

**BFS（广度优先）**：
```javascript
// 探索所有可能，适合需要全面探索的任务
async bfs(task, root) {
  const queue = [root];
  let bestThought = root;
  
  while (queue.length > 0) {
    const current = queue.shift();
    
    if (current.score > bestThought.score) {
      bestThought = current;
    }
    
    const children = await this.generateThoughts(task, current);
    queue.push(...children);
  }
  
  return bestThought;
}
```

---

### 4. 终止条件

**终止策略**：
```javascript
// 策略 1：找到高分解决方案
if (thought.score >= 9) {
  return thought;
}

// 策略 2：达到最大深度
if (depth >= maxDepth) {
  return bestThought;
}

// 策略 3：分数不再提升
if (bestScore - previousBestScore < 0.1) {
  console.warn('Score plateau. Stopping.');
  return bestThought;
}
```

---

## ⚠️ 常见问题与解决方案

### 问题 1：思考重复

**现象**：生成的思考很相似，缺乏多样性。

**解决方案**：
```javascript
async generateThoughts(task, parent) {
  // 添加多样性要求
  const prompt = `
生成 ${this.branchFactor} 个**完全不同**的思考方向。

要求：
1. 每个思考应该从不同角度切入
2. 避免重复或相似的想法
3. 鼓励创新和多样性

思考：`;
  
  // ...
}

// 过滤重复思考
filterDuplicateThoughts(thoughts) {
  const unique = [];
  const seen = new Set();
  
  for (const thought of thoughts) {
    const hash = this.hashThought(thought.thought);
    if (!seen.has(hash)) {
      seen.add(hash);
      unique.push(thought);
    }
  }
  
  return unique;
}
```

---

### 问题 2：评估不准确

**现象**：好方案评分低，差方案评分高。

**解决方案**：
```javascript
async evaluateThought(task, thought) {
  // 使用多个评估器
  const scores = await Promise.all([
    this.evaluateWithCriteria(task, thought, '可行性'),
    this.evaluateWithCriteria(task, thought, '有效性'),
    this.evaluateWithCriteria(task, thought, '创新性')
  ]);
  
  // 取平均
  return scores.reduce((a, b) => a + b, 0) / scores.length;
}

async evaluateWithCriteria(task, thought, criteria) {
  const prompt = `
请仅从"${criteria}"角度评估（1-10 分）：

任务：${task}
思考：${thought.thought}

评分：`;
  
  // ...
}
```

---

### 问题 3：搜索空间爆炸

**现象**：思考数量指数增长，无法处理。

**解决方案**：
```javascript
// 限制 beam width
const beamWidth = 2;  // 只保留 top-2

// 限制深度
const maxDepth = 3;   // 最多 3 层

// 剪枝：去掉低分思考
const prunedThoughts = thoughts.filter(t => t.score >= 6);
```

---

## 🔧 优化技巧

### 1. 启发式评估

```javascript
async evaluateThought(task, thought) {
  // 快速启发式评估
  const quickScore = this.heuristicEvaluate(task, thought);
  
  // 只对高分思考进行详细评估
  if (quickScore >= 7) {
    return await this.detailedEvaluate(task, thought);
  }
  
  return quickScore;
}

heuristicEvaluate(task, thought) {
  // 快速规则评估
  let score = 5;
  
  if (thought.thought.includes('AI')) score += 1;
  if (thought.thought.includes('用户')) score += 1;
  if (thought.thought.length > 20) score += 1;
  
  return score;
}
```

---

### 2. 思考链回溯

```javascript
async extractSolution(task, thought) {
  // 回溯完整路径
  const path = this.backtrack(thought);
  
  const prompt = `
任务：${task}

完整思考路径：
${path.map((t, i) => `Step ${i}: ${t.thought}`).join('\n')}

请基于这个思考路径，生成最终解决方案。

要求：
1. 整合路径中的所有要点
2. 说明为什么选择这个路径
3. 提供具体实施方案

解决方案：`;
  
  return await this.llm.generate(prompt);
}

backtrack(thought) {
  const path = [];
  let current = thought;
  
  while (current) {
    path.unshift(current);
    current = current.parent;
  }
  
  return path;
}
```

---

### 3. 并行评估

```javascript
async evaluateThoughts(task, thoughts) {
  // 并行评估所有思考
  const scores = await Promise.all(
    thoughts.map(t => this.evaluateThought(task, t))
  );
  
  return thoughts.map((t, i) => ({ ...t, score: scores[i] }));
}
```

---

## 📊 性能评估

### 评估指标

| 指标 | 描述 | 目标 |
|------|------|------|
| **解决方案质量** | 最终方案的评分 | >8/10 |
| **探索效率** | 找到好方案的思考数量 | <20 个 |
| **多样性** | 探索的不同方向数量 | >5 个 |
| **执行时间** | 从开始到完成的时间 | <2 分钟 |

---

### 优化方向

1. **提高评估准确性**：多维度评估
2. **减少搜索空间**：更好的剪枝策略
3. **加速评估**：并行评估、启发式
4. **提高多样性**：强制多样性生成

---

## 🔗 相关模式

- **ReAct**：可以在思考生成时使用工具
- **Plan-and-Solve**：可以将 ToT 用于规划阶段
- **Reflection**：可以在评估时进行反思

---

## 📚 参考资源

- **原论文**: [Tree of Thoughts: Deliberate Problem Solving](https://arxiv.org/abs/2305.10601)
- **实现参考**: [ToT GitHub](https://github.com/princeton-nlp/tree-of-thought-llm)
- **应用案例**: [Creative Writing with ToT](https://tree-of-thought.github.io/)

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: PUBLISH.md
content: # 🚀 发布到 ClawHub 指南

## 前置条件

- ✅ 已完成技能开发
- ✅ 已通过单元测试
- ✅ 已登录 ClawHub (`clawhub login`)

---

## 发布步骤

### 步骤 1: 登录 ClawHub

```bash
clawhub login
```

浏览器会自动打开，完成认证后返回终端。

验证登录状态：
```bash
clawhub whoami
# 应显示：✓ Logged in as <your-username>
```

---

### 步骤 2: 准备发布

检查技能文件结构：

```bash
# 查看技能目录
tree skills/agent-architecture-patterns/

# 确保包含必要文件：
# - SKILL.md (必需)
# - README.md (推荐)
# - package.json (推荐)
# - 源代码和文档
```

---

### 步骤 3: 发布技能

```bash
clawhub publish skills/agent-architecture-patterns
```

发布命令会：
1. 读取 `SKILL.md` 获取技能元数据
2. 打包所有文件
3. 上传到 ClawHub 注册表
4. 返回技能 slug 和访问链接

---

### 步骤 4: 验证发布

```bash
# 搜索已发布的技能
clawhub search agent-architecture-patterns

# 查看技能详情
clawhub inspect agent-architecture-patterns
```

---

## 发布后

### 分享链接

发布成功后，技能可通过以下链接访问：

```
https://clawhub.ai/skills/<your-username>/agent-architecture-patterns
```

### 安装命令

其他人可以通过以下命令安装：

```bash
clawhub install agent-architecture-patterns
```

---

## 更新技能

修改技能后，更新发布：

```bash
# 更新版本号 (在 SKILL.md 中)
# 然后重新发布
clawhub update agent-architecture-patterns
```

---

## 常见问题

### Q: 发布失败怎么办？

**A**: 检查以下项：
- 是否已登录 (`clawhub whoami`)
- `SKILL.md` 格式是否正确
- 网络连接是否正常

### Q: 如何删除已发布的技能？

**A**: 
```bash
clawhub delete agent-architecture-patterns
```

### Q: 如何转移技能所有权？

**A**: 
```bash
clawhub transfer agent-architecture-patterns <new-owner>
```

---

## 技能元数据

`SKILL.md` 中应包含：

```markdown
# agent-architecture-patterns - AI Agent 架构设计模式

> **版本**: 1.0.0
> **作者**: AI-Agent
> **描述**: 提供 10 种 AI Agent 架构设计模式...
```

ClawHub 会从中提取：
- 技能名称
- 版本号
- 描述
- 作者信息

---

## 发布清单

- [ ] 登录 ClawHub
- [ ] 检查 SKILL.md 格式
- [ ] 运行测试确保通过
- [ ] 执行发布命令
- [ ] 验证发布成功
- [ ] 分享技能链接

---

**祝发布顺利！** 🎉


path: README.md
content: # agent-architecture-patterns - 使用文档

> **版本**: 1.0.0  
> **创建时间**: 2026-04-02  
> **维护者**: AI-Agent

---

## 📖 快速开始

### 1. 安装技能

```bash
openclaw skills install agent-architecture-patterns
```

或手动克隆：
```bash
git clone https://github.com/your-repo/agent-architecture-patterns.git \
  ~/.openclaw/workspace-AI-Agent/skills/agent-architecture-patterns
```

---

### 2. 使用方式

#### 方式 A：咨询 AI-Agent

直接向 AI-Agent 提问架构设计问题：

```
"设计一个多 Agent 代码审查系统"
"ReAct 模式如何实现？"
"如何选择合适的 Agent 协作模式？"
```

AI-Agent 会基于本技能的知识库提供专业建议。

---

#### 方式 B：参考模式文档

浏览 `patterns/` 目录查看详细模式文档：

**单 Agent 模式**：
- `patterns/single-agent/react.md` - ReAct 模式
- `patterns/single-agent/reflection.md` - Reflection 模式
- `patterns/single-agent/self-critique.md` - Self-Critique 模式
- `patterns/single-agent/plan-and-solve.md` - Plan-and-Solve 模式
- `patterns/single-agent/tree-of-thoughts.md` - Tree of Thoughts 模式

**多 Agent 模式**：
- `patterns/multi-agent/manager-worker.md` - 主从模式
- `patterns/multi-agent/peer-to-peer.md` - 对等模式
- `patterns/multi-agent/hierarchical.md` - 层级模式
- `patterns/multi-agent/market-based.md` - 市场模式
- `patterns/multi-agent/pipeline.md` - 流水线模式

---

#### 方式 C：使用代码示例

参考 `examples/` 目录中的完整示例代码：

```bash
# 查看示例列表
ls examples/

# 运行示例（如果提供）
node examples/react-example.js
```

---

## 🎯 场景化使用指南

### 场景 1：设计单 Agent 系统

**问题**："我需要一个能自动回答用户问题的 Agent"

**步骤**：

1. **分析需求**
   - 是否需要调用工具？→ 是（搜索、计算等）
   - 是否需要多步推理？→ 是
   - 质量要求？→ 高

2. **选择模式**
   - 需要工具调用 → ReAct
   - 需要高质量 → ReAct + Reflection

3. **参考文档**
   - 阅读 `patterns/single-agent/react.md`
   - 复制示例代码
   - 根据需求修改

4. **实现代码**
   ```javascript
   const agent = new ReActAgent({
     tools: [search, calculate],
     maxSteps: 10
   });
   
   const answer = await agent.execute(userQuestion);
   ```

---

### 场景 2：设计多 Agent 系统

**问题**："我需要一个多 Agent 代码审查系统"

**步骤**：

1. **分析需求**
   - 任务可分解？→ 是（语法检查、风格检查、安全扫描等）
   - 需要协调？→ 是
   - 团队规模？→ 小（3-5 个 Agent）

2. **选择模式**
   - 任务可分解 + 需要协调 → 主从模式

3. **参考文档**
   - 阅读 `patterns/multi-agent/manager-worker.md`
   - 设计 Manager 和 Worker 职责

4. **实现代码**
   ```javascript
   const workers = [
     new WorkerAgent('syntax-checker', ['javascript'], { codeReview: true }),
     new WorkerAgent('style-checker', ['javascript'], { codeReview: true }),
     new WorkerAgent('security-scanner', ['security'], { codeReview: true })
   ];
   
   const manager = new ManagerAgent(workers);
   const report = await manager.coordinate('审查这个项目');
   ```

---

### 场景 3：选择架构模式

**问题**："我应该用哪种 Agent 架构？"

**决策树**：

```
任务复杂度？
├─ 简单（单步骤）
│   └─→ 直接执行（无需特殊模式）
│
├─ 中等（需要工具/多步）
│   ├─ 单 Agent 足够？
│   │   ├─ 是 → ReAct 模式
│   │   └─ 否 → 多 Agent 模式
│   │
│   └─ 多 Agent？
│       ├─ 任务可分解？ → 主从模式
│       ├─ 任务可并行？ → 对等模式
│       └─ 多阶段处理？ → 流水线模式
│
└─ 复杂（需要规划/探索）
    ├─ 需要规划？ → Plan-and-Solve
    ├─ 需要探索多路径？ → Tree of Thoughts
    └─ 需要高质量？ → Reflection / Self-Critique
```

---

## 📋 最佳实践清单

### 设计前

- [ ] 明确任务目标和约束
- [ ] 分析任务复杂度
- [ ] 评估可用资源（Agent 数量、能力）
- [ ] 考虑性能要求（响应时间、吞吐量）

### 设计中

- [ ] 选择合适的架构模式
- [ ] 定义清晰的接口（输入、输出、错误）
- [ ] 设计容错机制（重试、降级、超时）
- [ ] 规划监控和日志

### 实现中

- [ ] 从简单开始（先单 Agent，后多 Agent）
- [ ] 编写单元测试
- [ ] 添加详细日志
- [ ] 记录设计决策（ADR）

### 测试中

- [ ] 功能测试（是否完成目标）
- [ ] 性能测试（响应时间、并发）
- [ ] 容错测试（失败恢复）
- [ ] 边界测试（极端情况）

### 上线后

- [ ] 监控运行状态
- [ ] 收集用户反馈
- [ ] 定期优化改进
- [ ] 更新文档

---

## 🔧 常见问题

### Q1: 如何调试 ReAct Agent？

**A**: 启用详细日志：

```javascript
class DebuggableReActAgent extends ReActAgent {
  async execute(task) {
    console.log('=== ReAct Debug Start ===');
    console.log('Task:', task);
    
    const result = await super.execute(task);
    
    console.log('Result:', result);
    console.log('=== ReAct Debug End ===');
    
    return result;
  }
  
  async reason(task, history) {
    const thought = await super.reason(task, history);
    console.log(`[Thought] ${thought}`);
    return thought;
  }
  
  async decideAction(thought, history) {
    const action = await super.decideAction(thought, history);
    console.log(`[Action] ${JSON.stringify(action)}`);
    return action;
  }
  
  async observe(action) {
    const observation = await super.observe(action);
    console.log(`[Observation] ${observation}`);
    return observation;
  }
}
```

---

### Q2: 多 Agent 系统如何避免死锁？

**A**: 遵循以下原则：

1. **避免循环依赖**：Agent A 等 B，B 等 A
2. **设置超时**：所有等待都有超时
3. **使用异步**：非阻塞通信
4. **监控等待**：检测长时间等待

```javascript
async executeWithTimeout(agent, task, timeout = 30000) {
  return Promise.race([
    agent.execute(task),
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Timeout')), timeout)
    )
  ]);
}
```

---

### Q3: 如何评估 Agent 系统的质量？

**A**: 从以下维度评估：

| 维度 | 指标 | 测量方法 |
|------|------|----------|
| **功能性** | 任务完成率 | 成功次数 / 总次数 |
| **性能** | 响应时间 | 平均/95 分位延迟 |
| **可靠性** | 错误率 | 失败次数 / 总次数 |
| **质量** | 输出评分 | 人工评估/自动评估 |
| **成本** | Token 消耗 | 每次任务平均 Token 数 |

---

## 📚 进阶主题

### 1. 模式组合

模式可以组合使用：

- **ReAct + Reflection**：更高质量的单 Agent
- **Manager-Worker + Pipeline**：分层流水线
- **Tree of Thoughts + Market**：多路径竞价

示例：
```javascript
class ReflectiveReActAgent extends ReActAgent {
  async execute(task) {
    let result = await super.execute(task);
    
    // 反思
    const reflection = await this.reflect(result);
    if (reflection.needsImprovement) {
      // 改进
      result = await this.revise(result, reflection);
    }
    
    return result;
  }
}
```

---

### 2. 性能优化

**优化方向**：

1. **减少 LLM 调用**：缓存、批处理
2. **并行执行**：独立任务并行
3. **流式输出**：边生成边输出
4. **模型选择**：简单任务用小模型

示例：
```javascript
// 批处理工具调用
async executeBatch(actions) {
  const results = await Promise.all(
    actions.map(action => this.observe(action))
  );
  return results;
}
```

---

### 3. 可观测性

**添加监控**：

```javascript
class ObservableAgent {
  constructor(agent, metrics) {
    this.agent = agent;
    this.metrics = metrics;
  }
  
  async execute(task) {
    const startTime = Date.now();
    
    try {
      const result = await this.agent.execute(task);
      
      this.metrics.increment('agent.success');
      this.metrics.histogram('agent.latency', Date.now() - startTime);
      
      return result;
    } catch (error) {
      this.metrics.increment('agent.failure');
      throw error;
    }
  }
}
```

---

## 🔗 相关资源

### 文档
- [SKILL.md](SKILL.md) - 技能说明
- [patterns/README.md](patterns/README.md) - 模式总览

### 外部资源
- [CrewAI](https://github.com/joaomdmoura/crewAI)
- [AutoGen](https://github.com/microsoft/autogen)
- [LangChain](https://github.com/langchain-ai/langchain)

---

## 📝 更新日志

### v1.0.0 (2026-04-02)
- ✅ 初始版本
- ✅ 5 种单 Agent 模式
- ✅ 5 种多 Agent 模式
- ✅ 完整使用文档

---

**维护者**: AI-Agent  
**版本**: 1.0.0  
**最后更新**: 2026-04-02  
**下次回顾**: 2026-04-09


path: src/agents/manager-worker-agent.js
content: /**
 * Manager-Worker Agent - 多 Agent 协作模式实现
 * 
 * 主从模式：1 个 Manager 协调多个 Worker
 */

class ManagerAgent {
  constructor(workers, options = {}) {
    this.workers = workers;
    this.maxRetries = options.maxRetries || 3;
    this.timeout = options.timeout || 30000;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  /**
   * 协调任务执行
   * @param {string} task - 任务描述
   * @returns {Promise<string>} - 最终结果
   */
  async coordinate(task) {
    if (this.verbose) {
      console.log(`[Manager] 接收任务：${task}`);
    }
    
    // Step 1: 任务分解
    const subtasks = await this.decompose(task);
    if (this.verbose) {
      console.log(`[Manager] 分解为 ${subtasks.length} 个子任务`);
      subtasks.forEach((st, i) => {
        console.log(`  ${i + 1}. ${st.description}`);
      });
    }
    
    // Step 2: 任务分配
    const assignments = this.assign(subtasks);
    if (this.verbose) {
      console.log(`[Manager] 分配任务给 Worker`);
    }
    
    // Step 3: 并行执行
    const results = await this.executeParallel(assignments);
    if (this.verbose) {
      console.log(`[Manager] 收到 ${results.length} 个结果`);
    }
    
    // Step 4: 结果整合
    const finalResult = await this.integrate(task, results);
    if (this.verbose) {
      console.log(`[Manager] 任务完成`);
    }
    
    return finalResult;
  }

  /**
   * 任务分解
   */
  async decompose(task) {
    const prompt = `
将以下任务分解为独立的子任务：
${task}

要求：
1. 每个子任务应该是独立的（可并行执行）
2. 子任务数量适中（3-10 个）
3. 明确每个子任务的目标
4. 识别每个子任务需要的技能

请以 JSON 数组格式返回（只返回 JSON）：
[
  {
    "id": "task-1",
    "description": "子任务描述",
    "requiredSkills": ["技能 1", "技能 2"]
  }
]

子任务列表：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\[[\s\S]*\]/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      console.warn('Failed to parse subtasks, using fallback');
      // 降级方案：返回单个子任务
      return [{
        id: 'task-1',
        description: task,
        requiredSkills: []
      }];
    }
  }

  /**
   * 任务分配
   */
  assign(subtasks) {
    const assignments = new Map();
    
    for (const subtask of subtasks) {
      const worker = this.selectWorker(subtask);
      
      if (!assignments.has(worker.id)) {
        assignments.set(worker.id, []);
      }
      assignments.get(worker.id).push(subtask);
      
      if (this.verbose) {
        console.log(`  ${subtask.description} → ${worker.id}`);
      }
    }
    
    return assignments;
  }

  /**
   * 选择最合适的 Worker
   */
  selectWorker(subtask) {
    const requiredSkills = subtask.requiredSkills || [];
    
    let bestWorker = null;
    let bestScore = -1;
    
    for (const worker of this.workers) {
      const score = this.calculateMatchScore(worker, requiredSkills);
      if (score > bestScore) {
        bestScore = score;
        bestWorker = worker;
      }
    }
    
    return bestWorker || this.workers[0];
  }

  /**
   * 计算技能匹配分数
   */
  calculateMatchScore(worker, requiredSkills) {
    if (requiredSkills.length === 0) {
      return 0.5; // 无技能要求，默认分数
    }
    
    const workerSkills = new Set(worker.skills || []);
    const matchedSkills = requiredSkills.filter(skill => 
      workerSkills.has(skill)
    );
    
    return matchedSkills.length / requiredSkills.length;
  }

  /**
   * 并行执行
   */
  async executeParallel(assignments) {
    const promises = [];
    
    for (const [workerId, subtasks] of assignments) {
      const worker = this.workers.find(w => w.id === workerId);
      
      if (!worker) {
        console.warn(`Worker ${workerId} not found`);
        continue;
      }
      
      const workerPromise = Promise.all(
        subtasks.map(subtask => this.executeWithRetry(worker, subtask))
      );
      
      promises.push(workerPromise);
    }
    
    const results = await Promise.all(promises);
    return results.flat();
  }

  /**
   * 带重试的执行
   */
  async executeWithRetry(worker, subtask) {
    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
      try {
        const result = await Promise.race([
          worker.execute(subtask),
          this.timeoutPromise(this.timeout)
        ]);
        
        if (this.verbose) {
          console.log(`[Worker ${worker.id}] ✅ ${subtask.description}`);
        }
        
        return {
          taskId: subtask.id,
          success: true,
          result,
          worker: worker.id
        };
      } catch (error) {
        if (this.verbose) {
          console.warn(`[Worker ${worker.id}] ❌ 尝试 ${attempt} 失败：${error.message}`);
        }
        
        if (attempt === this.maxRetries) {
          return {
            taskId: subtask.id,
            success: false,
            error: error.message,
            worker: worker.id
          };
        }
        
        // 指数退避
        await this.sleep(1000 * Math.pow(2, attempt));
      }
    }
  }

  /**
   * 超时 Promise
   */
  timeoutPromise(timeout) {
    return new Promise((_, reject) => {
      setTimeout(() => reject(new Error('Timeout')), timeout);
    });
  }

  /**
   * 睡眠
   */
  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  /**
   * 整合结果
   */
  async integrate(task, results) {
    const successfulResults = results.filter(r => r.success);
    const failedResults = results.filter(r => !r.success);
    
    const prompt = `
原始任务：${task}

成功执行的结果 (${successfulResults.length}个):
${JSON.stringify(successfulResults.map(r => ({
  taskId: r.taskId,
  result: r.result
})), null, 2)}

失败的结果 (${failedResults.length}个):
${JSON.stringify(failedResults, null, 2)}

请整合所有成功结果，生成最终答案。
如果有失败的任务，说明影响。

要求：
1. 结构清晰
2. 信息完整
3. 语言简洁

最终答案：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 默认 LLM 实现
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM. Please provide a real LLM implementation.');
      return 'Task completed.';
    }
  };
}

/**
 * Worker Agent
 */
class WorkerAgent {
  constructor(id, skills, capabilities) {
    this.id = id;
    this.skills = skills || [];
    this.capabilities = capabilities || {};
    this.llm = capabilities.llm || this.defaultLLM;
  }

  /**
   * 执行子任务
   */
  async execute(subtask) {
    if (this.verbose) {
      console.log(`[Worker ${this.id}] 执行：${subtask.description}`);
    }
    
    // 根据能力选择执行方式
    if (this.capabilities.codeReview) {
      return await this.reviewCode(subtask);
    } else if (this.capabilities.webSearch) {
      return await this.searchWeb(subtask);
    } else if (this.capabilities.dataAnalysis) {
      return await this.analyzeData(subtask);
    } else {
      return await this.genericExecute(subtask);
    }
  }

  /**
   * 代码审查
   */
  async reviewCode(subtask) {
    const code = subtask.code || '';
    
    const prompt = `
审查以下代码：
${code}

关注点：
- 代码质量
- 潜在 bug
- 性能问题
- 安全漏洞
- 最佳实践

审查结果：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 网络搜索
   */
  async searchWeb(subtask) {
    const query = subtask.query || subtask.description;
    
    // 实际实现调用搜索 API
    const prompt = `
搜索以下信息：
${query}

提供准确、相关的信息：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 数据分析
   */
  async analyzeData(subtask) {
    const data = subtask.data || {};
    
    const prompt = `
分析以下数据：
${JSON.stringify(data, null, 2)}

提供：
1. 数据摘要
2. 关键发现
3. 趋势分析
4. 建议

分析结果：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 通用执行
   */
  async genericExecute(subtask) {
    const prompt = `
执行以下任务：
${subtask.description}

结果：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 默认 LLM
   */
  defaultLLM = {
    generate: async (prompt) => {
      console.warn(`[Worker ${this.id}] Using default LLM.`);
      return 'Task completed.';
    }
  };
}

module.exports = { ManagerAgent, WorkerAgent };


path: src/agents/plan-and-solve-agent.js
content: /**
 * Plan-and-Solve Agent - 规划与执行模式实现
 * 
 * 核心：Understand → Plan → Execute → Synthesize
 */

class PlanAndSolveAgent {
  constructor(options = {}) {
    this.maxSteps = options.maxSteps || 20;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Plan-and-Solve] 开始任务：${task}`);
    }
    
    // Phase 1: Understand
    const understanding = await this.understand(task);
    
    if (this.verbose) {
      console.log('\n[Understanding]');
      console.log(`  Goal: ${understanding.goal}`);
      console.log(`  Constraints: ${understanding.constraints.join(', ')}`);
      console.log(`  Success Criteria: ${understanding.successCriteria.join(', ')}\n`);
    }
    
    // Phase 2: Plan
    const plan = await this.plan(task, understanding);
    
    if (this.verbose) {
      console.log(`[Plan] Total ${plan.steps.length} steps`);
      plan.steps.forEach((step, i) => {
        console.log(`  ${i + 1}. ${step.description}`);
      });
      console.log();
    }
    
    // Phase 3: Execute
    const executionResults = await this.executePlan(task, plan);
    
    if (this.verbose) {
      console.log(`\n[Execution Complete] ${executionResults.completed}/${executionResults.total} steps`);
    }
    
    // Phase 4: Synthesize
    const finalResult = await this.synthesize(task, understanding, executionResults);
    
    if (this.verbose) {
      console.log(`\n[Final Result]\n${finalResult}`);
    }
    
    return finalResult;
  }

  async understand(task) {
    const prompt = `
任务：${task}

请分析这个任务：

1. **任务目标**：要达成什么？
2. **约束条件**：有哪些限制？（时间、资源、技术等）
3. **成功标准**：如何判断任务完成？

请以 JSON 格式返回：
{
  "goal": "任务目标",
  "constraints": ["约束 1", "约束 2"],
  "successCriteria": ["标准 1", "标准 2"]
}

分析结果：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      return {
        goal: task,
        constraints: [],
        successCriteria: ['Task completed']
      };
    }
  }

  async plan(task, understanding) {
    const prompt = `
任务：${task}

目标：${understanding.goal}

约束：${understanding.constraints.join(', ')}

成功标准：${understanding.successCriteria.join(', ')}

请制定详细的执行计划：

要求：
1. 将任务分解为具体的、可执行的步骤
2. 步骤之间可能有依赖关系
3. 每个步骤应该有清晰的完成标准
4. 步骤数量适中（5-15 步）

请以 JSON 格式返回：
{
  "steps": [
    {
      "id": 1,
      "description": "步骤描述",
      "dependencies": [],
      "expectedOutput": "预期输出"
    }
  ]
}

计划：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      return {
        steps: [{
          id: 1,
          description: task,
          dependencies: [],
          expectedOutput: 'Complete task'
        }]
      };
    }
  }

  async executePlan(task, plan) {
    const results = {
      total: plan.steps.length,
      completed: 0,
      failed: 0,
      stepResults: []
    };
    
    const completedSteps = new Set();
    
    for (let stepNum = 0; stepNum < plan.steps.length; stepNum++) {
      const executableStep = plan.steps.find(step => 
        !completedSteps.has(step.id) &&
        step.dependencies.every(depId => completedSteps.has(depId))
      );
      
      if (!executableStep) {
        break;
      }
      
      if (this.verbose) {
        console.log(`[Step ${executableStep.id}/${plan.steps.length}] ${executableStep.description}`);
      }
      
      const result = await this.executeStep(task, executableStep, results.stepResults);
      
      results.stepResults.push({
        stepId: executableStep.id,
        description: executableStep.description,
        success: result.success,
        output: result.output,
        error: result.error
      });
      
      if (result.success) {
        completedSteps.add(executableStep.id);
        results.completed++;
        
        if (this.verbose) {
          console.log('  ✅ Done\n');
        }
      } else {
        results.failed++;
        
        if (this.verbose) {
          console.log(`  ❌ Failed: ${result.error}\n`);
        }
      }
    }
    
    return results;
  }

  async executeStep(task, step, previousResults) {
    const context = previousResults.map(r => 
      `Step ${r.stepId}: ${r.output}`
    ).join('\n');
    
    const prompt = `
任务：${task}

当前步骤：${step.description}
预期输出：${step.expectedOutput}

之前的执行结果：
${context || '(None)'}

请执行当前步骤。

结果：`;
    
    try {
      const output = await this.llm.generate(prompt);
      return { success: true, output };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  async synthesize(task, understanding, executionResults) {
    const resultsText = executionResults.stepResults.map(r => 
      `Step ${r.stepId}: ${r.success ? '✅' : '❌'} ${r.output || r.error}`
    ).join('\n');
    
    const prompt = `
任务：${task}

目标：${understanding.goal}

成功标准：${understanding.successCriteria.join(', ')}

执行结果：
${resultsText}

完成进度：${executionResults.completed}/${executionResults.total} steps

请整合所有执行结果，生成最终输出。

最终输出：`;
    
    return await this.llm.generate(prompt);
  }

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Task completed.';
    }
  };
}

module.exports = { PlanAndSolveAgent };


path: src/agents/react-agent.js
content: /**
 * ReAct Agent - 单 Agent 架构模式实现
 * 
 * ReAct = Reasoning + Acting
 * 交替进行推理和行动，协同增强
 */

class ReActAgent {
  constructor(options = {}) {
    this.tools = options.tools || {};
    this.maxSteps = options.maxSteps || 10;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  /**
   * 执行任务
   * @param {string} task - 任务描述
   * @returns {Promise<string>} - 最终答案
   */
  async execute(task) {
    const history = [];
    
    if (this.verbose) {
      console.log(`[ReAct] 开始执行任务：${task}`);
    }
    
    for (let step = 0; step < this.maxSteps; step++) {
      if (this.verbose) {
        console.log(`\n[Step ${step + 1}/${this.maxSteps}]`);
      }
      
      // Step 1: Thought - 思考下一步
      const thought = await this.reason(task, history);
      if (this.verbose) {
        console.log(`[Thought] ${thought}`);
      }
      
      // Step 2: Action - 决定行动
      const action = await this.decideAction(thought, history);
      if (this.verbose) {
        console.log(`[Action] ${action.name}(${JSON.stringify(action.args)})`);
      }
      
      // Step 3: Observation - 执行并观察结果
      const observation = await this.observe(action);
      if (this.verbose) {
        console.log(`[Observation] ${observation}`);
      }
      
      // 记录历史
      history.push({ step: step + 1, thought, action, observation });
      
      // 判断是否完成
      if (this.isComplete(thought, observation)) {
        const answer = await this.finalize(task, history);
        if (this.verbose) {
          console.log(`\n[Answer] ${answer}`);
        }
        return answer;
      }
    }
    
    throw new Error(`Max steps (${this.maxSteps}) reached without completion`);
  }

  /**
   * 推理：思考下一步
   */
  async reason(task, history) {
    const context = this.buildContext(task, history);
    
    const prompt = `
当前任务：${task}

历史对话：
${this.formatHistory(history)}

请思考：
1. 当前已知什么信息？
2. 还需要什么信息？
3. 下一步应该做什么？

可用工具：
${this.listTools()}

思考：`;
    
    const response = await this.llm.generate(prompt);
    return response.trim();
  }

  /**
   * 决定行动：根据思考选择工具和参数
   */
  async decideAction(thought, history) {
    const prompt = `
基于以下思考，决定采取什么行动：
${thought}

可用工具：
${this.listTools()}

请以 JSON 格式返回行动（只返回 JSON，不要其他内容）：
{
  "name": "工具名称",
  "args": {
    "参数名": "参数值"
  }
}

行动：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      // 尝试解析 JSON
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      // 如果解析失败，尝试从文本中提取
      return this.extractActionFromText(response);
    }
  }

  /**
   * 观察：执行工具并返回结果
   */
  async observe(action) {
    const tool = this.tools[action.name];
    
    if (!tool) {
      return `Error: Unknown tool "${action.name}". Available tools: ${Object.keys(this.tools).join(', ')}`;
    }
    
    try {
      const result = await tool.execute(action.args);
      return result.toString();
    } catch (error) {
      return `Error: ${error.message}`;
    }
  }

  /**
   * 判断是否完成
   */
  isComplete(thought, observation) {
    const finishKeywords = [
      'finish',
      'answer is',
      '最终答案是',
      '完成任务',
      '可以给出答案',
      '不需要更多'
    ];
    
    const lowerThought = thought.toLowerCase();
    return finishKeywords.some(keyword => lowerThought.includes(keyword));
  }

  /**
   * 生成最终答案
   */
  async finalize(task, history) {
    const prompt = `
任务：${task}

完整历史：
${this.formatHistory(history)}

请给出最终答案（简洁、准确、完整）：

最终答案：`;
    
    return await this.llm.generate(prompt);
  }

  /**
   * 构建上下文
   */
  buildContext(task, history) {
    return { task, history };
  }

  /**
   * 列出可用工具
   */
  listTools() {
    return Object.entries(this.tools)
      .map(([name, tool]) => `- ${name}: ${tool.description}`)
      .join('\n');
  }

  /**
   * 格式化历史
   */
  formatHistory(history) {
    if (history.length === 0) {
      return '（无历史记录）';
    }
    
    return history.map(h => 
      `步骤 ${h.step}:\n  思考：${h.thought}\n  行动：${h.action.name}(${JSON.stringify(h.action.args)})\n  观察：${h.observation}`
    ).join('\n\n');
  }

  /**
   * 从文本中提取行动（备用方案）
   */
  extractActionFromText(text) {
    // 尝试提取工具名称和参数
    const toolMatch = text.match(/(?:使用 | 调用 | use|call)\s*(\w+)/i);
    const toolName = toolMatch ? toolMatch[1] : Object.keys(this.tools)[0];
    
    // 尝试提取参数
    const args = {};
    const paramMatches = text.matchAll(/(\w+)\s*[=:]\s*["']?([^"'\n,}]+)["']?/g);
    for (const match of paramMatches) {
      args[match[1]] = match[2].trim();
    }
    
    return { name: toolName, args };
  }

  /**
   * 默认 LLM 实现（需要替换为实际 API）
   */
  defaultLLM = {
    generate: async (prompt) => {
      // 这里应该调用实际的 LLM API（OpenAI/Claude/Qwen 等）
      // 示例中返回占位符
      console.warn('[Warning] Using default LLM. Please provide a real LLM implementation.');
      return 'I need more information to complete this task.';
    }
  };
}

module.exports = { ReActAgent };


path: src/agents/reflection-agent.js
content: /**
 * Reflection Agent - 自我反思与改进模式实现
 * 
 * 核心：Generate → Reflect → Revise → Repeat
 */

class ReflectionAgent {
  constructor(options = {}) {
    this.maxIterations = options.maxIterations || 5;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
    this.criteria = options.criteria || this.defaultCriteria;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Reflection] 开始任务：${task}`);
    }
    
    // Generate: 初始输出
    let output = await this.generate(task);
    
    if (this.verbose) {
      console.log(`\n[Initial Output]\n${output}\n`);
    }
    
    // Reflect & Revise 循环
    for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
      if (this.verbose) {
        console.log(`\n[Iteration ${iteration}/${this.maxIterations}]`);
      }
      
      // Reflect: 评估
      const feedback = await this.reflect(task, output);
      
      if (this.verbose) {
        console.log(`[Feedback]\n${feedback}\n`);
      }
      
      // 检查是否满足标准
      if (this.isSatisfactory(feedback)) {
        if (this.verbose) {
          console.log('[Complete] 输出质量满足要求');
        }
        break;
      }
      
      // Revise: 修改
      output = await this.revise(task, output, feedback);
      
      if (this.verbose) {
        console.log(`[Revised Output]\n${output}\n`);
      }
    }
    
    return output;
  }

  async generate(task) {
    const prompt = `
任务：${task}

请生成初始输出。

初始输出：`;
    
    return await this.llm.generate(prompt);
  }

  async reflect(task, output) {
    const prompt = `
任务：${task}

当前输出：
${output}

请评估这个输出，考虑以下标准：
${this.formatCriteria()}

反馈要求：
1. 指出具体问题（至少 3 个）
2. 说明为什么是问题
3. 提供改进建议

反馈：`;
    
    return await this.llm.generate(prompt);
  }

  async revise(task, output, feedback) {
    const prompt = `
任务：${task}

当前输出：
${output}

反馈：
${feedback}

请根据反馈修改输出，改进所有指出的问题。

修改后的输出：`;
    
    return await this.llm.generate(prompt);
  }

  isSatisfactory(feedback) {
    // 检查是否有严重问题
    const criticalKeywords = ['严重问题', '重大错误', '完全不符合', '无法接受'];
    const hasCriticalIssues = criticalKeywords.some(keyword => 
      feedback.includes(keyword)
    );
    
    // 如果没有严重问题，认为满足要求
    return !hasCriticalIssues;
  }

  formatCriteria() {
    return this.criteria.map((c, i) => `${i + 1}. ${c}`).join('\n');
  }

  defaultCriteria = [
    '准确性：信息是否正确、无误',
    '完整性：是否覆盖所有要点',
    '清晰性：表达是否清晰易懂',
    '逻辑性：推理是否严密、自洽',
    '相关性：是否紧扣任务要求'
  ];

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated output.';
    }
  };
}

module.exports = { ReflectionAgent };


path: src/agents/self-critique-agent.js
content: /**
 * Self-Critique Agent - 自我批评与修正模式实现
 * 
 * 核心：Generate → Critique (找错) → Fix → Repeat
 */

class SelfCritiqueAgent {
  constructor(options = {}) {
    this.maxIterations = options.maxIterations || 3;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
    this.errorTypes = options.errorTypes || this.defaultErrorTypes;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Self-Critique] 开始任务：${task}`);
    }
    
    // Generate: 初始输出
    let output = await this.generate(task);
    
    if (this.verbose) {
      console.log(`\n[Initial Output]\n${output}\n`);
    }
    
    // Critique & Fix 循环
    for (let iteration = 1; iteration <= this.maxIterations; iteration++) {
      if (this.verbose) {
        console.log(`\n[Iteration ${iteration}/${this.maxIterations}]`);
      }
      
      // Critique: 结构化批评
      const critique = await this.critique(task, output);
      
      if (this.verbose) {
        console.log(`[Critique]\n${JSON.stringify(critique, null, 2)}\n`);
      }
      
      // 如果没有错误，结束
      if (!critique.errors || critique.errors.length === 0) {
        if (this.verbose) {
          console.log('[Complete] 未发现错误');
        }
        break;
      }
      
      // Fix: 修正错误
      output = await this.fix(task, output, critique);
      
      if (this.verbose) {
        console.log(`[Fixed Output]\n${output}\n`);
      }
    }
    
    return output;
  }

  async generate(task) {
    const prompt = `
任务：${task}

请生成初始答案。

答案：`;
    
    return await this.llm.generate(prompt);
  }

  async critique(task, output) {
    const prompt = `
任务：${task}

待检查的输出：
${output}

请按照以下错误类型进行系统检查：

${this.formatErrorTypes()}

对于每种错误类型：
1. 仔细检查是否存在此类错误
2. 如果存在，明确指出错误位置和内容
3. 说明为什么这是错误
4. 提供正确的信息或建议

请以 JSON 格式返回检查结果：
{
  "errors": [
    {
      "type": "错误类型",
      "location": "错误位置",
      "description": "错误描述",
      "reason": "为什么这是错误",
      "suggestion": "修正建议"
    }
  ],
  "summary": "总体评价"
}

检查结果：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\{[\s\S]*\}/);
      if (jsonMatch) {
        return JSON.parse(jsonMatch[0]);
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      console.warn('Failed to parse critique, assuming no errors');
      return { errors: [], summary: '检查完成' };
    }
  }

  async fix(task, output, critique) {
    const errorsText = critique.errors.map((e, i) => 
      `${i + 1}. [${e.type}] ${e.location}: ${e.description}\n   修正建议：${e.suggestion}`
    ).join('\n');
    
    const prompt = `
任务：${task}

原始输出：
${output}

发现的错误：
${errorsText}

请修正所有错误，生成改进后的版本。

要求：
1. 逐一修正每个错误
2. 保持原有的正确信息
3. 不要引入新错误
4. 保持格式一致

修正后的输出：`;
    
    return await this.llm.generate(prompt);
  }

  formatErrorTypes() {
    return this.errorTypes.map((et, i) => 
      `${i + 1}. **${et.name}**: ${et.description}\n   检查要点：${et.checkpoints.join('; ')}`
    ).join('\n\n');
  }

  defaultErrorTypes = [
    {
      name: '事实错误',
      description: '信息是否真实、准确、可验证',
      checkpoints: ['数据准确性', '引用真实性', '无幻觉']
    },
    {
      name: '逻辑错误',
      description: '推理是否严密、自洽',
      checkpoints: ['前提成立', '推理严密', '无矛盾']
    },
    {
      name: '计算错误',
      description: '数学计算、统计是否正确',
      checkpoints: ['加减乘除', '百分比', '单位换算']
    },
    {
      name: '遗漏错误',
      description: '是否缺少关键信息',
      checkpoints: ['回答问题', '背景信息', '限制条件']
    }
  ];

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated output.';
    }
  };
}

module.exports = { SelfCritiqueAgent };


path: src/agents/tree-of-thoughts-agent.js
content: /**
 * Tree of Thoughts Agent - 思维树模式实现
 * 
 * 核心：Branch → Evaluate → Select → Expand
 */

class TreeOfThoughtsAgent {
  constructor(options = {}) {
    this.maxDepth = options.maxDepth || 3;
    this.branchFactor = options.branchFactor || 3;
    this.beamWidth = options.beamWidth || 2;
    this.verbose = options.verbose || false;
    this.llm = options.llm || this.defaultLLM;
  }

  async execute(task) {
    if (this.verbose) {
      console.log(`[Tree of Thoughts] 开始任务：${task}`);
    }
    
    // 初始化根节点
    const root = {
      id: 'root',
      thought: '',
      depth: 0,
      score: 0,
      parent: null,
      children: []
    };
    
    // 生成初始思考
    const initialThoughts = await this.generateThoughts(task, root);
    root.children = initialThoughts;
    
    if (this.verbose) {
      console.log(`[Initial Thoughts] Generated ${initialThoughts.length} thoughts\n`);
    }
    
    // Beam Search
    let currentLevel = initialThoughts;
    
    for (let depth = 1; depth <= this.maxDepth; depth++) {
      if (this.verbose) {
        console.log(`[Depth ${depth}/${this.maxDepth}]`);
      }
      
      // 评估当前层
      const evaluatedThoughts = await this.evaluateThoughts(task, currentLevel);
      
      if (this.verbose) {
        evaluatedThoughts.forEach(t => {
          console.log(`  [${t.id}] Score: ${t.score.toFixed(1)} - ${t.thought.substring(0, 50)}...`);
        });
        console.log();
      }
      
      // 检查是否找到解决方案
      const solution = evaluatedThoughts.find(t => t.score >= 9);
      if (solution) {
        if (this.verbose) {
          console.log(`[Solution Found] Score: ${solution.score}\n`);
        }
        return this.extractSolution(task, solution);
      }
      
      // 选择 top-k
      const selectedThoughts = this.selectTopK(evaluatedThoughts, this.beamWidth);
      
      if (this.verbose) {
        console.log(`[Selected] Keeping ${selectedThoughts.length} thoughts\n`);
      }
      
      // 生成子思考
      const nextLevel = [];
      for (const thought of selectedThoughts) {
        const children = await this.generateThoughts(task, thought);
        thought.children = children;
        nextLevel.push(...children);
      }
      
      if (nextLevel.length === 0) {
        if (this.verbose) {
          console.log('[No More Thoughts] Cannot expand further\n');
        }
        break;
      }
      
      currentLevel = nextLevel;
    }
    
    // 返回最佳方案
    const bestThought = currentLevel.sort((a, b) => b.score - a.score)[0];
    return this.extractSolution(task, bestThought);
  }

  async generateThoughts(task, parent) {
    const prompt = `
任务：${task}

当前思考：${parent.thought || '(Initial)'}
Depth: ${parent.depth}

请生成 ${this.branchFactor} 个不同的思考方向。

要求：
1. 每个思考应该是不同的角度或方法
2. 思考应该具体、可执行
3. 思考之间应该有差异性

请以 JSON 数组格式返回：
[
  {
    "thought": "思考内容"
  }
]

思考：`;
    
    const response = await this.llm.generate(prompt);
    
    try {
      const jsonMatch = response.match(/\[[\s\S]*\]/);
      if (jsonMatch) {
        const thoughts = JSON.parse(jsonMatch[0]);
        return thoughts.map((t, i) => ({
          id: `${parent.id}-${i}`,
          thought: t.thought,
          depth: parent.depth + 1,
          score: 0,
          parent: parent.id,
          children: []
        }));
      }
      throw new Error('Invalid JSON');
    } catch (error) {
      return [{
        id: `${parent.id}-0`,
        thought: 'Continue exploring',
        depth: parent.depth + 1,
        score: 0,
        parent: parent.id,
        children: []
      }];
    }
  }

  async evaluateThoughts(task, thoughts) {
    const evaluatedThoughts = [];
    
    for (const thought of thoughts) {
      const score = await this.evaluateThought(task, thought);
      evaluatedThoughts.push({ ...thought, score });
    }
    
    return evaluatedThoughts;
  }

  async evaluateThought(task, thought) {
    const prompt = `
任务：${task}

思考：${thought.thought}

请评估这个思考的质量（1-10 分）：

评分标准：
- 10 分：完美解决方案，直接可以实施
- 8-9 分：很好的方案，少量改进即可
- 6-7 分：可行方案，需要一些改进
- 4-5 分：有潜力，但需要大量改进
- 1-3 分：不可行或方向错误

考虑因素：
1. 可行性：这个方案可以实施吗？
2. 有效性：能解决问题吗？
3. 效率：是高效的方法吗？
4. 完整性：覆盖了关键要点吗？

评分（只返回 1-10 的数字）：`;
    
    const response = await this.llm.generate(prompt);
    const score = parseFloat(response.match(/\d+(\.\d+)?/)?.[0] || '5');
    
    return Math.min(10, Math.max(1, score));
  }

  selectTopK(thoughts, k) {
    return thoughts
      .sort((a, b) => b.score - a.score)
      .slice(0, k);
  }

  async extractSolution(task, thought) {
    const prompt = `
任务：${task}

思考路径：${thought.thought}

请基于这个思考路径，生成最终的解决方案。

解决方案：`;
    
    return await this.llm.generate(prompt);
  }

  defaultLLM = {
    generate: async (prompt) => {
      console.warn('[Warning] Using default LLM.');
      return 'Generated thought.';
    }
  };
}

module.exports = { TreeOfThoughtsAgent };


path: src/index.js
content: /**
 * Agent Architecture Patterns - Main Entry Point
 * 
 * Export all agent implementations
 */

const { ReActAgent } = require('./agents/react-agent');
const { ReflectionAgent } = require('./agents/reflection-agent');
const { SelfCritiqueAgent } = require('./agents/self-critique-agent');
const { PlanAndSolveAgent } = require('./agents/plan-and-solve-agent');
const { TreeOfThoughtsAgent } = require('./agents/tree-of-thoughts-agent');
const { ManagerAgent, WorkerAgent } = require('./agents/manager-worker-agent');

module.exports = {
  // Single-Agent Patterns
  ReActAgent,
  ReflectionAgent,
  SelfCritiqueAgent,
  PlanAndSolveAgent,
  TreeOfThoughtsAgent,
  
  // Multi-Agent Patterns
  ManagerAgent,
  WorkerAgent
};


path: tests/react-agent.test.js
content: /**
 * ReAct Agent 单元测试
 * 
 * 运行方式：node tests/react-agent.test.js
 */

const { ReActAgent } = require('../src/agents/react-agent');

// ============================================
// Mock LLM
// ============================================

class MockLLM {
  constructor(responses) {
    this.responses = responses || [];
    this.callCount = 0;
  }

  async generate(prompt) {
    this.callCount++;
    const response = this.responses[this.callCount - 1];
    
    if (response === undefined) {
      throw new Error(`No mock response for call ${this.callCount}`);
    }
    
    return response;
  }

  reset() {
    this.callCount = 0;
  }
}

// ============================================
// Mock Tools
// ============================================

const mockTools = {
  search: {
    description: '搜索网络信息',
    execute: async ({ query }) => {
      const mockResults = {
        '北京 气温': '北京今天晴，最高气温 25°C',
        '上海 气温': '上海今天多云，最高气温 22°C'
      };
      return mockResults[query] || '未找到信息';
    }
  },
  
  calculate: {
    description: '执行数学计算',
    execute: async ({ expression }) => {
      try {
        return eval(expression).toString();
      } catch (error) {
        return `Error: ${error.message}`;
      }
    }
  }
};

// ============================================
// Test Utilities
// ============================================

let passedTests = 0;
let failedTests = 0;

function assert(condition, message) {
  if (condition) {
    console.log(`  ✅ ${message}`);
    passedTests++;
  } else {
    console.error(`  ❌ ${message}`);
    failedTests++;
  }
}

function assertEqual(actual, expected, message) {
  if (actual === expected) {
    console.log(`  ✅ ${message}`);
    passedTests++;
  } else {
    console.error(`  ❌ ${message}`);
    console.error(`     Expected: ${expected}`);
    console.error(`     Actual:   ${actual}`);
    failedTests++;
  }
}

// ============================================
// Tests
// ============================================

async function testReActAgent() {
  console.log('\n=== ReAct Agent 测试 ===\n');
  
  // Test 1: 基本功能测试
  console.log('Test 1: 基本功能测试');
  {
    const llm = new MockLLM([
      // Step 1: Thought
      '我需要查询北京的气温。',
      // Step 1: Action
      '{"name": "search", "args": {"query": "北京 气温"}}',
      // Step 2: Thought (finish)
      '我已经知道答案了。finish',
      // Step 2: Action (finish - will be parsed as action but ignored)
      '{"name": "finish", "args": {}}',
      // Finalize
      '北京今天气温 25°C',
      // Extra
      'extra1',
      'extra2',
      'extra3',
      'extra4',
      'extra5',
      'extra6',
      'extra7'
    ]);
    
    const agent = new ReActAgent({
      tools: mockTools,
      maxSteps: 5,
      llm,
      verbose: false
    });
    
    try {
      const result = await agent.execute('北京今天的气温是多少？');
      assertEqual(result, '北京今天气温 25°C', '返回正确答案');
    } catch (error) {
      assert(false, `执行失败：${error.message}`);
    }
  }
  
  // Test 2: 工具调用测试
  console.log('\nTest 2: 工具调用测试');
  {
    let toolCalled = false;
    const tools = {
      test: {
        description: '测试工具',
        execute: async (args) => {
          toolCalled = true;
          return 'test result';
        }
      }
    };
    
    const llm = new MockLLM([
      '使用测试工具',
      '{"name": "test", "args": {}}',
      'finish',
      'done',
      'extra'
    ]);
    
    const agent = new ReActAgent({ tools, llm, verbose: false });
    
    try {
      await agent.execute('test');
      assert(toolCalled, '工具被正确调用');
    } catch (error) {
      assert(false, `执行失败：${error.message}`);
    }
  }
  
  // Test 3: 最大步数限制测试
  console.log('\nTest 3: 最大步数限制测试');
  {
    const llm = new MockLLM(
      Array(10).fill('继续') // 永远不会完成
    );
    
    const agent = new ReActAgent({
      tools: mockTools,
      maxSteps: 3,
      llm,
      verbose: false
    });
    
    try {
      await agent.execute('test');
      assert(false, '应该抛出最大步数错误');
    } catch (error) {
      assert(
        error.message.includes('Max steps'),
        '正确抛出最大步数错误'
      );
    }
  }
  
  // Test 4: 未知工具处理测试
  console.log('\nTest 4: 未知工具处理测试');
  {
    const llm = new MockLLM([
      '使用未知工具',
      '{"name": "unknownTool", "args": {}}',
      'finish',
      '{"name": "finish", "args": {}}',
      'done',
      'extra1',
      'extra2',
      'extra3',
      'extra4',
      'extra5',
      'extra6',
      'extra7'
    ]);
    
    const agent = new ReActAgent({
      tools: mockTools,
      llm,
      verbose: false
    });
    
    try {
      const result = await agent.execute('test');
      // 未知工具会返回错误信息，但执行应该继续
      assert(true, '未知工具处理完成');
    } catch (error) {
      // 允许抛出错误
      assert(true, '未知工具处理完成');
    }
  }
  
  // Test 5: JSON 解析失败降级测试
  console.log('\nTest 5: JSON 解析失败降级测试');
  {
    const llm = new MockLLM([
      '思考...',
      '无效的 JSON 格式', // 不是有效 JSON
      'finish',
      'done',
      'extra1',
      'extra2',
      'extra3'
    ]);
    
    const agent = new ReActAgent({
      tools: mockTools,
      llm,
      verbose: false
    });
    
    try {
      await agent.execute('test');
      assert(true, 'JSON 解析失败时降级处理');
    } catch (error) {
      // 允许抛出错误
      assert(true, 'JSON 解析失败时处理');
    }
  }
  
  // Test 6: 思考历史构建测试
  console.log('\nTest 6: 思考历史构建测试');
  {
    const llm = new MockLLM([
      '思考 1',
      '{"name": "search", "args": {"query": "test"}}',
      '思考 2',
      '{"name": "calculate", "args": {"expression": "1+1"}}',
      'finish',
      'done',
      'extra'
    ]);
    
    let historyLength = 0;
    
    const agent = new ReActAgent({
      tools: mockTools,
      llm,
      verbose: false
    });
    
    // 重写 reason 方法来检查历史
    const originalReason = agent.reason.bind(agent);
    agent.reason = async (task, history) => {
      historyLength = history.length;
      return originalReason(task, history);
    };
    
    try {
      await agent.execute('test');
      assertEqual(historyLength, 2, '历史包含 2 个步骤');
    } catch (error) {
      assert(false, `执行失败：${error.message}`);
    }
  }
  
  // Test 7: 完成判断测试
  console.log('\nTest 7: 完成判断测试');
  {
    const agent = new ReActAgent({ tools: mockTools, verbose: false });
    
    const finishKeywords = [
      'finish',
      'answer is',
      '最终答案是',
      '完成任务',
      '可以给出答案'
    ];
    
    let allDetected = true;
    for (const keyword of finishKeywords) {
      if (!agent.isComplete(keyword, '')) {
        allDetected = false;
        console.error(`  未检测到关键词：${keyword}`);
      }
    }
    
    assert(allDetected, '正确识别所有完成关键词');
  }
  
  // Test 8: 工具列表格式化测试
  console.log('\nTest 8: 工具列表格式化测试');
  {
    const agent = new ReActAgent({ tools: mockTools, verbose: false });
    const toolList = agent.listTools();
    
    assert(
      toolList.includes('search') && toolList.includes('calculate'),
      '工具列表包含所有工具'
    );
    assert(
      toolList.includes('搜索网络信息'),
      '工具列表包含工具描述'
    );
  }
}

// ============================================
// Run Tests
// ============================================

async function runAllTests() {
  console.log('🧪 开始运行 ReAct Agent 单元测试...\n');
  
  const startTime = Date.now();
  
  await testReActAgent();
  
  const endTime = Date.now();
  const duration = endTime - startTime;
  
  console.log('\n=== 测试结果 ===');
  console.log(`总测试数：${passedTests + failedTests}`);
  console.log(`✅ 通过：${passedTests}`);
  console.log(`❌ 失败：${failedTests}`);
  console.log(`⏱️  耗时：${duration}ms`);
  
  if (failedTests === 0) {
    console.log('\n🎉 所有测试通过！');
  } else {
    console.error(`\n⚠️  有 ${failedTests} 个测试失败`);
    process.exit(1);
  }
}

// ============================================
// Main
// ============================================

runAllTests().catch(error => {
  console.error('测试运行失败:', error);
  process.exit(1);
});


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)