让 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，再回读确认并运行测试。

这条链路可以概括为：

Plain 复制代码

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

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

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

Bash 复制代码

apifox test-scenario run  --project  --environment  --out-dir ./apifox-reports

cli-schema：写入前先检查 JSON

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

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

Markdown 复制代码

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

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

Bash 复制代码

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 Agent 的 Apifox 操作规则。比如用户说"帮我给这个接口补测试"，Agent 会根据 Skill 先定位 endpoint，获取有效的测试用例分类，读取已有 case 作为参考，再获取 test-case-create schema，生成 JSON，校验后写入。写入后还要 get 回读，并运行一次确认请求体、断言、变量提取和脚本在 runner 中真正生效。

对于复杂场景用例，Skill 还会约束 Agent 不要一上来手写完整步骤树。因为测试场景里有接口步骤、场景引用、条件、循环、等待、脚本、数据库操作、断言、提取变量和步骤间引用，字段很多，靠模型硬拼很容易出现页面展示不完整或运行时变量为空。更稳的方式是先创建场景元数据，再导入已有接口、测试用例或其它场景步骤，回读服务端保存后的完整结构，最后只做局部修改。

Bash 复制代码

apifox test-scenario import-steps  --project  --source endpoint --ids  --sync manual
apifox test-scenario get  --project  --with-case-detail

以上面的命令为例，这里的关键是 get --with-case-detail。它让 Agent 拿到真实保存后的步骤树、HTTP 详情、请求参数、Body、断言和后置操作，而不是根据零散信息继续猜。后续如果要改断言、补变量提取、调整请求体，Agent 也应该基于这份完整结构修改，再用 cli-schema validate 校验后更新，避免把已有步骤或处理器覆盖掉。这些隐含的流程，不需要特别去记住，已经完美呈现在 Apifox Skill 中，Agent 阅读后即可像个 Apifox 专家一样按需执行。

Skill 也会帮助 Agent 做任务分流和风险判断。单接口验证走 test-case，多步骤业务流程走 test-scenario，回归集合走 test-suite，CI 执行和报告上传走自动化测试相关命令，OpenAPI 或 Apifox 原生格式迁移走导入导出流程，涉及分支写入时再判断是否需要 AI 分支、pick 资源、发起合并请求。这样用户不需要每次都把这些规则重新解释一遍，只要提出目标，Agent 就能按更接近 Apifox 实际使用方式的路径推进。

目前 Apifox 提供了 8 个配套 Skill，覆盖 CLI 通用操作、CLI 使用检查、API 生命周期、测试用例、场景用例、自动化测试、导入导出和分支协作。它们沉淀的不是"有哪些命令"，而是 Agent 在真实项目里应该怎样选择命令、怎样校验结构、怎样回读确认、怎样避免误写，以及什么时候应该停下来让用户确认。

AI 分支：让 Agent 修改项目更可控

新版 CLI 能修改很多项目资源，这也意味着权限更大。如果 Agent 直接改主分支、迭代分支或团队正在协作的通用分支，风险会比较高。所以 Apifox 提供了「AI 分支」，用来承接外部 AI 发起的编辑行为。

Apifox 默认不允许外部 AI 直接编辑主分支、迭代分支和通用分支。Agent 如需修改项目资源，可以在用户确认后创建 AI 分支，并在 AI 分支中完成修改；用户确认差异后，再合并回目标分支。

如果团队明确希望 Agent 直接编辑主分支、迭代分支和通用分支，也可以在项目设置里打开对应权限。

一个典型流程是：

Plain 复制代码

创建 AI 分支 -> Agent 修改资源 -> 回读和运行验证 -> 用户查看差异 -> 合并或创建合并请求

AI 分支用于承接外部 AI 编辑行为，不占用普通迭代分支数量，并会在与源分支无差异后自动归档，避免分支长期堆积。

对团队来说，AI 分支就是给 Agent 修改项目资源时加一层隔离和确认。

可以直接落地的 Agent 工作流

新版 CLI + Skill 的价值，最终会体现在具体任务里。

