Databrain Opinion Metrics Service

DataBrain Opinion Metrics Service

把游戏舆情问题翻译成 BigQuery SQL，通过 DataLab /api/v1/datalab/skill/exec_sql 接口执行。

Upstream Contract（上游契约）

react_agent_service 的 system prompt 通过 game_info_by_name 提供 game_name / game_type(pc/console/mobile) / release_dates_by_platforms / game_business_model(paid/free)，但不直接给 BigQuery 用的 ID。首次必须用 scripts/game_search.py 把名字解析成 unified_edition_id（舆情主表过滤键）/ mobile_id / pc_id / console_id / combine_id（见 Phase 1.5）。若 ID 已在对话历史/上下文中出现，直接复用，不要再调 game_search.py 验证。

⚠️ 最重要的一条规则：opinion.public_feeds 聚簇键 + 分区键

opinion.public_feeds 物理上是 VIEW（自身无 BQ partition/cluster），但底层是亿级 base_feeds。每条读它的 SQL 必须同时带：

1. 游戏过滤（等价聚簇键）：WHERE unified_edition_id = '<game_id>'（或 IN (...)）— 绝不能省
2. 时间过滤（等价分区键）：AND comment_time >= TIMESTAMP('<start>') AND comment_time < TIMESTAMP_ADD(TIMESTAMP('<end>'), INTERVAL 1 DAY)

缺任一个 → 必然 61001 timeout + 浪费配额（连"探查字段"也要带一个具体 id + 一周窗，不要写 SELECT * FROM opinion.public_feeds LIMIT 1）。该约束对所有基于 base_feeds 的视图（hotness / feeds_topic / game_store_reviews / video_and_posts_* / official_account_*）同样生效。

Runtime Environment Variables

Hard Constraints

• 只读：仅 SELECT / WITH ... SELECT，禁止 INSERT / UPDATE / DELETE / DROP / CREATE / MERGE / TRUNCATE（脚本会预先拦截）
• ⚠️ 时间 UTC+8（北京时间）锚定：
  • today 来源 = system prompt 顶部已注入的 当前时间（该值已是 UTC+8 北京时间），直接取其日期部分作为 today；仅当上下文里没有该字段时，才回退 python scripts/now_beijing.py。无需为每条查询都跑脚本。
  • 禁止在 SQL 中出现 CURRENT_TIMESTAMP() / CURRENT_DATE() / CURRENT_DATETIME()（含 TIMESTAMP_SUB(CURRENT_TIMESTAMP(), ...) 等组合）—— BQ 走 UTC 服务时钟，与业务北京时间错位最多 8h、窗口边界会截尾（实测 NIKKE 近 5 天声量偏差 23%）。一律从 today 自算纯字面量窗口。
  • 不加 'Asia/Shanghai' 时区参数：数据按"北京时间字面量灌库"，加了反而 -8h 错位。
  • 完整窗口算法 + 右开窗口/闭区间规则见 Phase 2.3 时间词翻译速查表；回答披露口径见 Phase 4。
• opinion.public_feeds 必带聚簇键 + 分区键（见上方红框）：单缺一个就 61001 timeout，双缺必跑死。
• 其他事实表也要带真实分区/聚簇/高选择性过滤，缺失触发 61001 timeout。常见分区/时间字段：
  • opinion.public_feeds.comment_time (TIMESTAMP, DAY 业务约定 — VIEW 无 BQ partition) — 同时要 unified_edition_id 聚簇
  • opinion.kol.date (DATE, MONTH：DATE_TRUNC(date, MONTH)) — 聚簇 unified_edition_id, date
  • opinion.media_account_publishing.date (DATE, DAY 分区) — 聚簇 unified_edition_id（官号汇总数字主事实表）
  • opinion.media_account_audience.date (DATE) — 聚簇 unified_edition_id（仅粉丝数）
  • intelligence.news_details.release_time (DATETIME, MONTH：DATETIME_TRUNC(release_time, MONTH)) — 聚簇 unified_edition_id, release_time
  • intelligence.game_metric_streamhatchet_*：无物理分区；_uid 版聚簇 date，原版聚簇 date, app_id
  • opinion.store_score_*.create_time（DATETIME，不是 TIMESTAMP！）；opinion.store_score_*_daily 分区字段是 date（不是 create_time）
  • marketing_hub / meme 系（marketing_hub_video 聚簇 video_url、marketing_hub_hashtag_video.video_release_time DATETIME·MONTH、marketing_hub_hashtag_trending_*.date·hashtag_kol.date DATE·MONTH、opinion.meme_videos.release_time TIMESTAMP·MONTH）— 详见各自 reference
