sino-bc-cli 1.8.26 → 1.8.27

package/dist/skills/custom/biz-line-strategy-generate/scripts/summarize.py

@@ -14,6 +14,7 @@ SCRIPTS = Path(__file__).resolve().parent
 if str(SCRIPTS) not in sys.path:
     sys.path.insert(0, str(SCRIPTS))
 
+from cli_json import learning_text, amount_change
 from cli_json import (
     bid_adjust_stats,
     budget_abs_share,
@@ -73,7 +74,7 @@ def load_merged(bl: Path, stem: str) -> list:
 
 
 def object_name_maps(rows, id_key, name_key) -> tuple[dict[str, str], dict[str, str]]:
-    """id → 明细展示名（空则回退 id），以及原始 display（空名不当作 id，避免命名规律拆 ID）。"""
+    """id → 明细展示名（空则回退 id），以及原始 display（空名不当作 id，避免分布在拆 ID）。"""
     names: dict[str, str] = {}
     raw: dict[str, str] = {}
     for row in rows:
@@ -164,7 +165,7 @@ def bid_changes(rows, fields):
 
 
 def new_items(curr_rows, prev_rows, key, id_key=None):
-    """按稳定 ID/维度值聚合基础指标，再识别本期新出现的对象。只为新增对象保留行。"""
+    """按稳定 ID/维度值聚合基础指标，再识别新增的对象。只为新增对象保留行。"""
     def identity(row):
         return str(row.get(id_key) or "") if id_key else disp(row, key)
     previous: dict[str, str] = {}
@@ -195,7 +196,7 @@ def dim_layer_text(title: str, items: list, stop_labs: list, rule=None):
     rule = rule or core_rule("")
     metric = rule["metric"]
     if not items and not stop_labs:
-        return f"{title}\n本期无新增，跳过。", None, 0.0, 0.0
+        return f"{title}\n本期无新增。", None, 0.0, 0.0
     lines = [title]
     usable = [it for it in items if it["spend"] >= 50]
     for it in usable[:DETAIL_LIMIT]:
@@ -208,7 +209,7 @@ def dim_layer_text(title: str, items: list, stop_labs: list, rule=None):
     if len(items) > len(usable):
         lines.append(f"· 另有 {len(items) - len(usable)} 个新增消耗不足 $50，不纳入聚合")
     if stop_labs:
-        lines.append(f"· 本期未出现 {len(stop_labs)} 个：{examples(stop_labs)}（不等同已暂停）")
+        lines.append(f"· 暂停 {len(stop_labs)} 个：{examples(stop_labs)}")
     records = [r for it in usable for r in it.get("rows", [])]
     value = metric_value(records, metric)
     hit = rule_hit(value, rule)
@@ -217,27 +218,10 @@ def dim_layer_text(title: str, items: list, stop_labs: list, rule=None):
 
 
 def setting_line(title, curr_set, prev_set, first_period=False) -> str:
-    news, stops = sorted(curr_set - prev_set), sorted(prev_set - curr_set)
-    lines = [title]
+    """主表仅保留集合数量；成员名称统一在明细列出。"""
     if first_period:
-        labs = sorted(curr_set)
-        if title.startswith("【国家】"):
-            main, _extra = summarize_countries(labs)
-            lines.append(f"首期展示当期配置：{main}；示例 {examples(labs)}")
-        else:
-            lines.append(f"首期展示当期 {len(labs)} 个：{examples(labs)}")
-        return "\n".join(lines)
-    if news:
-        if title.startswith("【国家】"):
-            main, _extra = summarize_countries(news)
-            lines.append(f"新增 {len(news)} 个（{main}）：{examples(news)}")
-        else:
-            lines.append(f"新增 {len(news)} 个：{examples(news)}")
-    if stops:
-        lines.append(f"本期未出现 {len(stops)} 个：{examples(stops)}")
-    if len(lines) == 1:
-        lines.append("未发现新增或本期未出现")
-    return "\n".join(lines)
+        return f'{title}\n当期 {len(curr_set)} 个'
+    return f'{title}\n新增 {len(curr_set - prev_set)} 个，暂停 {len(prev_set - curr_set)} 个'
 
 
 def ad_keywords(names, n=3):
@@ -255,6 +239,7 @@ def ad_keywords(names, n=3):
 
 def summarize_request(req: Path):
     """仅使用本次通过分页校验的文件，固定生成摘要和完整明细。"""
+    from strategy_output import effect_code
     biz = load_json_file(req / "biz-line.json") or {}
     detail = load_json_file(req / "biz-line-detail.out.json") or {}
     detail_data = detail.get("data") if isinstance(detail.get("data"), dict) else {}
@@ -281,12 +266,8 @@ def summarize_request(req: Path):
     if len(curr) == 2 and len(prev) == 2:
         period = f"本期：{curr[0]}～{curr[1]}\n上期：{prev[0]}～{prev[1]}"
     else:
-        # 本次请求未落 periods.json 时，回退业务线接口上的策略周期
-        cs = biz.get("periodStart") or detail_data.get("periodStart")
-        ce = biz.get("periodEnd") or detail_data.get("periodEnd")
-        ps = biz.get("prevPeriodStart") or detail_data.get("prevPeriodStart")
-        pe = biz.get("prevPeriodEnd") or detail_data.get("prevPeriodEnd")
-        period = f"本期：{cs}～{ce}\n上期：{ps}～{pe}" if cs and ce and ps and pe else ""
+        # 缺少请求周期时不能以业务线周期冒充本次分析范围。
+        raise ValueError('缺少有效 periods.json，请通过统一入口重新拉取数据')
 
     spend = {"curr": {}, "prev": {}}
     imps = {"curr": {}, "prev": {}}
@@ -354,7 +335,7 @@ def summarize_request(req: Path):
         spend_verdict = "待观察"
         gate_note = f"本期有效投放 {eff_days} 天、消耗 ${curr_total:,.0f}、安装 {curr_inst:,.0f}"
     qoq_pct_s = "" if qoq_pct is None else f"{qoq_pct * 100:+.1f}%"
-    details: list[dict] = [{"bizLine": name, "kind": "口径", "action": "客户 KPI", "channel": "", "name": core_index or "未填写", "extra": rule["reason"]}]
+    details: list[dict] = []  # KPI 原文仅参与内部判定，不写入任一 sheet。
     coverage_notes = []
     from datetime import date, timedelta
     for per, bounds in (("curr", periods.get("curr")), ("prev", periods.get("prev"))):
@@ -398,12 +379,7 @@ def summarize_request(req: Path):
             f"{label}：上调 {stats['raise_n']} 个广告组，下调 {stats['lower_n']} 个；"
             f"期内变化但首末持平 {stats['flat_n']} 个；幅度中位数 {stats['median_abs']:.2f}"
         ]
