@be-link/smart-test 1.0.1-beta.2 → 1.0.1-beta.21

package/README.md

@@ -1,524 +1,420 @@
 # @be-link/smart-test
 
-> AI-powered visual testing for Playwright - 基于 AI 视觉模型的 Playwright 测试工具
-
-使用 AI 视觉识别能力，让你的 E2E 测试更智能、更可靠。
+AI-powered visual testing for Playwright | 基于 AI 视觉模型的 Playwright 测试工具
 
 ## ✨ 特性
 
-### 🤖 AI 视觉检查
-
-- 基于通义千问等视觉模型，智能检查页面是否符合预期
-- 支持自然语言描述测试预期
-- 自动识别页面问题并给出详细反馈
-
-### 🎯 零代码测试生成（开发中）
-
-- **CLI 工具**：一条命令自动生成测试代码
-- **录制模式**：访问页面自动录制接口和交互
-- **代码分析**：扫描项目代码自动生成 Mock 数据
-- **AI 生成**：基于自然语言描述生成完整测试
-
-### 🔧 灵活易用
-
-- 与 Playwright 无缝集成，零侵入设计
-- 支持全局配置和单次调用配置
-- 优雅降级：无 API Key 时自动跳过
-- 完整的 TypeScript 类型支持
-
-### 📸 自动化
-
-- 自动截图并保存
-- 自动生成 Mock 数据
-- 自动生成测试用例
+- 🎯 **AI 视觉检查**：使用 AI 视觉模型自动检查页面截图是否符合预期
+- 🤖 **AI 代码生成**：使用 AI 自动生成测试用例和 Mock 数据
+- 📝 **TypeScript 支持**：完整的 TypeScript 类型定义
+- 🔧 **灵活配置**：支持自定义 AI 模型和服务地址
 
 ## 📦 安装
 
 ```bash
-# 使用 pnpm（推荐）
 pnpm add -D @be-link/smart-test
-
-# 使用 npm
-npm install -D @be-link/smart-test
-
-# 使用 yarn
-yarn add -D @be-link/smart-test
 ```
 
 ## 🚀 快速开始
 
-### 方式一：使用 CLI 工具（推荐）⭐
-
-#### 1. 初始化配置
-
-```bash
-npx smart-test init
-```
-
-交互式配置向导会引导你完成设置：
-
-```
-━━━ 初始化 Smart Test 配置 ━━━
-
-? 请输入 AI API Key: sk-xxxxx
-? 选择 AI 模型: 通义千问 (qwen3-vl-plus)
-? 测试文件目录: ./tests/e2e
-? Helpers 目录: ./tests/helpers
-? Playwright Base URL: http://localhost:8080
-? 文件命名风格: kebab-case
-
-✓ 配置文件已创建: .smarttestrc.json
-```
-
-#### 2. 生成测试代码（开发中）
-
-```bash
-# 录制模式 - 访问页面自动录制
-npx smart-test record --url http://localhost:8080/coupon
-
-# 代码分析模式 - 扫描页面代码
-npx smart-test generate --page src/pages/coupon/index.tsx
-
-# 描述生成模式 - 基于自然语言
-npx smart-test generate --desc "优惠券列表页，有可用券和已用券两个 tab"
+### 1. 初始化配置
 
-# 交互式模式 - 引导式生成
-npx smart-test generate --interactive
-```
-
-#### 3. 运行测试
+首先在项目中初始化配置文件：
 
 ```bash
-npx playwright test
+# 在项目根目录运行
+smart-test init
 ```
 
----
-
-### 方式二：手动编程
-
-#### 1. 配置 API Key
+然后编辑 `tests/smart-test.config.json`，配置 AI API 密钥：
 
-在项目根目录创建 `.env` 文件：
-
-```bash
-AI_API_KEY=sk-your-api-key-here
+```json
+{
+  "ai": {
+    "apiKey": "${VITE_AI_API_KEY}",
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "visionModel": "qwen3-vl-plus",
+    "codeModel": "qwen3-coder-plus"
+  }
+}
 ```
 
-#### 2. 初始化配置
-
-在 `playwright.config.ts` 中配置：
-
-```typescript
-import { defineConfig } from '@playwright/test';
-import { configure } from '@be-link/smart-test';
-
-// 初始化 AI 配置
-configure({
-  apiKey: process.env.AI_API_KEY,
-  screenshotDir: './test-results/ai-screenshots',
-});
+配置文件会在使用 AI 功能时自动加载，无需手动调用配置函数。
 
