@chen-rmag/ai-runner 0.1.0

package/src/agents/tools/EXAMPLES.md

@@ -0,0 +1,347 @@
+# LangChain Playwright 工具使用示例
+
+## 完整示例：在 Healer 中使用工具
+
+```typescript
+import { Page } from 'playwright';
+import { createAgent } from '@langchain/core';
+import { getAllTools } from './tools';
+
+class Healer {
+  private llm: BaseChatModel;
+  private page: Page;
+
+  constructor(llm: BaseChatModel, page: Page) {
+    this.llm = llm;
+    this.page = page;
+  }
+
+  async execute(objective: string) {
+    // 获取所有工具
+    const tools = getAllTools(this.page);
+
+    // 创建 Agent
+    const agent = createAgent({
+      model: this.llm,
+      tools: tools,
+      systemPrompt: `
+        你是一个浏览器自动化专家。
+        使用提供的工具完成用户的目标。
+
+        可用工具包括：
+        - 导航工具：browser_navigate, browser_navigate_back
+        - 交互工具：browser_click, browser_hover
+        - 表单工具：browser_fill, browser_select_option
+        - 等待工具：browser_wait_for_selector, browser_wait_for_time
+        - 验证工具：browser_get_url, browser_screenshot, browser_verify_text
+
+        请根据目标选择合适的工具。
+      `
+    });
+
+    // 执行 Agent
+    const result = await agent.invoke({
+      messages: [{
+        role: 'user',
+        content: objective
+      }]
+    });
+
+    return result;
+  }
+}
+
+// 使用示例
+const page = await browser.newPage();
+const healer = new Healer(llm, page);
+await healer.execute('打开 example.com 并点击第一个链接');
+```
+
+## 单独使用工具
+
+### 导航工具
+
+```typescript
+import { createNavigateTool, createGoBackTool } from './tools/navigate';
+
+const navigateTool = createNavigateTool(page);
+const result = await navigateTool.invoke('https://example.com');
+console.log(result); // "Navigated to https://example.com"
+
+const goBackTool = createGoBackTool(page);
+await goBackTool.invoke('');
+```
+
+### 交互工具
+
+```typescript
+import { createClickTool, createHoverTool } from './tools/snapshot';
+
+const clickTool = createClickTool(page);
+
+// 点击按钮
+await clickTool.invoke('button');
+
+// 使用多个选择器
+await clickTool.invoke('button[type="submit"], #submit, .submit-btn');
+
+const hoverTool = createHoverTool(page);
+await hoverTool.invoke('nav.menu');
+```
+
+### 表单工具
+
+```typescript
+import {
+  createFillFormTool,
+  createSelectOptionTool,
+  createSetCheckedTool
+} from './tools/form';
+
+const fillTool = createFillFormTool(page);
+await fillTool.invoke('{"selector": "#username", "value": "john"}');
+
+const selectTool = createSelectOptionTool(page);
+await selectTool.invoke('{"selector": "select#country", "value": "China"}');
+
+const checkTool = createSetCheckedTool(page);
+await checkTool.invoke('{"selector": "#agree", "checked": true}');
+```
+
+### 等待工具
+
+```typescript
+import {
+  createWaitForTimeTool,
+  createWaitForSelectorTool,
+  createWaitForURLTool
+} from './tools/wait';
+
+const waitTimeTool = createWaitForTimeTool(page);
+await waitTimeTool.invoke('5000'); // 等待 5 秒
+
+const waitSelectorTool = createWaitForSelectorTool(page);
+await waitSelectorTool.invoke('button, timeout=5000'); // 等待按钮出现，超时 5 秒
+
+const waitURLTool = createWaitForURLTool(page);
+await waitURLTool.invoke('**/login'); // 等待 URL 匹配
+```
+
+### 验证工具
+
+```typescript
+import {
+  createGetURLTool,
+  createGetTextTool,
+  createScreenshotTool,
+  createVerifyTextVisibleTool
+} from './tools/verify';
+
+const getURLTool = createGetURLTool(page);
+const url = await getURLTool.invoke('');
+console.log(url); // "Current URL: https://example.com"
+
+const getTextTool = createGetTextTool(page);
+const text = await getTextTool.invoke('h1');
+console.log(text); // "Text from element "h1": Example Domain"
+
+const screenshotTool = createScreenshotTool(page);
+await screenshotTool.invoke(''); // 保存截图
+
+const verifyTool = createVerifyTextVisibleTool(page);
+await verifyTool.invoke('Welcome'); // 验证文本可见
+```
+
+## 在现有 Healer 中集成
+
+### 替换现有的 createPlaywrightTools
+
+```typescript
+// healer.ts
+import { getAllTools } from './tools';
+
+class Healer {
+  private createPlaywrightTools(page: Page): DynamicTool[] {
+    // 使用新的工具集
+    return getAllTools(page);
+  }
+
+  async execute(state: HealAgentState) {
+    const page = state.context.page;
+
+    // 获取工具
+    const tools = this.createPlaywrightTools(page);
+
+    // 创建 Agent
+    const agent = createAgent({
+      model: this.llm,
+      tools: tools,
+      systemPrompt: this.buildSystemPrompt(state)
+    });
+
+    // 执行...
+  }
+}
+```
+
+### 按需选择工具
+
+```typescript
+import { navigateTools, snapshotTools, waitTools } from './tools';
+
+class Healer {
+  private createMinimalTools(page: Page): DynamicTool[] {
+    // 只使用必要的工具
+    return [
+      ...navigateTools(page),
+      ...snapshotTools(page).slice(0, 2), // 只使用 snapshot 和 click
+      ...waitTools(page).slice(0, 1),    // 只使用 wait_for_time
+    ];
+  }
+}
+```
+
+## 高级用法
+
+### 自定义工具组合
+
+```typescript
+import {
+  createNavigateTool,
+  createClickTool,
+  createFillFormTool,
+  createWaitForSelectorTool
+} from './tools';
+
+const customToolSet = (page: Page) => [
+  createNavigateTool(page),
+  createClickTool(page),
+  createFillFormTool(page),
+  createWaitForSelectorTool(page),
+];
+```
+
+### 包装工具以添加日志
+
+```typescript
+import { createClickTool } from './tools/snapshot';
+
+function createClickToolWithLogging(page: Page) {
+  const tool = createClickTool(page);
+
+  return new DynamicTool({
+    name: tool.name,
+    description: tool.description,
+    func: async (input: string) => {
+      console.log(`[Tool] Calling ${tool.name} with input: ${input}`);
+      const startTime = Date.now();
+
+      try {
+        const result = await tool.invoke(input);
+        const duration = Date.now() - startTime;
+        console.log(`[Tool] ${tool.name} completed in ${duration}ms`);
+        return result;
+      } catch (error) {
+        console.error(`[Tool] ${tool.name} failed:`, error);
+        throw error;
+      }
+    }
+  });
+}
+```
+
+### 组合多个工具
+
+```typescript
+import { createClickTool, createFillFormTool } from './tools';
+
+async function fillAndSubmitForm(page: Page) {
+  const fillTool = createFillFormTool(page);
+  const clickTool = createClickTool(page);
+
+  // 填写表单
+  await fillTool.invoke('{"selector": "#email", "value": "test@example.com"}');
+  await fillTool.invoke('{"selector": "#password", "value": "secret"}');
+
+  // 点击提交按钮
+  await clickTool.invoke('button[type="submit"]');
+}
+```
+
+## 错误处理
+
+```typescript
+import { createClickTool } from './tools/snapshot';
+
+async function safeClick(page: Page, selector: string) {
+  const tool = createClickTool(page);
+
+  try {
+    const result = await tool.invoke(selector);
+    console.log('Success:', result);
+  } catch (error) {
+    console.error('Failed to click:', (error as Error).message);
+
+    // 尝试备选方案
+    console.log('Trying alternative selector...');
+    await tool.wait(1000); // 等待一下
+    await tool.invoke(selector);
+  }
+}
+```
+
+## 性能优化
+
+```typescript
+import { getAllTools } from './tools';
+
+// 缓存工具实例
+class ToolCache {
+  private tools: Map<Page, DynamicTool[]> = new Map();
+
+  get(page: Page): DynamicTool[] {
+    if (!this.tools.has(page)) {
+      this.tools.set(page, getAllTools(page));
+    }
+    return this.tools.get(page)!;
+  }
+}
+
+const cache = new ToolCache();
+const tools = cache.get(page);
+```
+
+## 调试技巧
+
+```typescript
+import { createClickTool } from './tools';
+
+// 添加详细日志
+async function debugClick(page: Page) {
+  const tool = createClickTool(page);
+
+  console.log('Available tools:', [tool.name]);
+  console.log('Tool description:', tool.description);
+
+  const selectors = ['button', 'a', 'input[type="submit"]'];
+
+  for (const selector of selectors) {
+    console.log(`Trying selector: ${selector}`);
+    try {
+      const result = await tool.invoke(selector);
+      console.log(`✓ Success with "${selector}":`, result);
+      break;
+    } catch (error) {
+      console.log(`✗ Failed with "${selector}"`);
+    }
+  }
+}
+```
+
+## 注意事项
+
+1. **超时处理**：大多数工具有默认超时，注意处理超时异常
+2. **选择器优先级**：工具会按优先级尝试不同类型的选择器
+3. **返回值**：所有工具返回字符串格式的结果
+4. **JSON 输入**：某些工具需要 JSON 格式的输入，注意格式正确性
+5. **错误传播**：工具失败会抛出异常，需要在外部捕获处理

