@kkeve/suite 0.0.1 → 0.0.3

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

@@ -0,0 +1,236 @@
+# 脚本生成指南 (Script Generation Guide)
+
+> Phase 2 指引：旅程规划 → 测试脚本生成 → keveAssert 视觉断言
+
+---
+
+## Step 1: 旅程规划
+
+从 test-cases.yaml 的用例步骤生成测试旅程（journey），确定排列组合。
+
+### 旅程结构
+
+```json
+{
+  "journeys": [
+    {
+      "id": "AG-01-type-filter",
+      "name": "类型筛选只显示用户自建",
+      "testCaseId": "AG-01",
+      "permutations": {
+        "role": ["admin", "viewer"],
+        "dataState": ["populated", "empty"]
+      },
+      "steps": [
+        { "action": "navigateTo", "pom": "AgentListPage" },
+        { "action": "selectFilterType", "pom": "AgentListPage", "args": ["我创建的"] },
+        { "action": "assertFilterResult", "pom": "AgentListPage", "expected": "只显示当前用户创建的Agent" }
+      ]
+    }
+  ]
+}
+```
+
+### 排列维度
+
+从以下维度识别排列：
+- **角色/权限**：admin vs viewer
+- **数据状态**：有数据 vs 空数据
+- **Feature Flag**：开关状态
+- **环境条件**：已登录 vs 未登录
+
+---
+
+## Step 2: 测试脚本生成
+
+将旅程映射为 Playwright 测试代码。
+
+### 核心纪律（强制规则）
+
+> 1. **绝不使用原始定位器**：不使用 `page.locator()` / `page.$()` / CSS/XPath（POM 内部除外）
+> 2. **绝不硬编码等待时间**：不使用 `waitForTimeout()`，通过 POM waitForReady 或断言等待
+> 3. **绝不硬编码环境数据**（D05）：ID/配置值从 `fixtures/test-data.ts` 导入
+> 4. **每个测试覆盖恰好一个排列**：测试体内无 if/else 分支逻辑
+
+### 正确模式 vs 禁止模式
+
+```typescript
+// ✅ 正确：POM 方法 + test-data 导入
+import { testData } from '../fixtures/test-data';
+await agentDetailPage.navigate(testData.agents.tcPortal.id, 'edit');
+await expect(page.locator('[data-e2e-name="智能应用列表-筛选区域"]')).toBeVisible();
+
+// ❌ 禁止：原始定位器 + 硬编码
+await page.locator('.filter-area').click();
+await page.waitForTimeout(5000);
+await agentDetailPage.navigate(636, 'edit');
+```
+
+### fixtures/test-data.ts 结构
+
+```typescript
+export const testData = {
+    agents: { tcPortal: { id: 636, name: '天策门户Agent' }, ... },
+    knowledges: { tcPortal: { id: 1008, name: '天策门户知识库' }, ... },
+    welcomeWord: { maxChars: 300 },
+};
+```
+
+### 测试文件结构（装饰器写法，D15 决策）
+
+> **注意**：装饰器只用于 spec 测试文件。POM 类仍然是普通 TypeScript 类，不使用装饰器。
+
+```typescript
+import { test, expect, keveModel, keveScene } from '@ks-data/keve-suite/keve-test';
+import { AgentListPage } from '../../../keve_test_spec/poms/AgentListPage';
+import { testData } from '../../../keve_test_spec/fixtures/test-data';
+
+@keveModel('AG', '智能应用列表筛选去除TC/DATASET')
+class AgentFilterTests {
+  @keveScene('AG-01', '智能应用列表不显示TC/DATASET来源筛选选项')
+  static async testSourceFilterHidden({ page, keveGoal, keveAssert }: any) {
+    const agentListPage = new AgentListPage(page);
+    await keveGoal({ step: '进入智能应用列表页', expected: '页面正常加载，筛选区域可见' }, async () => {
+      await agentListPage.navigateTo();
+    });
+    await keveGoal({ step: '观察来源筛选区域选项', expected: '来源筛选不显示TC/DATASET选项，仅显示权限筛选' }, async () => {
+      await agentListPage.assertSourceFilterHidden();
+      await keveAssert('筛选区域不显示TC/DATASET选项', { label: 'AG01-Step2' });
+    });
+  }
+
+  @keveScene('AG-02', '权限筛选功能正常')
+  static async testPermissionFilter({ page, keveGoal, keveAssert }: any) {
+    const agentListPage = new AgentListPage(page);
+    await keveGoal({ precondition: '已登录且在列表页', step: '选择"我创建的"筛选', expected: '列表仅显示当前用户创建的Agent' }, async () => {
+      await agentListPage.navigateTo();
+      await agentListPage.selectFilterType('我创建的');
+      await keveAssert('列表仅显示用户创建的Agent', { label: 'AG02-Step1' });
+    });
+  }
+}
+```
+
+**三层装饰器映射**：
+
+| 层级 | 装饰器/函数 | 对应 | 职责 |
+|------|------------|------|------|
+| 模块 | `@keveModel(id, description)` | test.describe | 模块ID + 描述 |
+| 场景 | `@keveScene(id, description)` | test | 用例ID + 描述 + fn.toString() 自动捕获完整场景脚本 |
+| 步骤 | `keveGoal({ precondition?, step, expected })` | 步骤元数据 | 函数调用，嵌套在 @keveScene 方法体内 |
+
+**装饰器/函数签名**：
+- `@keveModel(id, description)` — 两个参数：模块ID（如 `AG`）+ 描述
+- `@keveScene(id, description)` — 两个参数：用例ID（如 `AG-01`）+ 描述
+- `keveGoal({ precondition?, step, expected }, fn)` — 函数调用形式，在方法体内每步调用一次，fn 为该步骤的执行函数
+
+**结构约束**：
+- 一个 `@keveModel` 下可以有多个 `@keveScene`
+- 一个 `@keveScene` 下至少有一个 keveGoal 调用
+
+**重要约束**：
+- `@keveModel` 和 `@keveScene` 的 id 对应 test-cases.yaml 中的模块 ID 和用例 ID
+- **禁止** 使用 `@keveGoal` 装饰器（已移除，改用 `keveGoal({...}, fn)` 函数调用）
+- **禁止** 单独调用 `keveGoal({...})` 不传 fn（步骤元数据必须和执行代码绑定）
+- **禁止** 在 `@keveScene` 方法内嵌套 `static async step1()` 子方法
+- **禁止** 把 ID 和描述混在一个字符串里（如 `@keveModel('AG: 智能应用...')`）
+- **禁止** 传入回调函数（如 `@keveModel('AG', () => {})`)
+- `@keveScene` 自动捕获 `fn.toString()` 供 Reporter 做 code-goal 一致性校验
+
+### 用例状态过滤
+
+| 状态 | 处理 |
+|------|------|
+| `active` | 正常生成脚本 |
+| `skipped` | **不生成脚本** |
+| `pending` + `data_dependency: true` | **暂不生成**，等待数据后补充 |
+
+---
+
+## Step 3: keveAssert 视觉断言（消除假阳性）
+
+> **核心思路**：Playwright DOM 断言为主（确定性、快速），keveAssert 视觉断言为辅（验证真实页面状态）。
+
+```typescript
+// 1. 导入装饰器和测试工具
+import { test, expect, keveModel, keveScene } from '@ks-data/keve-suite/keve-test';
+import { AgentListPage } from '../../keve_test_spec/poms/AgentListPage';
+
+// 2. 使用 @keveModel/@keveScene 装饰器 + keveGoal() 函数调用编写用例
+@keveModel('AG', '智能应用列表筛选去除TC/DATASET')
+class AgentFilterTests {
+  @keveScene('AG-01', '智能应用列表不显示TC/DATASET来源筛选选项')
+  static async testNoSourceFilter({ page, keveGoal, keveAssert }: any) {
+    const agentListPage = new AgentListPage(page);
+    await keveGoal({ precondition: '已登录', step: '进入列表页并观察筛选区域', expected: '来源筛选区域不显示TC/DATASET选项' }, async () => {
+      await agentListPage.navigateTo();
+      await agentListPage.assertSourceFilterHidden();
+      await keveAssert('筛选区域不显示TC/DATASET选项', { label: 'AG01-Step1' });
+    });
+  }
+}
+```
+
+**何时添加 keveAssert**：
+
+| 步骤类型 | 是否需要 keveAssert | 示例 |
+|----------|---------------------|------|
+| 页面首次加载完成 | **必须** | "页面已完全加载，无加载中提示" |
+| 关键交互操作后 | **必须** | "点击筛选后列表仅显示对应类型" |
+| 状态变更断言 | **必须** | "按钮已变为禁用状态" |
+| 简单导航跳转 | 可选 | 跳转到详情页 |
+| 数据填充/输入 | 可选 | 填写表单字段 |
+
+**keveAssert 规范要点**:
+- 断言描述必须**具体、可视觉判断**，不要写模糊描述如"页面正常"
+- 断言描述要包含**负面条件**："无加载中提示"、"无错误弹窗"
+- label 格式：`用例ID-StepN-视觉验证`（如 `AG01-Step1-视觉验证`）
+- keveAssert 失败时直接抛出 Error，测试标记为 failed
+
+**keveAssert 数量约束**（D12 决策）:
+- 每个测试用例**最多 5 次** keveAssert 调用
+- **建议 2-3 次**：Step1 验证页面加载状态，Step2-3 验证核心断言
+- 冗余断言应**合并**
+- 可由 DOM `expect` 覆盖的验证**不使用 keveAssert**
+
+**keveWaitFor 使用**（替代硬等待）：
+
+```typescript
+// 替代 page.waitForTimeout(2000)
+await keveWaitFor('页面加载完成，列表数据已渲染', { timeoutMs: 10000 });
+```
+
+**Tooltip 验证**（不依赖 hover/popper）：
+
+ks-tooltip 基于 ks-popper，content 存在 Vue 组件 props 中。使用 `getTooltipContent()` 直接读取，无需 hover 触发：
+
+```typescript
+import { getTooltipContent, getAllTooltipContents } from '@ks-data/keve-suite/keve-test';
+
+// 单个验证
+const tip = await getTooltipContent(page, '[data-e2e-name="新建按钮提示"]');
+expect(tip).toBe('暂无创建权限');
+
+// 批量验证
+const tips = await getAllTooltipContents(page, '[data-e2e-name$="-tooltip"]');
+for (const t of tips) {
+  expect(t.content).not.toBeNull();
+}
+```
+
+**禁止**：`await page.hover(...)` + `await page.waitForSelector('.ks-popper')` 这种方式不稳定。
+
+**页面 console.error 自动采集**（D11 决策）：
+- 所有使用 `keve-fixture` 的测试默认启用 console.error 采集
+- 测试结束后，如有 console.error，自动附加到报告作为 `页面-Console-Error` attachment
+
+---
+
+## 输出文件
+
+| 文件 | 路径 |
+|------|------|
+| 测试脚本 | `.keve/task_xxx/keve_test_spec/*.spec.ts` |
+| 测试数据 | `keve_test_spec/fixtures/test-data.ts` |
+
+> POM 类输出到 `keve_test_spec/poms/*.ts`，详见 [pom-generation-guide](pom-generation-guide.md)

