Agent 外部工具实践：从 Apifox MCP 到 CLI + SKILL
Agent 真的需要上百个工具吗？
在开发 Apifox MCP 这几个月，我们被迫重新回答了一个问题：当一个产品进入 Agent 时代，是不是把所有能力都封装成 MCP 工具，就等于完成了 Agent 化？
一开始，我们的答案是肯定的。
今年年初，MCP 成为行业热点。Anthropic 推动协议，Cursor、Claude Code、各类 Agent IDE 和大量 SaaS 产品快速跟进。
那段时间，几乎每一个有 API 的产品都会被问到同一个问题：你们有 MCP 吗？
对 Apifox 来说，这个选择尤其自然。Apifox 本身沉淀了接口文档、Schema、Mock、测试用例、测试场景、测试套件、报告、导入导出和分支协作。如果 Agent 会成为新的软件入口，那么把这些能力通过 MCP 暴露出去，看起来就是一张必须补上的门票。
我们确实认真做了。
服务端实现里，Apifox MCP 并不是一个简单 demo。它是一个完整的 MCP Server：MCP 客户端先初始化会话，服务端生成 sessionId，并通过 Redis 保存会话状态；后续请求继续带着 sessionId 访问。也就是说，它不是一次性的 HTTP 调用，而是一个协议级的会话系统。
工具层也不是手写几个固定接口。我们把 Apifox 的工具分成几类：一类是项目摘要、目录结构、资源详情这类原生项目工具；一类是导入导出、接口详情、测试用例这类内置领域工具；还有一类是由 OpenAPI 接口定义自动转换出来的工具。这类生成工具有 126 个，每个工具都带有唯一标识、路径、HTTP 方法、输入 Schema。
为了降低工具暴露压力，我们还做了动态发现层：Agent 可以先搜索可用接口工具，再获取某个工具的 OpenAPI 详情，最后按工具 id 执行实际 HTTP 调用。
这已经是一次 progressive disclosure 的尝试。我们没有简单地把所有底层接口都直接显式摆出来，而是希望 Agent 先搜索、再取详情、最后执行。
但进入真实任务后，问题仍然很快暴露出来。
当一个用户只是说“帮我给这个接口补一个测试，并跑一下验证”。Agent 实际面对的却是一组连续判断：先找项目，还是先找接口？先读取接口详情，还是先列测试用例？测试用例该走 createTestCase，还是需要先找用例分组？测试场景该直接调用 update 工具，还是先导入步骤再回读？
从实现角度看，这些问题都能通过工具解决；从 Agent 体验看，它们构成了一面随机的工具墙。
Agent 工具实践上，并不是 MCP 没有价值。MCP 的价值在于标准化连接，它让不同工具可以通过统一协议暴露给 Agent，这对整个生态很重要。
但对 Apifox 这类复杂工程产品来说，单纯把能力拆成 MCP 工具，会遇到四个结构性问题。
第一，工具发现成本会快速上升。
Apifox 不是十几个接口就能描述完的产品。接口、Schema、环境、Mock、测试用例、场景用例、Runner、报告、分支、导入导出，每个模块继续拆下去，都能得到一组工具。工具从十几个变成几十个、上百个之后，Agent 需要先解决“用哪个工具”这个问题，才能开始解决用户问题。
我们曾经尝试把工作流写进工具 description （用于给 AI Agent 暴露工具的特性）。比如某个工具描述会明确说明：查询接口数据前，需要先通过另一个工具确认项目，再通过第三个工具获取项目元数据，最后才能调用当前工具。这个方法在小规模工具集里有效，但在海量工具墙里，description 本身也会竞争模型注意力。
第二，业务 Schema 会侵占上下文。
每个 MCP 工具都不只是一个工具名。它背后有 description、input schema、字段的解释、枚举值和返回结构。保守估算，100 个工具，每个工具平均 500 Token，用户的问题可能只有 50 个字，但模型要先被迫引入 50000 Token 的工具说明，而这仅仅是一个 MCP。
Cursor 在今年 1 月的官方博客《Dynamic Context Discovery》中给过一组有参考价值的数据：通过把 MCP 工具描述、终端会话和长对话转化为可按需加载的上下文，运行时 Token 消耗降低了 46.9%。Trae 的做法更直接：限制 MCP 工具数量和单工具描述长度，把工具数量上限设在 40，并限制单工具描述不超过 8000 字符。
实际上，早期内测就有大量团队反馈 Apifox MCP 在 Trae 中存在部分工具无法唤醒的问题，Agent 因为模型上下文有限被迫做出了取舍，外部工具是首先被“开刀”的对象。
这些方案都说明了同一个事实：工具描述不能无限进入模型上下文。
第三，协议会话让执行链路更重。
Apifox MCP 服务端需要处理 MCP initialize、sessionId、Redis session、transport connect/close、session touch、DELETE session、JSON response 或 SSE 配置等协议状态。对一个简单工具来说，这些成本可以接受；对一个大量调用、频繁探索的 Agent 任务来说，这些状态管理会增加服务端和客户端的复杂度。
在落地 Apifox MCP 时，消耗了团队大量精力去排查、适配不同的 Agent 客户端，但是协议兼容性问题长期存在，MCP 官方协议也在持续修修补补。各方苦不堪言。
第四，原子工具无法自然表达产品语义。
在 Apifox 的测试场景中，不是一个简单的 steps 数组表达，它涉及导入、回读、内部 case、前后置操作、断言、提取变量、运行环境和报告验证。把这些拆成多个 MCP 工具后，Agent 仍然要自己承担流程编排工作。
工具越原子，模型越需要理解产品内部语义。这显然这已经超出模型了能力范围，这迫使 Apifox 团队要主动针对内部产品语义进行技术工程上的调整，原子化的接口被动加了一层转化，而仅仅是为了适应 MCP 工具层的一次调度，对工程上的挑战，后期的维护成本，无疑艰巨了许多。
这四个问题的根源是同一件事：MCP 更擅长连接工具，但复杂研发任务需要的不只是工具连接，而是可执行的工程流程。
从 MCP Server 到 CLI Runtime
熟悉 Apifox CLI 的朋友都清楚，过去 Apifox CLI 的核心能力是 apifox run。
它主要服务 CI/CD、流水线和外部调度系统，用来运行测试，并生成测试报告。这个定位很清晰，也很实用。
但随着 Agent 调度的需求增加，就不只是运行已有测试。它还要读接口、查项目、创建测试用例、维护测试场景、理解 Schema、导入导出接口文件……AI 充当指挥员的角色，在用户、代码/文档文件、Apifox 服务之间，持续流转数据。
新版 Apifox CLI 的变化，不只是给旧 CLI 加几个命令，而是把 Apifox 的核心能力系统性地引入 CLI。
如果说旧版 CLI 回答的是“如何在外部运行 Apifox 测试”，新版 CLI 回答的是“AI Agent 如何稳定地使用 Apifox”。
背后的架构边界发生了巨大变化。
一个直观的对比：
MCP 路线的典型执行链路是：初始化 MCP session，加载工具列表和工具描述，Agent 选择工具，必要时通过 listOpenApiEndpoints 搜索更多工具，再用 getOpenApiDetails 获取 schema，最后通过 executeOpenApi 执行底层 HTTP 调用。
CLI + SKILL 路线的典型执行链路是：SKILL 判断任务类型，CLI 执行产品语义命令，cli-schema 在写入前校验结构，agentHints 给出下一步建议，最后通过 get 回读或 apifox run 形成验收闭环。
两条链路的区别不是“HTTP 还是命令行”，而是复杂度放置位置不同。
MCP 把大量复杂度放在模型上下文和工具选择阶段。Agent 需要理解工具列表、工具描述、schema、调用顺序和返回结构。
CLI + SKILL 把复杂度分散到工程系统里。SKILL 负责方法论，CLI 负责执行产品语义动作，cli-schema 负责写入前校验，agentHints 负责执行后导航。
一个典型的链路如下：
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 的路径因此从“猜工具、猜字段、直接写入”，变成“读事实、生成变更、校验结构、写入、运行验证”。
核心原则：CLI 产出事实，模型基于事实行动
我们这次沉淀下来的核心原则是：不要让模型记住所有规则，要让规则在合适的位置被执行。
这和 Agent 评测里的经验很像。确定性指标应该交给脚本计算，语义判断再交给 LLM。放到 Apifox CLI + SKILL 里，确定性结构校验应该交给 CLI，任务判断再交给 Agent。
cli-schema validate 是这个原则最直接的体现。
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
当 Agent 想写入或更新测试场景时，由 AI 生成复杂的步骤结构体非常容易出错，这段命令的 validate 即可以证实发起写入请求前对 Agent 生成的 --file ./scenario-update.json 进行一次从字段名、结构合法性、枚举值有效性的全面检测。
这不单只是给人类看的文档能力，而是 Agent 行为保持稳定的一种规范栅栏。
以测试用例里的前后置操作为例，Agent 很容易写错这些字段：变量类型不是 global，而是 globals；断言比较符不是 contains，而是 include；响应体 subject 不是 responseBody，而是 responseJson；delay 的 data 不能写成字符串，而必须是数字。
而这些问题通通都可以通过validate 命令发现并输出质量建议给 Agent 调整。
这些规则如果全部写进 Prompt，无疑会增加上下文负担；如果完全依赖模型记忆，又会增加错误率。更合理的方式是让 Agent 生成草稿，让 CLI 在写入前执行校验。
这就是 cli-schema 和cli-schema validate 的设计思路。
它把 Schema 从“模型需要背下来的知识”，变成“写入前必须经过的质量门禁”，问题不会消耗在无意义的来回网络请求中，靠本地命令就完成了质检。
agentHints：把隐含 workflow 放到输出里
传统 CLI 输出主要面向人类。成功了打印 success，失败了打印错误。
但 Agent 不只是读取结果，它还要把结果接到下一步任务链路里。
所以新版 CLI 在输出里加入了 agentHints，这可以说是 AI Agent 时代的 API 最佳实践 。
{
"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."
]
}
}
agentHints 可以解决 Agent 的执行惯性问题。
在上面的例子中，创建资源成功后，模型经常直接继续生成下一步写入。但复杂的业务流程里并不适合机械的连贯执行，最正确做法往往是先回读。服务端可能补默认值，前端可能依赖某些解析或结构变体，导入可能生成新的关联 ID。
如果不回读真实结构，Agent 很容易基于自己的“想象”继续写入。
agentHints 把产品经验变成机器可读的下一步建议，并且刚好出现在 Agent 需要做决策的位置。
Apifox CLI 内置了上千组树状工作流，因此不单是命令执行器，也成为轻量的状态引导器。
SKILL：把操作经验版本化
只有 CLI 和 AgentHints 还不够。
首先，Agent 仍然需要知道任务应该如何分解跨业务的执行流程，特别是隐藏了业务流程和“业务坑”。这些经验不能全面的写在工具描述、示例里，也不应该散落在聊天上下文中，SKILL 驱动 CLI 的价值在这里可以被放大，它定义的是 Agent 在特定领域里的工作边界、推荐流程、错误处理和验收方式。
其次， Apifox SKILL 是可进化、可版本化的操作经验。比如 Apifox CLI 在迭代中，命令发生了局部变化，抑或是用户有了更多个性化的工作流， Apifox SKILL 必须支持主动产生正向变化。
当命令升级后，Apifox SKILL 规范了主动进化和反思回路的指令，Agent 被赋予的写入权限，SKILL 落后了、不好用了，完全没关系，Agent 可以随时修改。
例如，在测试场景维护任务里，SKILL 不应该只是告诉 Agent 有 test-scenario update 命令，而要把真实产品流程沉淀下来：复杂场景不适合凭空手写完整结构，更稳定的路径是先导入已有接口或用例步骤，再回读完整结构，最后做局部修改。另外，get --with-case-detail 让 Agent 拿到真实结构，而不是凭空想象步骤内部的 case。我们也从真实 bug 里学到过类似经验：有些场景步骤在二次更新时，外层 step 更新成功了，但内部 HTTP case 没有正确更新。后来我们把这类兼容逻辑放进 CLI，让用户和 Agent 不需要知道内部标记，也能完成符合产品语义的更新。而这些约束背后的含义已按需分层到 Apifox SKILL 中。
这里关键不是命令本身，而是步骤大纲和步骤详情被流程约束了，如果依赖 --help 全部带入规则，将带出大量无意义的 token 占用，现在只需要 Agent 按需预热 SKILL。
复杂性应该由执行层和说明书吸收，而不是全量暴露给模型。
实践效果：工具调用、Token 与错误恢复
CLI + SKILL 的收益，不只体现在主观体验上。
我们内部对大量用户典型任务做过对比，包括根据接口补测试用例并运行验证、维护测试场景、导入并验证项目资产。
在“根据接口补测试用例并运行验证”这类任务中，MCP 路线通常需要多轮工具选择和字段修正。换成 CLI + SKILL 后，工具调用步骤平均减少约 30%，由无效工具描述和错误重试带来的 Token 消耗下降约 25%。
在后置操作中，processor、assertion、extractor 这类结构化写入任务中，引入 cli-schema validate 后，结构性错误导致的重复调用下降约 40%。
在创建资源后的连续操作中，引入 agentHints 后，Agent 主动回读、校验、运行验证的比例明显提升，直接跳到下一步导致的错误重试下降约 21%。
这些数字说明一个更具体的问题：复杂工程产品的 Agent 化，不是工具数量越多越好。工具数量增加之后，模型真正消耗的不是 API 调用能力，而是上下文、注意力、路径选择和用户的 token 成本之间做出取舍。
CLI + SKILL 的目标，是把这些成本从模型上下文里移出来，放回工程系统可以承载的位置。
任务典型实践：从 PRD 和代码库到测试闭环
在阐述了这么多 CLI + SKILL 的优点后，我们来展开一项实践，如何完成从 PRD 和代码库到测试闭环。
假设，一个团队刚写完一份“订单退款”PRD，代码库里也已经有对应的 route 和 controller。过去 Agent 要完成这件事，往往要在一堆 MCP 工具里反复选择：先查项目，还是先建接口；先写测试用例，还是先生成 Schema；写完以后是直接跑测试，还是先回读资源。
CLI + SKILL 的路径满足真实产研流程。
Agent 可以先根据 PRD 和代码库生成 OpenAPI，再导入 Apifox。
apifox import --project <projectId> --format openapi --file ./openapi.json
导入后，先围绕“退款接口”补单接口测试用例，并在写入前校验结构。
apifox cli-schema validate test-case-create --file ./test-case-create.json
单接口验证通过后，再根据 PRD 里的完整链路生成“创建订单 -> 支付 -> 退款 -> 查询退款状态”的测试场景，并继续在写入前校验。
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
最后运行自动化测试，作为这次接口和场景变更的验收。
apifox run --project <projectId> --out-dir ./apifox-reports
在这个案例中，Agent 不再直接对着一堆原子接口乱调。PRD、代码库、接口资产、单接口测试和业务场景被串成了一条可验证链路。一切都有迹可循。
CI/CD 仍然是底座
做 Agent 工具时，很容易只盯着对话式体验，Apifox CLI 有一个重要的服务对象：CI/CD。
过去 CLI 主要服务的就是这个场景。很多团队已经在流水线里用 Apifox 跑接口自动化测试、生成报告、做质量门禁。这个场景要求输出稳定、命令可脚本化、退出码明确、参数可配置，不能因为照顾 Agent 就破坏自动化。
所以我们迭代的主要原则是：Agent 友好必须建立在 CI/CD 友好之上。
同一条命令，在 CI 里可以作为质量门禁，在 Agent 里可以作为验收动作。
apifox run --project <projectId> --out-dir ./apifox-reports
CI 关心退出码、报告文件和稳定参数。
Agent 关心结构化结果、失败原因和下一步建议。
这也是 CLI 这条路线最吸引我们的地方。它不是为了 AI 重新发明一套只能给 AI 用的协议，而是在一个已经被工程系统验证过的形态上，增加 Agent 需要的结构化输出、Schema 校验和下一步引导。
Agent 时代的好 CLI 工程工具，应该能同时服务好人、脚本、CI 和 Agent。
当前仍然存在的问题
CLI + SKILL 并非没有代价。
第一，Skill 工程是手艺活。它不是把命令列表复制进去就结束，而是要把领域判断、错误边界、推荐流程写清楚。Skill 迭代往往落后于 CLI，升级触达困难，Agent 在 CLI 升级后可能仍然会走歪。
第二，流程会比一次性工具调用慢。读事实、validate（校验检测）、回读、运行，每一步都有成本。但这些成本换来的是可解释、可验证和可恢复。
第三，CLI 需要持续承担产品语义的兼容。比如二次更新测试场景时，内部 case 的更新标记不应该暴露给 Agent，而应该由 CLI 吸收。这要求 CLI 不能只是后端 API 的薄封装。
第四，Agent 行为仍有不确定性。CLI 和 SKILL 能收敛行为，但不能消除模型波动。我们能做的是把关键节点工程化：校验、回读、运行、报告。
从 Spec-First 到 Skill-First
过去，许多开发团队的开发协作流程是 Spec-First。
团队先把接口设计清楚，再围绕接口文档、Mock、调试、测试、发布进行协作。这样可以减少前后端扯皮，也可以让测试和联调更稳定。
AI Coding 出现之后，接口资产的消费者变了。
Agent 也开始消费这些资产。
它要读接口、补测试、跑自动化、根据报告修代码，也要判断一次变更是否真的可用。
这时，Apifox 里的接口文档、测试用例、测试场景就不只是协作材料，而是 Agent 可以调用的确定性资产。
Skill-First 在 Spec-First 的基础上，把接口规范、测试用例、业务场景进一步包装成 Agent 可执行、可验证、可追踪的技能。
在这个体系里，Apifox 管理 API 和测试资产，CLI 提供确定性执行，SKILL 提供任务判断和操作路径，Agent 负责理解目标、调用命令、根据反馈调整。
接下来，Apifox CLI + SKILL 在 AI Coding 时代将继续服务好广大开发者、测试团队，欢迎体验：
复制下面的话，直接给您最常用的 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
