在聊CLI+SKILL之前，我们先明确一件事：Apifox MCP依然可用，并且我们会持续维护它。

MCP这套协议，说白了就是提供了一种标准化的工具连接方式。它在下面这些场景里特别有价值：

• 简单、定义明确的单一操作
• 那些偏爱基于MCP工作流的用户
• 需要跟符合MCP规范的客户端做生态集成

所以，我们不是要取代MCP，而是构建了CLI+SKILL来作为补充方案。

从实践来看，MCP擅长连接工具，但碰到复杂的研发工作流——比如那些包含校验、回读和验证的多步流程——Agent其实更需要的是可执行的工程流程。这正是CLI+SKILL大显身手的地方。

简单理解这张表就清楚了：

任务类型	推荐方案
简单工具调用（例如：获取 endpoint）	MCP 或 CLI —— 两者皆可
多步工作流（例如：创建测试、校验、运行）	CLI + SKILL —— 体验更佳
CI/CD 集成	CLI —— 原生适配
MCP 生态集成	MCP —— 协议标准

旧版 CLI：在流程末端跑测试

长期以来，Apifox CLI 一直是命令行里运行 API 测试的入口。命令行长这样：

apifox run --project  --test-scenario  --environment 

不过，这个基础功能依然重要。团队确实需要一种可靠的方式来：

• 从终端运行 API 测试
• 在 CI 流水线里生成报告
• 在自动化工作流中守住质量关口

但旧版 CLI 主要就是围绕“测试执行”来设计的。它总是出现在工作流的最末端：

设计 → 文档 → Mock → 调试 → 测试 → [CLI 运行测试]

CLI 是最后一步——在所有其他工作都完成后，才轮得上它。

新需求：Agent 需要更多能力

API 开发这件事，正在发生一些有趣的变化。

现在，AI Agent 开始参与到更早的阶段：

阶段	Agent 活动
API 设计	根据 PRD 生成 endpoint 定义
测试生成	根据 API 规范创建测试用例
调试	分析失败原因，提供修复建议
迁移	跨项目迁移 API
维护	当 API 变更时更新测试

面对这些工作流，CLI 不能仅仅是跑个测试那么简单了。

它还需要为 Agent 提供一种稳定的方式，来：

• 读取 API 资产（endpoints、schemas、environments）
• 创建或更新测试资产（test cases、test scenarios）
• 在写入前校验结构化变更
• 将变更写回项目
• 验证结果

系统性扩张，而非增量式添加

全新的 Apifox CLI，不是简单地在旧版 CLI 基础上多加几个命令。

它是系统性地把 Apifox 的核心能力搬进了命令行，让它成为开发者、脚本和 AI Agent 的“工作流层”。

旧版 CLI 关注的问题	新版 CLI 关注的问题
“我如何从外部运行 Apifox 测试？”	“AI Agent 如何稳定地使用 Apifox？”

背后的架构边界，已经发生了巨大的变化。

MCP VS CLI：执行链对比

咱们来对比一下复杂工作流里，两种方案的典型执行链。

MCP 路径（适用于工具连接）

初始化 MCP 会话↓加载工具列表 + 工具描述↓Agent 选择工具↓搜索更多工具 (listOpenApiEndpoints)↓获取 schema (getOpenApiDetails)↓执行 HTTP 调用 (executeOpenApi)

MCP 的优势是：它提供了一个标准化协议，把工具连接到 Agent。

但问题在哪呢？大部分复杂性都堆积在了“模型上下文”和“工具选择”阶段。Agent 要去理解：

• 工具列表
• 工具描述
• 输入 schemas
• 调用序列
• 返回结构

所以，它最适合的还是那些“工具到任务映射关系明确”的简单操作。

挑战在于：当工作流复杂起来，Agent 必须编排多个工具、理解产品语义并处理各种校验，这就比较吃力了。

CLI + SKILL 路径（更适用于复杂工作流）

SKILL 判断任务类型↓CLI 执行产品语义命令↓cli-schema 校验结构↓agentHints 提供下一步建议↓验证循环 (获取回读或运行 apifox run)

CLI+SKILL 的优势，是把复杂性分散到了整个工程系统里。

具体来说：

• SKILL：负责方法论和工作流引导
• CLI：负责产品语义的执行
• cli-schema：负责写入前的校验
• agentHints：负责执行后的导航

它最适合的场景是：多步工作流、重校验操作、以及 Agent 驱动的测试。

核心区别：复杂性存在于何处

这两种方法，最本质的区别就在于“复杂性被放在了哪里”。

方案	复杂性位置	最适合
MCP	模型上下文 + 工具选择阶段	简单工具调用，MCP 生态
CLI + SKILL	工程系统 (SKILL, CLI, 校验, hints)	复杂工作流，多步操作

