站点图标 高效码农

API转CLI：别让AI助手再背文档了！这款神器能自动生成可复用命令行工具

高效码农

api2cli：为Claude Code打造的API转CLI技能，让AI轻松调用任何API

你是否曾幻想过，只需一句指令，就能让AI助手直接调用任意API——无论是发送邮件、管理域名，还是操作客户数据？更棒的是，生成的命令行工具不仅人机友好，还能在AI会话间无缝复用，而无需阅读任何源码？这正是 api2cli 要解决的问题。作为 Claude Code 的一款技能，它能把任何API描述、文档甚至网络抓包文件，自动转化为一个功能完备的CLI，同时生成一个让Claude自己学会使用它的“技能包”。从此，你和你的AI助理都能以统一的命令行方式与成百上千个API对话，效率倍增。

本文将深入拆解 api2cli 的设计哲学、核心功能、使用场景及内部实现，带你领略“AI优先”的CLI设计新范式。无论你是开发者、DevOps 还是对AI增强开发感兴趣的极客，都能从中获得实用启发。

一、为什么需要“API转CLI”？

在日常开发中，我们经常需要与各种第三方API打交道。以邮件服务 Resend 为例，你想通过它发送一封邮件，通常需要：

  1. 阅读API文档，理解端点、请求方法、认证方式。
  2. 编写代码（curl、Node.js、Python等）构造请求。
  3. 处理错误、分页、重试等细节。
  4. 如果换了项目，重复以上步骤。

如果有一个CLI工具封装好这一切，你只需在终端输入类似 resend emails send --to ... 即可。更重要的是，AI助手（如 Claude）可以直接调用这个CLI，自主完成多步操作，而无需每次都从头理解API文档。这正契合了“agent-first”的理念：让AI以工具的方式与外界交互，而非强行让AI理解所有业务细节。

api2cli 正是为此而生。它不是一个独立的CLI生成器，而是深深嵌入 Claude Code 生态的技能。当你对 Claude 说“帮我为 Resend API 建个CLI”，它会自动发现端点、生成CLI脚本、并创建一个 .claude/skills/resend/SKILL.md 文件，教会未来的 Claude 会话如何使用这个CLI。一次生成，永久受益。

二、快速上手：从Resend API示例看全流程

让我们以 Resend 邮件API为例，看看 api2cli 的完整工作流程。你只需在 Claude Code 环境中输入：

给我为 Resend API 建一个CLI。文档在这里：https://resend.com/docs/api-reference

接下来，Claude 会自动：

  1. 发现端点：访问文档页面，解析出所有API端点。它会告诉你找到了15个端点，分布在5个资源下（emails、domains、api-keys、audiences、contacts），并列出每个资源的端点数量。
  2. 构建端点目录：自动收集每个端点的认证方式、是否支持分页、是否有速率限制等信息。
  3. 生成CLI：在 scripts/resend.ts 生成一个基于 Commander.js 的CLI工具，每个端点一个子命令。
  4. 生成技能文档：在 .claude/skills/resend/SKILL.md 生成一份详细的技能说明，包含所有命令、示例、常见工作流以及触发条件。

生成后，你立即可以试用：

# 查看所有命令（无参数运行会自述）
npx tsx scripts/resend.ts
{
  "ok": true,
  "command": "resend",
  "result": {
    "description": "Resend email API CLI",
    "commands": [
      { "command": "resend emails send", "description": "发送邮件" },
      { "command": "resend emails get <id>", "description": "根据ID获取邮件" },
      { "command": "resend domains list", "description": "列出所有域名" },
      ...
    ]
  }
}

# 发送一封邮件
npx tsx scripts/resend.ts emails send \
    --to user@example.com \
    --subject "Hello from CLI" \
    --html "<p>Hi there</p>"

# 列出域名（终端直接运行，输出人类可读表格）
npx tsx scripts/resend.ts domains list
ID          Domain              Status
re_abc123   example.com         verified
re_def456   staging.example.com pending

# 将输出通过管道传给其他命令（自动切换为JSON格式，包含下一步建议）
npx tsx scripts/resend.ts domains list | cat
{
  "ok": true,
  "command": "resend domains list",
  "result": { "domains": [...], "count": 2 },
  "next_actions": [
    { "command": "resend domains get re_abc123", "description": "查看域名详情" },
    { "command": "resend emails send --from noreply@example.com", "description": "从已验证域名发送邮件" }
  ]
}

注意最后一种输出：当管道被检测到时，CLI自动输出JSON信封，其中 result 包含实际数据，next_actions 提供了基于当前结果的下一步建议。这种设计正是“agent-first”的精髓——让AI能够理解当前状态，并自主规划后续操作。

