QaAutomationHub/docs/USER_GUIDE.md

# 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 execute` — 自动化测试执行

```text
/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` — 仅评审

```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 → 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 新需求首次生成

```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 缺陷**: 默认仅生成建议，需人工确认后回写
- **去重保护**: 回写前自动检查与已有知识的相似度
- **变更记录**: 所有自动回写会记录时间戳和来源