sino-bc-cli 1.8.19 → 1.8.21

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

@@ -1,296 +1,45 @@
-# 指标口径与策略效果生成
+# 固定分析与 learning 规则
 
-来源：飞书文档 7.4 策略效果生成 + wiki《策略涉及的数据维度+指标》指标 sheet。
+正常生成由 `summarize.py` 固定执行，Agent 不为单次业务线写修订脚本。未知或不支持的口径明确标注，不猜阈值、币种、汇率或转化定义。
 
-## 基础指标 vs 衍生指标
+## 基础指标与衍生指标
 
-维度/成效接口（`+facebook-metrics` / `+google-metrics` / `+tiktok-metrics`）的 `indicators` **只支持以下 12 个基础指标**，一次查询按需传其中若干个：
+接口请求基础字段 `spend_usd`、`impressions`、`clicks`、`installs`、`purchase`、`purchase_value`。不要把衍生指标名传进 `indicators`。
 
-| 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% 以内，且无新增/关停 | 实际没有发生有效调整，不评价调整成效 |
+| 安装 CPI（美元） | Σspend_usd / Σinstalls | 越低越好 |
+| CPC（美元） | Σspend_usd / Σclicks | 越低越好 |
+| CPM（美元） | Σspend_usd / Σimpressions × 1000 | 越低越好 |
+| ROAS | Σpurchase_value / Σspend_usd | 越高越好 |
+| CTR（%） | Σclicks / Σimpressions × 100 | 越高越好 |
 
-### 第三步：输出格式（结论 + 效果数据 + 建议）
+缺少必需字段、非数值或分母为零时记为不可计算；不补零、不平均各行比率、不混合账号粒度和日期粒度的分子分母。
 
-**预算策略**（调整出价 + Spend 两个子项，总结论取 Spend）：
+安装量不等于客户激活数，美元 CPI 不等于人民币 CPA。缺少同币种或留存数据时，客户 KPI 为「不可判定」。禁止旧的 `CPM≤5` 默认达标线。
 
-```
-结论：有效（取 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，未达标
+## 核心指标识别
 
-建议：再观察一周
-```
+读取 `coreIndex` 原文（不是 `coreEffectIndex`），完整保存到明细。固定解析器只判断定义明确的单一表达式，例如 `CPI USD <= 3`、`CPM <= 5美元`、`ROAS >= 1.2`、`CTR >= 2%`。
 
-```
-结论：无效
-口径：本期无新增，走关停
-KPI：CPI≤10
+组合条件、人民币 CPA、次日留存、未知指标或缺少币种的成本阈值，不强行解析为可判定 KPI。默认用美元安装 CPI 作观察指标，并说明无法对标客户 KPI 的原因，不使用 CPM 自动补位掩盖安装数据缺失。
 
-关停后存量 CPI 13.2，未达标
-关停前 13.0，环比稳定 +1.5%
+## 周期与总体结论
 
-建议：复核策略
-```
+- 首期由本次实际采用的上期起止日期是否齐全决定；有可判定 KPI 才按是否达标给出有效/待观察，否则待观察。
+- 第二期起按同口径核心指标环比；绝对变化 ≤10% 为稳定，成本下降/收益上升为变好。变好=有效，稳定=待观察，变差=待观察（预警）。缺上期值或分母为零=无法对比，结论待观察。
+- 本期消耗不足 $50、有效投放不足 3 天，或安装 CPI 的安装量不足 10，结论保持待观察。
+- 同时展示请求周期和各渠道实际返回日期；六天对七天等覆盖差异要提示，不能把短周期消耗下降直接说成主动减预算。
+- 总体环比只是同期观察，不能证明新增国家、广告或某次调价的因果效果。
 
-要求：
+## 四大策略的依据
 