生成接口测试用例时，Agent 可以先读取接口信息，再生成测试用例 JSON，通过 cli-schema 检查后写入 Apifox，最后回读并运行测试确认结果。
维护复杂场景用例时，Agent 可以先导入已有接口或测试用例步骤，再回读完整结构，最后局部修改断言、变量提取和前后置操作，减少一次性手写复杂结构的风险。
迁移或复现项目资产时，Agent 可以通过 CLI 导出和导入 Apifox 原生格式数据，让接口、Schema、测试用例和场景用例进入自动化处理流程。
对已经在使用自动化测试流水线的团队来说，apifox run 仍然可以作为稳定的测试执行入口。不同的是，在 Agent 参与接口或测试资产修改之后，它也可以作为最后的验证动作。

如何安装和升级

已安装 Apifox CLI 的用户，可以通过下面的命令查看版本：

Bash 复制代码

apifox -v

如果版本低于 2.2.6，建议更新到最新版后使用。首次从旧版升级到新版 CLI 时，建议通过 npm 安装最新版，并同步安装 Apifox Skill：

Markdown 复制代码

npm install -g apifox-cli@latest; npx -y skills add https://apifox.com -y

npm 官方源较慢时，可以使用国内镜像源安装：

Bash 复制代码

npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/; npx -y skills add https://apifox.com -y

升级到新版后*（版本号≥**2.2.5** ）*，后续再更新 CLI，可以使用内置的自更新命令：

Markdown 复制代码

apifox update
apifox update --yes

新版 CLI 仍然兼容旧命令，但后续推荐使用 auth 命令组登录和管理账号，并支持多账号管理：

Bash 复制代码

apifox auth login
apifox auth status
apifox auth switch
apifox auth whoami
apifox auth logout

apifox auth status 可以查看已登录账号和当前正在使用的账号，列表中带 * 的账号就是当前账号
apifox auth switch 可以在不同账号之间切换。对于同时使用官方服务和私有化部署的团队，这样就不需要每次执行命令时都手动拼接 --api-base-url

也可以直接复制下面这句话给正在使用的 AI Agent，让它根据安装说明完成 CLI 和 Skill 的安装：

Plain 复制代码

阅读说明并帮我安装 Apifox CLI：
https://apifox.com/apifox-cli-installation-guide.md

安装、登录、命令参数和常见使用方式，可查看Apifox CLI 帮助文档。

可以先试一个小任务

安装完成后，可以先让 Agent 做一个低风险任务，例如读取项目列表、选择一个项目、创建一个简单的健康检查接口，再回读确认结果。

你可以把下面这段话复制给正在使用的 Agent：

Plain 复制代码

请使用 Apifox CLI 帮我完成一个低风险任务：先检查 CLI 是否可用，并列出我可以访问的项目。等我确认项目后，创建一个 GET /health 接口，名称为 Health Check，返回 200 示例。写入前校验结构，写入后回读确认，并总结创建结果。

这个任务足够小，也能覆盖 Agent 使用 Apifox CLI 的基本路径：检查环境、读取项目、生成变更、写入前校验、写入后回读。

常见问题

Apifox CLI 还能继续用于自动化测试吗？

可以。apifox run 仍然可以继续作为自动化测试执行入口，用于持续集成、外部调度和测试报告生成。

新版 CLI 增强的是 Agent 友好能力，并没有替代原有测试执行场景。

Apifox CLI 和 MCP 有什么不同？

MCP 和 CLI 都是给 AI Agent 调用 Apifox 的工具入口。MCP 更适合细粒度工具调用；新版 Apifox CLI 则把读取、校验、写入、回读和测试验证组织成更稳定的命令流程。

现阶段更推荐使用 Apifox CLI + Skill 。CLI 调用步数更少、上下文占用更低、输出更稳定，也能更好地配合 cli-schema、agentHints 和 AI 分支完成可验证的任务。已有 MCP 使用方式仍可继续使用，新接入的 Agent 工作流建议优先选择 CLI + Skill。

AI 会会直接修改主分支吗？

默认情况下，Apifox 会关闭外部 AI 对主分支、迭代分支和通用分支的直接编辑权限。通过 CLI 或 MCP 发起的编辑，会优先在 AI 分支里完成。用户可以先查看差异，确认后再合并回目标分支。

更多常见问题和命令说明，可以前往Apifox CLI 官方文档查看。

写在最后

新版 Apifox CLI + Skill 的核心价值，不只是多了一批命