QaAutomationHub/docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md

# Agentic QE Fleet 集成设计

> 版本: 1.0 | 日期: 2026-07-09 | 状态: 已确认

## 1. 概述

将现有 QA Automation Hub（测试用例生成流水线）深度重构为 Agentic QE Fleet——一个由 14 个专业 AI Agent 组成的自治质量工程舰队，覆盖从需求输入到知识沉淀的全生命周期。

### 1.1 核心升级维度

| 维度 | 原项目 | QE Fleet |
|------|--------|----------|
| Agent 数量 | 4 | 14 |
| 战区划分 | 无 | 5 战区 (Prepare/Analyze/Design/Review/Monitor) |
| 编排方式 | skill 文件分散 | fleet_runner.py 集中编排 |
| 知识管理 | 静态手动维护 | 自动激活 + 自动回写沉淀 |
| 质量门禁 | 简单检查 | 三级裁决 (PASS/PASS_WITH_FIX/BLOCKED) |
| 覆盖率 | 无系统性追溯 | 需求→测试点→用例三级追溯 |
| 执行反馈 | 无 | Monitor 战区：结果分析 + 知识沉淀 |
| CLI 入口 | /case_generate | /qe-fleet + 子命令 |

### 1.2 设计原则

- **战区隔离**：每个战区独立运行，通过标准化 manifest JSON 交接
- **Agent 专职**：一个 Agent 只做一件事，文件短小精悍
- **确定性编排**：fleet_runner.py 编排 Agent 执行顺序，不依赖 LLM 自主决策流程
- **向后兼容**：保留 `/case_generate` 别名，保留 `case_pipeline.py` 接口
- **产出一致**：输出格式与原项目兼容，现有用户无缝迁移

---

## 2. 整体架构

```
                          /qe-fleet run <需求文档>
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────┐
│                    FLEET ORCHESTRATOR                        │
│                  scripts/fleet_runner.py                     │
│         读取 fleet_config.yml → 发令 → 收集 → 裁决 → 导出    │
└──────────────────────────────────────────────────────────────┘
         │              │              │              │
    ┌────▼────┐    ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
    │ PREPARE │    │ ANALYZE │    │ DESIGN  │    │ REVIEW  │
    │ 准备战区 │───▶│ 分析战区 │───▶│ 设计战区 │───▶│ 评审战区 │
    │ 2 Agent │    │ 3 Agent │    │ 4 Agent │    │ 3 Agent │
    └─────────┘    └─────────┘    └─────────┘    └─────────┘
                                                        │
                                              ┌────▼────┐
                                              │ MONITOR │
                                              │ 监控战区 │
                                              │ 2 Agent │
                                              └─────────┘
```

### 2.1 14 个专业 Agent

| # | 战区 | Agent ID | 名称 | 核心职责 |
|---|------|----------|------|----------|
| 1 | Prepare | `document-parser` | 文档解析专家 | docx/pdf/doc → MD 标准化 + 技术方案识别 |
| 2 | Prepare | `knowledge-activator` | 知识激活专家 | 按需求自动激活术语/规则/历史缺陷/最佳实践 |
| 3 | Analyze | `requirement-analyzer` | 需求分析专家 | 结构化需求模型 + 歧义标注 |
| 4 | Analyze | `conflict-detector` | 冲突检测专家 | 语义级历史需求冲突检测 |
| 5 | Analyze | `risk-assessor` | 风险评估专家 | 风险矩阵量化 (资损/可用性/数据/合规/兼容性) |
| 6 | Design | `test-strategist` | 测试策略师 | 分层测试策略 + 优先级矩阵 |
| 7 | Design | `testpoint-designer` | 测试点设计师 | 全面测试点矩阵 + 来源标注 |
| 8 | Design | `case-designer` | 用例设计师 | 可执行用例 + 双验证预期结果 |
| 9 | Design | `data-builder` | 数据构造师 | 精确测试数据集 |
| 10 | Review | `case-reviewer` | 用例评审师 | 用例质量/规范性/可执行性评审 |
| 11 | Review | `coverage-auditor` | 覆盖率审计师 | 需求→测试点→用例三级追溯覆盖 |
| 12 | Review | `quality-gatekeeper` | 质量门禁裁决官 | 三级裁决 (PASS/PASS_WITH_FIX/BLOCKED) |
| 13 | Monitor | `execution-analyst` | 执行结果分析师 | 失败归类 + 失败模式识别 + 根因推测 |
| 14 | Monitor | `knowledge-curator` | 知识沉淀师 | 自动回写知识库 + 去重保护 |

