generate-test-cases

name	generate-test-cases
description	自主学习型测试文档生成器。从需求文档（Markdown）生成测试用例 XMind 文件，支持持久化记忆和持续学习。当用户提到"生成测试用例"、"根据需求生成测试"时触发。
compatibility	Requires Python 3

根据需求生成测试用例

从需求文档自动生成专业测试用例，具备深度解析、质量自检、自主学习能力。

核心能力

• 深度解析：4 种测试设计方法（EP/BVA/ST/EG）系统性覆盖需求
• 质量内建：覆盖率验证 + 优先级分布检查 + 自检门禁，生成前拦截缺陷
• 需求追溯：自动建立需求↔用例双向追溯矩阵，量化覆盖率
• 自主学习：持久化记忆 + 历史趋势分析 + 歧义决策复用，越用越准
• 交互式确认：快速模式，关键节点人工把关

质量标准

生成的测试用例必须满足以下 7 维度（Phase 2.8 质量预审时逐项检查）：

维度	标准	检查方式
需求覆盖	每条需求至少关联 1 条用例，覆盖率 ≥ 95%	追溯矩阵计算
方法覆盖	每条需求至少使用 1 种设计方法，复杂需求 ≥ 2 种	方法分布统计
优先级分布	P0: 10-15%, P1: 30-40%, P2: 30-40%, P3: 10-20%	分布比例检查
步骤可执行	每条用例的步骤明确、可操作，预期结果可验证	AI 自检
无需求外编造	所有用例来源于需求文档，不凭空编造场景	追溯关系验证
术语一致	用例中使用的术语与需求文档、terminology.json 一致	术语对照
无冗余重复	不同设计方法产生的用例无语义重复；已覆盖的验证目标不得以不同数据状态为由重复生成	去重扫描

交互模式

详见 INTERACTION-PATTERNS.md

采用快速模式：回车继续，仅在发现问题或异常时询问用户。

交互检查点

检查点	阶段	行为
解析确认	Phase 2.5	摘要 + 有问题时询问
歧义处理	Phase 2.6	仅关键歧义
生成预览	Phase 2.8	统计数据

测试设计方法

详细定义与示例见 TEST-DESIGN-METHODS.md

4 种方法按序叠加使用：

EP 等价类划分 → BVA 边界值分析 → ST 场景法 → EG 错误推测

方法	核心动作	触发条件
EP 等价类	划分有效/无效等价类，无效类单独覆盖	有输入范围、格式、枚举约束
BVA 边界值	测试上点、离点、内点	有数值/长度/时间边界
ST 场景法	基本流→备选流→异常流各生成用例	涉及多步骤业务流程
EG 错误推测	补充特殊字符、极端值、并发场景	高风险模块、历史缺陷多

需求追溯与覆盖率

详细规范见 TRACEABILITY.md

• 需求ID：自动识别 REQ-xxx、F1.2、US_042、PROJ-123 等模式；无ID时生成 MOD_{缩写}_{序号}
• 双向追溯：需求→用例 + 用例→需求，Phase 2.8 输出覆盖率统计
• 覆盖率目标：≥ 95%，未覆盖需求在预览中高亮警告

优先级与回归分类

详细规则见 TEST-PRIORITY.md

级别	来源	回归集
P0 核心	基本流用例	冒烟测试（每次构建）
P1 主要	备选流 + 边界值	核心回归（每日/提测）
P2 次要	异常流 + 错误推测	全量回归（发版前）
P3 边缘	边缘错误推测	全量回归（发版前）

.memory 记忆系统

完整 Schema 定义见 MEMORY-SCHEMA.md

Skill 在项目中创建 .memory/ 文件夹，存储跨会话学习数据：

.memory/
├── project-context.json      # 项目上下文（路径、名称）
├── terminology.json          # 领域术语库（自动学习 + 手动补充）
├── generation-history.json   # 生成历史（质量趋势分析）
├── user-preferences.json     # 用户偏好（交互模式、默认标签）
└── ambiguity-decisions.json  # 歧义决策记录（避免重复询问）

核心机制：

• 每次生成自动写入 generation-history.json（含覆盖率、优先级分布、标签）
• 歧义处理决策写入 ambiguity-decisions.json，后续相似歧义自动复用
• 用户修正的术语、偏好自动持久化，下次会话即刻生效