package/doc/skills/keve-e2e-gen/references/test-auditor-guide.md

@@ -0,0 +1,189 @@
+# 测试审计员指南 (Subagent: Test Auditor)
+
+## 使命
+
+测试审计员是**一致性守卫者**。它确保生成的 Playwright 测试脚本与原始测试用例描述一一对应，防止出现"浅层测试"（只验证页面可见，不验证业务功能）。
+
+> 核心洞察：如果测试用例描述"筛选只显示用户自建"，但生成的脚本只调用 `assertPageVisible()`，这就是**一致性违规**。
+
+---
+
+## 问题定义
+
+### 测试深度等级
+
+> 详细的等级定义、适用场景和反例参见 [Fix Loop Guide](fix-loop-guide.md)。
+
+| 等级 | 名称 | 最低要求 | 示例 |
+|------|------|----------|------|
+| L0 | 无断言 | ❌ 不允许 | 点击按钮但不检查结果 |
+| L1 | 页面可见 | 导航测试可接受 | `expect(container).toBeVisible()` |
+| L2 | 元素可见 | 最低要求 | `expect(button).toBeVisible()` |
+| L3 | 业务断言 | 功能测试必须达到 | `expect(filterOptions).toEqual([...])` |
+| L4 | 状态断言 | 交互/数据变更测试 | `expect(countAfter).toBeLessThan(countBefore)` |
+
+**最低要求**：每个测试用例的脚本至少达到 **L2 级别**。如果原始用例描述包含业务功能验证（如"筛选只显示"、"按钮禁用"），脚本应达到 **L3 级别**。
+
+> 详细的断言策略、时序等待方法和反模式参见 [Fix Loop Guide](fix-loop-guide.md)。
+
+---
+
+## 一致性校验规则
+
+### 规则 1：用例ID-脚本对应
+
+每个测试用例 ID 必须在生成的脚本中找到对应的 `test()` 块。
+
+```
+用例: AG-01 类型筛选只显示用户自建
+  → 必须存在 test('AG-01: ...', ...) 
+  → test 内必须包含与"筛选只显示用户自建"相关的断言
+```
+
+### 规则 2：预期结果-断言对应
+
+每个用例的"预期结果"必须在脚本中有对应的断言。
+
+| 预期结果关键词 | 应有的断言类型 |
+|----------------|----------------|
+| "只显示" / "不显示" | 数量断言、内容断言、可见性断言 |
+| "禁用" / "disabled" | `expect(element).toBeDisabled()` |
+| "可见" / "可见性" | `expect(element).toBeVisible()` |
+| "文案为" / "显示" | `expect(element).toHaveText()` |
+| "排序" / "排在前面" | 顺序断言、索引断言 |
+| "自动截断" | 长度断言 |
+| "字数" / "计数" | 文本长度断言 |
+
+### 规则 3：禁止降级断言
+
+如果原始用例描述了具体的业务功能验证，生成的脚本**不允许降级为 L1（页面可见）断言**。
+
+```
+❌ 错误示例:
+  用例: AG-01 筛选只显示用户自建
+  脚本: expect(agentListPage.getContainer()).toBeVisible()  // L1 断言，与用例不匹配
+
+✅ 正确示例:
+  用例: AG-01 筛选只显示用户自建
+  脚本: 
+    const options = agentListPage.getFilterOptions();
+    await expect(options).toHaveLength(3);
+    await expect(options.nth(0)).toHaveText('全部');
+    await expect(options.nth(1)).toHaveText('我创建的');
+    await expect(options.nth(2)).toHaveText('可编辑的');
+    // 不包含 '天策门户' 和 '数据集'
+```
+
+---
+
+## 校验流程
+
+### Step 1: 读取测试用例文档
+
+从以下来源获取原始测试用例描述：
+- `.codeflicker/discuss/*/notes/test-cases.md`
+- PRD 文档中的测试用例表格
+- 用户提供的用例列表
+
+### Step 2: 解析每个用例的 ID、描述、预期结果
+
+```json
+{
+  "id": "AG-01",
+  "description": "类型筛选只显示用户自建",
+  "expectedResult": "只显示'全部/我创建的/可编辑的'筛选，天策门户/数据集单选项不显示"
+}
+```
+
+### Step 3: 扫描生成的测试脚本
+
+遍历所有 `.spec.ts` 文件，提取每个 `test()` 块的：
+- 用例 ID（从 test title 中提取）
+- 实际断言列表（从 `expect()` 调用中提取）
+- 断言深度等级（L0~L4）
+
+### Step 4: 逐一对比
+
+对每个用例，对比"预期结果关键词"和"实际断言"：
+
+```
+用例 AG-01:
+  预期关键词: ["只显示", "不显示", "筛选"]
+  实际断言:   [expect(container).toBeVisible()]  // L1
+  匹配结果:   ❌ 一致性违规
+  原因:       "只显示" 需要 L3 级别的数量/内容断言，但脚本只有 L1 级别的可见性断言
+  建议:       补充 getFilterOptions() 断言
+```
+
+### Step 5: 生成审计报告
+
+输出格式：
+
+```json
+{
+  "auditId": "audit-2026-05-28",
+  "totalCases": 38,
+  "consistentCases": 15,
+  "violations": [
+    {
+      "caseId": "AG-01",
+      "expectedDepth": "L3",
+      "actualDepth": "L1",
+      "expectedKeywords": ["只显示", "筛选"],
+      "missingAssertions": ["getFilterOptions数量断言", "getFilterOptions内容断言"],
+      "suggestion": "补充: await expect(filterOptions).toHaveLength(3)"
+    }
+  ],
+  "coverageRate": "39.5%"
+}
+```
+
+### Step 6: 自动补充断言（可选）
+
+对于一致性违规的用例，自动补充深层断言：
+
+1. 分析用例的预期结果关键词
+2. 确定需要的断言类型和等级
+3. 查找 POM 中是否有对应的方法
+4. 如果有 → 直接补充调用
+5. 如果没有 → 触发 Agent 4 重新生成 POM 方法（如 `assertFilterOptions`）
+
+---
+
+## 与 Subagent 的集成方式
+
+测试审计员作为一个独立 subagent 运行，在 Agent 6 生成测试脚本之后、Agent 7 执行测试之前触发：
+
+```
+Agent 5 (choreographer) → 生成 journeys.json
+    ↓
+Agent 6 (assistant-director) → 生成测试脚本 (*.spec.ts)
+    ↓
+【在这里触发 Subagent: test-auditor】
+    ↓
+    ├─ 如果有违规 → 自动补充断言 / 重新生成部分脚本
+    └─ 如果全部一致 → 继续执行
+    ↓
+Agent 7 (continuity-lead) → 执行测试
+```
+
+### Subagent 配置
+
+在 `.codeflicker/agents/` 中创建 `test-auditor.md`：
+
+```yaml
+---
+name: test-auditor
+description: Validate consistency between test case descriptions and generated Playwright scripts
+---
+```
+
+---
+
+## 关键原则
+
+1. **预期结果驱动断言** — 用例的"预期结果"决定脚本应有的断言深度
+2. **禁止降级** — 有业务功能描述的用例不允许降级为 L1 断言
+3. **关键词-断言映射** — 预期结果中的关键词必须有对应的断言类型
+4. **审计覆盖率** — 目标 ≥ 80% 的用例达到 L2+ 级别
+5. **自动补充优先** — 尽量自动补充断言，减少人工干预

