data-import

/digital-marketing-pro:data-import

脚本位置。 如果宿主未设置 ${CLAUDE_PLUGIN_ROOT}，脚本位于此插件的 scripts/ 文件夹中，与 skills/ 文件夹同级。请使用 Python 3.10 或更高版本运行：使用 python；如果找不到 python，则使用 python3（macOS 和许多 Linux 系统）。

用途

通用数据导入工具，可将结构化数据导入任何已连接的平台。可从 CSV、JSON 或 Google Sheets 导入数据到 CRM 系统、电子邮件订阅者列表、受众细分、竞品跟踪工具、营销活动管理器或自定义数据存储。处理完整的导入流程——自动建议字段映射、数据验证、与现有记录去重、联系人数据的同意与合规性验证、通过平台 MCP 执行分批写入，以及在需要时提供详细结果报告和回滚指导。

执行门槛（必须遵守——不可跳过）

1. 在操作任何线上系统之前，先提供完整预览——收件人 / 支出 / 变更 / 合规性——作为执行摘要。
2. 用户必须输入 yes（或明确表示批准的等效内容）。任何其他输入——含糊、暗示、部分批准或未作批准——都会取消此次运行。
3. 切勿根据含糊的输入继续执行。执行失败后切勿自动重试；失败后必须由人工审核，才能重新运行。
4. 只有在用户输入 yes 后，才记录批准：python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"data-import","platform":"<platform>","content_summary":"<one line from the Execution Summary>","risk_level":"<tier>"}'，然后运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action approve --id {approval_id}。如果任一命令报错，立即停止并报告错误；切勿通过其他工具绕过。该记录证明此操作执行了审批步骤，但无法证明是谁输入了 yes。
5. 执行操作。通过 connector_executor.py 发送的写入操作需要 --approval-id，且只有在记录匹配、未使用且未过期时才会执行（参见 /digital-marketing-pro:execute-action）。通过已连接 MCP 服务工具执行的写入操作不受该代码检查约束：此类操作依赖用户输入的 yes 以及宿主的权限提示。之后运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action mark-executed --id {approval_id} --data '{"execution_result":"success"}'（或将结果设为 failure）。

所需输入

用户必须提供（或将被提示提供）：

• 数据源：本地 CSV 或 JSON 文件的路径，或 Google Sheets URL——即要导入的原始数据。对于 CSV，如果分隔符不是标准分隔符，请指定分隔符。对于 Google Sheets，如果不是第一个工作表的全部内容，请指定工作表名称和范围。当前环境必须能够访问该文件
• 目标平台：数据的导入目标——CRM（HubSpot、Salesforce）、电子邮件平台（Mailchimp、ActiveCampaign、SendGrid）、受众管理器、竞品跟踪工具或自定义目标。必须已在 .mcp.json 中连接并配置相应的 MCP 服务
• 字段映射：源列与目标字段之间的映射方式——提供明确映射（例如，“Company Name” -> “company”，“Work Email” -> “email”），或请求自动映射，由系统根据列名相似度建议映射。未映射的列会被标记以供审核；未映射的必填目标字段会阻止导入，直至问题解决
• 导入选项（可选）：去重策略（跳过重复项 skip、更新现有记录 update，或无论如何都创建新记录 create-new——默认值为 skip）、同意验证级别（strict 要求提供明确的选择加入字段，standard 检查退订标记，none 用于非联系人数据）、API 写入的批次大小（默认值为 100），以及用于验证但不执行操作的试运行模式

流程

