Apifox CLI + SKILL 正式上线了。

过去，Apifox CLI 最核心的能力是 apifox run。它能在 CI/CD、流水线和外部调度系统中执行场景用例、测试套件，并生成测试报告。这个定位清晰而实用。

但在 AI 时代，它还不够让 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 的理想路径不再是猜测工具和字段，而是：

1. 读取事实
2. 生成变更
3. 校验结构
4. 写入资产
5. 回读结果
6. 运行验证

这条路径并不花哨，但它把模型最容易犯错的环节放到了确定性执行层：真实数据由读取命令提供，结构由校验命令约束，最终结果由运行命令验收。

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