@chen-rmag/ai-runner 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @ai-test/ai-heal
+
+AI-powered self-healing SDK for Playwright test scripts.
+
+> **版本**: v0.2.0
+> **状态**: 核心设计完成，准备开发
+> **重大更新**: 基于 MCP 工具限制重新设计架构，可行性提升至 ⭐⭐⭐⭐⭐
+
+## 概述
+
+`ai-heal` 是一个为 Playwright 测试脚本设计的自愈 SDK，通过 AI Agent 在测试执行失败时自动修复脚本错误，提高测试稳定性和维护效率。
+
+## 核心特性
+
+- 🔄 **自动自愈**: 测试步骤失败时自动触发 AI 修复流程
+- 🤖 **智能 Agent**: 基于 LangGraph 的 ReAct 循环实现智能决策
+- 🔧 **变量绑定**: Ref<T> 包装器支持复杂 Playwright 对象的引用传递
+- 📝 **代码生成**: Agent 分析错误并生成修复代码，在用户 Browser 上下文执行
+- 🎯 **类型安全**: 完整的 TypeScript 类型支持
+- ⚡ **零状态隔离**: 在用户真实 Browser 中执行，状态完全一致
+
+## 架构亮点
+
+### ✅ 解决核心问题
+
+**问题**: Playwright MCP 工具无法返回 Page、Tab、DOM 节点等复杂对象。
+
+**方案**:
+```
+Agent 使用 MCP 观察（只读）→ 生成修复代码 → SDK 在用户 Browser 执行
+```
+
+**优势**:
+- ✅ 完全绕过 MCP 返回值限制
+- ✅ 支持所有 Playwright 复杂对象
+- ✅ Cookie、Session、Storage 完全共享
+- ✅ 原生 Playwright API 完全可用
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install @ai-test/ai-heal
+```
+
+### 基本使用
+
+```typescript
+import { AIHeal, Ref } from '@ai-test/ai-heal';
+import { test, expect } from '@playwright/test';
+
+test('示例测试', async ({ page }) => {
+  // 初始化自愈实例
+  const heal = new AIHeal({
+    testCaseId: 'test-123',
+    projectId: 'project-456'
+  });
+
+  // 声明需要自愈的变量
+  const userPage = new Ref<typeof>(null);
+  const userData = new Ref<any>(null);
+
+  // 使用 runStep 包装测试步骤
+  await heal.runStep({
+    description: '打开登录页面并输入用户信息',
+    variables: {
+      page: userPage,
+      data: userData
+    },
+    context: page
+  }, async () => {
+    await page.goto('https://example.com/login');
+    await page.fill('#username', 'testuser');
+    await page.fill('#password', 'password123');
+    await page.click('#login-button');
+
+    // 保存变量供后续使用
+    userData.current = { username: 'testuser' };
+  });
+
+  // 继续使用自愈后的变量
+  await heal.runStep({
+    description: '验证用户登录成功',
+    variables: { page: userPage }
+  }, async () => {
+    await expect(userPage.current).toHaveURL(/.*dashboard/);
+  });
+
+  // 生成自愈报告和修复后的脚本
+  const summary = await heal.summary();
+  console.log(`总步骤数: ${summary.totalSteps}`);
+  console.log(`自愈成功数: ${summary.healedSteps}`);
+});
+```
+
+## API 文档
+
+### AIHeal
+
+#### 构造函数
+
+```typescript
+new AIHeal(config: AIHealConfig)
+```
+
+**参数:**
+- `testCaseId?: string` - 测试用例 ID，用于查询原始脚本
+- `projectId?: string` - 项目 ID
+- `scriptContent?: string` - 手动注入的脚本内容
+- `modelConfig?: ModelConfig` - AI 模型配置
+- `enableAutoSave?: boolean` - 是否自动保存修复后的脚本（默认 false）
+- `maxRetries?: number` - 最大自愈重试次数（默认 3）
+
+#### runStep
+
+```typescript
+async runStep<T>(
+  options: RunStepOptions,
+  fn: () => Promise
+): Promise<T>
+```
+
+**参数:**
+- `description: string` - 步骤描述，用于 AI 理解
+- `variables?: Record<string, Ref<any>>` - 需要传递的变量绑定
+- `context?: any` - Playwright 上下文对象（Page, BrowserContext 等）
+
+**返回:**
+- 泛型 `T` - 步骤执行结果
+
+#### summary
+
+```typescript
+async summary(): Promise<HealSummary>
+```
+
+**返回:**
+- `totalSteps: number` - 总步骤数
+- `healedSteps: number` - 自愈成功的步骤数
+- `modifiedScript?: string` - 修复后的脚本
+- `healingDetails: HealingDetail[]` - 每次自愈的详细信息
+
+### Ref<T>
+
+用于包装需要跨步骤传递的变量，支持 AI Agent 修改外部变量。
+
+```typescript
+const page = new Ref<Page>(null);
+
+// 获取值
+const currentPage = page.current;
+
+// 赋值
+page.current = await context.newPage();
+```
+
+## 架构设计
+
+### 核心组件
+
+```
+ai-heal/
+├── src/
+│   ├── core/              # 核心逻辑
+│   │   ├── ai-heal.ts     # AIHeal 主类
+│   │   ├── healer.ts      # 自愈执行器
+│   │   └── variable-binding.ts  # 变量绑定机制
+│   ├── agents/            # AI Agent
+│   │   ├── heal-agent.ts  # 自愈 Agent
+│   │   └── graph.ts       # LangGraph 定义
+│   ├── types/             # 类型定义
+│   ├── utils/             # 工具函数
+│   └── index.ts           # 导出入口
+├── docs/                  # 文档
+├── examples/              # 使用示例
+└── tests/                 # 测试
+```
+
+### 自愈流程
+
+```
+1. 执行原始代码
+   ↓
+2. 捕获错误
+   ↓
+3. 判断是否可自愈
+   ↓
+4. 构建 ReAct Agent
+   ↓
+5. Agent 使用 Playwright 工具重新执行
+   ↓
+6. 解析并应用变量赋值
+   ↓
+7. 记录自愈上下文
+   ↓
+8. 返回结果
+```
+
+## 开发计划
+
+- [x] 核心架构设计
+- [x] 技术方案文档
+- [x] POC 验证 (3个)
+- [ ] 基础类型定义
+- [ ] 变量绑定机制实现
+- [ ] AIHeal 主类实现
+- [ ] LangGraph Agent 集成
+- [ ] Playwright MCP 集成
+- [ ] 脚本修复逻辑
+- [ ] 单元测试
+- [ ] 集成测试
+- [ ] 文档完善
+
+## POC 验证
+
+**当前状态**: ✅ 准备就绪
+
+我们已经创建了 3 个 POC 验证脚本，用于验证核心技术方案的可行性：
+
+### POC 清单
+
+| POC | 验证内容 | 文件 | 预期时间 |
+|-----|---------|------|---------|
+| **POC 1** | Ref<T> 类型推断 | `src/poc/poc1-ref-type-inference.ts` | ~2s |
+| **POC 2** | 上下文代码执行 | `src/poc/poc2-context-execution.ts` | ~15s |
+| **POC 3** | 复杂对象序列化 | `src/poc/poc3-object-serialization.ts` | ~10s |
+
+### 快速运行
+
+```bash
+# 进入项目目录
+cd ai-heal
+
+# 安装依赖
+npm install
+npx playwright install
+
+# 运行所有 POC 测试
+npm test
+
+# 或使用 Playwright 直接运行
+npx playwright test src/poc/
+
+# 查看详细报告
+npx playwright show-report
+```
+
+### 详细说明
+
+请查看 [POC README](src/poc/README.md) 了解完整的验证说明和验收标准。
+
+## 技术方案
+
+详见 [docs/technical-design.md](docs/technical-design.md)
+
+## 可行性分析
+
+详见 [docs/feasibility-analysis.md](docs/feasibility-analysis.md)
+
+## 许可证
+
+MIT

package/SUMMARY_USAGE.md

@@ -0,0 +1,359 @@
+# AIHeal Summary 功能使用指南
+
+## 功能概述
+
+AIHeal 的 `summary()` 方法会在测试执行完毕后：
+1. 收集所有自愈上下文
+2. 如果配置了 `enableAutoSave: true`，使用 LLM 生成修复后的完整脚本
+3. 根据是否提供 `projectId` 和 `testCaseId`，决定是保存到数据库还是打印到控制台
+
+## 基本用法
+
+### 1. 仅收集统计信息（默认行为）
+
+```typescript
+import { AIHeal } from '@ai-test/ai-heal';
+
+const heal = new AIHeal({
+  modelConfigId: 'your-model-id'
+});
+
+// ... 执行测试步骤
+
+const summary = await heal.summary();
+
+console.log(`总步骤数: ${summary.totalSteps}`);
+console.log(`自愈步骤数: ${summary.healedSteps}`);
+console.log(`自愈详情:`, summary.healingDetails);
+```
+
+**输出**：
+```json
+{
+  "totalSteps": 5,
+  "healedSteps": 2,
+  "healingDetails": [
+    {
+      "step": "点击提交按钮",
+      "error": "Timeout 5000ms exceeded",
+      "recoveryTime": 3500,
+      "llmInteractions": 0
+    }
+  ]
+}
+```
+
+### 2. 启用自动脚本生成和保存
+
+```typescript
+const heal = new AIHeal({
+  modelConfigId: 'your-model-id',
+  enableAutoSave: true,  // 启用自动脚本生成
+  projectId: 'project-123',
+  testCaseId: 'test-456'
+});
+
+// ... 执行测试步骤
+
+const summary = await heal.summary();
+
+// 如果有自愈发生，summary.modifiedScript 会包含修复后的脚本
+if (summary.modifiedScript) {
+  console.log('脚本已修复并保存！');
+}
+```
+
+**行为**：
+- ✅ 如果提供了 `projectId` 和 `testCaseId`，脚本会保存到 `TestCaseRepository`
+- ❌ 如果保存失败，会回退到打印到控制台
+- 如果没有提供项目信息，直接打印到控制台
+
+### 3. 无项目信息时打印脚本
+
+```typescript
+const heal = new AIHeal({
+  modelConfigId: 'your-model-id',
+  enableAutoSave: true
+  // 不提供 projectId 和 testCaseId
+});
+
+// ... 执行测试步骤
+
+const summary = await heal.summary();
+
+// 脚本会打印到控制台
+```
+
+**控制台输出**：
+```
+========================================
+[AIHeal] 生成修复后的脚本...
+========================================
+[AIHeal] 调用 LLM 生成修复脚本...
+[AIHeal] 修复脚本生成完成
+========================================
+[AIHeal] 修复后的测试脚本
+========================================
+
+test('example test', async ({ page }) => {
+  await page.goto('https://example.com');
+
+  // 修复：使用更稳定的选择器
+  await page.click('button[type="submit"]', { timeout: 10000 });
+
+  const title = await page.title();
+  expect(title).toBeTruthy();
+});
+
+========================================
+[AIHeal] 脚本处理完成
+========================================
+```
+
+## 完整示例
+
+### 示例 1: 有项目信息的集成测试
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { AIHeal, Ref } from '@ai-test/ai-heal';
+
+test.describe('电商网站测试', () => {
+  test('购物车功能', async ({ page, context }) => {
+    const heal = new AIHeal({
+      modelConfigId: 'model-config-id',
+      enableAutoSave: true,  // 启用自动保存
+      projectId: 'ecommerce-project',
+      testCaseId: 'cart-test-001',
+      debugMode: true
+    });
+
+    // 步骤 1: 访问网站
+    await heal.runStep({
+      description: '访问购物车页面',
+      context: { page, context }
+    }, async () => {
+      await page.goto('https://shop.example.com/cart');
+    });
+
+    // 步骤 2: 添加商品（可能失败并触发自愈）
+    const productId = new Ref<string>('');
+
+    await heal.runStep({
+      description: '获取第一个商品ID',
+      context: { page, context },
+      variables: { productId }
+    }, async () => {
+      // 这个选择器可能会变化，触发自愈
+      const id = await page.locator('.product-item:first-child').getAttribute('data-id');
+      productId.value = id || '';
+    });
+
+    // 步骤 3: 点击结算
+    await heal.runStep({
+      description: '点击结算按钮',
+      context: { page, context }
+    }, async () => {
+      await page.click('#checkout-btn');
+    });
+
+    // 测试结束，生成摘要和修复脚本
+    const summary = await heal.summary();
+
+    console.log(`测试完成，共 ${summary.totalSteps} 步`);
+    console.log(`自愈了 ${summary.healedSteps} 个步骤`);
+
+    if (summary.modifiedScript) {
+      console.log('修复后的脚本已保存到项目中');
+    }
+  });
+});
+```
+
+### 示例 2: 本地调试（无项目信息）
+
+```typescript
+import { test } from '@playwright/test';
+import { AIHeal } from '@ai-test/ai-heal';
+
+test('本地测试调试', async ({ page, context }) => {
+  const heal = new AIHeal({
+    modelConfigId: 'model-config-id',
+    enableAutoSave: true,
+    debugMode: true
+    // 不提供 projectId 和 testCaseId
+  });
+
+  // ... 测试步骤
+
+  const summary = await heal.summary();
+
+  // 修复后的脚本会打印到控制台
+  // 可以手动复制并更新到测试文件中
+});
+```
+
+## 配置选项
+
+### AIHealConfig 相关字段
+
+```typescript
+interface AIHealConfig {
+  /** 是否自动生成并保存修复后的脚本 */
+  enableAutoSave?: boolean;
+
+  /** 项目 ID（用于保存脚本） */
+  projectId?: string;
+
+  /** 测试用例 ID（用于保存脚本） */
+  testCaseId?: string;
+
+  /** 模型配置 ID（用于生成脚本） */
+  modelConfigId?: string;
+
+  /** Agent 最大执行步数 */
+  agentMaxSteps?: number;
+
+  /** 是否开启调试模式 */
+  debugMode?: boolean;
+}
+```
+
+## 工作流程
+
+```
+测试执行
+  ↓
+runStep() 执行（可能触发自愈）
+  ↓
+记录 HealContext（错误、恢复过程等）
+  ↓
+调用 summary()
+  ↓
+检查 enableAutoSave && 有自愈发生
+  ↓
+┌─────────────────────────────────┐
+│  使用 LLM 生成修复后的脚本        │
+│  - 输入：原始脚本 + 自愈历史       │
+│  - 输出：修复后的完整脚本          │
+└─────────────────────────────────┘
+  ↓
+┌─────────────────────────────────┐
+│  判断：有 projectId && testCaseId? │
+└─────────────────────────────────┘
+  ↓ 是              ↓ 否
+保存到数据库       打印到控制台
+  ↓
+返回 HealSummary
+```
+
+## HealSummary 返回值
+
+```typescript
+interface HealSummary {
+  /** 总步骤数 */
+  totalSteps: number;
+
+  /** 自愈步骤数 */
+  healedSteps: number;
+
+  /** 修复后的脚本（如果启用 enableAutoSave） */
+  modifiedScript?: string;
+
+  /** 自愈详情列表 */
+  healingDetails: HealingDetail[];
+}
+
+interface HealingDetail {
+  /** 步骤描述 */
+  step: string;
+
+  /** 错误信息 */
+  error: string;
+
+  /** 恢复时间（毫秒） */
+  recoveryTime: number;
+
+  /** LLM 交互次数（暂未实现） */
+  llmInteractions: number;
+}
+```
+
+## LLM 生成脚本的质量
+
+### 优点
+- ✅ 基于实际自愈经验
+- ✅ 包含详细的修复注释
+- ✅ 使用稳定的选择器
+- ✅ 保留原始代码结构
+
+### 注意事项
+- ⚠️ LLM 生成的代码需要人工审查
+- ⚠️ 复杂的业务逻辑可能需要手动调整
+- ⚠️ 建议在测试环境中验证修复后的脚本
+
+## 最佳实践
+
+1. **开发阶段**：不启用 `enableAutoSave`，只查看统计信息
+   ```typescript
+   const heal = new AIHeal({
+     modelConfigId: 'xxx'
+     // enableAutoSave: false  // 默认
+   });
+   ```
+
+2. **CI/CD 集成**：启用自动保存，但需要人工审核
+   ```typescript
+   const heal = new AIHeal({
+     modelConfigId: 'xxx',
+     enableAutoSave: true,
+     projectId: 'xxx',
+     testCaseId: 'xxx'
+   });
+   ```
+
+3. **调试阶段**：启用 debugMode 查看详细过程
+   ```typescript
+   const heal = new AIHeal({
+     modelConfigId: 'xxx',
+     enableAutoSave: true,
+     debugMode: true
+   });
+   ```
+
+## 故障排查
+
+### 问题 1: 脚本没有生成
+
+**原因**：`enableAutoSave` 未设置或没有自愈发生
+
+**解决**：
+```typescript
+// 确保启用自动保存
+const heal = new AIHeal({
+  enableAutoSave: true,  // 必须设置为 true
+  modelConfigId: 'xxx'
+});
+
+// 确保有自愈发生
+const summary = await heal.summary();
+console.log('自愈步骤数:', summary.healedSteps);
+```
+
+### 问题 2: 脚本保存失败
+
+**原因**： projectId 或 testCaseId 错误
+
+**解决**：
+- 检查控制台错误日志
+- 脚本会自动回退到打印模式
+- 手动复制打印的脚本
+
+### 问题 3: LLM 生成的代码质量差
+
+**原因**：模型配置不当或提示词不够清晰
+
+**解决**：
+- 使用更强的模型（如 Claude 3.5 Sonnet）
+- 在 `buildSystemPrompt()` 中调整提示词
+- 人工审查和修改生成的代码