Workflow

Phase 0: 项目初始化（首次运行）

1. 检测项目结构（扫描 requirements/、test-docs/ 等目录）
2. 创建 .memory/ 文件夹（memory_manager.py --action init）
3. 从需求文档提取领域术语，存入 terminology.json
4. 保存用户偏好到 user-preferences.json

Phase 1: 读取需求

1. 直接读取 requirements/ 目录下所有 .md 文件，按文件名排序，文件间以 --- 分隔，拼接为完整需求文本
2. 读取 requirements/ 目录下所有图片文件（.png、.jpg、.jpeg、.gif、.webp、.bmp、.svg），与需求文本一起作为多模态输入
3. 以上述内容进入 Phase 2 解析

Phase 2: 解析需求

1. 加载记忆并应用：
   • 读取 terminology.json → 解析时统一术语，避免同义词重复
   • 读取 ambiguity-decisions.json → 相似歧义自动复用历史决策，跳过询问
   • 读取 generation-history.json → 提取历史优先级分布作为基线，识别历史常见遗漏场景类型并主动补充
   • 读取 user-preferences.json → 应用用户步骤粒度、标题风格等偏好
2. 提取需求ID：识别或生成需求唯一标识
3. 结构识别：功能模块、验收条件、业务规则
4. 系统性测试设计（按 EP→BVA→ST→EG 顺序叠加）：
   • 等价类划分：识别所有输入的有效/无效等价类
   • 边界值提取：识别数值、长度、时间边界
   • 场景流识别：基本流、备选流、异常流
   • 错误推测补充：根据输入类型和模块风险等级触发
   • 业务规则补充：参考 BUSINESS-RULES.md，匹配需求涉及的功能类型（列表、输入框、按钮等）自动追加对应规则用例
5. 去重扫描：不同方法产生的用例可能语义重复（如 EP 无效类与 EG 错误推测场景重叠），合并等价用例，保留更具体的那条。
   • 状态变体去重：若某条规则已被一个清晰的用例验证，不要再以"不同数据状态"为由生成同等验证目标的变体用例。
     • ✅ 已有「系统报表展示【系统】标签」+ 「自定义报表不展示【系统】标签」→ 不需要再生成「仅存在自定义报表时不显示标签」「新增系统报表后自动显示标签」「删除系统报表后自定义报表仍不显示标签」，因为验证目标完全相同，只是前置数据状态不同
     • 判断标准：新用例的验证目标（"验什么"）是否已被现有用例覆盖，若是则丢弃；只有"验什么"不同才保留
   • 场景修饰词变体去重：不要在已有用例的基础上，通过添加"混合时""同时存在时""共存时"等场景修饰词生成新用例，若验证目标实质相同则合并。
     • ✅ 已有「系统汇总表排在上方自定义汇总表排在下方」→ 不需要再生成「存在系统表和自定义表混合时排序规则正确」，因为"混合场景"本就是前者的前置条件，两者验证目标完全相同
     • 判断标准：去掉修饰词后，两条用例核心断言（"系统在上、自定义在下"）是否一致，一致则合并，保留表述更明确的那条
6. 歧义检测：识别不明确的需求描述；与 ambiguity-decisions.json 比对，相似歧义自动复用历史决策
7. 覆盖率预计算：统计需求→用例映射，标记未覆盖需求
8. 参考 PARSING-RULES.md

Phase 2.5: 【检查点1】解析确认

使用 AskUserQuestion 确认解析结果：

已识别 X 个模块，Y 条需求，Z 条规则

ℹ️ 标签：使用上次选择「{default_tag}」（或首次询问）

仅在发现警告或无 default_tag 时询问用户
无警告且有 default_tag 则自动继续

当无 default_tag 或发现警告时，在此阶段询问标签（适用端）。询问前先检查需求文档是否有显式平台声明：

• 若需求中存在类似 tag只适用于PC端、仅适用于APP、适用端：小程序 等直接声明语句，直接读取并应用，不得询问用户，并在摘要中提示 ℹ️ 标签：从需求文档读取「{tag}」
• 若需求中没有显式声明，则展示如下选项询问：