在 MCP 方案里，模型必须自己扛下很多东西：

• 用哪个工具？
• 工具描述到底说了什么？
• 哪些字段是必填的？
• 该遵循什么执行顺序？
• 返回的结构到底意味着什么？

当任务到工具的映射足够直接时，这套玩法是成立的。但一旦复杂起来，就成了模型的噩梦。

在 CLI+SKILL 方案里，工程系统来帮你分担这些负担：

• 这是什么任务类型？（由 SKILL 判断）
• 该执行什么命令？（由 CLI 执行）
• 什么结构才是有效的？（由 cli-schema 校验）
• 下一步该做什么？（由 agentHints 引导）

所以，当工作流里包含校验关口、回读需求和验证循环时，CLI+SKILL 的效果明显更好。

典型工作流示例

来看一个具体的 CLI+SKILL 工作流例子：

# 步骤 1: 读取事实
apifox endpoint get  --project 

# 步骤 2: 写入前校验
apifox cli-schema validate test-case-create --file ./test-case-create.json

# 步骤 3: 执行验证
apifox run --project  --out-dir ./apifox-reports

这三个命令，代表了三个实实在在的工程动作：

命令	动作
endpoint get	从项目中读取事实
cli-schema validate	在写入前校验结构
apifox run	执行验证

复杂工作流的 Agent 路径

面对复杂的多步骤工作流，Agent 的执行路径会因为采用 CLI+SKILL 结构而变得清晰很多。

复杂工作流的 MCP 路径

"选择工具 → 理解 schemas → 编排序列 → 处理错误"

Agent 需要：

• 从一大堆工具里挑出合适的
• 理解工具描述和 schemas
• 编排正确的执行顺序
• 通过重试来处理错误

这当然也能跑通，但每一个决策点都在消耗大量的模型推理能力。

复杂工作流的 CLI + SKILL 路径

"读取事实 → 生成变更 → 校验结构 → 写入 → 运行验证"

Agent 需要做的就清晰多了：

• 先读取现有事实（由 SKILL 引导）
• 基于事实生成变更
• 在本地校验结构（cli-schema）
• 写入项目
• 运行验证（agentHints 引导下一步）

工程系统把校验、引导和验证这些脏活累活都接过去了，帮模型省下了不少推理的力气。

两条路径都能完成任务，但 CLI+SKILL 明显降低了模型在上下文理解阶段的复杂度。

CLI 目前涵盖的内容

这次升级之后，CLI 能覆盖的 Apifox 核心资源更多了：

资源	CLI 能力
项目与元数据	列出、读取
API 与 API 定义	获取、创建、更新
环境与变量	列出、管理
测试用例	创建、更新、校验
测试场景	创建、更新、导入步骤、获取详情
测试套件	管理
报告	从 apifox run 生成
导入/导出	导出项目、导入文件

这样一来，Apifox CLI 的角色就变了。

它不再仅仅是在一切完成之后才执行的测试工具。

现在，它可以更早地参与到开发循环里——在 Agent 需要理解项目、生成或更新测试资产、校验变更、以及运行验证的时候，它都能顶上。

架构总结

到这里，我们可以把 MCP 和 CLI+SKILL 的核心区别总结一下了：

维度	MCP	CLI + SKILL
主要优势	工具连接	工作流执行
复杂性位置	模型上下文	工程系统
复杂任务的 Agent 路径	选择、编排、重试	读取、校验、写入、验证
覆盖范围	126 个生成的工具 + 原生工具	全资源管理 + 校验
最适合	简单操作，MCP 生态	复杂工作流，CI/CD

两者都可用，按任务需求来选就行。

下一步

既然我们已经明确了 CLI+SKILL 是如何补充 MCP 的，接下来要面对的问题就是：

让 CLI+SKILL 在复杂工作流中真正发挥作用的核心原则是什么？

在第三部分《黄金法则：CLI 产生事实，模型基于事实行动》里，我们会深入探讨指导每一个 CLI+SKILL 决策的设计哲学——就从 cli-schema validate 开始说起，这个质量关口能在错误变成一次失败的写入之前，就把它给捕获住。

核心要点

• MCP 持续发挥作用——把它用于简单操作和 MCP 生态集成。
• CLI + SKILL 是 MCP 的补充——更适合那些带有校验环节的复杂工作流。
• 核心区别在于复杂性被放在了哪里：模型上下文，还是工程系统。
• CLI + SKILL 通过校验、引导和验证，实实在在地减轻了模型的推理负担。
• CLI 现在覆盖了项目、API、环境、测试用例、场景等核心资源。
• 两种方案都可用——根据任务的复杂程度来选择就行。