Apifox CLI Agent 工作流 从 PRD 到测试闭环

本文通过一个真实案例，详细拆解API自动化测试的完整流程：某团队刚刚完成“订单退款”的PRD（产品需求文档），代码库中也已备好对应的路由与控制器。接下来，让Agent基于PRD和代码库，自动生成退款功能的API测试并执行校验，以此展示Apifox CLI与SKILL组合的实际落地效果。

场景设定

场景设定清晰明了：团队刚完成“订单退款”的PRD编写，代码库中相应的路由与控制器也已就绪。用户向Agent提出的请求非常直接：“根据PRD和代码库，生成退款功能的API测试，然后运行校验。”

传统方法的局限

如果采用MCP工具处理此类需求，Agent会在多个决策点上陷入反复纠结，难以快速确定路径。以下是典型的困境表现：

最终，Agent将大量精力耗费在“如何行动”的决策上，而非真正执行核心任务。

CLI + SKILL 路径

相比之下，CLI+SKILL方式通过清晰的执行序列，精准映射了真实的研发流程：

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

接下来，我们将一步步拆解这一过程。

步骤 1：生成 OpenAPI 并导入

Agent读取PRD和代码库后，首先生成OpenAPI规范文件。

PRD关键内容摘录如下：

Order Refund API
POST /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", ... } } } }

然后通过CLI命令导入Apifox：

apifox import --project --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优先处理“退款接口”的测试用例。

首先读取接口结构：

apifox endpoint get ep-001 --project

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 --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 --file ./scenario-update.json

步骤 4：运行校验

测试用例与场景准备就绪后，执行最终校验：

apifox run --project --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." ] } }

完整链路

所有元素现已连通，构成一个环环相扣的闭环：

每一步均有据可查，全程可追溯。

贯穿流程的 agentHints

注意 agentHints 如何在每次状态转换后提供明确指引：

Agent永远无需猜测下一步该做什么。

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

核心要点

• 完整工作流：PRD → OpenAPI → 导入 → 测试用例 → 场景 → 校验
• 每一步都配有CLI命令 + 验证机制 + agentHints指引
• 导入步骤结合回读确认，比手动编写场景更安全可靠
• --with-case-detail 参数为更新提供真实的结构参考
• agentHints 引导每一次状态转换
• 整个过程均可验证、可追溯