### 2.2 战区数据流

```
Prepare → manifest_prepare.json   (标准化需求路径、激活的知识库清单、文档置信度)
Analyze → manifest_analyze.json   (结构化需求、冲突列表、风险矩阵)
Design  → manifest_design.json    (测试策略、测试点、用例路径、测试数据路径)
Review  → manifest_review.json    (评审结论、覆盖率报告、门禁裁决)
Monitor ← 外部测试执行结果        (失败分析、知识回写建议)
```

---

## 3. 战区详细设计

### 3.1 Prepare 战区

**触发**: `/qe-fleet prepare <需求文档>`

**document-parser**:
- 输入: 原始需求文档 (.docx/.doc/.pdf/.md)
- 处理: 解析 → 提取文本 → 标准化 Markdown
- 自动识别同主题技术方案 (文件名 + 内容相似度匹配)
- 标注解析置信度
- 产出: `output/normalized_inputs/{BASE_NAME}/requirement.md`

**knowledge-activator**:
- 输入: 标准化需求 + 项目画像
- 激活策略:
  - 常驻: `terminology.md` (核心术语)、`test_case_template.md`、`definition_of_done.md`、`review_checklist.md`
  - 关键词匹配: 可选术语文件 (如 saas 术语)
  - 语义匹配: 历史缺陷、最佳实践中与需求相关的条目
- 激活结果记录在 manifest 中，附带激活理由
- 自动检测知识缺口并建议补充

### 3.2 Analyze 战区

**触发**: `/qe-fleet analyze <需求文档>`

**requirement-analyzer**:
- 结构化输出: 背景与目标 / 范围与边界 / 用户角色 / 关键业务规则 / 主流程 / 异常流程 / 技术约束
- 项目画像差异化: 将通用约束替换为项目特定约束
- 歧义标注: `> ⚠️ 待确认：问题、影响范围、建议确认方向`

**conflict-detector**:
- 对比范围: 所有历史需求 (requirements/ + source_docs/)
- 冲突类型: 规则方向冲突 / 数值口径冲突 / 状态机冲突 / 权限冲突
- 语义级检测: 结合术语解释判断规则语义是否真正矛盾 (不只看 n-gram)
- 严重度分级: P0(高风险)/P1(中风险)/P2(低风险)/P3(提示)

**risk-assessor** (新增):
- 风险维度: 资损 / 可用性 / 数据 / 合规 / 兼容性
- 量化矩阵: 可能性(1-5) × 影响度(1-5) = 风险等级
- 高风险项自动映射为 P0 必测项

**Agent 协作**: analyzer 和 detector 可并行运行，risk-assessor 串行消费两者输出。

### 3.3 Design 战区

**触发**: `/qe-fleet design <需求文档>`

**test-strategist** (新增):
- 输入: 风险矩阵 + 需求分析
- 输出: 测试金字塔分配 / 优先级覆盖规则 / P0 清单

**testpoint-designer**:
- 输入: 策略 + 分析 + 冲突 + 历史缺陷 + 易漏场景 + 最佳实践
- 覆盖维度: 主流程/异常/边界/状态流转/权限/并发幂等/弱网超时/历史缺陷防御/跨需求冲突防御
- 来源标注: `[需求]` `[历史缺陷]` `[风险矩阵]` `[冲突修订]` `[项目画像]` `[漏测清单]`

**case-designer**:
- 将测试点转化为可执行用例，严格使用 template 表头
- 用例原子性: 一个用例一个验证点
- 预期结果双验证: UI反馈 + 数据状态
- 中后台页面: 补齐列表/按钮/只读态/状态权限映射/端间隔离
- 保存前按 review_checklist 自检

