sino-bc-cli 1.8.18 → 1.8.19

package/dist/skills/custom/biz-line-strategy-generate/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: biz-line-strategy-generate
+description: Use when 用户要为 BeyondClick 业务线生成投放策略（预算/广告产品/受众/素材四大策略及效果 learning）并导出 Excel。典型说法："帮我生成第一页的业务线策略"、"把前 10 个业务线生成策略"、"给名称为 xxx 的业务线生成策略"。不负责单条接口的原始查询（那些走 sino-bc-biz-line 域技能），本技能是编排多个 biz-line 接口 + 本地计算 + 导出文件的完整工作流。
+metadata:
+  requires:
+    bins:
+      - sino-bc-cli
+      - python3
+---
+
+# 业务线策略生成
+
+按业务线/项目维度自动生成「预算策略、广告产品策略、受众策略、素材策略」四大策略内容与效果 learning，最终导出为 Excel。这是一条编排流程（多次调用 `biz-line` 域接口 + 本地计算 + 落盘），不是单条 Shortcut。
+
+**开始前 MUST 先用 Read 工具读取 [`../sino-bc-shared/SKILL.md`](../sino-bc-shared/SKILL.md)**（配置、信封、确认门、禁止拼 HTTP）。查询业务线相关接口的字段口径见 [`../sino-bc-biz-line/SKILL.md`](../sino-bc-biz-line/SKILL.md)。
+
+## When to Use
+
+- 用户要求「生成业务线策略」「生成投放策略」，或提到「策略生成」「策略 learning」并希望产出文件
+- 常见变体：
+  - 「帮我生成第一页业务线的策略」→ 第 1 页，默认页大小
+  - 「把前 10 个业务线生成策略」→ 前 10 条
+  - 「给名称为 xxx 的业务线生成策略」→ 按名称筛选
+  - 「给业务线 A 生成策略，用广告账号 act_123（Facebook）」→ 用户指定账号覆盖接口返回的账号
+
+不要用本技能处理：单纯查询业务线列表/详情/项目（那是只读查询，直接走 `biz-line +list` / `+project-list` 等，不需要走完整生成流程）。
+
+## Agent 流程
+
+按顺序执行。**拉数和聚合不要手写**：用本目录 `scripts/fetch_data.py`、`scripts/summarize.py`。Windows 传参、信封解包、翻页见 [`references/runtime.md`](references/runtime.md)。字段口径见 [`references/api-flow.md`](references/api-flow.md)。
+
+1. **开请求目录**：`%TEMP%/sino-bc-strategy/<requestId>/`。维护 `excels_written`。
+2. **拉数（一条命令，不要自己循环调几十次 CLI）**：
+   ```bash
+   python3 scripts/fetch_data.py --request-dir <本次目录> --name "业务线名" \
+     --curr-start 2026-09-08 --curr-end 2026-09-10 \
+     --prev-start 2026-09-06 --prev-end 2026-09-08 \
+     --account-fb act_xxx --account-gg 123-456 --account-tt 789
+   ```
+   用户没给账号时脚本会先拉 `+list` / `+project-list`（失败则退回 `+detail.projectNames`），再按去重账号拉维度和成效。默认排序/条数仍按 [`api-flow.md`](references/api-flow.md)。多条业务线就按 ID 循环调用本脚本（`--id`），不要把多条混进一次请求目录。
+3. **汇总成文案草稿**：`python3 scripts/summarize.py --request-dir <本次目录>`，得到 `payload.json`。Agent **必须打开 payload 看一眼**：枚举是否已译成中文、词包有没有整包粘贴、learning 有没有把上百条低消耗广告逐条列出。硬伤改 payload 后再导，不要从原始 JSON 重写一套聚合。
+4. **导出 Excel**：`python3 scripts/build_report.py --input <本次目录>/payload.json`。固定 12 列，一个业务线一行；「本期/上期」紧跟业务线，两段日期写在同一单元格。把 `output_path` 记入 `excels_written`。
+5. **收尾**：中途重导过则 `cleanup.py --keep-excel <最终> --written-excel ...`；然后 `cleanup.py --request-dir <本次目录>`。只汇报最终那一份 Excel。
+
+learning 判定口径（双维度、关停、预算 Spend）见 [`references/metrics.md`](references/metrics.md)；策略内容写法见 [`references/four-strategies.md`](references/four-strategies.md)。用户指定了本期/上期日期就用用户的，允许两端日期重叠。
+
+时间范围（本期/上期）默认规则见 [`references/api-flow.md`](references/api-flow.md)「第 5 步」；用户明确给出本期、上期时间时改用用户指定值。
+
+## 常见误区
+
+- 不要把接口不支持的衍生指标（CTR/CPC/CPI/ROAS 等）直接传给 `indicators`，必须先查基础指标再本地计算。
+- `country_code` 只能单独传或与 `calendar_date` 同传，和其他维度混传会报错；维度接口和成效接口都支持它，国家的成效数据能取到。传它时服务端转跨渠道接口，`headerMap` 列名会变，不要写死列名。
+- 判 learning 时不要用「整体数据」评价新增项：除预算策略外，其他三大策略只看**新增值自身**的投放数据；也不要用「全维度达标才算达标」或「一个达标就算达标」，按消耗加权算达标占比。
+- **达标占比不等于结论**：达标占比只是双维度判定里的「是否达标」这一个轴，必须再配上环比变化查表才能定结论。漏掉环比轴会把「未达标但趋势向好」误判成无效。
+- 环比方向不能只看数值涨跌：CPI 从 15 降到 12 是**变好**（成本类下降为好），ROAS 下降才是变差。上期无数据时环比记「无法对比」，此时达标=有效、未达标=待观察。
+- 维度合计 / 策略合计的衍生指标必须**先把基础指标求和、再算比率**，不能对各枚举值的比率取平均（会踩辛普森悖论）。
+- 本期只有关停没有新增时，不要退化成「看现有总投放是否达标」，要走关停口径（关停后存量 vs 关停前整体），见 [`references/metrics.md`](references/metrics.md)。
+- 出价调整次数不能用区间聚合值推断：出价每天一个快照，必须带 `calendar_date` + `adgroup_id` + `adgroup_name` 按天拉明细，再相邻两天比对计数；粒度是**广告组**，不要下钻到 `ad_id`（会重复计数）。次数按广告组各自统计并在文案里点名广告组，调整前后值取本期首日值和末日值。
+- 分析单位是业务线：把该业务线下所有项目的广告账号**按账号 ID 去重**后合并分析，不要按项目分别调接口再拼结果（会重复计消耗、次数翻倍）。
+- Excel 不输出「项目PM」列：现阶段没有确认好的项目 PM 取数来源（`biz-line-project-list` 不返回 PM 字段），不要为了补这一列去猜或用业务线级 `pmUserNames` 顶替。
+- 组别名称直接用 `ssoTeamCodeName`，本期/上期周期直接用 `periodStart/periodEnd`、`prevPeriodStart/prevPeriodEnd`，都不用自己反查或按自然周推算。
+- 未绑定项目/广告账号的业务线不要强行生成策略或编造数据。
+- 一个业务线下有多个项目时，Excel 仍是**一个业务线一行**；多个项目名称写在同一单元格内用 `\n` 分隔，不要按项目拆成多行。
+- 写文件路径优先用户电脑桌面（`~/Desktop`），不要写进本仓库或临时目录，除非用户另有指定。
+- 导出脚本在本 `SKILL.md` 同级的 `scripts/build_report.py`，不要用仓库相对路径 `skills/biz-line-strategy-generate/...`。
+- 文案用 `display_*` 或业务中文（如「应用推广」「成本上限」「自定义出价」「应用内事件」），不要把 `OUTCOME_SALES`、`COST_CAP`、`BID_TYPE_CUSTOM`、`IN_APP_EVENT` 原样写进 Excel；关键词/兴趣是**一个词包一个维度值**，只写「新增/关停 N 个」加最多 3 个短词，禁止把逗号分隔的整包贴进单元格。
+- learning 第 1 层只写**过了消耗门槛**（≥$50）的新增值；其余写成「另有 N 个新增消耗不足 $50，不纳入聚合」，不要把 200 条 $0 广告逐条列进单元格。
+- 无新增且无关停时：所有占比都在 ±2% 内才是「无实质动作」；占比变了超过 ±2% 要按**可环比**走双维度，不要写成无实质动作。
+- 不要手写维度/成效翻页。CLI 信封里维度/成效的行在 `data.data`、总数在 `data.total`；列表才是 `data.result`。认错字段会把 1800 行当成 0 行、只拿第 1 页。
+- PowerShell 不要手写 `--data '{"id":1}'`（引号常被吃掉）；用 `scripts/fetch_data.py`，见 [`references/runtime.md`](references/runtime.md)。
+- 每个用户请求只保留**一份最终 Excel**。改文案请改 payload 后再导，并删掉本次 `excels_written` 里的上一份。禁止按桌面 `业务线策略生成_*.xlsx` glob 删除——会误删其他请求的文件。
+- 一条业务线的数据拉取和文案完成后，马上删它的原始回包临时文件；整次请求汇报完后删本次 `requestId` 目录。只删本次目录/本次清单，不要动别的 `requestId` 或桌面上非本次写出的 xlsx。
+
+## References
+
+- [`references/api-flow.md`](references/api-flow.md)：完整接口调用顺序、默认排序/分页/时间范围规则
+- [`references/four-strategies.md`](references/four-strategies.md)：四大策略的字段映射、支持渠道、生成内容示例
+- [`references/metrics.md`](references/metrics.md)：基础/衍生指标口径、核心指标识别、策略效果 learning 判定流程
+- [`references/output-excel.md`](references/output-excel.md)：Excel 输出列规范与 `scripts/build_report.py` 用法
+- [`references/runtime.md`](references/runtime.md)：信封解包、Windows 传参、本次请求目录、一次请求只留最终 Excel
+- `scripts/fetch_data.py` / `summarize.py` / `build_report.py` / `cleanup.py`：拉数、汇总草稿、导出、清理
+
+```bash
+# 脚本路径相对本 SKILL.md 所在目录。账号与业务线名只是文档示意，不要当真实请求。
+python3 scripts/fetch_data.py --request-dir "$TMPDIR/sino-bc-strategy/<requestId>" --name "示例业务线" \
+  --curr-start 2026-09-08 --curr-end 2026-09-10 --prev-start 2026-09-06 --prev-end 2026-09-08 \
+  --account-fb act_xxx --account-gg 123-456 --account-tt 789
+python3 scripts/summarize.py --request-dir "$TMPDIR/sino-bc-strategy/<requestId>"
+python3 scripts/build_report.py --input "$TMPDIR/sino-bc-strategy/<requestId>/payload.json"
+python3 scripts/cleanup.py --keep-excel <最终xlsx> --written-excel <本次xlsx...>
+python3 scripts/cleanup.py --request-dir "$TMPDIR/sino-bc-strategy/<requestId>"
+```

