Apideck CLI：低消耗的 AI Agent 接口方案

演示永远不会向你展示的问题

如果你使用过 MCP 服务器的任何超出演示范围的场景，这个故事会显得很熟悉。

你连接了 GitHub、Slack 和 Sentry。三个服务，总共差不多 40 个工具。在你的 AI 智能体读到单一条用户消息之前，55,000 个 token 的工具定义已经占据了上下文窗口。这超过了 Claude 200k 限额的四分之一。就这样消失了。

情况会变得更糟。每个 MCP 工具需要 550-1,400 个 token 来容纳它的名称、描述、JSON 模式、字段描述、枚举和系统指令。连接一个真实的 API 表面，比如一个拥有 50+ 个端点的 SaaS 平台，光是描述 AI 智能体能做什么就需要 50,000+ 个 token，几乎没什么空间留给 AI 智能体应该做什么。

有一个团队报告说三个 MCP 服务器消耗了 200,000 个 token 中的 143,000 个。这是上下文窗口的 72%。AI 智能体只剩下 57,000 个 token 用于实际对话、检索文档、推理和回复。别指望在这点空间里建造什么有用的东西。

这不是纯理论上的问题。David Zhang (@dzhng) 在开发 Duet 时，描述了他们完全撕掉 MCP 集成的经历，即使在让 OAuth 和动态客户端注册工作后也是如此。折衷是不可接受的：

一次性加载所有东西 → 失去推理和历史的工作内存

限制集成数量 → AI 智能体只能与少数服务通话

构建动态工具加载 → 增加延迟和中间件复杂性

他称之为"三角困境"。

这些数字在受控测试下是站得住的。Scalekit 最近的一个基准测试运行了 75 次头对头的对比（相同模型、Claude Sonnet 4、相同任务、相同提示），结果发现 MCP 比 CLI 相同操作多花费 4 到 32 倍的 token。他们最简单的任务——检查一个仓库的编程语言——通过 CLI 消耗 1,365 个 token，通过 MCP 消耗 44,026 个。额外开销几乎完全来自架构：43 个工具定义被注入到每次对话中，而 AI 智能体通常只用到其中一两个。

应对同一问题的三种方法

业界正在聚合到三种应对上下文膨胀的方案上。每一种都有其优势所在。

MCP 配合压缩技巧

第一种方案是保留 MCP 但对抗膨胀。团队压缩架构、使用工具搜索按需加载定义，或者构建中间件将 OpenAPI 规范切片成更小的块。

这适用于小型、良好定义的交互，比如查询一个 issue、创建一张工单或获取一份文档。当你有一套 AI 智能体频繁使用的紧凑操作集时，MCP 的结构化工具调用和类型架构确实很有用。

但它增加了基础设施成本。你需要一个工具注册表、搜索逻辑、缓存和路由。你在构建一个服务来管理你的服务。而且每次 AI 智能体决定它需要一个新能力时，你仍然要为每个工具支付 token 成本。

代码执行方法

代码执行方法把 AI 智能体当作一个拥有持久工作区的开发者。当 AI 智能体需要一个新的集成时，它读取 API 文档，根据 SDK 编写代码，运行它，并保存脚本以便重用。Duet 通过让 AI 智能体编写和维护自己的集成脚本来开创了这个模式。

这对于跨会话维护状态并需要复杂工作流的长期工作区 AI 智能体来说很强大：循环、条件语句、轮询、批量操作。那些用单独工具调用表达起来很尴尬的东西在代码中就变得自然了。

有一个更有针对性的变体值得关注：代码模式。AI 智能体不是对原始 API 编写任意代码，而是编写简短的编排脚本来调用底层的结构化 MCP 工具。Sideko 在 12 个 Stripe 任务上的基准测试表明，代码模式 MCP 比原始 MCP 少用 58% 的 token，比 CLI 少用 56%。关键洞察在于：在创建带有行项目的发票这样的多步骤任务上，CLI 需要 19 次 LLM 往返，原始 MCP 需要 12 次，而代码模式把它缩减到了 4 次。AI 智能体编写一个 TypeScript 程序，在内部处理循环，而不是在每一步后回到 LLM。

