技能介绍

要解决的具体问题

构建 Klaviyo API 集成时，开发者常面临几个实际难题：SDK 与 MCP 的选择困惑——什么时候该用 SDK 写生产代码，什么时候该用 MCP 做探索性查询；事件 Schema 设计的复杂性——如何命名属性、哪些属性是必需的、如何处理嵌套数据在不同场景下的限制；集成健康审计——如何系统性地检查现有集成的数据质量、识别重复或不一致的指标、发现脆弱的流程触发器。

核心能力与工作流程

该技能采用 SDK 优先策略，明确区分 SDK 和 MCP 的使用场景：SDK 用于生产集成、批量同步、Webhook 处理和 CI/CD 环境；MCP 用于探索账户的事件 Schema、快速验证属性结构、调试流程触发条件。

核心能力覆盖七个领域：API 认证与版本管理、自定义事件追踪、Profile 管理、Webhook、SDK 使用、Catalog 同步、数据导出与仓库集成。提供 Python、Node.js、Ruby、PHP 四种语言的 SDK 快速参考，以及详细的速率限制表和 API 修订版本时间线。

对于新建集成，技能提供十步工作流程：定义需求 → API 密钥配置 → 事件 Schema 设计 → Profile 同步策略 → 实现追踪 → Catalog 同步 → Webhook 设置 → 速率限制策略 → 监控 → 测试验证。对于现有集成审计，提供八步健康检查流程，最终产出带严重性评级的审计报告（Critical/High/Medium/Low）。

适用边界与注意点

MCP 版本限制：官方 MCP 固定在 API 修订版本 2026-04-15，如果自己的 SDK 代码基于更早版本，需要注意兼容性。嵌套规则限制：模板可以访问嵌套对象，但流程条件分支和分段只支持顶层属性——如果需要在分段或分支中使用嵌套数据，必须将其扁平化为顶层属性。修订版本管理：始终在 API 请求中包含 revision: YYYY-MM-DD 头部，并固定到特定版本。速率限制：大多数端点 75 请求/秒，批量导入 10 请求/秒，Profile/Event 创建 350 请求/秒——需要在 429 响应时实现指数退避加抖动。

截图预览

使用场景

搭建电商订单同步管道时，需通过 Events API 发送 Placed Order 事件，确保包含 $value 和 Items 等必需属性。
现有 Klaviyo 集成中流程触发器频繁失效，需审计事件 Schema、检查属性命名一致性，识别嵌套数据在分段中的使用限制。
上线订阅业务线时，需设计 Account Created 和 Subscription Started 自定义事件，并将关键属性同步到 Profile 支持分段。
数据仓库需定期从 Klaviyo 拉取用户行为数据，需实现游标分页和速率限制处理。