| name | test-case-generator |
| description | 通用测试用例生成引擎，支持从 PRD/API 定义/技术设计文档自动生成高质量测试用例；内置 46 种测试模式（风险/API/业务/错误），支持 5 种输出格式（XMind/Markdown/Excel/JSON/CSV）；当用户需要生成测试用例、编写测试文档、设计测试覆盖方案时使用 |
测试用例生成器
执行入口
立即跳转到执行引擎：execution-engine.md
本文档是轻量级引导，仅指向核心执行控制器。
核心目标
根据 API 定义或需求文档，自动生成结构化、高覆盖、可执行的测试用例。
数据流架构
三层架构
raw-knowledge/ # 原始知识数据层（手动放入）
└── 99-common/ # 通用知识
knowledge/ # 知识层（LLM 自动维护）
input/ # 原始数据层（用户手动存放）
├── prd/ # PRD文档
├── tech-design/ # 技术设计文档
└── images/ # 相关图片
requirements/ # 需求目录（AI自动生成）
└── REQ-XXX-需求名称/
├── input/ # 复制的原始文档
├── extracted/ # 提取的结构化数据
└── output/ # 最终输出
完整数据流：knowledge/（知识参考）+ input/（原始）→ requirements/REQ-XXX/（处理+输出）
数据提取流程（Step 2）
Step 2: 数据提取与结构化（预处理阶段）
当用户提供原始文档时，先执行数据提取：
step_2_data_extraction:
supported_input_formats:
- ".docx - Word文档（pandoc + python-docx）"
- ".pdf - PDF文档（pdfplumber + pytesseract OCR）"
- ".xlsx - Excel表格（pandas + openpyxl）"
- ".pptx - Pow[占位]oint（markitdown + python-pptx）"
- ".png/.jpg/.jpeg - 图片（pytesseract OCR）"
- "飞书文档链接 - docx/wiki（feishu.py）"
auto_execution_scripts:
script_1_docx_extraction:
name: "docx.py"
path: "scripts/extractors/docx.py"
trigger: "input/prd/ 目录存在 .docx 文件"
output:
- "extracted/prd.md"
- "extracted/prd.json"
action: "自动执行Word文档提取"
script_2_tech_design_extraction:
name: "tech_design.py"
path: "scripts/extractors/tech_design.py"
trigger: "input/tech-design/ 目录存在 .docx 文件"
output:
- "extracted/tech-design.md"
- "extracted/tech-design-api.yaml"
- "extracted/tech-design.json"
action: "自动执行技术方案增强提取（API/SQL/表结构识别）"
script_3_image_extraction:
name: "docx.py（内置图片提取）"
path: "scripts/extractors/docx.py"
trigger: "源文档包含图片"
output:
- "extracted/images/"
- "extracted/images-content.md"
- "output/images/"
action: "Word文档提取时自动提取内嵌图片"
script_4_feishu_doc_extraction:
name: "feishu.py"
path: "scripts/extractors/feishu.py"
trigger: "用户提供飞书文档链接（.feishu.cn/docx/ 或 .feishu.cn/wiki/）"
output:
- "extracted/prd.md"
- "extracted/prd.json"
- "extracted/images/feishu/"
action: "通过飞书开放平台API拉取文档内容并转换为Markdown/JSON"
manual_commands:
extract_docx: "python scripts/extractors/docx.py <input.docx> <output_dir>"
extract_tech_design: "python scripts/extractors/tech_design.py <input.docx> <output_dir> [--ai-enhance] [--platform <name>]"
extract_feishu_doc: "python scripts/extractors/feishu.py <feishu_url> <requirements_dir>"
generate_xmind: "python scripts/output/xmind.py <input.md> <output.xmind> [--title '标题']"
image_gate_check: "python scripts/extractors/_image_gate.py <requirements_dir>"
input_sources:
prd_docs:
path: "input/prd/"
output:
- "extracted/prd.md"
- "extracted/prd.json"
- "extracted/api-schema.yaml"
tech_design_docs:
path: "input/tech-design/"
output:
- "extracted/tech-design.md"
- "extracted/tech-design-api.yaml"
image_extraction:
output: "extracted/images-content.md"
primary_method: "AI视觉分析（Claude Vision）"
fallback_method: "Tesseract OCR"
mandatory: true
guide: "references/guides/image-extraction-guide.md"
classification:
- type: "流程图"
extraction: "AI视觉识别流程步骤、决策条件，转换为Mermaid语法"
- type: "表格截图"
extraction: "AI视觉提取表格数据，转换为Markdown表格"
- type: "界面截图"
extraction: "AI视觉识别按钮、字段、提示，提取操作步骤"
- type: "代码/架构图"
extraction: "AI视觉识别方法名、SQL、组件、数据流向"
- type: "数据报表"
extraction: "AI视觉提取关键指标和筛选条件"
- type: "手机界面"
extraction: "AI视觉标注移动端特性和交互"
执行流程（15步）
Step 1:知识上下文 → Step 2:数据提取 → Step 3:需求验证 → Step 4:图片分析闸门
→ Step 5:输入分类 → Step 6:技术方案分析 → Step 7:Pattern路由 → Step 8:风险叠加 → Step 9:扩展生成
→ Step 10:去重规范 → Step 11:优先级判定 → Step 12:覆盖验证 → Step 13:输出格式化
→ Step 14:知识沉淀 → Step 15:自动归档推送 → 输出测试用例集 + 更新知识库
⚠️ 关键特性：内置歧义问题清单收集 + 内联输出
执行前检查清单（必须完成）
pre_execution_checklist:
check_1_demand_identity:
item: "确认当前操作的需求"
action: "读取 extracted/prd.json 中的 metadata.title 和 metadata.source"
confirm: "向用户展示需求名称和来源文档，确认后再继续"
failure_action: "停止执行，要求用户明确需求"
check_2_directory_match:
item: "检查当前目录与需求匹配"
validate: "当前工作目录应包含正确需求编号(如REQ-002)"
on_mismatch: "提示用户切换到正确目录，拒绝执行"
check_3_data_extraction:
item: "检查数据提取完整性"
validate:
- "extracted/prd.json 存在且完整"
- "extracted/tech-design.md 存在（如提供了技术方案）"
- "extracted/images-content.md 存在（如PRD含图片）"
on_missing: "先执行Step 2数据提取"
check_4_image_analysis:
item: "【关键检查】图片AI视觉分析"
critical: true
validate:
- "检测源文档是否包含图片"
- "extracted/images/ 目录存在且非空（如有图片）"
- "extracted/images-content.md 存在且包含分析结果"
- "界面截图识别出字段、按钮、表单"
- "流程图识别出步骤、分支"
action: "使用AI视觉分析识别界面元素、流程、代码细节"
output: "extracted/images-content.md"
AI视觉分析流程（Step 4增强）
ai_vision_analysis:
when: "PRD文档包含图片"
priority: "主方案（优于OCR）"
capabilities:
- "界面截图：识别按钮、输入框、提示文字"
- "流程图：识别决策节点、流程步骤"
- "表格：识别表头、数据行、业务规则"
- "代码截图：识别方法名、SQL、配置"
- "架构图：识别组件、数据流向"
output: "extracted/images-content.md"
usage: "基于识别的细节补充测试用例"
输入来源优先级：
- extracted/prd.json — 首选（结构化数据）
- extracted/prd.md — 次选（完整文本，含图片引用）
- input/prd/*.docx — 备选（原始Word）
技术方案输入优先级：
- extracted/tech-design-api.yaml — 首选（详细接口定义）
- extracted/tech-design.md — 次选（技术方案文本）
- input/tech-design/*.docx — 备选（原始技术方案）
⚠️ 重要：如存在技术方案文档，生成测试用例时必须同时参考 PRD 和技术方案。
输出格式规范
详细定义见 output-schema.md，以下仅摘录核心规则。
文件头部（强制）
必须以 # 测试用例集名称 开头（XMind 中心节点）。
XMind Markdown 格式（必须使用列表形式，禁止标题形式）
# 测试用例集名称
## 一、[P0] 模块名
### 1.1 子模块名
- TC-XXX-001：用例名称
- **优先级**: P0
- **测试方法**: 场景法
- **前置条件**
- 条件1
- 条件2
- **测试步骤**
1. 步骤1
2. 步骤2
- **测试数据**
- 参数1: 值1
- 参数2: 值2
- **预期结果**
- 结果1
- 结果2
错误格式：
❌ 不要这样写：
### TC-XXX-P0: 用例名称
- **前置条件**: ...
- **测试步骤**: ...
文件命名
- current/ 目录：
{需求名}-{格式标识}.{扩展名}（不含版本号）
- versions/ 目录：
{YYYY-MM-DD-N}（日期+序号）
文档加载顺序
执行时按以下顺序加载文档：
- execution-engine.md — 执行入口，读取执行流程
- knowledge/_index.yaml — 加载模块索引（Step 1 知识上下文）
- knowledge/{module}.md — 加载匹配模块的知识文件（按 PRD 关键词匹配）
- knowledge/state-machines/{entity}-states.md — 加载状态机文件
- pattern-registry.md — 获取 Pattern 路由和冲突解决规则
- quality-checks.md — 加载5项强制校验规则
- risk-patterns.md — 加载风险模式（Level 1）
- api-test-patterns.md / business-test-patterns.md — 按输入类型加载（Level 2）
- error-patterns.md — 加载错误模式（Level 3）
- deduplicate-guide.md / normalize-guide.md — 加载去重和规范化规则
注意：knowledge/ 为当前知识层，raw-knowledge/ 为原始数据层。
核心文档索引
系统级（P0 必须加载）
Pattern 层（按优先级加载）
规则与约束
格式规范
质量保障
知识支撑（按需加载）
双层知识架构
| 层级 | 路径 | 职责 |
|---|
| 原始数据层 | raw-knowledge/ | 手动放入业务知识文档（按模块分目录） |
| 知识层 | knowledge/ | LLM 自动维护的精简知识（AI 生成用例时参考） |
扩展：平台特定规则
本项目支持通过 references/platforms/example/ 了解如何添加平台规则。
模板资源（Templates）
专项测试领域（按需加载）
当用户输入包含特定关键词时，加载对应专项测试文档：
注意：部分领域扩展包（如电商/[占位]/财务）位于 references/domain-packs/，不默认加载，需在 pattern-registry.md 中显式注册。
⚠️ 关键执行纪律（防错重点）
1. 图片处理强制流程（最容易遗漏）
这是最容易被遗漏的步骤，必须严格执行：
image_processing_mandatory:
step_1_detect: "检测源文档是否包含图片（Word/PDF/PPT）"
step_2_extract: "提取所有内嵌图片到 extracted/images/"
step_3_analyze: "对每个图片进行AI视觉分析（Claude Vision）"
step_4_document: "输出分析结果到 extracted/images-content.md"
step_5_output: "确保图片可在 output/images/ 访问"
step_6_integrate: "生成测试用例时必须参考 images-content.md"
critical_checkpoints:
- "extracted/images/ 目录存在且非空"
- "extracted/images-content.md 存在且包含详细分析"
- "界面截图识别出所有字段、按钮、表单"
- "流程图识别出所有步骤、分支"
- "output/images/ 可正常访问"
on_failure: "停止执行，不允许跳过图片处理"
reference: "references/guides/image-extraction-guide.md"
2. 需求验证强制步骤（防误操作）
demand_verification_mandatory:
step_1: "读取 extracted/prd.json 确认需求名称和来源"
step_2: "向用户展示需求信息并确认"
step_3: "验证当前目录与需求匹配"
on_mismatch: "停止执行，拒绝在错误目录操作"
强制约束
- 执行入口：必须首先加载 execution-engine.md，不允许其他入口
- Pattern 路由：必须通过 pattern-registry.md 获取路由规则，禁止硬编码
- 图片处理：Step 4 图片分析闸门必须通过，不可跳过
- 风险匹配：Step 8 必须根据业务对象智能匹配 Risk Pattern
- 质量保障：Step 10 去重与规范化是强制步骤
- 覆盖验证：Step 12 5项强制校验必须执行，不达标必须返回补充（最多 3 次）
执行后校验（输出前必须执行）
以下校验在输出测试用例集之前强制执行：
校验 1：优先级分布检查
| 模式 | P0目标 | P1目标 | P2目标 | P3目标 |
|---|
| 快速 | ≤45% | ≥30% | ≥15% | ≥0% |
| 标准 | 25-40% | 30-45% | 15-30% | 5-15% |
| 深度 | 20-30% | 25-35% | 20-30% | 15-25% |
校验 2：风险覆盖检查
- 有状态流转的实体 → 至少触发 STATE-001、STATE-003 中 2 个
- 有数值型字段的实体 → 至少触发 BOUNDARY-001、CONCUR-002 中 2 个
- 涉及并发操作 → 必须有 ≥ 2 条并发用例
- 涉及数据写入 → 必须有 ≥ 1 条数据一致性用例
校验 3：参数覆盖检查
- 边界值：min, max, min-1, max+1（数值型参数）
- 枚举值：所有合法值 + 1 个非法值（枚举型参数）
- 必填：参数缺失场景
校验 4：结构化断言检查
- P0/P1 用例必须包含结构化断言
- 断言类型：SQL、Response、State、DB
快速开始示例
自动化工作流（推荐）
用户只需：把需求文档放在 input/ 目录，告诉我文档路径。
AI自动完成：创建需求目录 → 复制文档 → 数据提取 → 生成测试用例
示例 1：从 input/ 目录生成
用户输入：
为 "input/prd/XX功能PRD.docx" 生成测试用例
AI自动执行：
auto_setup:
- 读取源文档: "input/prd/XX功能PRD.docx"
- 生成目录名: "REQ-003-XX功能"
- 创建目录结构
data_extraction:
- Word → Markdown: "extracted/prd.md"
- Word → JSON: "extracted/prd.json"
- 图片提取到: "output/images/"
test_generation:
- 读取 "extracted/prd.json"
- 执行 15-step 测试用例生成流程
- 输出到: "output/current/test-cases/XX功能-测试用例.md"
注意事项
关键执行纪律（按优先级排序）
-
【最高优先级】图片处理强制流程
- Step 2 必须提取所有内嵌图片到
extracted/images/
- 必须进行AI视觉分析，识别界面元素、流程步骤、代码细节
- 必须输出到
extracted/images-content.md
- 必须确保图片在
output/images/ 可访问
- 生成测试用例时必须参考
images-content.md
- 参考文档：
references/guides/image-extraction-guide.md
- ⚠️ 这是最容易遗漏的步骤，必须严格检查
-
必须先执行 Step 3 需求验证
- 读取 extracted/prd.json 确认需求名称
- 向用户确认当前操作的需求
- 检查当前目录是否与需求匹配
- 不确认不继续
-
AI视觉分析优先于OCR
- PRD图片必须使用AI视觉分析（Claude Vision）
- 识别界面元素、流程步骤、代码细节
- 输出到 extracted/images-content.md
- 基于识别的细节补充测试用例
-
严格按执行流程
- 必须首先加载 execution-engine.md
- 不允许跳过任何步骤，不允许更改执行顺序
- Step 3 需求验证是强制步骤
-
数据提取完整性
- 优先从
extracted/prd.json 读取结构化输入
- 如 extracted/ 目录不存在，先执行 Step 2 数据提取
- 技术方案文档必须同时参考
常见错误预防
| 错误场景 | 后果 | 预防措施 |
|---|
| 操作了错误的需求 | 生成错误需求的用例 | Step 3 强制确认需求身份 |
| 忘记提取图片 | 遗漏界面元素测试场景 | 强制检查extracted/images/目录 |
| 图片未进行AI分析 | 无法识别界面字段和流程 | 强制输出images-content.md |
| 图片位置错误 | 引用失效、无法查看 | 验证output/images/可访问 |
| 图片分析不充分 | 测试用例覆盖不足 | AI视觉分析识别所有字段/按钮/流程 |
| 遗漏技术方案细节 | 接口测试缺失 | 强制检查tech-design.md |
| 覆盖已有用例 | 版本混乱 | 版本策略检查 |
图片处理错误案例分析
错误场景：CRM需求生成时未正确处理图片
问题：
- 没有从Word文档提取内嵌图片
- 没有进行AI视觉分析
- 图片没有放到output/images/目录
- 生成的测试用例缺少界面元素验证
根因：
- Step 2 图片处理流程不明确
- 没有强制检查点
- 未建立images-content.md文件
解决方案（已更新到流程）：
- 新增检查点：Step 4 增加3个图片处理强制检查点
- 新增文档：references/guides/image-extraction-guide.md
- 更新检查清单：执行检查清单增加8项图片相关检查
- 明确流程：AI视觉分析 → 结构化输出 → 整合到prd.md