本次用例适用哪些端？请输入编号或直接填写：
1. PC
2. APP
3. C端
4. PC, APP
5. 小程序
6. 其他（请说明）

重要：标签问题在此阶段完成后，Phase 2.6 / 2.8 及后续所有阶段不得再次询问适用端，即使将其视为歧义也不例外。

Phase 2.6: 歧义处理

对检测到的歧义需求逐一询问：

需求原文：{text}
歧义类型：边界不明确 / 规则冲突 / 条件缺失
我的理解：{interpretation}

请选择：
1. 接受我的理解
2. 提供不同解释
3. 跳过此需求
4. 标记为待确认

• 仅询问影响 P0/P1 的关键歧义，其他歧义自动采用 AI 理解并标注

Phase 2.8: 【检查点2】质量预审 & 生成预览

使用 AskUserQuestion 预览生成方案：

质量自检（不通过则修正后再展示）：

□ 覆盖率 ≥ 95%（未覆盖需求列表高亮）
□ P0 占比 10-15%
□ P1 占比 30-40%
□ 每条需求至少关联 1 种设计方法
□ 无需求外编造的场景
□ 无语义重复用例

将生成 X 条用例 | 覆盖率 ZZ% | P0:X P1:X P2:X P3:X

仅在质量自检不通过时询问
通过则回车继续

Phase 3: 生成文档

1. 分配优先级：根据用例类型自动判断 P0-P3
2. 关联需求ID：每个用例记录来源需求
3. 用例写作规范：
   • 标题格式：动作 + 对象 + 条件/场景，禁用模糊词（“正常”“正确”）
   • 步骤粒度：每步只做一件事，禁止多动作合并（如"输入用户名并点击登录"应拆为两步）；步骤只写操作，禁止在步骤中使用"验证""检查""确认"等验证类动词
   • 步骤编号：每条操作以 N. 起始（如 1. 打开登录页面），对应预期结果使用相同编号（如 1. 显示账号密码输入框），编号从 1 开始连续递增，steps 与预期结果数组长度必须相等
   • 预期结果：必须可验证，包含具体数据/状态，禁用"系统正常处理""正常显示"等模糊描述；一个步骤有多个验证点时用逗号连接写在同一条预期结果中，不拆分步骤
   • 前置条件：仅当需要特定环境准备时填写，避免写"用户已登录"这类显而易见的内容
   • 业务规则扩充（BUSINESS-RULES.md）属于合理推断范围，不受"无编造"约束限制
   • 应用 user-preferences.json 中存储的步骤粒度、标题风格偏好
4. 将用例组织为 JSON 数组，写入项目临时文件 tmp/cases_<时间戳>.json（如 tmp/cases_20260225143022.json），目录不存在时自动创建

• 时间戳必须为 14 位：YYYYmmddHHMMSS（正则：^\d{14}$）
• 禁止仅日期命名（如 tmp/cases_20260226.json）

4. 调用 scripts/generate_xmind.py -f tmp/cases_<时间戳>.json 生成 XMind 文件，输出路径固定为 test-docs/testcases_<时间戳>.xmind

Phase 4: 更新记忆（自学习闭环）

完整学习规则见 LEARNING-RULES.md

1. 生成历史：写入 generation-history.json，包含覆盖率、优先级分布、用例数、标签、来源文件
2. 歧义决策：将 Phase 2.6 中用户的歧义处理决策写入 ambiguity-decisions.json，后续相似歧义自动复用
3. 新术语：如解析中发现新术语，更新 terminology.json
4. 用户偏好：保存默认标签等到 user-preferences.json
5. 质量趋势：与历史记录对比，生成趋势摘要（如覆盖率是否提升、用例数变化）

Phase 5: 用户反馈学习（生成后可选）

用户对生成结果提出修改时，自动触发学习：

反馈类型	示例	学习动作
纠正错误	“这条用例逻辑不对”	重新生成 + 记录歧义模式到 ambiguity-decisions.json
删减用例	“P2 太多了”	询问“是否调整优先级分布作为默认？”→ 写入 user-preferences.json
补充场景	“还缺并发场景”	增补用例 + 记录为常见遗漏到 generation-history.json
修改术语	“这里应该叫 XXX”	询问“是否记住？”→ 写入 terminology.json
调整步骤	“步骤太细了，合并一下”	询问“是否记住这个粒度偏好？”→ 写入 user-preferences.json

