sino-bc-cli 1.0.0-beta.0

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

@@ -0,0 +1,705 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CLI 信封解包与文案用的小工具。拉数 / 汇总脚本共用，避免再手写解析。"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import threading
+import math
+import re
+from contextlib import contextmanager
+from pathlib import Path
+
+_local = threading.local()
+
+
+@contextmanager
+def cli_context(cancel, progress):
+    """每个业务线独立传递取消信号与进度回调，不共享可变回包。"""
+    _local.cancel, _local.progress = cancel, progress
+    try:
+        yield
+    finally:
+        _local.cancel = _local.progress = None
+
+
+def report_progress(message):
+    """统一入口由协调回调串行输出；诊断脚本沿用控制台输出。"""
+    callback = getattr(_local, "progress", None)
+    if callback:
+        callback(message)
+    else:
+        print(message, flush=True)
+
+ENUM_ZH = {
+    "OUTCOME_APP_PROMOTION": "应用推广",
+    "OUTCOME_SALES": "销量",
+    "OUTCOME_LEADS": "线索",
+    "OUTCOME_AWARENESS": "认知",
+    "OUTCOME_TRAFFIC": "流量",
+    "OUTCOME_ENGAGEMENT": "互动",
+    "OUTCOME_APP_INSTALLS": "应用安装",
+    "APP_INSTALLS": "应用安装",
+    "APP_PROMOTION": "应用推广",
+    "CONVERSIONS": "转化",
+    "REACH": "覆盖",
+    "LINK_CLICKS": "链接点击",
+    "LANDING_PAGE_VIEWS": "落地页浏览",
+    "VALUE": "价值",
+    "OFFSITE_CONVERSIONS": "站外转化",
+    "COST_CAP": "成本上限",
+    "BID_CAP": "出价上限",
+    "LOWEST_COST_WITHOUT_CAP": "最低成本",
+    "LOWEST_COST_WITH_BID_CAP": "最低成本（出价上限）",
+    "LOWEST_COST_WITH_MIN_ROAS": "最低成本（最低 ROAS）",
+    "TARGET_COST": "目标成本",
+    "TARGET_CPA": "目标 CPA",
+    "TARGET_ROAS": "目标 ROAS",
+    "MAXIMIZE_CONVERSIONS": "尽可能多转化",
+    "MAXIMIZE_CONVERSION_VALUE": "尽可能高转化价值",
+    "LOOKALIKE": "类似受众",
+    "CUSTOM": "自定义受众",
+    "CUSTOM_AUDIENCE": "自定义受众",
+    "BOARD": "通用",
+    "BROAD": "通用",
+    "CORE": "核心受众",
+    "INTEREST": "兴趣",
+    "IMAGE": "图片",
+    "VIDEO": "视频",
+    "CAROUSEL": "轮播",
+    "COLLECTION": "精选",
+    "SINGLE_IMAGE": "单图",
+    "SINGLE_VIDEO": "单视频",
+    "PERFORMANCE_MAX": "PMax",
+    "SEARCH": "搜索广告",
+    "DISPLAY": "展示广告",
+    "SHOPPING": "购物广告",
+    "MULTI_CHANNEL": "多渠道",
+    "MALE": "男性",
+    "FEMALE": "女性",
+    "GENDER_MALE": "男性",
+    "GENDER_FEMALE": "女性",
+    "VIDEO_VIEWS": "视频播放",
+    "IN_APP_EVENT": "应用内事件",
+    "INSTALL": "安装",
+    "ENGAGED_VIEW": "有效观看",
+    "BID_TYPE_CUSTOM": "自定义出价",
+    "BID_TYPE_NO_BID": "不设出价",
+    "WEB_CONVERSIONS": "网站转化",
+    "CONVERT": "转化",
+    "CUSTOM&LOOKALIKE": "自定义/相似受众",
+}
+
+
+def resolve_cli() -> list[str]:
+    """优先 PATH 上的 sino-bc-cli；Windows 找不到时再退到 npm 全局包。"""
+    found = shutil.which("sino-bc-cli")
+    if found:
+        # Windows 的 cmd shim 会重新解释 JSON 中的特殊字符，直接调用同包 Node 入口。
+        if os.name == "nt" and Path(found).suffix.lower() in (".cmd", ".bat"):
+            return [shutil.which("node") or "node", str(shim_entry(Path(found)))]
+        return [found]
+    npm_js = (
+        Path(os.environ.get("APPDATA", ""))
+        / "npm"
+        / "node_modules"
+        / "sino-bc-cli"
+        / "dist"
+        / "index.js"
+    )
+    if npm_js.is_file():
+        return ["node", str(npm_js)]
+    raise FileNotFoundError("找不到 sino-bc-cli，请先全局安装或执行 /init")
+
+
+def shim_entry(shim: Path) -> Path:
+    """只读解析 npm/pnpm 的 Node 入口，不执行 cmd 文本或解释用户 JSON。"""
+    candidates = [shim.parent / 'node_modules/sino-bc-cli/dist/index.js']
+    content = shim.read_text(encoding='utf-8')
+    for value in re.findall(r'"([^"\r\n]*sino-bc-cli[\\/]dist[\\/]index\.js)"', content, re.I):
+        value = re.sub(r'%(?:~dp0%?|dp0%)', lambda _: str(shim.parent) + os.sep, value, flags=re.I)
+        if '%' not in value:
+            path = Path(value)
+            candidates.append(path if path.is_absolute() else shim.parent / path)
+    for entry in candidates:
+        if entry.is_file():
+            return entry.resolve()
+    raise RuntimeError('CLI shim 对应包入口不可访问或布局无法识别，请检查全局安装目录权限')
+
+
+def parse_json_text(raw: str):
+    """从混有日志的文本里取出第一段 JSON。数组文件必须从 '[' 起读，不能先找 '{'。"""
+    text = (raw or "").strip()
+    starts = [i for i in (text.find("{"), text.find("[")) if i >= 0]
+    if not starts:
+        return None
+    try:
+        return json.loads(text[min(starts) :])
+    except json.JSONDecodeError:
+        return None
+
+
+def load_json_file(path: Path):
+    if not path.exists():
+        return None
+    return parse_json_text(path.read_text(encoding="utf-8"))
+
+
+def unwrap_page(envelope: dict) -> tuple[list, int]:
+    """CLI 信封里的分页行。
+
+    - 列表：data.result + data.total
+    - 维度/成效：data.data + data.total（不是 data.result）
+    - project-list：data 直接是数组
+    """
+    if not isinstance(envelope, dict):
+        return [], 0
+    data = envelope.get("data")
+    if isinstance(data, list):
+        return data, len(data)
+    if not isinstance(data, dict):
+        return [], 0
+    if isinstance(data.get("data"), list):
+        rows = data["data"]
+        return rows, int(data["total"] if data.get("total") is not None else len(rows))
+    if isinstance(data.get("result"), list):
+        rows = data["result"]
+        return rows, int(data["total"] if data.get("total") is not None else len(rows))
+    return [], 0
+
+
+def exec_cli_to_file(cmd: list[str], out_path: Path) -> tuple[int, str]:
+    """两个输出流直写本次文件；取消时等待子进程退出后才允许清理。"""
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    cancel = getattr(_local, "cancel", None)
+    if cancel and cancel.is_set():
+        raise InterruptedError("任务已取消")
+    with out_path.open("w", encoding="utf-8") as f, out_path.with_suffix(".stderr.txt").open("w", encoding="utf-8") as err:
+        proc = subprocess.Popen(cmd, stdout=f, stderr=err, shell=False)
+        try:
+            while True:
+                try:
+                    proc.wait(timeout=0.2)
+                    break
+                except subprocess.TimeoutExpired:
+                    if cancel and cancel.is_set():
+                        raise InterruptedError("任务已取消")
+        finally:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+    raw = out_path.read_text(encoding="utf-8")
+    return proc.returncode, raw
+
+
+def list_query_body(*, name: str = "", biz_id: int = 0) -> dict:
+    """+list 只接受 --data，禁止再拼 --name / --id flag。"""
+    body = {
+        "pageNum": 1,
+        "pageSize": 20,
+        "sortType": "PERIOD",
+        "sortDirection": "DESC",
+    }
+    if biz_id:
+        body["idList"] = [int(biz_id)]
+        body["pageSize"] = 10
+    elif name:
+        body["name"] = name
+    return body
+
+
+def run_cli(args: list[str], body: dict | None, out_path: Path) -> dict:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    cmd = [*resolve_cli(), *args, "--format", "json"]
+    if body is not None:
+        body_path = out_path.with_name(out_path.name.replace(".out.json", ".body.json"))
+        if body_path == out_path:
+            body_path = out_path.with_suffix(".body.json")
+        body_path.write_text(json.dumps(body, ensure_ascii=False), encoding="utf-8")
+        cmd.extend(["--data", json.dumps(body, ensure_ascii=False)])
+    rc, raw = exec_cli_to_file(cmd, out_path)
+    parsed = parse_json_text(raw.strip())
+    stderr = out_path.with_suffix(".stderr.txt").read_text(encoding="utf-8", errors="replace")
+    if not isinstance(parsed, dict) or rc != 0 or parsed.get("ok") is not True:
+        error = parse_json_text(stderr) or stderr or parsed or raw or "无有效 CLI 回包"
+        parsed = {"ok": False, "error": error, "rc": rc}
+    return parsed
+
+
+def require_ok(envelope, label):
+    """失败信封不能按空数据继续生成报告。"""
+    if not isinstance(envelope, dict) or envelope.get("ok") is not True:
+        raise RuntimeError(f"{label}: {json.dumps(envelope, ensure_ascii=False)[:2000]}")
+    return envelope
+
+
+def optional_num(row, key):
+    """指标缺失与零分开，拒绝 NaN/Infinity 进入分析及 Excel。"""
+    try:
+        value = float(row.get(key))
+        return value if math.isfinite(value) else None
+    except (TypeError, ValueError):
+        return None
+
+
+# 2026-09-23 核对三个渠道成效接口 indicators 枚举，统一作为查询与识别来源。
+BASE_METRICS = {
+    'spend_usd': ('消耗', '消耗金额', '花费', 'spend'),
+    'impressions': ('曝光', '曝光量', '展示', '展示次数'),
+    'clicks': ('点击', '点击量', '点击次数'),
+    'video_views': ('视频观看', '视频观看次数', '视频播放量'),
+    'add_to_cart': ('添加购物车次数', '加购', '加购量', '加购次数'),
+    'checkouts': ('发起结账次数', '结账', '结账次数'),
+    'purchase': ('购买', '购买次数', '购买量'),
+    'purchase_value': ('购买金额', '购买金额美元', '购买收入'),
+    'installs': ('安装', '安装量', '应用安装量'),
+    'complete_registration': ('注册', '注册量', '完成注册量'),
+    'leads': ('线索', '线索量', '潜客', '潜客数量', '留下潜客信息次数'),
+    'engagement': ('互动', '互动量', '互动次数'),
+}
+
+# 飞书「指标」sheet 的顺序是明细表的固定列顺序；code 是本地计算键，不传给成效接口。
+REPORT_METRICS = [
+    ('spend_usd', '消耗金额_美元', False), ('impressions', '曝光量', False),
+    ('clicks', '点击量', False), ('video_views', '视频观看次数', False),
+    ('add_to_cart', '添加购物车次数', False), ('checkouts', '发起结账次数', False),
+    ('purchase', '购买次数', False), ('purchase_value', '购买金额', False),
+    ('installs', '应用安装量', False), ('complete_registration', '完成注册量', False),
+    ('leads', '留下潜客信息次数', False), ('engagement', '互动次数', False),
+    ('ctr', '点击率', True), ('cpc', '单次点击成本', False),
+    ('cpm', '千次曝光成本', False), ('cpi', '单次下载成本', False),
+    ('cpe', '单次互动成本', False), ('cpv', '单次视频观看成本', False),
+    ('cpaPurchase', '单次订单成本', False),
+    ('cpaAddsToCart', '单次加入购物车成本', False),
+    ('cpr', '单次注册成本', False), ('cpl', '单次线索成本', False),
+    ('cvrAddsToCart', '加入购物车转化率', True),
+    ('cvrPurchases', '订单转化率', True),
+    ('cvrAppInstalls', '安装转化率', True), ('vtr', '视频观看率', True),
+    ('roas', '投资回报率', False), ('arpp', '笔单价', False),
+    ('cvrRegistrationsCompleted', '注册转化率', True),
+]
+
+
+# 衍生指标只在本地计算；不能把这些名称传给接口 indicators。
+METRIC_FORMULAS = {"CPI": ("spend_usd", "installs", 1), "CPC": ("spend_usd", "clicks", 1),
+                   "CPM": ("spend_usd", "impressions", 1000), "ROAS": ("purchase_value", "spend_usd", 1),
+                   "CTR": ("clicks", "impressions", 100)}
+# 文档公式中的 spendUsdUsd/spendUsd、add_to_cart/addsToCart 等写法统一映射到
+# 三渠道成效接口的 12 个 snake_case 基础字段；百分率以百分数展示。
+METRIC_FORMULAS.update({
+    'ctr': ('clicks', 'impressions', 100),
+    'cpc': ('spend_usd', 'clicks', 1),
+    'cpm': ('spend_usd', 'impressions', 1000),
+    'cpi': ('spend_usd', 'installs', 1),
+    'cpe': ('spend_usd', 'engagement', 1),
+    'cpv': ('spend_usd', 'video_views', 1),
+    'cpaPurchase': ('spend_usd', 'purchase', 1),
+    'cpaAddsToCart': ('spend_usd', 'add_to_cart', 1),
+    'cpr': ('spend_usd', 'complete_registration', 1),
+    'cpl': ('spend_usd', 'leads', 1),
+    'cvrAddsToCart': ('add_to_cart', 'clicks', 100),
+    'cvrPurchases': ('purchase', 'clicks', 100),
+    'cvrAppInstalls': ('installs', 'clicks', 100),
+    'vtr': ('video_views', 'impressions', 100),
+    'roas': ('purchase_value', 'spend_usd', 1),
+    'arpp': ('purchase_value', 'purchase', 1),
+    'cvrRegistrationsCompleted': ('complete_registration', 'clicks', 100),
+})
+
+# 单次事件成本均可由美元消耗和对应事件量计算，不再局限原来的五个衍生指标。
+DERIVED_ALIASES = {}
+for _field, _names in BASE_METRICS.items():
+    if _field in ('spend_usd', 'purchase_value', 'impressions'):
+        continue
+    _code = 'cost_per_' + _field
+    METRIC_FORMULAS[_code] = ('spend_usd', _field, 1)
+    for _name in (_field, *_names):
+        DERIVED_ALIASES[_name + '成本'] = _code
+        DERIVED_ALIASES['单次' + _name + '成本'] = _code
+    DERIVED_ALIASES[_code] = _code
+# 安装和点击继续使用旧标准 code，保证指标识别及输出兼容。
+DERIVED_ALIASES.update({'安装成本': 'CPI', '应用安装成本': 'CPI', '点击成本': 'CPC',
+                        '注册成本': 'cost_per_complete_registration', '完成注册成本': 'cost_per_complete_registration',
+                        '线索成本': 'cost_per_leads', '购买成本': 'cost_per_purchase',
+                        '加购成本': 'cost_per_add_to_cart', '结账成本': 'cost_per_checkouts',
+                        '视频观看成本': 'cost_per_video_views', '互动成本': 'cost_per_engagement',
+                        '客单价': 'average_purchase_value'})
+METRIC_FORMULAS['average_purchase_value'] = ('purchase_value', 'purchase', 1)
+
+
+def metric_formula(metric):
+    """解析已知衍生指标或由基础字段明确指定的比值，不执行任意表达式。"""
+    if metric in METRIC_FORMULAS:
+        return METRIC_FORMULAS[metric]
+    match = re.fullmatch(r'([a-z_]+)/([a-z_]+)(\*100)?', str(metric or ''))
+    if match and match[1] in BASE_METRICS and match[2] in BASE_METRICS:
+        return match[1], match[2], 100 if match[3] else 1
+    return None
+
+
+def metric_fields(metric):
+    """返回核心指标依赖字段，以识别服务端 conflictField 的不支持反馈。"""
+    formula = metric_formula(metric)
+    return set(formula[:2]) if formula else ({metric} if metric else set())
+
+
+def metric_value(rows, metric="CPI"):
+    """同一粒度先合计基础指标再计算，任一缺失不当作零补齐。只扫一遍，可接迭代器。"""
+    if metric in BASE_METRICS:
+        total, seen = 0.0, False
+        for row in rows or ():
+            seen = True
+            value = optional_num(row, metric)
+            if value is None:
+                return None
+            total += value
+        return total if seen else None
+    formula = metric_formula(metric)
+    if formula is None:
+        return None
+    a, b, scale = formula
+    seen = False
+    num_a = num_b = 0.0
+    for row in rows or ():
+        seen = True
+        left, right = optional_num(row, a), optional_num(row, b)
+        if left is None or right is None:
+            return None
+        num_a += left
+        num_b += right
+    if not seen:
+        return None
+    return num_a / num_b * scale if num_b > 0 else None
+
+
+def core_rule(text):
+    """识别接口指标 code/中文别名及单一阈值；不猜复合目标或换算未知币种。"""
+    text = str(text or '').strip()
+    invalid = {'metric': None, 'usable': False, 'reason': '核心指标为空' if not text else '核心指标不支持'}
+    if not text:
+        return invalid
+    normalized = text.lower().replace('：', ':').strip()
+    for word, symbol in [('不超过', '<='), ('不低于', '>='), ('小于等于', '<='), ('大于等于', '>='),
+                         ('至少', '>='), ('至多', '<='), ('低于', '<'), ('高于', '>'), ('小于', '<'), ('大于', '>')]:
+        normalized = normalized.replace(word, symbol)
+    aliases = {alias.lower(): code for code, names in BASE_METRICS.items() for alias in (code, *names)}
+    # 指标表的 API 字段沿用驼峰命名，统一映射到三个成效接口实际返回的 snake_case 字段。
+    aliases.update({'spendusdusd': 'spend_usd', 'spendusd': 'spend_usd',
+                    'videoviews': 'video_views', 'addstocart': 'add_to_cart',
+                    'checkoutsinitiated': 'checkouts', 'purchases': 'purchase',
+                    'purchasesvalue': 'purchase_value', 'appinstalls': 'installs',
+                    'registrationscompleted': 'complete_registration',
+                    'engagements': 'engagement'})
+    # 显式比值可使用字段 code 或中文别名，分子分母均须确认为接口基础指标。
+    base_aliases = dict(aliases)
+    expression = re.match(r'^(.+?)[/÷](.+?)(\s*[*×]\s*100)?(?=\s*(?:<=|>=|≤|≥|<|>|=|$))', normalized)
+    if expression:
+        left, right = (base_aliases.get(expression[i].strip()) for i in (1, 2))
+        if left and right:
+            code = left + '/' + right + ('*100' if expression[3] else '')
+            normalized = code + normalized[expression.end():]
+            aliases[code] = code
+    aliases.update({key.lower(): key for key in METRIC_FORMULAS})
+    aliases.update(DERIVED_ALIASES)
+    # 指标表的中文名称和 API 字段均可作核心指标；同义词只映射到这 29 项的公式。
+    aliases.update({label.lower(): code for code, label, _is_percent in REPORT_METRICS})
+    aliases.update({'cpi': 'CPI', 'cpc': 'CPC', 'cpm': 'CPM', 'ctr': 'CTR', 'roas': 'ROAS'})
+    aliases.update({'安装成本': 'CPI', '点击成本': 'CPC', '千次展示成本': 'CPM', '点击率': 'CTR', '广告支出回报率': 'ROAS'})
+    # 最长名称优先，避免把“购买金额”误识别成“购买”。
+    pattern = '|'.join(re.escape(key) for key in sorted(aliases, key=len, reverse=True))
+    match = re.fullmatch(r'(' + pattern + r')\s*(.*?)', normalized)
+    if not match:
+        return invalid
+    alias, tail = match.groups()
+    metric = aliases[alias]
+    formula = metric_formula(metric)
+    supported_formulas = {metric_formula(code) for code, _label, _is_percent in REPORT_METRICS
+                          if code not in BASE_METRICS}
+    if metric not in BASE_METRICS and formula not in supported_formulas:
+        return invalid
+    cost = metric == 'spend_usd' or bool(formula and formula[0] == 'spend_usd')
+    percent = bool(formula and formula[2] == 100)
+    rule = {'metric': metric, 'usable': True, 'reason': '', 'target': None, 'op': None,
+            'higher_is_better': not cost}
+    money = metric in ('spend_usd', 'purchase_value') or bool(formula and formula[0] in ('spend_usd', 'purchase_value')
+                and formula[1] not in ('spend_usd', 'purchase_value') and not percent)
+    if not tail or (money and tail in ('usd', '美元', '$')) or (percent and tail == '%'):
+        return rule
+    target_match = re.fullmatch(r'(usd|美元|\$)?\s*(<=|>=|≤|≥|<|>|=|==)\s*(\d+(?:\.\d+)?)\s*(usd|美元|\$|%|次|个|量)?', tail)
+    if not target_match:
+        return {**invalid, 'metric': metric, 'reason': '核心指标无法识别'}
+    currency, op, target, suffix = target_match.groups()
+    if ((currency or suffix in ('usd', '美元', '$')) and not money
+            or (suffix == '%' and not percent)
+            or (percent and suffix != '%')
+            or (money and suffix in ('次', '个', '量'))):
+        return {**invalid, 'metric': metric, 'reason': '核心指标无法识别'}
+    rule.update(op=op, target=float(target))
+    # 阈值明确上下限时，其方向优先于指标缺省方向。
+    if op in ('>', '>=', '≥', '<', '<=', '≤'):
+        rule['higher_is_better'] = op in ('>', '>=', '≥')
+    return rule
+
+
+def rule_hit(value, rule):
+    """仅对明确定义的 KPI 判断，缺数据不输出未达标。"""
+    if value is None or not rule.get("usable") or rule.get('target') is None:
+        return None
+    target, op = rule["target"], rule["op"]
+    return {"<=": value <= target, "≤": value <= target, "<": value < target,
+            ">=": value >= target, "≥": value >= target, ">": value > target, "=": value == target, "==": value == target}[op]
+
+
+def is_first_period(biz: dict) -> bool:
+    start = str((biz or {}).get("prevPeriodStart") or "").strip()
+    end = str((biz or {}).get("prevPeriodEnd") or "").strip()
+    return not (start and end)
+
+
+def period_verdict(
+    *,
+    first_period: bool,
+    qoq_label: str,
+    kpi_usable: bool = False,
+    kpi_hit=None,
+) -> str:
+    """有可比上期时仅看趋势；没有上期时才按可识别阈值判断。"""
+    if not kpi_usable:
+        return '待观察'
+    if first_period:
+        return '待观察' if kpi_hit is None else ('有效' if kpi_hit else '无效')
+    if qoq_label == '无法对比':
+        return '待观察'
+    return '有效' if qoq_label == '变好' else '无效'
+
+
+def evaluate_learning(rule, current, previous, has_previous, sample_sufficient=True):
+    """各数据范围共用判定规则；有数据但指标缺失不冒充没有上期。"""
+    if not rule.get('usable'):
+        return '待观察', learning_text('待观察', rule)
+    if current is None or not sample_sufficient:
+        return '待观察', learning_text('待观察')
+    if has_previous:
+        trend, _ = qoq_axis(current, previous, rule['higher_is_better'])
+        verdict = period_verdict(first_period=False, qoq_label=trend, kpi_usable=True)
+        return verdict, learning_text(verdict)
+    hit = rule_hit(current, rule)
+    verdict = period_verdict(first_period=True, qoq_label='无法对比', kpi_usable=True, kpi_hit=hit)
+    note = None if hit is None else ('核心指标达标' if hit else '核心指标未达标')
+    return verdict, learning_text(verdict, note=note)
+
+
+def learning_text(verdict, rule=None, note=None):
+    """所有 learning 统一仅输出结论和业务说明，不附 KPI 原文或证据明细。"""
+    notes = {'有效': '策略有效', '待观察（预警）': '警惕，再观察一周',
+             '待观察（潜力）': '再给一周机会', '无效': '需关停',
+             '待观察': '数据不足，暂无法判断'}
+    if rule is not None and not rule.get('usable'):
+        return f'结论：待观察\n说明：{rule["reason"]}'
+    return f'结论：{verdict}\n说明：{note or notes[verdict]}'
+
+
+def amount_change(curr, prev):
+    """相对上期的金额环比；零基数不伪造百分比。"""
+    if prev == 0:
+        return '环比持平' if curr == 0 else '环比不可计算（上期为0）'
+    return f'环比 {(curr - prev) / prev * 100:+.2f}%'
+
+
+def is_ghost_enum(curr_share: float, prev_share: float) -> bool:
+    """两端占比都是 0 的残留枚举，不当关停动作。"""
+    return float(curr_share or 0) <= 0 and float(prev_share or 0) <= 0
+
+
+def region_bucket(name: str) -> str:
+    n = name or ""
+    if "非东南亚" in n:
+        return "other"
+    if "东南亚" in n:
+        return "sea"
+    return "other"
+
+
+def bid_adjust_stats(items: list) -> dict:
+    raise_n = lower_n = flat_n = 0
+    deltas: list[float] = []
+    details = []
+    for it in items:
+        fr = float(it.get("from") or 0)
+        to = float(it.get("to") or 0)
+        delta = to - fr
+        deltas.append(abs(delta))
+        if to > fr:
+            raise_n += 1
+            action = "上调"
+        elif to < fr:
+            lower_n += 1
+            action = "下调"
+        else:
+            flat_n += 1
+            action = "持平"
+        details.append({**it, "action": action, "delta": delta})
+    n = len(deltas)
+    if n == 0:
+        median = 0.0
+    else:
+        ordered = sorted(deltas)
+        mid = n // 2
+        median = ordered[mid] if n % 2 else (ordered[mid - 1] + ordered[mid]) / 2
+    list_all = len(items) < 10
+    return {
+        "raise_n": raise_n,
+        "lower_n": lower_n,
+        "flat_n": flat_n,
+        "median_abs": median,
+        "list_all": list_all,
+        "details": details if list_all else [],
+    }
+
+
+def budget_abs_share(
+    channel: str,
+    *,
+    prev_abs: float,
+    curr_abs: float,
+    prev_share: float,
+    curr_share: float,
+) -> str:
+    abs_delta = curr_abs - prev_abs
+    share_delta = curr_share - prev_share
+    flag = ""
+    if share_delta > 0.2 and abs_delta < -0.5:
+        flag = "；⚠️占比升但金额降"
+    elif share_delta < -0.2 and abs_delta > 0.5:
+        flag = "；⚠️占比降但金额升"
+    share = '' if round(prev_share, 1) == round(curr_share, 1) == 100 else f'；占比 {prev_share:.1f}% → {curr_share:.1f}%（{share_delta:+.1f}%）'
+    return f'{channel}：${prev_abs:,.0f} → ${curr_abs:,.0f}（{abs_delta:+,.0f}）；{amount_change(curr_abs, prev_abs)}{share}{flag}'
+
+
+_NAMING_SKIP = {
+    "ios",
+    "and",
+    "android",
+    "fb",
+    "tt",
+    "gg",
+    "bid",
+    "cap",
+    "all",
+    "copy",
+    "test",
+    "测试",
+    "自制",
+    "客供",
+    "英语",
+    "英文",
+    "中文",
+    "繁中",
+    "install",
+    "smart",
+}
+
+
+def naming_patterns(names: list[str], limit: int = 3) -> str:
+    """按名称中可见词段统计对象数，一对象同词只计一次，不臆测内部代码含义。"""
+    counts = {}
+    for name in names:
+        tokens = set()
+        clean = re.sub(r'\.(mp4|mov|jpg|jpeg|png)$', '', str(name or ''), flags=re.I)
+        for tok in re.split(r'[-_\s/|]+', clean):
+            tok = tok.strip()
+            if not tok or tok.isdigit() or len(tok) < 2 or len(tok) > 16:
+                continue
+            if tok.lower() in {'copy', 'test', '测试', 'ad', 'adgroup'} or re.fullmatch(r'[0-9a-fA-F]{8,}', tok):
+                continue
+            tokens.add(tok)
+        for tok in tokens:
+            counts[tok] = counts.get(tok, 0) + 1
+    top = sorted(counts, key=lambda k: (-counts[k], k))[:limit]
+    return '、'.join(f'{tok}（{counts[tok]}个）' for tok in top) if top else '未识别分类'
+
+
+def summarize_countries(countries: list[str]) -> tuple[str, list[str]]:
+    uniq = [c for c in dict.fromkeys(countries) if c]
+    if len(uniq) <= 50:
+        return f"共 {len(uniq)} 个国家", uniq
+    return f"国家超过 50 个，主页面只展示区域/大洲聚合（共 {len(uniq)} 个）", uniq
+
+
+def num(row: dict, key: str) -> float:
+    v = row.get(key)
+    if v in (None, "", "-"):
+        return 0.0
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def zh(raw: str) -> str:
+    s = (raw or "").strip()
+    if not s or s == "-":
+        return ""
+    return ENUM_ZH.get(s) or ENUM_ZH.get(s.upper()) or s
+
+
+def disp(row: dict, key: str) -> str:
+    for candidate in (f"display_{key}", key):
+        v = row.get(candidate)
+        if v not in (None, "", "-"):
+            return zh(str(v).strip())
+    return ""
+
+
+def short_label(raw: str, limit: int = 18) -> str:
+    """词包是一个维度值，只留前几个短词，禁止整包进 Excel。"""
+    s = (raw or "").strip()
+    if "," in s and len(s) > limit:
+        parts = [p.strip() for p in s.split(",") if p.strip()]
+        s = "、".join(parts[:3]) + ("…" if len(parts) > 3 else "")
+    if len(s) > 36:
+        s = s[:36] + "…"
+    return s
+
+
+def examples(items, n: int = 3) -> str:
+    return "、".join([short_label(x) for x in items if x][:n])
+
+
+def cpm(spend: float, imps: float):
+    if imps <= 0:
+        return None
+    return spend / imps * 1000
+
+
+def fmt_cpm(v) -> str:
+    return "-" if v is None else f"{v:.2f}"
+
+
+def hit_kpi(v, target: float = 5.0):
+    if v is None:
+        return None
+    return v <= target
+
+
+def qoq_axis(curr, prev, higher_is_better=False):
+    """成本类：下降为好。返回 (label, pct)。"""
+    if curr is None or prev is None or prev == 0:
+        return "无法对比", None
+    change = (curr - prev) / prev
+    # 包含 2% 边界；容忍浮点除法误差，不把恰好 2% 判成稳定。
+    if abs(change) < 0.02 and not math.isclose(abs(change), 0.02, rel_tol=1e-9, abs_tol=1e-12):
+        return "稳定", change
+    return ("变好" if (change > 0 if higher_is_better else change < 0) else "变差"), change
+
+
+def dual_verdict(is_hit, qoq_label: str) -> str:
+    """旧调用兼容入口也使用新趋势规则，不再保留四象限分支。"""
+    return period_verdict(first_period=False, qoq_label=qoq_label, kpi_usable=True, kpi_hit=is_hit)