用途
该技能用于指导将邮件/CDP 技术栈迁移到 Klaviyo，覆盖三类迁移场景：从已弃用的 Klaviyo v1/v2 API 迁移到当前 API、从竞品 ESP（Mailchimp、SendGrid 等）迁移到 Klaviyo、以及使用绞杀者模式（strangler fig pattern）进行平台重构。
主要能力
技能按迁移类型划分复杂度、时长与风险：Klaviyo v1/v2 到当前 API 为低至中等复杂度、1-2 周、低风险；Mailchimp/SendGrid 到 Klaviyo 为中等复杂度、2-4 周、中等风险；自定义 ESP 到 Klaviyo 为高复杂度、4-8 周、高风险；完整平台重构为高复杂度、2-3 个月、高风险。
工作流包含五个步骤：
- v1/v2 迁移到当前 API：用 klaviyo-api SDK 替换已弃用的 track / identify / v2 subscribe HTTP 调用，改用 createOrUpdateProfile、createEvent、subscribeProfiles。会话骨架为：
import { ApiKeySession, ProfilesApi, EventsApi } from 'klaviyo-api';
const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);
const profilesApi = new ProfilesApi(session);
const eventsApi = new EventsApi(session);
-
API 字段映射：将 v1/v2 字段重命名为当前 schema，去掉 $ 前缀、统一改为 camelCase（$first_name → firstName），并将地址字段嵌套到 location 下。
-
竞品迁移：编写转换适配器，将竞品联系人结构映射为 Klaviyo profile，然后批量导入（每批 50 条），使用 Promise.allSettled、进度日志和限流延迟，跳过已抑制/已退订联系人。
-
绞杀者模式：通过功能开关后的 MigrationRouter 路由流量，将 Klaviyo 从 0% 逐步提升到 100%，可选双写以作对比。
-
迁移后验证：运行 validateMigration() 对比 profile 数量、样本数据完整性和列表成员关系，再下线旧系统。
使用方式
前置条件包括：已配置目标 Klaviyo 账户、安装 klaviyo-api SDK（npm install klaviyo-api）、可访问源系统以导出数据、具备功能开关基础设施（用于渐进式发布）。认证方式为：将 Klaviyo 私有 API 密钥（pk_***）导出为 KLAVIYO_PRIVATE_KEY，供 SDK 的 ApiKeySession 使用；旧版 v1/v2 调用在请求体中使用公共 token，当前 REST API 在会话头中使用私有密钥。
最小首次切换示例（当前 API 上的单条 profile upsert）：
await profilesApi.createOrUpdateProfile({
data: {
type: 'profile',
attributes: { email: 'user@example.com', firstName: 'Jane', properties: { plan: 'pro' } },
},
});
输出
使用该技能可产出：迁移后的代码（v1/v2 HTTP 调用替换为 klaviyo-api SDK 调用，或竞品到 Klaviyo 的转换适配器加批量导入运行器）；导入结果 { imported, skipped, failed[] }，其中 failed 列表可用于定向重试；MigrationRouter（用于渐进式切换），在功能开关后按可配置百分比将流量路由到 Klaviyo；验证报告 { passed, checks[] }，覆盖 profile 数量、数据完整性和列表成员关系，作为下线旧系统前的 go/no-go 门槛。
适用场景
适用于从 Klaviyo 旧版 API 升级、从竞品 ESP 迁移、自定义 ESP 迁移或完整平台重构等场景，尤其适合需要渐进式灰度切换和迁移后验证的团队。
限制
技能文档未提供具体收费、价格或效果数据。错误处理对照表列出常见问题：重复 profile（同一邮箱导入两次，应使用 createOrUpdateProfile 做 upsert）、电话格式错误（非 E.164 格式，需预校验并格式化为 E.164）、导入时限流（批次过大或过快，需减小批次并增加延迟）、缺少同意时间戳（历史数据，需设置 historicalImport: true 标志）、模板渲染错误（模板语法不兼容，需转换为 Klaviyo Django 模板语法）。完整实现代码位于 references/implementation.md，端到端示例位于 references/examples.md。