| name | generate-test-docs |
| description | 自主学习型测试文档生成器。从需求文档（PDF/Word/Markdown）生成测试文档，支持持久化记忆和持续学习。当用户提到"生成测试用例"、"测试计划"、"测试报告"或"根据需求生成测试"时触发。 |
| allowed-tools | Write Read Glob Bash AskUserQuestion |
| compatibility | Requires Python 3, openpyxl, PyMuPDF, python-docx |
自主学习型测试文档生成器
从需求文档自动生成专业测试文档，具备项目感知、持续学习和专业测试设计方法能力。
核心能力
- 专业测试设计方法：等价类划分、边界值分析、场景法、错误推测法
- 需求追溯矩阵：自动生成需求-用例追溯关系，计算覆盖率
- 优先级管理：P0-P3 优先级分类，支持冒烟/核心/全量回归测试集
- 自主学习：学习项目模板、领域术语、命名规范
- 交互式确认：关键节点询问用户，支持快速/专家双模式
交互模式
详见 INTERACTION-PATTERNS.md
模式定义
| 模式 | 名称 | 适用场景 | 确认方式 |
|---|
quick | 快速模式 | 日常生成、熟悉流程 | 回车继续，仅问题时询问 |
expert | 专家模式 | 首次使用、精细控制 | 每阶段确认，完整预览 |
交互检查点
| 检查点 | 阶段 | Quick 模式 | Expert 模式 |
|---|
| 解析确认 | Phase 2.5 | 摘要 + 有问题时询问 | 完整列表 + 等待确认 |
| 歧义处理 | Phase 2.6 | 仅关键歧义 | 所有歧义 |
| 生成预览 | Phase 2.8 | 统计数据 | 统计 + 样例 + 可调整 |
| 输出选择 | Phase 2.9 | 确认默认配置 | 完整格式选择 |
模式切换
- 首次运行：询问用户选择模式
- 命令切换：
切换模式 / 快速模式 / 专家模式
- 偏好存储：
.memory/user-preferences.json
首次使用
检测或询问用户项目结构：
- 模板文件夹路径（默认:
./templates）
- 需求文档路径（默认:
./requirements）
- 创建
.memory 文件夹用于存储学习数据
安装依赖：
pip install openpyxl PyMuPDF python-docx
测试设计方法
详见 TEST-DESIGN-METHODS.md
方法选择指南
| 需求特征 | 推荐方法 |
|---|
| 有明确输入范围/格式要求 | 等价类划分 + 边界值分析 |
| 涉及业务流程/多步骤操作 | 场景法 |
| 历史缺陷多/高风险模块 | 错误推测法 |
核心4种方法
-
等价类划分法 (EP)
- 划分有效/无效等价类
- 一条用例覆盖多个有效类，每个无效类单独覆盖
-
边界值分析法 (BVA)
- 测试边界点：上点、离点、内点
- 对闭区间 [a,b]：测试 a-1, a, b, b+1
-
场景法 (ST)
-
错误推测法 (EG)
- 基于经验推测常见错误
- 补充特殊字符、极端值、并发等测试
用例设计流程
1. 等价类划分 → 识别所有输入的有效/无效等价类
↓
2. 边界值分析 → 对每个等价类的边界进行测试
↓
3. 场景法 → 覆盖主要业务流程（基本流+备选流+异常流）
↓
4. 错误推测 → 补充经验性测试用例
需求追溯与覆盖率
详见 TRACEABILITY.md
追溯矩阵
生成用例时自动关联需求ID，输出包含：
- 正向追溯：需求ID → 关联用例列表
- 反向追溯：用例 → 来源需求
- 覆盖率统计：需求覆盖率、覆盖深度
需求ID提取规则
自动识别需求文档中的ID模式：
REQ_001、REQ-123F1.2、F-3.1.2US_042- JIRA格式：
PROJ-123
若无明确ID，自动生成：MOD_{模块缩写}_{序号}
优先级与回归分类
详见 TEST-PRIORITY.md
优先级定义
| 级别 | 定义 | 来源 |
|---|
| P0 | 核心功能，不可用则系统无法使用 | 基本流用例 |
| P1 | 主要功能，影响核心业务流程 | 备选流 + 边界值 |
| P2 | 次要功能，不影响主流程 | 异常流 + 错误推测 |
| P3 | 体验优化，边缘场景 | 边缘错误推测 |
回归测试集
| 测试集 | 包含用例 | 执行时机 |
|---|
| 冒烟测试 | 所有 P0 | 每次构建 |
| 核心回归 | P0 + P1 | 每日/提测 |
| 全量回归 | 所有 | 发版前 |
项目感知
识别项目结构
- 扫描项目根目录
- 查找
templates/、requirements/、docs/ 等目录
- 识别模板文件和需求文档
- 将识别结果存入
.memory/project-context.json
支持的文档格式
| 格式 | 扩展名 | 提取脚本 |
|---|
| PDF | .pdf | scripts/extract_document.py --format pdf |
| Word | .docx | scripts/extract_document.py --format docx |
| Markdown | .md | 直接读取 |
| 富文本 | .rtf | scripts/extract_document.py --format rtf |
.memory 记忆系统
Skill 在项目中创建 .memory/ 文件夹，存储学习数据：
project-context.json
{
"project_name": "电商平台",
"detected_at": "2024-01-15",
"template_dir": "./templates",
"requirements_dir": "./requirements",
"output_dir": "./test-docs"
}
template-schemas.json
{
"test_case": {
"source": "./templates/测试用例模板.xlsx",
"columns": ["用例编号", "模块名称", "用例标题", "优先级", "关联需求ID", "设计方法", "前置条件", "测试步骤", "预期结果", "实际结果", "是否通过", "回归类型", "备注"],
"id_format": "TC_{module}_{seq:03d}",
"learned_at": "2024-01-15"
}
}
terminology.json
{
"domain_terms": {
"SKU": "库存单位",
"GMV": "商品交易总额"
},
"module_abbreviations": {
"用户登录": "LOGIN",
"购物车": "CART"
}
}
generation-history.json
{
"generations": [
{
"date": "2024-01-15",
"type": "test_case",
"source": "PRD-v1.0.pdf",
"output": "登录模块_测试用例_v1.xlsx",
"case_count": 25,
"coverage_rate": "95%"
}
]
}
Workflow
Phase 0: 项目初始化（首次运行）
- 询问或检测项目结构
- 询问交互模式：Quick（快速）或 Expert（专家）
- 创建
.memory/ 文件夹
- 学习模板结构，存入
template-schemas.json
- 提取领域术语，存入
terminology.json
- 保存用户偏好到
user-preferences.json
Phase 1: 读取需求
- 用户指定需求文档或文件夹
- 调用
scripts/extract_document.py 提取文本
- 返回结构化内容
Phase 2: 解析需求
- 读取
.memory/terminology.json 理解领域术语
- 提取需求ID：识别或生成需求唯一标识
- 结构识别：功能模块、验收条件、业务规则
- 等价类划分：识别输入的有效/无效等价类
- 边界值提取：识别数值、长度、时间边界
- 场景流识别：识别基本流、备选流、异常流
- 错误推测补充：根据输入类型和模块类型触发
- 歧义检测：识别不明确的需求描述
- 参考 PARSING-RULES.md
Phase 2.5: 【检查点1】解析确认
使用 AskUserQuestion 确认解析结果：
Expert 模式：
显示完整解析结果表格：
- 识别的模块列表（名称、需求数、缩写）
- 提取的需求ID列表（ID、名称、验收条件数）
- 识别的业务规则
- 识别的边界条件
等待用户确认：确认 / 修改 / 重新解析
Quick 模式：
显示摘要：已识别 X 个模块，Y 条需求，Z 条规则
仅在发现警告时询问用户
无警告则自动继续
Phase 2.6: 歧义处理
对检测到的歧义需求逐一询问：
需求原文：{text}
歧义类型：边界不明确 / 规则冲突 / 条件缺失
我的理解：{interpretation}
请选择：
1. 接受我的理解
2. 提供不同解释
3. 跳过此需求
4. 标记为待确认
- Expert 模式：询问所有歧义
- Quick 模式：仅询问影响 P0/P1 的关键歧义
Phase 2.8: 【检查点2】生成预览
使用 AskUserQuestion 预览生成方案：
Expert 模式：
显示优先级分布：P0/P1/P2/P3 数量和占比
显示设计方法分布：EP/BVA/ST/EG
显示样例用例：每个优先级展示1条
可选操作：
- 调整优先级分布
- 增加/减少特定类型用例
- 预览特定模块
Quick 模式：
显示统计：将生成 X 条用例，P0:X | P1:X | P2:X | P3:X
仅在分布异常时询问（如 P0 > 20%）
正常则回车继续
Phase 2.9: 【检查点3】输出选择
使用 AskUserQuestion 选择输出格式：
Expert 模式：
多选输出格式：
- Excel 测试用例
- Markdown 测试用例
- 测试计划文档
- 测试报告模板
单选追溯矩阵：
- 包含在Excel中
- 单独生成文件
- 不生成
Quick 模式：
确认默认配置（基于上次选择或默认）：
- ✅ Excel 测试用例（含追溯矩阵）
- ✅ 覆盖率统计
回车确认，或输入"更多"选择其他格式
Phase 3: 生成文档
- 读取
.memory/template-schemas.json 获取模板结构
- 分配优先级：根据用例类型自动判断 P0-P3
- 设置回归类型：根据优先级映射冒烟/核心/全量
- 标记设计方法：EP/BVA/ST/EG
- 关联需求ID：每个用例记录来源需求
- 调用
scripts/generate_excel.py 生成 Excel（含追溯矩阵）
Phase 4: 更新记忆
- 记录本次生成到
generation-history.json
- 如有新术语，更新
terminology.json
- 保存用户偏好到
user-preferences.json
- 如用户反馈，调整学习数据
输出格式
测试用例 Excel
默认列：
| 列名 | 说明 |
|---|
| 用例编号 | TC_{MODULE}_{SEQ:03d} |
| 模块名称 | 功能模块 |
| 用例标题 | 测试点简述 |
| 优先级 | P0/P1/P2/P3（下拉选择，带颜色） |
| 关联需求ID | REQ_XXX（支持多个，逗号分隔） |
| 设计方法 | EP/BVA/ST/EG |
| 前置条件 | 执行前提 |
| 测试步骤 | 详细操作步骤 |
| 预期结果 | 期望行为 |
| 实际结果 | 执行时填写 |
| 是否通过 | 通过/未通过/阻塞/未执行 |
| 回归类型 | 冒烟/核心/全量 |
| 备注 | 补充说明 |
额外 Sheet（启用追溯时）：
- 需求追溯矩阵：需求ID、关联用例、覆盖状态
- 覆盖率统计：总需求数、覆盖率、优先级分布
测试计划 Markdown
固定8章节结构：
- 测试目标
- 测试范围
- 测试策略
- 测试环境
- 测试资源
- 测试进度
- 风险与应对
- 交付物
测试报告 Markdown
固定5章节结构：
- 执行概述
- 测试统计
- 缺陷分析
- 覆盖率报告
- 结论与建议
脚本调用
提取文档
python3 "${SKILL_ROOT}/scripts/extract_document.py" \
--input "/path/to/PRD.pdf" \
--format pdf \
--output "/tmp/prd-content.json"
生成 Excel（带追溯矩阵）
python3 "${SKILL_ROOT}/scripts/generate_excel.py" \
--output "测试用例.xlsx" \
--data '[{"用例编号":"TC_LOGIN_001", "优先级":"P0", "关联需求ID":"REQ_001", ...}]' \
--traceability \
--requirements '[{"id":"REQ_001", "name":"用户登录"}]'
管理记忆
python3 "${SKILL_ROOT}/scripts/memory_manager.py" \
--action init \
--project "/path/to/project"
学习能力
自动学习
- 首次使用时学习模板结构
- 从需求文档积累领域术语
- 识别命名规范并保持一致
用户反馈学习
- 用户修正后，询问是否记住
- 将反馈存入记忆供后续使用
记忆更新命令
"更新术语表" → 重新扫描并更新 terminology.json
"重新学习模板" → 重新解析模板结构
"清除记忆" → 删除 .memory 文件夹
约束
- 需求追溯：所有用例必须关联需求ID
- 方法标记：所有用例必须标记设计方法
- 优先级覆盖：P0 占比 10-15%，P1 占比 30-40%
- 交互确认：Expert 模式下每个检查点必须等待用户确认
- 歧义处理：发现不明确需求时必须询问用户（可配置）
- 模式记忆：用户模式偏好存入
.memory/user-preferences.json
- 遵循项目已有的命名规范
- 不凭空编造需求中不存在的场景
- 默认输出中文，除非项目配置为其他语言
.memory 文件夹应加入 .gitignore（可选）
参考文档
