---
name: qe-fleet
description: Agentic QE Fleet — 混合流水线：Python 脚手架 + AI Agent 内容生成
metadata:
  short-description: 多 Agent QE Fleet：从需求到测试用例的全流程自动化 + 质量门禁 + 知识沉淀
---

# Agentic QE Fleet（混合流水线 v3.0）

当用户输入以下任一意图时使用本 skill：

- `/qe-fleet run <需求文档>`
- `/qe-fleet prepare <需求文档>`
- `/qe-fleet analyze <需求文档>`
- `/qe-fleet design <需求文档>`
- `/qe-fleet review <需求文档>`
- `/qe-fleet export <需求文档>`
- `/qe-fleet monitor <需求文档> --results <测试结果>`
- `/qe-fleet status <需求文档>`
- `/case_generate <需求文档>`（向后兼容别名）

## 架构概述

本流水线采用**混合架构**：

- **Python 脚本（fleet_runner.py）**: 处理确定性工作——文档解析、知识激活、需求分析、冲突检测、风险矩阵、测试策略模板、测试数据模板、Playwright/Appium 脚本骨架、清单管理
- **Claude Code Agent（本 Skill）**: 处理生成式 AI 工作——测试点设计、测试用例编写、用例评审、覆盖率审计、质量裁决

## `/qe-fleet run` — 全流程自动执行

收到此命令后，按以下 6 个阶段自动执行，不要停在说明阶段：

### Phase 1: SCAFFOLD（脚手架生成）

```bash
python scripts/fleet_runner.py run --scaffold-only --requirement <需求文档路径>
```

产出：
- 标准化需求文档（含附加文件检测 + 多源注册表）
- 知识激活 + 缺口检测
- 需求分析 + 冲突检测 + 风险矩阵
- 测试策略模板 + 测试数据模板
- Playwright/Appium 脚本骨架
- 所有战区 manifest（含 `pending_ai` 标记）

### Phase 2: GATE-CHECK（门禁检查）

读取 `output/manifests/{BASE_NAME}_analyze.json`：
- 若 `confirmation_gate.required=true` 且 `decision_status` 不是 `confirmed` 或 `not_required`：
  - 🛑 阻断并告知用户：确认单路径、阻断原因
  - 不得继续执行后续阶段
- 若门禁通过或无门禁要求，继续 Phase 3

### Phase 3: AI-DESIGN（AI 生成设计产物）

按依赖顺序调用 AI Agent 填充设计产物。**重要**：若目标文件已存在且内容非空（>500 字符），跳过该 Agent 并告知用户可手动重新生成。

#### 3a: data-builder + testpoint-designer（可并行）

**Agent: data-builder**
- 输入文件：`output/analysis/{BASE_NAME}_分析.md`、`{PROJECT_PROFILE}`、来自 prepare manifest 的 `sources_registry` 中所有 `role=api_spec` 的附加文件
- Agent prompt：`agents/design/data_builder.md`
- 输出：`output/analysis/{BASE_NAME}_测试数据.md`（覆盖模板）
- 验证：文件存在且 >300 字符
- 调用方式：使用 Agent 工具，subagent_type=general-purpose，在 prompt 中指明输入文件和输出文件

**Agent: testpoint-designer**
- 输入文件：`output/analysis/{BASE_NAME}_分析.md`、`output/analysis/{BASE_NAME}_风险评估.md`、`output/analysis/{BASE_NAME}_测试策略.md`、`output/analysis/{BASE_NAME}_关联与冲突.md`、`{PROJECT_PROFILE}`、`knowledge_base/02_history/common_missed_scenes.md`、`knowledge_base/02_history/historical_defects.md`、`knowledge_base/01_standards/definition_of_done.md`、prepare manifest 中 `sources_registry` 的所有附加文件
- Agent prompt：`agents/design/testpoint_designer.md`
- 输出：`output/test_points/{BASE_NAME}_测试点.md`
- 验证：文件存在且 >500 字符，含有 `TP-` 标识符
- 调用方式：使用 Agent 工具，subagent_type=general-purpose

#### 3b: case-designer（依赖 3a 完成）

- 输入文件：`output/test_points/{BASE_NAME}_测试点.md`（3a 产出）、`output/analysis/{BASE_NAME}_测试数据.md`、`knowledge_base/01_standards/test_case_template.md`、`knowledge_base/01_standards/review_checklist.md`、`knowledge_base/03_best_practices/`
- Agent prompt：`agents/design/case_designer.md`
- 输出：`output/test_cases/{BASE_NAME}_测试用例.md`
- 验证：文件存在且 >500 字符，含 Markdown 表格，表头与 `test_case_template.md` 一致
- 调用方式：使用 Agent 工具

### Phase 4: AI-REVIEW（AI 评审）

#### 4a: case-reviewer + coverage-auditor（可并行）

**Agent: case-reviewer**
- 输入文件：`output/test_cases/{BASE_NAME}_测试用例.md`、`knowledge_base/01_standards/review_checklist.md`、`knowledge_base/01_standards/test_case_template.md`、`knowledge_base/01_standards/definition_of_done.md`、`output/analysis/{BASE_NAME}_风险评估.md`
- Agent prompt：`agents/review/case_reviewer.md`
- 输出：`output/analysis/{BASE_NAME}_评审报告.md`
- 验证：文件存在且 >500 字符，含阻断项/建议项计数

