sino-bc-cli 1.8.19 → 1.8.21

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

@@ -10,83 +10,73 @@ metadata:
 
 # 业务线策略生成
 
-按业务线/项目维度自动生成「预算策略、广告产品策略、受众策略、素材策略」四大策略内容与效果 learning，最终导出为 Excel。这是一条编排流程（多次调用 `biz-line` 域接口 + 本地计算 + 落盘），不是单条 Shortcut。
+本技能随 CLI 安装，需要 Python 3。复用现有 `biz-line` 接口，按固定分析规则和 Excel 模板生成四大策略与 learning，单次最多并发 3 条业务线。每条独立导出一份 Excel（`策略` + `明细` 两张表），校验成功后清理本次其他临时文件。执行入口与参数见下方「Agent 流程」。
 
-**开始前 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)。
+**开始前 MUST 先读 [`../sino-bc-shared/SKILL.md`](../sino-bc-shared/SKILL.md)**。字段口径见 [`../sino-bc-biz-line/SKILL.md`](../sino-bc-biz-line/SKILL.md)。
+
+口径来自 2026-09-17 策略优化沟通：主表只放总结，明细进第二张表；第二期结论跟环比，KPI 只作依据。
 
 ## When to Use
 
-- 用户要求「生成业务线策略」「生成投放策略」，或提到「策略生成」「策略 learning」并希望产出文件
-- 常见变体：
-  - 「帮我生成第一页业务线的策略」→ 第 1 页，默认页大小
-  - 「把前 10 个业务线生成策略」→ 前 10 条
-  - 「给名称为 xxx 的业务线生成策略」→ 按名称筛选
-  - 「给业务线 A 生成策略，用广告账号 act_123（Facebook）」→ 用户指定账号覆盖接口返回的账号
+- 「生成业务线策略 / 投放策略 / 策略 learning」并要产出文件
+- 「第一页 / 前 N 个 / 名称为 xxx」；用户指定账号则覆盖接口账号
 
-不要用本技能处理：单纯查询业务线列表/详情/项目（那是只读查询，直接走 `biz-line +list` / `+project-list` 等，不需要走完整生成流程）。
+不要用本技能处理：只查列表/详情/项目（走 `biz-line +list` 等）。
 
 ## Agent 流程
 
-按顺序执行。**拉数和聚合不要手写**：用本目录 `scripts/fetch_data.py`、`scripts/summarize.py`。Windows 传参、信封解包、翻页见 [`references/runtime.md`](references/runtime.md)。字段口径见 [`references/api-flow.md`](references/api-flow.md)。
+使用本技能目录的 **`scripts/run_workflow.py`**，不要临时重写拉数、分析或排版脚本。执行前定位技能的绝对路径；Python 只需标准库。首次使用读取 [`references/runtime.md`](references/runtime.md)。
+
+1. 用户给名称，传 `--name`；命中多个候选则返回歧义。用户给多个 ID，重复传 `--id`。用户要第一页/前 N 条，先用既有 `biz-line +list --data` 选出真实 ID，再在**一次入口调用**中传入。
+2. 入口默认最多 **3 条业务线并发**，允许 `--concurrency 1` 或 `2`，不能大于 3。同一批次不要并排启动多个入口绕开限制；单条内部 CLI 请求和分页串行。
+3. 每条自动执行现拉 → 固定分析 → 一次性排版 → Excel 回读校验 → 发布最终文件 → 清理。默认接口周期；用户给日期时成对传 `--curr-start/--curr-end`、`--prev-start/--prev-end`。
+4. 每条成功后立即交付**该业务线自己的最终 Excel**，并删除本次其他临时产物，包括 JSON、请求/回包、日志副本、图片、临时脚本、缓存、无扩展名文件及临时 Excel，不等全部业务线结束。
+5. 失败任务返回阶段和错误摘要，清理自己的临时文件，其他业务线继续。清理失败须报告残留路径，不能声称已清理。只给实际成功返回的 `output_path` 链接；不用已删除的请求目录作交付物。
+
+```bash
+python3 -B <本技能绝对路径>/scripts/run_workflow.py --name "用户指定的业务线名称"
+python3 -B <本技能绝对路径>/scripts/run_workflow.py --id <真实ID1> --id <真实ID2> --concurrency 3
+```
+
+`--output-dir` 指定最终目录，默认桌面。用户明确指定账号时使用可重复的 `--account-fb/--account-gg/--account-tt`；这些覆盖参数用于本次调用全部业务线，账号范围不同须分别请求并遵守并发上限。
 
