@chen-rmag/ai-runner 0.1.0

package/src/agents/healer.ts

@@ -0,0 +1,619 @@
+/**
+ * Healer - 测试自愈代理
+ * 使用 LangChain 的 createAgent API 实现 ReAct 循环
+ *
+ * 参考：https://www.npmjs.com/package/langchain
+ */
+
+import { createAgent } from 'langchain';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { DynamicTool } from '@langchain/core/tools';
+import type { HealAgentState, HealAgentResult } from './types';
+import type { ModelConfig } from '../types/external';
+import type { ReActStep } from '../types';
+import { getAllTools } from './tools';
+
+// ============================================================================
+// Playwright 工具集（使用标准化工具 + 自定义工具）
+// ============================================================================
+
+/**
+ * 创建 Playwright 工具集
+ * 使用标准化的 Playwright MCP 转换工具，并添加 Healer 特有的变量管理工具
+ */
+function createPlaywrightTools(page: any, setVariable: (name: string, value: any) => void, getAllVariables?: () => Record<string, any>): DynamicTool[] {
+  // 获取所有标准化工具
+  const standardTools = getAllTools(page);
+
+  // 添加 set_variable 工具
+  const setVariableTool = new DynamicTool({
+    name: 'set_variable',
+    description: 'Set the value of a variable. Input format: variableName,value (comma separated). For example: username,john or url,https://example.com. This tool is used to save data retrieved from the page to variables for later use.',
+    func: async (input: string) => {
+      const parts = input.split(',');
+      const varName = parts[0].trim();
+      const varValue = parts.slice(1).join(',').trim();
+
+      setVariable(varName, varValue);
+      return `Variable set: ${varName} = ${varValue}`;
+    }
+  });
+
+  // 添加 get_variable 工具 - 查看所有变量或获取特定变量
+  const getVariableTool = new DynamicTool({
+    name: 'get_variable',
+    description: 'Get all variables or get a specific variable value. To get all variables, use: get_variable or get_variable/all. To get a specific variable, use: get_variable,variableName. This helps you understand what data has been stored.',
+    func: async (input: string) => {
+      if (!input || input.trim() === '' || input.trim() === 'all') {
+        // 获取所有变量
+        const allVars = getAllVariables ? getAllVariables() : {};
+        const varList = Object.keys(allVars).map(key => `  - ${key}: ${JSON.stringify(allVars[key])}`).join('\n');
+        return `Current variables:\n${varList || '  (no variables set)'}`;
+      } else {
+        // 获取特定变量
+        const varName = input.trim();
+        const allVars = getAllVariables ? getAllVariables() : {};
+        const value = allVars[varName];
+        return `Variable ${varName}: ${JSON.stringify(value)}`;
+      }
+    }
+  });
+
+  return [...standardTools, setVariableTool, getVariableTool];
+}
+
+// ============================================================================
+// Healer 类
+// ============================================================================
+
+export class Healer {
+  private modelConfig: ModelConfig;
+  private maxSteps: number;
+  private debugMode: boolean;
+  private reactSteps: ReActStep[] = [];  // 记录 ReAct 循环的详细步骤
+  private setVariableCallback?: (name: string, value: any) => void;  // 外部传入的 setVariable 回调
+  private getAllVariablesCallback?: () => Record<string, any>;  // 外部传入的 getAllVariables 回调
+
+  constructor(modelConfig: ModelConfig, config: { maxSteps?: number; debugMode?: boolean; setVariable?: (name: string, value: any) => void; getAllVariables?: () => Record<string, any> } = {}) {
+    this.modelConfig = modelConfig;
+    this.maxSteps = config.maxSteps ?? 20;
+    this.debugMode = config.debugMode ?? false;
+    this.setVariableCallback = config.setVariable;
+    this.getAllVariablesCallback = config.getAllVariables;
+  }
+
+  /**
+   * 默认的 setVariable 方法（当没有提供回调时使用）
+   */
+  private defaultSetVariable(name: string, value: any): void {
+    if (this.debugMode) {
+      console.log(`[Healer] ⚠️  没有设置 setVariable 回调，变量 ${name} = ${value} 不会被保存`);
+    }
+  }
+
+  /**
+   * 默认的 getAllVariables 方法（当没有提供回调时使用）
+   */
+  private defaultGetAllVariables(): Record<string, any> {
+    if (this.debugMode) {
+      console.log(`[Healer] ⚠️  没有设置 getAllVariables 回调，返回空对象`);
+    }
+    return {};
+  }
+
+  /**
+   * 执行自愈（使用 LangChain createAgent API）
+   */
+  async execute(state: HealAgentState): Promise<HealAgentResult> {
+    console.log('\n========================================');
+    console.log('[Healer] 开始执行（使用 langchain createAgent）');
+    console.log('========================================');
+    console.log(`[Healer] 模型: ${this.modelConfig.provider}/${this.modelConfig.modelName}`);
+    console.log(`[Healer] 目标: ${state.objective}`);
+    console.log(`[Healer] 错误: ${state.error}`);
+
+    const page = state.context?.page;
+
+    if (!page) {
+      throw new Error('缺少 page 对象');
+    }
+
+    try {
+      // 重置步骤记录
+      this.reactSteps = [];
+
+      // 创建 LLM 实例
+      const llm = this.createLLM();
+
+      // 步数计数器（用于在工具返回值中提醒）
+      let stepCount = 0;
+      const stepCounter = { count: 0 };
+
+      // 创建 Playwright 工具（包装日志输出和步数提醒）
+      const tools = this.createPlaywrightToolsWithLogging(
+        page,
+        this.setVariableCallback || this.defaultSetVariable.bind(this),
+        this.getAllVariablesCallback || this.defaultGetAllVariables.bind(this),
+        stepCounter,
+        this.maxSteps
+      );
+
+      // 使用 createAgent API
+      const agent = createAgent({
+        model: llm,
+        tools: tools as any, // Cast to any to bypass duplicate @langchain/core type incompatibility
+        systemPrompt: this.buildSystemPrompt(state)
+
+      } as any); // Cast entire config to bypass type instantiation issues
+
+      console.log(`[Healer] 🚀 开始 ReAct 循环...`);
+
+      // 使用 stream 以便实时输出每一步
+      const inputStream = {
+        messages: [{
+          role: 'user' as const,
+          content: this.buildUserMessage(state)
+        }]
+      };
+
+      let finalResult: any = null;
+      let lastEvent: any = null;
+
+      // 流式执行并实时输出
+      const stream = await agent.stream(inputStream, {
+        recursionLimit: 25,
+        streamMode: 'updates',
+      });
+
+      for await (const event of stream) {
+        stepCount++;
+        stepCounter.count = stepCount;
+        lastEvent = event;  // 保存最后一个事件
+
+        if (this.debugMode) {
+          console.log(`\n[Healer] 📊 步骤 ${stepCount}:`);
+          console.log(`[Healer] 🔍 事件类型:`, Object.keys(event));
+          console.log(`[Healer] 🔍 事件结构:`, JSON.stringify(event, null, 2).substring(0, 500));
+        }
+
+        // 在 updates 模式下，messages 在不同位置
+        // 1. AI 思考和工具调用：event.model_request.messages
+        // 2. 工具执行结果：event.tools.messages
+        const messages = event.model_request?.messages || event.messages;
+        const toolMessages = event.tools?.messages;
+
+        if (this.debugMode) {
+          console.log(`[Healer] 🔍 检查 messages:`, messages ? `找到 ${messages.length} 条消息` : '未找到');
+          console.log(`[Healer] 🔍 检查 tools.messages:`, toolMessages ? `找到 ${toolMessages.length} 条工具消息` : '未找到');
+        }
+
+        // 处理 AI 思考和工具调用
+        if (messages && Array.isArray(messages)) {
+          for (const msg of messages) {
+            if (msg.type === 'ai') {
+              // AI 消息：content 是 string（思考过程），tool_calls 是数组（工具调用）
+              if (msg.content && typeof msg.content === 'string') {
+                // Thought 步骤
+                console.log(`[Healer] 💭 AI思考: ${msg.content}`);
+                this.recordThoughtStep(msg.content, stepCount);
+              }
+
+              // 处理工具调用
+              const aiMsg = msg as any;
+              if (aiMsg.tool_calls && Array.isArray(aiMsg.tool_calls)) {
+                for (const toolCall of aiMsg.tool_calls) {
+                  // Action 步骤
+                  const name = toolCall.name || toolCall.id;
+                  const args = toolCall.args || {};
+                  console.log(`[Healer] 🔧 工具调用: ${name}`);
+                  console.log(`[Healer] 📝 参数:`, JSON.stringify(args, null, 2));
+                  this.recordActionStep(name, args, stepCount);
+                }
+              }
+            }
+          }
+        }
+
+        // 处理工具执行结果
+        if (toolMessages && Array.isArray(toolMessages)) {
+          for (const msg of toolMessages) {
+            if (msg.type === 'tool') {
+              // Observation 步骤
+              const output = msg.content?.toString()?.substring(0, 200) || '(空)';
+              const success = true; // 如果能收到消息说明执行成功了
+              console.log(`[Healer] ✅ 工具结果 [${msg.name}]:`, output);
+              this.recordObservationStep(output, success, stepCount);
+            }
+          }
+        }
+      }
+
+      // 使用最后一个事件作为最终结果（不要重新调用 invoke）
+      finalResult = lastEvent || { messages: [] };
+
+      // 调试：输出 finalResult 结构
+      if (this.debugMode) {
+        console.log('\n[Healer] 🔍 finalResult 结构:', JSON.stringify(finalResult, null, 2).substring(0, 1000));
+      }
+
+      // 提取结果
+      const success = this.isSuccess(finalResult);
+      const reasoning = this.extractReasoning(finalResult);
+      const steps = stepCount;  // 直接使用记录的步数
+
+      console.log(`\n[Healer] 执行${success ? '成功 ✅' : '失败 ❌'}`);
+      console.log(`[Healer] 总步数: ${steps || stepCount}`);
+      console.log(`[Healer] 📝 记录了 ${this.reactSteps.length} 个 ReAct 步骤`);
+      console.log('========================================\n');
+
+      return {
+        success,
+        reasoning,
+        steps: steps || stepCount,
+        updatedVariables: {},  // 变量已通过回调函数设置，这里返回空对象
+        reactSteps: this.reactSteps  // 返回详细的 ReAct 步骤记录
+      };
+
+    } catch (error) {
+      console.error(`[Healer] ❌ 执行失败: ${error}`);
+
+      return {
+        success: false,
+        errorMessage: (error as Error).message,
+        reasoning: `Healer 执行失败: ${(error as Error).message}`,
+        steps: 0,
+        updatedVariables: {},
+        reactSteps: this.reactSteps
+      };
+    }
+  }
+
+  /**
+   * 记录 Thought 步骤
+   */
+  private recordThoughtStep(thought: string, stepNumber: number): void {
+    this.reactSteps.push({
+      stepNumber,
+      stepType: 'thought',
+      timestamp: Date.now(),
+      thought
+    });
+    if (this.debugMode) {
+      console.log(`[Healer] 📝 已记录 Thought 步骤，当前共 ${this.reactSteps.length} 个步骤`);
+    }
+  }
+
+  /**
+   * 记录 Action 步骤
+   */
+  private recordActionStep(toolName: string, toolInput: any, stepNumber: number): void {
+    this.reactSteps.push({
+      stepNumber,
+      stepType: 'action',
+      timestamp: Date.now(),
+      toolCall: {
+        name: toolName,
+        input: toolInput
+      }
+    });
+    if (this.debugMode) {
+      console.log(`[Healer] 📝 已记录 Action 步骤，当前共 ${this.reactSteps.length} 个步骤`);
+    }
+  }
+
+  /**
+   * 记录 Observation 步骤
+   */
+  private recordObservationStep(output: string, success: boolean, stepNumber: number): void {
+    this.reactSteps.push({
+      stepNumber,
+      stepType: 'observation',
+      timestamp: Date.now(),
+      toolResult: {
+        output,
+        success
+      }
+    });
+    if (this.debugMode) {
+      console.log(`[Healer] 📝 已记录 Observation 步骤，当前共 ${this.reactSteps.length} 个步骤`);
+    }
+  }
+
+  /**
+   * 创建带日志输出的 Playwright 工具
+   */
+  private createPlaywrightToolsWithLogging(
+    page: any,
+    setVariable: (name: string, value: any) => void,
+    getAllVariables: () => Record<string, any>,
+    stepCounter: { count: number },
+    maxSteps: number
+  ): DynamicTool[] {
+    const baseTools = createPlaywrightTools(page, setVariable, getAllVariables);
+
+    // 包装每个工具以添加日志输出和步数提醒
+    return baseTools.map(tool => {
+      const originalFunc = tool.func;
+      tool.func = async (input: string) => {
+        if (this.debugMode) {
+          console.log(`\n[Healer] 🔧 工具调用: ${tool.name}`);
+          console.log(`[Healer] 📝 输入: ${input}`);
+        }
+
+        const startTime = Date.now();
+        const result = await originalFunc.call(tool, input);
+        const duration = Date.now() - startTime;
+
+        if (this.debugMode) {
+          console.log(`[Healer] ✅ 输出: ${result}`);
+          console.log(`[Healer] ⏱️  耗时: ${duration}ms`);
+        }
+
+        // 附加步数信息到结果中
+        const currentStep = stepCounter.count;
+        const remainingSteps = Math.max(0, maxSteps - currentStep);
+
+        let stepWarning = '';
+        if (remainingSteps <= 0) {
+          stepWarning = `\n\n🚨🚨🚨 【紧急警告】：你已经达到最大步数限制 (${maxSteps} 次)！必须立即结束，不能再调用任何工具！🚨🚨🚨`;
+        } else if (remainingSteps <= 3) {
+          stepWarning = `\n\n⚠️⚠️⚠️ 【重要提醒】：你只剩下 ${remainingSteps} 次工具调用机会！请立即完成当前任务，不要再调用新工具！⚠️⚠️⚠️`;
+        } else if (currentStep >= 10) {
+          stepWarning = `\n\n📊 【步数提醒】：已使用 ${currentStep}/${maxSteps} 次，还剩 ${remainingSteps} 次，请加快速度。`;
+        }
+
+        return result + stepWarning;
+      };
+      return tool;
+    });
+  }
+
+  /**
+   * 创建 LLM 实例
+   */
+  private createLLM(): any {
+    switch (this.modelConfig.provider) {
+      case 'anthropic':
+        return new ChatAnthropic({
+          apiKey: this.modelConfig.apiKey,
+          model: this.modelConfig.modelName,
+          temperature: this.modelConfig.temperature ?? 0,
+          maxTokens: this.modelConfig.maxTokens ?? 4096
+        });
+
+      case 'openai':
+        // 需要安装 @langchain/openai
+        const { ChatOpenAI } = require('@langchain/openai');
+        return new ChatOpenAI({
+          apiKey: this.modelConfig.apiKey,
+          modelName: this.modelConfig.modelName,
+          temperature: this.modelConfig.temperature ?? 0,
+          maxTokens: this.modelConfig.maxTokens ?? 4096,
+          configuration: {
+            baseURL: this.modelConfig.baseURL
+          }
+        });
+
+      default:
+        throw new Error(`不支持的模型提供商: ${this.modelConfig.provider}`);
+    }
+  }
+
+  /**
+   * 构建系统提示
+   */
+  private buildSystemPrompt(state: HealAgentState): string {
+    // 获取当前可用变量列表
+    const allVars = this.getAllVariablesCallback ? this.getAllVariablesCallback() : {};
+    const variableList = Object.keys(allVars).length > 0
+      ? Object.keys(allVars).map(v => `  - ${v}: ${JSON.stringify(allVars[v])}`).join('\n')
+      : '  (no variables set yet)';
+
+    return `
+You are a Playwright test self-healing expert, skilled at analyzing and fixing errors in browser automation tests.
+
+## Available Tools
+### Navigation & Page Control
+- browser_navigate(url): Navigate to a URL
+- browser_navigate_back(): Navigate back
+- browser_navigate_forward(): Navigate forward
+
+### Element Interaction
+- browser_click(selector): Click on an element (supports multiple selectors, comma-separated)
+- browser_fill(json): Fill form fields. Format: {"selector": "css-or-text", "value": "value"}
+- browser_set_checked(json): Check/uncheck checkboxes. Format: {"selector": "css-or-text", "checked": true|false}
+- browser_select_option(json): Select dropdown option. Format: {"selector": "css-or-text", "value": "option-value"}
+- browser_hover(selector): Hover over an element
+
+### Waiting & Synchronization
+- browser_wait_for_time(ms): Wait for specified time in milliseconds
+- browser_wait_for_selector(selector): Wait for element to appear (supports optional timeout: "selector, timeout=5000")
+- browser_wait_for_url(pattern): Wait for URL to match pattern
+
+### Verification & Inspection
+- browser_snapshot(): Get accessibility snapshot of the page
+- browser_get_url(): Get current page URL
+- browser_get_content(): Get page HTML content
+- browser_get_text(selector): Get text content of an element
+- browser_screenshot(): Take a screenshot and save it
+- browser_verify_text(text): Verify if text is visible on page
+- browser_verify_element(selector): Verify if element exists on page
+
+### Variable Management (IMPORTANT!)
+- set_variable(name,value): Save a variable value for later use. Format: variableName,value
+  - Example: set_variable(url,https://example.com) or set_variable(username,john)
+- get_variable: Get all variables or get a specific variable. Use this to understand what data is already stored.
+  - To get all variables: get_variable or get_variable/all
+  - To get specific variable: get_variable,variableName
+
+## Current Available Variables
+${variableList}
+
+## Variable Handling Best Practices
+1. **Use existing variables**: Before setting new variables, check what's already available using get_variable
+2. **Maintain variable assignments**: If the original code sets variables (like url = page.url()), you MUST reproduce this behavior
+3. **Semantic understanding**: Analyze the original code to understand what each variable represents (e.g., 'url' typically means current page URL)
+4. **Consistency**: Use the same variable names and meanings as in the original code
+
+## Workflow
+1. **Check existing variables**: Use get_variable to see what's already stored
+2. **Analyze Error**: Understand the error cause and current state
+3. **Analyze original code**: Look for variable assignments that need to be reproduced
+4. **Select Tool**: Choose appropriate tool based on the error
+5. **Execute & Set Variables**: Call tools and use set_variable to maintain variable assignments
+6. **Evaluate**: Determine if successful, decide next step
+7. **Loop**: Until success or max steps reached
+
+## Step Limit (CRITICAL!)
+- **Maximum step limit: ${this.maxSteps} steps**
+- **When system shows ≤ 3 steps remaining, stop calling new tools immediately**
+- **When system shows 0 steps remaining, must end immediately, no more tool calls**
+- **Prioritize direct approaches, avoid unnecessary debugging (like frequent screenshots)**
+- **Every tool call consumes a step, use them wisely**
+
+## Strategy Tips
+- Timeout errors: Use browser_wait_for_selector first, then retry
+- Element not found: Try multiple selectors or use browser_screenshot to check state
+- Selector errors: Try more generic selectors (button, a, input)
+- Network delays: Use browser_wait_for_time to wait
+- Uncertain state: Use browser_screenshot or browser_get_url to inspect
+- **Variable handling**: If original code involves variable assignment, use browser_get_text to get the value, then set_variable(name,value) to save it
+- **Efficiency first**: Complete tasks in minimum steps, every step must have clear purpose
+
+Please use the tools to complete the self-healing task.
+`.trim();
+  }
+
+  /**
+   * 构建用户消息
+   */
+  private buildUserMessage(state: HealAgentState): string {
+    return `
+Please help me fix the following test error:
+
+## Current Task
+${state.objective}
+
+## Error Message
+${state.error}
+
+## Original Code
+\`\`\`typescript
+${state.originalCode}
+\`\`\`
+
+## Important Instructions
+1. Check existing variables using get_variable before setting new ones
+2. Analyze the original code to understand what variables are being set (e.g., heal.set(), variable assignments)
+3. Reproduce those variable assignments using set_variable after completing the task
+4. Use semantic understanding to determine what each variable represents
+
+Please use the provided tools to analyze the problem and attempt to fix it.
+`.trim();
+  }
+
+  /**
+   * 判断是否成功
+   * TODO: 后续优化成功判断逻辑，支持更多场景
+   */
+  private isSuccess(result: any): boolean {
+    if (!result) {
+      return false;
+    }
+
+    // 兼容不同的数据结构
+    let messages: any[] | undefined;
+
+    if (result.model_request && result.model_request.messages) {
+      // 结构: { model_request: { messages: [...] } }
+      messages = result.model_request.messages;
+    } else if (result.messages) {
+      // 结构: { messages: [...] }
+      messages = result.messages;
+    }
+
+    if (!messages || !Array.isArray(messages)) {
+      return false;
+    }
+
+    const lastMessage = messages[messages.length - 1];
+    const content = lastMessage.content?.toString() || '';
+
+    // 检查是否包含成功关键词
+    return content.includes('成功') ||
+           content.toLowerCase().includes('success') ||
+           !content.includes('失败') && !content.toLowerCase().includes('error');
+  }
+
+  /**
+   * 提取推理过程
+   * TODO: 后续优化推理过程提取，支持更详细的分析
+   */
+  private extractReasoning(result: any): string {
+    if (!result) {
+      return '无法提取推理过程';
+    }
+
+    const reasoningParts: string[] = [];
+
+    // 兼容不同的数据结构
+    let messages: any[] | undefined;
+
+    if (result.model_request && result.model_request.messages) {
+      // 结构: { model_request: { messages: [...] } }
+      messages = result.model_request.messages;
+    } else if (result.messages) {
+      // 结构: { messages: [...] }
+      messages = result.messages;
+    }
+
+    // 处理工具执行结果（event.tools.messages 结构）
+    const toolMessages = result.tools?.messages;
+    if (toolMessages && Array.isArray(toolMessages)) {
+      for (const msg of toolMessages) {
+        if (msg.type === 'tool') {
+          const output = msg.content?.toString()?.substring(0, 300) || '';
+          reasoningParts.push(`工具结果 [${msg.name}]: ${output}`);
+        }
+      }
+    }
+
+    if (messages && Array.isArray(messages)) {
+      // 收集所有消息内容
+      const messageTexts = messages.map((msg: any) => {
+        const parts: string[] = [];
+
+        // AI 消息：content 是 string，tool_calls 是数组
+        if (msg.type === 'ai') {
+          if (msg.content && typeof msg.content === 'string') {
+            parts.push(`AI思考: ${msg.content}`);
+          }
+
+          const aiMsg = msg as any;
+          if (aiMsg.tool_calls && Array.isArray(aiMsg.tool_calls)) {
+            for (const toolCall of aiMsg.tool_calls) {
+              const name = toolCall.name || toolCall.id;
+              const args = JSON.stringify(toolCall.args || {});
+              parts.push(`工具调用: ${name}`);
+              parts.push(`参数: ${args}`);
+            }
+          }
+        } else if (msg.type === 'tool') {
+          // 工具执行结果（兼容旧结构）
+          const output = msg.content?.toString()?.substring(0, 300) || '';
+          parts.push(`工具结果: ${output}`);
+        }
+
+        return parts.join('\n');
+      });
+
+      reasoningParts.push(...messageTexts);
+    }
+
+    if (reasoningParts.length === 0) {
+      return '无法提取推理过程';
+    }
+
+    return reasoningParts.filter(Boolean).join('\n\n---\n\n');
+  }
+}