@cotestdev/ai-runner 0.0.1

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/dist/agents/heal-agent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 自愈 Agent
+ * 使用 LangChain 的 Healer 执行 ReAct 循环
+ */
+import type { HealAgentState, HealAgentResult, HealAgentConfig } from './types';
+/**
+ * 自愈 Agent
+ * 使用 LLM + ReAct 循环实现智能自愈
+ */
+export declare class HealAgent {
+    private config;
+    private healer?;
+    constructor(config?: HealAgentConfig);
+    /**
+     * 执行自愈
+     *
+     * 使用 Healer 通过 ReAct 循环执行自愈任务
+     * - Thought: 分析错误和目标
+     * - Action: 调用 Playwright 工具执行操作
+     * - Observation: 观察工具执行结果
+     * - Reflection: 判断是否继续或结束
+     * - 循环直到成功或达到最大步数
+     */
+    heal(state: HealAgentState): Promise<HealAgentResult>;
+    /**
+     * 日志输出
+     */
+    private log;
+}
+//# sourceMappingURL=heal-agent.d.ts.map

package/dist/agents/heal-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-agent.d.ts","sourceRoot":"","sources":["../../src/agents/heal-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGhF;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,MAAM,GAAE,eAAoB;IAoBxC;;;;;;;;;OASG;IACG,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IA8B3D;;OAEG;IACH,OAAO,CAAC,GAAG;CAKZ"}

package/dist/agents/heal-agent.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * 自愈 Agent
+ * 使用 LangChain 的 Healer 执行 ReAct 循环
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealAgent = void 0;
+const healer_1 = require("./healer");
+/**
+ * 自愈 Agent
+ * 使用 LLM + ReAct 循环实现智能自愈
+ */
+class HealAgent {
+    constructor(config = {}) {
+        this.config = {
+            maxSteps: config.maxSteps ?? 20,
+            debugMode: config.debugMode ?? false,
+            model: config.model,
+            setVariable: config.setVariable,
+            getAllVariables: config.getAllVariables
+        };
+        // 如果提供了模型配置，初始化 Healer
+        if (this.config.model) {
+            this.healer = new healer_1.Healer(this.config.model, {
+                maxSteps: this.config.maxSteps,
+                debugMode: this.config.debugMode,
+                setVariable: this.config.setVariable,
+                getAllVariables: this.config.getAllVariables
+            });
+        }
+    }
+    /**
+     * 执行自愈
+     *
+     * 使用 Healer 通过 ReAct 循环执行自愈任务
+     * - Thought: 分析错误和目标
+     * - Action: 调用 Playwright 工具执行操作
+     * - Observation: 观察工具执行结果
+     * - Reflection: 判断是否继续或结束
+     * - 循环直到成功或达到最大步数
+     */
+    async heal(state) {
+        this.log('[HealAgent] ========== 开始自愈流程 ==========');
+        this.log(`[HealAgent] 目标: ${state.objective}`);
+        this.log(`[HealAgent] 错误: ${state.error}`);
+        this.log(`[HealAgent] 最大步数: ${state.maxSteps || this.config.maxSteps}`);
+        this.log(`[HealAgent] 模式: ${this.healer ? 'LLM Healer' : '未配置'}`);
+        if (!this.healer) {
+            const errorMsg = 'Healer 未初始化，请提供 model 配置';
+            this.log(`[HealAgent] ❌ ${errorMsg}`);
+            return {
+                success: false,
+                errorMessage: errorMsg,
+                reasoning: '未配置模型，无法执行自愈',
+                steps: 0,
+                updatedVariables: {}
+            };
+        }
+        this.log('[HealAgent] 使用 Healer（LLM Agent）');
+        const result = await this.healer.execute(state);
+        this.log(`[HealAgent] 执行结果: ${result.success ? '成功 ✅' : '失败 ❌'}`);
+        this.log(`[HealAgent] 执行步数: ${result.steps}`);
+        this.log('[HealAgent] ========== 自愈流程结束 ==========\n');
+        return result;
+    }
+    /**
+     * 日志输出
+     */
+    log(message) {
+        if (this.config.debugMode) {
+            console.log(message);
+        }
+    }
+}
+exports.HealAgent = HealAgent;
+//# sourceMappingURL=heal-agent.js.map