-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。
+不要人工改 payload 再二次导出，或导入另一工作簿库重排。固定分析与 learning 规则见 [`references/metrics.md`](references/metrics.md)；策略写法见 [`references/four-strategies.md`](references/four-strategies.md)。
 
-learning 判定口径（双维度、关停、预算 Spend）见 [`references/metrics.md`](references/metrics.md)；策略内容写法见 [`references/four-strategies.md`](references/four-strategies.md)。用户指定了本期/上期日期就用用户的，允许两端日期重叠。
+## 主表 vs 明细
 
-时间范围（本期/上期）默认规则见 [`references/api-flow.md`](references/api-flow.md)「第 5 步」；用户明确给出本期、上期时间时改用用户指定值。
+| 位置 | 写什么 |
+| --- | --- |
+| `策略` sheet（12 列，一业务线一行） | 总结：预算金额+占比、出价升/降数量与中位数、命名规律、国家>50 时只写区域聚合 |
+| `明细` sheet | 国家全量、广告组名、出价逐条、兴趣词/关键词、广告名 |
+
+主表禁止堆全量广告组名或逐条出价。少于 10 条出价调整可以在主表列全，同时仍写入明细。
+
+## 结论规则
+
+- **首期**（没有 `prevPeriodStart/End`）：对客户 KPI；认不出或没填 → 待观察；展示当期全量兴趣词/关键词/国家，避免全 0。
+- **第二期起**：结论只跟核心指标环比（优先明确的可比核心指标；默认观察 CPI=美元消耗/平台安装量）。变好=有效，稳定=待观察，变差=待观察（预警）。KPI / 达标占比只写在「依据」，**不能**单独把结论打成无效。
+- 不要用脚本旧默认 `CPM≤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。
+- 衍生指标不要传给 `indicators`，先查基础指标再本地算。
+- `country_code` 只能单独传或与 `calendar_date` 同传；国家用**投放报告实际国家**，不用设置项。
+- 除预算外，三大策略看新增值自身数据；0%↔0% 残留枚举不当本期未出现。
+- 环比方向：成本类下降为好。维度合计先求和再算比率。
+- 出价按广告组 + `calendar_date` 相邻天比对；主表输出升/降数量、幅度分布/中位数，不要默认罗列。
+- 分析单位是业务线，账号按 ID 去重。Excel 不输出项目 PM。
+- 组别用 `ssoTeamCodeName`，周期用接口 period 字段。
+- 未绑定项目/账号不要编造。多项目仍一行，名称 `\n` 分隔。
+- 文案用中文/`display_*`；词包只写「新增/本期未出现 N 个」+ 最多 3 短词。
+- learning 第 1 层只写消耗 ≥$50 的新增。
+- CLI 回包必须直写文件（`exec_cli_to_file`），`capture_output` 会在约 64KB 截断。翻页上限用脚本 `PAGE_CAP`（≥80），不要手写 30 页就停。
+- 每条业务线只留一份最终 Excel；禁止按桌面 `业务线策略生成_*.xlsx` glob 删除。
 
 ## 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>"
-```
+- [`references/spec.md`](references/spec.md)：本技能的行为与验收规格，统一在技能目录内维护。
+- [`references/api-flow.md`](references/api-flow.md)
+- [`references/four-strategies.md`](references/four-strategies.md)
+- [`references/metrics.md`](references/metrics.md)
+- [`references/output-excel.md`](references/output-excel.md)
+- [`references/runtime.md`](references/runtime.md)

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

@@ -6,6 +6,7 @@
 
 ```bash
 sino-bc-cli biz-line api biz-line-list --data '{"pageNum":1,"pageSize":10,"sortType":"PERIOD","sortDirection":"DESC"}'
+# 按名称：同样走 --data（scripts/list_query_body），不要 +list --name
 ```
 
 - **默认排序**：用户未指定时，按「本期策略周期倒序」，即 `sortType: "PERIOD"`、`sortDirection: "DESC"`。
