data-export

/digital-marketing-pro:data-export

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

用途

将营销数据（指标、联系人、活动结果和绩效快照）导出到外部数据存储，以进行分析、报告或与其他工具集成。支持 BigQuery，用于数据仓库和高级分析；支持 Google Sheets，便于与利益相关方共享和协作；支持 Supabase，用于自定义数据库和应用程序集成。将原始营销数据转换为整洁、结构化的表格格式，并提供完整的架构文档，便于下游使用。将联系人数据导出到共享目标位置时，会处理 PII 脱敏，以确保符合隐私法规。

使用此命令将数据从营销系统中导出，用于外部分析、客户报告或数据仓库集成。如果要专门导出受众细分，请先使用 /digital-marketing-pro:segment-audience 创建细分，然后再使用此命令导出成员数据。

执行门槛（强制 — 不可跳过）

1. 在接触任何线上系统之前，先将完整预览（收件人 / 支出 / 变更 / 合规性）作为执行摘要呈现。
2. 用户必须输入 yes（或明确等效的批准）。任何其他输入（含糊、暗示、部分或未提供的批准）都会取消本次运行。
3. 不得在输入含糊时继续。执行失败后不得自动重试；任何重新运行都需要人工审核。
4. 只有在用户输入 yes 后，才记录批准：python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"data-export","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）。

必需输入

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

• 数据类型：要导出的内容 — 指标（KPI、渠道表现、漏斗指标）、联系人（CRM 记录、细分群体、潜在客户名单）、营销活动（结构、设置、定向、创意）、表现数据（每日/每周快照、趋势数据、同比对比），或自定义查询（由用户定义的特定字段和筛选条件）
• 目标位置：导出到哪里 — BigQuery（项目、数据集和表名）、Google Sheets（现有电子表格 ID，或使用指定名称新建），或 Supabase（项目引用、架构和表名）
• 日期范围：导出的时间段 — 指定开始和结束日期、相对时间窗口（过去 7/30/90/365 天）、本季度至今、本年至今，或所有可用的历史数据
• 筛选条件（可选）：用于缩小导出范围的条件 — 特定渠道、营销活动、受众细分群体、地理市场、设备类型、表现阈值（例如，仅导出 ROAS 高于 2.0 的营销活动），或自定义字段值
• 格式偏好：列排序优先级（维度优先或指标优先）、命名约定（snake_case、camelCase、Title Case）、日期格式（ISO 8601、MM/DD/YYYY、YYYY-MM-DD）、货币格式（符号、代码、小数位数）、时间戳时区，以及是否包含计算字段（百分比、比率、环比变化）
• 追加或替换：是否将新数据追加到现有目标表/工作表，或替换全部内容 — 对于定期导出至关重要；追加可避免数据重复，而替换可确保生成干净的快照
• 架构偏好（可选）：自定义列定义、数据类型或转换 — 例如，“将全名拆分为 first_name 和 last_name”、“将所有货币转换为 USD”、“将每日数据汇总为每周数据”或“将渠道透视为列”
• 计划安排（可选）：这是一次性导出，还是应保存为定期导出模板 — 如果是定期导出，请指定频率（每日、每周、每月）和任何条件触发器（例如，仅在有新数据时导出）
• 访问权限（可选）：对于 Google Sheets，指定谁可以访问（特定电子邮件地址、整个网域或公开链接）。对于 BigQuery，指定哪些服务账号或用户需要查询权限。对于 Supabase，指定哪些 API 密钥或角色需要读取权限。
• PII 处理（可选）：是否对个人身份信息进行编辑、哈希处理或匿名化 — 在将联系人数据导出到共享目标位置或安全性较低的环境时尤其相关
• 对比基准（可选）：是否在当前导出数据旁包含上一期间的数据以进行趋势分析 — 例如，并排包含本月和上月的数据，或添加环比变化列
• 汇总行偏好（可选）：是否包含汇总行 — 在导出内容底部添加总计、平均值或加权平均值，便于快速查看，无需额外计算
• 完成通知（可选）：导出完成时是否发送通知 — 通过电子邮件发送下载链接、通过 Slack 发送包含摘要统计信息的消息，或在 CRM 活动日志中记录导出数据的引用