生成的技能文档（SKILL.md）更是点睛之笔。它包含了：

---
name: resend
description: 与Resend邮件API交互。当用户需要发送邮件、管理域名、创建API密钥、管理受众和联系人时使用。
---

# Resend CLI

## 设置
export RESEND_API_KEY=re_your_key_here

## 命令
### emails send --to <email> --subject <text> --html <html>
### domains list | get <id> | create --name <domain>
### contacts list --audience-id <id> | create --email <email>
...

有了这份文档，任何后续的 Claude 会话都能立即知道如何调用这个CLI，而无需阅读生成的 TypeScript 代码。技能文档被放在 .claude/skills/ 目录下，Claude 会自动加载，并在相关话题出现时主动建议使用。

三、api2cli 的核心能力拆解

1. 多模式API发现

api2cli 支持三种方式发现API端点，适应不同场景：

方法 适用场景 工作原理
文档解析 公开API，有在线文档 爬取文档页面，识别常见API模式（如 GET /users，POST /emails），提取端点路径、方法、参数说明
主动探测 已知API基础URL，有访问凭证 基于常见API模式（REST、GraphQL等）进行智能猜测，发送轻量级探测请求（如 GET /、OPTIONS）发现可用端点
peek-api 抓包 需要从现有Web应用中逆向API 配合 peek-api 捕获浏览器网络请求，自动过滤出API调用，并重建端点签名

文档解析是最常用的方式，它能够从非结构化的HTML文档中提取结构化信息。Claude利用其对自然语言的理解，即使文档排版不统一也能准确识别。主动探测则在文档缺失或需要验证时发挥作用。peek-api 抓包特别适合内部系统或未公开API的发现——你可以像用户一样操作界面，让 peek-api 记录下所有网络请求，然后交给 api2cli 生成CLI。

2. 智能端点目录

在生成CLI前，api2cli 会构建一个详细的端点目录，包含：

  • 资源名称：如 emails、domains
  • 端点列表：每个端点的HTTP方法、URL路径、参数（路径参数、查询参数、请求体参数）
  • 认证方式：API Key、OAuth2、JWT等（通过文档解析或用户输入推断）
  • 分页信息：是否支持分页，参数名（如 page、limit）
  • 速率限制：文档中声明的限制（如 10 req/s），用于CLI内置限流
  • 示例响应结构：用于生成 next_actions 提示

这个目录不仅用于生成CLI，还会展示给用户确认，确保准确性。

3. 生成功能完备的CLI

api2cli 生成的CLI基于 Commander.js，具备以下开箱即用的特性：

  • 每个端点一个子命令：命令结构为 cli <资源> <操作> [参数]，例如 resend emails send。
  • 自文档化：无参数运行显示所有命令，并输出JSON格式描述（便于AI解析）。
  • 双模输出：
    • 人可读模式：终端直接运行时，输出格式化的表格、列表等。
    • Agent模式：当检测到标准输出被管道或重定向时，自动切换为JSON信封，包含 ok 状态、command、result 数据以及 next_actions 建议。
  • 内置API客户端：自动处理认证（从环境变量读取API Key）、请求重试（指数退避）、速率限制（令牌桶）、缓存（可配置TTL）。
  • 错误处理：错误时输出结构化错误信息，并提供 fix 建议（如“检查API Key是否设置”），帮助AI自动修正。
  • 分页支持：对支持分页的列表命令，CLI默认只取第一页，但提供 --all 参数获取全部结果，或通过 next_actions 提示下一页命令。

例如，对于分页的域名列表，CLI可能输出：

{
  "ok": true,
  "command": "resend domains list",
  "result": {
    "domains": [...],
    "page": 1,
    "total_pages": 5
  },
  "next_actions": [
    { "command": "resend domains list --page 2", "description": "查看下一页域名" }
  ]
}

4. 生成即用的Claude技能

这是 api2cli 的杀手级特性。它不仅仅是生成CLI，还会自动创建一个 .claude/skills/{service}/SKILL.md 文件，内容包含：

  • YAML前置元数据：name、description、triggers（触发短语），让Claude知道何时该技能适用。
  • 命令速查表：列出所有子命令，附带常用参数和简短说明。
  • 常见工作流示例：如“发送邮件给新用户”、“创建域名并验证”等，组合多个命令。
  • 环境变量说明：如何设置API Key等。

当用户在 Claude 中提及“发送邮件”或“管理域名”时，Claude 会自动加载 resend 技能，并知道可以调用 resend emails send 等命令。这样，AI 不再需要每次重复学习API细节，而是直接使用现成的工具。