@@ -32,7 +33,7 @@ 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` 已做这个回退。
+- **`+project-list` 失败即中止该条**：返回错误并清理本次临时文件，不能把失败当成无关联项目或继续导出不完整报告。
 - 把该业务线下**所有项目**的项目名称都收集好，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 用。）
@@ -75,7 +76,7 @@ sino-bc-cli biz-line api biz-line-project-list --data '{"bizLineId": 1251}'
 | Google | `icenter-strategy-metrics-google` | `biz-line +google-metrics` |
 | TikTok | `icenter-strategy-metrics-tiktok` | `biz-line +tiktok-metrics` |
 
-请求体在维度接口基础上多了 `indicators`（成效指标数组，必填）。**接口只支持基础指标**（见 [`metrics.md`](metrics.md) 的基础/衍生指标口径），业务线核心指标若是衍生指标，要展开成其依赖的基础指标一并查出，在 Agent 侧计算衍生值，不要把衍生指标名传给接口（会被忽略或报错）。
+请求体在维度接口基础上多了 `indicators`（成效指标数组，必填）。**接口只支持基础指标**（见 [`metrics.md`](metrics.md) 的基础/衍生指标口径），业务线核心指标若是衍生指标，要展开成其依赖的基础指标一并查出，在固定汇总脚本中计算衍生值，不要把衍生指标名传给接口（会被忽略或报错）。
 
 ## 第 5 步：时间范围默认规则
 
@@ -85,7 +86,7 @@ sino-bc-cli biz-line api biz-line-project-list --data '{"bizLineId": 1251}'
 
 - **本期**：出参 `periodStart` ~ `periodEnd`。
 - **上期**：出参 `prevPeriodStart` ~ `prevPeriodEnd`。
-- 仅当这些字段为空（业务线还没有任何策略周期）时，才退回按自然周推算：本期 = 当前自然周周一至周日；上期 = 本期周一的上一周周一至该周周日。
+- 缺少本期周期时明确报错，请用户指定日期，不自行猜测自然周。上期日期为空按首期处理。
 - 两次调用（本期、上期）分别传各自的 `startDate` / `endDate`，本期与上期返回的数据在 Agent 侧做环比对比，不要在一次请求里跨两周合并查询。
 - 注意区分：`periodStart` 系列是**出参**（业务线当前周期）；`previewPeriodStart` 系列是策略新建/更新接口的**入参**字段名，两者不要混用。
 - 维度接口与成效接口的时间范围最多支持近 21 天，不要传超过 21 天的跨度。
@@ -93,10 +94,10 @@ sino-bc-cli biz-line api biz-line-project-list --data '{"bizLineId": 1251}'
 
 ## 分页与数据量
 
-维度/成效接口默认每页 10 条（`size`），建议显式传更大的 `size`（不超过 1000）覆盖账号下全部广告，按 `result.total` 判断是否需要翻页；广告量大时优先加大 `dimensions` 粒度或分批翻页，不要漏页导致漏算占比。
+维度/成效接口默认每页 10 条（`size`），脚本显式 `size=1000`，按 `data.total` 翻页，上限 `PAGE_CAP=80`（TikTok 出价按天可到 4～5 万行）。回包直写文件。每次现拉，不要跳过已有页；最终 Excel 校验发布后立即清理该条全部临时文件。
 
 ## 汇总到 Excel 前的数据整理
 
 按业务线 -> 渠道 两层汇总策略文案与 learning（账号已在业务线层去重，不再按项目拆分），最终按 [`output-excel.md`](output-excel.md) 的列规范拼成行数组，**一个业务线一行**；该业务线下的多个项目名称写在同一单元格内，每个项目一行（用换行分隔）。
 
-一条业务线的行文案定稿后，删除该业务线本次拉取留下的原始 JSON 目录，再处理下一条。全部行就绪后只调用一次导出；请求结束时的清理见 [`runtime.md`](runtime.md)。
+通过 `run_workflow.py` 一次提交本次真实 ID 列表，最多 3 条并发；每条独立拉数、分析、导出、校验与清理。最终 Excel 成功校验前不删除原始数据；成功或失败后的清理规则见 [`runtime.md`](runtime.md)。

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

@@ -5,18 +5,18 @@
 ## 生成总则
 
 - 策略生成默认按周维度运行，对比本周（本期）与上周（上期）的广告结构配置、消耗占比和核心 KPI 表现。
-- 每个维度的生成内容需覆盖：**策略标签**（本周动作类型归纳，如预算调整/产品结构调整/受众新增/素材上新）、**策略内容**（自然语言描述变化）、**广告动作**（底层依据，如新增/关闭数量、出价变化）；效果 learning 见 [`metrics.md`](metrics.md)。
+- 每个维度的生成内容需覆盖：**策略标签**（本周动作类型归纳，如预算调整/产品结构调整/受众新增/素材上新）、**策略内容**（自然语言描述变化）、**广告动作**（底层依据，如新增/本期未出现数量、出价变化）；效果 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、广告目标、广告系列类型、成效目标、出价方式等）需结合成效数据计算**占比变化**。
+- 关键词、兴趣词包在接口里常常是**一整包逗号分隔字符串 = 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 |
+| 调整出价 | 按广告组按天比对（见下）。主表只写**上调/下调广告组数量、幅度中位数**；条目 <10 才在主表列全。逐条进 `明细` sheet。 | 【调整出价】Meta：上调 3 个、下调 2 个；幅度中位数 0.40 | Meta、Google、TikTok |
+| Spend（预算） | 每个渠道必须同时写**金额绝对值 + 占比**（`budget_abs_share`）。占比升但金额降（或相反）要在主表标 ⚠️ | 【预算】`FB：$10,000 → $8,000（-2,000）；8.8% → 11.6%（+2.8%）；⚠️占比升但金额降` | Meta、Google、TikTok、Twitter、ASA |
 
 ### 出价调整次数怎么算
 
@@ -25,9 +25,11 @@
 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 次」，让读者知道是哪个广告组调了几次。同一渠道下有多个广告组发生调整时，逐个列出。
+4. **主表统计、明细列全**：主表用 `bid_adjust_stats` 写上调/下调数量与幅度中位数；<10 条才在主表列全。全部逐条写入 `payload.details`（kind=出价）。不要默认在主表点名几十个广告组。
 5. **调整前后值取本期首末值**：前值 = 该广告组**本期第一天**的出价，后值 = **本期最后一天**的出价，写成「从 首日值 调整到 末日值」。不要把中间每一次的跳变都串起来罗列。
 6. **边界处理**：
+   - 期内有变化但首末值相同单独计为首末持平，不归类为下调；多个出价字段完整进明细，主表方向基于代表字段。
+   - 广告、广告组按渠道 + ID 区分，全量明细保留 ID，同名不能合并。
    - 某天缺快照（广告组当天未投放）→ 跳过该天，用其前后两个**有值**的相邻快照继续比对，不要把「无值」当成一次变化。首末值同理取区间内第一个/最后一个**有值**的快照。
    - 广告组在区间内新建（第一天才出现）→ 首次出现不算调整，只作为比对起点。
    - 全区间出价值恒定 → 0 次，该广告组不写进文案；整个渠道都没有调整时写「本周未发生明显出价调整」。
@@ -47,7 +49,7 @@ Facebook 维度接口请求示例（本期按天 + 按广告组拉出价）：
 }
 ```
 