-        if stats["list_all"]:
-            for b in stats["details"]:
-                lines.append(
-                    f"· {short_label(b.get('name') or '')}：{b.get('action')} "
-                    f"{b.get('from')} → {b.get('to')}（{b.get('times')} 次）"
-                )
+        lines.append('分布在：' + naming_patterns([b.get('name') or '' for b in items]))
         return "\n".join(lines)
 
     for ch in ("fb", "gg", "tt"):
@@ -424,6 +400,7 @@ def summarize_request(req: Path):
     budget_strategy = "\n".join(
         [
             "【调整出价】",
+            f"合计 {sum(len(items) for items in bids.values())} 个广告组调整出价",
             bid_text("fb"),
             bid_text("gg"),
             bid_text("tt"),
@@ -450,53 +427,41 @@ def summarize_request(req: Path):
                 prev_share=prev_share["tt"],
                 curr_share=curr_share["tt"],
             ),
-            f"消耗合计：本期 ${curr_total:,.0f} / 上期 ${prev_total:,.0f}",
+            f"消耗合计：本期 ${curr_total:,.0f} / 上期 ${prev_total:,.0f}；{amount_change(curr_total, prev_total)}",
         ]
     )
     cpi_s = f"全渠道 {metric}：本期 {fmt_cpm(core_c)} / 上期 {fmt_cpm(core_p)}"
     cpi_s += "（美元消耗 / 平台安装量，非客户激活或留存成本）" if metric == "CPI" else "（同粒度基础指标合计后计算）"