四、技术深度：CLI与技能的协同设计

1. HATEOAS 风格的 next_actions

受HATEOAS（超媒体即应用状态引擎）启发，api2cli 生成的CLI在输出JSON时，会包含 next_actions 数组。这些建议基于当前结果动态生成，比如：

  • 创建了一个域名后，建议 domains verify <id>。
  • 列出发送失败的邮件后，建议 emails retry <id>。

这使得AI能够“探索”API的可能性，而无需预编程所有工作流。例如，AI可以先执行 domains list，看到有未验证的域名，然后自动调用 domains verify。整个过程行云流水，仿佛AI真的“理解”了业务逻辑。

2. Agent-first CLI 设计原则

api2cli 遵循一套“agent-first”的设计原则，这些原则体现在生成的CLI的方方面面：

  • 结构化输出：所有输出要么是人类友好的终端表格，要么是机器可解析的JSON。不存在混杂格式。
  • 命令自述：根命令输出所有可用命令的JSON描述，让AI可以动态发现能力。
  • 错误可恢复：错误输出包含足够上下文，并给出可能的修正建议（fix）。
  • 上下文安全：CLI不会假设终端宽度、颜色等，所有输出都是纯文本，保证AI读取时不会乱码。
  • 幂等性与安全：修改类命令默认要求确认（除非指定 --force），避免AI误操作。

这些原则源自 Joel Hooks 的 agent-first CLI 设计，确保了生成的CLI既适合人类临时使用，也适合AI长期自主调用。

3. 客户端底层：稳健的API调用层

生成的 TypeScript 代码中包含一个强大的 apiClient 模块，它实现了：

  • 认证注入：支持多种认证方式，通过环境变量获取密钥。
  • 自动重试：对5xx错误或网络故障，默认重试3次，使用指数退避（初始延迟1s，倍数2）。
  • 速率限制：基于端点目录中的限制信息，使用令牌桶算法限制请求速率（如10次/秒）。
  • 缓存：对GET请求默认缓存5分钟，可通过 --no-cache 禁用。
  • 分页抽象：自动处理游标或页码，提供 fetchAll 方法。
  • 错误分类：区分客户端错误（4xx）和服务端错误（5xx），并提取API返回的错误信息。

所有这些细节都封装在底层，使得生成的CLI命令代码极其简洁，只需定义参数映射和调用对应方法。

五、安装与使用流程

前置条件

  • Claude Code：api2cli 是Claude Code的技能，因此你需要在项目中启用Claude Code。具体安装Claude Code请参考官方文档。
  • Node.js 环境：生成的CLI是TypeScript脚本，需要Node.js和tsx（或ts-node）运行。

安装 api2cli 技能

# 克隆仓库
git clone https://github.com/alexknowshtml/api2cli.git

# 将技能复制到你的Claude项目
cp -r api2cli/skill/ /path/to/your/project/.claude/skills/api2cli/

复制后，Claude Code 会在启动时自动加载 api2cli 技能。现在你可以直接向 Claude 发出指令了。

典型对话示例

场景1：基于文档生成CLI

你：为 SendGrid API 建个CLI，文档在 https://docs.sendgrid.com/api-reference
Claude：正在访问文档... 发现12个端点，涉及邮件、模板、列表等资源。要生成CLI吗？
你：是的。
Claude：CLI已生成在 scripts/sendgrid.ts。我已同时创建技能 .claude/skills/sendgrid/SKILL.md。你可以设置 SENDGRID_API_KEY 环境变量后试用。

场景2：基于现有API基础URL（主动探测）

你：我有一个内部API，基础URL是 https://api.internal.example.com/v2，帮我生成CLI。认证用Bearer Token，从环境变量 INTERNAL_TOKEN 读取。
Claude：正在探测... 根据常见模式推测出8个可能端点。请确认以下目录：
- users (GET /users, GET /users/{id}, POST /users)
- orders (GET /orders, GET /orders/{id})
... 确认后生成？
你：确认。
Claude：已生成。

场景3：结合 peek-api 抓包

你：这是我的 peek-api 抓包文件 capture.json，请为里面的API生成CLI。
Claude：解析抓包... 发现23个唯一端点，其中包含 GraphQL 请求。已构建端点目录。生成CLI？
你：生成。
Claude：已生成，注意 GraphQL 端点被封装为两个子命令：graphql query 和 graphql mutation。

无论哪种方式，最终产物都是可立即使用的CLI + 技能文档。

六、生成内容的内部组件（参考文件结构）