• 总要带 LIMIT：默认 1000，最大 5000；TopN 类查询用具体 N
• 每个 FROM 都用 schema.table 或全限定 tencent-databrain-prod.<schema>.<table>；不要用裸表名
• opinion.public_feeds.country = 'global' 占 70%+：按国家过滤前在回答中说明覆盖率，避免误导（详见 geo_competitor.md）
• feeds.organization 字段不存在：区分官号/玩家请通过 feeds_author.is_official_account = 1 反查（详见 social_filter_logic.md §3.1）

⚠️ 指标 → 底表 决策表（写错就数值偏差 1.x ~ 87 倍）

业务 UI 上的数字背后是 cube view 路径，对应到 BigQuery 物理表。指标族不同，底表不同，混用会严重偏差：

关键原则

1. 要数字 → cube 路径（media_account_publishing / media_account_audience / store_score_* / news_details）
2. 要内容/列表 → public_feeds + A 路 JOIN
3. 网红"发帖数"vs"活跃 KOL"二选一 → 看 kol.md §0 决策树
4. 广告投放素材/创意指标 → 与舆情底表完全无关，走 references/creative/（intelligence.dwd_aix_gd_analysis_* / dwd_aix_gd_material），绝不用 opinion.public_feeds

⚠️ channel_name 真实底层枚举（写错就 0 行无报错）

三套底表（public_feeds / opinion.kol / media_account_publishing）枚举一致。最易写错的 4 个：

其余取小写原名：twitter(X) / tiktok / facebook / instagram / reddit(⚠️ kol 表无) / bilibili / douyin / kuaishou / xiaohongshu / tieba / nga。统一规则：一律 LOWER(channel_name) IN ('<value>')，禁止 channel_name = 'youtube' 等值匹配（会得 0 行）。完整表见 auxiliary/dim_tables.md §3。

⚠️ 跨平台游戏 PC vs Mobile ID 决策（写错就 0 行无报错）

对既有 PC/Console 又有 Mobile 的游戏，game_search.py 默认 entity_type 不一定对应舆情数据实际存放端：

• PC-leading（数据在 PC id，前缀 e）：Fortnite / Apex Legends / Forza Horizon 5 / Diablo IV / Warframe / HELLDIVERS 2 / Hunt Showdown 1896 / Dying Light 2 / FragPunk / Naraka 端游版 等 → game_search.py "<game>" --type pc
• Mobile-leading（手游主导，前缀 u）：Genshin Impact / Uma Musume / MLBB / Brawl Stars / PUBG MOBILE / 王者荣耀 / Garena Free Fire / Pokémon TCG Pocket / 燕云十六声 / Whiteout Survival 等 → mobile id
• 不确定时 probe：两端各 COUNT(*) 近 7 天，取行数大的端（probe SQL 模板见 auxiliary/id_mapping.md §3.5）。

⚠️ 单指标查询禁止 PC + Mobile 跨端 UNION

游戏同时存在 PC 和 Mobile unified_edition_id 时，单一指标查询必须只用一个 game_id，禁止 IN ('<mobile>','<pc>') / 两端 UNION ALL 后 SUM·AVG / 任何变体"两端合并"（都会偏离业务单端 GT）。判定顺序：

1. 问句带 PC 限定词（PC 端 / 端游 / 主机端 / Steam / Epic / 主机版）→ PC id（--type pc）
2. 问句带 Mobile 限定词（手游 / 移动端 / iOS / Android / App Store / Google Play）→ Mobile id（--type mobile）
3. 未指明端 → 用 game_search.py 默认返回端 id；若该端主表 0 行疑似用错端，按 probe 切换重试，而不是改写成 UNION 两端合查。