-- 先给**策略级结论**（`结论：有效 / 待观察 / 无效 / 无法对比`），并写清双维度判定的两个输入：**达标占比（是否达标）** 与 **环比变化（幅度 + 变好/变差/稳定）**，让「为什么是这个结论」可复核。
-- 结论下面按维度分段，**三层都要有**：① 每个新增枚举值的指标值 + 是否达标 + 消耗（`·` 一行一条，最多 8 条）；② 该维度全部新增值合计的指标值 + 是否达标；③ 策略级达标占比与环比已在开头给出。
-- 维度合计与策略合计都必须**先合并基础指标再算比率**，不要对各枚举值的比率取平均。
-- 被门槛拦下、无新增、或该渠道不支持取数的维度也要点名说明原因（「本期无新增，跳过」「Google 渠道不支持该维度取数，无法对比」「消耗仅 $30，样本不足」），不能静默省略。
-- 走关停口径时要在文案里说明，并给出 `KPI_after` 与 `KPI_before` 的对比。
-- 全程带上 KPI 目标值，不要只写「达标 / 未达标」。
+预算取同粒度全渠道基础数据合计，展示每渠道金额、占比与出价变动。其他三大策略以新增值自身数据为分项依据；按渠道 + ID（对象维度）或渠道 + 维度值识别新增，避免同名对象混淆。
 
-## 与「策略内容」的关系
+1. 新增值消耗 ≥$50 才逐条写成效，低消耗只汇总数量。
+2. 每个维度的过门槛新增基础数据先合计再算指标。明细完整保存每个新增对象的 ID、名称、渠道、消耗及指标。
+3. 各维度可能覆盖同一投放，不能相加当成不重复的业务线消耗。客户 KPI 不可判定时，不生成达标/未达标或伪造达标占比。
+4. 无新增时说明无新增；本期集合缺失仅代表「本期未出现」，不证明已暂停，不使用所谓关停因果结论。
+5. 0% 到 0% 的残留枚举不作为调整依据。主表摘要最多列 8 个新增，完整细节进明细，超长内容分续行而非丢弃。
 
-策略内容（[`four-strategies.md`](four-strategies.md)）描述「做了什么变化」，策略 learning 描述「这个变化效果如何」。四大策略各自产出一条 learning，**四大策略之间不互相聚合**（预算策略的结论不影响受众策略的结论）；单个策略内部的多个维度按上文「消耗加权」聚合成该策略的结论。
+四大策略输出结论、依据和建议。第二期总结论采用总体可比指标，分项仍单独展示新增部分，明确二者的观察范围。

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

@@ -1,6 +1,6 @@
 # 输出 Excel
 
-生成结果的落盘环节，用本 skill 附带脚本 `scripts/build_report.py`（纯 Python 标准库，无第三方依赖，不需要 `pip install`）。脚本只做「结构化数据 → `.xlsx`」的机械转换，不做任何数据拉取或文案生成——那些在此之前由 Agent 按 [`api-flow.md`](api-flow.md)、[`four-strategies.md`](four-strategies.md)、[`metrics.md`](metrics.md) 完成。
+`scripts/build_report.py` 只做「结构化数据 → `.xlsx`」。一份文件两张表：**`策略`**（摘要，对应会议主页面）和 **`明细`**（对应二级页）。
 
 ## 输出列（固定 12 列，顺序不可改）
 
@@ -8,7 +8,7 @@
 | --- | --- |
 | 组别 | `biz-line-list` 出参 `ssoTeamCodeName`（组别名称，已直接返回，**不需要**再用 `ssoTeamCode` 去 `sso +group-list` 反查） |
 | 业务线 | `biz-line-list` 出参 `name` |
-| 本期/上期 | 本次请求实际使用的时间范围，**写在同一单元格内两行**：`本期：yyyy-MM-dd～yyyy-MM-dd` + 换行 + `上期：yyyy-MM-dd～yyyy-MM-dd`。用户指定了就用用户的，否则用 `periodStart/periodEnd` 与 `prevPeriodStart/prevPeriodEnd` |
+| 本期/上期 | 本次请求实际使用的时间范围，**写在同一单元格内，并附实际覆盖范围**：`本期：yyyy-MM-dd～yyyy-MM-dd` + 换行 + `上期：yyyy-MM-dd～yyyy-MM-dd`。用户指定了就用用户的，否则用 `periodStart/periodEnd` 与 `prevPeriodStart/prevPeriodEnd` |
 | 项目名称 | `biz-line-project-list` 出参 `result[].projectName`；一个业务线的多个项目**写在同一单元格内，一个项目一行**（用 `\n` 分隔） |
 | 预算策略内容 / 预算策略learning | 见 [`four-strategies.md`](four-strategies.md) 预算策略 与 [`metrics.md`](metrics.md) learning 生成规则 |
 | 广告产品策略内容 / 广告产品策略learning | 同上，广告产品策略 |
