在探讨 CLI+SKILL 方案之前，需要先明确一点：Apifox MCP 服务不仅依然可用，我们也会持续对其进行维护与更新。
MCP 协议本质上提供了一套标准化的工具连接接口。在以下场景中，它的价值尤为突出：
- 实现简单、定义清晰的单一操作任务
- 满足偏好使用 MCP 工作流的用户群体
- 与遵循 MCP 规范的客户端进行生态集成
因此，我们并非要替代 MCP，而是通过构建 CLI+SKILL 方案作为其有力补充。
从实践经验来看，MCP 的优势在于连接工具，但在面对包含校验、回读与验证等多步骤的复杂研发工作流时，AI 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 是最后一步——只有在其他所有工作均已完成之后，才能轮得到它发挥作用。
新需求涌现：AI Agent 需要更强大的能力
API 开发的格局正在经历一些有趣且深远的变化。
如今，AI Agent 已经开始参与到项目开发的更早期阶段：
| 阶段 | Agent 活动 |
|---|---|
| API 设计 | 根据产品需求文档 (PRD) 自动生成 endpoint 定义 |
| 测试生成 | 依据 API 规范自动创建测试用例 |
| 调试 | 分析测试失败原因，并提供有针对性的修复建议 |
| 迁移 | 跨项目自动化迁移 API 资产 |
| 维护 | 当 API 发生变更时，自动更新相关的测试资产 |
面对这些复杂的、贯穿项目全生命周期的工作流，CLI 的功能绝不能仅仅停留在“运行测试”层面。
它需要一个稳定可靠的接口，来赋予 Agent 以下核心能力：
- 读取 API 资产（例如 endpoints、schemas、environments）
- 创建或更新测试资产（例如 test cases、test scenarios）
- 在将结构化变更写入项目之前进行校验
- 将变更可靠地写回项目
- 验证变更后的最终结果
系统性架构升级，而非简单功能叠加
全新的 Apifox CLI 并非在旧版基础上简单堆砌几个新命令。
它的本质是系统性地将 Apifox 的核心数据与操作能力迁移至命令行环境，使其成为人类开发者、自动化脚本以及 AI Agent 共用的“工程化工作流层”。
| 旧版 CLI 关注的问题 | 新版 CLI 关注的问题 |
|---|---|
| “我该如何从外部运行 Apifox 测试？” | “AI Agent 如何才能稳定、可靠地使用 Apifox 的全部能力？” |
这背后反映的是架构边界的深刻变化。
MCP 与 CLI 的执行链路对比
让我们通过对比，来看清在复杂工作流中，两种方案的典型执行路径。
MCP 路径（适用于工具连接场景）
初始化 MCP 会话↓加载工具列表及工具描述↓Agent 选择所需工具↓搜索更多工具 (listOpenApiEndpoints)↓获取 schema 定义 (getOpenApiDetails)↓执行 HTTP 调用 (executeOpenApi)
MCP 的核心优势在于：它通过标准化协议，将各种工具高效地连接到 AI Agent。
但挑战在于：大部分复杂性都堆积在了“模型上下文理解”和“工具选择”阶段。Agent 需要解析：
- 庞大的工具列表
- 每个工具的描述信息
- 工具的输入 Schemas
- 正确的调用序列
- 返回值的结构含义
因此，它最适合处理“工具到任务映射关系”清晰明确的简单操作。
真正的挑战在于：当工作流复杂度攀升，需要 Agent 编排多个工具、深入理解产品语义并进行各种校验时，MCP 路径会变得异常吃力。
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 执行路径对比
在面对复杂的多步骤工作流时，采用 CLI+SKILL 结构能让 Agent 的执行路径变得异常清晰。
复杂工作流的 MCP 路径
"选择工具 → 理解 Schemas → 编排执行序列 → 处理运行时错误"
Agent 需要反复进行：
- 从大量备选工具中挑选出最合适的
- 深入理解每个工具的说明和参数 Schemas
- 编排并维护正确的执行顺序
- 通过反复重试来处理各类错误
这当然也能实现，但每一个决策点都在大量消耗模型的宝贵推理资源。
复杂工作流的 CLI + SKILL 路径
"读取事实 → 生成变更 → 校验结构 → 写入项目 → 运行验证"
Agent 的任务被分解得极为清晰：
- 首先读取现有事实状态（由 SKILL 引导）
- 基于这些事实生成所需的变更
- 在本地进行结构校验（cli-schema 负责）
- 将变更写入项目
- 触发验证（agentHints 引导下一步）
工程化系统主动承担了校验、引导和验证这些繁杂工作，显著降低了模型在整个上下文理解阶段的计算负担。
虽然两条路径最终都能完成任务，但 CLI+SKILL 路径明显降低了 Agent 在复杂逻辑编排时的出错概率和推理成本。
新版 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、环境、测试用例、测试场景等核心资源的管理。
- 两种方案均可用于生产环境——请根据具体任务的复杂程度进行理性选择。