**data-builder** (新增):
- 为用例构造精确测试数据: 账号/金额/商品ID/券码/状态枚举/边界值
- 数据来源: 项目画像字段 + 术语枚举 + 需求具体数值
- 输出: `{BASE_NAME}_测试数据.md`

**执行顺序**: strategist → testpoint + data 并行 → case (消费 testpoint 和数据)

### 3.4 Review 战区

**触发**: `/qe-fleet review <需求文档>`

**case-reviewer**: 按 checklist 逐项检查，错误分级 (阻断/建议/优化)，标注到具体行号。

**coverage-auditor** (新增): 需求→测试点→用例三级追溯矩阵，识别覆盖缺口和过度覆盖。

**quality-gatekeeper** (新增):
- 三级裁决: PASS / PASS_WITH_FIX / BLOCKED
- 裁决依据: 评审阻断项 + 覆盖率数据 + 风险矩阵
- BLOCKED 时必须告知原因和解决路径

**并行策略**: reviewer 和 auditor 并行，gatekeeper 等待两者完成。

### 3.5 Monitor 战区

**触发**: `/qe-fleet monitor <测试结果文件>` 或 CI webhook

**execution-analyst**:
- 支持格式: JUnit XML / JSON / 结构化 Markdown
- 失败归类: ENV_ISSUE / DATA_ISSUE / CASE_BUG / REAL_BUG
- 失败模式识别: 同一模式≥3次 → 标记为系统性问题
- 根因推测 + 回归建议

**knowledge-curator**:
- 自动回写: REAL_BUG → historical_defects / 新漏测模式 → common_missed_scenes / 高质量用例 → best_practices
- 去重保护: Jaccard 相似度 + LLM 语义去重
- 安全策略: P0 确认缺陷可配置自动生效，P1-P3 默认人工确认
- 输出: 变更 diff + 建议说明

---

## 4. CLI 设计

### 4.1 命令体系

```
/qe-fleet run <需求文档>          # 全流程
/qe-fleet prepare <需求文档>      # 仅准备
/qe-fleet analyze <需求文档>      # 准备+分析
/qe-fleet design <需求文档>       # 准备→分析→设计
/qe-fleet review <需求文档>       # 仅评审已有产物
/qe-fleet export <需求文档>       # 仅 Excel 导出
/qe-fleet monitor <测试结果>      # 执行分析+知识沉淀
/qe-fleet status <需求文档>       # 进度和产物状态
/qe-fleet knowledge sync          # 知识库健康检查
/qe-fleet knowledge gaps          # 知识库覆盖缺口报告
```

兼容: `/case_generate` = `/qe-fleet run` 别名

### 4.2 自动执行规则 (CLI)

Agent 收到 `/qe-fleet run` 后必须自动完成:

1. 解析需求文档路径，提取 BASE_NAME
2. 执行 `python3 scripts/fleet_runner.py run --requirement <路径>`
3. 按战区顺序执行，读取各阶段 manifest 状态
4. 检查 confirmation_gate，必要时阻断并告知
5. 最终汇总: 成功/失败、产物路径、质量裁决

---

## 5. 目录结构

```
QaAutomationHub/
├── .claude/
│   ├── skills/qe_fleet/SKILL.md       # Fleet skill 定义
│   └── commands/qe_fleet.md           # 子命令分发
├── AGENTS.md                          # Codex CLI 入口
├── agents/
│   ├── prepare/                       # 准备战区 (2 Agent)
│   │   ├── document_parser.md
│   │   └── knowledge_activator.md
│   ├── analyze/                       # 分析战区 (3 Agent)
│   │   ├── requirement_analyzer.md
│   │   ├── conflict_detector.md
│   │   └── risk_assessor.md
│   ├── design/                        # 设计战区 (4 Agent)
│   │   ├── test_strategist.md
│   │   ├── testpoint_designer.md
│   │   ├── case_designer.md
│   │   └── data_builder.md
│   ├── review/                        # 评审战区 (3 Agent)
│   │   ├── case_reviewer.md
│   │   ├── coverage_auditor.md
│   │   └── quality_gatekeeper.md
│   └── monitor/                       # 监控战区 (2 Agent)
│       ├── execution_analyst.md
│       └── knowledge_curator.md
├── scripts/
│   ├── fleet_runner.py                # 核心编排器
│   ├── fleet_manifest.py              # Manifest 管理
│   ├── fleet_agents.py                # Agent 加载和上下文注入
│   ├── case_pipeline.py               # 向后兼容
│   ├── export_excel.py                # Excel 导出
│   └── governance_audit.py            # 治理审计
├── knowledge_base/                    # 保持现有结构
├── knowledge_gaps/                    # 知识缺口追踪
├── fleet_config.yml                   # Fleet 全局配置
├── output/                            # 输出产物
├── docs/
│   ├── USER_GUIDE.md                  # 用户指南
│   └── MAINTENANCE_GUIDE.md           # 维护指南
└── README.md                          # 项目入口文档
```

