send-report

/digital-marketing-pro:send-report

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

用途

从已连接的分析来源生成格式化的效果报告，并通过 Slack、电子邮件或 Google Sheets 发送。支持每周简报、月度回顾、QBR 和自定义报告类型。从已连接的平台提取实时指标，根据目标和前期数据计算 KPI，添加趋势分析与异常检测，生成可执行的建议，然后按照用户偏好的渠道进行格式化和发送，并设置适当的审批关卡。

执行关卡（强制 — 不可跳过）

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

所需输入

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

• 报告类型：报告格式——weekly-pulse（核心指标和亮点，1 页）、monthly-review（完整的渠道细分及趋势，3-5 页）、qbr（包含战略分析和建议的季度业务回顾，8-12 页），或 custom（由用户定义指标选择和结构）
• 交付渠道：报告发送位置——Slack（以格式化区块发布到频道或通过私信发送）、email（通过 SendGrid 或已连接的 email MCP 发送 HTML 报告），或 Google Sheets（新建电子表格，或追加到现有跟踪表格）
• 日期范围：报告周期——过去 7 天、过去 30 天、上一季度、自定义开始和结束日期，或“自上次报告以来”，以从执行日志中自动检测上次交付时间戳
• 收件人：可选——Slack 频道名称或用户账号、分发列表中的电子邮件地址，或目标受众的 Google Sheets 共享权限和通知设置
• 自定义指标：可选——报告类型默认指标之外需要纳入或排除的特定指标、自定义 KPI 定义、计算字段（例如，混合 CAC、受营销影响的销售管道），或需要单独分析的特定 campaign ID
• 对比周期：可选——与上一周期（WoW、MoM、QoQ、YoY）、特定自定义日期范围，或品牌档案中定义的目标和预测进行对比
• 报告品牌设计：可选——加入品牌标志、自定义配色方案、页眉和页脚文本，或用于面向客户或代理机构交付的白标格式
• 叙述深度：可选——仅提供执行摘要（3-5 句话）、标准版（摘要加渠道分析），或深度分析（完整分析，包含假设和测试建议）
• Campaign 筛选条件：可选——仅分析特定 campaign、渠道或受众细分的数据，而非报告所有活动
• 基准：可选——纳入行业基准以提供背景信息、来自先前分析的竞争情报，或品牌定义的自定义基准
• 注释：可选——在报告中标注的关键事件（campaign 上线、促销、季节性活动、预算变更），为指标变化提供背景信息
• 分发计划：可选——设置报告按指定频率（每周、每月、每季度）使用相同配置自动定期生成
• 高管受众：可选——列出将阅读报告的具体利益相关者，以便相应调整叙述语气和指标抽象层级

流程

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. 从已连接的分析平台提取指标：运行 performance-monitor.py，从已连接的分析 MCP 服务收集数据——Google Analytics（流量、转化）、Google Ads（支出、CPC、ROAS）、Meta Ads（支出、覆盖人数、频次）、LinkedIn Ads（支出、潜在客户）、电子邮件平台（打开率、点击率、送达率）以及其他已配置的数据源。汇总指定日期范围和对比周期的指标。
3. 对照目标计算 KPI：将实际表现与 profile.json 中定义的目标以及对比周期进行比较。计算周期环比变化、百分比变化、趋势方向，以及关键变动的统计显著性。对于高于或低于目标超过 10% 的指标，使用严重程度标记（警告、严重）。
4. 识别趋势和异常：分析报告时间范围内的指标走势——识别持续上升或下降的趋势（连续 3 个或更多周期）、突然的峰值或跌幅（单周期变动超过 2 个标准差）、季节性模式，以及可能表明归因变化或预算重新分配机会的渠道间相关性。
5. 叠加事件注释：将用户提供的注释（活动启动、促销、预算变更、外部事件）映射到时间线上，使指标变动可以结合已知事件进行解读。如果有执行日志，则自动检测注释。
6. 生成建议：根据表现数据，提出 3-5 条可执行建议，并按预期影响排序——扩大哪些投入（表现出色且仍有增长空间）、暂停哪些投入（消耗预算但表现不佳）、测试哪些内容（根据异常提出假设），以及调查哪些情况（无法解释的变动）。每条建议都要关联具体数据点，并估算影响范围。
7. 生成报告内容：运行 report-generator.py，根据所选类型编制完整报告——执行摘要（发生了什么、为何重要、下一步行动）、包含迷你趋势图和状态指标的 KPI 仪表板部分、包含周期环比比较的逐渠道分析、带可视化图表的趋势分析、附带调查提示的异常标记，以及按优先级排列的建议。根据报告类型应用相应的模板详略程度。
8. 按交付渠道设置格式：根据所选渠道设置报告内容格式——Slack（结构化消息块，包含加粗指标、表情符号标记，以及作为附件的图表图片）、电子邮件（响应式 HTML 模板，包含内嵌图表、摘要表和指向平台仪表板的深层链接按钮），或 Google Sheets（设置结构化工作表标签页，包括摘要、渠道详情和原始数据，并使用条件格式、迷你图公式和图表对象）。如果指定了品牌格式，则应用该格式。
9. 创建审批记录：通过 approval-manager.py --action create-approval 创建记录，并在 --data JSON 中指定风险级别——内部团队收件人使用 {"type":"send-report","platform":"<platform>","content_summary":"...","risk_level":"low"}；外部利益相关方、面向客户的交付或包含收入/财务数据的报告使用 "medium"。不存在 --risk-level 标志；具体命令请参阅上文的执行门控。生成报告预览并附上交付配置。
10. 展示报告预览：展示完整报告内容供用户审核——执行摘要、带趋势指标的关键数据、渠道重点、异常标记和建议。显示交付配置——渠道、收件人、格式和品牌信息。等待用户明确批准后再发送。
11. 通过 MCP 交付：获批后，通过已连接的 MCP 服务交付报告——将报告发布到 Slack 频道并附上串接详情，通过电子邮件平台发送带跟踪功能的 HTML 邮件，或创建并分享设置了适当权限的 Google Sheets 文档。根据渠道要求处理附件、图表图片和格式。
12. 验证交付：确认报告已成功交付——检查 Slack 消息的发布状态、电子邮件送达确认，或 Google Sheets 分享权限是否已设置。发生故障时，报告错误详情；只有能够确认写入操作从未到达平台时才重试（连接被拒绝、DNS 故障或 429 速率限制拒绝）。超时或回复丢失后，先在平台上查找记录（消息是否已在频道或收件箱中？），仅当记录不存在时才重新发送。
13. 归档报告快照：将报告内容和关键指标的副本保存到品牌洞察历史记录中，用于历史比较和跨报告周期的趋势跟踪。
14. 记录交付日志：运行 execution-tracker.py，记录报告交付信息，包括时间戳、报告类型、日期范围、交付渠道、收件人列表、关键指标值，以及用于去重和频次跟踪的报告内容哈希。

