微信小店达人筛选

0. 术语与口径（全文统一）

「数据缺口」与「待核实」不可互换：前者是平台不给，后者是给了但跨阈值。用错会分别导致"漏采"和"误报命中"。

1. 目标

把"要找什么样的达人"转成一份可执行、可复核、来源可追溯的候选名单。核心原则：只输出有来源的数据；没有来源的写"待补充/待核实"并给出获取方式，绝不臆造。

两条能力路径，判定规则与术语完全一致：

2. 触发条件

使用本技能（出现任一）：

• 品牌方要在视频号找达播/分销达人，需按商业条件（销售额、场均观看、场次、客单价、粉丝量、类目）筛选
• 需要把"直播销售额 1万-10万、场均观看 1000-5000、场次≥20"这类硬条件落成真实名单
• 手上已有一批达人数据（后台截图、数据平台导出、招商表），需清洗成候选名单
• 需要评估达人与本品的匹配度、给出打分与风险提示

触发词：视频号选人 / 找达人 / 达人广场 / 主播筛选 / 带货主播 / 匹配度 / 达人名单 / 微信小店优选联盟。

不触发：抖音/抖店达人筛选 → 用 douyin-ecommerce-ops；只要人群画像分析不要名单 → 不属本技能。

3. 输入

3.1 前置条件（实时取数路径）

不满足则走本地判定路径，不得假装能实时取数。

3.2 条件参数

条件以 JSON 传入（模板 assets/conditions.example.json）。以 _ 开头的键视为注释。

strict_boundary 会显著改变结果量：同批数据实测宽松 45 条 / 严格 0 条。默认 false（不漏）；要求"严格满足"才设 true，并须在报告中声明。

4. 输出

4.1 实时路径（pipeline.py judge）固定 13 列

主播名称, 所属类目, 命中条件与数值, 未满足/待核实条件, 带货销售总额,
场均成交额, 场均观看人数, 总带货场次, 粉丝数, 带货评分, 客单价, 有联系方式, 平台认证

列顺序固定，定义见 references/output_schema.md。标准样例：assets/sample_output.csv、assets/sample_report.md。

4.2 本地路径（screen.py）

默认 20 列（含打分、命中理由、数据缺口）；--format wechat 输出与 4.1 完全一致的 13 列。

4.3 剔除统计 Markdown

按「价格不符 / 联系方式缺失 / 类目不符 / 其他」给数量与占比，并单独声明待核实条数。

列结构不得随意增删改；确需扩展时用 judge --columns 显式指定，并在回复中说明。

5. 执行流程

5.1 快速上手（3 分钟，无需浏览器）

cd ~/.workbuddy/skills/wechat-store-talent-screening
python scripts/pipeline.py plan  --cond assets/conditions.example.json --backend assets/backend_filters.example.json
python scripts/pipeline.py judge --cond assets/conditions.example.json --pool assets/sample_pool.json --detail assets/sample_detail.json --out out/名单.csv

out/名单.csv 应与 assets/sample_output.csv 一致（13 列）；剔除统计与 assets/sample_report.md 一致。

5.2 实时取数（六步，顺序不可颠倒）

第 1 步 明确选人约束（缺则问，不猜）
集齐：产品品类与价格带、目标人群、投放目标（铺量/打爆/测品）、硬性门槛、可接受佣金与坑位费。产品资料是唯一依据。

第 2 步 拿后台真实档位（必做，不可跳过）

python scripts/pipeline.py probe --out out/backend.json          # 18 个下拉筛选器：名称+档位

probe 只覆盖下拉型筛选器。类目在复选框区、画像在复合面板，需另读（见 §6.2）。不得凭记忆假设档位名称——档位会变，写死会导致勾选失败或筛出空池。

第 3 步 生成执行计划（不联网）

python scripts/pipeline.py plan --cond cond.json --backend out/backend.json --out out/_plan.json

plan 自动完成三件事，必须先看告警再决定是否继续：
- 条件 → 后台筛选器映射，按区间重叠勾选（宁可多选，保证不漏）
- 标出后台无筛选器、必须走详情页的条件（场均成交额、总带货场次）
- 冲突检测：如 场均成交额下限 × 场次下限 > 总额上限 直接告警"该口径下无解"

出现 [WARN] …无任何档位与…重叠 或「条件冲突」→ 先与用户确认放宽口径，不要硬跑。

第 4 步 抓取候选池

python scripts/pipeline.py fetch --plan out/_plan.json --outdir out/ --pages-per-round 6 --max-rounds 50

fetch 先清空后台已有勾选、再按 plan 勾选，然后分页抓取。禁止自行改写成长时间静默的循环。

第 5 步 抓详情页带货数据

python scripts/pipeline.py detail --pool out/pool.json --out out/detail.json

详情页是平台唯一提供「场均成交额档位 / 场均观看档位（含 1000 分界）/ 精确总带货场次」的地方。接口有签名校验，直连会 403，只能驱动真实浏览器触发。

第 6 步 判定与出表

python scripts/pipeline.py judge --cond cond.json --pool out/pool.json \
       --detail out/detail.json --out 名单.csv --report 剔除统计.md

三态：hit（档位完全落入目标区间）/ uncertain（部分重叠）/ out（无交集或缺失）。结果表输出 hit + uncertain，uncertain 必须在报告与回复中标注待人工核实。

第 7 步 结论与放宽建议
- 合格数 0 或过少 → 必须归因：数据不可得 / 平台只给档位 / 门槛数学互斥 / 类目无人
- 放宽顺序：先场次与观看 → 再客单价 → 最后才放宽品类契合
- 明确下一步：向谁要什么数据、在哪个平台筛、何时回填

5.3 一条命令串联

