Agent 友好性这件事，必须建立在 CI/CD 友好性的基础上。为什么 apifox run 能同时服务 CI 流水线和 AI Agent？双重用途到底意味着什么？

双重受众

设计 Agent 工具时，很容易一门心思扑在怎么跟它聊天、怎么让它更“智能”上。

但有一点必须清楚：Apifox CLI 的另一个重要服务对象，始终是 CI/CD。

原始受众	新受众
CI/CD 流水线	AI Agents
外部调度系统	对话式工作流
脚本与自动化	用户驱动的任务

实际上，很多团队早就在流水线里用 Apifox 来做这些事了：

• 运行 API 自动化测试
• 生成报告
• 维护质量门禁 (Quality Gates)

这样的场景对工具提出了一些硬性要求：

需求	原因
稳定的输出	脚本需要解析可预测的结果
可脚本化的命令	自动化执行的需要
清晰的退出状态码	流水线通过/失败的决策依据
可配置的参数	针对特定环境的运行

千万不能为了让 Agent 用起来更顺手，就把自动化那套流程给搞砸了。

核心原则

Agent 友好性必须建立在 CI/CD 友好性的基础上。

我们没有另起炉灶，去搞一套只有 AI 才能理解的协议。

而是在已经被工程系统验证过的形式上，添上了 Agent 需要的结构化输出、Schema 校验和下一步指引。

Agent 时代，一个优秀的 CLI 工程工具应该能同时服务这么几类人：

消费者	他们的需求
人类	可读的输出、帮助文本、交互式功能
脚本	稳定的输出、可脚本化的命令
CI 流水线	退出状态码、报告文件、可配置的运行
AI Agents	结构化结果、校验、引导

apifox run：核心命令

基础仍然是那个基础：

apifox run --project  --test-scenario  --environment  -r "cli,html,junit" --out-dir ./apifox-reports

这个命令，就是上面那四类消费者的共同入口。

CI 关注什么

CI 需求	CLI 特性
退出状态码	0 表示通过，1 表示失败 —— 流水线决策依据
报告文件	--out-dir 中支持 HTML、JUnit、JSON 格式
稳定的参数	跨版本的选项保持一致
可配置的运行	迭代次数 (-n)、请求延迟 (--delay-request)、环境 (-e)

CI 用起来大概是这样的：

# GitHub Actions
- name: Run API Tests
  run: |
    apifox run --project $PROJECT_ID --test-scenario $SCENARIO_ID --environment $ENV_ID -r "junit" --out-dir ./reports
  env:
    PROJECT_ID: ${{ secrets.APIFOX_PROJECT_ID }}
    SCENARIO_ID: ${{ secrets.APIFOX_SCENARIO_ID }}
    ENV_ID: production
- name: Publish Test Report
  uses: mikepenz/action-junit-report@v3
  with:
    report_paths: './reports/junit.xml'

流程很清晰：流水线读取退出状态码 → 决定通过还是失败 → 发布报告。

Agent 关注什么

Agent 需求	CLI 特性
结构化结果	带有 data 对象的 JSON 输出格式
失败原因	error 对象中的具体错误详情
下一步建议	带有 nextSteps 数组的 agentHints
校验	写入前的 cli-schema validate

Agent 用起来是另一种体验：

{
  "success": true,
  "stats": {
    "total": 10,
    "passed": 8,
    "failed": 2
  },
  "failures": [
    {
      "step": "Payment processing",
      "error": "Assertion failed: status != 'success'",
      "response": {...}
    }
  ],
  "agentHints": {
    "summary": "2 tests failed. Review failure details.",
    "nextSteps": [
      "Debug the Payment processing step failure.",
      "Check assertion: expected status 'success'.",
      "Update test case or endpoint after fixing."
    ]
  }
}

Agent 解析 JSON → 理解失败原因 → 照着下一步建议去执行。

同一命令，不同消费者

apifox run --project  --out-dir ./apifox-reports

消费者	他们提取的内容
CI 流水线	退出状态码 (0/1)、报告文件位置
Agent	JSON 输出、agentHints、失败详情
人类	控制台输出、HTML 报告链接
脚本	标准输出/标准错误、可配置格式

一个命令，就把所有场景都给覆盖了。

集成点

Apifox CLI 跟下面这些主流工具都能集成得很好：

CI 工具	集成方式
Jenkins	流水线步骤、报告发布
GitLab CI	YAML 配置、Artifacts
GitHub Actions	Workflow 步骤、Secret 管理
CircleCI	Orbs、Workflow 配置
Azure DevOps	流水线任务、测试结果

所有集成，核心都围绕着那个 apifox run 命令。

质量门禁 vs. 验证

使用场景	意义
CI 质量门禁	通过/失败决定流水线的推进
Agent 验证	变更后运行以确认正确性

同一个命令，放到不同场景下，意义完全不同：

上下文	何时使用	目的
CI	代码推送后	防止错误代码部署
Agent	测试创建后	确认 Agent 的工作是正确的

基础原则

我们在这个系列里提到的所有东西 —— cli-schema、agentHints、SKILL —— 都建立在这个基础上：

┌─────────────────────────────────────────┐
│                Agent 功能                │
│  (cli-schema, agentHints, SKILL)         │
├─────────────────────────────────────────┤
│              CI/CD 基础                  │
│  (apifox run, 退出状态码, 报告)          │
├─────────────────────────────────────────┤
│               核心 CLI                   │
│  (命令, 参数, 执行)                      │
└─────────────────────────────────────────┘

Agent 的功能并不是要取代 CI 的功能，而是在它之上做扩展。

下一步预告

到现在为止，我们算是把整个图景都给串起来了 —— 从怎么发现问题，到怎么落地工作流，再到这些基础原则。

但还有一个关键环节没讲：安全。

当 Agent 可以修改项目资源的时候，怎么防止它们直接影响到主分支？

在下一部分（第 9 部分 AI Branch：使用 AI Agent 进行更安全的项目变更）里，我们会深入探讨 AI Branch 如何提供一个隔离的编辑环境。

简单来说，就是变更会留在独立的分支里，直到有人工审核通过。这相当于给 Agent 驱动的修改加了一道安全锁。

核心要点

• CI/CD 兼容性是地基，不是可选项。
• Agent 友好性建立在 CI 友好性之上，顺序不能乱。
• 同一个命令 (apifox run)，同时伺候着 CI、Agent、人类和脚本。
• CI 需要：退出状态码、报告、稳定的参数。
• Agent 需要：结构化输出、失败详情、下一步建议。
• 质量门禁 (CI) + 验证 (Agent) = 这就叫双重用途。