-按 `adgroup_id` 升序 + `calendar_date` 升序返回，可以直接顺序扫一遍完成相邻比对；注意用 `result.total` 确认是否需要翻页，漏页会少算调整次数。`dimensionValues.account_id` 传的是该业务线下**全部项目去重后**的同渠道账号（见 [`api-flow.md`](api-flow.md)「账号去重与分析口径」）。
+按 `adgroup_id` 升序 + `calendar_date` 升序返回，可以直接顺序扫一遍完成相邻比对；注意用 `data.total` 确认是否需要翻页，漏页会少算调整次数。`dimensionValues.account_id` 传的是该业务线下**全部项目去重后**的同渠道账号（见 [`api-flow.md`](api-flow.md)「账号去重与分析口径」）。
 
 ## 广告产品策略
 
@@ -62,20 +64,20 @@ Facebook 维度接口请求示例（本期按天 + 按广告组拉出价）：
 
 | 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
 | --- | --- | --- | --- |
-| 国家（`country_code`，须单独请求，只能与 `calendar_date` 同传） | 查投放设置上的国家，总结新增/关停。成效接口也支持该维度，可按国家取成效用于 learning | 【国家】新增 1 个国家：xxx；关停 1 个国家：xxxx，投放区域有小幅调整。 | Meta、Google、TikTok |
-| 兴趣词包（`targeting_interests` / `targeting_flexible_interests` / `targeting_exclusion_interests`） | 查投放设置上的兴趣词包，总结新增/关停 | 【兴趣词包】新增 2 个兴趣词包：短剧、线上娱乐；未发现关停，受众覆盖范围扩大。 | Meta、TikTok（Google 不支持） |
+| 国家（`country_code`，须单独请求，只能与 `calendar_date` 同传） | 用**投放报告实际国家**，不用设置项。主表写新增/本期未出现数量+示例；>50 个只写区域聚合，全量进明细。首期展示当期全量 | 【国家】新增 1 个：xxx | 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 |
+| 关键词（`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`） | 主表只写新增/本期未出现数量 + `naming_patterns` 命名规律；全量名称进明细 | 【广告组】Meta：新增 17 个，本期未出现 26 个；命名规律：KPOP、两性 | Meta、Google、TikTok |
 
 ## 素材策略
 
 | 字段 | 数据逻辑 | 生成内容示例 | 支持渠道 |
 | --- | --- | --- | --- |