在 api2cli 技能目录中，包含了多个参考文档，用于指导Claude生成高质量的CLI：

  • discovery-strategies.md：描述三种发现策略的详细技术实现，包括文档解析的启发式规则、主动探测的端点猜测算法、peek-api 抓包的过滤规则。
  • api-client-template.md：提供API客户端的模板代码，包含重试、限流、缓存、分页等实现，Claude会据此生成最终的 client.ts。
  • agent-first-patterns.md：定义双模输出、next_actions 生成规则、错误格式规范等。
  • commander-patterns.md：介绍 Commander.js 的高级用法，如命令嵌套、参数解析、帮助生成等。

这些文档不是直接复制到项目中，而是作为Claude的知识背景，帮助它在生成时遵循最佳实践。例如，当生成 resend domains list 命令时，Claude会参考 agent-first-patterns.md 中的规则，决定何时输出表格、何时输出JSON，以及如何构建 next_actions。

七、实际应用案例与价值

案例：AI驱动的客户支持自动化

假设你有一个客户管理系统，API 提供了获取用户、创建工单、发送通知等功能。使用 api2cli 生成CLI后，你可以让 Claude 扮演智能客服：

  1. 用户请求：“帮我查一下用户abc123的最近工单，并给ta发一封提醒邮件。”
  2. Claude 调用 crm users get abc123 获取用户信息。
  3. 调用 crm tickets list --user-id abc123 获取最近工单。
  4. 调用 crm notifications send --user-id abc123 --message "您的工单已有更新"。
  5. 整个过程 Claude 自主完成，你只需查看最终结果。

案例：运维自动化

对于内部基础设施API，如Kubernetes集群管理、云资源操作，生成CLI后，运维人员可以用自然语言指挥Claude执行复杂操作：

“将 staging 环境的 web 服务扩容到5个副本，然后检查所有pod状态。”

Claude 会依次调用 kubectl scale deployment web --replicas=5 和 kubectl get pods -l app=web（假设这些命令已被包装成CLI）。相比直接写脚本，这种方式更灵活，且AI能根据输出决定下一步。

案例：快速原型与测试

当你在开发一个新API时，可以先用 api2cli 生成CLI，然后直接通过命令行测试所有端点，而无需写测试代码。CLI 的双模输出让你既能看表格，也能拿到JSON做断言。甚至可以让 Claude 自动运行一系列测试命令并报告结果。

八、常见问题（FAQ）

api2cli 支持所有类型的API吗？

理论上支持RESTful API、部分GraphQL（通过解析抓包或主动探测）、以及符合常规模式的HTTP API。对于非标准API（如SOAP、XML-RPC），可能需要定制发现规则，但当前版本主要面向JSON over HTTP的现代API。

生成的CLI需要手动维护吗？

不需要。只要API不变，CLI可以一直使用。如果API有变更，可以重新运行 api2cli 生成新版本，并替换旧文件。由于技能文档独立存在，你甚至可以生成多个版本的CLI共存（例如v1和v2）。

如何处理API密钥等敏感信息？

CLI通过环境变量读取认证信息，例如 RESEND_API_KEY。这符合12-factor应用原则，也避免了密钥硬编码。在技能文档中会明确提示用户设置哪些环境变量。

生成的CLI能否用于生产环境？

可以。生成的代码经过充分测试（Claude会进行基本验证），且包含错误处理、重试等健壮性设计。但建议在关键场景下进行额外审查和测试。

技能文档如何被Claude识别？

技能文档放在 .claude/skills/ 下任意子目录中，文件名必须为 SKILL.md。Claude启动时会扫描该目录，解析YAML元数据，并在对话中根据描述和触发词自动加载。

九、总结与展望

api2cli 不仅仅是一个代码生成器，它代表了一种全新的“AI优先”工具设计哲学。通过将API封装为CLI，再将CLI封装为技能，我们构建了一个AI能够自主发现、调用、组合的工具集。开发者只需要一次投入，就能让AI助理永久拥有操作该API的能力。

未来，随着Claude Code生态的扩展，类似的技能可能会成为标准开发流程的一部分。试想，当你引入一个新的微服务，只需告诉Claude它的API文档，一个对应的CLI技能就自动诞生，并被所有项目成员共享。AI辅助开发将不再是“对话-复制-粘贴”的浅层互动，而是真正深入到工具链的自动化协作。

如果你对 api2cli 感兴趣，不妨立刻安装体验，让Claude为你最常用的API建一个CLI。你可能会发现，这比你想象中更简单、更实用。

本文基于 api2cli 项目官方文档撰写，所有技术细节均源于项目仓库。如需获取最新版本或贡献代码，请访问 GitHub：https://github.com/alexknowshtml/api2cli

退出移动版