xst
b2a035c4f9
- 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
461 lines
16 KiB
Markdown
461 lines
16 KiB
Markdown
# QA Automation Hub 操作手册
|
||
|
||
这份文档不再重复 `README.md` 的快速开始。它只回答三个问题：
|
||
|
||
- 这个仓库长期该维护什么
|
||
- 新需求、新业务线、线上事故发生后该怎么回写
|
||
- 哪些文件是资产，哪些只是执行产物
|
||
|
||
基础使用方式、固定输出和常用命令请先看 [README.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/README.md)。
|
||
|
||
## 1. 文档分工
|
||
|
||
- `README.md`
|
||
- 面向第一次进入仓库的人
|
||
- 用于说明仓库用途、快速开始、固定输出、关键规则
|
||
- `操作手册.md`
|
||
- 面向长期维护仓库的人
|
||
- 用于说明目录职责、知识库维护、需求输入规范、结果治理策略
|
||
|
||
如果一个内容只影响“怎么开始用”，放 `README.md`。
|
||
如果一个内容影响“仓库以后怎么维护”，放 `操作手册.md`。
|
||
|
||
## 2. 目录职责
|
||
|
||
### 长期资产
|
||
|
||
以下目录或文件是团队要持续投入维护的：
|
||
|
||
- `requirements/`
|
||
- 正式维护版 Markdown 目录
|
||
- 适合已经沉淀成长期维护版本的 `.md` 需求
|
||
- `knowledge_base/`
|
||
- 团队长期沉淀的规则、缺陷、经验和案例
|
||
- 决定仓库是否会越用越强
|
||
- `agents/`
|
||
- 控制分析、测试点、测试用例、自审的输出风格和约束
|
||
- `.claude/`
|
||
- Claude CLI 的入口规则和命令定义
|
||
- `AGENTS.md`
|
||
- Codex CLI 的入口规则
|
||
- `scripts/`
|
||
- 固定流水线脚本，负责 `prepare / verify / export`
|
||
|
||
### 执行产物
|
||
|
||
以下目录默认不作为长期知识维护区：
|
||
|
||
- `output/analysis/`
|
||
- `output/test_points/`
|
||
- `output/test_cases/`
|
||
- `output/excel_reports/`
|
||
- `output/manifests/`
|
||
- `output/normalized_inputs/`
|
||
- `output/versions/`
|
||
|
||
这些内容的定位是执行结果、回溯样例、排查依据，不应该代替知识库源文件。
|
||
|
||
### 可忽略内容
|
||
|
||
- `.DS_Store`
|
||
- `__pycache__/`
|
||
- 历史临时 Excel
|
||
- 已无参考价值的旧样例产物
|
||
|
||
### `decisions/`
|
||
|
||
这里放跨需求冲突的人为确认结论，不放测试产物，不放知识库通用规则。
|
||
|
||
适合放：
|
||
|
||
- 子需求与旧需求的关系判定
|
||
- 替代 / 补充 / 并行生效结论
|
||
- 生效范围、失效范围、影响模块
|
||
- 需要回写和重跑的需求列表
|
||
|
||
不适合放：
|
||
|
||
- 临时聊天记录
|
||
- 未确认的零散意见
|
||
- 与具体需求无关的通用规则
|
||
|
||
## 3. 知识库怎么维护
|
||
|
||
### `requirements/`
|
||
|
||
这里是正式维护版 Markdown 目录，适合已经沉淀成长期维护版本的正式需求文档，不放知识库，不放历史产物。
|
||
|
||
推荐命名：
|
||
|
||
```text
|
||
requirements/项目名_版本号.md
|
||
requirements/order_center_v1.2.md
|
||
requirements/member_coupon_v2.0.md
|
||
```
|
||
|
||
当前脚本同步正式维护版时，固定使用：
|
||
|
||
```text
|
||
requirements/{BASE_NAME}.md
|
||
```
|
||
|
||
维护建议：
|
||
|
||
- 同一主题只保留一个正式维护版文件
|
||
- 不要再派生 `xxx_final.md`、`xxx_最新版.md`、`xxx_20260426.md`
|
||
- 如果确实存在多阶段版本差异，用确认单和 `output/versions/` 做追溯，不靠在 `requirements/` 里堆文件名分叉
|
||
|
||
边界要求：
|
||
|
||
- `requirements/` 推荐只放 `.md`
|
||
- 这里的文件会被 `prepare` 当成可执行输入和关联需求扫描范围
|
||
- 当前推荐由脚本在 `export` 成功后自动同步正式维护版，不再手工复制 raw 文档
|
||
- 如果 `requirements/` 与 `source_docs/requirements_raw/` 同时存在同主题文档，后续关联识别优先使用 `requirements/` 下的维护版
|
||
- 不要把技术方案、接口说明混放进来，否则目录语义会变脏，后续也容易误用
|
||
|
||
### `source_docs/`
|
||
|
||
这里放原始输入材料和非直接执行文档。
|
||
|
||
推荐分层：
|
||
|
||
- `source_docs/requirements_raw/`
|
||
- 原始需求稿，如 `doc`、`docx`、`pdf`
|
||
- `source_docs/technical_solutions/`
|
||
- 技术方案、接口说明、时序图、数据结构说明等
|
||
|
||
建议原则：
|
||
|
||
- 当前主推荐做法是直接使用 `source_docs/requirements_raw/` 下的 `doc`、`docx`、`pdf` 作为 `/case_generate` 输入
|
||
- 如果需求已经沉淀为稳定的长期维护版本，`export` 后会自动同步一份到 `requirements/`
|
||
- `prepare` 会自动把原始需求稿和关联技术方案标准化到 `output/normalized_inputs/`，后续分析阶段统一消费标准化文件
|
||
- 原始需求稿和技术方案保留在 `source_docs/`，方便追溯
|
||
|
||
## 3.1 产物版本规则
|
||
|
||
当前产物和历史版本分开管理：
|
||
|
||
- 当前最新版始终使用固定文件名
|
||
- `output/analysis/{BASE_NAME}_分析.md`
|
||
- `output/test_points/{BASE_NAME}_测试点.md`
|
||
- `output/test_cases/{BASE_NAME}_测试用例.md`
|
||
- `output/excel_reports/{BASE_NAME}_测试用例.xlsx`
|
||
- 历史快照统一放到：
|
||
- `output/versions/{BASE_NAME}/v1/`
|
||
- `output/versions/{BASE_NAME}/v2/`
|
||
- `output/versions/{BASE_NAME}/v3/`
|
||
- `output/versions/{BASE_NAME}/VERSION_INDEX.md`
|
||
|
||
递增规则：
|
||
|
||
- 只在 `export` 成功后检查是否需要新增版本
|
||
- 只有当前分析、测试点、测试用例、manifest、标准化输入、Excel 任一内容相对上一个快照发生变化，才会新增 `vN`
|
||
- 如果只是重复导出同一份结果，版本不变
|
||
- `export` 还会自动迁移同一需求下遗留的时间戳 Excel，并把 `output/excel_reports/` 收敛到只保留当前最新版文件
|
||
- 每个需求最多只保留最近 `3` 个版本；新增第 `4` 个及以后版本时，会自动淘汰更早版本
|
||
- 每个 `vN/` 目录下会自动生成 `snapshot_meta.json`，用于标识快照类型
|
||
- `VERSION_INDEX.md` 会汇总每个版本是“完整流水线快照”还是“历史 Excel 导入”
|
||
|
||
这样做的目的很明确：
|
||
|
||
- 日常使用永远打开固定文件名，不需要在一堆时间戳文件里找最新版
|
||
- 需要回溯时，再到 `output/versions/` 看 `v1/v2/v3`
|
||
- 版本只跟“有效产物变化”绑定，不跟每次命令执行绑定
|
||
|
||
如果历史仓库里已经积累了大量旧时间戳 Excel，可以执行一次：
|
||
|
||
```bash
|
||
python3 scripts/case_pipeline.py migrate-history --all
|
||
```
|
||
|
||
这会把旧时间戳 Excel 迁移进对应 `BASE_NAME` 的版本目录，并从 `output/excel_reports/` 清掉旧文件。
|
||
|
||
### `knowledge_base/00_project/`
|
||
|
||
这里放项目级差异化约束，当前核心文件是：
|
||
|
||
- [project_profile.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/knowledge_base/00_project/project_profile.md)
|
||
|
||
这个文件要描述：
|
||
|
||
- 项目类型与目标用户
|
||
- 业务边界和禁用能力
|
||
- 项目特有高风险规则
|
||
- 技术依赖和一致性约束
|
||
- 冲突判定口径
|
||
|
||
如果项目画像不维护，后续测试分析和用例会退化成“通用模板输出”。
|
||
|
||
### `knowledge_base/01_standards/`
|
||
|
||
这里放稳定规则，不放项目实例。
|
||
|
||
当前职责：
|
||
|
||
- `terminology.md`
|
||
- 核心商城术语，常驻输入
|
||
- `terminology_optional_saas.md`
|
||
- 私域、分销、储值、CRM 等扩展术语
|
||
- 由流水线根据目标需求和项目画像自动识别是否纳入上下文
|
||
- `test_case_template.md`
|
||
- 唯一表头、`类型` 枚举、云效导出映射和命名约束规则
|
||
- `definition_of_done.md`
|
||
- 测试点与测试用例的完成门禁，用来约束覆盖维度、风险场景、待确认项和评审通过条件
|
||
- `review_checklist.md`
|
||
- 测试用例生成前自检和评审阶段的逐项检查清单，用来把完成门禁落成可执行检查项
|
||
|
||
适合继续放进来的内容：
|
||
|
||
- 优先级规则
|
||
- 命名规则
|
||
- 非功能清单
|
||
- 缺陷严重度定义
|
||
|
||
### `knowledge_base/02_history/`
|
||
|
||
这里放历史问题和团队经验。
|
||
|
||
适合放：
|
||
|
||
- 常见漏测场景
|
||
- 历史缺陷
|
||
- 业务线特有规则
|
||
- 已发生过的线上事故防御结论
|
||
|
||
建议做法：
|
||
|
||
- 通用内容放公共文件
|
||
- 业务线变多后按模块拆分
|
||
- 一条缺陷至少写清模块、现象、根因、建议防御点
|
||
|
||
### `knowledge_base/03_best_practices/`
|
||
|
||
这里放优秀用例范式，不放正式执行结果。
|
||
|
||
用途是告诉 Agent：
|
||
|
||
- 什么颗粒度合适
|
||
- 什么写法可执行
|
||
- 什么预期结果是合格的
|
||
- 哪类需求应参考哪类范式，避免把支付类范式直接套到营销活动、后台配置、C 端弹窗领取等不同场景
|
||
|
||
当前建议：
|
||
|
||
- `payment_flow_cases.md`
|
||
- 支付、收银台、订单支付状态、超时取消、支付失败切换等交易链路
|
||
- `marketing_activity_cases.md`
|
||
- 平台端/商家端活动配置、列表管理、状态流转、C 端资格展示、领取防重等营销活动链路
|
||
|
||
## 4. 需求文档输入标准
|
||
|
||
需求文档至少应包含以下内容：
|
||
|
||
- 背景
|
||
- 目标
|
||
- 用户角色
|
||
- 功能范围
|
||
- 关键业务规则
|
||
- 主流程
|
||
- 异常流程
|
||
- 非功能要求
|
||
- 不在本期范围
|
||
|
||
以下信息如果缺失，会明显拉低生成质量：
|
||
|
||
- 状态流转规则
|
||
- 金额计算口径
|
||
- 优惠互斥或叠加规则
|
||
- 超时与重试规则
|
||
- 权限边界
|
||
- 逆向流程规则
|
||
- 兼容历史逻辑的说明
|
||
|
||
如果某条规则会影响金额、库存、权益、权限、安全或合规，需求里必须写清，不能只靠 Agent 猜。
|
||
|
||
## 5. 结果不理想时先改哪里
|
||
|
||
优先检查输入和规则源，不要先手改 `output/` 结果：
|
||
|
||
1. 需求输入是否写清楚；若当前走原始文档流程，先检查 `source_docs/requirements_raw/` 中的原始需求稿
|
||
2. `knowledge_base/` 是否缺规则、缺缺陷、缺历史漏测点
|
||
3. `knowledge_base/00_project/project_profile.md` 是否缺项目差异化信息
|
||
4. `agents/` 的 prompts 是否约束不够
|
||
|
||
只有在确认源信息已经足够时，才去微调 prompts 或脚本。
|
||
|
||
## 5.1 已有需求继续迭代时怎么处理
|
||
|
||
这类场景是当前仓库最容易“看起来能跑，实际上没有完全闭环”的地方。推荐固定按下面的顺序执行：
|
||
|
||
1. 保留旧需求文档在 `source_docs/requirements_raw/` 或 `requirements/`
|
||
2. 把新子需求放进 `source_docs/requirements_raw/`
|
||
3. 把配套技术方案放进 `source_docs/technical_solutions/`
|
||
4. 先跑一次正常流程，让 `prepare` 自动生成 `关联与冲突.md`
|
||
5. 如果识别到历史相似需求、冲突候选或高风险 `> ⚠️ 待确认`，暂停在确认阶段
|
||
6. 在 `decisions/` 下新增一份确认单
|
||
7. 确认“补充 / 替代 / 并行”关系后，执行 `python3 scripts/case_pipeline.py apply-confirmation --requirement <需求文档路径>`
|
||
8. 由脚本按确认单里的重跑列表自动重跑受影响需求，并在 `decisions/applied/` 留存维护说明
|
||
|
||
这里要特别注意：
|
||
|
||
- 旧需求如果只留在 `output/versions/`，后续不会再被当成历史需求扫描对象
|
||
- 当前脚本能自动发现候选，但不会自动帮你裁决新旧规则关系
|
||
- 当前脚本已经会因为“冲突或待确认尚未解除”阻断 `verify/export`
|
||
|
||
所以，跨需求冲突场景下，`decisions/` 不是可选附件，而是闭环证据。
|
||
|
||
## 5.2 什么情况下必须进入确认阶段
|
||
|
||
出现以下任一情况，建议不要直接把当前产物当最终结论：
|
||
|
||
- `关联与冲突.md` 识别到历史相似需求
|
||
- 冲突候选涉及金额、库存、权益、权限、安全、合规
|
||
- 新需求可能替代旧规则，而不是单纯补充子场景
|
||
- 同一对象的状态机、阈值、次数、时效口径发生变化
|
||
- 需求正文或分析结果中出现 `> ⚠️ 待确认`
|
||
|
||
建议确认阶段只让人做“拍板”，不要让人重复做机器已经能做的事。人工重点只确认：
|
||
|
||
- 关系类型：`补充 / 替代 / 并行`
|
||
- 生效范围和失效范围
|
||
- 是否需要同步回写旧需求
|
||
- 是否允许未确认前继续导出
|
||
- 哪些需求需要在确认后重跑
|
||
|
||
## 6. 新项目或新业务线接入
|
||
|
||
每次新项目接入，至少补这几类内容：
|
||
|
||
1. 新需求文档优先放进 `source_docs/requirements_raw/`；若已沉淀成稳定 Markdown 版本，也可放进 `requirements/`
|
||
2. 项目画像补进 `knowledge_base/00_project/project_profile.md`
|
||
3. 相关术语补进 `knowledge_base/01_standards/`
|
||
- 核心共性词放 `terminology.md`
|
||
- 只在部分项目出现的扩展词优先单独拆文件，由流水线自动识别
|
||
4. 历史缺陷补进 `knowledge_base/02_history/`
|
||
5. 易漏测点补进 `knowledge_base/02_history/`
|
||
6. 高质量案例补进 `knowledge_base/03_best_practices/`
|
||
|
||
不要只放需求文档，不补项目画像和知识库。那样只能得到一次性结果，不能形成可复用资产。
|
||
|
||
## 6.1 确认单怎么写
|
||
|
||
建议统一使用 [decisions/确认结论模板.md](/Users/fangyuehui/Desktop/codeAll/qa-team/qa-automation-hub/decisions/确认结论模板.md)。
|
||
|
||
确认单至少要写清：
|
||
|
||
- 当前需求和关联历史需求
|
||
- 关系类型：`补充 / 替代 / 并行`
|
||
- 生效范围和失效范围
|
||
- 影响模块、角色、接口或数据口径
|
||
- 最终确认口径
|
||
- 是否需要回写旧需求
|
||
- 需要重跑的需求列表
|
||
|
||
如果确认单里没有“边界”和“重跑范围”，`apply-confirmation` 最多只能安全地重跑当前需求，无法稳定帮你把旧需求一起收敛。
|
||
|
||
## 7. 线上事故或漏测后怎么回写
|
||
|
||
每次线上事故、重大缺陷或明显漏测后，至少做一次回写：
|
||
|
||
1. 把缺陷沉淀到 `knowledge_base/02_history/historical_defects.md`
|
||
2. 如果属于通用遗漏，补进 `common_missed_scenes.md`
|
||
3. 如果属于业务线特有问题，新增或更新对应模块文件
|
||
4. 如果生成逻辑本身没有覆盖到，再补 `agents/` 或 `project_profile.md`
|
||
|
||
如果事故没有回写，仓库不会积累能力，只会重复犯同类错误。
|
||
|
||
## 8. 如何控制知识库膨胀
|
||
|
||
知识库变大以后，问题通常不是“内容太多”，而是“内容混乱”。
|
||
|
||
建议遵守这几个原则：
|
||
|
||
- 一个文件只讲一类东西，不混规则、缺陷、样例
|
||
- 文件名要能直接看出业务范围
|
||
- 通用内容和项目内容分开
|
||
- 样例产物不要反向混入长期规则
|
||
- 出现 30 到 50 条以上同类内容时，考虑按模块拆分
|
||
|
||
## 9. 样例与产物怎么处理
|
||
|
||
代表性样例产物可以少量保留，用于：
|
||
|
||
- 跑通演示
|
||
- 格式参考
|
||
- 新成员理解输出结构
|
||
|
||
但不要把 `output/` 当唯一真相。真正要维护的是需求、知识库、prompts 和脚本。
|
||
|
||
如果后续历史样例过多，可以只保留：
|
||
|
||
- 1 份代表性需求
|
||
- 1 套代表性分析/测试点/测试用例
|
||
- 少量高价值 Excel 导出样例
|
||
|
||
## 10. 日常维护原则
|
||
|
||
平时最重要的不是反复改产物，而是维护好这些源头：
|
||
|
||
- `source_docs/requirements_raw/`
|
||
- `source_docs/technical_solutions/`
|
||
- `requirements/`
|
||
- `knowledge_base/`
|
||
- `knowledge_base/00_project/project_profile.md`
|
||
- `agents/`
|
||
|
||
补充原则：
|
||
|
||
- Markdown 用例是内部高质量源格式，允许保留 `测试数据`、`备注` 等细粒度字段
|
||
- Excel 导出默认对齐团队云效字段模型，`测试数据` 会自动并入 `步骤描述`
|
||
- 如果团队平台字段模型发生变化，优先更新 `test_case_template.md` 和 `scripts/export_excel.py`
|
||
- `requirements/` 目录只保留正式维护版 Markdown，不保留 Finder 缓存、临时副本或手工导出的重复文件
|
||
|
||
一句话原则：
|
||
|
||
先改输入和规则源，再改 prompts，最后才考虑改执行结果。
|
||
|
||
## 11. 流程治理检查
|
||
|
||
仓库内已提供低频治理脚本：
|
||
|
||
```bash
|
||
python3 scripts/governance_audit.py auto
|
||
```
|
||
|
||
这项检查只应在以下类型改动后触发：
|
||
|
||
- 流程脚本改动：`scripts/`
|
||
- CLI 入口规则改动：`AGENTS.md`、`.claude/`
|
||
- prompts 改动：`agents/`
|
||
- 标准规范改动：`knowledge_base/01_standards/`
|
||
- 仓库入口文档改动：`README.md`、`操作手册.md`
|
||
|
||
这项检查不会因为以下普通内容更新自动触发：
|
||
|
||
- `requirements/` 下新增或修改需求
|
||
- `knowledge_base/02_history/` 的历史缺陷、易漏场景更新
|
||
- `knowledge_base/03_best_practices/` 的案例补充
|
||
- `output/` 下的执行产物变化
|
||
|
||
这项检查的目的有两个：
|
||
|
||
- 检查 `Codex CLI` 和 `Claude CLI` 的流程是否仍然一致
|
||
- 检查 `README.md` 和 `操作手册.md` 是否落后于当前实现
|
||
|
||
## 12. 当前流程缺口与下一步实现建议
|
||
|
||
如果你希望后续真正满足“自动识别冲突、人工确认、确认后自动续跑”的闭环，还需要继续补脚本能力。当前最值得补的点是：
|
||
|
||
1. 增加回写到需求源文件的能力
|
||
- 当前已支持写到 `decisions/applied/` 维护说明，但不会直接修改原始 `docx/md`
|
||
2. 增加更细粒度的门禁级别
|
||
- 例如把“仅弱关联提示”和“高风险必须阻断”分开
|
||
3. 增加确认单结构化校验
|
||
- 避免只有一句“已确认”，却没有写清边界、影响范围和重跑列表
|
||
|
||
在这些能力落地前，当前最稳的工作方式仍然是：
|
||
|
||
- 机器负责识别、汇总、出建议
|
||
- 人负责最终裁决
|
||
- 人再触发受影响需求的重跑
|