让 AI Agent 稳定使用 Apifox:新版 CLI + Skill 正式上线!


随着 AI Coding 和 AI Agent 进入研发流程,CLI 要承担的任务也变了。

旧版 Apifox CLI 主要是通过 apifox run 在外部系统里运行测试。很多团队会把它接入自动化测试流程,用来执行 Apifox 里的测试用例、场景用例和测试套件。这个定位很清楚:CLI 主要负责把 Apifox 的测试能力带到外部系统里。

但现在,AI Agent 开始参与接口开发和测试维护。它不只是运行已有测试,还可能要读取接口、补充测试用例、调整场景用例,再根据运行结果继续修改。无论你使用的是 Cursor、Claude Code、Trae、Codex,还是其他支持命令行调用的 Agent,都可以通过新版 Apifox CLI 与 Apifox 项目资产协同工作。

这也是本次 CLI 全面升级的重点:Apifox 里原本主要在界面里完成的很多操作,现在都可以通过 CLI 完成,也就可以交给 AI Agent 来调用。

你可以用 CLI 查看项目和接口,创建或维护测试用例,编排场景用例,校验 JSON 结构,导入导出项目资源,运行测试并生成报告。

也就是说,旧版 CLI 更像一个测试执行工具;新版 CLI 开始变成 Apifox 的命令行入口。它不只是把测试跑起来,也让接口和测试资产的维护进入了自动化和 AI Agent 的工作流。


「新版 CLI」

把 Apifox 能力变成 Agent 可执行的步骤

新版 Apifox CLI 是一个面向自动化测试、项目资源管理和 AI Agent 工作流的命令行工具。除了继续支持通过 apifox run 执行自动化测试,它还提供了结构化命令,覆盖接口、Schema、Mock、环境变量、测试用例、场景用例、测试套件、报告、导入导出和分支协作等资源的增、删、查、改。

基于这些能力,Agent 不再只是触发一次测试,而是可以参与更完整的接口研发与验证流程。例如,当你让 Agent 给某个接口补测试时,它可以先读取接口定义,生成测试用例,通过 cli-schema 校验后写入 Apifox,再回读确认并运行测试。

这条链路可以概括为:

读取接口 -> 生成变更 -> 校验结构 -> 写入 Apifox -> 回读确认 -> 运行测试

对 Agent 来说,关键不只是“能调用更多命令”,而是这些命令被组织成了更贴近研发流程的任务步骤。它不需要在一堆细碎操作里自己摸索顺序,也不需要把所有产品规则都放进上下文里,而是可以围绕真实项目资产,一步步完成可检查、可回读、可验证的任务。

apifox run 的原有使用场景不受影响,仍然可以用于持续集成、自动化测试流水线和外部调度。在 Agent 工作流中,它也可以作为接口或测试资产修改后的验收动作。

apifox test-scenario run


「cli-schema」

写入前先检查 JSON

AI Agent 可以帮你生成测试用例和场景用例,但这些内容最后通常会变成一份复杂 JSON。Apifox 的测试用例和场景用例里,可能包含请求参数、断言、变量提取、前后置操作、脚本、数据集和步骤编排。一旦结构写错,就可能导致写入失败、页面展示不完整,或者测试运行结果不符合预期。

对于这类需要提交复杂 JSON 的创建和更新操作,新版 CLI 提供了 cli-schema。AI 可以先读取对应操作的结构规范,了解字段、枚举值和嵌套结构,再生成 JSON 草稿:

apifox cli-schema get test-case-create
apifox cli-schema get test-scenario-update

生成草稿后,AI 还可以在正式写入 Apifox 之前,用 cli-schema validate 检查 JSON 结构是否正确:

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

这一步可以提前发现字段名、枚举值、嵌套结构等问题。例如变量类型应该是 globals,不是 global;断言比较符应该是 include,不是 contains;响应体 subject 应该是 responseJson,不是 responseBody。

这样一来,AI 不需要把所有字段规则都记在上下文里。它可以先读取结构规范,再生成草稿;校验失败后,根据错误提示修正,再继续写入。问题会尽量暴露在写入 Apifox 之前,而不是写入失败之后反复重试。


「agentHints」

命令执行完,CLI 会提示下一步

传统 CLI 通常只告诉你成功或失败。但 AI Agent 不只是看结果,它还要决定下一步做什么。所以新版 Apifox CLI 在命令输出中加入了 agentHints,它可以在创建资源、写入变更或执行命令后,给出更适合 Agent 理解的下一步建议。

比如 Agent 创建了一个接口,CLI 不只是返回创建成功和资源 ID,还可以提示它接下来配置 Mock、补充接口测试用例,或者运行测试验证。再比如 Agent 创建或修改了场景用例,CLI 可以提示它先回读保存后的结构,再继续修改或运行测试。

这很重要。因为很多资源创建成功之后,服务端可能会补默认值,导入步骤可能会生成新的关联 ID,场景用例里也可能有页面展示依赖的结构细节。如果 Agent 不先回读,就可能继续基于不完整的信息修改。

agentHints 的作用,就是把这些下一步建议直接放到命令结果里,让 Agent 不容易跳步,也不必完全靠猜测推进后续操作。


「Skill」

给 AI Agent 的 Apifox 使用说明

CLI 让 Agent 能执行 Apifox 命令,cli-schema 让 Agent 能在写入前检查 JSON,agentHints 让 Agent 能根据命令结果继续下一步。但这些还不够。Agent 还需要知道一个任务应该归到哪个资源上:是单接口测试用例,还是多步骤测试场景;是直接运行已有套件,还是先补完整场景步骤;是导入 OpenAPI,还是把已有接口导入到测试场景里复用。

这就是 Skill 的作用。它不是一份命令清单,而是一组写给 AI Ag…

— 以上为试看内容(约 40%),开通会员后阅读全文 —