概述
API技能是一个面向开发者的综合性REST API参考文档库，涵盖147个主流第三方服务，按AI/ML、支付、通信、CRM等17个领域分类组织。该技能不提供可执行代码，而是作为技术文档参考工具，帮助开发者快速查阅API集成所需的关键信息。
核心用法
技能采用分类文档架构，每个领域对应一个markdown文件（如apis/ai-ml.md、apis/payments.md）。使用前需先阅读setup.md了解指引规范。每个API文件顶部设有索引表，标注各API名称与行号范围，支持精准定位。典型工作流程：通过API Categories表格定位服务所属文件 → 读取文件索引 → 使用行号跳转精确阅读目标API章节（每节约50-100行）。
文档内容涵盖四大核心维度：认证模式（OAuth2、API Key、JWT等）、端点参考（附curl示例）、速率限制与分页模式、常见陷阱警示。另设专题文件深入讲解认证模式(auth.md)、分页策略(pagination.md)、容错处理(resilience.md)及Webhook实现(webhooks.md)。
显著优点
覆盖广度：147个服务横跨AI大模型（OpenAI、Anthropic）、金融科技（Stripe、Plaid）、企业软件（Salesforce、HubSpot）至新兴工具（Clerk、Novu），形成一站式查阅体验。结构效率：索引+行号跳转机制避免全文检索，显著降低信息获取成本。实践导向：每个API配套curl示例与"gotchas"章节，直击集成痛点如Content-Type遗漏、密钥泄露风险、幂等键使用等。跨平台适配：支持Linux、macOS、Windows三端，依赖仅curl与jq。
局限性与风险
纯文档属性：技能明确声明"documentation only"，不包含SDK封装、类型定义或自动代码生成，开发者需自行管理API密钥与请求编排。时效依赖：第三方API迭代频繁（尤其AI领域），文档版本1.3.1可能存在滞后，关键集成应交叉验证官方文档。安全合规：虽然文档倡导密钥入Header而非URL参数、建议使用幂等键，但用户侧仍可能因误操作导致密钥泄露或重复扣款。无执行验证：curl示例未经实时测试，端点变更、字段废弃等无法自动感知。
适合人群
- 需快速比对接多供应商API方案的技术负责人
- 首次集成特定服务（如首次对接Stripe或SendGrid）的后端开发者
- 编写集成代码时查阅认证细节与分页策略的工程师
- 排查"明明返回200为何业务失败"类问题的调试场景
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 密钥泄露 | 示例中的占位符KEY可能被误填真实密钥并提交至版本控制 | 使用.env文件与gitignore，启用密钥扫描工具 |
| 速率超限 | 忽视`X-RateLimit-Remaining`导致429封禁 | 实现指数退避重试，预设告警阈值 |
| 数据误操作 | 支付类API未用幂等键造成重复扣款 | 生产环境强制Idempotency-Key头部 |
| 分页遗漏 | 默认limit=10未处理致数据不完整 | 循环检查`has_more`或`next_cursor` |
| 版本漂移 | 文档与官方API版本不一致 | 关键字段以官方OpenAPI/Swagger为准 |