流程

1. 加载品牌背景：读取 ~/.claude-marketing/brands/_active-brand.json 获取当前品牌 slug，然后加载 ~/.claude-marketing/brands/{slug}/profile.json。遵循品牌语气、目标市场的合规规则（skills/context-engine/compliance-rules.md）和行业背景。同时检查指南：查看 ~/.claude-marketing/brands/{slug}/guidelines/_manifest.json；如果存在，则加载限制要求和相关类别文件。检查 ~/.claude-marketing/sops/ 中是否有代理机构的 SOP。如果不存在品牌，请询问：“先设置一个品牌吗（/digital-marketing-pro:brand-setup）？”——或者使用默认设置继续。
2. 从可用来源收集数据：从本地存储收集数据——~/.claude-marketing/brands/{slug}/campaigns/（通过 campaign-tracker.py --action list-campaigns）、~/.claude-marketing/brands/{slug}/executions/（通过 execution-tracker.py --action get-history）、~/.claude-marketing/brands/{slug}/performance/ 快照、洞察文件和细分群体导出文件——并根据请求的数据类型和日期范围，从已连接的 MCP（Google Analytics、广告平台、CRM、电子邮件平台）收集数据。必要时合并多个来源的数据，并按来源优先级解决冲突。
3. 将数据转换为表格格式：将收集到的所有数据规范化为扁平表格结构——将嵌套的 JSON 对象展开为列，统一日期格式和时区，将货币值规范为请求的币种单位，应用列命名规范，计算派生字段（CTR、ROAS、CPA、转化率、同期变化），并根据字段类型，以一致的方式处理空值（空字符串、“N/A”或 0）。
4. 应用筛选和排序：根据用户指定的条件筛选记录——日期范围、渠道、营销活动、细分群体或自定义条件。按最相关的维度排序（默认按日期降序，或按指定方式排序）。删除重复行，并验证联接数据集之间的引用完整性。
5. 验证数据质量：检查转换后数据集的完整性和准确性——按列统计缺失值（空值百分比）、检测异常值（超出 3 个标准差的值）、检查日期连续性（日数据中没有意外的间隔）、验证引用完整性（营销活动 ID 与名称匹配、渠道名称一致），并检查行数是否合理（如果行数明显多于或少于该日期范围的预期值，则标记出来）。
6. 检查目标位置的连接和架构：验证是否有权访问目标位置——BigQuery 数据集写入权限和配额、Google Sheets API 访问权限和工作表大小限制，或 Supabase 连接凭据和表权限。确认目标表或工作表存在（或使用正确的架构创建），并在向现有数据追加内容时验证架构兼容性（列名、数据类型和顺序必须匹配）。
7. 设置审批关卡：将数据导出的风险评估为低。提供导出预览，显示总行数、含数据类型的列架构、以格式化表格展示的前 5 行数据、目标位置详情（URL/路径）、追加/替换模式、预计文件大小，以及需要留意的任何数据质量警告。
8. 获批后，通过目标 MCP 导出：通过相应 MCP 将数据推送到目标平台——小型数据集通过 BigQuery MCP 使用流式插入，大型数据集使用加载作业；通过 Google Sheets MCP 使用批量更新（含格式设置）；通过 Supabase MCP 使用 upsert 并处理冲突。处理大型数据集的分页，仅在能够确认写入从未到达平台时重试（连接被拒绝、DNS 故障或收到 429 速率限制响应）；超时或回复丢失后，先在平台上查询记录（BigQuery 流式插入在超时后重试会造成行重复；应先统计平台上已有的行），只重新发送缺失的数据。如果有指定，则应用访问权限。
9. 应用 PII 处理规则：如果指定了 PII 处理方式，则相应处理联系数据字段——对电子邮件地址脱敏（j***@example.com）、对电话号码进行哈希处理（SHA-256）、匿名化姓名，或完全删除 PII 列。记录修改的字段及所用处理方法，以供审计。
10. 应用 Google Sheets 格式设置（如适用）：对于 Google Sheets 导出，应用专业格式设置——冻结标题行、自动调整列宽、应用数字格式（货币、百分比、整数）、为 KPI 添加条件格式（高于/低于目标时显示绿色/红色），并创建命名范围，以便在公式和图表中轻松引用。
11. 验证导出完整性：导出完成后，在目标位置验证数据完整性——确认行数与来源一致，抽查 5 个值并与源数据核对，验证架构是否正确应用（列名、数据类型、格式），对于 Google Sheets，还要确认标题、列宽、数字格式和条件格式均正确显示。
12. 记录执行情况并保存模板：记录完整的导出信息——时间戳、数据类型、所用来源、行数、列数、目标位置 URL/路径、应用的 PII 处理方式、耗时、数据质量评分及任何警告——并保存到 ~/.claude-marketing/brands/{slug}/logs/data-export-log.json。如果用户要求设置计划，则将导出配置保存为可重复使用的模板，路径为 ~/.claude-marketing/brands/{slug}/templates/exports/。