package/dist/skills/custom/biz-line-strategy-generate/references/api-flow.md

@@ -0,0 +1,102 @@
+# 接口调用流程
+
+字段口径以 `src/api-doc/oapi/biz-line-strategy.md`（安装后 `dist/api-doc/oapi/`）为准，本文件只写本 skill 场景下的调用顺序与默认参数。全部接口都走 `biz-line +<shortcut>` 或 `biz-line api <name> --data '<json>'`，不要自己拼 HTTP。`--data` 在 Windows / PowerShell 下的传法见 [`runtime.md`](runtime.md)。
+
+## 第 1 步：拉取业务线列表
+
+```bash
+sino-bc-cli biz-line api biz-line-list --data '{"pageNum":1,"pageSize":10,"sortType":"PERIOD","sortDirection":"DESC"}'
+```
+
+- **默认排序**：用户未指定时，按「本期策略周期倒序」，即 `sortType: "PERIOD"`、`sortDirection: "DESC"`。
+- **默认条数**：用户未指定时只取前 10 条，即 `pageSize: 10`；用户说「第一页」按平台默认页大小理解为 10 条（`pageNum:1, pageSize:10`）；用户说「前 N 个」则 `pageNum:1, pageSize:N`。
+- **按名称筛选**：用户点名业务线（如「名称为 xxx 的业务线」）改用 `name` 模糊匹配，此时不再套用「前 10 条」限制；`name` 命中多条时把候选列出来，不要擅自选一条。
+- **按 ID 筛选**：已知业务线 ID 时用 `idList`。
+- **本接口出参很全，后续多数字段不用再查别的接口**，直接取用：
+  - `id`、`name`：业务线 ID 与名称
+  - `ssoTeamCodeName`：**组别名称**，已直接返回，不需要再用 `ssoTeamCode` 去 `sso +group-list` 反查
+  - `periodStart` / `periodEnd`、`prevPeriodStart` / `prevPeriodEnd`：本期与上期策略周期（见下方「第 5 步」，优先用这些而不是自己推算自然周）
+  - `coreIndex`：业务线核心指标（自由文本，来源 `t_biz_line.core_index`，未配置时为 null）。注意与 `coreEffectIndex`（当期核心效果指标，策略回顾字段）**不是同一字段**，识别 KPI 时用 `coreIndex`
+  - `pmUserNames`：业务线级 PM 姓名列表（当前 Excel 不输出 PM 列，见下方说明）
+  - `projectIds`：关联项目 ID 列表，**本接口不含项目名称**，名称要走第 2 步
+  - `trafficLight` / `trafficLightDesc`、`spend` / `realSpend`、`weekSpendQoq` 等表现字段，可用于辅助 learning 判断
+
+## 第 2 步：拉取业务线关联项目与广告账号
+
+对第 1 步选中的每个业务线 ID 调用：
+
+```bash
+sino-bc-cli biz-line api biz-line-project-list --data '{"bizLineId": 1251}'
+```
+
+- 一个业务线可能关联多个项目，每个项目下又有多个广告账号（分渠道：Meta/Facebook、Google、TikTok 等）。
+- **判定是否可生成策略**：按文档 7.1 生成入口的逻辑——若该业务线未绑定项目、或项目下没有关联广告账号，则不允许自动生成，直接跳过并在汇报里说明「未绑定项目/广告账号」；不要对空账号硬凑数据。
+- **用户指定广告账号**：如果用户在本次请求中明确给了广告账号 ID 和所属渠道，直接用用户提供的账号（覆盖接口返回的账号），但仍需要业务线/项目名称等基础信息用于 Excel 输出，因此第 2 步仍要跑一次以取项目名称。
+- **`+project-list` 失败不要停**：测试环境曾经对该 path 返回 404。此时改走 `+detail` 的 `projectNames`（或 `+queryByPage`），项目名仍要写进 Excel；用户已指定账号时继续用用户账号拉数。`scripts/fetch_data.py` 已做这个回退。
+- 把该业务线下**所有项目**的项目名称都收集好，Excel 里要写进同一行的单元格（见 [`output-excel.md`](output-excel.md)）。
+
+> **项目 PM 暂不输出**：`biz-line-project-list` 只返回 `projectId` / `projectName` / `adAccounts`，不含 PM 字段；现阶段没有确认好的项目 PM 取数来源，Excel 里已去掉「项目PM」列，不要为了填这一列去猜或硬凑。（`biz-line-list` 的 `pmUserNames` 是**业务线级** PM，粒度不同，不能当项目 PM 用。）
+
+### 账号去重与分析口径
+
+**分析单位是业务线，不是项目。** 把该业务线下所有项目的广告账号汇总到一起，**按账号 ID 去重**后再按渠道分组分析：
+
+- 同一个广告账号可能挂在同一业务线的多个项目下，不去重会导致消耗被重复计算、占比失真、出价调整次数翻倍。
+- 去重后按渠道（Facebook / Google / TikTok）分桶，每个渠道的全部账号 ID 一次性放进 `dimensionValues.account_id` 数组里调用，而不是按项目分别调用再拼接结果。
+- 四大策略的所有占比、次数、新增/关停统计都在这个「业务线级去重账号集合」上计算，最终一个业务线得到一套策略内容与 learning。
+
+## 第 3 步：按渠道查广告策略维度数据
+
+判定可以生成后，把去重后的广告账号按渠道分组，分别调用对应渠道的维度接口。三渠道 name：
+
+| 渠道 | 维度接口 name | Shortcut |
+| --- | --- | --- |
+| Facebook（Meta） | `icenter-strategy-dimension-facebook` | `biz-line +facebook-dimension` |
+| Google | `icenter-strategy-dimension-google` | `biz-line +google-dimension` |
+| TikTok | `icenter-strategy-dimension-tiktok` | `biz-line +tiktok-dimension` |
+
+请求体核心字段（三渠道一致）：`startDate` / `endDate`（yyyy-MM-dd，两者必填）、`dimensionValues: {"account_id": ["<账号ID>", ...]}`（该账号所属渠道下的全部账号一次传入）、`dimensions`（分组维度数组，必填，按 [`four-strategies.md`](four-strategies.md) 对应策略维度选取需要的字段）。
+
+**国家维度特殊规则**：`country_code` 只能**单独传**，或与 `calendar_date` **两个一起传**；与其他任何维度同传会报错「[country_code]只能和[calendar_date]同时传入」。所以国家维度要单独发一次请求。
+
+- **维度接口与成效接口都支持 `country_code`**，国家维度的成效数据可以取到（用于 learning 判 KPI）。
+- 传了 `country_code` 维度时，`dimensionValues` 额外支持 `country_code` 过滤（传国家码数组），可直接只取本期新增的那几个国家；不传 `country_code` 维度时该过滤条件无效。
+- ⚠️ 传 `country_code` 时服务端转走跨渠道接口，`headerMap` 列名会变：`calendar_date` → 「日期」、`country_code` → 「国家/地区」。列名一律读 `headerMap` 实际返回值，不要写死。
+
+**出价维度特殊规则**：出价字段每天只有一个快照，要数「出价调整次数」必须在 `dimensions` 里同时带上 `calendar_date`、`adgroup_id`、`adgroup_name`，按天按**广告组**拉明细后在本地做相邻两天比对，不能指望接口直接给次数，也不要下钻到 `ad_id`（会把一次广告组出价变更重复计数）。算法与边界见 [`four-strategies.md`](four-strategies.md)「出价调整次数怎么算」。
+
+## 第 4 步：按渠道查广告成效数据
+
+同样按渠道分组调用成效接口：
+
+| 渠道 | 成效接口 name | Shortcut |
+| --- | --- | --- |
+| Facebook（Meta） | `icenter-strategy-metrics-facebook` | `biz-line +facebook-metrics` |
+| Google | `icenter-strategy-metrics-google` | `biz-line +google-metrics` |
+| TikTok | `icenter-strategy-metrics-tiktok` | `biz-line +tiktok-metrics` |
+
+请求体在维度接口基础上多了 `indicators`（成效指标数组，必填）。**接口只支持基础指标**（见 [`metrics.md`](metrics.md) 的基础/衍生指标口径），业务线核心指标若是衍生指标，要展开成其依赖的基础指标一并查出，在 Agent 侧计算衍生值，不要把衍生指标名传给接口（会被忽略或报错）。
+
+## 第 5 步：时间范围默认规则
+
+用户未指定本期/上期时间时，按文档默认逻辑：
+
+**优先直接用 `biz-line-list` 已返回的周期字段，不要自己按自然周推算**：该接口出参里已经带了 `periodStart` / `periodEnd`（最新策略周期起止）和 `prevPeriodStart` / `prevPeriodEnd`（上期策略周期起止），直接取用即可，这是平台的权威口径。
+
+- **本期**：出参 `periodStart` ~ `periodEnd`。
+- **上期**：出参 `prevPeriodStart` ~ `prevPeriodEnd`。
+- 仅当这些字段为空（业务线还没有任何策略周期）时，才退回按自然周推算：本期 = 当前自然周周一至周日；上期 = 本期周一的上一周周一至该周周日。
+- 两次调用（本期、上期）分别传各自的 `startDate` / `endDate`，本期与上期返回的数据在 Agent 侧做环比对比，不要在一次请求里跨两周合并查询。
+- 注意区分：`periodStart` 系列是**出参**（业务线当前周期）；`previewPeriodStart` 系列是策略新建/更新接口的**入参**字段名，两者不要混用。
+- 维度接口与成效接口的时间范围最多支持近 21 天，不要传超过 21 天的跨度。
+- 用户明确指定本期、上期起止日期时，直接使用用户指定值，跳过上述默认推算。
+
+## 分页与数据量
+
+维度/成效接口默认每页 10 条（`size`），建议显式传更大的 `size`（不超过 1000）覆盖账号下全部广告，按 `result.total` 判断是否需要翻页；广告量大时优先加大 `dimensions` 粒度或分批翻页，不要漏页导致漏算占比。
+
+## 汇总到 Excel 前的数据整理
+
+按业务线 -> 渠道 两层汇总策略文案与 learning（账号已在业务线层去重，不再按项目拆分），最终按 [`output-excel.md`](output-excel.md) 的列规范拼成行数组，**一个业务线一行**；该业务线下的多个项目名称写在同一单元格内，每个项目一行（用换行分隔）。
+
+一条业务线的行文案定稿后，删除该业务线本次拉取留下的原始 JSON 目录，再处理下一条。全部行就绪后只调用一次导出；请求结束时的清理见 [`runtime.md`](runtime.md)。

