Apifox新版命令行与技能上线，让AI智能体稳定使用_AI热点日报

新版ApifoxCLI升级为统一命令行入口，支持AIAgent管理项目全生命周期，提供结构化命令、cli-schema校验、agentHints提示及Skill规则，并引入AI分支隔离编辑风险，确保Agent稳定参与接口开发、测试与维护。

Apifox CLI 最近迎来了一次非常重要的升级。这次升级不仅仅是版本号的跳动，而是从根本上改变了 CLI 的角色——从过去单纯的测试执行工具，变成了 Apifox 的完整命令行入口，直接面向 AI Agent 和自动化工作流。

核心变化可以概括为三点：

新版 CLI 不再是“只能跑测试”的工具，而是 Apifox 的命令行大门
它提供了结构化的命令，覆盖项目资源的全生命周期管理
为 AI Agent 组织并呈现了贴近真实研发流程、可一步步验证的任务步骤

当 AI Coding 和 AI Agent 真正进入研发流程后，CLI 的使命也随之升级。

旧版 Apifox CLI 的核心任务很纯粹——通过 apifox run 在外部系统里跑测试。很多团队把它接入自动化测试流水线，用来执行用例、场景和套件。这个定位很清楚：它就是测试能力的搬运工，把 Apifox 的测试引擎带到 CI 环境里去。

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

这也是本次升级的重点：Apifox 里原本主要靠界面完成的那些操作，现在大都可以通过 CLI 来完成，也就可以交给 AI Agent 去调用。

查看项目、管理接口、创建测试用例、编排场景、校验 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  --project  --environment  --out-dir ./apifox-reports

「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 检查结构对不对：

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 不一样，它不仅关注结果，还得决定下一步怎么走。所以新版 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 不要一上来就手写完整步骤树。因为测试场景里有很多复杂的东西：接口步骤、场景引用、条件、循环、等待、脚本、数据库操作、断言、提取变量和步骤间引用，字段太多，靠模型硬拼很容易出现问题。更稳妥的方式是先创建场景元数据，再导入已有接口、测试用例或其他场景步骤，回读服务端保存后的完整结构，最后只做局部修改。

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 直接编辑主分支或迭代分支，也可以在项目设置里打开对应权限。

一个典型流程是：

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

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

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

可以直接落地的 Agent 工作流

新版 CLI 加上 Skill，最终的价值还是会体现在具体的任务里。

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

如何安装和升级

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

apifox -v

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

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

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

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

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

apifox update
apifox update --yes

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

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，让它完成安装：

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

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

可以先试一个小任务

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

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

请使用 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 更适合细粒度工具调用；新版 CLI 则把读取、校验、写入、回读和测试验证组织成更稳定的命令流程。

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

AI 会直接修改主分支吗？

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

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

新版 Apifox CLI 和 Skill 的核心价值，不只是多了一批命令，而是把 Apifox 的接口资产、测试资产和自动化能力，组织成 Agent 可以稳定执行的工程路径。

在这条路径里：CLI 负责确定性执行，cli-schema 负责写入前校验，agentHints 负责执行后的下一步引导，Skill 负责沉淀任务判断和操作经验，AI 分支负责隔离外部 AI 编辑风险。

过去，Apifox CLI 主要把测试能力带到持续集成和自动化测试流水线。现在，它已经开始把 Apifox 的核心能力带到 AI Agent 和自动化研发流程中。

如果你的团队已经在使用 AI Coding 工具，可以从升级 Apifox CLI、安装配套 Skill 开始，让 Agent 在更可控的流程中使用 Apifox 项目资产。