输出

结构化报告交付确认，包含：

• 报告内容：完整的生成报告，包含执行摘要、KPI 仪表板、逐渠道分析、趋势分析、异常标记和按优先级排序的建议
• 交付确认：渠道、收件人、时间戳和交付状态（已发送、已发布或已共享），以及已交付报告的直接链接——Slack 消息 URL、电子邮件跟踪 ID 或 Google Sheets URL
• 指标摘要：精简表格中的核心 KPI——指标名称、实际值、目标值、与目标的差值、与上一周期相比的变化，以及趋势方向指示（上升／下降／持平）
• 绩效亮点：本报告周期表现最好的 3 项（表现最强）和最值得关注的 3 项（表现不佳或存在异常），并提供支持性数据点和背景信息
• 建议：3-5 项按优先级排序的行动项，包含预期影响估算（收入、效率或增长）、工作量级别（快速见效、中等、重大）和紧急程度评级（立即采取行动、本周、本月）
• 趋势分析：关键指标的变化轨迹，包含方向、变化速度、拐点，以及任何检测到的异常、推测原因和调查提示
• 对比数据：所有报告指标的周期环比和目标值与实际值对比表，包含变化百分比和统计显著性标记
• 报告元数据：报告类型、日期范围、使用的数据源及其新鲜度时间戳、因数据缺失或不完整而排除的指标，以及采用的对比基准
• 基准背景：在适用时，与行业基准进行对比，展示品牌在关键指标上的表现相对于行业平均水平的排名
• 数据质量说明：用于计算的任何数据缺口、延迟指标、平台 API 问题或估算值，确保审阅报告的利益相关方了解情况
• 下次报告安排：根据当前频率（每周、每月、每季度）建议下次报告日期，并提示用户可按需设置自动交付
• 事件注释：在时间线上标注营销活动启动、促销、预算变更和外部事件，为报告周期内的指标变化提供背景信息
• 报告归档参考：历史对比所用的归档报告快照链接，便于追踪同一指标在连续报告周期内的变化
• 分发计划状态：如果请求定期交付，则确认自动计划已设置，并提供下次交付日期和频率
• 执行日志条目：带时间戳的报告生成和交付记录，用于审计追踪、频率追踪和历史报告归档参考

使用的 Agent

• analytics-analyst — 汇总已连接平台的指标、根据目标计算 KPI、分析趋势并检测异常、映射事件注释、评估绩效、对比基准、分析跨渠道相关性，并生成包含影响估算的可执行建议
• execution-coordinator — 根据交付渠道规范设置报告格式、按受众风险级别执行审批工作流、执行 MCP 交付、验证交付、归档报告以供历史对比，并记录执行日志以追踪交付频率