package/dist/skills/custom/biz-line-strategy-generate/references/four-strategies.md

@@ -0,0 +1,91 @@
+# 四大策略生成
+
+来源：飞书文档《优化工作台广告策略生成》7.3 四大策略生成 + 名词解释表 + 「策略涉及的数据维度+指标」维度 sheet。四大策略固定为：**预算策略、广告产品策略、受众策略、素材策略**，覆盖渠道优先 Meta、Google、TT（Twitter、ASA 部分维度也支持，见下表「支持渠道」列）。
+
+## 生成总则
+
+- 策略生成默认按周维度运行，对比本周（本期）与上周（上期）的广告结构配置、消耗占比和核心 KPI 表现。
+- 每个维度的生成内容需覆盖：**策略标签**（本周动作类型归纳，如预算调整/产品结构调整/受众新增/素材上新）、**策略内容**（自然语言描述变化）、**广告动作**（底层依据，如新增/关闭数量、出价变化）；效果 learning 见 [`metrics.md`](metrics.md)。
+- 输出文案用优化师能看懂的业务语言，不直接暴露底层字段名（如不要直接写 `targetingInterests`，写「兴趣词包」）。展示给用户时优先 `display_*`；若仍是枚举 code 要译成中文。除 `OUTCOME_*` / `COST_CAP` / `LOOKALIKE` / `BOARD` 外，常见还有：`BID_TYPE_CUSTOM`→自定义出价、`IN_APP_EVENT`→应用内事件、`INSTALL`→安装、`VIDEO_VIEWS`→视频播放、`ENGAGED_VIEW`→有效观看、`CORE`→核心受众。对照表在 `scripts/cli_json.py` 的 `ENUM_ZH`。
+- 关键词、兴趣词包在接口里常常是**一整包逗号分隔字符串 = 1 个维度值**。只写「新增/关停 N 个」再加最多 3 个短词（`scripts/cli_json.py` 的 `short_label`），禁止把整包几百个词贴进单元格。
+- 「设置类字段」（国家、年龄、性别、兴趣词包、关键词、广告组等）判断**新增/关闭/配置变化**，不强依赖消耗数据；「报告类字段」（Spend、广告目标、广告系列类型、成效目标、出价方式等）需结合成效数据计算**占比变化**。
+- 各维度对应的接口字段来自「维度接口」（`+facebook-dimension` / `+google-dimension` / `+tiktok-dimension`）的 `dimensions` 数组取值，账号级过滤用 `dimensionValues.account_id`。
+
+## 预算策略
+
+| 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
+| --- | --- | --- | --- |
+| 调整出价 | 出价字段是**每天一个快照**，按**广告组**粒度按天拉取后相邻两天对比来数调整次数，详见下方「出价调整次数怎么算」。Meta 用 `bid_amount`；Google 用 `cpc_bid_amount`/`cpm_bid_amount`/`cpv_bid_amount`（任一变化即算一次变化）；TikTok 用 `bid_amount`/`conversion_bid`/`deep_cpabid`（任一变化即算一次变化）。出价方式取 `bid_strategy` | 【调整出价】Meta 出价方式是 xxx，广告组 A 调整了 3 次，从 1.5 调整到 2.2；广告组 B 调整了 1 次，从 0.8 调整到 0.9；GG 本周未发生明显出价调整。 | Meta、Google |
+| Spend（预算） | 按渠道汇总 `spend_usd` 绝对值与占比，对比本周 vs 上周。占比变化在 ±2% 内视为「无变化」，否则输出「渠道：变化 x%」 | 【预算】换行后每渠道一行：`FB：50.0% → 55.0%（+5.0%）` | Meta、Google、TikTok、Twitter、ASA |
+
+### 出价调整次数怎么算
+
+出价字段在维度接口里**每天只有一个快照值**，接口不返回「调整了几次」这种聚合结果，必须自己按天比对推算。**对比粒度是广告组（adgroup），不是单个广告**：
+
+1. **按天 + 按广告组粒度拉数据**：`dimensions` 里必须同时包含 `calendar_date`、`adgroup_id`、`adgroup_name`（名称要写进文案，必须一起取），以及该渠道的出价字段。少了 `calendar_date` 就只能拿到区间聚合值，数不出次数；少了 `adgroup_id` 会把不同广告组的出价混成一行，得出的「变化」是伪变化。不要下钻到 `ad_id`，那会把同一个广告组的一次出价变更重复计成多次。
+2. **按广告组分组、按日期升序排列**：同一个 `adgroup_id` 的记录按 `calendar_date` 从早到晚排好。
+3. **相邻两天两两对比**：同一广告组第 N 天与第 N-1 天的出价值不同 → 该广告组计 1 次出价调整。多个出价字段的渠道（Google 的 CPC/CPM/CPV，TikTok 的 bid_amount/conversion_bid/deep_cpabid）中，**同一天内任一字段发生变化就整体算 1 次**，不要按字段分别累加成多次。
+4. **次数按广告组各自统计，不跨广告组相加**：文案里逐个广告组说明「广告组 X 调整了 N 次」，让读者知道是哪个广告组调了几次。同一渠道下有多个广告组发生调整时，逐个列出。
+5. **调整前后值取本期首末值**：前值 = 该广告组**本期第一天**的出价，后值 = **本期最后一天**的出价，写成「从 首日值 调整到 末日值」。不要把中间每一次的跳变都串起来罗列。
+6. **边界处理**：
+   - 某天缺快照（广告组当天未投放）→ 跳过该天，用其前后两个**有值**的相邻快照继续比对，不要把「无值」当成一次变化。首末值同理取区间内第一个/最后一个**有值**的快照。
+   - 广告组在区间内新建（第一天才出现）→ 首次出现不算调整，只作为比对起点。
+   - 全区间出价值恒定 → 0 次，该广告组不写进文案；整个渠道都没有调整时写「本周未发生明显出价调整」。
+7. **时间范围**：数本期次数就用本期起止日期拉本期每一天；上期同理单独拉一次。区间跨度受接口近 21 天限制。
+
+Facebook 维度接口请求示例（本期按天 + 按广告组拉出价）：
+
+```json
+{
+  "startDate": "2026-09-01",
+  "endDate": "2026-09-07",
+  "dimensionValues": { "account_id": ["act_123", "act_456"] },
+  "dimensions": ["calendar_date", "adgroup_id", "adgroup_name", "bid_amount", "bid_strategy"],
+  "orders": { "adgroup_id": "asc", "calendar_date": "asc" },
+  "page": 1,
+  "size": 1000
+}
+```
+
+按 `adgroup_id` 升序 + `calendar_date` 升序返回，可以直接顺序扫一遍完成相邻比对；注意用 `result.total` 确认是否需要翻页，漏页会少算调整次数。`dimensionValues.account_id` 传的是该业务线下**全部项目去重后**的同渠道账号（见 [`api-flow.md`](api-flow.md)「账号去重与分析口径」）。
+
+## 广告产品策略
+
+| 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
+| --- | --- | --- | --- |
+| 广告目标（`objective`） | 查本周、上周分媒体分广告目标的消耗占比 | 【广告目标】下一行按渠道：`Meta：认知 60.0% → 68.0%；销量 40.0% → 32.0%` | Meta、TikTok、Twitter |
+| 广告系列类型（`advertising_channel_type`） | 查本周、上周分广告系列类型的消耗占比 | 【广告系列类型】Google 预算更集中在 PMax 系列。详细：PMax 60%>>68%，搜索广告 40%>>32% | Google |
+| 成效目标 / 优化目标（`optimization_goal`） | 查本周、上周分成效目标的消耗占比 | 【成效目标】成效目标更聚焦在安装。详细：安装 45%>>60%，点击 55%>>40% | Meta、Google、TikTok |
+| 出价方式（`bid_strategy`） | 查本周、上周出价方式的消耗占比 | 【出价方式】整体更偏向系统自动优化。详细：（按占比列出各出价方式变化） | Meta、Google、TikTok |
+
+## 受众策略
+
+| 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
+| --- | --- | --- | --- |
+| 国家（`country_code`，须单独请求，只能与 `calendar_date` 同传） | 查投放设置上的国家，总结新增/关停。成效接口也支持该维度，可按国家取成效用于 learning | 【国家】新增 1 个国家：xxx；关停 1 个国家：xxxx，投放区域有小幅调整。 | Meta、Google、TikTok |
+| 兴趣词包（`targeting_interests` / `targeting_flexible_interests` / `targeting_exclusion_interests`） | 查投放设置上的兴趣词包，总结新增/关停 | 【兴趣词包】新增 2 个兴趣词包：短剧、线上娱乐；未发现关停，受众覆盖范围扩大。 | Meta、TikTok（Google 不支持） |
+| 受众类型（`audience_type`） | 查受众类型消耗数据（需加工），总结占比变化 | 【受众类型】无变化。详细：通用 50%>>55%，类似受众 40%>>35%，自定义受众 10%>>10% | Meta、Google、TikTok |
+| 关键词（`keywords`） | 查投放设置上的关键词，总结新增/关停 | 【关键词】新增 3 个关键词：xxxx，关停 1 个低效关键词：xxxx | Google（Meta、TikTok 不支持） |
+| 关键词分类（需在关键词基础上加工分类，无独立接口字段） | 查投放设置上的关键词并加工分类，总结新增/关停 | 【关键词分类】新增通用词 2 个：xxx、竞品词 1 个：xxx，品牌词无明显变化 | ASA |
+| 年龄（`targeting_age`） | 查投放设置上的年龄，总结新增/关停 | 【年龄】年龄定向无明显变化，仍以 18-44 岁人群为主。 | Meta、Google、TikTok |
+| 性别（`targeting_genders`） | 查投放设置上的性别，总结新增/关停 | 【性别】性别定向无明显变化，仍以女性人群为主。 | Meta、Google、TikTok |
+| 广告组（`adgroup_id` / `adgroup_name`） | 查广告组投放数据，总结新增/关停 | 【广告组】新增 4 个广告组：xxxx，关停 2 个低消耗广告组：xxxxx | Meta、Google、TikTok |
+
+## 素材策略
+
+| 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
+| --- | --- | --- | --- |
+| Ad / Ad name（`ad_id` / `ad_name`） | 查 Ad 的投放报告，总结本周 Ad 新增/关停情况，并根据 `ad_name` 提取关键词，得出图片/视频素材的消耗占比变化 | 【广告】Meta：新增 2 个广告，素材集中在「剧情反转」方向；关停 2 个，素材为「内测人群」方向。TT：新增 1 个广告，素材集中在「强冲突开头」方向。 | Meta、Google、TikTok |
+| 创意类型（`ad_format`） | 查创意类型（图片/视频等）的消耗占比变化 | 【创意类型】整体更偏向视频素材放量。图片 30%>>25%，视频 70%>>75%。 | Meta、Google、TikTok |
+
+## 三类调整对象的对比口径（判定策略是否发生变化时使用）
+
+| 类型 | 定义 | 对比方式 |
+| --- | --- | --- |
+| 可环比（如预算调整、媒体占比变化） | 上周有、本周也有 | 本周 vs 上周（同一对象） |
+| 新增（如新国家、新广告、新素材） | 本周新增，上周没有 | 本周新增部分 vs 本周整体 |
+| 关停（如下架广告、关停国家） | 上周有，本周已关停 | 关停后剩余存量整体表现 vs 关停前整体表现 |
+
+预算始终走「可环比」逻辑——看各媒体占比变化，以及各媒体总数据是否达标 KPI。
+
+其他三大策略生成 learning 时，KPI 只看**该维度本期新增值自身**的投放数据（如国家新增美国 → 只看美国的数据），不看业务线整体；一个策略下多维度按消耗加权聚合成一个结论。详见 [`metrics.md`](metrics.md)「第零步」与「一个策略下多个维度怎么聚合成一个结论」。

