xst/Yb-QaAutomationHub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Agentic QE Fleet v2.0.0 - 14-agent quality engineering platform

Browse Source 
- 14 specialized AI agents across 5 battle zones (Prepare/Analyze/Design/Review/Monitor)
- New: risk-assessor, test-strategist, data-builder, coverage-auditor, quality-gatekeeper, execution-analyst, knowledge-curator
- New: fleet_runner.py orchestrator with multi-zone manifest pipeline
- New: fleet_config.yml for centralized configuration
- New: knowledge activation system (keyword + semantic matching)
- New: semantic conflict detection with severity grading (P0-P3)
- New: three-tier quality gate (PASS/PASS_WITH_FIX/BLOCKED)
- New: monitor zone for test execution analysis and auto knowledge curation
- Backward compatible: /case_generate alias, case_pipeline.py preserved
- Comprehensive docs: USER_GUIDE.md + MAINTENANCE_GUIDE.md
This commit is contained in:
xst
2026-07-09 14:29:11 +08:00
commit b2a035c4f9
79 changed files with 9905 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MAINTENANCE_GUIDE.md
+438
View File
@@ -0,0 +1,438 @@
# Agentic QE Fleet 维护指南
> 版本: 2.0.0 | 最后更新: 2026-07-09 | 面向: 仓库维护者
## 目录
1. [架构概览](#1-架构概览)
2. [目录职责速查](#2-目录职责速查)
3. [日常维护任务](#3-日常维护任务)
4. [Agent 管理](#4-agent-管理)
5. [知识库维护](#5-知识库维护)
6. [配置调优](#6-配置调优)
7. [故障排查](#7-故障排查)
8. [版本升级](#8-版本升级)
---
## 1. 架构概览
### 1.1 战区执行顺序
```
PREPARE ──→ ANALYZE ──→ DESIGN ──→ REVIEW ──→ MONITOR
│ │ │ │ │
│ │ │ │ └── 异步触发（测试执行后）
│ │ │ └── quality-gatekeeper 裁决
│ │ └── 4 Agent (strategy + testpoints + cases + data)
│ └── 3 Agent (analysis + conflicts + risk)
└── 2 Agent (parse + knowledge activate)
```
### 1.2 数据流
```python
# 每个战区产出独立 manifest，下一战区消费
manifest_prepare.json → 标准化路径、激活知识清单
manifest_analyze.json → 需求分析、冲突、风险矩阵、确认门禁
manifest_design.json → 策略、测试点、用例、数据路径
manifest_review.json → 评审、覆盖率、质量裁决
manifest_monitor.json → 执行分析、知识沉淀建议
```
### 1.3 关键文件
| 文件 | 职责 | 改动频率 |
|------|------|----------|
| `fleet_config.yml` | 全局配置（开关、阈值、策略） | 低频 |
| `fleet_runner.py` | 核心编排器 | 低频 |
| `fleet_manifest.py` | Manifest 读写 | 低频 |
| `fleet_agents.py` | Agent 注册表和加载 | 新增 Agent 时 |
| `agents/*/*.md` | 14 个 Agent 的行为定义 | 调优 prompt 时 |
| `knowledge_base/` | 领域知识 | 持续维护 |
| `case_pipeline.py` | 向后兼容的流水线脚本 | 低频 |
---
## 2. 目录职责速查
```
QaAutomationHub/
├── agents/ # 🔧 Agent 行为定义（14 个 prompt 文件）
│ ├── 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 # 向后兼容的 prepare/verify/export
│ ├── export_excel.py # Markdown → Excel
│ └── governance_audit.py # 治理审计
├── knowledge_base/ # 📚 长期资产（持续投入维护）
│ ├── 00_project/ # 项目画像
│ ├── 01_standards/ # 标准规范
│ ├── 02_history/ # 历史经验
│ └── 03_best_practices/ # 最佳实践
├── knowledge_gaps/ # 📝 知识缺口追踪
├── decisions/ # 📋 跨需求冲突确认单
├── source_docs/ # 📄 原始输入文档
├── requirements/ # 📄 正式维护版需求
├── output/ # 📊 执行产物（不作为长期资产）
├── fleet_config.yml # ⚙️ 全局配置
├── docs/ # 📖 文档
└── .claude/ # 🔧 CLI 入口
```
### 资产 vs 产物
**长期资产**（需要持续投入维护）:
- `knowledge_base/` — 决定 Fleet 质量的源头
- `agents/` — Agent 行为定义
- `fleet_config.yml` — 全局配置
- `scripts/` — 编排脚本
- `decisions/` — 冲突确认结论
**执行产物**（每次运行产生，不做长期维护）:
- `output/analysis/`
- `output/test_points/`
- `output/test_cases/`
- `output/excel_reports/`
- `output/manifests/`
- `output/versions/`
---
## 3. 日常维护任务
### 3.1 新增需求时
```bash
# 1. 放置需求文档
cp 新需求.docx source_docs/requirements_raw/
# 2. 放置配套技术方案（若有）
cp 技术方案.docx source_docs/technical_solutions/
# 3. 运行 Fleet
/qe-fleet run source_docs/requirements_raw/新需求.docx
# 4. 如果触发确认门禁 → 创建确认单 → 确认后重新运行
```
### 3.2 线上事故后
**必须做的事**（每次事故至少做一项）:
```markdown
1. 编辑 knowledge_base/02_history/historical_defects.md
添加条目：
### {缺陷标题}
- 模块: xxx
- 现象: xxx
- 根因: xxx
- 防御建议: xxx
- 发现日期: 2026-07-09
- 严重度: P0/P1/P2
2. 如果是通用漏测模式，编辑 common_missed_scenes.md
添加条目：
### {漏测场景}
- 场景描述: xxx
- 为什么容易漏测: xxx
- 应该在哪个阶段发现: xxx
- 预防措施: xxx
```
### 3.3 发现高质量用例时
将优秀用例加入 `knowledge_base/03_best_practices/`，作为后续生成的范例。
### 3.4 知识库健康检查
```bash
# 检查知识库覆盖缺口
/qe-fleet knowledge gaps
# 同步和去重
/qe-fleet knowledge sync
```
---
## 4. Agent 管理
### 4.1 新增 Agent
1. 在 `agents/<zone>/` 下创建 prompt 文件
2. 在 `fleet_agents.py` 的 `AGENT_REGISTRY` 中注册：
```python
"new-agent-id": {
"zone": "design", # 所属战区
"path": "design/new_agent.md",
"name": "新 Agent 名称",
"description": "一句话描述",
}
```
3. 在对应战区的 `fleet_runner.py` 处理函数中加入该 Agent 的调用逻辑
4. 运行验证：
```bash
python3 scripts/fleet_runner.py validate
```
### 4.2 修改 Agent 行为
Agent 行为完全由 prompt 文件定义。修改步骤：
1. 编辑 `agents/<zone>/<agent_name>.md`
2. 修改 Role/Task/Constraints 部分
3. 用真实需求测试效果
**调优原则**:
- 先改知识库（源头），再改 prompt（行为），最后改脚本（流程）
- 每次只改一个 Agent，对比前后效果
- 保留旧 prompt 备份（`_v1_backup.md`）
### 4.3 Agent 注册表
| Agent ID | 战区 | 文件 |
|----------|------|------|
| `document-parser` | prepare | `agents/prepare/document_parser.md` |
| `knowledge-activator` | prepare | `agents/prepare/knowledge_activator.md` |
| `requirement-analyzer` | analyze | `agents/analyze/requirement_analyzer.md` |
| `conflict-detector` | analyze | `agents/analyze/conflict_detector.md` |
| `risk-assessor` | analyze | `agents/analyze/risk_assessor.md` |
| `test-strategist` | design | `agents/design/test_strategist.md` |
| `testpoint-designer` | design | `agents/design/testpoint_designer.md` |
| `case-designer` | design | `agents/design/case_designer.md` |
| `data-builder` | design | `agents/design/data_builder.md` |
| `case-reviewer` | review | `agents/review/case_reviewer.md` |
| `coverage-auditor` | review | `agents/review/coverage_auditor.md` |
| `quality-gatekeeper` | review | `agents/review/quality_gatekeeper.md` |
| `execution-analyst` | monitor | `agents/monitor/execution_analyst.md` |
| `knowledge-curator` | monitor | `agents/monitor/knowledge_curator.md` |
---
## 5. 知识库维护
### 5.1 项目画像（必维护）
`knowledge_base/00_project/project_profile.md` 是 Fleet 生成质量的根基。至少填写：
- 项目名称、类型、目标用户
- 核心业务域
- 业务边界与禁用能力
- 项目特有高风险规则
- 技术依赖和关键系统
**不维护的后果**: Fleet 输出退化为通用模板，没有项目针对性。
### 5.2 术语文件
- `terminology.md` — 核心商城术语，**常驻激活**，始终生效
- `terminology_optional_saas.md` — 私域/分销/储值术语，**按需激活**
新增术语的原则：
- 通用术语放 `terminology.md`
- 特定业务线术语单独拆文件，由 Fleet 自动识别是否激活
- 每个术语包含：中文名、英文名、定义、适用范围、关联术语
### 5.3 历史缺陷
格式规范（每条缺陷应包含）：
```markdown
### {缺陷标题}
- 模块: xxx
- 现象: 具体可观测的异常行为
- 根因: 为什么发生
- 影响: 用户/数据/资金的直接影响
- 防御建议: 测试中应如何覆盖
- 发现日期: YYYY-MM-DD
- 严重度: P0/P1/P2
```
### 5.4 最佳实践
格式规范（每个案例应包含）：
```markdown
### {案例标题}
- 适用场景: 什么类型的需求可以参考
- 用例编号: TC-XXX
- 亮点: 为什么这个用例写得好（颗粒度/数据/预期结果）
- 用例内容: （表格或引用）
```
### 5.5 知识库膨胀控制
- 一个文件只讲一类东西
- 出现 30-50 条以上同类内容时，按模块拆分
- 每季度做一次去重重审
- 删除已过时或不再适用的条目（不要怕删）
---
## 6. 配置调优
### 6.1 fleet_config.yml 关键参数
```yaml
# 质量门禁严格度（0-1）
quality_gate:
min_coverage: 0.95 # 调低 → 更容易 PASS；调高 → 更严格
max_blockers: 0 # 允许的阻断项上限
# 知识沉淀自动策略
monitor:
auto_curate_p0: true # P0 缺陷自动沉淀（推荐开启）
auto_curate_p1_p3: false # P1-P3 人工确认（推荐保持关闭）
# 冲突检测阈值
conflict_detection:
related_similarity_threshold: 0.015 # 关联需求阈值
conflict_similarity_threshold: 0.22 # 冲突判定阈值
semantic_conflict_detection: true # 语义级检测（推荐开启）
# 版本管理
output:
snapshot_keep: 3 # 每个需求保留的版本快照数
```
### 6.2 战区开关
```yaml
battle_zones:
monitor:
enabled: false # 暂时不需要 Monitor → 关闭
```
### 6.3 调试模式
编辑 `fleet_config.yml`，临时调整：
```yaml
battle_zones:
analyze:
auto_confirm: true # 跳过确认门禁（仅调试用）
```
---
## 7. 故障排查
### 7.1 问题：Agent prompt 找不到
**症状**: `FileNotFoundError: Agent prompt 不存在`
**排查**:
```bash
# 验证所有 Agent 就绪
python3 scripts/fleet_runner.py validate
```
### 7.2 问题：确认门禁阻断
**症状**: `🛑 确认门禁未通过，暂停在 ANALYZE 战区`
**解决**:
1. 查看关联与冲突报告
2. 在 `decisions/` 下创建确认单
3. 确认状态写 `确认状态：已确认`
4. 重新运行 `/qe-fleet run`
### 7.3 问题：质量裁决 BLOCKED
**症状**: `🛑 质量裁决 BLOCKED，跳过导出`
**解决**:
1. 查看 `output/analysis/{需求名}_质量裁决.md`
2. 解决阻断项（参考评审报告中的修复建议）
3. 重新运行设计战区: `/qe-fleet design`
### 7.4 问题：文档解析失败
**症状**: `> ⚠️ 待确认：PDF 未提取到可用文本`
**原因**: 扫描件/图片型 PDF，文本层缺失
**解决**:
- 优先使用 `.docx` 格式
- 或手动将 PDF 内容转录为 Markdown 放到 `requirements/`
### 7.5 问题：生成质量不理想
**排查顺序**（不改产物，先查源头）:
1. 需求文档是否写清楚？（背景/目标/规则/边界/异常）
2. 项目画像是否维护？（业务边界、高风险规则、技术约束）
3. 知识库是否缺内容？（历史缺陷、易漏场景、最佳实践、术语定义）
4. Agent prompt 是否需要调优？（某个 Agent 的行为约束不够）
5. 最后才考虑手工修改产物
---
## 8. 版本升级
### 8.1 从 v1 (qa-automation-hub) 升级到 v2 (Agentic QE Fleet)
v1 产物完全兼容 v2，无需迁移：
- v1 的 `/case_generate` = v2 的 `/qe-fleet run`
- v1 的 `case_pipeline.py` 所有命令仍然可用
- v1 的 `output/` 产物命名规则不变
- v1 的 `knowledge_base/` 目录结构不变
**新增内容**:
- 10 个新 Agent（从 4 到 14）
- 5 个新产出类型（策略、风险、数据、评审、裁决）
- Monitor 战区（执行分析 + 知识沉淀）
- Manifest 多文件结构（prepare/analyze/design/review/monitor）
- fleet_config.yml 全局配置
### 8.2 升级后建议
1. 运行 `/qe-fleet validate` 确认所有 Agent 就绪
2. 用已有需求跑一次 `/qe-fleet run`，对比 v1 和 v2 的产出
3. 根据项目实际调整 `fleet_config.yml` 中的阈值
4. 补充项目画像中的具体信息
5. 开启 Monitor 战区，开启知识自动沉淀
### 8.3 治理审计
当改动涉及以下文件时，自动触发治理审计：
```bash
python3 scripts/governance_audit.py auto
```
触发条件：改动了 `scripts/`、`.claude/`、`agents/`、`AGENTS.md`、`README.md`、`fleet_config.yml`
**不会触发**: `requirements/`、`knowledge_base/02_history/`、`knowledge_base/03_best_practices/`、`output/` 的普通更新
---
## 附录: 快速排查命令
```bash
# Agent 健康检查
python3 scripts/fleet_runner.py validate
# 查看 Fleet 进度
python3 scripts/fleet_runner.py status --requirement source_docs/requirements_raw/需求.docx
# 重置某个战区（删除 manifest 重新运行）
rm output/manifests/需求_design.json
/qe-fleet design source_docs/requirements_raw/需求.docx
# 查看知识库健康度
/qe-fleet knowledge sync
# 治理审计
python3 scripts/governance_audit.py auto
# 仅导出 Excel（不重复生成）
python3 scripts/fleet_runner.py export --requirement source_docs/requirements_raw/需求.docx
```
docs/USER_GUIDE.md
+377
View File
@@ -0,0 +1,377 @@
# Agentic QE Fleet 用户指南
> 版本: 2.0.0 | 最后更新: 2026-07-09
## 目录
1. [快速开始](#1-快速开始)
2. [命令参考](#2-命令参考)
3. [工作流详解](#3-工作流详解)
4. [知识库使用](#4-知识库使用)
5. [常见场景](#5-常见场景)
6. [FAQ](#6-faq)
---
## 1. 快速开始
### 环境要求
- Python 3.10+
- Git
- pip
### 安装
```bash
# 克隆仓库
git clone http://47.109.59.41:3000/xst/QaAutomationHub.git
cd QaAutomationHub
# 安装依赖
python3 -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt
```
### 3 步上手
**第 1 步**: 把需求文档放进 `source_docs/requirements_raw/`
```
source_docs/requirements_raw/你的需求.docx
```
**第 2 步**: 确认项目画像已维护
```
knowledge_base/00_project/project_profile.md
```
**第 3 步**: 运行 Fleet
```
/qe-fleet run source_docs/requirements_raw/你的需求.docx
```
Fleet 会自动完成：文档解析 → 知识激活 → 需求分析 → 冲突检测 → 风险评估 → 测试策略 → 测试点 → 用例 → 评审 → 覆盖审计 → 质量裁决 → Excel 导出。
---
## 2. 命令参考
### `/qe-fleet run` — 全流程自动化
```text
/qe-fleet run source_docs/requirements_raw/需求.docx
```
从需求到 Excel 一条命令搞定。等价于依次执行 prepare → analyze → design → review → export。
**参数**:
- `--zone <战区>`: 仅运行到指定战区（prepare/analyze/design/review/monitor）
- `--skip-export`: 跳过最终 Excel 导出
### `/qe-fleet prepare` — 仅准备
```text
/qe-fleet prepare source_docs/requirements_raw/需求.docx
```
执行文档解析 + 知识激活。适合先看看标准化后的需求是什么样。
### `/qe-fleet analyze` — 准备 + 分析
```text
/qe-fleet analyze source_docs/requirements_raw/需求.docx
```
执行到分析战区结束。产出需求分析、冲突报告、风险评估。
### `/qe-fleet design` — 准备 → 分析 → 设计
```text
/qe-fleet design source_docs/requirements_raw/需求.docx
```
执行到设计战区结束。产出测试策略、测试点、测试用例、测试数据。
### `/qe-fleet review` — 仅评审
```text
/qe-fleet review source_docs/requirements_raw/需求.docx
```
对已有产物执行评审（不重复生成）。产出评审报告、覆盖率审计、质量裁决。
### `/qe-fleet export` — 仅导出
```text
/qe-fleet export source_docs/requirements_raw/需求.docx
```
将已有测试用例导出为 Excel + 版本快照。
### `/qe-fleet monitor` — 执行分析 + 知识沉淀
```text
/qe-fleet monitor source_docs/requirements_raw/需求.docx --results test-results.xml
```
分析测试执行结果，分类失败，沉淀知识。
### `/qe-fleet status` — 查看进度
```text
/qe-fleet status source_docs/requirements_raw/需求.docx
```
查看当前需求的 Fleet 运行进度和产物状态。
### `/qe-fleet validate` — 验证 Agent 就绪
```text
/qe-fleet validate
```
验证所有 14 个 Agent prompt 文件是否存在且非空。
### 兼容命令
```text
/case_generate source_docs/requirements_raw/需求.docx
```
完全等同于 `/qe-fleet run`，向后兼容。
---
## 3. 工作流详解
### 3.1 标准流程
```
需求文档 → PREPARE → ANALYZE → [人工确认] → DESIGN → REVIEW → [质量裁决] → EXPORT
```
### 3.2 确认门禁
当 Fleet 检测到以下情况时，会在 ANALYZE 战区后暂停：
- 识别到历史相似需求
- 检测到规则冲突（P0/P1 级别）
- 需求中存在 `⚠️ 待确认` 项
**此时你需要**:
1. 查看 `output/analysis/{需求名}_关联与冲突.md`
2. 在 `decisions/` 下创建确认单（使用 `确认结论模板.md`）
3. 确认状态写为 `确认状态：已确认`
4. 重新运行 `/qe-fleet run`（Fleet 会自动跳过已完成战区）
### 3.3 质量裁决
评审战区结束后，quality-gatekeeper 会做出三级裁决：
| 裁决 | 含义 | 后续操作 |
|------|------|----------|
| ✅ PASS | 全部达标 | 自动导出 Excel |
| 🔧 PASS_WITH_FIX | 已自动修复 | 自动导出 Excel |
| 🛑 BLOCKED | 有阻断项 | 查看裁决报告，修复后重跑 |
### 3.4 Monitor 循环
```
测试执行 → /qe-fleet monitor → 执行分析 → 知识沉淀 → 知识库自动更新 → 下次生成更准
```
这是一个正向循环：用得越多，知识库越丰富，生成质量越高。
---
## 4. 知识库使用
### 4.1 知识库结构
```
knowledge_base/
├── 00_project/ # 项目画像（必须维护）
│ └── project_profile.md
├── 01_standards/ # 标准规范
│ ├── terminology.md # 核心术语（常驻）
│ ├── terminology_optional_saas.md # 扩展术语（按需激活）
│ ├── test_case_template.md # 用例模板
│ ├── definition_of_done.md # 完成标准
│ └── review_checklist.md # 评审清单
├── 02_history/ # 历史经验（手动+自动维护）
│ ├── common_missed_scenes.md # 易漏场景
│ ├── historical_defects.md # 历史缺陷
│ └── marketing_rules.md # 营销规则
└── 03_best_practices/ # 最佳实践（手动+推荐）
├── payment_flow_cases.md # 支付链路范例
└── marketing_activity_cases.md # 营销活动范例
```
### 4.2 知识激活机制
Fleet 不会全量加载所有知识库，而是按需求内容智能激活：
- **常驻激活**: `terminology.md`、`template.md`、`definition_of_done.md`、`review_checklist.md`
- **关键词匹配**: 如需求包含"导购、分销、企微"→ 激活 `terminology_optional_saas.md`
- **语义匹配**: 计算需求与知识库文件的 Jaccard 相似度，≥ 0.08 则激活
### 4.3 知识缺口
当 Fleet 发现需求涉及但知识库无覆盖的领域时，会在 Prepare 战区输出 `knowledge_gaps`，提示你补充相关知识。
---
## 5. 常见场景
### 5.1 新需求首次生成
```bash
# 1. 放置文档
cp 新人礼需求.docx source_docs/requirements_raw/
# 2. 一键生成
# 在 CLI 中输入:
/qe-fleet run source_docs/requirements_raw/新人礼需求.docx
# 3. 查看产物
ls output/analysis/新人礼需求_*
ls output/test_points/新人礼需求_*
ls output/test_cases/新人礼需求_*
ls output/excel_reports/新人礼需求_*
```
### 5.2 已有需求的子需求迭代
```bash
# 1. 保留旧需求文档在 requirements/ 或 source_docs/requirements_raw/
# 2. 放置新子需求
cp 新人礼二期需求.docx source_docs/requirements_raw/
# 3. 运行 Fleet
/qe-fleet run source_docs/requirements_raw/新人礼二期需求.docx
# 4. 如果 Fleet 在 ANALYZE 后暂停（检测到冲突）
# → 查看 output/analysis/新人礼二期需求_关联与冲突.md
# → 在 decisions/ 下创建确认单
# → 确认单写"确认状态：已确认"
# → 重新运行 /qe-fleet run
# 5. 按确认结论重跑受影响需求
python3 scripts/case_pipeline.py apply-confirmation --requirement source_docs/requirements_raw/新人礼二期需求.docx
```
### 5.3 线上事故后回写
```bash
# 1. 手动补充历史缺陷
# 编辑 knowledge_base/02_history/historical_defects.md
# 写明：模块、现象、根因、防御建议
# 2. 手动补充易漏场景
# 编辑 knowledge_base/02_history/common_missed_scenes.md
# 3. （可选）运行知识库健康检查
/qe-fleet knowledge sync
# 4. 下次运行 Fleet 时，新的历史经验会自动激活
```
### 5.4 测试执行后分析
```bash
# 拿到测试执行结果后
/qe-fleet monitor source_docs/requirements_raw/需求.docx --results junit-results.xml
# 产出：
# - output/analysis/需求_执行分析.md（失败分类 + 根因分析）
# - knowledge_base/ 自动更新（P0 缺陷自动沉淀）
# - knowledge_gaps/ 待确认沉淀（P1-P3 需人工确认）
```
### 5.5 查看进度
```bash
/qe-fleet status source_docs/requirements_raw/需求.docx
```
输出示例：
```
✅ prepare: completed
✅ analyze: completed
⏳ design: in_progress
⬜ review: pending
⬜ monitor: pending
```
---
## 6. FAQ
### Q: 和原来的 /case_generate 有什么区别？
`/qe-fleet` 是升级版，Agent 从 4 个增加到 14 个，新增了风险评估、测试策略、数据构造、覆盖率审计、质量门禁、执行分析、知识沉淀等能力。`/case_generate` 保留为别名。
### Q: 必须所有战区都跑吗？
不必须。你可以分步运行：
- 只想看分析 → `/qe-fleet analyze`
- 只想看设计 → `/qe-fleet design`
- 只想导出 Excel → `/qe-fleet export`
- 只想分析测试结果 → `/qe-fleet monitor`
### Q: Fleet 生成的用例能直接用吗？
Fleet 生成的用例经过 4 个 Agent 协作（设计 → 评审 → 覆盖审计 → 质量裁决），质量裁决 PASS 后可以直接使用。但建议：
- 首次使用前先配置项目画像
- 补充知识库中的具体业务规则
- 对 P0 高风险用例做一次人工确认
### Q: 如何让 Fleet 越来越准？
1. 维护项目画像（`knowledge_base/00_project/project_profile.md`）
2. 每次线上事故后回写到历史缺陷/易漏场景
3. 积累高质量用例到最佳实践
4. 使用 Monitor 战区的自动知识沉淀功能
5. 定期运行 `/qe-fleet knowledge sync` 做知识库健康检查
### Q: 支持哪些文档格式？
- `.docx`（推荐，结构保留最好）
- `.doc`（通过 pyantiword 解析）
- `.pdf`（通过 PDF 流解析，扫描件/图片型 PDF 质量差）
- `.md`（直接使用）
- `.txt`（直接使用）
### Q: Excel 导出格式是什么？
默认导出为云效字段模型（标题/编号/目录/创建时间/前置条件/步骤描述/预期结果/优先级/类型/URL）。可在 `fleet_config.yml` 中修改。
### Q: 如何关闭某个战区？
编辑 `fleet_config.yml`：
```yaml
battle_zones:
monitor:
enabled: false # 关闭 Monitor 战区
```
### Q: 如何调整质量门禁严格度？
编辑 `fleet_config.yml`：
```yaml
quality_gate:
min_coverage: 0.90 # 降低覆盖率要求（默认 0.95）
max_blockers: 2 # 允许最多 2 个阻断项（默认 0）
```
### Q: 知识沉淀会自动修改我的知识库文件吗？
Monitor 战区的 knowledge-curator Agent：
- **P0 确认缺陷**: 默认自动回写（可在 `fleet_config.yml` 中关闭）
- **P1-P3 缺陷**: 默认仅生成建议，需人工确认后回写
- **去重保护**: 回写前自动检查与已有知识的相似度
- **变更记录**: 所有自动回写会记录时间戳和来源
docs/superpowers/specs/2026-07-09-agentic-qe-fleet-design.md
+357
View File
@@ -0,0 +1,357 @@
# 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 端到端流程