API 生命周期工作流
开始前必须读取
../apifox-cli/SKILL.md。若旧总入口与本 workflow 的领域规则冲突，以当前 CLI help 和本 workflow 为准。按步骤再读取apifox-branch、apifox-import-export、apifox-test-case；涉及复杂测试流程时读取apifox-test-scenario，涉及执行和 CI 时读取apifox-test-automation。
具体 endpoint、schema、environment、test-report 命令以当前 CLI help 为准。本流程用于从需求到 API 资产、测试、报告和分支合并的端到端交付，重点关注资源顺序、质量门禁和交付验证。Agent 执行时优先形成 help/schema -> get -> validate -> write -> run/report 闭环，不要仅凭旧文档或记忆写入。
适用场景
- 根据需求创建或更新一组接口。
- 导入 OpenAPI/Postman 后整理接口、Schema、目录和测试。
- 从代码库、PRD、需求文档、测试文档或讨论内容生成 API spec 后导入 Apifox。
- 给接口补 Mock、测试用例、文档和发布设置。
- 在 AI 分支完成 API 变更并准备合并。
工作流
确认项目/分支
-> 如需从代码/文档导入，先做 spec 生成和质量门禁
-> 设计接口和 Schema
-> 配置环境和变量
-> 配置 Mock
-> 创建接口测试用例
-> 运行测试并查看报告
-> 导出/发布文档
-> 合并或创建 MRStep 1：确认上下文
按当前 CLI help 确认身份、项目、目标分支和是否需要 AI 分支。
- 用户要直接改主分支/迭代分支时，确认 AI 写入权限或走 AI 分支。
- 如果通过 AI 分支改已有资源，先用
branch pick-to导入源资源。
Step 2：设计 API 资源
按当前 CLI help 使用 endpoint、schema、response-component、security-scheme、folder 等 API 设计资源命令。
最小边界：endpoint 是接口定义，test-case 是接口下测试用例，不要混写；schema、response-component、security-scheme 等可复用资源应先创建，再由 endpoint 引用；环境变量不要写进 common-parameter。
如果任务是从代码库、PRD 或文档生成并导入 API spec，先读取 ../apifox-import-export/SKILL.md，完成生成器搜索、OpenAPI 指标校验、tags 分组和临时项目导入验证，再进入接口设计或测试补充。
- 先建
schema、response-component、security-scheme等可复用资源，再引用到 endpoint。 - 创建后必须
endpoint get验证真实保存结构。
Step 3：配置环境
按当前 CLI help 使用 environment、variables、database-connection、vault 等环境和运行上下文命令。
- 没有合适环境时创建或更新环境。
- 敏感变量不要出现在最终回复中。
- 运行测试和 CI 交付命令建议显式带
--environment，避免默认环境变化导致不可复现。
Step 4：补测试用例
读取 ../apifox-test-case/SKILL.md。
- 不要创建空壳 case。
- 创建后
test-case get验证步骤、断言、提取器被保存。
Step 5：验证和交付
- 测试报告异常先区分本地报告、云端上传和下载概要；必要时转
apifox-cli-checkup。 - 前端展示异常转
apifox-cli-checkup。 - 需要合并时转
apifox-branch。 - 如果新建 API 的测试运行返回 404 或断言失败，先检查 Mock/环境是否配置，不要直接判定 endpoint 或 test-case 创建失败。Mock 未配置导致运行失败是执行环境问题，不等于设计资产未保存。
不可违反规则
- 不要跳过 project/branch 确认。
- 不要直接在受保护主分支写入。
- 不要只创建接口不验证保存结构。
- 不要只创建空测试用例。
- 不要把测试失败当作接口创建失败；分别定位 API 定义、环境、测试用例和执行报告。