package/dist/skills/custom/biz-line-strategy-generate/references/metrics.md

@@ -0,0 +1,296 @@
+# 指标口径与策略效果生成
+
+来源：飞书文档 7.4 策略效果生成 + wiki《策略涉及的数据维度+指标》指标 sheet。
+
+## 基础指标 vs 衍生指标
+
+维度/成效接口（`+facebook-metrics` / `+google-metrics` / `+tiktok-metrics`）的 `indicators` **只支持以下 12 个基础指标**，一次查询按需传其中若干个：
+
+| API 字段 | 中文名 |
+| --- | --- |
+| `spend_usd` | 消耗金额（美元） |
+| `impressions` | 曝光量 |
+| `clicks` | 点击量 |
+| `video_views` | 视频观看次数 |
+| `add_to_cart` | 添加购物车次数 |
+| `checkouts` | 发起结账次数 |
+| `purchase` | 购买次数 |
+| `purchase_value` | 购买金额 |
+| `installs` | 应用安装量 |
+| `complete_registration` | 完成注册量 |
+| `leads` | 留下潜客信息次数 |
+| `engagement` | 互动次数 |
+
+**互动次数（`engagement`）及以下的指标都是衍生指标**，接口不支持直接查询，必须先查出对应的基础指标，再在 Agent 侧按下表公式计算：
+
+| 衍生指标 | 中文名 | 计算公式（基础指标） |
+| --- | --- | --- |
+| `ctr` | 点击率 | `clicks / impressions` |
+| `cpc` | 单次点击成本 | `spend_usd / clicks` |
+| `cpm` | 千次曝光成本 | `spend_usd / impressions * 1000` |
+| `cpi` | 单次下载成本 | `spend_usd / installs` |
+| `cpe` | 单次互动成本 | `spend_usd / engagement` |
+| `cpv` | 单次视频观看成本 | `spend_usd / video_views` |
+| `cpaPurchase` | 单次订单成本 | `spend_usd / purchase` |
+| `cpaAddsToCart` | 单次加入购物车成本 | `spend_usd / add_to_cart` |
+| `cpr` | 单次注册成本 | `spend_usd / complete_registration` |
+| `cpl` | 单次线索成本 | `spend_usd / leads` |
+| `cvrAddsToCart` | 加入购物车转化率 | `add_to_cart / clicks` |
+| `cvrPurchases` | 订单转化率 | `purchase / clicks` |
+| `cvrAppInstalls` | 安装转化率 | `installs / clicks` |
+| `vtr` | 视频观看率 | `video_views / impressions` |
+| `roas` | 投资回报率 | `purchase_value / spend_usd` |
+| `arpp` | 笔单价 | `purchase_value / purchase` |
+| `cvrRegistrationsCompleted` | 注册转化率 | `complete_registration / clicks` |
+
+计算前先确认分母对应的基础指标已经在同一次 `indicators` 请求中一起查出（同一 `dimensions` 粒度下），避免分子分母来自不同粒度导致口径不一致。分母为 0 时该指标记为「-」，不参与后续 KPI 判断。
+
+## 核心指标识别
+
+1. `biz-line-list`（或 `biz-line +detail`）出参里的 `coreIndex` 是自由文本（来源 `t_biz_line.core_index`，未配置时为 null），先尝试匹配到上述基础/衍生指标名称（中英文、别名均可，如「安装成本」→ `cpi`；文本里可能带阈值如 `ROI>1.2`，要把指标名和目标阈值分别解析出来，阈值即 KPI 达标线）。
+   ⚠️ 不要拿 `coreEffectIndex` 当核心指标：那是策略回顾里的「当期核心效果指标」，与业务线维度的 `coreIndex` 不是同一字段。
+2. 若 `coreIndex` 为空或无法识别，按投放行业给默认核心指标（ECBR → ROAS，APP/GAME → CPI；此为文档中的候选默认值，如与业务方最新口径冲突以业务方最新说明为准）。行业取值见 `biz-line +categories` 一级节点（1=APP，2=ECBR，3=游戏）。
+3. 核心指标若是衍生指标，必须展开到其依赖的基础指标（见上表公式），把这些基础指标一并加入本次 `indicators` 查询，不能只查核心指标名。
+4. 一个业务线可能有多个核心指标，逐个按下方判定流程生成 learning，多个结论在同一个策略 learning 里合并展示。
+
+## 策略效果判定流程（生成 learning）
+
+### 第零步：先分清「预算策略」和「其他三大策略」的取数口径
+
+两类策略的 KPI 评判对象完全不同，**先按这一步选对取数粒度，再往下走**：
+
+| 策略 | KPI 评判对象 | 取数方式 |
+| --- | --- | --- |
+| **预算策略** | **各媒体的总投放数据** | 按渠道汇总本期全量 `spend_usd` 与核心指标基础指标（`dimensions` 只需 `account_id`，不下钻到具体配置值），逐渠道判断该渠道整体是否达标 KPI，再看渠道间占比变化 |
+| **广告产品策略 / 受众策略 / 素材策略** | **该维度本期「新增值」自己的投放数据** | 按对应维度分组取成效（`dimensions` 带上该维度字段），只取本期新增出现的那些维度值，判断**这些新增值自身**是否达标 KPI，而不是看整体 |
+
+举例：受众策略里国家新增了美国，就只看**美国**这个新增值的投放数据是否达标 KPI，不看整个业务线整体；素材策略新增了 2 个广告，就只看这 2 个新增广告的数据。
+
+「新增值」的识别：用本期与上期的同维度取值集合做差集，本期有、上期没有的即新增值（判定方法同 [`four-strategies.md`](four-strategies.md) 各维度的新增/关停逻辑）。
+
+**国家维度现已可取成效**（接口已更新）：`country_code` 在维度接口和成效接口都支持，但只能**单独传**或**与 `calendar_date` 两个一起传**，与其他任何维度同传会报错「[country_code]只能和[calendar_date]同时传入」。所以国家维度要单独发一次成效请求：
+
+```json
+{
+  "startDate": "2026-09-01", "endDate": "2026-09-07",
+  "dimensionValues": { "account_id": ["act_123"], "country_code": ["US"] },
+  "dimensions": ["country_code"],
+  "indicators": ["spend_usd", "installs"],
+  "page": 1, "size": 1000
+}
+```
+
+- 传了 `country_code` 维度后，`dimensionValues` 额外支持 `country_code` 过滤，**直接把本期新增的国家码数组传进去**即可只取新增国家的数据，不必全量拉回本地再筛。
+- ⚠️ 传 `country_code` 时服务端转走跨渠道接口，`headerMap` 列名会变（`calendar_date` → 「日期」，`country_code` → 「国家/地区」）。展示列名一律读 `headerMap` 实际返回值，**不要写死**。
+- 12 个基础指标在跨渠道接口同样支持、照常返回聚合值。
+
+### 第一步：区分三类调整对象
+
+| 类型 | 定义 | 对比方式 |
+| --- | --- | --- |
+| 可环比 | 上周有、本周也有（如预算调整、媒体占比变化） | 本周 vs 上周（同一对象） |
+| 新增 | 本周新增，上周没有（如新国家、新广告、新素材） | 本周新增部分 vs 本周整体 |
+| 关停 | 上周有，本周已关停（如下架广告、关停国家） | 关停后剩余存量整体表现 vs 关停前整体表现 |
+
+预算策略始终走「可环比」逻辑（各媒体总数据 + 渠道占比变化）；其他三大策略以「新增」为主，新增值的 KPI 达标情况是判定主依据。
+
+### 第二步：判定结论（KPI 为主 + 环比为辅，双维度）
+
+**本表的作用范围**（重要）：
+
+- ✅ 四大策略各自的**总 learning 结论**（预算策略、广告产品策略、受众策略、素材策略，各查一次表）
+- ✅ 预算策略里 **Spend 子项的次级 learning 结论**（Spend 子项也要同时看达标与环比，单独查一次表）
+- ❌ 不作用于第 1 层（每个新增枚举值）和第 2 层（维度合计）——那两层只回答「是否达标 KPI」，作为分项证据
+
+| 是否达标 KPI | 环比变化 | 结论 | 说明 |
+| --- | --- | --- | --- |
+| ✅ 达标 | 变好或稳定 | 有效 | 达标且没变差 |
+| ✅ 达标 | 变差（>10%） | 待观察（预警） | 达标但下滑明显，再观察一周 |
+| ❌ 未达标 | 变好（>10%） | 待观察（潜力） | 未达标但趋势向好，再给一周机会 |
+| ❌ 未达标 | 稳定或变差 | 无效 | 未达标且没改善，需关停 |
+
+**两个轴分别怎么算**：
+
+| 轴 | 预算策略 Spend 子项 / 预算策略总结论 | 其他三大策略总结论 |
+| --- | --- | --- |
+| 是否达标 KPI | 全渠道加总后的核心指标 vs KPI 目标值 | 第 3 层消耗加权达标占比 ≥70% 即「达标」 |
+| 环比变化 | 全渠道加总核心指标：本期 vs 上期 | 业务线级核心指标：本期 vs 上期（同一口径下整体对比） |
+
+**环比变化的判定**：`变化幅度 = (本期值 - 上期值) / 上期值`，绝对值 ≤10% 记「稳定」，>10% 按方向记「变好」或「变差」。
+
+⚠️ **方向要按指标类型判断，不能只看数值涨跌**：
+- **成本类**（CPI、CPC、CPM、CPE、CPV、CPA、CPR、CPL、笔单价除外）→ **数值下降 = 变好**
+- **收益/转化类**（ROAS、CTR、VTR、各类转化率 CVR、ARPP）→ **数值上升 = 变好**
+
+例：CPI 从 15 降到 12，变化幅度 -20%，成本类指标下降 → 记「变好（>10%）」，不是变差。
+
+上期值缺失（业务线本期首次投放、上期无数据）→ 环比记「无法对比」，此时结论只按 KPI 达标定：达标 = 有效，未达标 = 待观察（给一周观察期，不直接判无效），并在文案里说明缺上期数据。
+
+### 各维度能否按值取成效（决定该维度能不能判 KPI）
+
+成效接口的 `dimensions` 枚举决定了哪些维度可以「按值取投放数据」。下表已按 spec 核对：
+
+| 维度字段 | Facebook | Google | TikTok | 说明 |
+| --- | --- | --- | --- | --- |
+| `optimization_goal` 成效目标 | ✅ | ✅ | ✅ | 广告产品策略 |
+| `bid_strategy` 出价方式 | ✅ | ✅ | ✅ | 广告产品策略 |
+| `objective` 广告目标 | ✅ | ❌ | ✅ | Google 不支持 |
+| `advertising_channel_type` 广告系列类型 | ❌ | ✅ | ❌ | 仅 Google |
+| `audience_type` 受众类型 | ✅ | ✅ | ✅ | 受众策略 |
+| `targeting_age` 年龄 | ✅ | ✅ | ✅ | 受众策略 |
+| `targeting_genders` 性别 | ✅ | ✅ | ✅ | 受众策略 |
+| `targeting_interests` 兴趣词包 | ✅ | ❌ | ✅ | Google 不支持 |
+| `keywords` 关键词 | ❌ | ✅ | ❌ | 仅 Google |
+| `adgroup_id` / `adgroup_name` 广告组 | ✅ | ✅ | ✅ | 受众策略 |
+| `ad_id` / `ad_name` 广告 | ✅ | ✅ | ✅ | 素材策略 |
+| `ad_format` 创意类型 | ✅ | ✅ | ✅ | 素材策略 |
+| `country_code` 国家 | ✅ | ✅ | ✅ | 受众策略；**须单独请求**（只能与 `calendar_date` 同传） |
+
+标 ❌ 的维度（当前渠道拿不到该维度成效）→ 该维度记「无法对比」，在 learning 里写明「无法对比：<维度> 该渠道不支持取数」，不参与达标聚合。
+
+### 三层聚合：枚举值 → 维度 → 大策略
+
+learning 要逐层给出结果，**三层都要落到文案里**（预算策略除外，它走下方「预算策略的特殊处理」）：
+
+**第 1 层 · 每个新增枚举值**：只写**过了评判门槛**的新增值（消耗 ≥$50 等），给出核心指标值与是否达标。
+例：国家维度新增了美国、越南 → 分别给「美国 CPI 6.4 达标（消耗 $2100）」「越南 CPI 12.1 未达标（消耗 $600）」。
+被门槛拦下的不要逐条罗列：写成「另有 N 个新增消耗不足 $50，不纳入聚合」。广告/广告组新增值经常上百条且大半 $0，把它们全写进单元格会毁可读性，也不改变聚合结果。
+
+**第 2 层 · 该维度所有新增枚举值合起来**：把该维度全部新增枚举值的基础指标**先求和再算核心指标**（不是对各枚举值的核心指标取平均），给出该维度整体的 KPI 值与是否达标。
+例：`该维度 CPI = Σ(各新增值 spend_usd) / Σ(各新增值 installs)`。
+⚠️ 衍生指标必须「先合并基础指标、再算比率」，直接平均比率会得出错误结论（辛普森悖论）。
+
+**第 3 层 · 大策略总结论**：走下方「第二步」的**双维度判定**（KPI 达标 + 环比变化）。其中「是否达标 KPI」这一轴用消耗加权得出：
+
+`达标占比 = Σ(达标维度的新增值消耗) / Σ(纳入聚合的全部维度新增值消耗)`
+
+达标占比 **≥ 70% 记为「达标」**，否则记为「未达标」。这个达标/未达标结果**不直接等于结论**，还要再和环比变化一起查双维度表才能定结论。
+
+只把**能取到成效、且通过评判门槛**的维度纳入聚合；「无法对比」和被门槛拦下的维度不投票，但要在文案里点名说明。
+
+**为什么达标轴用消耗加权**：「全维度达标才算达标」会让维度多的策略天然吃亏——受众策略有 7 个维度，一个小兴趣词包不达标就把整个策略判成无效，这是维度个数带来的偏差而不是真实信号；「一个达标就算达标」是镜像问题，一个亮点能洗白多个拖累项。消耗是天然权重：烧了 $5000 的新国家本就该比烧了 $80 的新兴趣词包更有话语权，且结论与维度个数无关。这也和「消耗不足 <$50 判待观察」的门槛口径一致。
+
+**第 1、2 层只给「是否达标」，不走双维度判定**：枚举值级和维度级只需回答「这个新增值/这个维度的新增值合计有没有达标 KPI」，作为文案里的分项证据；双维度判定（含环比）只在第 3 层策略级做一次。
+
+### 特殊情况：所有维度都没有新增，只有关停 / 减少
+
+此时没有「新增值」可评，**不要退化成「看业务线现有总投放是否达标」**——那衡量的是业务线大盘水平，跟本期这次「关停」动作没有因果关系，会把大盘本来就好/本来就差的情况错误归因到这次策略上。
+
+改用**关停动作自身的因果口径：存量对比**（与第一步「关停」类型的对比方式一致）：
+
+1. 取**关停后仍在投放的存量**（本期继续投放的那部分）的核心指标，记为 `KPI_after`。
+2. 取**关停前同一批存量 + 被关停对象**（即上期全量）的核心指标，记为 `KPI_before`。
+3. 判定：仍走「第二步」的双维度表，只是两个轴的取值换成关停口径 —— **达标轴** = `KPI_after` 是否达标 KPI 目标；**环比轴** = `KPI_after` 相对 `KPI_before` 的变化（方向同样按成本类/收益类判断）。对应结果：
+
+| 情况 | 结论 | 含义 |
+| --- | --- | --- |
+| `KPI_after` 达标 且 相对 `KPI_before` 变好或稳定 | 有效 | 砍掉低效部分后大盘变好，关停动作奏效 |
+| `KPI_after` 达标 但相对 `KPI_before` 变差 >10% | 待观察（预警） | 虽达标但砍完反而下滑，可能砍错了 |
+| `KPI_after` 未达标 但相对 `KPI_before` 变好 >10% | 待观察（潜力） | 方向对了但还没到线，再给一周 |
+| `KPI_after` 未达标 且 未改善 | 无效 | 关停没解决问题，需换策略 |
+
+4. 多个维度都只有关停时，同样按**各维度被关停对象的上期消耗**做消耗加权（消耗越大的关停动作影响越大），套用第 3 层的占比阈值。
+5. 「无实质动作」必须**同时**满足：无新增、无关停、**所有占比变化都在 ±2% 内**。无新增但占比变化超过 ±2%（例如成效目标从安装改成应用内事件）是**可环比结构调整**，用业务线核心指标走双维度表，不要写成「本期无实质调整动作」。
+
+文案要明确写出这是关停口径，例如：`无效。本期无新增，仅关停 2 个低效兴趣词包；关停后存量 CPI 13.2（未达标，KPI 目标 ≤10），关停前 13.0，未见改善。建议换策略。`
+
+4. 纳入聚合的维度为 0 个（全部无法对比 / 全被门槛拦下）→ 整个策略记「无法对比」，不要硬给结论。
+
+聚合结果要在 learning 里可追溯：三层都写进文案（见「第三步」输出格式）。
+
+### 预算策略的特殊处理（不走上面的三层聚合）
+
+预算策略下只有两个子项：**调整出价**和 **Spend**，各自的达标口径不同，且策略总结论只取 Spend。
+
+**子项一 · 调整出价**：只看**本期发生过出价调整的广告组**，没调过的广告组不纳入。
+
+1. 先按 [`four-strategies.md`](four-strategies.md)「出价调整次数怎么算」定出哪些广告组本期有出价变化。
+2. 逐个给出**每个有出价调整的广告组**的核心指标值与是否达标（对应第 1 层）。
+3. 汇总：把**所有有出价调整的广告组**的基础指标先求和、再算核心指标，得到调整出价子项的总 KPI 与达标结果（对应第 2 层，同样先合并基础指标再算比率）。
+4. 本期没有任何广告组调整过出价 → 该子项记「无实质动作 / 无法对比」，不影响 Spend 子项。
+
+**子项二 · Spend**：把**所有渠道的数据加在一起**算核心指标（不是逐渠道分别算再平均），得到业务线级的 KPI 与达标结果。
+
+Spend 子项的次级 learning 结论要走**双维度判定**（见「第二步」）：既看全渠道加总 KPI 是否达标，也看该 KPI 本期 vs 上期的环比变化，两个轴一起查表定「有效 / 待观察 / 无效」。文案里同时给各渠道的消耗占比变化（占比变化仍按 ±2% 判有无变化）。
+
+**预算策略总结论 = Spend 子项的双维度判定结果**（直接沿用，不再单独算一次）。调整出价的结论只作为文案里的分项说明呈现，不参与总结论计算。理由：出价调整是手段，预算分配的整体产出才是预算策略要负责的结果；且有出价调整的广告组可能只占一小部分消耗，让它左右总结论会失真。
+
+调整出价子项只给「是否达标」（逐广告组 + 合计），不走双维度判定。
+
+### 评判门槛（命中任一即判定「待观察」，不再往下判断有效/无效）
+
+门槛的判定对象跟着上面第零步的取数口径走：**预算策略**按各渠道总数据判；**其他三大策略**按该维度**新增值自身**的数据判（新增值消耗小是常态，门槛在这里会经常命中，属预期行为）。
+
+| 门槛 | 规则 | 原因 |
+| --- | --- | --- |
+| 消耗不足 | 本周消耗 < $50 | 数据量太小，指标不稳定 |
+| 天数不足 | 本周有效投放天数 < 3 天 | 投放未跑满一周，样本代表性不足 |
+| 转化不足 | 主 KPI 为转化类指标（CPI/CPA/ROI 等）且转化量 < 10 | 转化样本不够，统计显著性不足 |
+| 无实质动作 | 占比变化在 ±2% 以内，且无新增/关停 | 实际没有发生有效调整，不评价调整成效 |
+
+### 第三步：输出格式（结论 + 效果数据 + 建议）
+
+**预算策略**（调整出价 + Spend 两个子项，总结论取 Spend）：
+
+```
+结论：有效（取 Spend 子项）
+KPI：CPI≤7
+
+Spend
+· 全渠道 CPI：本期 6.5 / 上期 6.8，达标，环比稳定 -4.4% → 有效
+· 占比：FB 50.0% → 55.0%；TT 40.0% → 35.0%；GG 10.0% → 10.0%
+
+调整出价
+· 广告组A CPI 6.1 达标（$2400）
+· 广告组B CPI 7.4 未达标（$900）
+· 广告组C CPI 5.8 达标（$1500）
+· 合计 CPI 6.3，达标
+
+建议：继续执行
+```
+
+（上例中环比 -4.4% 未超 10%，记「稳定」；达标 + 稳定 → 有效。）
+
+**其他三大策略**（三层：每个新增枚举值 → 该维度合计 → 大策略加权）：
+
+```
+结论：待观察（潜力）
+依据：达标占比 52%（<70% → 未达标）；环比本期 CPI 7.6 / 上期 9.1，变好 -16.5%
+KPI：CPI≤7
+
+国家
+· 新增「美国」CPI 6.4 达标（$2100）
+· 新增「越南」CPI 12.1 未达标（$600）
+· 合计 CPI 7.3，未达标
+
+兴趣词包
+· 新增「短剧」CPI 12.3 未达标（$1900）
+· 新增「线上娱乐」CPI 6.2 达标（$2600）
+· 合计 CPI 8.1，未达标
+
+建议：再观察一周
+```
+
+```
+结论：无效
+口径：本期无新增，走关停
+KPI：CPI≤10
+
+关停后存量 CPI 13.2，未达标
+关停前 13.0，环比稳定 +1.5%
+
+建议：复核策略
+```
+
+要求：
+
+- 先给**策略级结论**（`结论：有效 / 待观察 / 无效 / 无法对比`），并写清双维度判定的两个输入：**达标占比（是否达标）** 与 **环比变化（幅度 + 变好/变差/稳定）**，让「为什么是这个结论」可复核。
+- 结论下面按维度分段，**三层都要有**：① 每个新增枚举值的指标值 + 是否达标 + 消耗（`·` 一行一条，最多 8 条）；② 该维度全部新增值合计的指标值 + 是否达标；③ 策略级达标占比与环比已在开头给出。
+- 维度合计与策略合计都必须**先合并基础指标再算比率**，不要对各枚举值的比率取平均。
+- 被门槛拦下、无新增、或该渠道不支持取数的维度也要点名说明原因（「本期无新增，跳过」「Google 渠道不支持该维度取数，无法对比」「消耗仅 $30，样本不足」），不能静默省略。
+- 走关停口径时要在文案里说明，并给出 `KPI_after` 与 `KPI_before` 的对比。
+- 全程带上 KPI 目标值，不要只写「达标 / 未达标」。
+
+## 与「策略内容」的关系
+
+策略内容（[`four-strategies.md`](four-strategies.md)）描述「做了什么变化」，策略 learning 描述「这个变化效果如何」。四大策略各自产出一条 learning，**四大策略之间不互相聚合**（预算策略的结论不影响受众策略的结论）；单个策略内部的多个维度按上文「消耗加权」聚合成该策略的结论。