达人素材数据统计（Influencer Stats）

投手场景下，把「素材底表」加工成「每个达人的整体消耗 / 整体成交金额」统计表。核心难点在于：达人名称藏在素材名称末尾，一条视频可挂多个达人，且剪辑输出时达人名常有错漏。

何时使用

用户给出含 素材名称 / 整体消耗 / 整体成交金额 列的 Excel，要求「按达人统计消耗和成交」
用户要求「合并相似达人」「把编辑打错的达人名归一」
用户质疑某达人数值对不上，需要核查提取/合并口径

素材名称命名规则（解析依据）

投手导出的达人素材底表中，「素材名称」字段承载了达人归属信息。本技能依赖其固定结构进行解析。

1. 字段结构

素材名称通常形如：

【亚瑟】刘宇-山东_11:15_伊-B2362-五一-亮泽CP-达人-贵妇-颜值-25+-谢咏-刘宇-4.22-种-乐采垠,立夏,懒懒美.mp4

用「-」分段后：

| 段 | 含义 | 示例 | |----|------|------| | 0 | 品牌/剪辑组 | 【亚瑟】刘宇 | | 1 | 地区 | 山东 | | 2 | 时段 | 11:15 | | 3 | 编号 | 伊-B2362 | | 4..n-3 | 活动/产品/卖点 | 五一/亮泽CP/达人/贵妇/颜值 | | n-2 | 剪辑/负责人 | 谢咏 | | n-1 | 主理人/达人主体 | 刘宇 | | n | 末尾达人段（核心） | 乐采垠,立夏,懒懒美 |

关键规则：达人名称在 最后一个「-」之后、视频后缀之前。

2. 多达人分隔符

,（逗号）：最常见，乐采垠,立夏,懒懒美
+（加号）：少数素材使用，达人A+达人B

两者都表示「一个视频出现多个达人，每个达人都按该条素材的完整数值统计」。

3. 视频后缀

素材名称以视频格式结尾，需去除：

.mp4（最常见）
.MP4（大写，偶发）
其它：.mov / .avi / .mkv

4. 边界 / 异常情况（务必处理）

| 现象 | 示例 | 处理 | |------|------|------| | 末尾是「机-」或「种-」后直接 .mp4 | ...-成钰敬-4.24-机-.mp4 | 无达人，跳过该素材（不计入任何达人） | | 末尾是「机」或「种」但前面还有达人 | ...-刘宇-4.22-种-乐采垠,立夏 | 正常取最后段 乐采垠,立夏 | | 含「(改)」「(改卡审)」「采买N」等标记 | 王门门(改卡审) / 乐采垠采买6 | 属编辑噪声，应在「合并相似名称」阶段归一 | | 英文名大小写 / 拼写变体 | Cenili vs Cecilia | 在合并阶段人工判断 |

5. 解析伪代码

def extract_talents(name):
    name = re.sub(r'\.(mp4|mov|avi|mkv|MP4)$', '', name.strip())
    parts = name.split('-')
    talent_part = parts[-1].strip()
    if not talent_part:        # 机-.mp4 类边界
        return []
    return [t.strip() for t in re.split(r'[,+]', talent_part) if t.strip()]

6. 多维展开（核心统计口径）

一条视频出现 N 个达人 → 在明细表中生成 N 行，每行都携带该条素材的完整消耗与成交金额。汇总时按达人 sum，因此：

单个达人在多条视频出现 → 累加那些视频各自的数值
一条视频多个达人 → 每个达人各得一次该视频全额

总消耗 / 总成交金额跨达人求和会大于底表实际总额（因为同一素材被计了 N 次），这是预期行为，符合「每个达人都能用对应的数值统计」的口径。

核心业务逻辑

1. 素材名称 → 达人列表

达人名在 最后一个「-」之后、视频后缀之前，用 , 和 + 分隔多个达人。字段结构、边界异常与解析伪代码见上方「素材名称命名规则」章节。

def extract_talents(name):
    name = re.sub(r'\.(mp4|mov|avi|mkv|MP4)$', '', name.strip())
    talent_part = name.split('-')[-1].strip()
    if not talent_part:          # 「机-.mp4」类无达人边界
        return []
    return [t.strip() for t in re.split(r'[,+]', talent_part) if t.strip()]

2. 多维展开（最重要口径）

一条视频含 N 个达人 → 明细生成 N 行，每行都带该素材的完整消耗/成交。因此：

