/qa-spec — prd.md → 测试点 → 测试 spec（+ 可选 XMind 导出）

权威路径（唯一）： 工作区 .cursor/skills/qa-spec/。禁止使用 ~/.cursor/plugins/**/qa-spec 等旧副本。

版本： 1.2.0

前置条件

• metadata.yaml 中 prd.status 为 confirmed
• test_spec.status 为 pending

流程

Step 0: 确保 specs 仓库最新

提示用户在 specs 仓库目录执行 git pull，确保 prd.md 是产品团队提交的最新版本。可通过 git status 检测是否 behind remote，若 behind 则必须先提示 pull。

Step 0.5: 飞书文档链接（可选入口）

若用户给出飞书云文档 URL（如 *.feishu.cn/docx/...），且当前需求尚无可用 prd.md：

1. 用飞书 MCP fetch-doc（doc_id 传完整 URL）拉取正文
2. 将内容整理为符合本仓库规范的 prd.md（含 MODULE、功能描述；不套用外部券商/对账模板）
3. 请产品/测试确认后，将 prd.status 置为 confirmed，再继续 Step 1

已有确认过的 prd.md 时跳过本步。拉取失败（无权限/空文档）则停止并说明原因。

Step 1: 定位需求

自动模式：扫描 requirements/ 下 prd 已确认且测试 spec 为 pending 的需求。
手动模式：用户直接指定路径。

Step 2: 读取 prd.md

读取 prd.md 全文。从中抽出 MODULE / Feature List 范围（后续生成与原型过滤的唯一边界）。

⛔ 输入隔离（决策 D5）：禁止读取 openspec/changes/ 下任何开发产出。唯一输入来源：prd.md + 原型（如有）。

Step 2.5: 原型辅助阅读（默认本地 prototypes）

Demo 只作补充，辅助理解与 PRD 一致的交互/控件文案；prd.md 仍是主要需求来源。

默认读取顺序（固定，不默认拉 pages 外链）：

1. 读当前需求目录 metadata.yaml → sources.prototype（相对路径，如 prototypes/device-control-demo.html）
2. 若无配置：扫描 prototypes/**/*.html；多个时优先文件名含 demo 者，或与 prd「原型/demo」表中本地路径一致者
3. 不默认请求 pages.yc345.tv / 其它外链；仅当用户明确要求「读外链」且本地缺失时再尝试，失败则记录并继续，不阻断

阅读与过滤（强制）：

• 只读取、理解与 PRD MODULE / Feature List 一致的功能片段（含 prd 写明的场景开关，如本类需求的 teacher-multi）
• Demo 中未出现在 PRD Feature List 的模块/场景（如无关的管理员全校视图、其它业务页）一律忽略
• 禁止根据 demo 自行引申并生成无关模块测试点或用例
• 与 PRD 冲突时以 PRD 为准；demo 仅用于补步骤中的控件名、弹窗文案、入口位置等

无 prototypes/ 或找不到 HTML：跳过本步，仅依据 prd.md 生成（不报错中断）。

Step 3: 扫描前后端现状（默认跳过）

默认跳过，避免无 PRD 依据的推断。
仅当用户明确要求「结合代码现状」时，再从 workspace-repos.json 解析仓库路径做只读扫描；扫描结论不得突破 PRD MODULE 边界。

Step 4: 五维测试点提取（强制）

1. 完整阅读 references/test-point-extraction.md
2. 按 MODULE 做五维提取（功能 / 业务规则 / 边界 / 异常 / 非功能）
3. 严格有据：只依据 prd.md + Step 2.5 已对齐的设计图；禁止随意生成与主动推导非功能
4. 产出测点草稿表（含「依据」列）

默认不调用 superpowers:brainstorming。仅当用户明确要求 brainstorm / 策略研讨时再调用。

Step 4.5: 测点二检（自动检查与补全，强制）

落盘测点前，扮演二检角色（不暂停等人审）：

1. 完整阅读 references/test-point-gates.md
2. 对草稿跑 T1–T6，输出二检表
3. 对 FAIL 执行对应补全/删除/待确认（仍须有据）
4. 再检；最多 2 轮
5. 通过后写入 test/test-points.md（若已存在：先备份 test/test-points.backup-YYYYMMDD.md 再覆盖）

2 轮后仍 FAIL：保留 [待确认] 于「风险提醒」，仍写入 test-points.md，继续 Step 5。

Step 5: 按测试点展开四级用例

输入：test/test-points.md（主）+ prd.md + 对齐 MODULE 的 prototype（辅）。

生成原则：
1. 每个测点展开为一条（少数相关测点可合并为一条）四级场景；场景可标注 **测点**: #N
2. 覆盖测点清单中全部 P0/P1；P2 按风险取舍，跳过须在覆盖展示中说明
3. 仅围绕有据测点生成，不添加无关用例
4. 预期结果只保留一个成立条件
5. MODULE ID 与 prd.md 严格一致（决策 D22）
6. 测试步骤描述业务操作（决策 D24）
7. 场景不使用编号，仅使用描述性标题（决策 QA-D9）
8. 公共写法（生成时即遵守）：步骤用「动作+对象」；预期可观测、禁空词；信息不足写 [待确认:…]。细则见 references/quality-gates.md
9. 原型边界（决策 QA-P1）：每条用例须能回溯到测点 # 与 prd MODULE；不得因 demo 扩写 PRD 未列模块

