client-report

/digital-marketing-pro:client-report

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

用途

为特定品牌生成专业的白标客户报告。采用代理机构口吻（而非品牌口吻），包含 KPI 表现、渠道细分、策略建议和后续步骤。报告适用于通过 Slack、电子邮件、Google Sheets 或 Markdown 交付给外部客户；在向外发送前设置审批门槛，避免意外披露或过早发送尚未定稿的分析结果。

所需输入

用户必须提供以下信息（或将收到提示）：

• 品牌标识：此报告涵盖的品牌，必须与 ~/.claude-marketing/brands/ 中配置的品牌相匹配
• 报告类型：以下其中一种：
  • 每周简报：快速呈现 KPI 概览，包含 3-5 个关键指标和简短说明
  • 月度回顾：完整的绩效分析，包含渠道细分和建议
  • QBR：季度深度分析，包含策略路线图和后续计划
• 日期范围：报告期的具体开始日期和结束日期，决定提取和分析哪些数据
• 交付渠道：报告的发送渠道：slack、email、google-sheets 或仅 Markdown（不进行外部交付，只生成报告文件）
• 自定义章节（可选）：客户要求添加的任何章节，例如竞争情况更新、创意表现细分、受众洞察、归因深度分析或临时调查主题
• 比较周期：比较基准：上一周期、去年同期、计划/目标，或同时比较全部三项
• 收件人列表（可选）：若通过电子邮件或 Slack 交付，需提供应接收报告的具体客户联系人，以及其姓名和账号/地址
• 叙述重点（可选）：客户本周期最关注的方面：增长、效率、品牌认知度、潜在客户开发或收入；这会影响优先展示哪些指标以及如何呈现洞察
• 包含附录：是否附上原始数据表和广告系列级别的详细信息作为附录；月度回顾和 QBR 默认包含，周报默认不包含
• 白标设置（可选）：代理机构徽标位置、配色方案和免责声明文本；如果已配置，则从代理机构资料中提取，否则使用简洁的默认设置

流程

1. 加载品牌背景：读取 ~/.claude-marketing/brands/_active-brand.json 获取当前启用的品牌标识，然后加载 ~/.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. 获取品牌的所有指标：查询已连接的 MCP 服务，并运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/campaign-tracker.py" --brand {slug} --action list-campaigns（随后针对每个广告系列运行 --action get-campaign --id {id}），汇总所有活跃渠道的效果数据；分析时筛选指定日期范围内的数据。
3. 收集广告系列历史记录和执行日志：运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/execution-tracker.py" --brand {slug} --action get-history，汇总已完成的交付内容、已启动的广告系列、已进行的优化和已完成的测试，然后在分析时筛选报告周期内的数据。
4. 计算 KPI 与目标值及对比周期的差异：将实际数据与 profile.json 中注明的品牌 KPI 目标以及所选对比周期进行比较——计算差值、百分比变化、趋势方向，并在样本量允许时计算统计显著性。
5. 按渠道拆分效果表现：按渠道细分指标（付费搜索、付费社交、自然搜索、电子邮件、展示广告、视频、联盟营销等），列出各渠道的 KPI、支出、效率指标（CPC、CPA、ROAS、CTR）以及对总体目标的贡献比例。
6. 确定最佳成果及其归因：从该周期中选出表现最佳的 3–5 个广告系列或项目——记录采取了哪些措施、哪些因素促成了结果、受众与创意方面的洞察，以及这些成果与业务结果之间的关联。
7. 分析表现不佳的情况并查找根本原因：对于未达到目标的任何 KPI，找出根本原因：
   • 外部因素：市场变化、季节性、竞争对手动态、平台算法变化
   • 内部因素：预算限制、创意疲劳、受众饱和、时机不匹配
   • 纠正措施：已采取的措施，以及对下一周期的建议
8. 提出战略建议：根据效果数据，制定 3–5 条可执行的建议——哪些方面应扩大投入、哪些应暂停、下一步要测试什么、预算应如何调整，以及可以探索哪些新机会。
9. 采用代理机构语气撰写报告：使用专业的第三人称代理机构语气起草完整报告——不要采用品牌个性化语气。注重清晰度、以数据为依据的洞察、可执行的后续步骤，并保持自信但诚实的语调，以赢得客户信任。
10. 按交付渠道设置格式：运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/report-generator.py" --brand {slug} --action format-slack（或 format-email / format-sheets），通过 --data '{report_json}' 传入报告 JSON；若要生成简洁的 Markdown 文件，则使用 --action generate-report --data '{report_json}'。
11. 设置审批关卡：提交完整的报告预览供审核。风险等级：低。任何对外发送前都必须获得明确批准——标出可能需要提前向客户沟通的敏感数据、意外结果或负面发现。
12. 批准后通过 MCP 发送：若指定了交付渠道，则通过相应的 MCP 集成（Slack MCP、电子邮件 MCP、Google Sheets MCP）发送。发送出错时，仅在能够确定写入请求确实未到达平台的情况下重试（连接被拒、DNS 失败或收到 429 速率限制拒绝）；若发生超时或未收到响应，先在平台上查找记录（报告是否已出现在频道或收件箱中？），仅在报告不存在时重新发送。
13. 记录发送情况并归档：在执行日志中记录报告发送情况，包括时间戳、收件人、发送确认状态、报告版本，以及指向已归档报告的引用，以供后续比较。

输出

一份结构化的客户报告，包含：

• 执行摘要：用 3–5 句话概述本期情况——核心结果、关键成果、重点关注领域、下期展望，以及一项建议客户采取的行动
• KPI 记分卡：以便于浏览的表格对比实际值、目标值和对比期数据，并用颜色编码的状态指示（超出目标、按计划推进、有风险、未达目标）和趋势箭头展示变化方向
• 渠道表现细分：按渠道列出指标，包括支出、结果、效率指标（CPC、CPA、ROAS、CTR）、对整体目标的贡献比例，以及渠道健康状况评估
• 含归因分析的广告系列亮点：表现最佳的广告系列、成功驱动因素、创意和受众洞察、衡量到的影响，以及未来广告系列的复用建议
• 表现不佳分析：如实评估未达目标的情况，按根因分类（外部或内部），量化影响，说明已采取的纠正措施，以及下期的预防措施
• 战略建议（3–5 项）：有数据支持的后续步骤，包含预期影响、所需投入、实施时间表、优先级，以及与客户既定业务目标的关联
• 预算效率分析：按渠道汇总支出与回报、本期成本趋势线、预算使用率，以及与前期的效率对比，并标注提升或下降趋势
• 即将交付的成果和时间表：列出代理机构下期将交付的内容、日期、里程碑、依赖项，以及为确保计划顺利推进所需客户采取的行动
• 附录（如有要求）：原始数据表、广告系列级别的细分数据、完整指标导出、创意表现数据，以及供详细审查的计算依据
• 交付确认：渠道、时间戳、收件人、交付状态和报告版本；如果未要求外部交付，则提供 Markdown 文件

使用的 Agent

• agency-operations — 报告语气和风格（专业的代理机构口吻，而非品牌个性）、客户背景认知、审批工作流管理、白标格式设置和交付协调
• analytics-analyst — 指标分析、KPI 计算、渠道细分、趋势分析、对比计算、归因建模、统计显著性检查和建议的数据支持
• execution-coordinator — 面向交付渠道的报告格式设置、MCP 集成交付、执行日志记录、交付错误处理和归档