@be-link/smart-test 1.0.1-beta.9 → 1.1.0

package/README.md

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