package/doc/skills/keve-e2e-gen/scripts/extract-components.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# extract-components.sh — 从源代码自动扫描并提取组件注册表
+#
+# 自动扫描 src/ 目录下的 Vue/React 组件文件，提取组件名称和文件路径，
+# 生成 component-registry.json 供后续 Agent 使用。
+#
+# 使用方式：
+#   bash scripts/extract-components.sh [项目根目录路径]
+#
+# 输出: .keve/component-registry.json
+
+set -e
+
+PROJECT_ROOT="${1:-.}"
+OUTPUT_DIR="${PROJECT_ROOT}/.keve"
+mkdir -p "$OUTPUT_DIR"
+
+echo "[extract] 正在扫描项目源码提取组件..."
+
+# 自动扫描 src/ 下的 .vue / .tsx 组件文件，生成组件注册表
+node -e "
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = '$PROJECT_ROOT';
+const srcDir = path.join(projectRoot, 'src');
+
+if (!fs.existsSync(srcDir)) {
+  console.error('[extract] src/ 目录不存在，请确认项目结构');
+  process.exit(1);
+}
+
+// 扫描所有 .vue 和 .tsx 文件
+const components = [];
+const extensions = ['.vue', '.tsx'];
+
+function scanDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // 跳过 node_modules、test、__tests__、mock 等目录
+      if (['node_modules', 'test', '__tests__', '__test__', 'mock', 'mocks', 'stories'].includes(entry.name)) continue;
+      scanDir(fullPath);
+    } else if (extensions.some(ext => entry.name.endsWith(ext))) {
+      // 跳过测试文件和 Storybook 文件
+      if (entry.name.includes('.test.') || entry.name.includes('.spec.') || entry.name.includes('.stories.')) continue;
+
+      const filePath = path.relative(projectRoot, fullPath);
+      // 从文件名推断组件名（去掉扩展名）
+      let componentName = entry.name.replace(/\.vue$|\.tsx$/, '');
+      // 处理 index 文件 — 用父目录名作为组件名
+      if (componentName === 'index') {
+        componentName = path.basename(dir);
+      }
+
+      components.push({
+        name: componentName,
+        filePath: filePath,
+      });
+    }
+  }
+}
+
+scanDir(srcDir);
+
+// 排序：按文件路径排列，便于阅读
+components.sort((a, b) => a.filePath.localeCompare(b.filePath));
+
+const registry = {
+  components,
+  metadata: {
+    project: path.basename(projectRoot),
+    totalComponents: components.length,
+    extractedAt: new Date().toISOString(),
+  }
+};
+
+const outputPath = path.join('$OUTPUT_DIR', 'component-registry.json');
+fs.writeFileSync(outputPath, JSON.stringify(registry, null, 2));
+console.log('[extract] 找到 ' + components.length + ' 个组件');
+console.log('[extract] 组件注册表已生成: ' + outputPath);
+console.log('[extract] 下一步: 运行 inject-testids.sh 进行打标注入');
+"