这很重要，因为 CLI 的效率优势——它对单步发现和读取是真实存在的——可能在复杂链式写入上被削弱，因为每次往返都会加剧上下文成本。代码模式提供了一个中间地带：结构化工具访问而不需要架构膨胀，加上批量操作的能力而不需要每步的 LLM 开销。

折衷在于你的 AI 智能体正在对生产 API 编写和执行代码。即使是沙箱化的，安全表面也比具有结构化权限的 CLI 更大。你需要审查机制和对 AI 智能体判断力的信任。但对于涉及循环和依赖状态的工作流来说，这是一个值得与 CLI 并肩考虑的模式。

CLI 作为 AI 智能体界面

第三种方案是我们采取的。你给 AI 智能体一个 CLI，而不是把架构加载到上下文窗口中，也不让 AI 智能体编写集成代码。

一个设计良好的 CLI 本质上是一个渐进式披露系统。当一个人类开发者需要使用一个他们从未接触过的工具时，他们不会读整个 API 参考。他们运行 tool --help，找到他们需要的子命令，运行 tool subcommand --help，然后获得那个操作的特定标志。他们的注意力成本与他们实际需要的成正比。

AI 智能体可以做完全相同的事情。而 token 经济学差别很大。

为什么 CLI 是务实的最优点

渐进式披露节省 token

以下是 Apideck CLI AI 智能体提示的样子。这是 AI 智能体在其系统提示中需要的全部内容：

Use `apideck` to interact with the Apideck Unified API.
Available APIs: `apideck --list`
List resources: `apideck <api> --list`
Operation help: `apideck <api> <resource> <verb> --help`
APIs: accounting, ats, crm, ecommerce, hris, ...
Auth is pre-configured. GET auto-approved. POST/PUT/PATCH prompt (use --yes). DELETE blocked (use --force).
Use --service-id <connector> to target a specific integration.
For clean output: -q -o json

这大约是 80 个 token。与其他方案对比：

AI 智能体从 80 个 token 的指导开始，按需发现能力：

# 级别 1：有哪些 API 可用？（约 20 个 token 输出）
$ apideck --list
accounting ats connector crm ecommerce hris ...

# 级别 2：我可以用 accounting 做什么？（约 200 个 token 输出）
$ apideck accounting --list
Resources in accounting API:

invoices
    list       GET  /accounting/invoices
    get        GET  /accounting/invoices/{id}
    create     POST /accounting/invoices
    delete     DELETE /accounting/invoices/{id}

customers
    list       GET  /accounting/customers
    ...

# 级别 3：我如何创建发票？（约 150 个 token 输出）
$ apideck accounting invoices create --help
Usage: apideck accounting invoices create [flags]

Flags:
  --data string        JSON request body (or @file.json)
  --service-id string  Target a specific connector
  --yes                Skip write confirmation
  -o, --output string  Output format (json|table|yaml|csv)
  ...

每一步消耗 50-200 个 token，仅在 AI 智能体决定需要该信息时加载。一个处理会计查询的 AI 智能体可能在三个 --help 调用中总共消耗 400 个 token。通过 MCP 暴露相同表面会消耗 10,000+ 个 token 并一次性加载，无论 AI 智能体是否使用。

这反映了 Claude Agent Skills 的工作方式。元数据优先，完整细节只在选中时提供，参考资料仅在需要时提供。CLI 通过不同的机制做同样的事情。

Scalekit 的基准测试独立验证了这个模式。他们发现即使是一份最少的约 800 token 的"技能文件"（一份关于 CLI 技巧和常见工作流的文档）与裸 CLI 相比也能将工具调用减少三分之一，将延迟减少三分之一。我们的方法走得更远：约 80 token 的 AI 智能体提示以十分之一的成本提供相同的渐进式发现。原理是一样的。一份小的、前期的关于如何导航工具的提示比数千个 token 的详尽架构更值钱。

可靠性：本地胜于远程

MCP 问题有一个不够受重视的维度：可用性。

Scalekit 的基准测试记录了对 GitHub Copilot 服务器 MCP 调用的 28% 故障率。在 25 次运行中，7 次以 TCP 级连接超时失败。这些不是协议错误或坏工具调用。连接根本完成不了。