输出

包含以下内容的结构化数据导出报告：

• 导出确认：目标 URL 或 ID — BigQuery 完全限定表路径（project.dataset.table）、注明访问级别的 Google Sheets 可分享 URL，或附带连接详情的 Supabase 表引用 — 并提供直接访问链接
• 行数验证：源行数与目标行数对比及匹配确认；导出过程中跳过的行及具体原因（键为空、架构违规、超过大小限制）；以及传输的数据总量
• 列架构（数据字典）：完整列清单，包含数据类型、易于理解的描述、示例值、源系统、计算公式（用于派生字段）和空值率 — 可作为供任何使用导出数据的人查阅的文档
• 数据质量摘要：每列的完整度得分（非空值百分比）、标记的异常值及其值和上下文、日期范围覆盖情况确认、引用完整性结果，以及总体数据质量等级（根据完整度和一致性评定 A/B/C）
• 前 5 行预览：导出数据在目标位置呈现的样例 — 用于目视核验格式、列顺序、数字精度、日期格式和数据准确性
• 导出元数据：时间戳、总耗时、使用的数据源及各来源的记录数、应用的筛选条件、追加/替换模式，以及已完成的处理步骤
• 访问和共享详情：哪些人可以访问导出的数据 — 对于 Google Sheets，列出共享设置以及查看者/编辑者；对于 BigQuery，列出获授权的用户/服务账号；对于 Supabase，列出 API 访问配置
• PII 处理审计：已修改或脱敏的字段、每个字段的处理方法（脱敏、哈希处理、匿名化、移除），以及所采用 PII 处理方式的合规性依据
• 已应用的 Google Sheets 格式（如适用）：格式设置详情 — 冻结的行/列、条件格式规则、创建的命名范围、数字格式模式，以及添加的图表或汇总行
• 执行日志：带时间戳的导出流程记录 — 对源端和目标端的 API 调用、批次大小、响应状态、重试（仅限有证据证明从未到达平台的写入操作）、速率限制等待，以及各步骤的处理时长
• 与上次导出的对比（如定期导出）：行数变化、新增或移除的列、数据新鲜度对比，以及可能表明上游数据发生变化的架构漂移警告
• 源数据新鲜度：每个数据源中最新数据点的时间戳 — 用于确认导出是否反映了最新可用数据，以及是否有任何数据源的数据已过时并可能影响分析准确性
• 目标健康检查：导出后对目标的验证 — BigQuery 表大小和查询成本估算、Google Sheets 行数/单元格数相对于限制的使用情况，或 Supabase 存储用量和 API 速率状态
• 可复用的导出模板（如有请求）：用于定期导出的已保存配置文件路径 — 数据类型、筛选条件、目标、架构、计划频率、PII 处理规则，以及通过单条命令重新执行完全相同导出所需的全部参数

使用的 Agents

• analytics-analyst — 跨平台数据收集、转换逻辑、架构设计、派生指标计算、数据质量验证、异常值检测、导出验证和目标健康监控
• crm-manager — 从 CRM 提取数据、检查联系人数据合规性、制定 PII 处理和脱敏规则，以及映射 CRM 记录导出的字段
• execution-coordinator — 导出审批工作流、验证目标连接、管理批量执行、将重试限制在有证据证明从未到达平台的写入操作，并发送完成通知