@@ -27,60 +27,16 @@
 - learning：先 `结论` / `依据` / `KPI`，再按维度用 `·` 列明细（最多 8 条，其余写「另有 N 个」），最后一行 `建议`。
 - 不要再用 `{...}` 把明细包成一段，也不要用分号把几十条广告串在同一行。
 
-## 调用方式
+## 固定导出流程
 
-先用 `scripts/summarize.py --request-dir <本次目录>` 写出 `payload.json` 草稿，Agent 复核文案后再调导出脚本。不要从原始回包手拼 12 列。
+业务生成调用 `scripts/run_workflow.py`，每条业务线单独生成一份 Excel；不先汇总全部业务线再导一份。`build_report.py` 是内部标准库导出器，正常流程不由 Agent 手改 payload 或另用第三方库二次排版。
 
-脚本在本技能目录的 `scripts/build_report.py`（与 `SKILL.md` 同级）。先定位本技能目录再执行，不要用仓库相对路径：
+主表 12 列不变，明细固定为：业务线、明细类型、动作、渠道、名称、补充。明细保留完整国家、同名不同 ID 广告/广告组、出价字段、新增成效、KPI 原文及数据周期覆盖。最终布局统一列宽、表头、冻结首行、筛选、换行及行高；主表过长内容转入「完整说明」明细，明细过长按续行完整保存，禁止静默截断。
 
-```bash
-python3 scripts/summarize.py --request-dir <本次 requestId 目录>
-python3 scripts/build_report.py --input <本次目录>/payload.json
-```
+## 输出与校验
 
-payload 结构：
+先在本条临时目录生成一次最终样式，通过 ZIP、两张表、列名及逐单元格完整性校验后，以独占创建方式发布；再次回读验证成功才交付。最终目录必须在批次临时根外。
 
-```json
-{
-  "output_path": "可选，未传时默认写到用户桌面 业务线策略生成_YYYYMMDD_HHMMSS.xlsx",
-  "rows": [
-    {
-      "group": "华东组",
-      "bizLine": "示例业务线",
-      "period": "本期：2026-09-08～2026-09-10\n上期：2026-09-06～2026-09-08",
-      "project": "项目A\n项目B\n项目C",
-      "budgetStrategy": "...",
-      "budgetLearning": "...",
-      "productStrategy": "...",
-      "productLearning": "...",
-      "audienceStrategy": "...",
-      "audienceLearning": "...",
-      "creativeStrategy": "...",
-      "creativeLearning": "..."
-    }
-  ]
-}
-```
+默认最终目录为桌面 `~/Desktop`，不存在时回退用户主目录，可用 `--output-dir` 指定。文件名为 `业务线策略_<ID>_<名称>_<随机标识>.xlsx`，同名目标拒绝覆盖。
 
-也支持 stdin：`python3 scripts/build_report.py --input -`（把 JSON 从 stdin 喂入）。
-
-## 默认输出位置
-
-用户未指定路径时，默认写到当前用户桌面（`~/Desktop`，找不到则退回主目录），文件名 `业务线策略生成_YYYYMMDD_HHMMSS.xlsx`，避免覆盖**其他请求**已经落盘的文件。用户明确要求其他路径 / 文件名时，通过 `--output` 或 payload 的 `output_path` 指定。
-
-## 一次请求只留最终文件
-
-时间戳文件名是为了不覆盖**别的请求**，不是让同一次请求导很多份。同一次用户请求：
-
-1. payload 全部行定稿后再调用脚本，默认只成功写一次。
-2. 把 stdout 里的 `output_path` 记进本次 `excels_written`。
-3. 若必须重导：新文件成功后再删清单里的旧路径，可用 `scripts/cleanup.py --keep-excel <最终> --written-excel <旧1> --written-excel <旧2>`。
-4. **不要**用桌面 glob（`*策略生成*.xlsx`）再「只留最新」；未出现在本次 `excels_written` 里的文件一律当别人的，不准删。
-
-汇报给用户时只给最终路径。临时 JSON 的清理见 [`runtime.md`](runtime.md)。
-
-## 返回值与校验
-
-脚本成功时输出 `{"ok": true, "output_path": "...", "row_count": N}`；失败（如 `rows` 为空）输出 `{"ok": false, "error": "..."}` 并以非 0 退出。Agent 应读取 `output_path` 回报给用户，不要凭假设的路径汇报。
-
-生成后不做自动打开或回读校验（脚本没有 Excel 运行环境可用），Agent 汇报时按 `row_count` 与实际处理的业务线/项目数核对是否一致，不一致要说明原因（如某业务线被 7.1 判定为不可生成而跳过）。
+每条业务线完成后只保留验证成功的最终文件，其他本次临时产物全部清理。汇报 `output_path` 及错误/残留（如有）；不附带已经删除的 request 目录。完整生命周期见 [`runtime.md`](runtime.md)。

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

