meridian-scenario-planner

Meridian 场景规划器生成

此技能指导 Agent 生成场景规划器数据，将其序列化为 proto 文件以便交接给 Colab（无需进行 GCP 设置），并提供 Meridian Looker Studio 场景规划器 Colab 笔记本的链接。

前提条件

• Agent 必须能够访问已拟合的 Meridian 模型（序列化为 meridian_model.binpb）。

• 重要

  meridian_model.binpb 是一个二进制文件。切勿尝试使用文件查看工具或 grep 直接读取其内容，否则会导致无效的 UTF-8 错误。务必在 Python 脚本中使用 meridian_serde.load_meridian() 加载该文件。

核心工作流

交互检查点规则

在此工作流中，你会遇到关键交互检查点。在每个检查点，你必须：

1. 向用户展示当前建议的配置、路径或状态，以供审批。
2. 使用可用的用户交互工具（例如 ask_question），以多选题的形式询问用户是否准备好继续。切勿使用普通聊天文本。
3. 等待用户回复后再继续。
   • 强制要求：无论初始提示中的指示如何，在每个检查点都必须暂停（即使用户请求中包含“自主运行”“直接执行”“自主修复”等措辞）。初始请求不能绕过这些交互检查点。
   • 注意：如果用户在检查点以笼统的肯定答复（例如“继续”“按你认为最好的方式做”），则采用建议的默认值继续。

---

1. 初始设置

• 提示用户提供序列化模型文件的路径（默认为 meridian_model.binpb）。
• 提示用户提供输出 proto 路径（默认为： model_build/scenario_planner_data.binpb）。
• 提示用户提供生成的 Python 脚本所需路径。如果未指定，默认为 model_build/run_scenario_planner.py（或相对于模型目录的路径）。
• 关键交互检查点：向用户展示收集到的路径，并在配置规范参数前取得确认。

2. 配置场景规划器规范并进行交互检查

• 提示用户提供以下场景规划器规范配置（或确认默认值）：
  • optimization_name（String，例如 "Scenario Planner"）
  • include_non_paid_channels（Boolean，默认：True）
  • 时间粒度：yearly（默认：False）、quarterly（默认：True）、 monthly（默认：False）
  • min_spend_shift_ratio（Float，范围 0-1，默认：1.0）
  • max_spend_shift_ratio（Float > 0，默认：1.0）
  • use_optimal_frequency（Boolean，默认：True）
  • max_frequency（Float > 0，默认：10.0）
• 关键交互检查点：向用户展示建议的场景规划器规范配置，并在继续加载模型前取得批准。

3. 添加模型加载代码

• 使用 meridian_serde.load_meridian() 加载模型。
• 代码模板请参阅 script_template.md。
• 关键交互检查点：向用户展示模型加载路径配置和建议的 Python 代码片段，并在继续生成数据前取得批准。

4. 添加场景规划器数据生成和 Colab 交接代码

• 根据用户提供的配置，为 ModelFitSpec、MarketingAnalysisSpec 和 BudgetOptimizationSpec 创建规范。
• 使用 mmm_ui_gen.create_mmm_ui_data_proto() 创建 proto，其中包括 所请求的时间拆分生成器。
• 将 proto 序列化并保存到磁盘（例如： model_build/scenario_planner_data.binpb）。
• 指示用户将保存的文件上传到 Meridian 场景规划器 Colab 笔记本： https://colab.research.google.com/github/google/meridian/blob/main/demo/Meridian_Scenario_Planner_Beta.ipynb
• 代码模板请参阅 script_template.md。
• 关键交互检查点：向用户展示拟定的场景规划器规范配置和导出代码片段，并在继续前征得用户批准。

5. 执行前检查点

• 关键交互检查点：询问用户是否最终确认现在执行场景规划器生成脚本。

6. 执行和脚本设置

• 将累积的 Python 脚本写入用户指定的路径。如果你的文件写入工具可以让用户审核已写入的文件，请勿请求审核：执行前检查点已征求批准，额外提示会暂停工作流。
• 可参考 script_template.md 中的完整脚本模板。
• 使用安装了 google-meridian 的环境中的 Python 解释器执行脚本：优先使用用户指定的解释器；否则，如果虚拟环境已激活（设置了 VIRTUAL_ENV 或 CONDA_PREFIX），则使用 python3；否则，如果项目目录中存在虚拟环境（.venv/ 或 venv/，例如 .venv/bin/python3），则使用该环境；其他情况下使用 python3。如果 import meridian 失败，请询问用户应使用哪个环境，不要擅自搜索整台机器或安装软件包。
• 如果脚本在后台持续运行，请等待其完成，并在报告结果前检查最终输出。
• 重要：任务结束时不要删除生成的脚本、输出 proto 文件或交付物。这些是用户要求提供的交付物，必须保留。