# Agentic QE Fleet

> 14 个专业 AI Agent 组成的自治质量工程舰队 — 从需求到测试用例的全流程自动化 + 质量门禁 + 知识沉淀

---

## 什么是 QE Fleet？

QE Fleet 是一个面向测试团队的 AI 驱动质量工程平台。它不是一个提示词集合，而是一条完整的自动化流水线：

```
需求文档 → 文档解析 → 知识激活 → 需求分析 → 冲突检测 → 风险评估
→ 测试策略 → 测试点 → 用例设计 → 测试数据构造 → 用例评审
→ 覆盖率审计 → 质量裁决 → Excel 导出 → 执行分析 → 知识沉淀
```

**14 个专业 Agent 各司其职**，按 5 个战区协同工作，每个 Agent 只做一件事并做到极致。

---

## 3 步上手

1. 把需求文档放进 `source_docs/requirements_raw/`，技术方案放进 `source_docs/technical_solutions/`
2. 确认 `knowledge_base/00_project/project_profile.md` 已按项目实际维护
3. 在 CLI 中输入：

```text
/qe-fleet run source_docs/requirements_raw/你的需求.docx
```

> `/case_generate` 保留为别名，行为完全一致。

---

## 适用入口

- **Claude CLI**: `.claude/skills/qe_fleet/SKILL.md`
- **Codex CLI**: 根目录 `AGENTS.md`

两边共用同一套 Agent、脚本和输出。

---

## 快速开始

### 运行前提

- Python `3.10+`
- `git`
- `pip`
- `requirements.txt` 中的依赖：`openpyxl`、`python-docx`、`pyantiword`

