feat: Agentic QE Fleet v2.0.0 - 14-agent quality engineering platform
- 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
@@ -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 缺陷**: 默认仅生成建议，需人工确认后回写
|
||||
- **去重保护**: 回写前自动检查与已有知识的相似度
|
||||
- **变更记录**: 所有自动回写会记录时间戳和来源
|
||||
Reference in New Issue
Block a user