输出格式

测试用例 XMind

固定节点结构（符合 XMind 导入规范）：

根节点（项目名称）
  └── 模块（最多8层）
        └── tc-p0: 用例标题  /  tc: 用例标题（无优先级时）
              ├── pc: 前置条件（非必填）
              ├── 步骤1
              │     └── 预期结果1
              ├── 步骤2
              │     └── 预期结果2
              └── tag: 标签1,标签2（非必填）

AI 生成用例时输出的 JSON 字段：

字段	必填	说明
模块	✅	数组，最多8层，如 ["登录", "账号密码"]。末级目录按功能区域分组，不以单个功能点命名，规则见下方「模块分组规则」
用例标题	✅	格式：动作 + 对象 + 条件/场景，如“输入正确账号密码登录成功”
优先级	✅	P0/P1/P2/P3，影响节点前缀
需求ID	✅	关联的需求标识，如 REQ-001、MOD_LOGIN_001
设计方法	✅	EP/BVA/ST/EG 之一或多个，如 ["EP", "BVA"]
前置条件	❌	生成 pc: 子节点
步骤	✅	[{"操作": "1. ...", "预期": "1. ..."}]，操作与预期均以数字序号起始，同一步骤编号一致
标签	✅	测试端标识，多端用逗号+空格分隔，如 PC、APP、PC, APP

模块分组规则：

末级目录必须按功能区域归类，而非按单个功能点各自建目录。同一功能区域的所有用例共用同一个末级目录节点。

功能区域	末级目录名	包含的用例范围
列表展示、排序、标签、筛选、搜索	列表	列表页面上能看到的所有内容
新增/创建表单	新增	点击新增按钮后的页面/弹窗
编辑表单	编辑	编辑页面/弹窗相关用例
详情页	详情	查看详情页面相关用例
删除操作	删除	删除相关用例
导出功能	导出	导出相关用例
导入功能	导入	导入相关用例
权限控制	权限	权限相关用例

✅ 正确示例（汇总表需求含标签展示+排序逻辑，全部归入「列表」）：

{"模块": ["汇总表", "列表"], "用例标题": "系统报表展示【系统】标签"}
{"模块": ["汇总表", "列表"], "用例标题": "自定义报表不展示【系统】标签"}
{"模块": ["汇总表", "列表"], "用例标题": "系统汇总表排在上方自定义汇总表排在下方"}

❌ 错误示例（为每个功能点各建一个目录，导致目录过多）：

{"模块": ["汇总表", "系统报表标签"], "用例标题": "系统报表展示【系统】标签"}
{"模块": ["汇总表", "自定义报表标签"], "用例标题": "自定义报表不展示【系统】标签"}
{"模块": ["汇总表", "列表排序"], "用例标题": "系统汇总表排在上方自定义汇总表排在下方"}

JSON 完整示例：

{
  "模块": ["用户登录", "账号密码登录"],
  "用例标题": "输入正确账号密码登录成功",
  "优先级": "P0",
  "需求ID": "REQ-001",
  "设计方法": ["ST"],
  "前置条件": "用户已注册账号，且处于未登录状态",
  "步骤": [
    {"操作": "1. 打开登录页面", "预期": "1. 显示账号、密码输入框和登录按钮"},
    {"操作": "2. 输入正确的账号和密码", "预期": "2. 输入内容正常显示，密码为密文"},
    {"操作": "3. 点击登录按钮", "预期": "3. 登录成功，跳转到首页"}
  ],
  "标签": "C端"
}

标签取值规则：

• 显式声明优先：需求文档中若有明确的平台声明语句（如 tag只适用于PC端、适用端：APP），直接读取该值写入标签，无需询问用户。
• 禁止隐式推断：需求中未显式声明平台时，不得根据功能描述（如"用户在PC端操作"、"移动端约课"等上下文）自动推断标签；必须在 Phase 2.5 询问用户。
• 在 Phase 2.5 解析确认阶段统一处理一次，全程只处理一次，不得在 Phase 2.6、Phase 2.8 或生成阶段重复询问。
• 将用户输入（包括编号对应的文字）原样写入每条用例的 标签 字段，严禁对用户答案做任何翻译、展开或同义替换（例如：用户填 C端 就写 C端，不得改为 PC, APP；用户填 3 就写 C端，不得改为别的）。
• 所有用例共用同一答案，除非某条用例有用户明确指定的例外。

