从 PRD 到测试闭环：使用 Apifox CLI 的完整 Agent 工作流

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

场景设定

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

背景：

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

用户对 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",
        ...
      }
    }
  }
}

导入 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."
    ]
  }
}

完整链路

现在所有元素都已连接：

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

贯穿流程的 agentHints

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

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

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

下一步

这个实践案例展示了 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 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名