CLI AI 智能体没有这种故障模式。二进制文件在本地运行。没有远程服务器可以超时，没有连接池可以耗尽。当你的 AI 智能体运行 apideck accounting invoices list 时，它对 Apideck API 进行直接的 HTTPS 调用。一跳，不是两跳。

这在规模上很重要。每月 10,000 次操作，28% 的故障率意味着大约 2,800 次重试，每次都会燃烧额外的 token 和延迟。Scalekit 估计月度成本差异为 CLI 的 $3.20 对比直接 MCP 的 $55.20，是 17 倍的成本乘数，加上可靠性税。

远程 MCP 服务器会不断改进。连接池、更完善的基础设施和网关层将缩小这一差距。但“二进制文件就在你的机器上”是一种可靠性保证，无论服务端进行多少基础设施工程优化，都无法与之媲美。

结构化安全胜过基于提示词的安全

在系统提示词中告诉智能体“永远不要删除生产数据”，就像在核武器发射按钮上贴一张便利贴。它会一直有效，直到某个精心设计的提示词注入把这张纸撕下来。

关于 CI/CD 中 AI 智能体的安全研究已经表明，提示词注入可以操纵持有高权限令牌的智能体，使其泄露机密或修改基础设施。其模式总是相同的：不受信任的输入被注入提示词，智能体拥有广泛的工具访问权限，随后便会发生糟糕的事情。

Apideck CLI 采用了结构化方法。基于 HTTP 方法的权限分类被直接内置在二进制文件中：

// From internal/permission/engine.go
switch op.Permission {
case spec.PermissionRead:
    return ActionAllow      // GET -> auto-approved
case spec.PermissionWrite:
    return ActionPrompt     // POST/PUT/PATCH -> confirmation required
case spec.PermissionDangerous:
    return ActionBlock       // DELETE -> blocked by default
}

任何提示词都无法绕过这一机制。除非调用方显式传入 --force，否则 DELETE 操作会被阻止。POST 操作需要传入 --yes 或进行交互式确认。GET 操作可以自由执行，因为它们无法修改状态。

智能体框架进一步强化了这一点。Claude Code、Cursor 和 GitHub Copilot 都有用于限制 shell 命令执行的权限系统。因此，你会获得两层结构化安全保障：智能体框架会询问“我是否应该运行这条命令？”，而 CLI 本身则会强制判断“是否允许执行此操作？”。

你还可以针对每个操作自定义策略：

# ~/.apideck-cli/permissions.yaml
defaults:
  read: allow
  write: prompt
  dangerous: block

overrides:
  accounting.payments.create: block    # payments are sensitive
  crm.contacts.delete: prompt          # contacts can be soft-deleted

这与 Duda 阻止破坏性 MCP 操作背后的原则相同，但它是在二进制文件中以结构化方式强制执行的，而不是依赖提示词指令，去和上下文窗口中的其他所有内容争夺影响力。

通用兼容，零协议开销

每个成熟的智能体框架都将“运行 shell 命令”作为一种基础能力。Claude Code 有 Bash，Cursor 可以访问终端，GitHub Copilot SDK 暴露了 shell 执行能力，Gemini CLI 则原生支持运行命令。

MCP 需要专用的客户端支持、连接管线以及服务器生命周期管理。CLI 只需要 PATH 中存在一个二进制文件。

这件事的重要性超乎想象。当你构建一个需要与 API 交互的智能体时，CLI 的集成路径是：

设置用于身份认证的环境变量

在系统提示词中添加约 80 个 token

MCP 的集成路径则是：

实现或配置 MCP 客户端

建立服务器连接（传输、身份认证、生命周期）

处理工具注册和 schema 加载

管理连接状态和重连

处理工具定义所占用的 token 预算

CLI 方法还意味着，你的智能体集成不会被锁定在任何特定框架中。同一个 apideck 二进制文件可以用于 Claude Code、Cursor、自定义 Python 智能体、bash 脚本或 CI/CD 流水线。

Apideck CLI 是一个静态单体二进制文件，它会在启动时解析我们的 OpenAPI 规范，并动态生成完整的命令树。