package/dist/agents/heal-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-agent.js","sourceRoot":"","sources":["../../src/agents/heal-agent.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,qCAAkC;AAElC;;;GAGG;AACH,MAAa,SAAS;IAIpB,YAAY,SAA0B,EAAE;QACtC,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;YAC/B,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK;YACpC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,eAAe,EAAE,MAAM,CAAC,eAAe;SACxC,CAAC;QAEF,uBAAuB;QACvB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,IAAI,eAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;gBAC1C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAC9B,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAChC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBACpC,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe;aAC7C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,KAAqB;QAC9B,IAAI,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,mBAAmB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,mBAAmB,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,GAAG,CAAC,qBAAqB,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,mBAAmB,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAElE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,QAAQ,GAAG,0BAA0B,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;YAEtC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,QAAQ;gBACtB,SAAS,EAAE,cAAc;gBACzB,KAAK,EAAE,CAAC;gBACR,gBAAgB,EAAE,EAAE;aACrB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEhD,IAAI,CAAC,GAAG,CAAC,qBAAqB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,GAAG,CAAC,qBAAqB,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;QAEvD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,GAAG,CAAC,OAAe;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAxED,8BAwEC"}

package/dist/agents/healer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Healer - 测试自愈代理
+ * 使用 LangChain 的 createAgent API 实现 ReAct 循环
+ *
+ * 参考：https://www.npmjs.com/package/langchain
+ */
+import type { HealAgentState, HealAgentResult } from './types';
+import type { ModelConfig } from '../types/external';
+export declare class Healer {
+    private modelConfig;
+    private maxSteps;
+    private debugMode;
+    private reactSteps;
+    private setVariableCallback?;
+    private getAllVariablesCallback?;
+    constructor(modelConfig: ModelConfig, config?: {
+        maxSteps?: number;
+        debugMode?: boolean;
+        setVariable?: (name: string, value: any) => void;
+        getAllVariables?: () => Record<string, any>;
+    });
+    /**
+     * 默认的 setVariable 方法（当没有提供回调时使用）
+     */
+    private defaultSetVariable;
+    /**
+     * 默认的 getAllVariables 方法（当没有提供回调时使用）
+     */
+    private defaultGetAllVariables;
+    /**
+     * 执行自愈（使用 LangChain createAgent API）
+     */
+    execute(state: HealAgentState): Promise<HealAgentResult>;
+    /**
+     * 记录 Thought 步骤
+     */
+    private recordThoughtStep;
+    /**
+     * 记录 Action 步骤
+     */
+    private recordActionStep;
+    /**
+     * 记录 Observation 步骤
+     */
+    private recordObservationStep;
+    /**
+     * 创建带日志输出的 Playwright 工具
+     */
+    private createPlaywrightToolsWithLogging;
+    /**
+     * 创建 LLM 实例
+     */
+    private createLLM;
+    /**
+     * 构建系统提示
+     */
+    private buildSystemPrompt;
+    /**
+     * 构建用户消息
+     */
+    private buildUserMessage;
+    /**
+     * 判断是否成功
+     * TODO: 后续优化成功判断逻辑，支持更多场景
+     */
+    private isSuccess;
+    /**
+     * 提取推理过程
+     * TODO: 后续优化推理过程提取，支持更详细的分析
+     */
+    private extractReasoning;
+}
+//# sourceMappingURL=healer.d.ts.map

package/dist/agents/healer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healer.d.ts","sourceRoot":"","sources":["../../src/agents/healer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyDrD,qBAAa,MAAM;IACjB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,mBAAmB,CAAC,CAAqC;IACjE,OAAO,CAAC,uBAAuB,CAAC,CAA4B;gBAEhD,WAAW,EAAE,WAAW,EAAE,MAAM,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAO;IAQ5L;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;IACG,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAoK9D;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAexB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;OAEG;IACH,OAAO,CAAC,gCAAgC;IA8CxC;;OAEG;IACH,OAAO,CAAC,SAAS;IA4BjB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkFzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;;OAGG;IACH,OAAO,CAAC,SAAS;IA6BjB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAmEzB"}