-    budget_learning = "\n".join(
-        [
-            f"结论：{spend_verdict}（第二期起跟环比，KPI 只作依据）" if not first_period else f"结论：{spend_verdict}（首期）",
-            f"依据：{cpi_s}，环比{qoq_label}" + (f" {qoq_pct_s}" if qoq_pct_s else ""),
-            f"客户 KPI：{core_index or '未填写'}；{rule['reason']}",
-            *([f"门槛：{gate_note} → 待观察"] if gate_note else []),
-            "",
-            "Spend",
-            f"· {cpi_s}",
-            f"· 参考 CPM：本期 {fmt_cpm(overall_c)} / 上期 {fmt_cpm(overall_p)}（不作结论轴）",
-            f"· {budget_abs_share('FB', prev_abs=spend['prev']['fb'], curr_abs=spend['curr']['fb'], prev_share=prev_share['fb'], curr_share=curr_share['fb'])}",
-            f"· {budget_abs_share('GG', prev_abs=spend['prev']['gg'], curr_abs=spend['curr']['gg'], prev_share=prev_share['gg'], curr_share=curr_share['gg'])}",
-            f"· {budget_abs_share('TT', prev_abs=spend['prev']['tt'], curr_abs=spend['curr']['tt'], prev_share=prev_share['tt'], curr_share=curr_share['tt'])}",
-            "",
-            "调整出价",
-            *[
-                f"· {CH_LABEL[ch]}：上调 {bid_stats[ch]['raise_n']} / 下调 {bid_stats[ch]['lower_n']}，"
-                f"幅度中位数 {bid_stats[ch]['median_abs']:.2f}"
-                for ch in ("fb", "gg", "tt")
-            ],
-            "",
-            advice_of(spend_verdict),
-        ]
-    )
+    budget_learning = learning_text(spend_verdict, rule)
 
     def share_line(title, dim_key, stem, channels):
-        segs = []
-        moved = False
+        """占比同时展示对应消耗；主表汇总前三类，其余合并，明细保留全量。"""
+        segs, moved = [], False
         for ch in channels:
-            curr, _ = share_map(iter_stem_rows(bl, f"met_{ch}_curr_{stem}"), dim_key)
-            prev, _ = share_map(iter_stem_rows(bl, f"met_{ch}_prev_{stem}"), dim_key)
-            if share_moved(curr, prev):
-                moved = True
-            if curr or prev:
-                segs.append(f"{CH_LABEL[ch]}：{fmt_share(curr, prev)}")
-        return ("\n".join([title] + segs) if segs else ""), moved
+            current, current_total = share_map(iter_stem_rows(bl, f'met_{ch}_curr_{stem}'), dim_key)
+            previous, previous_total = share_map(iter_stem_rows(bl, f'met_{ch}_prev_{stem}'), dim_key)
+            moved = moved or share_moved(current, previous)
+            keys = [key for key in sorted(set(current) | set(previous), key=lambda key: (-current.get(key, 0), key))
+                    if not is_ghost_enum(current.get(key, 0), previous.get(key, 0))]
+            def aggregate_line(label, members):
+                cp, pp = sum(current.get(k, 0) for k in members), sum(previous.get(k, 0) for k in members)
+                ca, pa = cp * current_total / 100, pp * previous_total / 100
+                return f'{label}：消耗 ${pa:,.0f} → ${ca:,.0f}，占比 {pp:.1f}% → {cp:.1f}%；{amount_change(ca, pa)}'
+            for key in keys:
+                details.append({'bizLine': name, 'kind': title.strip('【】') + '/分布', 'action': '对比',
+                    'channel': CH_LABEL[ch], 'name': key, 'extra': aggregate_line(key, [key])})
+            parts = [aggregate_line(key, [key]) for key in keys[:3]]
+            if len(keys) > 3:
+                parts.append(aggregate_line('其余类别合计', keys[3:]))
+            if parts:
+                segs.append(CH_LABEL[ch] + '：' + '；'.join(parts))
+        return ('\n'.join([title] + segs) if segs else ''), moved
 
     p_obj, m1 = share_line("【广告目标】", "objective", "objective", ["fb", "tt"])
     p_ch, m2 = share_line("【广告系列类型】", "advertising_channel_type", "advertising_channel_type", ["gg"])
     p_opt, m3 = share_line("【成效目标】", "optimization_goal", "optimization_goal", ["fb", "gg", "tt"])
     p_bid, m4 = share_line("【出价方式】", "bid_strategy", "bid_strategy", ["fb", "gg", "tt"])