1. 加载品牌上下文：读取 ~/.claude-marketing/brands/_active-brand.json 获取当前启用的 slug，然后加载 ~/.claude-marketing/brands/{slug}/profile.json。针对目标市场应用合规规则（skills/context-engine/compliance-rules.md）——尤其是 GDPR、CAN-SPAM 和 CCPA 对联系人数据导入的要求。检查 ~/.claude-marketing/sops/ 中是否有机构的 SOP。如果没有品牌，请询问：“先设置品牌？（/digital-marketing-pro:brand-setup）”——或者使用默认设置继续。
2. 读取并解析源数据：从指定来源加载数据——通过检测表头并处理分隔符来解析 CSV，通过推断架构来解析 JSON，或者通过 Google Sheets MCP 从 Google Sheets 获取数据。验证基本格式完整性——所有行的列数一致、数据类型可解析、没有完全为空的行或列。报告来源统计信息：记录总数、检测到的列、推断的数据类型。
3. 字段映射向导：根据源列名与目标字段名的相似度自动建议映射（对 "email"、"first_name"、"phone"、"company" 等常见模式进行模糊匹配）。向用户展示建议的映射并请求确认。标记未映射的源列（将被忽略的数据）以及未映射的必填目标字段（必须在导入前解决的阻碍项）。允许用户调整、新增或移除映射。
4. 验证数据质量：对每条记录运行验证检查——验证电子邮件格式（RFC 5322）、检测电话号码格式、检查必填字段是否存在且非空、检查数据类型是否符合要求（日期、数字、字符串），以及字段长度是否符合目标平台的限制。检测导入文件内部的重复项。如果已连接 CRM，则使用电子邮件或电话号码作为匹配键，检查是否与现有记录重复。对于电子邮件和 SMS 导入，验证同意字段——检查明确的选择加入时间戳、退订标记，以及是否符合品牌所在市场的法规。
5. 创建审批关卡：呈现全面的导入摘要，供用户确认——源数据中的记录总数、通过验证的记录数、未通过验证的记录数（附分类原因）、检测到的重复记录数（文件内和现有数据中的重复项）、联系人导入的同意验证状态、目标平台和目标对象类型、字段映射摘要，以及将采用的去重策略。用户明确批准前，禁止执行。
6. 通过目标 MCP 执行导入：获批后，通过相应的 MCP 分批向目标平台写入记录——通过 CRM MCP 导入 CRM 联系人（HubSpot 或 Salesforce），通过电子邮件 MCP 导入电子邮件订阅者列表（Mailchimp、ActiveCampaign 或 SendGrid），通过 competitor-tracker.py 导入竞争对手基准数据，或者通过受众管理器导入受众细分。逐条跟踪成功、失败和跳过状态。达到速率限制时执行退避；仅在能确定写入从未到达平台时重试（连接被拒绝、DNS 故障或被 429 速率限制拒绝）；超时或回复丢失后，先在平台上查找该记录（按电子邮件或外部 ID），然后仅重新发送缺失的数据：绝不能仅因超时而重新发送。
7. 报告结果：生成详细的导入结果报告——成功导入的记录及其目标 ID、失败记录及每条记录的具体错误原因、因去重或验证而跳过的记录、同意验证摘要、API 调用总次数和处理时间。如果失败记录超过总记录数的 10%，请标记以供审核，并提供回滚指引。

输出

包含以下内容的结构化导入结果报告：

• 导入摘要：已处理、成功导入、失败、已跳过（重复项）和已跳过（验证失败）的记录总数，以及百分比细分和处理时间
• 使用的字段映射：源列与目标字段之间最终应用的映射，包括自动映射的字段和用户覆盖的映射，供审计追踪和未来导入时重用
• 验证报告：按类别列出发现的数据质量问题——无效电子邮件、缺少必填字段、格式不匹配、字段长度超限——并列出每类问题涉及的记录数和示例值
• 同意验证状态：对于联系人数据导入——已验证选择加入的记录数、缺少同意的记录数、带有退订标记的记录数，以及针对品牌目标市场法规（GDPR、CAN-SPAM、CCPA）的合规性评估
• 目标平台确认：平台名称、对象类型、批次数量、API 响应摘要，以及成功导入记录的目标记录 ID（如有）
• 失败记录的错误详情：按错误类型分组列出每条记录的失败原因——API 验证错误、速率限制（429）拒绝（针对有确凿证据表明从未到达平台的写入，在允许的重试次数用尽后仍被拒绝）、权限错误，以及目标平台拒绝的数据格式
• 回滚说明：如果需要撤销导入——要删除的记录 ID、要使用的 API 端点，以及目标平台的批量删除指南

使用的 Agent

• execution-coordinator — 负责导入流水线编排，涵盖从源数据解析到 MCP 执行的全过程；通过全面的导入前摘要和风险评估处理审批工作流；执行批量 MCP 数据写入，重试仅限于有确凿证据表明从未到达平台的写入，并处理错误；记录执行日志并跟踪每条记录的状态；为失败或存在问题的导入生成回滚指南
• crm-manager — 提供具备平台架构认知能力的 CRM 专用字段映射智能（HubSpot 属性、Salesforce 字段），使用电子邮件和电话号码匹配键与现有 CRM 记录进行去重，评估联系人数据质量，并根据品牌目标市场的合规要求验证同意字段