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
2026-07-09 14:29:11 +08:00
commit b2a035c4f9
79 changed files with 9905 additions and 0 deletions
@@ -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
+```