OpenAPI 原生，无需代码生成。该二进制文件内嵌了最新的 Apideck Unified API 规范。启动时，它使用 libopenapi 解析规范，并为每个 API 分组、资源和操作构建命令。当 API 新增端点时，apideck sync 会拉取最新规范。无需重新生成 SDK，也无需更新版本号。

智能的默认输出。在终端中运行时，默认输出为带颜色的格式化表格。通过管道传输或从非 TTY 环境调用时（智能体正是以这种方式调用它），默认输出为 JSON。智能体无需记住添加 --output json，即可获得机器可解析的输出。

# Agent calls this (non-TTY) -> gets JSON automatically
$ apideck accounting invoices list -q
[{"id": "inv_12345", "number": "INV-001", "total": 1500.00, ...}]

# Human runs the same command in terminal -> gets a table
$ apideck accounting invoices list
┌──────────┬─────────┬──────────┐
│ ID       │ Number  │ Total    │
├──────────┼─────────┼──────────┤
│ inv_12345│ INV-001 │ 1,500.00 │
└──────────┴─────────┴──────────┘

身份认证是无感的。凭据通过环境变量（APIDECK_API_KEY、APIDECK_APP_ID、APIDECK_CONSUMER_ID）或配置文件解析，并自动注入每个请求。智能体从不处理令牌、从不接触身份认证标头，也不需要管理会话。

连接器定向。--service-id 标志允许智能体指定特定集成。apideck accounting invoices list --service-id quickbooks 会访问 QuickBooks。将其替换为 --service-id xero，同一条命令就会访问 Xero。接口相同，后端不同，其余工作由统一 API 处理。

CLI 并非答案的场景

CLI 并非在所有情况下都更好。以下场景更适合其他方法。

MCP 更适合范围明确、调用频繁的工具。如果你的智能体在每个会话中都会数百次调用相同的 5～10 个工具，那么前期的 schema 成本可以得到充分摊销。一个只负责查询工单、更新状态和发送回复的客户支持智能体并不需要渐进式披露。它需要的是这些工具立即就绪。

代码执行更适合复杂且有状态的工作流。如果你的智能体需要每 30 秒轮询一次 API、聚合分页端点的结果，或者编排带有回滚逻辑的多步骤事务，那么编写代码比串联 CLI 调用更自然。正如 Sideko 基准测试所显示的那样，在多步骤链式写入中，每一次往返都会累积上下文，此时 CLI 的效率优势可能会逆转。对于这些模式，Code Mode（智能体编写调用结构化工具的编排脚本）或 Duet 方法（完整代码执行）虽然单步开销更高，但使用的总 token 数反而更少。

当你的智能体代表其他人的用户执行操作时，MCP 更合适。这是大多数 CLI 与 MCP 对比都会轻描淡写的维度，但值得直截了当地说明。当智能体自动化的是你自己的工作流时，环境中的现成凭据没有问题。你就是用户，唯一承担风险的人也是你。但如果你正在构建一款 B2B 产品，让智能体代表客户的员工，在这些客户所控制的组织中执行操作，那么身份问题就会分为三层：哪个智能体正在调用、哪个用户授权了它，以及适用哪个租户的数据边界。在这一边界上，按用户提供具有作用域限制的 OAuth 访问权限、同意流程和结构化审计轨迹都是真实存在的要求，而原始的 CLI 身份认证方式（gh auth login、环境变量）并不是为解决这些问题而设计的。无论 MCP 的授权模型会带来怎样的效率成本，它都原生解决了这一问题。

CLI 身份认证还存在一个更深层的身份缺口：智能体级身份。CLI 令牌可以认证用户，但 API 提供方永远不知道是哪个智能体发起了请求。这对于策略执行至关重要。如果 API 提供方与智能体 A 建立了合作关系，但没有与智能体 B 合作，就无法通过 CLI 令牌区分它们。MCP 的 OAuth 模型可以通过 act 等声明传递智能体身份；随着智能体开始调用其他智能体，并且你需要在令牌中记录完整的委托链，这一能力会变得至关重要。对于单智能体工作流而言，这只是一个理论问题；对于多智能体架构而言，它却是一个真实的架构约束。

