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

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 端到端流程