**Agent: coverage-auditor**
- 输入文件：`output/analysis/{BASE_NAME}_分析.md`、`output/test_points/{BASE_NAME}_测试点.md`、`output/test_cases/{BASE_NAME}_测试用例.md`、`output/analysis/{BASE_NAME}_风险评估.md`
- Agent prompt：`agents/review/coverage_auditor.md`
- 输出：`output/analysis/{BASE_NAME}_覆盖率审计.md`
- 验证：文件存在且 >500 字符

#### 4b: quality-gatekeeper（依赖 4a 完成）

- 输入文件：`output/analysis/{BASE_NAME}_评审报告.md`、`output/analysis/{BASE_NAME}_覆盖率审计.md`、`output/analysis/{BASE_NAME}_风险评估.md`、`fleet_config.yml`
- Agent prompt：`agents/review/quality_gatekeeper.md`
- 输出：`output/analysis/{BASE_NAME}_质量裁决.md`
- 验证：文件含 `PASS`、`PASS_WITH_FIX` 或 `BLOCKED`

### Phase 5: VERDICT（裁决 + 导出）

读取 `output/analysis/{BASE_NAME}_质量裁决.md` 中的裁决结果：

- **PASS** 或 **PASS_WITH_FIX**: 执行导出
  ```bash
  python scripts/fleet_runner.py export --requirement <需求文档路径>
  ```
  （若已有 review 战区的阻断项或覆盖缺口，在导出前先修复用例文件，参考 Phase 4 的评审报告）
- **BLOCKED**: 🛑 告知用户阻断原因，提供修复方向，不导出 Excel

### Phase 6: REPORT（汇总反馈）

输出最终状态汇总：

```
🏁 QE Fleet 运行完成
   ✅ prepare: 完成 (置信度 0.95, 附加文件 N 个)
   ✅ analyze: 完成 (风险 P0=N, P1=N)
   ✅ design: 完成 (测试点 N, 用例 N)
   ✅ execute: 完成 (Playwright + Appium 脚本)
   ✅ review: 完成 (裁决: PASS/PASS_WITH_FIX/BLOCKED)
   ✅ export: 完成/N/A

产物:
   📊 Excel: output/excel_reports/{BASE_NAME}_测试用例.xlsx
   🧠 XMind: output/xmind_reports/{BASE_NAME}.xmind
   📋 测试点: output/test_points/{BASE_NAME}_测试点.md (N个)
   📝 测试用例: output/test_cases/{BASE_NAME}_测试用例.md (N条)
   ✅ 质量裁决: output/analysis/{BASE_NAME}_质量裁决.md
```

---

## 其他命令

### `/qe-fleet prepare <需求文档>`
```bash
python scripts/fleet_runner.py prepare --requirement <需求文档路径>
```

### `/qe-fleet analyze <需求文档>`
```bash
python scripts/fleet_runner.py analyze --requirement <需求文档路径>
```

### `/qe-fleet design <需求文档>`
仅执行 Phase 3（AI-DESIGN），前提是 prepare 和 analyze 已完成。
若 manifest 未就绪，先执行对应的脚手架命令。

### `/qe-fleet review <需求文档>`
仅执行 Phase 4（AI-REVIEW），前提是设计产物已存在。

### `/qe-fleet export <需求文档>`
```bash
python scripts/fleet_runner.py export --requirement <需求文档路径>
```

### `/qe-fleet monitor <需求文档> --results <测试结果>`
```bash
python scripts/fleet_runner.py monitor --requirement <需求文档路径> --results <测试结果文件>
```

### `/qe-fleet status <需求文档>`
```bash
python scripts/fleet_runner.py status --requirement <需求文档路径>
```

---

## AI Agent 调用模板

每次调用 AI Agent 时，使用以下模板构造 prompt：

```
你是 {agent_name}。{从 agent prompt 文件读取的 role 描述}。

# 任务
{从 agent prompt 文件读取的 task 描述}

# 关键输入文件（必须读取）
{列出所有输入文件路径}

# 输出文件
写入: {output_file_path}

# 输出格式
{从 agent prompt 文件读取的 output format}

# 约束
{从 agent prompt 文件读取的 constraints}

# 附加上下文
- 项目画像: {PROJECT_PROFILE}
- 附加源文件（如有，来自 prepare manifest sources_registry）
```

---

## 约束

- 除非脚本执行失败，不要要求用户手动执行中间命令
- 确认门禁未解除时，必须阻断并告知原因和解决路径
- 质量裁决 BLOCKED 时，不得导出 Excel
- 若主输入是 .docx/.doc/.pdf，必须基于 prepare 产出的标准化 Markdown
- 若 manifest 中有附加源文件（`sources_registry`），必须纳入 AI Agent 的输入文件列表
- 需求有歧义时必须显式标注 `> ⚠️ 待确认：问题、影响范围、建议确认方向`
- 基于项目画像差异化，避免通用化输出
- 历史缺陷和易漏场景必须显式体现在测试点或用例中
- 预期结果必须同时覆盖 UI 反馈和数据状态变化
- 所有 bash 命令使用 `python`（非 `python3`）
- 若改动涉及 scripts/、.claude/、agents/、AGENTS.md、README.md，必须执行 `python scripts/governance_audit.py auto`

## 兼容性

`/case_generate` 保留为 `/qe-fleet run` 的别名，行为完全一致。