尽管如此，对于统一 API 架构而言，这一差距并没有看上去那么大。Apideck 已经通过 Vault 集中管理身份认证：凭据按消费者、按连接进行管理，并按服务限定作用域。--service-id 标志用于指定某个消费者 Vault 中的特定集成。结构化权限系统则在二进制文件中强制执行读、写、删除的边界。目前缺少的是按用户的 OAuth 同意流程和限定于租户的审计轨迹——这些确实是真实的缺口，但它们位于平台层，而不是智能体接口层。CLI 可以充当接口，同时由后端处理委托授权，二者并不相互排斥。

还值得注意的是，MCP 的身份认证方案并没有看起来那么成熟稳定。正如 Speakeasy 的 MCP OAuth 指南明确指出的那样，MCP 规范实际上并不要求面向用户的 OAuth 交换流程。直接传递访问令牌或 API 密钥完全符合规范。真正的复杂性出现在 MCP 客户端需要动态处理 OAuth 流程时，这要求支持 Dynamic Client Registration（DCR，动态客户端注册），而目前大多数 API 提供方并不具备这项能力。Stripe 和 Asana 等公司已经开始添加 DCR 以适配 MCP，但它仍然是一种集成阻力很大的方案。理论上，MCP 相比 CLI 确实具有身份认证方面的优势；但在实践中，整个生态系统仍在努力追赶规范。

CLI 在流式传输和双向通信方面较弱。CLI 调用采用请求-响应模式。如果需要服务器发送事件（SSE）、WebSocket 流或长连接，则应使用能够保持连接开启的 SDK 或 MCP 服务器。

分发存在一定阻力。理论上，MCP 服务器可以托管在某个 URL 后面。CLI 则需要针对不同平台提供二进制文件，还涉及更新和 PATH 管理。对于 Apideck CLI，我们发布了一个无需依赖、可在各个平台运行的静态 Go 二进制文件，但它仍然是一个需要安装的二进制文件。

坦率地说：MCP、代码执行和 CLI 是互补的工具。真正的问题在于把 MCP 当作万能答案，而对于许多集成模式，CLI 可以用低两个数量级的上下文开销完成同样的工作。

这对 API 提供商意味着什么

如果你在 2026 年构建开发者工具，AI 智能体正在成为 API 接口的主要使用者之一。它们不是唯一的使用者（人类开发者仍然很重要），但其数量正在快速增长。

以下几点值得考虑：

你的 OpenAPI 规范对于上下文窗口来说太大了。如果拥有 50 个以上的端点，将规范转换为 MCP 工具会耗尽大多数智能体交互的预算。应思考最小化的入口点应该是什么样子。

渐进式披露已不再只是一种 UX 模式，它也是一种 token 优化策略。为智能体提供逐步发现能力的方式，而不是一开始就把所有内容全部倾倒出来。

结构性安全不容妥协。基于提示词的护栏，在安全性上无异于依靠自觉缴费的停车场。应将权限模型构建到工具中，而不是写进提示词里。根据风险等级对操作进行分类，并在代码中强制执行这种分类。

提供机器友好的输出格式。在非交互式环境中默认使用 JSON。提供稳定的退出码和确定性的输出。这些都是智能体 CLI 设计中已有明确文档记录的原则，而且非常重要，因为你的下一位高级用户可能根本没有双手。

MCP 与 API——MCP 和 REST API 之间的关系（Apideck 博客）

智能体时代的 API 设计原则——以 AI 智能体作为一等使用者来设计 API

了解 MCP 的安全格局——深入探讨 MCP 的安全注意事项

MCP 上下文税——详细分析 MCP 的 token 开销

智能体 CLI 设计：7 项原则——将 CLI 设计为智能体接口时应遵循的设计原则

MCP 与 CLI 基准测试——Scalekit 的正面对比基准数据（75 次运行，Claude Sonnet 4）

CLI、MCP 与 Code Mode 基准测试——Sideko 使用 12 项 Stripe 任务对三种方案进行的基准对比

Code Mode：使用 MCP 的更好方式

什么是 MCP Tool Search？——用于解决上下文污染问题的 Claude Code 功能

如果你扼杀 MCP，就说明你根本不在乎安全

CLI、MCP 与 Code Mode

准备好开始了吗？

扩展你的集成战略，以前所未有的速度交付客户所需的集成。