package/src/agents/tools/README.md

@@ -0,0 +1,207 @@
+# LangChain 兼容的 Playwright 工具
+
+这是从 Playwright MCP 工具转换而来的 LangChain 兼容工具集，专门用于自愈 Agent。
+
+## 工具分类
+
+### 1. 导航工具 (`navigate.ts`)
+
+- **browser_navigate** - 导航到指定 URL
+- **browser_navigate_back** - 返回上一页
+- **browser_navigate_forward** - 前进到下一页
+
+### 2. 快照和交互工具 (`snapshot.ts`)
+
+- **browser_snapshot** - 获取页面的可访问性快照
+- **browser_click** - 点击元素（支持多个选择器）
+- **browser_hover** - 悬停在元素上
+
+### 3. 表单工具 (`form.ts`)
+
+- **browser_fill** - 填写表单字段
+- **browser_select_option** - 选择下拉选项
+- **browser_set_checked** - 勾选/取消复选框
+
+### 4. 等待工具 (`wait.ts`)
+
+- **browser_wait_for_time** - 等待指定时间
+- **browser_wait_for_selector** - 等待元素出现
+- **browser_wait_for_url** - 等待 URL 匹配
+
+### 5. 验证工具 (`verify.ts`)
+
+- **browser_get_url** - 获取当前 URL
+- **browser_get_content** - 获取页面内容
+- **browser_get_text** - 获取元素文本
+- **browser_screenshot** - 截取页面截图
+- **browser_verify_text** - 验证文本可见
+- **browser_verify_element** - 验证元素可见
+
+## 使用方法
+
+### 基本用法
+
+```typescript
+import { Page } from 'playwright';
+import { allTools } from './tools';
+
+const page: Page = await browser.newPage();
+
+// 获取所有工具
+const tools = allTools(page);
+
+// 在 LangChain Agent 中使用
+import { createReactAgent } from 'langchain/agents';
+
+const agent = createReactAgent({
+  llm: yourLLM,
+  tools: tools,
+  verbose: true
+});
+```
+
+### 按需导入
+
+```typescript
+// 只导入导航工具
+import { navigateTools } from './tools/navigate';
+
+const tools = navigateTools(page);
+
+// 只导入交互工具
+import { snapshotTools } from './tools/snapshot';
+
+const tools = snapshotTools(page);
+```
+
+## 工具特性
+
+### 1. 多选择器支持
+
+大多数交互工具支持多个选择器（用逗号分隔）：
+
+```typescript
+// 工具会依次尝试每个选择器，直到成功
+await clickTool.run('button, input[type="submit"], #submit-btn');
+```
+
+### 2. 智能选择器匹配
+
+工具会自动尝试不同类型的选择器：
+
+1. **文本选择器** - 通过文本内容查找元素
+2. **标签选择器** - 通过 label 关联查找表单元素
+3. **CSS 选择器** - 使用标准 CSS 选择器
+
+### 3. 错误处理
+
+所有工具都有完善的错误处理：
+
+```typescript
+try {
+  const result = await clickTool.run('button');
+  console.log(result);
+} catch (error) {
+  console.error('Tool failed:', error.message);
+}
+```
+
+## 与自愈 Agent 集成
+
+在 Healer 中使用这些工具：
+
+```typescript
+import { Healer } from './healer';
+import { allTools } from './tools';
+
+class Healer {
+  private createTools(page: Page): DynamicTool[] {
+    return allTools(page);
+  }
+
+  async execute(state: HealAgentState) {
+    const tools = this.createTools(state.context.page);
+
+    const agent = createAgent({
+      model: this.llm,
+      tools: tools,
+      systemPrompt: this.buildSystemPrompt(state)
+    });
+
+    // ... 执行 Agent
+  }
+}
+```
+
+## 工具输入格式
+
+### JSON 格式（用于复杂参数）
+
+```typescript
+// 填写表单
+await fillTool.run('{"selector": "#username", "value": "john"}');
+
+// 选择选项
+await selectOptionTool.run('{"selector": "select#country", "value": "China"}');
+
+// 勾选复选框
+await setCheckedTool.run('{"selector": "#agree", "checked": true}');
+```
+
+### 带参数的选择器
+
+```typescript
+// 带超时的等待
+await waitForSelectorTool.run('button, timeout=5000');
+```
+
+### 简单字符串输入
+
+```typescript
+// 导航
+await navigateTool.run('https://example.com');
+
+// 点击
+await clickTool.run('button');
+
+// 获取文本
+await getTextTool.run('h1');
+```
+
+## 从 MCP 转换说明
+
+这些工具是从 Playwright MCP 工具转换而来，主要变化：
+
+1. **移除了复杂的上下文系统** - 直接使用 Playwright Page 对象
+2. **简化了输入格式** - 使用简单的字符串或 JSON，而不是 Zod schema
+3. **LangChain 集成** - 使用 `DynamicTool` 包装，兼容 LangChain Agent
+4. **错误处理改进** - 统一的错误处理和消息格式
+5. **多选择器支持** - 增强的元素查找能力
+
+## 注意事项
+
+1. **超时设置** - 大多数工具有默认的超时时间（通常 30 秒）
+2. **元素查找** - 工具会按优先级尝试不同类型的选择器
+3. **返回值** - 所有工具返回字符串格式的结果消息
+4. **异常处理** - 工具执行失败会抛出异常，需要在外部处理
+
+## 扩展工具
+
+如果需要添加新工具：
+
+```typescript
+import { DynamicTool } from '@langchain/core/tools';
+
+export function createYourTool(page: Page): DynamicTool {
+  return new DynamicTool({
+    name: 'browser_your_tool',
+    description: 'Your tool description',
+    func: async (input: string) => {
+      // 实现你的逻辑
+      return 'result message';
+    }
+  });
+}
+```
+
+然后在对应的分类文件中导出，并在 `index.ts` 中注册。