package/doc/skills/keve-e2e-gen/scripts/inject-testids.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# inject-testids.sh — 扫描源代码 Vue/React 组件，注入缺失的标识符
+#
+# 注入策略（最小侵入，优先可访问性）：
+#   - 交互元素（button/input/link/radio）：优先注入 aria-label，绝不注入 data-e2e-name
+#   - 非交互元素（container/text/status）：不得已时注入 data-e2e-name
+#   - 旧属性共存，不删除
+#   - 命名规范：
+#     aria-label: 简洁动作描述（如 "新建智能应用"）
+#     data-e2e-name: 组件名-区域描述（如 "智能应用详情-置灰遮罩"）
+#
+# 输出：
+#   .keve/testid-injections.json — 注入记录
+#   源代码文件 — 直接修改（git diff 可查看变更）
+
+set -e
+
+PROJECT_ROOT="${1:-.}"
+OUTPUT_DIR="${PROJECT_ROOT}/.keve"
+COMPONENT_REGISTRY="${OUTPUT_DIR}/component-registry.json"
+INJECTIONS_FILE="${OUTPUT_DIR}/testid-injections.json"
+
+mkdir -p "$OUTPUT_DIR"
+
+echo "[inject] 正在扫描组件并注入 data-testid / aria-label..."
+
+# 如果没有 component-registry.json，先运行 extract-components.sh
+if [ ! -f "$COMPONENT_REGISTRY" ]; then
+    echo "[inject] 未找到 component-registry.json，请先运行 extract-components.sh"
+    exit 1
+fi
+
+# 扫描需要注入的组件文件
+COMPONENT_FILES=$(cat "$COMPONENT_REGISTRY" | python3 -c "
+import json, sys
+registry = json.load(sys.stdin)
+files = set()
+for component in registry.get('components', []):
+    f = component.get('filePath', '')
+    if f and f.endswith('.vue'):
+        files.add(f)
+print('\n'.join(sorted(files)))
+" 2>/dev/null)
+
+if [ -z "$COMPONENT_FILES" ]; then
+    echo "[inject] 未找到需要处理的组件文件"
+    exit 0
+fi
+
+INJECTIONS=()
+
+for FILE in $COMPONENT_FILES; do
+    FULL_PATH="${PROJECT_ROOT}/${FILE}"
+    if [ ! -f "$FULL_PATH" ]; then
+        echo "[inject] 跳过不存在的文件: $FILE"
+        continue
+    fi
+
+    echo "[inject] 处理: $FILE"
+
+    # 注入规则：使用 sed 进行源代码修改
+    # 规则1: <button> 没有 aria-label 且没有可见文本 → 注入 aria-label
+    # 规则2: 容器元素没有 data-testid → 注入 data-testid
+    # 规则3: 旧 data-e2e-name 共存
+
+    # 这些规则需要根据具体项目调整
+    # 以下是通用模板，实际注入由 Agent 2 (Stage Manager) 在分析后精确执行
+
+    # 检查文件中是否有 data-testid
+    TESTID_COUNT=$(grep -c 'data-testid' "$FULL_PATH" 2>/dev/null || echo "0")
+    echo "[inject]   已有 data-testid: $TESTID_COUNT 个"
+
+    if [ "$TESTID_COUNT" -eq "0" ]; then
+        echo "[inject]   ⚠️ 该文件缺少 data-testid，需要人工或 Agent 2 注入"
+        INJECTIONS+=("{\"file\":\"$FILE\",\"status\":\"needs_injection\",\"existing_testid_count\":$TESTID_COUNT}")
+    else
+        INJECTIONS+=("{\"file\":\"$FILE\",\"status\":\"partial\",\"existing_testid_count\":$TESTID_COUNT}")
+    fi
+done
+
+# 生成 injections 文件
+echo "[" > "$INJECTIONS_FILE"
+for i in "${!INJECTIONS[@]}"; do
+    if [ $i -gt 0 ]; then echo "," >> "$INJECTIONS_FILE"; fi
+    echo "${INJECTIONS[$i]}" >> "$INJECTIONS_FILE"
+done
+echo "]" >> "$INJECTIONS_FILE"
+
+echo "[inject] 注入扫描完成！"
+echo "[inject] 输出: $INJECTIONS_FILE"
+echo "[inject] 下一步："
+echo "  1. 使用 Agent 2 (Stage Manager) 分析每个组件，确定需要注入的具体元素"
+echo "  2. 根据分析结果修改源代码，注入 data-testid 和 aria-label"
+echo "  3. 运行 generate-locators.sh 生成 locator-catalog.json"
+echo "  4. 运行 generate-poms.sh 生成 POM 类"