@kkeve/suite 0.0.1 → 0.0.2

package/doc/skills/keve-e2e-gen/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: keve-e2e-gen
+description: 源码分析 + 打标 + POM 生成 + 测试脚本生成。通过静态分析应用源代码，自动注入测试标识，生成 Page Object Model 和 Playwright 测试脚本。
+allowed-tools: Bash(shell:*) Bash(npx:*) Bash(npm:*) Bash(node:*) Bash(git:*)
+---
+
+# keve-e2e-gen
+
+## 定位
+
+**本技能负责**：源码分析 → 打标 → POM → 测试脚本生成（不负责执行和修复）。
+
+目录结构详见 `keve_test_spec/keve.yaml` 顶部注释（Single Source of Truth）。
+
+***
+
+## Phase 0: Scaffold
+
+> 首次使用必须执行。
+
+```bash
+keve init
+```
+
+创建 `keve_test_spec/`、`.keve/`、`.codeflicker/` 等基础设施。
+
+> **严禁从零手写配置**，只需微调 `baseURL` 和 `webServer.command`。
+
+***
+
+## Phase 1: Source Code Analysis + POM Generation
+
+本阶段在源代码层面操作，不打开浏览器。四个 Agent **严格按顺序**执行：
+
+| Agent | Mission | Output | 必须完成才能继续? |
+|-------|---------|--------|:---:|
+| Script Analyst | 扫描组件，提取交互元素、Props、条件渲染 | component-registry.json | ✅ |
+| Stage Manager | 注入缺失的 aria-label / data-e2e-name | testid-injections.json + **源码实际修改** | ✅ **打标必须完成后才能生成定位器** |
+| Blocking Coach | 生成定位器优先级链 | locator-catalog.json | ✅ |
+| Set Designer | 生成 Page Object Model 类 | `keve_test_spec/poms/*.ts` | ✅ |
+
+> **重要**：Stage Manager（打标）必须完成并实际修改源代码后，Blocking Coach 才能基于打标后的元素生成定位器。跳过打标会导致定位器找不到元素。
+
+**POM 路径规范**：
+- POM 类必须输出到 **项目根目录** 的 `keve_test_spec/poms/*.ts`（共享模块，跨 MR 复用）
+- **禁止** 将 POM 输出到 `.keve/task_xxx/poms/`（任务级目录会导致 import 路径错误）
+
+**定位器优先级**：
+
+| 元素类型 | Priority 1 | Priority 2 | Priority 3 |
+|----------|-----------|-----------|-----------|
+| 交互元素 | `getByRole + name` | `locator('[data-e2e-name="xxx"]')` | 结构化 selector |
+| 交互元素 | `locator('[data-e2e-name="xxx"]')` | 文本内容 | - |
+
+> **注意**：项目使用 `data-e2e-name`，**不要**使用 `getByTestId()`（它查找 `data-testid`）。
+> 正确写法：`page.locator('[data-e2e-name="xxx"]')`
+
+**标识注入原则**：
+- 交互元素：优先 `aria-label`，**绝不**注入 `data-e2e-name`
+- 非交互元素：仅不得已时注入 `data-e2e-name`，命名规则 `组件名-区域描述`（<=3层）
+
+→ 详细规则见 [code-analysis-guide](references/code-analysis-guide.md)
+
+***
+
+## Phase 2: Test Generation
+
+| Agent | Mission | Output |
+|-------|---------|--------|
+| Choreographer | 规划用户旅程 + Feature Flag/权限排列组合 | journeys.json |
+| Assistant Director | 映射到 POM 方法，生成 Playwright 脚本 | `.keve/task_xxx/keve_test_spec/*.spec.ts` |
+
+### 脚本写法标准（D15 决策）
+
+统一使用 `@keveModel/@keveScene` 装饰器写法。`@keveModel` 自动注册所有 `@keveScene` 方法为 Playwright `test()`，**不需要在文件底部手动调用 `test()`**。
+
+**装饰器签名**：
+- `@keveModel(id, description)` — 两个参数：模块ID（如 `AG`）+ 描述
+- `@keveScene(id, description)` — 两个参数：用例ID（如 `AG-01`）+ 描述
+
+**keveGoal 步骤标记**（函数调用形式，在方法体内每步调用一次）：
+- `keveGoal({ precondition?, step, expected }, fn)` — 在 `@keveScene` 方法体内调用，每个步骤调用一次
+- `fn` 为该步骤的具体执行函数，元数据和执行代码绑定在一起
+- fixture 参数需声明 `keveGoal`：`{ page, keveGoal, keveAssert }`
+
+**结构约束**：
+- 一个 `@keveModel` 下可以有多个 `@keveScene`
+- 一个 `@keveScene` 方法体内至少调用一次 `keveGoal({...}, fn)`
+
+**禁止事项**：
+- **禁止** 使用 `@keveGoal` 装饰器（已移除，改用 `keveGoal({...}, fn)` 函数调用）
+- **禁止** 单独调用 `keveGoal({...})` 不传 fn（步骤元数据必须和执行代码绑定）
+- **禁止** 在 `@keveScene` 方法内嵌套 `static async step1()` 子方法
+- **禁止** 把 ID 和描述混在一个字符串里（如 `@keveModel('AG: 智能应用...')`）
+- **禁止** 给装饰器传回调函数（如 `@keveModel('AG', () => {})`）
+
+**正确写法 vs 错误写法**：
+
+```typescript
+// ✅ 正确：keveGoal 函数调用，步骤元数据 + 执行函数绑定
+@keveScene('SF-01', '页面初始化加载筛选维度和视频列表')
+static async testPageInit({ page, keveGoal, keveAssert }: any) {
+  const searchPage = new VideoSearchPage(page);
+  await keveGoal({ step: '导航到视频列表页', expected: '页面加载完成，搜索框可见' }, async () => {
+    await searchPage.navigateTo();
+  });
+  await keveGoal({ step: '观察筛选器区域', expected: '显示6个筛选器下拉' }, async () => {
+    await searchPage.assertFiltersVisible();
+  });
+  await keveGoal({ step: '观察视频卡片区域', expected: '5列网格布局' }, async () => {
+    await keveAssert('页面加载完成', { label: 'SF01-Step3' });
+  });
+}
+
+// ❌ 错误：@keveGoal 装饰器叠加（已移除）
+@keveScene('SF-01', '页面初始化')
+@keveGoal({ step: '导航', expected: '页面加载' })
+static async testPageInit({ page, keveAssert }: any) { }
+
+// ❌ 错误：keveGoal 不传 fn（步骤元数据和执行代码分离）
+keveGoal({ step: '导航', expected: '页面加载' });
+await searchPage.navigateTo();
+
+// ❌ 错误：方法体内嵌套 static 子方法
+static async testPageInit({ page, keveGoal, keveAssert }: any) {
+  await keveGoal({ step: '导航', expected: '页面加载' }, async () => {
+    static async step1() { }  // 方法体内不能定义 static 方法！
+  });
+}
+```
+
+**核心纪律**：
+- 仅使用 POM 方法，绝不使用 `page.locator()` / `page.$()`
+- 绝不硬编码等待时间
+- 绝不硬编码环境数据（D05），从 `fixtures/test-data.ts` 导入
+- keveGoal 步骤必须与 test-cases.yaml 一一对应（D14）
+- 关键步骤追加 `keveAssert` 视觉断言（D11），每测试最多 5 次
+@keveScene('SF-01', '页面初始化')
+static async testPageInit() {
+  @keveGoal({ step: '导航', expected: '页面加载' })
+  static async step1() { }
+}
+```
+
+**核心纪律**：
+- 仅使用 POM 方法，绝不使用 `page.locator()` / `page.$()`
+- 绝不硬编码等待时间
+- 绝不硬编码环境数据（D05），从 `fixtures/test-data.ts` 导入
+- goals 步骤必须与 test-cases.yaml 一一对应（D14）
+- 关键步骤追加 `keveAssert` 视觉断言（D11），每测试最多 5 次
+
+→ 详细规则见 [script-generation-guide](references/script-generation-guide.md)
+
+***
+
+## Key Decisions
+
+| ID | 决策 | 说明 |
+|----|------|------|
+| D01 | 独立配置文件 | `--config=keve_test_spec/keve-test.config.ts` |
+| D05 | 环境数据集中定义 | `fixtures/test-data.ts` 导入，不硬编码 |
+| D11 | 关键步骤视觉断言 | keveAssert + 页面 console.error 采集 |
+| D12 | keveAssert 数量约束 | 每测试上限 5 次（建议 2-3 次） |
+| D14 | 用例步骤绑定 | `keveGoal({ precondition?, step, expected }, fn)` 函数调用，步骤元数据与执行代码绑定，与 YAML 一一对应 |
+| D15 | 装饰器写法 | @keveModel 自动注册 @keveScene，不需要手动 test() |
+
+***
+
+## References
+
+- [code-analysis-guide.md](references/code-analysis-guide.md) — 组件扫描、打标、定位器生成
+- [pom-generation-guide.md](references/pom-generation-guide.md) — POM 类结构、设计原则、编码规范（waitForReady/hover/输入清空）
+- [script-generation-guide.md](references/script-generation-guide.md) — 旅程规划、脚本生成、装饰器写法、keveAssert 用法
+- [test-auditor-guide.md](references/test-auditor-guide.md) — 测试深度等级、一致性校验
+
+## Scripts
+
+- [extract-components.sh](scripts/extract-components.sh) — 从源码提取组件注册表
+- [inject-testids.sh](scripts/inject-testids.sh) — 扫描并注入缺失标识

package/doc/skills/keve-e2e-gen/references/code-analysis-guide.md

@@ -0,0 +1,208 @@
+# 代码分析指南 (Code Analysis Guide)
+
+> Phase 2 前三步的合并指引：组件扫描 → 打标 → 定位器生成
+
+---
+
+## 三阶段流程
+
+```
+Step 1: 组件扫描 (Script Analyst) → component-registry.json
+Step 2: 打标 (Stage Manager) → testid-injections.json + *.patch
+Step 3: 定位器生成 (Blocking Coach) → locator-catalog.json
+```
+
+> **关键依赖**：Step 3 必须在 Step 2 打标应用后执行。
+
+---
+
+## Step 1: 组件扫描
+
+扫描 MR 变更涉及的组件文件，提取交互元素信息和 API 依赖，构建组件注册表。
+
+**API 依赖扫描（D10）**：
+- 扫描组件中调用的 API 方法（如 `getEditAgentDetail`、`getAgentList`）
+- 提取对应的 endpoint 路径（如 `/api/agent/detail`）
+- 标记 `triggersRender: true` 如果该 API 响应决定页面主要内容渲染（如 `v-if="detail"`）
+- 在 POM 的 `waitForReady()` 中生成 `page.waitForResponse()` 等待该接口
+
+### 各框架提取重点
+
+| 框架 | 提取重点 |
+|------|----------|
+| React | 函数组件的 Props/State、事件处理器、条件渲染 |
+| Vue | SFC 的 template 交互元素、Composition API 的 ref/reactive、v-if/v-show |
+
+### 噪音过滤规则
+
+- 排除纯展示组件（无交互元素）
+- 排除第三方库内部组件
+- 排除未在本次 MR 变更范围内的组件
+
+### 组件注册表 Schema
+
+```json
+{
+  "components": [
+    {
+      "name": "AgentList",
+      "filePath": "src/pages/agent/AgentList.vue",
+      "framework": "vue",
+      "interactiveElements": [
+        {
+          "type": "button",
+          "role": "filter",
+          "label": "类型筛选",
+          "existingTestId": null,
+          "needsInjection": true
+        }
+      ],
+      "conditionalRendering": [
+        { "element": "deleteButton", "condition": "role === 'admin'" }
+      ],
+      "stateDependencies": ["filterType", "selectedRole"],
+      "apiDependencies": [
+        { "name": "getEditAgentDetail", "endpoint": "/api/agent/detail", "triggersRender": true }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Step 2: 打标
+
+为缺失标识符的元素注入确定性定位标记。
+
+### 元素分类注入策略
+
+> **核心原则**：交互元素优先可访问性标识（aria-label），尽量不增加 data-e2e-name。
+
+| 元素类型 | 判断依据 | 优先方案 | 降级方案 |
+|----------|----------|----------|----------|
+| **交互元素** | button、input、select、a、radio、checkbox、textarea | ① 已有 aria-label 或可见文本 → **不注入**<br/>② 无 aria-label 且无可见文本 → **注入 aria-label** | 绝不注入 data-e2e-name |
+| **非交互元素** | div、span、container、text、status | ① 已有 data-e2e-name → **不注入**<br/>② 无 data-e2e-name → **注入 data-e2e-name** | 不得已才注入 |
+
+### 注入决策树
+
+```
+元素需要定位标记？
+  ├─ 是交互元素？
+  │   ├─ 已有 aria-label？ → 不注入（用 getByRole）
+  │   ├─ 有可见文本？ → 不注入（用 getByRole + name）
+  │   └─ 都没有（图标按钮等）→ 注入 aria-label
+  │       └─ 示例：<button aria-label="更多操作"><IconMore/></button>
+  │
+  └─ 非交互元素？
+      ├─ 已有 data-e2e-name？ → 不注入
+      └─ 没有 → 注入 data-e2e-name（不得已）
+          └─ 示例：<div data-e2e-name="智能应用详情-置灰遮罩">...</div>
+```
+
+### aria-label 注入规则
+
+**触发条件**（同时满足）：
+1. 是交互元素（button/input/select/a/radio/checkbox/textarea）
+2. 无现有 aria-label
+3. 无可见文本内容（如纯图标按钮、icon-only 元素）
+
+**命名规范**：
+- 中文业务语义：`组件名-操作描述`
+- 示例：`新建智能应用`、`更多操作`、`关闭弹窗`
+- **不要**写成 `XX按钮`（Role 已经表达"按钮"语义）
+
+### data-e2e-name 注入规则
+
+**仅在非交互元素且无任何标识符时注入**。
+
+**命名规范**：
+- 中文业务语义：`组件名-区域-描述`
+- ≤ 3 层
+- 禁止：`XX容器`、`XX-wrapper`、英文命名
+
+**旧属性共存**：新增 data-e2e-name 不删除旧属性，逐步下线统一。
+
+### 注入模板
+
+**交互元素——只注入 aria-label**：
+```vue
+<!-- Vue: 图标按钮 -->
+<KsButton aria-label="更多操作"><IconMore/></KsButton>
+
+<!-- Vue: 有文本则不需要注入 -->
+<KsButton>新建</KsButton>        <!-- 通过 getByRole('button', { name: '新建' }) -->
+
+<!-- React: 图标按钮 -->
+<button aria-label="更多操作"><IconMore/></button>
+```
+
+**非交互元素——注入 data-e2e-name**：
+```vue
+<!-- Vue: 容器/遮罩层 -->
+<div data-e2e-name="智能应用详情-置灰遮罩">不可编辑</div>
+```
+
+---
+
+## Step 3: 定位器生成
+
+基于已打标源代码，为每个交互元素生成确定性定位器。
+
+### 定位器优先级链
+
+> **重要**：交互元素和非交互元素使用不同的定位器策略。
+
+**交互元素（button/input/select/a/radio/checkbox/textarea）**：
+
+| 优先级 | 定位器类型 | Playwright API | 示例 |
+|--------|-----------|----------------|------|
+| Level 1 | getByRole + name | `page.getByRole('button', { name: '新建' })` | 基于 aria-label 或可见文本 |
+| Level 2 | locator + data-e2e-name | `page.locator('[data-e2e-name="xxx"]')` | 仅当元素已有 data-e2e-name |
+| Level 3 | CSS/Locator | `page.locator('[id="xxx"]')` | 最后手段 |
+
+**非交互元素（div/span/container/text）**：
+
+| 优先级 | 定位器类型 | Playwright API | 示例 |
+|--------|-----------|----------------|------|
+| Level 1 | locator + data-e2e-name | `page.locator('[data-e2e-name="xxx"]')` | 基于 data-e2e-name |
+| Level 2 | Text/Locator | `page.getByText('xxx')` | 最后手段 |
+
+> **重要**：项目使用 `data-e2e-name` 而非 `data-testid`，因此不能用 `getByTestId()`。
+> 必须使用 `page.locator('[data-e2e-name="xxx"]')`。
+
+### AST 验证
+
+定位器选择后必须通过 AST 验证：
+- aria-label → 确认为静态字符串（非动态绑定）
+- data-e2e-name → 确认属性存在于源代码中
+- id → 确认为静态值而非动态生成
+
+### 动态元素特殊处理
+
+| 类型 | 处理方式 |
+|------|----------|
+| 动态列表项 | 模板化定位器：`locator('[data-e2e-name="列表项-{{name}}"]')` |
+| 条件渲染元素 | 标注出现条件：`conditionalRender: "v-if=\"type === DATA\""` |
+| Feature Flag 控制 | 标注 flag：`featureFlag: "enableAppCreation"` |
+| 多状态元素 | 标注状态变体：`states: ["enabled", "disabled"]` |
+
+---
+
+## 输出文件
+
+| 文件 | 路径 | 内容 |
+|------|------|------|
+| 组件注册表 | `.keve/component-registry.json` | 所有交互组件和元素 |
+| 打标注入 | `.keve/testid-injections.json` | 需注入的 testid 列表 |
+| 打标补丁 | `*.patch` 或源代码变更 | 注入后的代码变更 |
+| 定位器目录 | `.keve/locator-catalog.json` | 每个元素的定位器链 |
+
+---
+
+## 最佳实践
+
+- **全量扫描**：不遗漏任何组件目录（pages/、views/、layouts/）
+- **最小侵入**：交互元素优先 aria-label，尽量不增加 data-e2e-name
+- **区分策略**：交互元素 getByRole，非交互元素 locator('[data-e2e-name="xxx"]')
+- **POM 定位器优先级**：交互元素: getByRole > locator('[data-e2e-name]') > css locator / 非交互元素: locator('[data-e2e-name]') > text

package/doc/skills/keve-e2e-gen/references/decisions.md

@@ -0,0 +1,36 @@
+# 关键决策索引 (Key Decisions)
+
+> 本文档集中管理 keve-e2e-gen 的所有关键决策，便于查阅和引用。
+
+---
+
+## 决策列表
+
+| ID | 决策 | 说明 | 关联文档 |
+|----|------|------|----------|
+| D01 | 独立配置文件 | `--config=keve_test_spec/keve-test.config.ts` | - |
+| D05 | 环境数据集中定义 | `fixtures/test-data.ts` 导入，不硬编码 | [script-generation-guide](script-generation-guide.md) |
+| D06 | 保障进程完整执行 | `2>&1 \| tee` 确保 JSON reporter 写入不受影响 | - |
+| D07 | Auth 自动 | `globalSetup` 自动注入登录态 | - |
+| D08 | 多轮结果隔离 | `KEVE_TASK_DIR` + `KEVE_ROUND` 指定每轮输出 | - |
+| D09 | 路由对照源代码 | POM 中 `page.goto()` 路由必须从源代码 router 配置提取 | [code-analysis-guide](code-analysis-guide.md) |
+| D10 | waitForReady 等 API | 代码分析阶段扫描 API 依赖，waitForReady 中增加 waitForResponse | [code-analysis-guide](code-analysis-guide.md) |
+| D11 | 关键步骤视觉断言 | keveAssert + 页面 console.error 采集 | [script-generation-guide](script-generation-guide.md) |
+| D12 | keveAssert 数量约束 | 每测试上限 5 次（建议 2-3 次） | [script-generation-guide](script-generation-guide.md) |
+| D13 | 超时 60s | 适应 AI 视觉断言 API 耗时 | - |
+| D14 | 用例步骤绑定 | `keveGoal({ precondition?, step, expected }, fn)` 函数调用，步骤元数据与执行代码绑定，与 YAML 一一对应 | [script-generation-guide](script-generation-guide.md) |
+| D15 | 装饰器写法（统一标准） | @keveModel/@keveScene 装饰器 + keveGoal() 函数调用，TC39 Stage 3，sceneCodeMap 供 Reporter 校验 | [script-generation-guide](script-generation-guide.md) |
+
+---
+
+## D 类修复方法速查
+
+> 详细分类和修复流程见 [fix-loop-guide](fix-loop-guide.md)
+
+| D 子类型 | 修复方法 |
+|----------|----------|
+| D-1 定位器不匹配 | 更新 POM 定位器 |
+| D-2 硬编码路径 | 从 router 配置提取路由，改用 test-data |
+| D-3 断言逻辑错误 | 修正断言匹配页面实际行为 |
+| D-4 组件渲染不匹配 | 处理条件渲染/动态组件 |
+| D-5 等待策略不足 | 增加 waitFor / waitForResponse |

package/doc/skills/keve-e2e-gen/references/pom-generation-guide.md

@@ -0,0 +1,140 @@
+# POM 生成指南 (POM Generation Guide)
+
+> Phase 1 后半 + 实战编码规范：定位器目录 → POM 类生成
+
+---
+
+## POM 类结构
+
+```typescript
+export class AgentListPage {
+  constructor(private page: Page) {}
+
+  // 导航方法
+  async navigateTo(): Promise<void> {
+    await this.page.goto('/agents');
+    await this.waitForReady();
+  }
+
+  // 等待方法
+  async waitForReady(): Promise<void> {
+    // 等待关键 API 响应（如果页面依赖接口渲染） 注意接口地址严格按照代码逻辑不要随意改写
+    await this.page.waitForResponse(resp =>
+      resp.url().includes('/api/agent/detail') && resp.status() === 200
+    );
+    // 等待 DOM 渲染
+    await this.page.locator('[data-e2e-name="智能应用列表-筛选区域"]').waitFor({ state: 'visible' });
+  }
+
+  // 交互方法（语义化命名）
+  async selectFilterType(type: string): Promise<void> {
+    await this.page.getByRole('radio', { name: type }).click();
+  }
+
+  // 断言方法（返回 Locator 或直接断言）
+  async assertFilterOptionsVisible(): Promise<void> {
+    await expect(this.page.locator('[data-e2e-name="智能应用列表-筛选区域"]')).toBeVisible();
+  }
+}
+```
+
+## POM 设计原则
+
+- **单一页面 = 单一 POM 类**
+- **方法命名用业务语义**（`selectFilterType` 而非 `clickRadio`）
+- **定位器只在 POM 中定义**，测试文件通过 POM 方法调用
+- **navigate 方法必须包含 waitForReady**
+- **不包含环境数据**（D05：ID 从 test-data.ts 导入，POM 的 navigate 方法接受参数）
+- **路由必须对照源代码验证**（D09）：POM 中 `page.goto()` 的路由必须从源代码的 router 配置文件中提取，**严禁猜测路由格式**
+- **waitForReady 必须等待 API 响应**（D10）：在代码分析阶段扫描组件的 API 依赖（如 `getEditAgentDetail`），在 `waitForReady()` 中增加 `page.waitForResponse()` 等待接口返回后再定位元素。避免 `v-if="detail"` 导致的内容区空白超时。
+
+---
+
+## POM 编码规范（实战提炼）
+
+> 来自 MR868 实战经验，以下规范必须写入所有生成的 POM 代码。
+
+### waitForReady: 事件驱动，不吞错误
+
+```typescript
+// 反模式: 多层串行等待 + 超长timeout + catch吞错误 + 兜底硬等
+async waitForReady(): Promise<void> {
+  await this.page.waitForResponse(
+    resp => resp.url().includes('/api/list') && resp.status() === 200,
+    { timeout: 15000 }  // 太长!
+  ).catch(() => {});  // 吞掉错误, 可能导致静默超时
+  await this.page.waitForLoadState('domcontentloaded', { timeout: 15000 }).catch(() => {});
+  await this.page.locator('[data-e2e-name="列表"]').waitFor({ state: 'visible', timeout: 15000 }).catch(async () => {
+    await this.page.waitForTimeout(2000);  // 兜底硬等!
+  });
+}
+
+// 推荐: 单一关键信号等待 + 合理timeout + 不吞错误
+async waitForReady(): Promise<void> {
+  // 方案A: 等关键API响应 (最精确)
+  await this.page.waitForResponse(
+    resp => resp.url().includes('/api/list') && resp.status() === 200,
+    { timeout: 5000 }  // 合理timeout, API正常应在1-2s内返回
+  );
+  // 等关键UI元素可见 (确认渲染完成)
+  await this.page.locator('[data-e2e-name="列表"]').waitFor({ state: 'visible', timeout: 3000 });
+}
+
+// 方案B: 等UI信号 (不依赖API, 更健壮)
+async waitForReady(): Promise<void> {
+  await this.page.locator('[data-e2e-name="列表"]').waitFor({ state: 'visible', timeout: 5000 });
+}
+```
+
+**规范要点**:
+- `waitForResponse` timeout 不超过 5000ms (API正常1-2s内返回)
+- 不使用 `.catch(() => {})` 吞掉超时错误
+- 不使用 `waitForLoadState` + 兜底 `waitForTimeout` 组合
+- `waitForReady` 最多2层等待: API信号 + UI信号
+
+### Tooltip hover: 等DOM出现，不硬等时间
+
+```typescript
+// 反模式: 硬等tooltip弹出
+async hoverButton(): Promise<void> {
+  await this.button.hover({ force: true });
+  await this.page.waitForTimeout(800);  // 硬等, 可能不够或浪费
+}
+
+// 推荐: 等tooltip DOM出现
+async hoverButtonAndWaitTooltip(): Promise<void> {
+  await this.button.hover({ force: true });
+  await this.page.locator('[role="tooltip"], .ks-tooltip__popper')
+    .first().waitFor({ state: 'visible', timeout: 3000 });
+}
+```
+
+**规范要点**:
+- hover后用 `waitFor({ state: 'visible' })` 等tooltip DOM出现
+- 绝不使用 `waitForTimeout` 等待tooltip弹出
+- tooltip定位器优先 `[role="tooltip"]`, fallback `.ks-tooltip__popper`
+- disabled元素的hover必须使用 `{ force: true }`
+
+### 输入清空: 等DOM更新，不硬等时间
+
+```typescript
+// 反模式: 清空后硬等
+await input.clear();
+await page.waitForTimeout(500);
+
+// 推荐: 等字数统计DOM更新 (事件驱动)
+await input.clear();
+await expect(wordCountLocator).toHaveText(/0\/300/, { timeout: 3000 });
+```
+
+**规范要点**:
+- `input.clear()` 后用 `expect(locator).toHaveText()` 等DOM更新
+- 绝不使用 `waitForTimeout` 等清空生效
+- 如果没有对应的DOM指示器, 使用 `waitForFunction` 或 `waitForResponse`
+
+---
+
+## 输出路径
+
+- POM 类必须输出到 **项目根目录** 的 `keve_test_spec/poms/*.ts`（共享模块，跨 MR 复用）
+- **禁止** 将 POM 输出到 `.keve/task_xxx/poms/`（任务级目录会导致 import 路径错误）