用途
当数据来源是外部 API 或 SaaS 平台，而不是数据库或文件投放时，使用本技能。它用于帮助智能体设计可靠的数据抽取、分页、限流、认证处理以及可安全回填的摄取契约。
不要在把 API 当作静态表处理时使用；API 的行为、可用性和限额会随时间变化。
适用时机
- 从 REST 或 GraphQL API 抽取数据
- 摄取 SaaS 平台数据
- 处理分页、游标或同步令牌
- 应对限流与源端节流
- 安全地回填历史 API 数据
工作流程
- 定义源契约。包括：端点或对象名称、认证方式、抽取窗口、分页方式、限流、数据新鲜度预期。
- 为抽取韧性做设计。处理：重试、退避、令牌刷新、幂等重取行为、分页局部失败。
- 明确增量行为。判断数据源是否支持：更新时间戳、游标、变更令牌，还是仅支持全量快照。
- 在有用时记录原始源证据。API 数据源通常需要保留原始响应，以便进行事故诊断。
- 校验契约以应对源漂移。
常见误区
- “直接循环翻页就行。”——分页缺陷和重试缺口常导致静默数据丢失。
- “厂商 API 足够稳定。”——SaaS API 变更限流、字段和语义的频率往往超出团队预期。
- “请求失败就稍后重跑。”——缺少窗口划分和幂等规则时，重跑可能漏数据或重复数据。
危险信号
- 不存在限流策略
- 抽取窗口依赖未记录的源端行为
- 重试忽略重复或分页局部失败风险
- 未考虑认证轮换与令牌过期
验证项
- 源契约覆盖分页、限额、认证和节奏
- 抽取重试与失败在运维上是安全的
- 增量或快照行为已明确
- 已考虑源漂移与原始证据处理