QaAutomationHub/操作手册.md

QA Automation Hub 操作手册

这份文档不再重复 README.md 的快速开始。它只回答三个问题：

• 这个仓库长期该维护什么
• 新需求、新业务线、线上事故发生后该怎么回写
• 哪些文件是资产，哪些只是执行产物

基础使用方式、固定输出和常用命令请先看 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 目录，适合已经沉淀成长期维护版本的正式需求文档，不放知识库，不放历史产物。

推荐命名：

requirements/项目名_版本号.md
requirements/order_center_v1.2.md
requirements/member_coupon_v2.0.md

当前脚本同步正式维护版时，固定使用：

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，可以执行一次：

python3 scripts/case_pipeline.py migrate-history --all

这会把旧时间戳 Excel 迁移进对应 BASE_NAME 的版本目录，并从 output/excel_reports/ 清掉旧文件。

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。

确认单至少要写清：

• 当前需求和关联历史需求
• 关系类型：补充 / 替代 / 并行
• 生效范围和失效范围
• 影响模块、角色、接口或数据口径
• 最终确认口径
• 是否需要回写旧需求
• 需要重跑的需求列表

如果确认单里没有“边界”和“重跑范围”，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. 流程治理检查

仓库内已提供低频治理脚本：

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. 增加确认单结构化校验
   • 避免只有一句“已确认”，却没有写清边界、影响范围和重跑列表

在这些能力落地前，当前最稳的工作方式仍然是：

• 机器负责识别、汇总、出建议
• 人负责最终裁决
• 人再触发受影响需求的重跑