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 <endpointId> --project <projectId>
# 写入前校验测试用例结构
apifox cli-schema validate test-case-create --file ./test-case-create.json
# 运行自动化测试作为验收
apifox run --project <projectId> --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": "<resourceId>",
"name": "<resourceName>"
},
"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 <endpointId> --project <projectId>
apifox test-scenario get <scenarioId> --project <projectId> --with-case-detail
# 2. 从既有资产导入步骤，而不是凭空手写复杂 HTTP case
apifox test-scenario import-steps <scenarioId> \
--project <projectId> \
--source endpoint \
--ids <endpointIds> \
--sync manual
# 3. 生成局部更新 JSON，并在写入前校验
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
# 4. 写入后再次回读，再执行测试验收
apifox test-scenario get <scenarioId> --project <projectId> --with-case-detail
apifox run --project <projectId> --out-dir ./apifox-reports
关键不在于命令数量，而在于每一步都有明确目的：读取真实状态，避免猜测；复用已有资产，避免重建复杂结构；写入前校验，避免无效变更；运行测试，避免只完成“看起来写成功了”的操作。
当运行失败时，Agent 也有清晰的恢复路径：读取报告和当前资源状态，缩小修改范围，再次校验与运行，而不是盲目重试一串原子调用。
Agent 友好，不应牺牲 CI/CD 友好
Apifox CLI 长期服务于 CI/CD。流水线需要稳定参数、明确退出码、可解析输出和可归档报告；这些约束不能因为 Agent 体验而被破坏。
新版 CLI 的原则是：Agent 友好建立在 CI/CD 友好之上。
apifox run --project <projectId> --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
