我们为何开发了全新的 Apifox CLI + SKILL

在切入CLI+SKILL主题之前，我们需先确认一个前提：Apifox MCP仍在运行并持续维护，这为后续对比提供了基础。

MCP遵循协议提供了标准化的工具连接，这对于以下场景非常有价值：

1. 简单、定义明确的操作
2. 偏好基于MCP工作流的用户
3. 与符合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 <projectId> --test-scenario <scenarioId> --environment <environmentId>

这个基础仍然很重要。团队需要一种可靠的方式来：

1. 从终端运行API测试
2. 在CI流水线中生成报告
3. 在自动化工作流中保留质量关口

但旧版CLI主要围绕测试执行展开。它出现在工作流的末端：

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

CLI是最后一步 —— 在其他所有工作完成后进行。

新需求：Agent 需要更多能力

API开发正在发生变化。

AI Agent现在正参与到以下阶段：

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

对于这些工作流，CLI不能仅仅是运行现有测试的最后一步。

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

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

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

全新的Apifox CLI不仅仅是在旧版CLI基础上增加几个命令。

它是系统性地将Apifox的核心能力引入CLI，使其成为开发者、脚本和AI Agent的工作流层。

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

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

MCP VS CLI：执行链对比

让我们对比一下复杂工作流的典型执行链。

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

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

MCP的优势：将工具连接到Agent的标准化协议。

复杂性位置：大部分复杂性存在于模型上下文和工具选择阶段。Agent需要理解：

1. 工具列表
2. 工具描述
3. 输入 schemas
4. 调用序列
5. 返回结构

适用场景：具有明确工具到任务映射的简单操作。

挑战所在：Agent必须编排多个工具、理解产品语义并处理校验的复杂工作流。

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

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

CLI + SKILL的优势：将复杂性分散到工程系统中。

复杂性位置：

1. SKILL：方法论和工作流引导
2. CLI：产品语义执行
3. cli-schema：写入前的校验
4. agentHints：执行后的导航

适用场景：多步工作流、重校验操作、Agent驱动的测试。

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

这两种方法之间的区别在于复杂性被放置在哪里。

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

在MCP中，模型必须承载：

1. 使用哪个工具
2. 工具描述说了什么
3. 哪些字段是必填的
4. 遵循什么序列
5. 返回结构意味着什么

当任务到工具的映射很直接时，这种方式行之有效。

在CLI + SKILL中，工程系统承载：

1. 这是什么任务类型 (SKILL)
2. 执行什么命令 (CLI)
3. 什么结构是有效的 (cli-schema)
4. 下一步做什么 (agentHints)

当工作流具有校验关口、回读需求和验证循环时，这种方式效果更好。

典型工作流示例

这是一个CLI + SKILL工作流的具体示例：

# 步骤 1: 读取事实
apifox endpoint get <endpointId> --project <projectId>
# 步骤 2: 写入前校验
apifox cli-schema validate test-case-create --file ./test-case-create.json
# 步骤 3: 执行验证
apifox run --project <projectId> --out-dir ./apifox-reports

这三个命令代表了三个工程动作：

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

复杂工作流的 Agent 路径

对于复杂的、多步骤的工作流，Agent的路径受益于CLI + SKILL结构。

复杂工作流的 MCP 路径

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

Agent需要：

1. 从众多选项中选择合适的工具
2. 理解工具描述和 schemas
3. 编排正确的序列
4. 通过重试处理错误

这可以工作，但每个决策点都需要大量的模型推理。

复杂工作流的 CLI + SKILL 路径

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

Agent需要：

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

工程系统处理了校验、引导和验证，从而减轻了模型的推理负担。

两条路径都能完成任务。CLI + SKILL降低了模型上下文阶段的复杂性。

CLI 目前涵盖的内容

随着升级，CLI现在涵盖了更多Apifox核心资源：

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

这改变了Apifox CLI的角色。

它不再仅仅是在一切完成后执行测试的一种方式。

它现在可以更早地参与到开发循环中 —— 在Agent需要执行以下操作的地方：

1. 理解项目
2. 生成或更新测试资产
3. 校验变更
4. 运行验证

架构总结

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

两者均可用。请根据您的任务进行选择。

下一步

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

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

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

核心要点

1. MCP持续发挥作用 —— 将其用于简单操作和MCP生态集成。
2. CLI + SKILL补充了MCP —— 更适用于带有校验的复杂工作流。
3. 核心区别在于复杂性存在于何处：模型上下文 vs. 工程系统。
4. CLI + SKILL通过校验、引导和验证减轻了模型的推理负担。
5. CLI现在涵盖了项目、API、环境、测试用例、场景等。
6. 两种方案均可用 —— 根据任务复杂性进行选择。

下载Apifox，在一个工作空间内完成 设计、Mock、测试 和 文档 工作。了解更多关于用于命令行API测试、CI自动化和AI Agent工作流的 Apifox CLI 的信息。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集API文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容Postman和Swagger数据格式，导入数据非常方便，即使是新手也能很快上手。

综上，CLI+SKILL与MCP各有所长，工程系统承担了复杂工作流中的校验与引导，降低了模型推理负担，而Apifox平台亦提供私有化部署方案，满足企业安全合规与内网协作需求。