-export default defineConfig({
-  // ... 其他 Playwright 配置
-});
-```
+### 2. AI 视觉检查
 
-#### 3. 在测试中使用
+在 Playwright 测试中使用 AI 检查页面截图：
 
 ```typescript
-import { test, expect } from '@playwright/test';
+import { test } from '@playwright/test';
 import { aiReviewScreenshot } from '@be-link/smart-test';
 
-test.describe('优惠券页面', () => {
-  test('AI 检查页面布局', async ({ page }) => {
-    await page.goto('/coupon');
+test('页面显示正确', async ({ page }) => {
+  await page.goto('/home');
 
-    // 使用 AI 检查页面
-    const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表，包含标题、优惠券卡片和底部按钮');
+  const result = await aiReviewScreenshot(page, '顶部显示logo和导航栏，主内容区域显示3个产品卡片');
 
-    // 处理结果
-    if (result.skipped) {
-      test.skip(); // 无 API Key 时跳过
-    }
-
-    expect(result.ok, result.issues?.join(', ')).toBeTruthy();
-  });
+  if (!result.skipped && result.issues?.length) {
+    console.log('AI 发现的问题:', result.issues);
+  }
 });
 ```
 
-## 📖 CLI 命令参考
-
-### `smart-test init`
-
-初始化配置文件，交互式设置 AI API Key、模型、输出目录等。
-
-```bash
-smart-test init
-```
-
-### `smart-test generate` (开发中)
-
-生成测试代码。
-
-```bash
-# 基础用法
-smart-test generate
-
-# 指定页面（代码分析模式）
-smart-test generate --page <path>
-
-# 指定 URL（录制模式）
-smart-test generate --url <url>
+### 3. AI 生成测试用例
 
-# 基于描述（自然语言模式）
-smart-test generate --desc <description>
+自动生成完整的 Playwright 测试用例：
 
-# 交互式模式
-smart-test generate --interactive
-
-# 指定输出目录
-smart-test generate --page <path> --output tests/custom
+```typescript
+import { aiGenerateTestCase } from '@be-link/smart-test';
+
+const result = await aiGenerateTestCase({
+  pageUrl: '/coupon?userId=e2e-user&isPopup=true',
+  scenario: '优惠券页面展示和 Tab 切换功能',
+  apiMocks: [
+    {
+      path: '**/api/user/info/get-user-detail',
+      description: '返回用户信息，包含 id、nickname、memberLevel 等字段',
+    },
+    {
+      path: '**/api/user/coupon/get-available-coupons-grouped',
+      description: '返回可用优惠券列表，按券 ID 分组',
+    },
+  ],
+  aiCheckExpected: '顶部展示门店名称和用户昵称，列表中应显示3张优惠券卡片',
+  testSteps: ['验证页面显示"优惠券"标题', '验证显示"夏日满减券"', '点击"核销券"按钮', '验证显示"到店核销券"文本'],
+});
 
-# 预览模式（不写入文件）
-smart-test generate --page <path> --dry-run
+if (result.ok) {
+  console.log('生成的测试代码:\n', result.code);
+}
 ```
 
-**选项：**
-
-| 选项                   | 简写 | 说明                         |
-| ---------------------- | ---- | ---------------------------- |
-| `--page <path>`        | `-p` | 页面文件路径（代码分析模式） |
-| `--url <url>`          | `-u` | 页面 URL（录制模式）         |
-| `--desc <description>` | `-d` | 页面描述（自然语言模式）     |
-| `--output <dir>`       | `-o` | 输出目录                     |
-| `--interactive`        | `-i` | 交互式模式                   |
-| `--dry-run`            |      | 预览模式，不写入文件         |
-
-### `smart-test record` (开发中)
+### 4. AI 生成 Mock 数据
 
-录制模式的快捷命令（`generate --url` 的别名）。
-
-```bash
-# 基础录制
-smart-test record --url http://localhost:8080/coupon
+通过传入实际的 TypeScript 类型定义，AI 会生成完全符合接口规范的 Mock 数据：
 
-# 手动操作模式
-smart-test record --url http://localhost:8080/coupon --manual
+```typescript
+import { aiGenerateMock } from '@be-link/smart-test';
+import fs from 'fs';
+
+// 读取类型定义文件
+const addressTypes = fs.readFileSync('./src/api/address/types.ts', 'utf-8');
+
+// 提取需要的类型定义
+const result = await aiGenerateMock({
+  apiPath: '**/api/user/address/get-default-address',
+  description: '返回用户默认地址信息',
+  responseType: 'IDefaultAddressResp',
+  typeDefinitions: [
+    {
+      typeName: 'IDefaultAddressResp',
+      content: `export interface IDefaultAddressResp {
+  /** 默认地址 */
+  defaultAddress: IUserAddress | null;
+  /** 自提地址 */
+  pickupAddress: IPickUpStoreUserInfo | null;
+}`,
+    },
+    {
+      typeName: 'IUserAddress',
+      content: `export interface IUserAddress {
+  /** 地址ID */
+  id: string;
+  /** 用户ID */
+  userId: string;
+  /** 收件人姓名 */
+  receiverName: string;
+  /** 收件人手机号 */
+  receiverMobile: string;
+  /** 省份名称 */
+  provinceName: string;
+  /** 城市名称 */
+  cityName: string;
+  /** 区县名称 */
+  districtName: string;
+  /** 详细地址 */
+  detailAddress: string;
+  /** 是否默认地址：1-是，0-否 */
+  isDefault: number;
+  /** 创建时间（毫秒时间戳） */
+  createdAt: number;
+}`,
+    },
+    {
+      typeName: 'IPickUpStoreUserInfo',
+      content: `export interface IPickUpStoreUserInfo {
+  id?: string;
+  /** 用户ID */
+  userId: string;
+  /** 提货人手机号 */
+  receiverMobile: string;
+  /** 提货人名称 */
+  receiverName: string;
+}`,
+    },
+  ],
+});
 
-# 交互式引导
-smart-test record --url http://localhost:8080/coupon --interactive
+if (result.ok) {
+  console.log('生成的 Mock 代码:\n', result.code);
+  // AI 会严格按照类型定义生成符合规范的 mock 数据
+}
 ```
 
-**选项：**
-
-| 选项             | 简写 | 说明                     |
-| ---------------- | ---- | ------------------------ |
-| `--url <url>`    | `-u` | 要录制的页面 URL（必需） |
-| `--output <dir>` | `-o` | 输出目录                 |
-| `--manual`       |      | 手动操作模式             |
-| `--interactive`  |      | 交互式引导               |
+### 5. 通用代码生成
 
-### `smart-test config`
+使用 AI 生成任意 TypeScript 代码：
 
-查看当前配置。
+```typescript
+import { aiGenerateCode } from '@be-link/smart-test';
+
+const result = await aiGenerateCode({
+  prompt: '生成一个函数，用于计算两个日期之间的天数差',
+  context: `// 项目中的日期工具示例
+function formatDate(date: Date): string {
+  return date.toISOString().split('T')[0];
+}`,
+});
 
-```bash
-smart-test config
+if (result.ok) {
+  console.log('生成的代码:\n', result.code);
+}
 ```
 
-### 全局选项
-
-| 选项        | 简写 | 说明                 |
-| ----------- | ---- | -------------------- |
-| `--version` | `-V` | 显示版本号           |
-| `--verbose` | `-v` | 详细输出（调试模式） |
-| `--help`    | `-h` | 显示帮助信息         |
-
-## 📖 编程 API 文档
+## 📖 API 文档
 
-### `configure(config)`
+### aiReviewScreenshot
 
-配置全局设置。
+使用 AI 视觉模型检查页面截图是否符合预期。
 
 ```typescript
-import { configure } from '@be-link/smart-test';
-
-configure({
-  apiKey: 'sk-xxx', // AI API 密钥
-  baseURL: 'https://...', // AI 服务地址（可选）
-  model: 'qwen3-vl-plus', // AI 模型（可选）
-  timeout: 30000, // 超时时间（可选）
-});
+function aiReviewScreenshot(page: Page, options: string | AiCheckOptions): Promise<AiCheckResult>;
 ```
 
-### `aiReviewScreenshot(page, options)`
-
-使用 AI 检查页面截图。
-
 **参数：**
 
-- `page: Page` - Playwright Page 对象
-- `options: string | AiCheckOptions` - 检查选项
+- `page`: Playwright Page 对象
+- `options`: 检查选项
+  - 字符串：直接传入预期描述
+  - 对象：包含 `expected`（预期描述）、`fullPage`（是否全页截图）等配置
 
-**返回值：** `Promise<AiCheckResult>`
+**返回值：**
 
 ```typescript
 interface AiCheckResult {
   ok: boolean; // 检查是否通过
-  issues?: string[]; // 问题列表
-  skipped?: boolean; // 是否跳过
+  issues?: string[]; // 发现的问题列表
+  suggestion?: string[]; // 改进建议列表
+  skipped?: boolean; // 是否跳过检查
   reason?: string; // 跳过原因
-  screenshotPath?: string; // 截图路径
   rawResponse?: string; // AI 原始响应
 }
 ```
 
-## 🎨 使用示例
-
-### 基础用法
-
-```typescript
-// 简单字符串描述
-const result = await aiReviewScreenshot(page, '页面应该显示登录表单');
-```
+### aiGenerateTestCase
 
-### 带配置的用法
+使用 AI 生成完整的 Playwright 测试用例。
 
 ```typescript
-// 带配置对象
-const result = await aiReviewScreenshot(page, {
-  expected: '页面应该显示商品列表',
-  model: 'gpt-4-vision-preview', // 使用其他模型
-});
+function aiGenerateTestCase(options: AiTestCaseGenerationOptions): Promise<AiCodeGenerationResult>;
 ```
 
-### 完整测试示例
+**参数：**
 
 ```typescript
-import { test, expect } from '@playwright/test';
-import { aiReviewScreenshot } from '@be-link/smart-test';
-
-test.describe('商品页面测试', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/products');
-    await page.waitForLoadState('networkidle');
-  });
-
-  test('检查页面布局', async ({ page }) => {
-    const result = await aiReviewScreenshot(page, {
-      expected: '页面顶部应有搜索框，中间显示商品网格布局，底部有分页器',
-      fullPage: true,
-    });
-
-    if (result.skipped) {
-      console.log('跳过原因:', result.reason);
-      test.skip();
-    }
-
-    if (!result.ok && result.issues) {
-      console.warn('发现的问题:', result.issues);
-    }
+interface AiTestCaseGenerationOptions {
+  pageUrl: string; // 页面 URL
+  scenario: string; // 测试场景描述
+  apiMocks?: ApiMockConfig[]; // API Mock 配置列表
+  aiCheckExpected?: string; // AI 视觉检查预期
+  testSteps?: string[]; // 测试步骤列表
+  referenceCode?: string; // 参考代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
 
-    expect(result.ok, `AI 检查失败: ${result.issues?.join(', ')}`).toBeTruthy();
-  });
+interface ApiMockConfig {
+  path: string; // API 路径（支持通配符）
+  description: string; // Mock 数据描述
+}
+```
 
-  test('检查响应式布局', async ({ page }) => {
-    // 切换到移动端视图
-    await page.setViewportSize({ width: 375, height: 667 });
+### aiGenerateMock
 
-    const result = await aiReviewScreenshot(page, '移动端布局：商品应该以单列显示，每个卡片占满宽度');
+使用 AI 生成 API Mock 函数。
 
-    if (!result.skipped) {
-      expect(result.ok).toBeTruthy();
-    }
-  });
-});
+```typescript
+function aiGenerateMock(options: AiMockGenerationOptions): Promise<AiCodeGenerationResult>;
 ```
 
