QaAutomationHub/docs/USER_GUIDE.md

Agentic QE Fleet 用户指南

版本: 2.0.0 | 最后更新: 2026-07-09

目录

1. 快速开始
2. 命令参考
3. 工作流详解
4. 知识库使用
5. 常见场景
6. FAQ

---

1. 快速开始

环境要求

• Python 3.10+
• Git
• pip

安装

# 克隆仓库
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 — 全流程自动化

/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 — 仅准备

/qe-fleet prepare source_docs/requirements_raw/需求.docx

执行文档解析 + 知识激活。适合先看看标准化后的需求是什么样。

/qe-fleet analyze — 准备 + 分析

/qe-fleet analyze source_docs/requirements_raw/需求.docx

执行到分析战区结束。产出需求分析、冲突报告、风险评估。

/qe-fleet design — 准备 → 分析 → 设计

/qe-fleet design source_docs/requirements_raw/需求.docx

执行到设计战区结束。产出测试策略、测试点、测试用例、测试数据。

/qe-fleet execute — 自动化测试执行

/qe-fleet execute source_docs/requirements_raw/需求.docx

执行自动化测试：生成 Playwright (PC Web) + Appium (移动端) 脚本，采集截图，AI 视觉对比，输出测试结论报告。

产出:

• output/execution/{需求名}/playwright_tests.py — PC Web 自动化脚本
• output/execution/{需求名}/appium_tests.py — 移动端自动化脚本
• output/screenshots/{需求名}/ — 截图证据目录
• output/execution/{需求名}_执行报告.md — 含截图对比的测试结论

/qe-fleet review — 仅评审

/qe-fleet review source_docs/requirements_raw/需求.docx

对已有产物执行评审（不重复生成）。产出评审报告、覆盖率审计、质量裁决。

/qe-fleet export — 仅导出

/qe-fleet export source_docs/requirements_raw/需求.docx

将已有测试用例导出为 Excel + 版本快照。

/qe-fleet monitor — 执行分析 + 知识沉淀

/qe-fleet monitor source_docs/requirements_raw/需求.docx --results test-results.xml

分析测试执行结果，分类失败，沉淀知识。

/qe-fleet status — 查看进度

/qe-fleet status source_docs/requirements_raw/需求.docx

查看当前需求的 Fleet 运行进度和产物状态。

/qe-fleet validate — 验证 Agent 就绪

/qe-fleet validate

验证所有 14 个 Agent prompt 文件是否存在且非空。

兼容命令

/case_generate source_docs/requirements_raw/需求.docx

完全等同于 /qe-fleet run，向后兼容。

---

3. 工作流详解

3.1 标准流程

需求文档 → PREPARE → ANALYZE → [人工确认] → DESIGN → EXECUTE → 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 新需求首次生成

# 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 已有需求的子需求迭代

# 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 线上事故后回写

# 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 测试执行后分析

# 拿到测试执行结果后
/qe-fleet monitor source_docs/requirements_raw/需求.docx --results junit-results.xml

# 产出：
# - output/analysis/需求_执行分析.md（失败分类 + 根因分析）
# - knowledge_base/ 自动更新（P0 缺陷自动沉淀）
# - knowledge_gaps/ 待确认沉淀（P1-P3 需人工确认）

5.5 查看进度

/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：

battle_zones:
  monitor:
    enabled: false  # 关闭 Monitor 战区

Q: 如何调整质量门禁严格度？

编辑 fleet_config.yml：

quality_gate:
  min_coverage: 0.90    # 降低覆盖率要求（默认 0.95）
  max_blockers: 2       # 允许最多 2 个阻断项（默认 0）

Q: 知识沉淀会自动修改我的知识库文件吗？

Monitor 战区的 knowledge-curator Agent：

• P0 确认缺陷: 默认自动回写（可在 fleet_config.yml 中关闭）
• P1-P3 缺陷: 默认仅生成建议，需人工确认后回写
• 去重保护: 回写前自动检查与已有知识的相似度
• 变更记录: 所有自动回写会记录时间戳和来源