Yb-QaAutomationHub/docs/MAINTENANCE_GUIDE.md

Agentic QE Fleet 维护指南

版本: 2.0.0 | 最后更新: 2026-07-09 | 面向: 仓库维护者

目录

1. 架构概览
2. 目录职责速查
3. 日常维护任务
4. Agent 管理
5. 知识库维护
6. 配置调优
7. 故障排查
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 数据流

# 每个战区产出独立 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 新增需求时

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

必须做的事（每次事故至少做一项）:

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 知识库健康检查

# 检查知识库覆盖缺口
/qe-fleet knowledge gaps

# 同步和去重
/qe-fleet knowledge sync

---

4. Agent 管理

4.1 新增 Agent

1. 在 agents/<zone>/ 下创建 prompt 文件
2. 在 fleet_agents.py 的 AGENT_REGISTRY 中注册：

"new-agent-id": {
    "zone": "design",          # 所属战区
    "path": "design/new_agent.md",
    "name": "新 Agent 名称",
    "description": "一句话描述",
}

3. 在对应战区的 fleet_runner.py 处理函数中加入该 Agent 的调用逻辑
4. 运行验证：

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 历史缺陷

格式规范（每条缺陷应包含）：

### {缺陷标题}
- 模块: xxx
- 现象: 具体可观测的异常行为
- 根因: 为什么发生
- 影响: 用户/数据/资金的直接影响
- 防御建议: 测试中应如何覆盖
- 发现日期: YYYY-MM-DD
- 严重度: P0/P1/P2

5.4 最佳实践

格式规范（每个案例应包含）：

### {案例标题}
- 适用场景: 什么类型的需求可以参考
- 用例编号: TC-XXX
- 亮点: 为什么这个用例写得好（颗粒度/数据/预期结果）
- 用例内容: （表格或引用）

5.5 知识库膨胀控制

• 一个文件只讲一类东西
• 出现 30-50 条以上同类内容时，按模块拆分
• 每季度做一次去重重审
• 删除已过时或不再适用的条目（不要怕删）

---

6. 配置调优

6.1 fleet_config.yml 关键参数

# 质量门禁严格度（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 战区开关

battle_zones:
  monitor:
    enabled: false   # 暂时不需要 Monitor → 关闭

6.3 调试模式

编辑 fleet_config.yml，临时调整：

battle_zones:
  analyze:
    auto_confirm: true   # 跳过确认门禁（仅调试用）

---

7. 故障排查

7.1 问题：Agent prompt 找不到

症状: FileNotFoundError: Agent prompt 不存在

排查:

# 验证所有 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 治理审计

当改动涉及以下文件时，自动触发治理审计：

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/ 的普通更新

---

附录: 快速排查命令

# 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