package/src/agents/tools/form.ts

@@ -0,0 +1,138 @@
+/**
+ * 表单工具 - Form
+ */
+
+import { DynamicTool } from '@langchain/core/tools';
+import type { Page } from 'playwright';
+
+/**
+ * 创建填写表单工具
+ */
+export function createFillFormTool(page: Page): DynamicTool {
+  return new DynamicTool({
+    name: 'browser_fill',
+    description: 'Fill in a form field. Input should be in JSON format: {"selector": "css-selector-or-text", "value": "value-to-fill"}. For checkboxes, use "true" or "false" as the value.',
+    func: async (input: string) => {
+      try {
+        const params = JSON.parse(input);
+        const { selector, value } = params;
+
+        // 尝试多个选择器
+        const selectors = selector.split(',').map((s: string) => s.trim());
+
+        for (const sel of selectors) {
+          try {
+            // 尝试作为文本选择器
+            const locator = page.getByLabel(sel).or(page.getByPlaceholder(sel));
+            const count = await locator.count();
+            if (count > 0) {
+              await locator.fill(value);
+              return `Filled field with label: "${sel}" with value: "${value}"`;
+            }
+
+            // 尝试作为 CSS 选择器
+            await page.fill(sel, value);
+            return `Filled field: "${sel}" with value: "${value}"`;
+          } catch {
+            continue;
+          }
+        }
+
+        throw new Error(`No field found matching: ${selector}`);
+      } catch (error) {
+        throw new Error(`Failed to fill form: ${(error as Error).message}`);
+      }
+    }
+  });
+}
+
+/**
+ * 创建选择选项工具
+ */
+export function createSelectOptionTool(page: Page): DynamicTool {
+  return new DynamicTool({
+    name: 'browser_select_option',
+    description: 'Select an option in a dropdown. Input should be in JSON format: {"selector": "css-selector-or-text", "value": "option-value"}.',
+    func: async (input: string) => {
+      try {
+        const params = JSON.parse(input);
+        const { selector, value } = params;
+
+        // 尝试多个选择器
+        const selectors = selector.split(',').map((s: string) => s.trim());
+
+        for (const sel of selectors) {
+          try {
+            // 尝试作为文本选择器
+            const locator = page.getByLabel(sel);
+            const count = await locator.count();
+            if (count > 0) {
+              await locator.selectOption(value);
+              return `Selected option "${value}" in dropdown with label: "${sel}"`;
+            }
+
+            // 尝试作为 CSS 选择器
+            await page.selectOption(sel, value);
+            return `Selected option "${value}" in dropdown: "${sel}"`;
+          } catch {
+            continue;
+          }
+        }
+
+        throw new Error(`No dropdown found matching: ${selector}`);
+      } catch (error) {
+        throw new Error(`Failed to select option: ${(error as Error).message}`);
+      }
+    }
+  });
+}
+
+/**
+ * 创建复选框工具
+ */
+export function createSetCheckedTool(page: Page): DynamicTool {
+  return new DynamicTool({
+    name: 'browser_set_checked',
+    description: 'Check or uncheck a checkbox. Input should be in JSON format: {"selector": "css-selector-or-text", "checked": true|false}.',
+    func: async (input: string) => {
+      try {
+        const params = JSON.parse(input);
+        const { selector, checked } = params;
+
+        // 尝试多个选择器
+        const selectors = selector.split(',').map((s: string) => s.trim());
+
+        for (const sel of selectors) {
+          try {
+            // 尝试作为文本选择器
+            const locator = page.getByLabel(sel);
+            const count = await locator.count();
+            if (count > 0) {
+              await locator.setChecked(checked);
+              return `${checked ? 'Checked' : 'Unchecked'} checkbox with label: "${sel}"`;
+            }
+
+            // 尝试作为 CSS 选择器
+            await page.setChecked(sel, checked);
+            return `${checked ? 'Checked' : 'Unchecked'} checkbox: "${sel}"`;
+          } catch {
+            continue;
+          }
+        }
+
+        throw new Error(`No checkbox found matching: ${selector}`);
+      } catch (error) {
+        throw new Error(`Failed to set checked: ${(error as Error).message}`);
+      }
+    }
+  });
+}
+
+/**
+ * 表单工具集
+ */
+export const formTools = (page: Page): DynamicTool[] => [
+  createFillFormTool(page),
+  createSelectOptionTool(page),
+  createSetCheckedTool(page),
+];

package/src/agents/tools/index.ts

@@ -0,0 +1,29 @@
+/**
+ * LangChain 兼容的 Playwright 工具集
+ * 从 Playwright MCP 工具转换而来，用于自愈 Agent
+ */
+
+import { DynamicTool } from '@langchain/core/tools';
+import type { Page } from 'playwright';
+import { navigateTools } from './navigate';
+import { snapshotTools } from './snapshot';
+import { formTools } from './form';
+import { waitTools } from './wait';
+import { verifyTools } from './verify';
+
+// 重新导出工具工厂函数
+export { navigateTools } from './navigate';
+export { snapshotTools } from './snapshot';
+export { formTools } from './form';
+export { waitTools } from './wait';
+export { verifyTools } from './verify';
+
+// 获取所有工具的工厂函数
+export const getAllTools = (page: Page): DynamicTool[] => [
+  ...navigateTools(page),
+  ...snapshotTools(page),
+  ...formTools(page),
+  ...waitTools(page),
+  ...verifyTools(page),
+];
+