用途
本技能用于 Apifox 测试场景（test-scenario）的建模与维护，覆盖查询、创建、更新、删除和运行。当用户需要创建或维护复杂自动化测试流程时使用，例如设计多步骤流程（登录 -> 创建资源 -> 查询 -> 断言 -> 清理），编排多种步骤类型、条件分支、循环、等待、脚本、数据库操作或外部程序，处理前置/后置操作、变量引用、变量提取和断言链路，以及排查步骤衔接失败、变量为空、步骤顺序错误等问题。
不适用场景：单个接口下的测试用例应转 apifox-test-case；只运行已有场景、套件或 CI 命令应转 apifox-test-automation；只查看报告按当前 CLI help 使用 test-report；只配置环境、变量、数据库连接按当前 CLI help 使用 environment、variables、database-connection 等命令。
主要能力
- 测试场景的查询、创建、更新、删除和运行。
- 导入接口、单接口用例或其它场景步骤（import-steps）。
- 添加场景引用步骤（add-ref）。
- 复杂步骤编排：接口步骤、条件、循环、等待、脚本、数据库等步骤衔接。
- 前后置操作、变量引用、断言、提取器处理。
- 场景调试与验证。
使用方式
前置条件：先阅读 ../apifox-cli/SKILL.md。若旧总入口与本 skill 的领域规则冲突，以当前 CLI help 和本 skill 为准。涉及单接口 case 时读取 ../apifox-test-case/SKILL.md，涉及执行/CI/报告边界时读取 ../apifox-test-automation/SKILL.md。环境和变量命令以当前 CLI help 为准。具体命令参数以当前 CLI help 为准。
关键事实：test-scenario create 只保存元数据。即使 create payload 里包含 steps，步骤也不会在 create 阶段保存。正确流程是先 create 元数据，再 get --with-case-detail，再用 import-steps、add-ref 或 test-scenario update --file 添加或修改 steps。
常见导入优先使用高层命令，不要手写复杂 HTTP 绑定结构。已验证的入口包括：
apifox test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual
apifox test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual
apifox test-scenario import-steps <scenarioId> --project <projectId> --source test-scenario --from-scenario <sourceScenarioId> --step-ids <stepIds>
apifox test-scenario add-ref <scenarioId> --project <projectId> --scenario <sourceScenarioId>
语义边界：import-steps 是复制/导入为当前场景自己的步骤；add-ref 是添加一个引用其它场景的步骤，不复制源场景内部步骤；--sync manual 是默认模式，适合导入后补业务参数、变量引用和断言；--sync auto 只适用于 endpoint/test-case 来源，test-scenario 来源不支持 auto。CLI 是非交互式命令，缺 ID 时跟随 agentHints 先 list/get 定位。
场景建模标准流程：明确业务目标；确认 project、branch、environment；列出涉及的资源；已有相似场景先 list/get 读取作为模板；用自然语言先设计步骤图再转 JSON；获取 test-scenario-create schema 创建元数据；创建后 get --with-case-detail 回读；导入已有资源优先用 import-steps 或 add-ref；导入后再次回读确认；检查导入步骤的 params、headers、body、脚本变量是否只是 schema 示例值；精细编辑时获取 test-scenario-update schema；cli-schema validate 通过后 update，再回读确认。
步骤设计最佳实践：每个步骤写清 stepName、stepType、input、output、dependsOn、assertions、onError、cleanup。复杂流程建议分层：准备数据、鉴权/登录、主流程操作、结果查询与断言、副作用校验、清理资源。
数据传递和变量引用：步骤间传递数据优先考虑 Apifox 原生“读取前置步骤的运行结果”，例如 {{$.1.response.body.token}}，它只在自动化测试场景中生效，需要运行完整场景。同一数据多次引用或跨模块复用时使用后置操作的提取变量。随机后缀等适合写入环境变量。脚本中使用前置步骤结果时用 pm.variables.get("$.1.response.body.token")。步骤引用依赖步骤 ID/number，插入、删除、重排后必须同步检查。生成 payload 时必须原样保留 {{...}} 占位符。
步骤内容和处理器结构：Apifox CLI 不会自动格式化场景内容，写入前先预格式化字符串字段（接口 Body：requestBody.data；脚本内容：parameters.data；前置/后置脚本：preProcessors[].data、postProcessors[].data）。JSON Body 仍写成字符串，多行内容用 \n 写入。处理器使用扁平结构 { id, type, data, defaultEnable, enable }。提取全局变量时 data.variableType 使用 globals，data.shareScope 优先使用 PROJECT。
断言和脚本规则：常规校验优先用可视化 assertion。引用接口形成 HTTP 步骤时优先使用原接口自带的契约测试/响应校验。可视化断言字段使用当前 schema 枚举：HTTP 状态码用 httpCode，JSON 字段用 responseJson，全文包含用 responseText + include，比较符用 equal。自定义脚本只用于可视化断言覆盖不了的逻辑，脚本断言使用 pm.test(...) 包裹。
前后置和清理规则：前置操作适合鉴权、准备数据、生成随机值、初始化数据库状态；后置操作适合清理测试数据、撤销副作用、释放资源。有副作用的场景必须考虑清理步骤。数据库、外部程序、写入型接口步骤属于高风险操作，执行前确认环境不是生产环境。
常见复杂步骤处理：接口请求步骤先确认 endpoint/case 或直接请求结构；条件分支条件表达式必须基于已存在变量或响应字段；循环/迭代明确最大次数、退出条件和失败策略；等待/轮询明确等待上限；脚本步骤输入输出变量要显式；数据库步骤先确认连接、SQL 只操作测试数据；清理步骤即使主流程失败也尽量能执行。
字段风险提醒：步骤顺序看 number，不要只看回读数组顺序。HTTP 步骤必须带正确接口绑定信息。容器步骤 group/if/else/loop/forEach/onError 必须包含 disable=false、parameters、isOpen=true、children=[]。子步骤放在 children。group 展示名写在 parameters.name。if 和条件 break 使用 parameters.keyVariable + operator + valueVariable。else 和 onError 的 parameters 应为空对象 {}。loop 使用 parameters.count。delay 使用 parameters.timeout，单位毫秒。script 步骤使用 parameters.type="customScript"、parameters.data=<JS code>、enable=true。customHttp 的 URL 字段叫 customHttpRequest.path。testCaseRef 字段是 relatedId。onError 目前存在 CLI/schema/get 成功但客户端展开和配置展示不稳定的风险。
验证和调试规则：cli-schema validate 只保证基础 JSON 结构。更新或导入后先 get --with-case-detail 确认步骤树非空且结构正确，但不要把 get 成功当成可运行。创建、更新或导入步骤后默认先回读确认，不要自动运行；只有用户明确要求运行、调试失败或交付前需要验证可运行性时，才执行 test-scenario run 并检查报告。运行失败时看报告步骤详情。调试复杂场景时不要反复覆盖同一个业务场景，必要时新建版本化场景。
适用场景
- 创建或更新测试场景。
- 设计多步骤自动化流程。
- 编排多种步骤类型、条件分支、循环、等待、脚本、数据库操作或外部程序。
- 处理前置/后置操作、变量引用、变量提取、断言链路。
- 排查场景步骤衔接失败、变量为空、步骤顺序错误、场景创建后前端展示异常。
限制
- 单个接口下的测试用例不适用，应转 apifox-test-case。
- 只运行已有场景、套件或 CI 命令不适用，应转 apifox-test-automation。
- 只查看报告按当前 CLI help 使用 test-report。
- 只配置环境、变量、数据库连接按当前 CLI help 使用 environment、variables、database-connection 等命令。
- test-scenario create 只保存元数据，不保存 steps。
- --sync auto 只适用于 endpoint/test-case 来源，test-scenario 来源不支持 auto。
- cli-schema validate 只保证基础 JSON 结构，不保证 runner、客户端或处理器一定能正确解析。
- onError 目前存在 CLI/schema/get 成功但客户端展开和配置展示不稳定的风险。
- 数据库、外部程序、写入型接口步骤属于高风险操作，执行前确认环境不是生产环境。