메뉴
将接口文档、OpenAPI、Markdown 接口说明、请求/响应示例转换成可执行的框架原生 API spec（YAML/JSON），并按需导出 Excel/CSV。只要用户的主要输入是 API 文档并且目标是生成可执行 case 或场景规格，都应优先使用这个 skill。当用户说"根据接口文档生成测试用例""先出一版可执行 spec""把这份 OpenAPI 转成 case"时务必使用。即使用户同时提到后续的 flow 配置或执行，当前阶段仍应先由本技能产出原生 spec 再交接。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
TestSpec 需求分析和梳理（流程第 2 步）- 对需求做深度测试分析，运用等价类、边界值、状态迁移等方法，产出 requirements-analysis.md。当用户要「分析需求」「梳理测试点」「做需求分析」「拆解可测项」或执行 testspec-analysis / testspec analysis 时使用。也适用于用户说「这个 PRD 有哪些要测的」「帮我分析一下测试范围」「需求评审准备」的场景。注意：如果用户要的是简短的测试点清单而非深度分析，应使用 testspec-points。
TestSpec 生成测试用例（流程第 4 步）- 根据测试点（specs/*.md）生成完整测试用例并导出 Excel (.xlsx) 或 XMind (.xmind) 格式。当用户要「生成用例」「写测试用例」「导出 Excel」「导出 XMind」「生成测试用例表格」或执行 testspec-generate / testspec generate 时使用。也适用于用户说「把测试点展开成用例」「帮我出一份测试用例表」「生成 Excel 测试文档」的场景。使用内置 Python 脚本完成 Excel/XMind 文件生成，不依赖外部技能。
TestSpec 新建测试工作（流程第 1 步）- 创建测试变更目录，编写 proposal.md，并在用户提供已有 PRD/需求片段时净化成可验收的 requirements.md。当用户要「新建测试」「开始测试」「创建测试变更」「建一个测试项目」或执行 testspec-new / testspec new 时使用。也适用于用户说「我要测 XXX 功能」「帮我准备测试」「有个新需求要测」「帮我整理/审查 PRD」的场景——如果尚无 testspec/changes/ 目录，这是流程的起点。产出 testspec/changes/<name>/ 目录结构、proposal.md，必要时产出 requirements.md。
TestSpec 测试点（流程第 3 步）- 从需求分析中提炼「要测什么」的简短要点清单，产出 specs/testpoints.md。当用户要「写测试点」「提取测试要点」「列出要验证的内容」或执行 testspec-points / testspec points 时使用。也适用于用户说「这个功能要测哪些点」「帮我列测试清单」的场景。与测试用例区分：测试点只列验证目标（What），不写操作步骤（How）。产出供 testspec-generate 展开为完整测试用例。
TestSpec 用例评审（流程第 5 步）- 对生成的测试用例做 14 维度交叉验证（R1-R6 规则检查 + H1-H8 启发式检查），产出 review-report.md 评审报告。当用户要「评审用例」「检查用例质量」「审查测试用例」或执行 testspec-review / testspec review 时使用。也适用于用户说「用例写完了帮我看看」「检查一下覆盖度」「用例有没有问题」的场景。支持默认模式和 --deep 深度模式。
TestSpec 需求源更新与口径收敛（可重复执行的轻量 rebaseline）- 当已有 testspec/changes/<name>/ 后，用户补充、修改、删除、澄清、替换 PRD、接口文档、UI 图、原型图、产品回答、验收规则、权限规则、时间口径、收益映射、字段说明或需求范围时使用。适用于「产品改需求了」「补充接口文档」「新增 UI 图」「删掉这个需求」「同步最新 PRD」「口径收敛」「更新 requirements」「标记旧 analysis 过期」「用例写完后需求变了」「testspec-update / testspec update」。产出更新后的上游需求源、变更影响摘要、blocking_open_questions/dynamic_followups 分类，并标记 stale 下游产物。
| name | apitestspec-composer |
| description | 将接口文档、OpenAPI、Markdown 接口说明、请求/响应示例转换成可执行的框架原生 API spec（YAML/JSON），并按需导出 Excel/CSV。只要用户的主要输入是 API 文档并且目标是生成可执行 case 或场景规格，都应优先使用这个 skill。当用户说"根据接口文档生成测试用例""先出一版可执行 spec""把这份 OpenAPI 转成 case"时务必使用。即使用户同时提到后续的 flow 配置或执行，当前阶段仍应先由本技能产出原生 spec 再交接。 |
把接口文档转换成框架原生 API spec，默认产出 YAML，必要时再导出 JSON、Excel 或 CSV。
当前阶段只负责把“接口说明”变成“可执行 spec”。
YAML / JSON 规格，或先产出原生规格再导出 Excel / CSVapitestspec-surface-scanproject.yaml、flows/*.yaml。这属于 apitestspec-flow-configuratorapitestspec-scenario-runnerallure-results 或报告产物，当前目标是看报告。这属于 apitestspec-result-viewerapitestspec-surface-scanapitestspec-flow-configuratorapitestspec-scenario-runner详见 套件路由表。本 skill 对应阶段 2（有接口文档，但没有原生 spec）。如果用户一次提多个阶段，仍然先完成本阶段再交接。
目标不是写一份“测试建议”，而是把接口说明落成真正可执行的原生 spec，并控制边界，不把本 skill 扩展成 flow 配置或执行。
apitestspec-surface-scandocs/*.yaml、docs/*.jsonExcel / CSVproject.yaml 或 flows/*.yaml当用户需要先落一个最小 case 骨架时，优先使用：
python skills/apitestspec-composer/scripts/bootstrap_spec.py \
--output-dir <dir> \
--case-id <case-id> \
--case-name <case-name>
脚本只产出 cases/*.yaml。project.yaml、flows/*.yaml、config/.env.example 属于 apitestspec-flow-configurator 阶段，不在此处生成。
导出表格只在原生 spec 已存在且用户明确要求时执行：
python skills/apitestspec-composer/scripts/doc_to_excel.py -i <spec-path> -o <excel-path>
python skills/apitestspec-composer/scripts/doc_to_csv.py -i <spec-path> -o <csv-path>
apitestspec-surface-scanYAMLJSON${steps.xxx} 编排数据流转Excel / CSVapitestspec-flow-configuratorapitestspec-scenario-runnerdocs/生成 spec 时，你是测试架构师，不是模板填充器。以下是你应该内化的思维方式：
一个接口的验证不应只有 eq: [status_code, 200]。站在"这个接口可能怎么坏"的角度思考：
list 长度应 ≤ pageSize；批量接口的返回数应与请求数一致pending；审批后状态应变为 approved不要机械地每个接口都堆所有断言——判断哪些断言对这个具体接口有真正的缺陷发现能力。
示例值写 user001 没问题，但负向 case 的请求数据应该真正"坏"：
""、null、完全省略<script>alert(1)</script>、'; DROP TABLE--）这些不是穷举——根据接口的业务含义，挑 2-3 个最可能暴露问题的变异。
当接口文档中包含对同一资源的增删改查时，主动编排多步骤场景：
# 而不是 4 个孤立 case，编排成一个完整的生命周期链
- step: 创建用户
request: { method: POST, url: /users, json: { name: test_user } }
extract: { user_id: $.data.id }
validate:
- eq: [status_code, 201]
- exists: $.data.id
- step: 查询刚创建的用户
request: { method: GET, url: /users/${steps.创建用户.json.data.id} }
validate:
- eq: [$.data.name, test_user]
- step: 删除用户
request: { method: DELETE, url: /users/${steps.创建用户.json.data.id} }
- step: 确认已删除
request: { method: GET, url: /users/${steps.创建用户.json.data.id} }
validate:
- eq: [status_code, 404]
不是所有接口都需要编排——当文档中存在明显的实体生命周期时才这样做。
有些业务逻辑光看 HTTP 响应验证不够（如：删除接口返回 200 但数据库里没真删；转账接口返回成功但余额没变）。当你识别到这类场景时，在 spec 中用注释标注：
# ⚠️ 仅凭 HTTP 响应无法确认数据已物理删除，建议补充数据库层面校验
这是给人看的提示，不是让 runner 执行的逻辑。
YAML，除非用户明确要求 JSON__RANDOM__、__RANDOM_INT__、__DEP:依赖名:字段名__ 之类占位符user001、test@demo.com、1YAML/JSON 原生 spec 和 Excel/CSV 兼容表格使用不同的校验格式。产出时必须根据目标格式选择正确写法。
产出 cases/*.yaml 或 cases/*.json 时使用：
validate:
- eq: [status_code, 200]
- exists: $.data.token
- gte: [$.data.total, 0]
支持运算符：eq、ne、gt、gte、lt、lte、contains、exists。详见 spec-format.md 的断言运算符表。
预期响应校验 列）导出 Excel/CSV 时，预期响应校验 列使用字符串表达式：
==、!=、>、>=、<、<=、contains&&推荐写法：
$.code==200 && $.data.token && $.data.userId$.code==200 && $.data.list && $.data.total>=0$.code==404$.data.username==user001不推荐写法：
$.data.username=="user001"框架的 loader 会自动将表达式格式解析为结构化 validate 列表，两种格式可互转。
以下同时展示两种格式，按当前产出目标选用：
| 场景 | YAML validate | Excel 表达式 |
|---|---|---|
| 登录成功 | eq: [status_code, 200] + exists: $.data.token | $.code==200 && $.data.token && $.data.userId |
| 登录失败 | eq: [status_code, 400] | $.code==400 |
| 列表查询 | eq: [status_code, 200] + gte: [$.data.total, 0] | $.code==200 && $.data.list && $.data.total>=0 |
| 详情 | eq: [status_code, 200] + eq: [$.data.id, 1] | $.code==200 && $.data.id==1 |
| 创建 | eq: [status_code, 200] + exists: $.data.id | $.code==200 && $.data.id && $.data.username==user001 |
| 删除 | eq: [status_code, 200] | $.code==200 |
每条 case 的校验尽量控制在 1 到 3 个子条件内，保证易读、易维护，也便于 runner 定位失败原因。
回答时必须说明：
project.yaml