参考资料：
- references/test-writing-guide.md（十大类书写）
- references/quality-gates.md
- test/test-points.md
- Step 2.5 本地 prototypes（若有）

输出格式：

# 测试用例：<需求标题>

> 来源产品 spec: requirements/<requirement>/prd.md
> 来源测试点: requirements/<requirement>/test/test-points.md
> 确认时间: YYYY-MM-DD

## MODULE-MS-01: <模块名称>

### 场景: <正常流程描述>
**测点**: #1
**测试类型**: 功能测试
**覆盖端**: 运营后台
**前置条件**:
- 条件1
**操作步骤**:
1. 步骤1
**预期结果**:
- 结果1

测试类型优先级：功能测试 > 边界测试 > 其他按需。
场景标题必须唯一且有描述性，作为 XMind round-trip 时的匹配标识。

Step 5.5: 公共写法自审与自动改写（强制）

草稿生成后、进入人工 review 之前，必须执行：

1. 完整阅读 references/quality-gates.md
2. 对全部场景跑 Q1–Q5，按该文件格式输出自审表
3. 对 FAIL 项执行对应改写动作（fix_vague / fix_step / fix_step_expected / split_umbrella / mark_pending）
4. 再审；最多 2 轮自动改写
5. 2 轮后仍 FAIL：保留 [待确认]，带问题清单进入 Step 6，禁止为清零 FAIL 而灌水补场景

明确不做：验收标准对账硬门禁、按覆盖缺口批量补场景、外部风险/PCI/前置三要素等业务模板。

Step 6: 逐段 review

按 MODULE 逐个展示测试场景，测试同学可补充修改。展示时附带 Step 5.5 未消除的 [待确认] 项（如有）。

Step 7: 覆盖率校验

对照展示三层（展示与人工决策，非硬门禁）：

1. prd 验收标准 → 测点 #
2. 测点 # → 场景标题
3. 未覆盖项：需补充或标记不适用（由测试同学决定）

> 不对账式自动补缺；未覆盖项不自动灌水。

Step 8: 确认 & 写入

默认行为（强制）：自审通过（或 2 轮后仅剩 [待确认]）后，直接写入正式 test/test-spec.md，并更新 metadata.yaml：test_spec.status = confirmed、confirmed_at 为当日；可记录 generator: qa-spec@1.2.0。

• 若已存在正式 test-spec.md：先备份为 test/test-spec.backup-YYYYMMDD.md，再覆盖写入正式文件
• 禁止默认写 test-spec-*-trial.md 等试跑文件名；禁止再询问「是否升格正式」
• 仅当用户明确要求「只出草稿 / 试跑文件」时，才额外写旁路文件；否则一律正式路径
• test/test-points.md 已在 Step 4.5 写入；本步确认其与正式用例一并保留

Step 9: XMind 导出（可选）

询问是否生成 XMind 文件用于导入飞书项目或在 XMind 中编辑。如果确认，执行 /qa-sync-xmind export 流程：

1. 读取 test/test-spec.md
2. 按映射规则转换（参考 qa-sync-xmind 技能的 references/xmind-mapping.md）
3. 探测 MCP 工作目录，调用 create_xmind 生成到 MCP 工作目录（不复制到项目目录）
4. 自动用 open -a "XMind" 打开文件
5. 提示飞书导入与 /qa-sync-xmind import 回写

注意：项目目录中不保存 .xmind 文件，test-spec.md 是用例唯一真相源；test-points.md 为测点中间层。

Step 10: 转为 Case Flow 可执行用例（推荐）

test-spec.md 为 4 级源用例。上传 Case Flow 前，必须先提示用户执行 /qa-case4-case8，不要在本步直接引导 /qa-execute。

收尾提示文案：

> 可选下一步：/qa-case4-case8 转为 8 级可执行用例；完成后再 /qa-execute 上传 Case Flow。需要飞书/XMind 时再用 /qa-sync-xmind export。

Step 11: Case Flow 上传（可选，在 case8 之后）

仅当已产出 8 级嵌套列表 .md（或用户明确已有 Case Flow 直传格式）时，再提示 /qa-execute。

典型顺序：/qa-spec → （可选 /qa-sync-xmind）→ /qa-case4-case8 → /qa-execute

依赖

• mcp-xmind（Step 9，可选）— MCP Server: @41px/mcp-xmind
• 个人 Skill qa-case4-case8（Step 10，推荐）
• Python 3.9+、curl（Step 11，可选）
• 飞书 MCP fetch-doc（Step 0.5，可选）
• superpowers:brainstorming（可选，仅用户明确要求时）

约束

• 输入隔离：绝不读取开发 spec 或 change 目录（决策 D5）
• MODULE ID 与 prd.md 一一对应（决策 D22）
• test-spec.md 是用例唯一真相源，XMind 是派生产物（决策 QA-D1）；test-points.md 是测点中间层
• 测点与用例严格依据 PRD/设计图，禁止随意生成（决策 QA-TP1）
• 测点二检自动执行，不默认人工审测点停顿（决策 QA-TP2）
• 公共写法自审只改表述/结构，不做对账式自动补覆盖（决策 QA-QG1）
• 原型默认读本地 prototypes/；demo 仅补充对齐 MODULE 的交互细节（决策 QA-P1）