-| Ad / Ad name（`ad_id` / `ad_name`） | 查 Ad 的投放报告，总结本周 Ad 新增/关停情况，并根据 `ad_name` 提取关键词，得出图片/视频素材的消耗占比变化 | 【广告】Meta：新增 2 个广告，素材集中在「剧情反转」方向；关停 2 个，素材为「内测人群」方向。TT：新增 1 个广告，素材集中在「强冲突开头」方向。 | Meta、Google、TikTok |
+| Ad / Ad name（`ad_id` / `ad_name`） | 主表写数量 + 命名规律（与广告组同一套 `naming_patterns`）；空名称不要写成方向「(空)」。全量进明细 | 【广告】Meta：新增 72 个，本期未出现 121 个；命名规律：旅行、两性 | Meta、Google、TikTok |
 | 创意类型（`ad_format`） | 查创意类型（图片/视频等）的消耗占比变化 | 【创意类型】整体更偏向视频素材放量。图片 30%>>25%，视频 70%>>75%。 | Meta、Google、TikTok |
 
 ## 三类调整对象的对比口径（判定策略是否发生变化时使用）
@@ -84,8 +86,8 @@ Facebook 维度接口请求示例（本期按天 + 按广告组拉出价）：
 | --- | --- | --- |
 | 可环比（如预算调整、媒体占比变化） | 上周有、本周也有 | 本周 vs 上周（同一对象） |
 | 新增（如新国家、新广告、新素材） | 本周新增，上周没有 | 本周新增部分 vs 本周整体 |
-| 关停（如下架广告、关停国家） | 上周有，本周已关停 | 关停后剩余存量整体表现 vs 关停前整体表现 |
+| 本期未出现（如下架广告、本期未出现国家） | 上周有，本周未出现（不代表已暂停） | 仅陈述集合差异与整体同期表现，不证明因果 |
 
 预算始终走「可环比」逻辑——看各媒体占比变化，以及各媒体总数据是否达标 KPI。
 
-其他三大策略生成 learning 时，KPI 只看**该维度本期新增值自身**的投放数据（如国家新增美国 → 只看美国的数据），不看业务线整体；一个策略下多维度按消耗加权聚合成一个结论。详见 [`metrics.md`](metrics.md)「第零步」与「一个策略下多个维度怎么聚合成一个结论」。
+其他三大策略的新增成效取该维度本期新增值自身数据，完整进明细。总体结论与分项依据分开，固定规则见 [`metrics.md`](metrics.md)，不以多个重叠维度的消耗加总或缺失 KPI 推断策略效果。