@@ -1,72 +1,37 @@
-# 运行时约定（临时文件 / Excel 落盘 / Windows 传参）
+# 执行、并发与清理
 
-接口字段与策略文案规则仍以 [`api-flow.md`](api-flow.md)、[`four-strategies.md`](four-strategies.md)、[`output-excel.md`](output-excel.md) 为准。本文件只约定调用方式、本次请求目录和清理范围。
+业务流程统一使用 `scripts/run_workflow.py`，低层 fetch/summarize/build 脚本仅供维护诊断，不作为日常生成入口。
 
-## 调用 CLI
+## 并发与调用
 
-- 输出用 `--format json`，**不要**传 `--json`（会 `validation`：未知参数）。
-- `--data` 必须是合法 JSON 对象字符串。PowerShell 把 JSON 写进命令行时经常把引号吃掉，变成非法 JSON。
-- **推荐直接跑 `scripts/fetch_data.py`**（内部用参数数组调 CLI，`shell=False`）。不要在 PowerShell 里手写 `--data '{"id":1}'`，也不要为了躲引号去写死本机 `dist/index.js` 路径。
-- 成功看信封 `ok == true` 或退出码 0。
-- 回包必须写 UTF-8 文件再解析。合并文件是 JSON **数组**（以 `[` 开头），`json.loads` 要从第一个 `[` 或 `{` 里更靠前的那个开始，不能先 `find("{")`——否则会把第一行对象当全文，解析失败后当成空数据。
+- 默认同时处理至多 3 条业务线，可显式设置 1 或 2。单条从查询到清理占一个名额，清理结束即补位。同一批次不能拆成多个入口绕过上限；不做跨会话全局调度。
+- 单条内部接口、渠道和分页串行；只通过已安装 `sino-bc-cli`，不手写 HTTP。
+- Windows 通过已安装 CLI 对应 Node 入口传参数数组，避免 cmd 重新解释 JSON。权限错误应报告，不当成未安装去自动下载。
+- `--format json`，请求用 `--data`。成功必须同时满足退出码 0 和信封 `ok == true`；stderr 与 stdout 都直写本次文件。
+- 列表行为 `data.result`，项目为 `data` 数组，维度/成效为 `data.data` 和 `data.total`。分页 `size=1000`、`PAGE_CAP=80`；总数未取全、提前空页、失败或总数变化均中止该条，不导出部分成功文件。
 
-### 信封里行数据在哪（认错会漏页）
-
-| 接口 | CLI 信封 `data` | 行数组 | 总数 |
-| --- | --- | --- | --- |
-| `+list` | 对象 | `data.result` | `data.total` |
-| `+detail` | 业务线对象本身 | — | — |
-| `+project-list` | **数组**（或对象里的 `result`） | `data` 或 `data.result` | `len` |
-| 维度 / 成效 | 对象 | **`data.data`** | **`data.total`** |
-
-维度/成效**不要**读 `data.result`。上一轮调试里认错字段会把 `got=0` 当成空页，1800+ 行广告只留下第 1 页。翻页：`page`/`size`（`size`≤1000），`acc < total` 就继续。`scripts/cli_json.py` 的 `unwrap_page` 已按上表处理。
-
-## 本次请求的工作目录
-
-每次用户请求开始时新建**唯一**目录，后续原始回包、payload 都只写这里，禁止写仓库、禁止和其他请求共用一个扁平目录：
+## 目录归属
 
 ```text
-%TEMP%/sino-bc-strategy/<requestId>/
-  bl-<bizLineId>/     ← 该业务线维度/成效原始 JSON
-  payload.json        ← 全部业务线行拼好后再写
+%TEMP%/sino-bc-strategy/batch-<随机标识>/
+  .strategy-owner.json
+  line-<业务线ID>-<随机标识>/
+    .strategy-owner.json
+    请求体、回包、stderr、merged JSON、payload、summary、临时 Excel
 ```
 