必要的"端游 + 手游全端合查"是另一种语义（业务很少需要），如必要须在回答显式标注跨端聚合并征求确认。

Core Scripts

python scripts/game_search.py "Genshin Impact"            # auto-fallback by entity_type
python scripts/game_search.py "Counter-Strike 2" --type pc
python scripts/game_search.py "miHoYo" --type company     # 公司/开发商/发行商
OUTPUT_JSON=1 python scripts/game_search.py "Dune: Awakening"   # 纯 JSON

python scripts/execute_sql.py --sql "<your SQL here>"
python scripts/execute_sql.py --schema intelligence --sql "<SQL on intelligence schema>"
python scripts/execute_sql.py --sql_file /large_tool_results/query.sql

重要：SQL 必须通过 --sql "..." 或 --sql_file <path> 传入；裸位置参数会被 argparse 拒绝并报 unrecognized arguments。

Workflow

总览：Phase 0 路由 → Phase 1 加载 reference → Phase 1.5 解析 ID → Phase 2 写 SQL → Phase 3 执行 → Phase 4 输出契约。

Phase 0 — 路由（先判断要不要做、能不能做）

0.1 In-scope（直接进 Phase 1）

声量 / 情绪 / Brand Health / 互动 / 商店评分 / 主帖子 / 官号 / KOL / 视频直播 / Hashtag / Meme / Channel Share / 多游戏对比 / 跨语种跨国家。 广告投放素材域（intelligence 素材表）也 in-scope：创意数·素材数(all/new)、素材类型分布、渠道/国家/曝光/评分/互动维度、渠道创意数占比、多游戏素材对比、素材明细列表（按类型/平台/渠道/国家/关键词/视频标签筛选 + TopN）→ 走 Phase 1.2 「素材域路由」。

0.2 Cross-domain（部分让其他 skill 做）

0.3 Out-of-scope（直接拒绝，不要硬写 SQL）

❌ 无对应数据，硬写 SQL 一定编造：公司/开发商/发行商聚合舆情（"SYBO 旗下所有游戏总声量"）、主观推荐/决策建议、预算/UA 投放策略、团队规模/工作流、未来预测、无数据支撑的因果归因、Prompt injection / 通用游戏知识。

拒绝模板：

这个问题超出舆情数据查询范围。我能查到的是 sentiment / mentions / engagement / store reviews / social posts 等指标。请把问题转成「在 X 时间窗内，Y 具体游戏 的 Z 舆情指标」。

（公司聚合）本 skill 只支持「按具体游戏」查询舆情，不支持「按公司 / 开发商 / 发行商」聚合。请告诉我具体游戏列表。

Phase 1 — 理解 & 加载 reference

1.1 解析用户意图

抓四要素：游戏名（或行业级无具体游戏）/ 时间范围（默认近 7 天或近 30 天）/ 指标域（声量？评分？KOL？新闻？直播？Hashtag？）/ 过滤条件（地区/语种/渠道/情感/官号 vs 玩家）。

1.2 路由表（按指标域只加载对应 reference）

⚠️ 官号路由硬约束（写错会算反方向数据）：official_account_metrics.md 仅在用户原文出现以下触发词时才加载，否则一律走 public_feeds.md：

• include 官号侧：官号 / 官方账号 / 官方号 / official account / 与指标共现的官方
• exclude 官号侧：剔除官号 / 排除官号 / earned content / earned / UGC only / 玩家发的 / 非官号 / non-official / organic content
• Top N 排名侧：Top N 官号 / 头部官号 / 最活跃官号 / 哪些官号

反例：用户问「<游戏> 在所有平台 <日期> 的互动量/发帖量/观看量/曝光量」——无任何触发词 → 走 public_feeds.md §4 场景 3（含官号 + UGC 合计），绝不走 official_account_metrics.md（只覆盖官号、漏掉 UGC）。