### 安装

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Windows PowerShell:
```powershell
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

### 执行

```text
/qe-fleet run source_docs/requirements_raw/新人礼需求.docx
```

Fleet 会自动完成从需求解析到 Excel 导出的全流程。

---

## 命令速查

| 命令 | 说明 |
|------|------|
| `/qe-fleet run <文档>` | 全流程自动化 |
| `/qe-fleet prepare <文档>` | 仅文档解析 + 知识激活 |
| `/qe-fleet analyze <文档>` | 准备 → 分析（含冲突检测 + 风险评估） |
| `/qe-fleet design <文档>` | 准备 → 分析 → 设计（含策略 + 用例 + 数据） |
| `/qe-fleet execute <文档>` | 自动化执行（Playwright PC + Appium 移动端 + 截图） |
| `/qe-fleet review <文档>` | 评审已有产物（含覆盖率审计 + 质量裁决） |
| `/qe-fleet export <文档>` | 仅 Excel 导出 + 版本快照 |
| `/qe-fleet monitor <文档> --results <结果>` | 执行分析 + 知识沉淀 |
| `/qe-fleet status <文档>` | 查看 Fleet 运行进度 |
| `/qe-fleet validate` | 验证所有 Agent 就绪 |
| `/case_generate <文档>` | `/qe-fleet run` 别名（向后兼容） |

---

## 17 Agent 舰队

| 战区 | Agent | 职责 |
|------|-------|------|
| **Prepare** | document-parser | 文档解析标准化 |
| | knowledge-activator | 知识智能激活 |
| **Analyze** | requirement-analyzer | 需求分析 |
| | conflict-detector | 冲突检测 |
| | risk-assessor | 风险评估 |
| **Design** | test-strategist | 测试策略 |
| | testpoint-designer | 测试点设计 |
| | case-designer | 用例设计 |
| | data-builder | 测试数据构造 |
| **Execute** | web-executor | PC Web Playwright 自动化 + 截图 |
| | mobile-executor | 移动端 Appium 自动化 + 截图 |
| | result-reporter | AI 视觉对比 + 测试结论 |
| **Review** | case-reviewer | 用例评审 |
| | coverage-auditor | 覆盖率审计 |
| | quality-gatekeeper | 质量门禁裁决 |
| **Monitor** | execution-analyst | 执行结果分析 |
| | knowledge-curator | 知识自动沉淀 |

---

## 固定输出

针对任意支持的需求输入，产物统一写到：

| 产物 | 路径 |
|------|------|
| 需求分析 | `output/analysis/{BASE_NAME}_分析.md` |
| 关联与冲突 | `output/analysis/{BASE_NAME}_关联与冲突.md` |
| 风险评估 | `output/analysis/{BASE_NAME}_风险评估.md` |
| 测试策略 | `output/analysis/{BASE_NAME}_测试策略.md` |
| 测试点 | `output/test_points/{BASE_NAME}_测试点.md` |
| 测试用例 | `output/test_cases/{BASE_NAME}_测试用例.md` |
| 测试数据 | `output/analysis/{BASE_NAME}_测试数据.md` |
| 执行脚本(Web) | `output/execution/{BASE_NAME}/playwright_tests.py` |
| 执行脚本(移动端) | `output/execution/{BASE_NAME}/appium_tests.py` |
| 执行报告(含截图) | `output/execution/{BASE_NAME}_执行报告.md` |
| 截图 | `output/screenshots/{BASE_NAME}/` |
| 评审报告 | `output/analysis/{BASE_NAME}_评审报告.md` |
| 覆盖率审计 | `output/analysis/{BASE_NAME}_覆盖率审计.md` |
| 质量裁决 | `output/analysis/{BASE_NAME}_质量裁决.md` |
| 执行分析 | `output/analysis/{BASE_NAME}_执行分析.md` |
| Excel | `output/excel_reports/{BASE_NAME}_测试用例.xlsx` |
| 版本快照 | `output/versions/{BASE_NAME}/v1/`（保留最近 `3` 个版本） |
| 版本索引 | `output/versions/{BASE_NAME}/VERSION_INDEX.md` |
| 统一清单 | `output/manifests/{BASE_NAME}.json` |

---

## 目录概览

```text
QaAutomationHub/
├── .claude/                      # Claude CLI 配置
├── AGENTS.md                     # Codex CLI 入口规则
├── agents/                       # 14 个专业 Agent prompts
│   ├── prepare/                  #   准备战区 (2)
│   ├── analyze/                  #   分析战区 (3)
│   ├── design/                   #   设计战区 (4)
│   ├── review/                   #   评审战区 (3)
│   └── monitor/                  #   监控战区 (2)
├── scripts/                      # 编排脚本
│   ├── fleet_runner.py           #   核心编排器
│   ├── fleet_manifest.py         #   Manifest 管理
│   ├── fleet_agents.py           #   Agent 加载器
│   ├── case_pipeline.py          #   向后兼容
│   └── export_excel.py           #   Excel 导出
├── knowledge_base/               # 长期知识资产
│   ├── 00_project/               #   项目画像
│   ├── 01_standards/             #   标准规范
│   ├── 02_history/               #   历史经验
│   └── 03_best_practices/        #   最佳实践
├── fleet_config.yml              # Fleet 全局配置
├── docs/                         # 文档
│   ├── USER_GUIDE.md             #   用户指南
│   ├── MAINTENANCE_GUIDE.md      #   维护指南
│   └── EXECUTE_SETUP_GUIDE.md    #   Execute 战区环境配置指南（PC/Android/iOS）
└── output/                       # 执行产物
```

---

## 核心规则

- 只使用 `knowledge_base/01_standards/test_case_template.md` 中定义的唯一表头
- 生成前必须读取项目画像、标准、历史缺陷、易漏场景、最佳实践
- 需求有歧义时必须显式标注 `> ⚠️ 待确认：问题、影响范围、建议确认方向`
- 预期结果必须同时覆盖 UI/接口反馈和数据状态变化
- P0 风险必须 100% 覆盖，质量裁决 BLOCKED 时不得导出
- 术语文件按需求内容自动识别生效范围，不相关的不纳入上下文
- 用例评审必须对照 `review_checklist.md` 逐项检查
- 冲突检测支持语义级分析，不只是文本相似

---

## 进一步阅读

- **用户指南**: [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — 怎么用
- **维护指南**: [docs/MAINTENANCE_GUIDE.md](docs/MAINTENANCE_GUIDE.md) — 怎么维护
- **Execute 环境配置**: [docs/EXECUTE_SETUP_GUIDE.md](docs/EXECUTE_SETUP_GUIDE.md) — PC/Android/iOS 环境搭建
- **设计文档**: [docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md](docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md) — 架构说明
- **Codex CLI 规则**: [AGENTS.md](AGENTS.md)
- **Fleet Skill**: [.claude/skills/qe_fleet/SKILL.md](.claude/skills/qe_fleet/SKILL.md)