---

## 6. 配置文件

### fleet_config.yml

```yaml
fleet:
  name: "QE Fleet"
  version: "2.0.0"

battle_zones:
  prepare: { enabled: true, auto_confirm: false }
  analyze: { enabled: true, auto_confirm: false }
  design:  { enabled: true, auto_confirm: false }
  review:  { enabled: true, auto_confirm: false }
  monitor: { enabled: true, auto_confirm: true }

quality_gate:
  min_coverage: 0.95
  max_blockers: 0
  require_data_builder: true
  require_risk_assessment: true

monitor:
  auto_curate_p0: true
  auto_curate_p1_p3: false
  supported_formats: [junit, json, markdown]

output:
  excel_format: yunxiao
  snapshot_keep: 3
  auto_sync_maintained: true
```

---

## 7. 关键技术决策

| 决策点 | 选项 | 理由 |
|--------|------|------|
| 编排方式 | Python (fleet_runner.py) | 确定性、可调试、可度量 |
| Agent 通信 | 文件 + manifest JSON | 战区隔离、故障域清晰、可回溯 |
| CLI 入口 | Claude CLI + Codex CLI | 与现有基础设施一致、零额外部署 |
| 知识激活 | 关键词 + 语义匹配 | 精确匹配保底、语义扩展覆盖 |
| 冲突检测 | n-gram + 术语语义 | 提升检测精度，减少误报 |
| 质量门禁 | 三级裁决 | 允许自动修复，精准阻断高危项 |
| 知识沉淀 | 自动建议 + 人工确认 | P0 紧急可控、P1-P3 质量把关 |
| Excel 导出 | 保持云效格式 | 向后兼容现有平台 |
| 版本快照 | 保持固定文件名 + versions/ | 向后兼容、日常无感知 |

---

## 8. 与原项目兼容性

- `/case_generate` 保留为 `/qe-fleet run` 别名
- `case_pipeline.py` 的 prepare/verify/export 接口保留
- 输出文件命名规则不变 (固定文件名 + versions/ 快照)
- knowledge_base 目录结构不变 (monitor 追加不修改)
- Excel 导出格式保持云效字段模型
- 向下兼容: 仅用原 4 Agent 也可工作

---

## 9. 实现范围

### Phase 1: 核心重构
- [ ] 创建新目录结构
- [ ] 编写 fleet_config.yml
- [ ] 实现 fleet_runner.py (编排器)
- [ ] 实现 fleet_manifest.py (manifest 管理)
- [ ] 实现 fleet_agents.py (Agent 加载)
- [ ] 升级 .claude/ skill 和 command
- [ ] 升级 AGENTS.md

### Phase 2: Agent 迁移+新增
- [ ] 迁移 + 升级 Prepare 战区 Agent (2→2)
- [ ] 迁移 + 升级 Analyze 战区 Agent (1→3)
- [ ] 迁移 + 升级 Design 战区 Agent (1→4)
- [ ] 迁移 + 升级 Review 战区 Agent (1→3)
- [ ] 新建 Monitor 战区 Agent (0→2)

### Phase 3: 文档
- [ ] USER_GUIDE.md
- [ ] MAINTENANCE_GUIDE.md
- [ ] README.md 重写

### Phase 4: 推送部署
- [ ] Git 仓库初始化 + 推送
- [ ] 验证 /qe-fleet run 端到端流程