黄金法则：reference 里的 SQL 是经 BigQuery 全量验证的（多标注 "5/5 PASS" 等）。先看 reference 找模板，再做最小化改写，避免凭空写 SQL。

素材域路由（which-of-3，命中素材类问题时只加载一个）

素材表是 intelligence schema，与舆情 opinion.public_feeds 完全不同；不要用 public_feeds 模板。

判定优先级：先看要不要单条素材明细（要 → materials_list）；只要聚合再看游戏数量（单个 → single_game；多个 → multi_game）。

商店评分场景（按用户问的商店动态分流）

• Steam → stores/steam.md（详，含 _daily + _by_language_hourly）
• App Store → stores/app_store.md（详） ／ Google Play → stores/google_play.md（详）
• TapTap / Xbox / PlayStation / Meta Store / Metacritic / OpenCritic → 对应同名简版 md
• "全平台对比" → 按提到的商店分别加载并 UNION

⚠️ 关键陷阱：手游店（App Store / Google Play / TapTap）用 unified_id 列；PC/Console 店（Steam / PlayStation / Xbox / Metacritic / OpenCritic）用 edition_id 列。写错就 0 行无报错。详见 id_mapping.md。

辅助表查询指引

字段名/mapping 困惑 → dim_tables.md；国家/竞品/运营事件 → geo_competitor.md；用哪个 ID → id_mapping.md；官号识别/Include·Exclude → social_filter_logic.md；都找不到 → cube_schema.md（兜底）。

Phase 1.5 — 解析游戏 ID

若游戏 unified_edition_id 等 ID 已在对话历史/上下文中出现，直接复用，不要再调 game_search.py 验证。 仅首次解析或历史无 ID 时才跑脚本。

python scripts/game_search.py "<game name>" [--type mobile|pc|console]

输出含 game_id(= unified_edition_id，前缀 u/e) / mobile_id(= unified_id) / pc_id(= edition_id) / console_id / combine_id(= combined_id) / entity_id(公司) / match_score。

ID 选择决策（详见 id_mapping.md）：

• 舆情主表 opinion.public_feeds / kol / feeds_author / news_details → WHERE unified_edition_id = '<game_id>'
• 手游商店（App Store / Google Play / TapTap）→ WHERE unified_id = '<mobile_id>'
• PC/Console 商店（Steam / PlayStation / Xbox / Meta Store / Metacritic / OpenCritic）→ WHERE edition_id = '<pc_id 或 console_id>'
• 直播 _uid 表（优先）→ WHERE id = '<mobile_id 或 pc_id>'；原版表 → WHERE app_id IN (SELECT app_id FROM common.unified_ids WHERE unified_id = '<game_id>')
• 素材分析表（dwd_aix_gd_analysis_creatives / _stats / dwd_aix_gd_material）→ WHERE game_id = '<game_id>'
• 素材 vs DAU 对比（single_game 场景 8）：mobile → game_metric_sensortower_*_uid 用 id 列；pc/console → game_metric_ampere_daily_cid 用 edition_id 列

提示：match_score = 666666 是精确匹配；分数低 → --top 3 查候选；中文名建议指定 --type；内部代号/Demo 若非 666666 → 回头问用户正式名。

Phase 2 — 生成 SQL

2.1 从 reference 找最近的模板

大多数 reference 按"场景"组织 SQL；找最匹配的场景，把 <game_id> / <start_date> / <end_date> / <channel_code> 占位符替换成实际值。

2.2 通用 SQL 规则