python scripts/pipeline.py run --cond cond.json --backend out/backend.json --outdir out/ --out out/名单.csv

run = plan→fetch→detail→judge。probe 仍建议先单独跑一次确认档位。

5.4 仅对已有数据做本地判定（不联网）

python scripts/screen.py --input 主播数据.csv \
  --nl "直播销售额1万-10万，场均观看1000-5000，带货场次20场以上" \
  --csv 名单.csv --format wechat

6. 约束（硬规则）

6.1 判定口径

• 档位完全落入目标区间 → hit；部分重叠 → uncertain；无交集或缺失 → out
• 不取区间中点做判定（中点只用于排序打分）；展示一律用平台原文档位
• 结果表只含 hit + uncertain；out 只进剔除统计

6.2 平台能力边界（实测，写死不要再试）

6.3 身份与去重

6.4 采集可靠性（实时路径验收）

硬性要求：停止条件以「页面无下一页」为准；连续零新增需先排除"页面仍在加载"，确认加载完成后再计停滞；限流/403 退避后续抓同一页，不得直接结束。

6.5 跨批次合并

按 finderUsername 合并去重 → 重算漏斗 → 对合并后 hit + uncertain 全集重做详情 → 声明各批时间与覆盖率。不得沿用单批漏斗结论。

7. 边界与异常

完整清单见 references/edge_cases.md。必须处理的六类：

8. 反模式

• 用"某某类达人""画像方向"充数当名单——那是挖掘方向，不能计入清单行
• 把"待核实"写成具体数字；把"待补充"占位符当有效联系方式
• 缺数据时直接说"平台没有这个数据"，而没走详情页确认
• 按常识写类目名（如"滋补保健"）而不读平台真实取值
• 同一维度全选档位，然后得出"0 条 = 该类目没人"
• 把品牌自播号当达播达人推荐（榜单前排常是品牌自播店）
• 只给评分不给依据，或依据是"感觉不错""粉丝粘性高"
• 绕过 probe / plan 直接抓取，导致档位写错或条件冲突到最后才发现
• 用昵称做唯一键，导致重名达人被静默合并

9. 参考文件

9.1 改动后必跑自测

任何改动（脚本、资产、文档约束）后执行：

python scripts/selftest.py        # 60 项断言，约 25 秒

退出码 0 = 通过，非 0 = 有失败并逐条列出。自测覆盖：语法/注入模板/frontmatter/行尾、
资产一致性、规则引擎（含档位文本不得崩溃）、plan/judge 黄金样例 13 列与名单一致、
池子合并主键与重名不同号、以及采集脚本关键约束不得回退（主键 finderUsername、
STALE_LIMIT、jsonl 日志、total 覆盖率）。

自测只保证链路与口径不变；业务结论仍需按 §5 复核。

10. 版本变更

v1.1.1

新增：可复现的自动化自测（scripts/selftest.py，60 项断言，零依赖）
- 覆盖 A 静态完整性 / B 资产一致性 / C 规则引擎 / D plan+judge 端到端 / E 池子合并 / F 采集脚本约束防回退。
- 「采集脚本约束」一组用源码断言锁死关键行为（finderUsername 主键、STALE_LIMIT、jsonl 日志、total 覆盖率），防止后续改动悄悄退回昵称去重或去掉日志。

修复：规则引擎与合并工具 2 个真缺陷（均由自测发现）
- 档位文本（1000-5000、1万-10万、5万以上）传给数值条件时抛 TypeError: '>' not supported between 'str' and 'float' → 归一化后的记录带 _low/_high 不会踩，但直接拿原始记录判定会整批中断。已用 parse_range 还原为数值或区间，无法解析判待核实。
- pool_merge.score() 把合并时写入的 sources 字段也算进"完整度"，导致先到的记录永远胜出、后到的更完整记录无法替换（择优失效）。已排除 sources。

文档
- references/platform_fields.md 粉丝量一行补齐实测口径：4 档全选 → 0 条（全选无效，不是"无人"）、最小档已到 1 万无法筛「≥1000」。

v1.1.0

修正与统一
- 补齐 author 字段（此前为占位符文案，会导致上架信息不完整），现为 EDY。
- 结构改为六段式（术语 / 目标 / 触发 / 输入 / 输出 / 流程 / 约束 / 边界），与 douyin-ecommerce-ops v1.4.0 同构，便于两平台交叉维护。
- 新增第 0 节术语表，统一 命中/待核实/淘汰（代码键 hit/uncertain/out），明确「数据缺口」与「待核实」的区别。
- 「何时使用」与「反模式」中的重复条目合并；删除含糊表述（"不要假装能实时取数"改为可判定的前置条件表）。

新增实测约束（§6.2）
- 粉丝量 4 档全选会导致接口返回 0 条——判定为"全选无效"，不得解读为"该类目无人"。
- 粉丝量最小档为「小于1万」，无法筛 ≥1000，只能抓后本地判并标 uncertain。
- 类目在复选框区、不在 probe 覆盖的 18 个下拉内；平台真实类目名为「食品饮料」「保健食品/膳食营养补充食品」「母婴」。
- 粉丝年龄/画像/性别只作筛选参数、不进入返回记录，无法输出逐条分布；画像档位无"宝妈"标签。
- 详情页独有字段（liveAvgPayGmv、精确 liveCnt）列表层取不到。

采信与合并
- 去重稳定键由 nickname 改为 finderUsername > talentAppid > nickname（nickname 单独作键会静默丢人）。
- 新增 §6.4 采集可靠性 6 项验收与 §6.5 跨批合并流程。
- 新增 references/collection_reliability.md。

v1.0.2

• 实时取数 + 本地判定双路径；--format wechat 对齐 13 列输出。
• strict_boundary 引入（宽松 45 条 / 严格 0 条的实测差异）。