Add Beryl Agent and harness source

2026-09-08 20:10:03 +08:00
parent 06d72d001c
commit 47cfbcd66a
70 changed files with 12558 additions and 0 deletions
@@ -0,0 +1,58 @@
+---
+name: swads-daily-report
+description: 通过已连接的 SW Ads MCP 为当前或指定广告账户生成只读日报，并最终交付为一张完整的 PNG 图片。用户提及账户日报、每日投放报告、日报图片或显式请求 $swads-daily-report 时使用。
+---
+
+# SW Ads 单图日报
+
+通过 `swads` MCP 查询数据并生成本地日报。全程只读；不得修改账户、Campaign、预算、ROI 目标、素材选择、商品锚点或投放状态。
+
+## 前置条件
+
+1. 确认 SW Ads MCP 工具可用。
+2. 调用 `swads_whoami` 核实身份、可见账户、报表时区和币种。
+3. 请求的账户不可见时立即停止，报告可访问的账户名称和 ID；不得用商品标题、品牌关键词或相似名称推断账户映射。
+
+## 报表范围
+
+- 使用 MCP 返回的账户报表时区。
+- 默认使用最近一个完整业务日；当日未完整数据只作监测信号。
+- 用户指定账户或日期时严格使用该范围。
+- 构造查询前先读取 `metrics_catalog`，不猜测指标或维度名。
+
+## 数据采集
+
+只收集日报所需的只读数据：
+
+- 账户总览：消耗、展示、点击、CTR、转化或订单、收入、ROI/ROAS、健康状态、新鲜度和同步警告。
+- Campaign 拆分：有足够消耗或转化证据的最强与最弱 Campaign。
+- 素材拆分：消耗、商品展示/点击、CTR、订单、收入、ROAS、创作者和可用的商品/Campaign 身份。
+- 可用的运营发现和归因证据。
+
+端点或归因数据不可用时，明确标注限制并继续使用受支持的平台事实，不得虚构。
+
+## 分析规则
+
+- TikTok Shop 的“商品曝光”不得直接采用账户汇总层返回的 `product_impressions`。必须查询同一日期、账户和归因口径下的完整素材明细，将所有视频素材行的 `product_impressions` 与所有 `product_card:*` 商品页行的 `product_impressions` 求和：`商品曝光 = 视频商品曝光合计 + 商品页曝光合计`。
+- “商品点击”使用同一批完整素材明细，按相同规则将所有视频素材行与 `product_card:*` 商品页行的 `product_clicks` 求和。订单也必须使用相同日期、账户和归因口径。
+- 求和前按素材身份去重；同一 `external_creative_id` 出现多行时，先按其最低可用唯一组合键聚合，避免把重复同步记录重复累计。查询结果被截断、分页未取全或无法区分视频与商品页时，漏斗显示 `N/A` 并说明，不得用部分行冒充全量。
+- 可能时从聚合后的分子和分母重算比率。
+- 缺少分母或分母为零时，CTR、CPI、CVR、单均成本、ROI/ROAS 显示为 `N/A`，不将缺失值解读为真实的零。
+- 区分平台原生归因和因果增量；归因只是证据或相关性，不是因果证明。
+- 区分低样本不确定性和已确认的表现不佳。
+- 恰好输出 3 条按优先级排序、有数据支持的优化建议。
+- 任何预算、状态、ROI 目标、素材固定/移除、发布或其他修改都放在“需人工确认”区域，不执行。
+
+## 单图交付
+
+- 必须最终生成且只向用户交付一张 `swads-daily-report.png`。
+- 必须调用 `save_report_image`，使用 `reportType: daily` 生成最终 PNG。
+- 图片必须包含“商品曝光 → 商品点击 → 订单”三阶段漏斗及各阶段转化率。商品曝光和商品点击均采用“全部视频 + 商品页”的完整素材明细汇总口径，并在漏斗说明中分别标出视频贡献、商品页贡献和合计。无法安全聚合时显示 `N/A` 并解释缺失原因，不得混用普通广告曝光与商品曝光。
+- PNG 必须是可独立阅读的完整长图，包含账户身份、报表日期、时区、币种、数据新鲜度、核心指标、Campaign/素材要点、风险、局限和恰好 3 条建议。
+- 视觉使用节制的 Wise 风格绿色系、强数字层级、紧凑表格和清晰警告状态。
+- 可在本地生成规范化 JSON 和自包含 HTML 作为中间文件，但最终回复不展示、不链接这些中间文件。
+- 如果当前环境无法渲染 PNG，不得伪称已生成图片；明确报告渲染能力缺失。
+
+## 最终回复
+
+以业务结果和主要风险开头，标注报表日期、时区、币种、数据新鲜度和不可用来源。只链接最终 PNG，并确认全流程只读。