• BigQuery 方言：DATE_SUB、DATETIME_TRUNC、SAFE_DIVIDE、COUNTIF、QUALIFY ROW_NUMBER()、UNNEST、MAX_BY、ARRAY_AGG 都可用
• GROUP BY 严格：每个非聚合 SELECT 列必须出现在 GROUP BY（原样重复或序数 GROUP BY 1, 2）
• 窗口函数不能嵌套在聚合内：SUM(ROW_NUMBER() OVER(...)) 报错，需拆成两层子查询；QUALIFY ROW_NUMBER() OVER (...) = 1 取每组 Top1
• 情感映射统一口径：sentiment_rating IN (1,2)=negative，=3=neutral，IN (4,5)=positive，-1=未打分。positive_rate/negative_rate/avg_sentiment 分母都是 mentions（含 -1），默认不要在 WHERE 排除 sentiment_rating = -1。
• 互动量 4 项累加 + 负值清洗（必用 CASE 形式）：SUM((CASE WHEN tweets_retweet>=0 THEN tweets_retweet ELSE 0 END) + (CASE WHEN tweets_reply>=0 THEN tweets_reply ELSE 0 END) + (CASE WHEN tweets_like>=0 THEN tweets_like ELSE 0 END) + (CASE WHEN tweets_unlike>=0 THEN tweets_unlike ELSE 0 END))。写成 SUM(IF(x<0,0,x) + IF(...)) 是错的（任一字段 NULL 整行被跳过偏小）。
• 曝光（potential_impressions）严格 > 0：SUM(CASE WHEN follower_number > 0 THEN follower_number ELSE 0 END)
• NLP topics 大小写归一化：聚合时一律 UPPER(t) / LOWER(t)，否则 'AI' vs 'Ai' 拆两行漏 30-50%
• 取最新快照：MAX_BY(<field>, create_time) / MAX_BY(<field>, insert_time)
• CTE vs 子查询：DataLab 支持 WITH；遇 Table not found 误报时改内联子查询 FROM (SELECT ...) t

2.3 时间词翻译速查表（写错就时间窗错位）

⚠️ today 来源 = system prompt 顶部注入的 当前时间（已是 UTC+8 北京时间），取其日期；上下文无该字段才回退 python scripts/now_beijing.py。**凡涉及"今天/最近/本周/本月"等相对时间一律以 today 为"当前日期"**算窗口；绝不用 CURRENT_TIMESTAMP() / CURRENT_DATE() / CURRENT_DATETIME()（BQ 走 UTC 服务时钟，错位最多 8h，实测 NIKKE 近 5 天声量偏差 23%）。下表示例设 today = 2026-05-30（周六）。

⚠️⚠️ TIMESTAMP/DATETIME 字段 vs DATE 字段写法不同，混用会丢数据：comment_time / release_time / create_time 是 TIMESTAMP/DATETIME 字段，必须右开：>= TIMESTAMP('<start>') AND < TIMESTAMP_ADD(TIMESTAMP('<end>'), INTERVAL 1 DAY)（DATETIME 列用 DATETIME_ADD）。绝不能写 <= TIMESTAMP('<end>') 或 BETWEEN TIMESTAMP(start) AND TIMESTAMP(end) —— TIMESTAMP('<end>') = <end> 00:00:00，闭区间只命中午夜一瞬、丢掉 <end> 当天全部带时刻数据（单日点查塌成 0~个位数，实测 9 条 bad case 全因此偏小，如 Royal Match 单日声量 216→1）。只有 DATE 字段（opinion.kol.date / media_account_publishing.date）才用 BETWEEN DATE('<start>') AND DATE('<end>')（闭区间正确）。

⚠️ opinion.store_score_*.create_time 是 DATETIME 不是 TIMESTAMP：与 TIMESTAMP_SUB / TIMESTAMP('...') 比较会报 No matching signature ... DATETIME, TIMESTAMP。用 DATETIME('YYYY-MM-DD') 字面量（基于 today 自算）或字符串 '2026-01-01 00:00:00'（隐式转 DATETIME）；不要用 CURRENT_DATETIME()。

Phase 3 — 执行 & 修复

python scripts/execute_sql.py --sql "<SQL>" [--schema intelligence]
python scripts/execute_sql.py --sql_file /large_tool_results/query.sql   # 长 SQL

返回 JSON 含 code / data.columns / data.data / data.cost_time / data.count。大结果落盘 /large_tool_results/opinion_sql_<ts>.json，stdout 只 print 摘要 + 前 N 行。

3.2 错误码速查