-    product_strategy = "\n\n".join(x for x in [p_obj, p_ch, p_opt, p_bid] if x)
+    product_strategy = "\n".join(x for x in [p_obj, p_ch, p_opt, p_bid] if x) or '本期无可识别的广告产品策略数据'
     product_share_moved = any([m1, m2, m3, m4])
 
     def dim_sets(stem, key, channels):
@@ -538,7 +503,7 @@ def summarize_request(req: Path):
                 {
                     "bizLine": name,
                     "kind": kind,
-                    "action": "本期未出现",
+                    "action": "暂停",
                     "channel": channel,
                     "name": lab,
                     "extra": "",
@@ -551,9 +516,12 @@ def summarize_request(req: Path):
     add_setting_details("国家", country_curr, country_prev)
     add_setting_details("兴趣词", interest_curr, interest_prev)
     add_setting_details("关键词", kw_curr, kw_prev)
+    for label, field in (("年龄", "targeting_age"), ("性别", "targeting_genders")):
+        add_setting_details(label, *dim_sets(field, field, ["fb", "gg", "tt"]))
 
     def object_strategy(kind, id_key, name_key):
         bits = []
+        total_new = total_absent = 0
         for ch in CH_LABEL:
             stem = f"{id_key}+{name_key}"
 
@@ -563,20 +531,25 @@ def summarize_request(req: Path):
             c, c_raw = index_objects("curr")
             p, _p_raw = index_objects("prev")
             new, absent = sorted(c.keys() - p.keys()), sorted(p.keys() - c.keys())
-            bits.append(f"{CH_LABEL[ch]}：本期新出现 {len(new)} 个，本期未出现 {len(absent)} 个；命名规律：{naming_patterns([c_raw[i] for i in new])}")
+            total_new += len(new)
+            total_absent += len(absent)
+            if not c and not p:
+                continue
+            bits.append(f"{CH_LABEL[ch]}：新增 {len(new)} 个，暂停 {len(absent)} 个；新增分布在：{naming_patterns([c_raw[i] for i in new])}；暂停分布在：{naming_patterns([_p_raw[i] for i in absent])}")
             for ident in sorted(c.keys() | p.keys()):
                 record_name = c.get(ident) or p[ident]
-                action = "当期" if first_period else ("新增" if ident in new else ("本期未出现" if ident in absent else "持续"))
+                action = "当期" if first_period else ("新增" if ident in new else ("暂停" if ident in absent else "持续"))
                 details.append({"bizLine": name, "kind": kind, "action": action, "channel": CH_LABEL[ch], "name": record_name, "extra": f"ID={ident}；集合差异不等同创建/暂停操作"})
-        return bits
+        return [f'合计新增 {total_new} 个{kind}，暂停 {total_absent} 个'] + bits
 
+    audience_type_text, audience_type_moved = share_line("【受众类型】", "audience_type", "audience_type", ["fb", "gg", "tt"])
     ag_bits = object_strategy("广告组", "adgroup_id", "adgroup_name")
-    audience_strategy = "\n\n".join(
+    audience_strategy = "\n".join(
         x
         for x in [
             setting_line("【国家】", country_curr, country_prev, first_period=first_period),
             setting_line("【兴趣词包】", interest_curr, interest_prev, first_period=first_period),
-            share_line("【受众类型】", "audience_type", "audience_type", ["fb", "gg", "tt"])[0],
+            audience_type_text,
             setting_line("【关键词】", kw_curr, kw_prev, first_period=first_period),
             setting_line("【年龄】", *dim_sets("targeting_age", "targeting_age", ["fb", "gg", "tt"]), first_period=first_period),
             setting_line("【性别】", *dim_sets("targeting_genders", "targeting_genders", ["fb", "gg", "tt"]), first_period=first_period),
@@ -589,12 +562,11 @@ def summarize_request(req: Path):
     creative_fmt = share_line("【创意类型】", "ad_format", "ad_format", ["fb", "gg", "tt"])[0] or ""
     creative_strategy = "【广告】\n" + "\n".join(ad_bits) + (("\n\n" + creative_fmt) if creative_fmt else "")
 
-    def strategy_learning(dim_specs, allow_share_fallback=False, share_did_move=False):
-        texts = []
-        hit_spend = all_spend = 0.0
-        any_new = only_stop = False
+    # 文案和效果在同一判断点产出，不扫描 learning 文本反推状态。
+    learning_effects = {}
+
+    def strategy_learning(dim_specs, allow_share_fallback=False, share_did_move=False, strategy_key=''):
         for title, stem, key, channels, id_key in dim_specs:
-            items_all, stops_all = [], []
             for ch in channels:
                 curr_stem = f"met_{ch}_curr_{stem}"
                 prev_stem = f"met_{ch}_prev_{stem}"
@@ -613,18 +585,6 @@ def summarize_request(req: Path):
                         hit = rule_hit(value, rule)
                         verdict_text = '不可判定' if hit is None else ('达标' if hit else '未达标')
                         details.append({"bizLine": name, "kind": f"新增成效/{title}", "action": "新增", "channel": CH_LABEL[ch], "name": item["label"], "extra": f"ID={item['id']}；消耗美元 {item['spend']:.2f}；{metric} {fmt_cpm(value)}；KPI {verdict_text}"})
-                items_all.extend(items)
-                stops_all.extend(stops)
-            if items_all:
-                any_new = True
-            if stops_all and not items_all:
-                only_stop = True
-            text, _hit, hs, ts = dim_layer_text(title, items_all, stops_all, rule)
-            texts.append(text)
-            if ts > 0:
-                hit_spend += hs
-                all_spend += ts
-        detail = "\n\n".join(texts)
         verdict = period_verdict(
             first_period=first_period,
             qoq_label=qoq_label,
@@ -633,55 +593,8 @@ def summarize_request(req: Path):
         )
         if gate_note:
             verdict = "待观察"
-        evidence = (
-            f"{cpi_s}，环比{qoq_label}" + (f" {qoq_pct_s}" if qoq_pct_s else "")
-            + "。此为整体环比观察，不代表本次单一动作的因果效果；" + rule["reason"]
-        )
-        if not any_new and only_stop:
-            return "\n".join(
-                [
-                    f"结论：{verdict}",
-                    "口径：本期无新增，走本期未出现",
-                    f"依据：{evidence}",
-                    "",
-                    detail,
-                    "",
-                    advice_of(verdict),
-                ]
-            )
-        if not any_new:
-            if allow_share_fallback and share_did_move:
-                return "\n".join(
-                    [
-                        f"结论：{verdict}",
-                        "口径：无新增枚举，占比变化超过 ±2%，按可环比",
-                        f"依据：{evidence}",
-                        "",
-                        detail,
-                        "",
-                        advice_of(verdict),
-                    ]
-                )
-            return "\n".join(
-                [
-                    f"结论：{verdict}",
-                    "口径：本期无实质调整动作",
-                    f"依据：{evidence}",
-                    "",
-                    detail,
-                ]
-            )
-        ratio = (hit_spend / all_spend) if all_spend else 0.0
-        return "\n".join(
-            [
-                f"结论：{verdict}",
-                f"依据：{evidence}",
-                "",
-                detail,
-                "",
-                advice_of(verdict),
-            ]
-        )
+        learning_effects[strategy_key] = effect_code(verdict)
+        return learning_text(verdict, rule)
 
     product_learning = strategy_learning(
         [
@@ -692,6 +605,7 @@ def summarize_request(req: Path):
         ],
         allow_share_fallback=True,
         share_did_move=product_share_moved,
+        strategy_key='product',
     )
     audience_learning = strategy_learning(
         [
@@ -702,13 +616,13 @@ def summarize_request(req: Path):
             ("年龄", "targeting_age", "targeting_age", ["fb", "gg", "tt"], None),
             ("性别", "targeting_genders", "targeting_genders", ["fb", "gg", "tt"], None),
             ("广告组", "adgroup_id+adgroup_name", "adgroup_name", ["fb", "gg", "tt"], "adgroup_id"),
-        ]
+        ], strategy_key='audience',
     )
     creative_learning = strategy_learning(
         [
             ("广告", "ad_id+ad_name", "ad_name", ["fb", "gg", "tt"], "ad_id"),
             ("创意类型", "ad_format", "ad_format", ["fb", "gg", "tt"], None),
-        ]
+        ], strategy_key='creative',
     )
 
     row = {
@@ -724,7 +638,30 @@ def summarize_request(req: Path):
         "audienceLearning": audience_learning,
         "creativeStrategy": creative_strategy,
         "creativeLearning": creative_learning,
+        "budgetEffect": effect_code(spend_verdict),
+        **{key + 'Effect': value for key, value in learning_effects.items()},
     }
+    # 证据只来自实际快照或集合/占比变化；不把消耗下降推断为主动减预算。
+    evidence = {'budget': [], 'product': [], 'audience': []}
+    if any(bids.values()):
+        evidence['budget'].append('出价调整')
+    for field, action in [('raise_n', '上调出价'), ('lower_n', '下调出价')]:
+        if any(stats[field] for stats in bid_stats.values()):
+            evidence['budget'].append(action)
+    if not first_period:
+        for moved, label in zip((m1, m2, m3, m4), ('广告目标调整', '广告系列类型调整', '成效目标调整', '出价方式调整')):
+            if moved:
+                evidence['product'].append(label)
+        for current, previous, label in [(country_curr, country_prev, '国家调整'),
+                                          (interest_curr, interest_prev, '兴趣词调整'), (kw_curr, kw_prev, '关键词调整')]:
+            if current != previous:
+                evidence['audience'].append(label)
+        for stem, label in [('targeting_age', '年龄调整'), ('targeting_genders', '性别调整')]:
+            current, previous = dim_sets(stem, stem, ['fb', 'gg', 'tt'])
+            if current != previous:
+                evidence['audience'].append(label)
+        if audience_type_moved:
+            evidence['audience'].append('受众类型调整')
     payload = {"rows": [row], "details": details}
     (req / "payload.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
     summary = {
@@ -738,6 +675,7 @@ def summarize_request(req: Path):
         "spend_verdict": spend_verdict,
         "bid_counts": {ch: len(bids[ch]) for ch in bids},
         "detail_count": len(details),
+        "tag_evidence": evidence,
         "request_dir": str(req),
     }
     (req / "summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8")