-`requestId` 用本次开始时刻，如 `20260910_174600`。心里维护两份清单（可写在该目录的 `manifest.json`）：
-
-- `temp_dirs`：已创建的 `bl-<id>/` 路径
-- `excels_written`：本次请求里 `build_report.py` 成功返回的每一个 `output_path`（按时间追加）
-
-## 按业务线清理临时文件
+每次现拉，新建目录，不复用历史缓存。所有本次临时文件写入本次目录；不向技能源码树写缓存。最终 Excel 写在批次临时根以外，文件名包含业务线 ID 和随机请求标识，独占创建、不覆盖已有文件。
 
-对**一条**业务线：接口全部拉完 → 四大策略文案和 learning 已写入内存/payload 行 → **立即删除**该业务线的 `bl-<bizLineId>/`（含 `.body.json` / `.out.json` 等原始回包）。
+## 逐条清理
 
-不要在文案还没生成时删原始数据。跳过（未绑定项目/账号）的业务线若没有建目录，则不用删。
+成功路径：最终文件发布并回读验证 → 清理该业务线临时目录 → 输出完成结果。失败路径：保存可返回的错误摘要 → 关闭子进程 → 清理该业务线临时目录。所有任务停止后清理本次批次共享目录。
 
-## 整次请求结束时清理
-
-Excel 成功落盘、已向用户汇报最终路径之后：
-
-1. 按下面规则处理 Excel（只动本次清单）。
-2. 删除整个 `%TEMP%/sino-bc-strategy/<requestId>/`（含 `payload.json`、`manifest.json`、残留子目录）。
-3. 不要删 `%TEMP%/sino-bc-strategy/` 下**其他** `requestId` 目录。
-
-中途失败也要尽量删掉本次 `requestId` 目录，避免和下次请求的缓存混在一起。
-
-可用本技能脚本：
-
-```bash
-python3 scripts/cleanup.py --request-dir <本次 requestId 目录>
-python3 scripts/cleanup.py --keep-excel <最终xlsx> --written-excel <本次写过的xlsx1> --written-excel <xlsx2>
-```
+清理不限扩展名，包括 JSON、TXT、图片、日志副本、临时 Python、检查文件、缓存和所有临时 Excel；仅保留已验证的最终 Excel。清理范围以进程新建的目录、随机所有权标记及真实父路径为边界，不扫桌面、历史请求、其他任务或 CLI 全局审计日志，不动源码、技能和凭证。
 
-`--written-excel` 可重复。脚本**只删除出现在 `--written-excel` 里、且不是 `--keep-excel` 的文件**；路径对不上的一律跳过。
+符号链接和 Windows junction/reparse point 只移除本次目录中的链接本身，不能递归跟随目标。最终路径落入临时根时拒绝执行。文件占用或归属异常会返回残留路径并令批次非零退出，已验证最终文件仍保留。
 
-## 一次请求只留一份最终 Excel
+Ctrl+C/SIGTERM 停止启动新任务，并等待在途 CLI 终止后清理；强杀/断电无法保证清理，不自动删除历史遗留目录。
 
-- 先把**全部**业务线行的策略文案定稿，再调用一次 `scripts/build_report.py`。不要「先导一版再改文案再导一版」。
-- 若必须重导（脚本失败、列数不对、文案发现硬伤）：记下新的 `output_path`，立刻删掉本次清单里**上一份** Excel。只删 `excels_written` 里的精确路径。
-- **禁止**：按桌面文件名 glob（`业务线策略生成_*.xlsx`）再「只留最新」——会把**其他请求**的最终文件删掉。
-- **禁止**：`Remove-Item -Force` 扫整个桌面时间戳范围。
-- 其他请求、用户自己放在桌面的 xlsx，一律不动。
+## 输出
 
-向用户汇报时只给**最终**那一份路径。
+控制台 JSON 行返回业务线 ID、阶段进度、各阶段耗时和完成结果；最终事件包含成功/失败数量及每条 `output_path` 或错误。任意生成/导出/清理失败时批次非零退出，其他成功文件保留。不额外保留性能报告、预览图或分析日志。