一个达人出现在多条视频 → 累加那些视频各自的数值
一条视频多达人 → 每个达人各得一次全额
汇总后全达人总和会大于底表总额（同一素材被计 N 次），这是预期行为

3. 合并相似达人名

剪辑输出的达人名常有错漏（编号后缀、错别字、多余「(改)」「采买N」标记）。合并时 以素材数量最多的为准。合并映射放在 scripts/process.py 的 MERGE_MAP 中，按项目实际情况增删。

⚠️ 关键陷阱（踩坑必读）

陷阱一：合并映射的循环引用 → 死循环

若 A->B 且 B->A（初稿里 陈汤圆↔陈汤圆超 就中招），解析链式引用的 while changed 循环永不退出，脚本会卡死数分钟无输出。

✅ 解决：resolve_merge_map() 在展开链式引用时检测 target == k 立即抛错，并在写映射时避免成对互指。

# ❌ 错误写法（会死循环）
merge_map = {'陈汤圆': '陈汤圆超', '陈汤圆超': '陈汤圆'}
while changed:                       # 永远 changed=True
    for k, v in merge_map.items():
        if v in merge_map: merge_map[k] = merge_map[v]

# ✅ 正确：单向、无环
merge_map = {'陈汤圆': '陈汤圆超'}    # 只保留一个方向

陷阱二：openpyxl 逐行写大表极慢

明细常 5000+ 行。用 openpyxl 先 to_excel 再逐单元格 ws.write() 覆盖，双重写入 + 逐行格式会让进程卡 5 分钟以上被超时杀掉。

✅ 解决：直接用 pandas.ExcelWriter(engine='xlsxwriter') + to_excel，仅用 set_column 设列宽、freeze_panes 冻结首行，不做逐行格式。5189 行实测 0.2 秒完成。

陷阱三：末尾无达人的素材

部分素材以 机-.mp4 / 种-.mp4 结尾（机制/种草标记后无达人），最后段为空，应跳过，不要把它当成达人名。

陷阱四：用户质疑数值时的核查方法

当用户说「某达人我算只有 X，你怎么算成 Y」时：

拆出该达人所有「原始变体名」（如乐采垠 = 乐采垠 + 乐采垠亮 + 乐采垠采买6 + 乐采垠采买1）
逐变体从底表 sum 验证，定位差异来自哪个变体被漏算
常见原因：大额素材（如乐采垠采买6 有一条 ¥208,035 的素材）被用户的筛选漏掉

使用流程

# 1. 进入技能脚本目录
cd /root/.codebuddy/skills/influencer_stats/scripts

# 2. 运行（output 可省略，默认生成 <输入>_达人统计.xlsx）
python3 process.py <输入底表.xlsx> [输出.xlsx]

脚本自动完成：读取 → 提取达人 → 合并相似名 → 汇总 → 输出三 Sheet。

输出 Excel 结构

| Sheet | 内容 | 表头 | |-------|------|------| | 达人汇总 | 按整体消耗降序，含排名、素材数量、合计行 | 排名 / 达人名称 / 素材数量 / 整体消耗 / 整体成交金额 | | 达人明细 | 每条素材一行（多维展开后） | 达人名称 / 素材名称 / 整体消耗 / 整体成交金额 | | 合并说明 | 所有相似名合并记录 | 原始名称 / 合并后名称 |

用户自定义合并规则

编辑 scripts/process.py 顶部的 MERGE_MAP 字典：

MERGE_MAP = {
    '乐意鲤鲤2': '乐意鲤鲤',     # 编号后缀差异
    '花三三SPA': '花三三',       # 多余标记
    '浦儿姓浦': '蒲儿姓蒲',       # 错别字
    # ⚠️ 不要写互为反向的键！
}

若需确认某对是否真为同一人（如 吉吉护肤日记 vs 鳄鱼护肤日记），可先保留不合并，交付后让用户人工核对。

快速验证清单

[ ] 底表确有 素材名称 / 整体消耗 / 整体成交金额 三列
[ ] 末尾 机-/种- 无达人的素材被正确跳过（不出现空达人名行）
[ ] MERGE_MAP 无循环引用
[ ] 若用户质疑数值，已按「变体拆分 + 逐变体 sum」核查
[ ] 输出用 xlsxwriter，未被 openpyxl 逐行写拖垮性能