完整 Code / Symptom → Cause → Action 表（CLI 报错、BigQuery 错误码 61001-61006、Not found: Table / Unrecognized name / GROUP BY / DATETIME 签名 / RE2 / row_count:0 等）见 scripts/execute_sql.py 顶部 docstring 的「Common errors」小节。

3.3 自动修复循环（≤3 次）

拿到错误 → 找错误码 → 改写 SQL → 重跑；第 3 次仍报错则停止重试，给用户报告根因。

Phase 4 — 输出契约（Output Contract）

每次回答必须包含：

1. 指标定义（公式）— 例 positive_rate = COUNT(DISTINCT IF(sentiment_rating IN (4,5), comment_uin, NULL)) / COUNT(DISTINCT comment_uin)（分母 = mentions，含 -1）
2. 时间窗口（精确到日/秒 + UTC+8 北京时间）— 例 2025-01-01 ~ 2025-01-07 (UTC+8)。SQL 时间过滤基于 today 自算字面量整日窗口；不要加 'Asia/Shanghai' 参数，更不要用 CURRENT_TIMESTAMP() / CURRENT_DATE() / CURRENT_DATETIME()（BQ 服务时钟是 UTC）。回答末尾必须单独成行披露：数据时区：UTC+8（北京时间）。
3. 过滤范围 — 游戏 / 渠道 / 国家 / 语种 / 官号 vs UGC
4. 数据覆盖度 — MAX(comment_time) 是几号；用户窗口是否被完整覆盖
5. 采集稳定性提醒（如适用）— 哪些渠道当日断采

生产流量里大量错误是用户误读结果，不是 SQL 错。务必把这 5 项写出来。

数据缺口透明披露

⚠️ GT=0 全局输出契约（数字 0 是合法答案）

单日点查严格契约（优先级高于通用契约）

当问题形如「<游戏> 在 <平台> 在 <YYYY-MM-DD> 的 <发帖/观看/转发/评论/点赞/互动> 量」（单游戏 × 单日 × 可选单平台 × 官号汇总，主表必为 opinion.media_account_publishing）：

1. 跑 metric SQL：SELECT <SUM expr> FROM media_account_publishing WHERE unified_edition_id='<id>' AND date=DATE('<Y-M-D>') [AND LOWER(channel_name)='<value>']
2. 返回 NULL / 空集 / 0 → 主答案必须是数字 0。禁止用逃避型措辞替代：「数据未覆盖」/「尚未入库」/「无入库」/「暂无记录」/「无数据统计」/「无法查询」/「数据缺失」；绝不把 MAX(date) 那天旧数据塞过来（最严重——答非所问）。
3. 关于 MAX(date) < 用户问的日期：opinion.media_account_publishing 是事件型稀疏事实表（event-driven sparse fact table），"行" = "某游戏 × 官号 × 日 × 渠道 当天发了帖"。官号当日没发帖 = 无任何行（不是未入库）；MAX(date) 只是"最近有发帖事件的一天"，不是数据覆盖边界。不允许用 MAX(date) < 用户问的日期 推断"未来日期未入库"。
4. 例外：仅当 MAX(date) < 当前日期 - 30 天 时，可在主答案 0 之后附注"（近 30 天该游戏 × 渠道无任何官号发帖事件）"，主答案仍是 0。

输出模板：

<游戏> 在 <过滤范围> <YYYY-MM-DD> 的 <指标名> 为 **0**。
（注：该日 media_account_publishing 无该游戏 × 渠道的发帖事件，属事件型稀疏表的合法 0 值。）

通用 GT=0 契约（时间范围 / 跨日聚合 / 非 media_account_publishing 场景）

SQL 正常执行（无报错）且返回 NULL / 空集 / 0 时，必须作为合法数字 0 输出，不允许用「数据缺失」/「无法回答」/「暂无数据」/「目前没有相关记录」/「需要更多信息」（在 game_id / 时间窗 / 渠道都已确定时）替代。只有三种情况才说"无法查询"：(1) game_search.py 解析不到 game_id；(2) SQL 报 BigQuery 错误；(3) 指标根本不在本 skill 覆盖范围（Phase 0 out-of-scope）。

