通过一个真实案例来深入了解：一个团队拥有“订单退款”的 PRD 和代码库。看看 Agent 如何使用 Apifox CLI + SKILL 来生成 OpenAPI、创建测试、验证并进行端到端校验。

场景设定

让我们通过一个真实的流程使一切具体化。

背景：

一个团队刚刚写完“订单退款”的 PRD。代码库中已经有了相应的路由（routes）和控制器（controllers）。

用户对 Agent 的请求：

“根据 PRD 和代码库生成退款功能的 API 测试，然后运行校验。”

传统方法的局限

使用 MCP 工具时，Agent 面临着一系列抉择难题：

决策点	不确定性
先查询项目？	还是先创建接口（endpoint）？
先写测试用例（test case）？	还是先生成 Schema？
直接运行测试？	还是先回读资源？
每一步使用哪个工具？	在 126 个工具中搜索

Agent 花费了大量精力仅仅是在决定路径，而不是执行任务。

CLI + SKILL 路径

CLI + SKILL 通过清晰的序列满足了真实的研发流程：

从 PRD 和代码库生成 OpenAPI↓导入 Apifox↓添加单接口测试用例↓写入前验证↓为业务流生成测试场景↓写入前验证↓运行自动化测试

让我们逐步了解每个步骤。

步骤 1：生成 OpenAPI 并导入

Agent 读取 PRD 和代码库，然后生成 OpenAPI 规范。

PRD 摘录：

Order Refund APIPOST /api/orders/{orderId}/refund- Request body: { "reason": string, "amount": number }- Response: { "refundId": string, "status": string, "processedAt": datetime }GET /api/orders/{orderId}/refund/{refundId}- Response: { "refundId": string, "status": string, "amount": number }

Agent 生成 OpenAPI：

{"openapi": "3.0.0","paths": {"/api/orders/{orderId}/refund": {"post": {"summary": "Create refund request","parameters": [...],"requestBody": {...},"responses": {...}}},"/api/orders/{orderId}/refund/{refundId}": {"get": {"summary": "Get refund status",...}}}}

导入 Apifox：

apifox import --project <projectId> --format openapi --file ./openapi.json

CLI 输出：

{"success": true,"data": {"importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],"endpointIds": ["ep-001", "ep-002"]},"agentHints": {"summary": "OpenAPI imported successfully. 2 endpoints created.","nextSteps": ["List the imported endpoints to confirm structure.","Add test cases for each endpoint.","Create a test scenario for the complete refund flow."]}}

步骤 2：单接口测试用例

Agent 首先关注“退款接口”。

Agent 读取接口：

apifox endpoint get ep-001 --project <projectId>

CLI 返回接口结构：

{"id": "ep-001","method": "POST","path": "/api/orders/{orderId}/refund","requestBody": {"schema": {"type": "object","properties": {"reason": { "type": "string" },"amount": { "type": "number" }},"required": ["reason", "amount"]}},"responses": {"200": {...}}}

Agent 生成测试用例：

{"name": "Create refund - success","endpointId": "ep-001","request": {"path": "/api/orders/order-123/refund","body": {"reason": "Customer request","amount": 99.99}},"assertions": [{"subject": "responseJson.status","comparator": "equal","target": "processed"}]}

写入前验证：

apifox cli-schema validate test-case-create --file ./test-case-create.json

CLI 验证结果：

{"success": true,"agentHints": {"summary": "Test case structure is valid.","nextSteps": ["Create the test case in Apifox.","Read back the created test case to confirm.","Add more assertions if needed."]}}

创建测试用例：

apifox test-case create --project <projectId> --file ./test-case-create.json

CLI 输出：

{"success": true,"data": {"id": "tc-001","name": "Create refund - success"},"agentHints": {"summary": "Test case created successfully.","nextSteps": ["Read back test case tc-001 to confirm assertions.","Create test case for GET /refund/{refundId}.","Build test scenario for complete refund flow."]}}

步骤 3：完整流程的测试场景

根据 PRD，完整的业务流程是：

创建订单 → 支付 → 退款 → 查询退款状态

Agent 生成场景：

{"name": "Order Refund Complete Flow","steps": [{ "type": "case", "caseId": "tc-create-order" },{ "type": "case", "caseId": "tc-pay" },{ "type": "case", "caseId": "tc-001" },{ "type": "case", "caseId": "tc-get-refund" }]}

写入前验证：

apifox cli-schema validate test-scenario-update --file ./scenario-update.json

创建场景：

apifox test-scenario create --project <projectId> --file ./scenario-update.json

步骤 4：运行校验

在测试用例和场景准备就绪后：

apifox run --project <projectId> --test-scenario scenario-001 --environment env-production -r "cli,html,junit" --out-dir ./apifox-reports

CLI 输出：

{"success": true,"stats": {"total": 4,"passed": 4,"failed": 0},"reportFiles": {"cli": "./apifox-reports/cli-report.txt","html": "./apifox-reports/report.html","junit": "./apifox-reports/junit.xml"},"agentHints": {"summary": "All tests passed. 4 steps executed successfully.","nextSteps": ["Review the HTML report for detailed results.","If failures occurred, debug using CLI error details.","Integrate this test into CI pipeline."]}}

完整链路

现在所有元素都已连接：

元素	状态
PRD	已读取并处理
代码库	已分析路由
OpenAPI	已生成并导入
接口资产	已在 Apifox 中创建
单接口测试	已创建并验证
业务场景	已构建并校验

一切都是可验证且可追溯的。

贯穿流程的 agentHints

注意 agentHints 如何引导每一次转换：

之后	agentHints 建议
导入接口	“列出接口，添加测试用例”
创建测试用例	“回读，创建更多测试用例，构建场景”
创建场景	“添加断言，验证，运行”
运行测试	“查看报告，必要时调试，集成到 CI”

Agent 永远不必猜测下一步该做什么。

对比：MCP vs. CLI + SKILL 完成此任务

维度	MCP 方法	CLI + SKILL 方法
起点	Agent 搜索项目工具	SKILL 识别任务类型
接口创建	Agent 猜测使用哪个工具、哪些字段	从 OpenAPI 进行 CLI 导入
测试用例创建	字段错误导致多次重试	写入前进行本地验证
场景构建	Agent 手写结构	导入步骤，回读，更新
校验	Agent 寻找运行工具	场景完成后 agentHints 自动建议
总步骤	约 20-25 次调用（含重试）	约 10-12 次经过验证的调用

下一步

这个实践案例展示了 CLI + SKILL 在真实工作流中是如何运作的。

但在这一切之下还有一个基础：CI/CD 兼容性。

在第 8 部分，为什么 CI/CD 兼容性对 Agent 工具至关重要 中，我们将探讨为什么 apifox run 既能服务于 CI 流水线，也能服务于 AI Agent——以及为什么这种双重用途对于可持续的工具设计至关重要。

核心要点

• 完整工作流：PRD → OpenAPI → 导入 → 测试用例 → 场景 → 校验
• 每一步都有 CLI 命令 + 验证 + agentHints
• 导入步骤 + 回读比手写场景更安全
• --with-case-detail 为更新提供了真实的结构
• agentHints 引导每一次转换
• 一切都是可验证且可追溯的

下载 Apifox，在同一个工作区内完成 API 的 设计、Mock、测试 和 文档 编写。了解更多关于用于命令行 API 测试、CI 自动化和 AI Agent 工作流的 Apifox CLI 的信息。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。