脚本调用

生成 XMind

# 时间戳格式：YYYYmmddHHMMSS
TIMESTAMP=$(date +%Y%m%d%H%M%S)
mkdir -p "${SKILL_ROOT}/tmp"
# 先将用例 JSON 写入临时文件
cat > "${SKILL_ROOT}/tmp/cases_${TIMESTAMP}.json" << 'EOF'
[{...}]
EOF
# 再生成 XMind
python3 "${SKILL_ROOT}/scripts/generate_xmind.py" \
  --title "项目名称" \
  --output "test-docs/testcases_${TIMESTAMP}.xmind" \
  -f "${SKILL_ROOT}/tmp/cases_${TIMESTAMP}.json"

管理记忆

# 初始化
python3 "${SKILL_ROOT}/scripts/memory_manager.py" \
  --action init \
  --project "${SKILL_ROOT}"

# 记录本次生成历史（Phase 4 使用）
python3 "${SKILL_ROOT}/scripts/memory_manager.py" \
  --action add-record \
  --project "${SKILL_ROOT}" \
  --data '{"type":"test_case","source":"requirements/xxx.md","output":"test-docs/xxx.xmind","case_count":40,"coverage_rate":"100%"}'

自学习闭环

完整学习规则见 LEARNING-RULES.md

越用越准的核心机制：

写入端（Phase 4/5）                    读取端（Phase 2）
─────────────────────                ─────────────────────
生成历史 ───→ generation-history.json ──→ 优先级基线 + 遗漏场景补充
歧义决策 ───→ ambiguity-decisions.json ─→ 相似歧义自动复用
新术语   ───→ terminology.json ────────→ 术语统一 + 缩写展开
用户偏好 ───→ user-preferences.json ────→ 标签/粒度/风格自动应用
用户反馈 ───→ 分发到以上各文件 ──────────→ 下次生成自动避免相同问题

记忆命令："更新术语表" / "清除记忆" / "查看偏好" → 调用 memory_manager.py 对应 action。

约束

质量底线

• 需求追溯：所有用例必须关联需求ID，不允许悬空用例
• 方法标记：所有用例必须标记至少 1 种设计方法
• 优先级分布：P0: 10-15%, P1: 30-40%，P2 补足剩余，P3 ≤ 20%（异常时 Phase 2.8 拦截）
• 覆盖率：≥ 95%（未达标时 Phase 2.8 高亮警告）
• 无编造：不凭空编造需求中不存在的场景
• 无冗余：不同设计方法产生的语义重复用例必须合并

标签规则

• 需求有显式平台声明时直接读取，无需询问
• 无显式声明时在 Phase 2.5 询问一次，全程不再重复询问
• 用户输入原样写入，禁止翻译、展开或同义替换

交互规则

• 仅在发现问题/异常时询问用户
• 无异常时自动继续执行

其他

• 遵循项目已有命名规范
• 文件命名中的 <时间戳> 必须使用 YYYYmmddHHMMSS（14 位），不得使用仅日期（8 位）格式
• 默认输出中文，除非项目配置为其他语言
• .memory 文件夹应加入 .gitignore
• 禁止复用 tmp/ 缓存：每次生成均从 Phase 1 重新开始，不得读取 tmp/ 中已有的 JSON 文件跳过生成步骤

参考文档

• INTERACTION-PATTERNS.md - 交互模式与问题模板
• TEST-DESIGN-METHODS.md - 核心4种测试设计方法详解
• TRACEABILITY.md - 需求追溯矩阵规范
• TEST-PRIORITY.md - 优先级与回归分类
• PARSING-RULES.md - 需求解析规则
• MEMORY-SCHEMA.md - 记忆文件结构
• LEARNING-RULES.md - 学习规则
• BUSINESS-RULES.md - 业务测试规则（列表、输入框、按钮等通用场景）