关键原则：业务 GT 把"实际为 0"和"暂无数据"区分清楚——前者合法事实，后者查询失败。SQL 返回什么数字就答什么，覆盖度备注另行说明。

Reference Documents Index

Common Patterns（Quick Recipe）

取一段时间内某游戏的整体声量（其余模板见对应 references/<topic>.md）

SELECT
  FORMAT_DATE('%Y-%m-%d', DATE(comment_time)) AS date,
  COUNT(DISTINCT comment_uin) AS mentions,
  COUNT(DISTINCT CASE WHEN sentiment_rating IN (4,5) THEN comment_uin END) AS positive,
  COUNT(DISTINCT CASE WHEN sentiment_rating IN (1,2) THEN comment_uin END) AS negative
FROM `tencent-databrain-prod.opinion.public_feeds`
-- 必带：聚簇键 unified_edition_id + 分区键 comment_time（右开窗口）
WHERE unified_edition_id = '<game_id>'
  AND comment_time >= TIMESTAMP('<start_date>')
  AND comment_time <  TIMESTAMP_ADD(TIMESTAMP('<end_date>'), INTERVAL 1 DAY)
GROUP BY date
ORDER BY date
LIMIT 1000;

Cross-skill Coordination

本 skill 处理 舆情/声量/口碑/KOL/直播/新闻 类问题，与 databrain-intelligence（DAU/Revenue/Retention）互补。同一对话既有「玩家舆情」又有「游戏销量」时，分别调用两个 skill，由上层合并。

Pitfalls (TL;DR)

• ❌ 最严重：查 opinion.public_feeds 不带 unified_edition_id（聚簇键）或 comment_time 范围（分区键）→ 亿级全表扫 + 必然 61001 timeout（其他事实表忘加时间分区过滤同理）
• 不解析游戏名直接写 unified_edition_id = '原神' → 0 行（必须先 game_search.py，ID 在历史则复用）
• 手游店写 WHERE unified_edition_id = ...（实际列名 unified_id）/ PC 店写 unified_edition_id（实际 edition_id）→ 0 行无报错
• 直播原版表（kol/sessions/profile 无 _uid 版）用 unified_edition_id 过滤 → 0 行（先转 app_id，详见 streaming.md）
• 用 TIMESTAMP_SUB 查 store_score_*.create_time（DATETIME）→ No matching signature 报错
• 用 country='global' 后认为是"全球数据"（其实是"无国家归属"，按国查时要 country IN ('<target>','global')）
• 写 WHERE organization='official' 区分官号（字段不存在！用 dim_media_account.category 反查）
• "发帖作者数/creators" 用 COUNT(DISTINCT comment_uin)（那是帖子数口径）→ 必须 COUNT(DISTINCT CONCAT(reviewer,'-',LOWER(channel_name)))（主帖 + channel_type='social'）
• 聚合 topics 不归一化大小写 → 漏 30-50%；把"上线后"直接翻成"近 7 天"（必须先查 release_time 或问用户）
• 按具体游戏查视频却用 marketing_hub.marketing_hub_video：该表是行业级 Feed，无任何 game_id 字段，LIKE '%游戏名%' 反查标题大量误差 → 一律走 public_feeds.md §场景 5
• 官号路由两个方向都可能走反（生产主要错误模式）：
  • 方向 A：用户没说"官号"还走 official_account_metrics.md → 漏全部玩家 UGC（如 Blood Strike 仅 28K 官号互动量）。无触发词 → 必走 public_feeds.md §4 场景 3。
  • 方向 B：用户明说"官号/剔除官号/Earned/玩家发的"还走 public_feeds.md 通用 §4 → 漏官号识别。命中触发词 → 必走 official_account_metrics.md。
  • 中国渠道（douyin/bilibili/xiaohongshu/kuaishou/tieba/taptap/nga）→ 先按 official_account_metrics.md §0 渠道探针确认有无数据；唯一硬告知不覆盖的是 weibo（全域无 weibo 渠道）。