migrating-from-customer-io

从 Customer.io 迁移

PostHog 会将 Customer.io 自动化导入为草稿工作流。草稿不会发送。由人员逐一审核，修复导入时无法保留的内容，然后启用。

你需要在两个 MCP 服务之间传递数据。从 Customer.io 的 MCP（或 cio CLI）读取数据，并将返回内容原样传给 PostHog 的 workflows-import-customerio。由 PostHog 完成转换，因此不要自行使用 workflows-create 重建工作流。

切勿迁移用户数据

只传递自动化、模板、发件人身份和细分受众名称。切勿获取或传递客户资料、细分受众成员、投递记录或事件数据。用户资料通常已在 PostHog 中，复制这些数据会带来用户未要求的隐私风险。

不要让邮件内容进入你的上下文

邮件模板体积很大，通常每个模板都包含数十 KB 的 HTML。当 PostHog 项目存储了 Customer.io App API 密钥时（运行过选择退出导入的团队会有此密钥），PostHog 会直接从 Customer.io 读取邮件内容。因此，请先传递自动化图结构，只有在 PostHog 要求时才读取模板。

步骤

1. 确认 PostHog 项目。 草稿会写入 PostHog MCP 的当前项目。使用 project-get 读取项目，告知用户其名称和 id，并询问是否应将草稿写入该项目。如果不是，则在读取 Customer.io 中的任何内容之前，使用 switch-project 切换项目。
2. 查找环境。 如果有多个 Customer.io 工作区，询问要迁移哪个工作区。其 id 就是以下所有路径中的 environment_id。
3. 列出自动化。 使用 Customer.io 读取工具（MCP 上的 cio_read_api，CLI 上的 cio api）调用 GET /v1/environments/{environment_id}/campaigns。该接口通过 page（从 0 开始）每页返回 20 条：读取所有页面，直到某页返回的条目少于 20 条。向用户展示列表及每个自动化的状态，并询问要迁移哪些自动化。通常选择正在运行的自动化；除非用户要求，否则跳过已归档的自动化。
4. 读取每个自动化。 调用 GET /v1/environments/{environment_id}/campaigns/{campaign_id}。保留响应中的 campaign 对象和顶层 actions 数组。campaign.actions 不存在。
5. 读取发件人和细分受众。 调用 GET /v1/environments/{environment_id}/identities?type=email，获取 sender_identities（id、email、name），并获取细分受众列表中的 segments（仅包含 id、name、type）。PostHog 会将每个邮箱匹配到地址相同的 PostHog 发件人，并在备注中标注细分受众名称。
6. 不读取模板进行预览。 调用 workflows-import-customerio，并传入 source: "customerio"、dry_run: true、campaigns: [{campaign, actions}]、sender_identities 和 segments。每次最多处理 50 个自动化。
7. 仅在需要时读取模板。 根据每个自动化的备注判断，而不是只看 content_fetched：true 仅表示 PostHog 读取了部分内容，一个自动化仍可能有消息未读取。对于备注指出消息内容未包含在导入中，或 PostHog 无法读取其消息的每个自动化，调用 GET /v1/environments/{environment_id}/templates/{template_id} 读取每个具有 template_id 的操作所用模板，保留 template 对象，然后使用 campaigns: [{campaign, actions, templates}] 再次预览。一次只读取一个模板：在大型工作区中列出所有模板会超时。告知用户，在 Workflows Opt-outs 标签页中使用 Import from Customer.io 会保存其 App API 密钥，这样下次就可以跳过此步骤。
8. 收集片段和布局。 如果备注中提到了 Customer.io 片段，或读取到的模板正文中包含 {{ snippets.name }}，则读取工作区片段，并将其作为 snippets（{name: content}）传入。PostHog 自行读取内容时也会读取片段，并会在备注中列出未能找到的片段。如果备注中提到了布局，则调用 GET /v1/environments/{environment_id}/layouts/{layout_id}，并将其 body 作为 layouts（{layout_id: body}）传入。
9. 报告预览结果。 对每个自动化，说明其状态和备注，并按级别分组（见下文）。对于状态为 failed 的项目，在导入前征求用户同意；其 validation_errors 会说明草稿被拒绝的原因。
10. 导入。 使用相同参数再次调用，并将 dry_run: false。分享每个草稿的链接（/workflows/{workflow_id}），并再次说明 needs_input 备注，因为团队必须先处理这些问题才能启用草稿。

如果不确定某个端点的参数，请仅查询该端点的架构（使用 resource.method 调用 cio_schema）。查询整个资源的架构会消耗数万个 token。

阅读备注

级别	含义	告诉用户什么
needs_input	草稿需要团队才能提供的设置：电子邮件发件人、触发群组、分支条件	这些会阻止启用。按工作流逐项列出。
approximated	此步骤在 PostHog 中的工作方式不同，例如等待时间最长为 30 天	启用前值得检查。
unsupported	此设置没有对应的 PostHog 功能，因此被省略，例如短信步骤	决定是否用其他方式重新构建。

相同的备注也会显示在 PostHog 应用中导入的工作流里，workflows-import-notes 会返回某个工作流的备注。

发件人和类别

电子邮件会使用 PostHog 中与其 Customer.io 发件人地址相同的发件人。如果 PostHog 中没有该地址的发件人，备注会列出该发件人并标记为 needs_input，以便用户将其添加为发件人。电子邮件的订阅主题会成为 PostHog 消息类别，该类别由导入流程根据该主题创建。如果主题未导入，备注会说明这一点。

细分群组和群组

Customer.io 细分群组不会导入。由细分群组触发的自动化会以空触发条件导入，并附带一条 needs_input 备注。如果用户已有与某个细分群组匹配的 PostHog 群组，传入 segment_cohorts: {"<segment id>": <cohort id>}，导入流程就会在该细分群组的触发条件和条件中使用此群组。群组触发条件需要实时群组。静态细分群组会有自己的备注：工作流无法检查静态群组，因此用户需要将其重建为条件。

推送通知

推送步骤会以 unsupported 备注导入，设备令牌不会随导入迁移。如果用户通过 Customer.io 发送推送通知，请告知用户：只有当设备上的应用通过 PostHog SDK 注册设备，或用户将导出的设备令牌导入 PostHog 推送渠道时，该设备才会关联到 PostHog。令牌导入是需要用户主动发起的独立步骤，因为令牌属于用户数据。

重新运行

再次导入自动化会替换其草稿，因此在 Customer.io 中修复问题后，可以重新运行导入。团队之后对该草稿所做的编辑会丢失，因此重新导入前请先征求同意。已有人启用的工作流，或用户无权编辑的工作流，绝不会更改：其结果为 skipped。

导入后

不要启用草稿。请引导用户查看 needs_input 备注，然后交由 building-workflows 技能进行测试和启用；这需要用户明确批准。