-## 🔧 配置文件
-
-### `.smarttestrc.json`
+**参数：**
 
-使用 `smart-test init` 命令生成的配置文件：
+```typescript
+interface AiMockGenerationOptions {
+  apiPath: string; // API 路径
+  description: string; // Mock 数据描述
+  responseType?: string; // 响应数据类型名称（可选）
+  typeDefinitions?: TypeDefinition[]; // TypeScript 类型定义列表（可选）
+  referenceCode?: string; // 参考代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
 
-```json
-{
-  "version": "1.0.0",
-  "ai": {
-    "model": "qwen3-vl-plus",
-    "apiKey": "${AI_API_KEY}",
-    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
-    "timeout": 30000
-  },
-  "output": {
-    "testsDir": "./tests/e2e",
-    "helpersDir": "./tests/helpers",
-    "naming": "kebab-case"
-  },
-  "templates": {
-    "mock": "default",
-    "test": "default"
-  },
-  "playwright": {
-    "baseURL": "http://localhost:8080",
-    "viewport": {
-      "width": 375,
-      "height": 667
-    },
-    "browser": "chromium"
-  }
+interface TypeDefinition {
+  typeName: string; // 类型名称
+  content: string; // 类型定义内容
 }
 ```
 
-### 支持的配置格式
-
-- `.smarttestrc.json`
-- `.smarttestrc.js`
-- `smarttest.config.js`
-- `package.json` 中的 `smarttest` 字段
+**使用说明：**
+传入 `typeDefinitions` 和 `responseType`，AI 会严格按照 TypeScript 类型定义生成 mock 数据，确保类型安全和数据准确性
 
-## 🔧 高级配置
+### aiGenerateCode
 
-### 支持多种 AI 模型
+通用的 AI 代码生成函数。
 
 ```typescript
-// 使用通义千问（默认）
-configure({
-  apiKey: process.env.QWEN_API_KEY,
-  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-  model: 'qwen3-vl-plus',
-});
-
-// 使用 OpenAI GPT-4 Vision
-configure({
-  apiKey: process.env.OPENAI_API_KEY,
-  baseURL: 'https://api.openai.com/v1',
-  model: 'gpt-4-vision-preview',
-});
+function aiGenerateCode(options: AiCodeGenerationOptions): Promise<AiCodeGenerationResult>;
 ```
 
-### 自定义截图存储
+**参数：**
 
 ```typescript
-configure({
-  screenshotDir: './custom-screenshots',
-  saveScreenshots: true,
-});
-
-// 单次调用自定义
-const result = await aiReviewScreenshot(page, {
-  expected: '...',
-  screenshotPrefix: 'my-feature',
-  screenshotDir: './feature-screenshots',
-});
+interface AiCodeGenerationOptions {
+  prompt: string; // 代码生成描述
+  context?: string; // 上下文代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
 ```
 
-### 在 CI 环境中使用
+**返回值：**
 
 ```typescript
-// 在 CI 中可能不需要保存截图，减少存储开销
-configure({
-  apiKey: process.env.AI_API_KEY,
-  saveScreenshots: process.env.CI !== 'true',
-});
+interface AiCodeGenerationResult {
+  ok: boolean; // 是否成功生成
+  code?: string; // 生成的代码
+  skipped?: boolean; // 是否跳过
+  reason?: string; // 跳过或失败原因
+  rawResponse?: string; // AI 原始响应
+}
 ```
 
-## 🤔 常见问题
-
-### Q: 没有配置 API Key 会怎样？
-
-A: 测试会自动跳过 AI 检查，返回 `skipped: true`，不会影响其他测试的执行。
-
-### Q: 支持哪些 AI 模型？
-
-A: 理论上支持所有兼容 OpenAI Chat Completions API 的视觉模型，包括：
+## 🎯 使用场景
 
-- 通义千问 (qwen3-vl-plus) - 默认
-- OpenAI GPT-4 Vision
-- 其他兼容的模型服务
+### 场景 1：视觉回归测试
 
-### Q: CLI 生成的测试代码需要手动修改吗？
+使用 AI 自动检测页面的视觉变化，无需手动维护大量的断言代码：
 
-A: 生成的代码是可以直接运行的，但建议根据实际需求进行调整。AI 会尽量生成合理的测试用例，但可能无法覆盖所有业务场景。
-
-### Q: 录制模式如何处理需要点击才能触发的接口？
-
-A: 录制模式支持三种方式：
-
-1. **手动操作**：`--manual` 参数，用户手动操作浏览器
-2. **交互式引导**：`--interactive` 参数，AI 引导用户操作
-3. **脚本引导**：`--actions` 参数，提供操作脚本自动执行
-
-### Q: 如何查看 AI 的原始响应？
+```typescript
+test('首页显示正常', async ({ page }) => {
+  await page.goto('/');
 
-A: 检查结果中的 `rawResponse` 字段包含了 AI 的原始响应内容。
+  const result = await aiReviewScreenshot(page, {
+    expected: '页面顶部显示网站logo和主导航，中间显示轮播图，下方显示4个产品分类卡片',
+    fullPage: true,
+  });
 
-```typescript
-const result = await aiReviewScreenshot(page, '...');
-console.log('AI 原始响应:', result.rawResponse);
+  expect(result.ok).toBeTruthy();
+});
 ```
 
-### Q: 生成的代码文件如何组织？
+### 场景 2：快速生成测试代码
 
-A: 默认按页面分组：
+为新功能快速生成测试用例骨架，节省编写测试代码的时间：
 
-- `tests/helpers/mock-{页面名}.ts` - Mock 数据
-- `tests/e2e/{页面名}.spec.ts` - 测试用例
+```typescript
+// 生成测试用例
+const result = await aiGenerateTestCase({
+  pageUrl: '/product/123',
+  scenario: '产品详情页展示和加入购物车功能',
+  apiMocks: [
+    { path: '**/api/product/detail', description: '返回产品详情' },
+    { path: '**/api/cart/add', description: '加入购物车成功' },
+  ],
+  testSteps: ['验证显示产品名称和价格', '点击"加入购物车"按钮', '验证显示成功提示'],
+});
 
-可以通过 `--output` 参数自定义输出目录。
+// 将生成的代码保存到文件，然后根据实际需要调整
+```
 
-## 🗺️ 开发路线图
+### 场景 3：Mock 数据管理
 
-### ✅ 已完成
+通过传入实际的类型定义，确保生成的 Mock 数据完全符合接口规范：
 
-- [x] AI 视觉检查核心功能
-- [x] CLI 基础架构
-- [x] 配置系统
-- [x] 交互式初始化
+```typescript
+// 读取或定义类型
+import { readFileSync } from 'fs';
+
+const addressTypeContent = readFileSync('./src/api/address/types.ts', 'utf-8');
+// 或者直接定义类型字符串
+
+const result = await aiGenerateMock({
+  apiPath: '**/api/user/address/get-default-address',
+  description: '返回用户默认地址',
+  responseType: 'IDefaultAddressResp',
+  typeDefinitions: [
+    {
+      typeName: 'IDefaultAddressResp',
+      content: extractTypeFromFile(addressTypeContent, 'IDefaultAddressResp'),
+    },
+    {
+      typeName: 'IUserAddress',
+      content: extractTypeFromFile(addressTypeContent, 'IUserAddress'),
+    },
+  ],
+});
 
-### 🚧 开发中
+// 生成的 mock 数据会严格符合类型定义，包括：
+// - 字段类型匹配（string、number、boolean、null 等）
+// - 必填/可选字段正确
+// - 嵌套对象结构准确
+// - 根据注释生成合理的测试数据
+```
 
-- [ ] 录制模式（Phase 2）
-  - [ ] 网络请求录制
-  - [ ] HAR 文件解析
-  - [ ] AI 生成 Mock 代码
-  - [ ] 交互操作录制
+## ⚙️ 配置说明
 
-### 📅 计划中
+### 默认配置
 
-- [ ] 代码分析模式（Phase 3）
-  - [ ] TypeScript AST 解析
-  - [ ] API 调用提取
-  - [ ] 类型定义分析
+```typescript
+{
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  visionModel: 'qwen3-vl-plus',
+  codeModel: 'qwen3-coder-plus',
+  timeout: 30000
+}
+```
 
-- [ ] 描述生成模式（Phase 4）
-  - [ ] 自然语言理解
-  - [ ] 交互式问答
-  - [ ] 代码生成
+## 🔍 最佳实践
 
-- [ ] 增强功能（Phase 5+）
-  - [ ] 增量更新
-  - [ ] 自定义模板
-  - [ ] 测试覆盖率分析
-  - [ ] VS Code 插件
+### 1. 合理使用 AI 检查
 
-## 📄 文档
+AI 视觉检查适合用于：
 
-- [CLI 设计文档](./docs/CLI_DESIGN.md) - 完整的 CLI 工具设计方案
-- [使用示例](./examples/) - 更多使用示例
+- ✅ 整体布局和结构验证
+- ✅ 内容完整性检查
+- ✅ 视觉回归测试
 
-## 📝 License
+不适合用于：
 
-MIT
+- ❌ 精确的像素级对比
+- ❌ 颜色值精确匹配
+- ❌ 性能敏感的场景
 
-## 🤝 贡献
+### 2. 组合使用
 
-欢迎提交 Issue 和 Pull Request！
+将 AI 检查与传统断言结合使用，获得最佳效果：
 
-## 📮 联系方式
+```typescript
+test('优惠券页面', async ({ page }) => {
+  await page.goto('/coupon');
 
-如有问题，请在 [GitHub Issues](https://github.com/snowmountain-top/be-link/issues) 中提出。
+  // 传统断言：精确的功能验证
+  await expect(page.getByText('优惠券')).toBeVisible();
+  await expect(page.getByRole('button', { name: '核销券' })).toBeVisible();
 
----
+  // AI 检查：整体视觉验证
+  const aiResult = await aiReviewScreenshot(page, '页面整体布局合理，优惠券卡片排列整齐，信息展示清晰');
 
-**版本**：v1.0.0 | **最后更新**：2025-12-30
+  if (!aiResult.skipped && aiResult.issues?.length) {
+    console.warn('AI 发现的潜在问题:', aiResult.issues);
+  }
+});
+```