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

在深入探讨 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 <projectId> --test-scenario <scenarioId> --environment <environmentId>

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

从终端运行 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 的核心能力引入 CLI，使其成为开发者、脚本和 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 工作流的具体示例：

# 步骤 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 需要：

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

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

复杂工作流的 CLI + SKILL 路径

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

Agent 需要：

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

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

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

CLI 目前涵盖的内容

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

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

这改变了 Apifox CLI 的角色。

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

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

理解项目
生成或更新测试资产
校验变更
运行验证

架构总结

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