Apifox CLI + SKILL 现已正式发布上线。
过去，Apifox CLI 的核心功能主要围绕 apifox run 展开：在 CI/CD 流水线、外部调度系统中执行场景用例与测试套件，并生成测试报告。这一定位清晰实用，但在人工智能时代，它尚不足以让 Agent 稳定、高效地使用 Apifox。
根本原因在于，Agent 的需求远不止运行测试。它还需要读取接口信息、查询项目数据、理解 Schema 结构、创建或维护测试资产、根据运行结果修正变更，并将最终结果交付给用户验收。对于这类复杂工程任务，真正的挑战并非为 Agent 提供更多工具，而是确保它在正确的时机、以正确的顺序、稳定地完成正确的操作——这正是新版 Apifox CLI + SKILL 的设计初衷。
复杂工程产品接入 Agent，难点不在于“是否支持 MCP”
今年年初，Apifox 推出了全新的 MCP 方案。这个选择非常自然：MCP 正逐步成为 Agent 调用外部能力的重要标准，用户也频繁询问产品是否支持这一协议。
Apifox 沉淀了接口、Schema、环境、Mock、测试用例、测试场景、Runner、报告、分支、导入导出等丰富资产。将这些能力开放给 Agent，本就是必须完成的任务。为此，我们构建了大量 MCP 工具，并为每个工具补充了参数说明、输入 Schema 与返回结构。然而，当真正进入复杂任务场景时，问题逐渐暴露出来。
当 Agent 需要“为某个接口补充测试并运行验证”时，它面对的不是单一清晰的动作，而是一长串候选工具：查询接口、查询用例、创建用例、更新用例、读取 Schema、运行测试、读取报告、查询环境、更新场景步骤。工具越细化，选择空间越大。模型并非不理解每个工具，但在大量候选工具与其他 MCP 服务并存的情况下，持续选择一条可靠的最短路径变得异常困难。
另一个挑战是上下文长度。每个 MCP 工具都包含描述、输入 Schema、字段解释和枚举值。随着工具数量增长，即便用户只提出一个简单任务，模型也可能因承载大量工具说明而承受不必要的上下文负担。
这并非 MCP 协议本身的问题。MCP 对于工具数量有限、能力边界清晰的服务依然非常适用；它也推动了整个行业深入思考 Agent 应如何调用外部系统。但像 Apifox 这样的复杂工程产品，需要解决的不仅是“如何暴露原子能力”，还包括“如何将能力组织成稳定的工程路径”。
CLI：将原子能力收敛为工程动作
新版 Apifox CLI 不再局限于测试执行器。它开始覆盖接口资产、测试资产以及 Agent 工作流中的核心操作。设计重点不是堆砌命令，而是让每条命令对应一个清晰、可检查、可恢复的工程动作。
# 读取接口事实
apifox endpoint get --project
# 写入前校验测试用例结构
apifox cli-schema validate test-case-create --file ./test-case-create.json
# 运行自动化测试作为验收
apifox run --project --out-dir ./apifox-reports
对于“为接口补充测试并验证”的任务，Agent 的理想路径不再是猜测工具和字段，而是：读取事实、生成变更、校验结构、写入资产、回读结果、运行验证。这条路径并不花哨，但它将模型最容易出错的环节放到了确定性执行层：真实数据由读取命令提供，结构由校验命令约束，最终结果由运行命令验收。
Schema 不必常驻，校验应发生在写入前
结构化写入离不开 Schema。没有 Schema，模型很容易猜错字段、枚举值和嵌套结构。问题在于，不应将所有资源的完整 Schema 一开始就放入模型上下文。多数 Schema 只会在某次具体写入时用到，提前全量加载既占用上下文，也不能保证模型真的记对。
因此，Apifox CLI 提供了通用的 cli-schema 校验能力。
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
Agent 可以先生成 JSON 文件，在写入前运行校验；如果校验失败，就根据精确的错误信息修正后再提交。例如，测试资产的前后置步骤涉及变量类型、断言比较符、响应体引用和延时参数等大量约束。让模型记住所有枚举并不可靠，依赖运行时校验则能把结构性错误挡在真正写入之前。规则不一定要塞进模型的上下文，更合适的做法是让规则在需要它的执行节点生效。
agentHints：让结果成为下一步的依据
传统 CLI 的输出主要面向人类：成功时打印成功，失败时打印错误。对 Agent 来说，这还不够。一个创建命令完成后，Agent 需要的不只是资源 ID。它还需要知道是否应该回读资源、先校验后续变更，或运行关联测试。
因此，Apifox CLI 的结构化输出中加入了 agentHints：
{
"success": true,
"data": {
"id": "",
"name": ""
},
"agentHints": {
"summary": "Resource created successfully.",
"nextSteps": [
"Read the created resource before making further changes.",
"Validate update payload with cli-schema before writing.",
"Run related tests after update."
]
}
}
这类提示承载的是产品经验，而非冗长文档。它跟随每次执行结果出现，恰好位于 Agent 决定下一步的时刻。“先回读”尤其重要。服务端可能补充默认值，导入动作可能生成新的关联 ID，复杂资源也可能存在需要保留的内部结构。Agent 如果基于想象继续写入，很容易在下一步产生无效变更。让命令输出带上与当前状态相关的下一步建议，能帮助 Agent 将一次操作衔接进完整工作流，而不是把每条命令当成彼此孤立的动作。
一条完整路径：补测试、修改、验证
以“为一个已有接口补充测试场景并运行验证”为例，Agent 可以按下面的流程工作：
# 1. 读取接口与已有场景，取得真实结构
apifox endpoint get --project
apifox test-scenario get --project --with-case-detail
# 2. 从既有资产导入步骤，而不是凭空手写复杂 HTTP case
apifox test-scenario import-steps --project --source endpoint --ids --sync manual
# 3. 生成局部更新 JSON，并在写入前校验
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
# 4. 写入后再次回读，再执行测试验收
apifox test-scenario get --project --with-case-detail
apifox run --project --out-dir ./apifox-reports
关键不在于命令数量，而在于每一步都有明确目的：读取真实状态，避免猜测；复用已有资产，避免重建复杂结构；写入前校验，避免无效变更；运行测试，避免只完成“看起来写成功了”的操作。当运行失败时，Agent 也有清晰的恢复路径：读取报告和当前资源状态，缩小修改范围，再次校验与运行，而不是盲目重试一串原子调用。
Agent 友好，不应牺牲 CI/CD 友好
Apifox CLI 长期服务于 CI/CD。流水线需要稳定参数、明确退出码、可解析输出和可归档报告；这些约束不能因为 Agent 体验而被破坏。新版 CLI 的原则是：Agent 友好建立在 CI/CD 友好之上。
apifox run --project --out-dir ./apifox-reports
同一条命令可以在 CI 中充当质量门禁，也可以在 Agent 工作流中充当验收动作。前者关心退出码和报告文件，后者关心结构化结果、失败原因与下一步建议。CLI 因而不是一套只服务 AI 的新协议，而是在已经被工程系统验证的执行形态上，补充 Agent 所需的可发现性、结构化反馈与校验机制。
SKILL：告诉 Agent 何时、为何这样做
CLI 提供确定性执行，但它本身不会判断用户意图，也不会自动解释一条工作流中哪些步骤不能省略。这正是 Apifox SKILL 的作用。它不是命令参考手册，而是一组面向任务的判断规则。
例如：
- 什么时候应先读取接口或场景详情；
- 什么时候必须执行
cli-schema validate； - 哪些 ID 或字段不能凭空猜测；
- 什么时候应从已有接口或用例导入步骤；
- 什么时候应使用 AI 分支或迭代分支；
- 什么时候必须通过自动化测试完成验收。
对于熟练用户，这些判断来自经验。对于 Agent，它们需要被清晰地写成可调用的工作规范。
SKILL 承担判断与路径组织，CLI 承担确定性执行，Apifox 管理接口和测试资产，Agent 则负责理解用户目标，并根据反馈推进任务。这比让模型在一面原子工具墙中自行组合流程，更贴近复杂研发工作的真实方式。
从 Spec-First 到 Skill-First
Spec-First 强调先设计接口，再围绕接口文档、Mock、调试、测试和发布展开协作。它让团队拥有一致、可复用的接口事实。AI Coding 出现后，接口资产多了一个重要消费者：Agent。它需要阅读接口、补充测试、运行自动化、理解报告，并判断一次变更是否真的可用。
因此，接口文档、测试用例和测试场景不再只是协作材料，也成为 Agent 可以读取、复用和验证的确定性资产。Skill-First 建立在 Spec-First 的基础上：将接口规范、测试用例和业务场景组织为 Agent 可理解、可执行、可验证、可追踪的能力。
在这个体系中，Apifox 管理资产，CLI 负责执行，SKILL 提供任务判断，Agent 负责理解目标并根据执行反馈调整。这不是用 CLI 取代 MCP，而是为复杂工程产品选择更合适的 Agent 执行层。
立即使用
将下面这句话发送给你正在使用的 Agent，即可阅读安装说明并完成 Apifox CLI + SKILL 的安装：
阅读说明并帮我安装 Apifox CLI：https://apifox.com/apifox-cli-installation-guide.md
或直接安装：
npm install -g apifox-cli@latest --registry=https://registry.npmmirror.com/
Npm 源命令：
npm install -g apifox-cli
