QaAutomationHub/docs/MAINTENANCE_GUIDE.md

# 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
```