infometa databrain-opinion-metrics
快速开始
收到请求时，按以下流程执行：
- 解析意图 → 确认游戏名称、时间范围、指标类型
- 确认 game_id → 若未知，调用
python scripts/game_search.py "游戏名"获取unified_edition_id - 查询指标 → 从
references/找到对应 SQL 模板 → 替换<game_id>、<start_date>、<end_date>→ 调用python scripts/query_metrics.py --message "用户原始问题" --sql "..." ...执行 - 解读输出 → 解析 JSON
rows字段，结合指标口径说明呈现结果
Configuration
环境变量
| 变量名 | 必填 | 默认值 | 说明 |
|---|---|---|---|
DATABRAIN_TOKEN |
是 | — | 认证 token 原始值（不含 Bearer 前缀），脚本会自动拼接；不要写死在代码中 |
DATABRAIN_HOST |
否 | 自动 fallback | API 主机地址；不设置时自动按优先级尝试 databrain.intlgame.com → databrain.woa.com → databrain-global.intlgame.com，首个成功的会被缓存复用。显式设置后仅使用该地址，仅允许受信任域名（databrain.woa.com、databrain.intlgame.com、databrain-*.intlgame.com） |
DATABRAIN_DISPLAY_HOST |
是 | — | 系统链接展示域名，由平台注入；Agent 构造系统链接时使用（{DATABRAIN_DISPLAY_HOST}/v2/agent/chat?sessionId=...），脚本不直接读取 |
Token 自动从环境变量读取。若为空，引导用户前往 https://databrain.woa.com/v2/user-center/personal-tokens-center 获取 Databrain Token，设置 DATABRAIN_TOKEN 环境变量即可，不要加 Bearer 前缀。外网用户可使用 https://databrain-global.intlgame.com/v2/user-center/personal-tokens-center。
数据源
所有可查指标均通过 POST /api/v1/opinion_pc/global/query（BigQuery Global Query API）执行，返回 CSV。
| 数据表 | 用途 | 可查性 |
|---|---|---|
tencent-databrain-prod.opinion.feeds |
声量、情绪、互动、评论 | ✅ 可查 |
store_score_* 系列 |
GP/AS/Steam 商店评分 | ❌ API 无权限，需 BQ 直连 |
t_opinion_news |
新闻稿指标 | ❌ BQ 路径待确认 |
查询流程
Step 1：确认 game_id
python scripts/game_search.py "游戏名"
输出示例：
{
"games": [{"game_id": "e76337e746e1f95fdbf7e23c26010e448", "entity_name": "Dune: Awakening"}]
}
e...= PC 游戏，u...= 移动游戏
Step 2：执行查询
从 references 找到 SQL 模板，替换占位符后传入：
python scripts/query_metrics.py \
--message "用户原始问题" \
--sql "SELECT ..." \
--game_id e76337e746e1f95fdbf7e23c26010e448 \
--start_date 2026-03-24 \
--end_date 2026-03-30
或从文件读取 SQL：
python scripts/query_metrics.py \
--sql_file /tmp/query.sql \
--game_id e76337e746e1f95fdbf7e23c26010e448 \
--date 2026-03-30
Step 3：解读输出
{
"game_id": "e76337e746e1f95fdbf7e23c26010e448",
"start_date": "2026-03-24",
"end_date": "2026-03-30",
"rows": [{"date": "2026-03-24", "volume": "1127"}, ...],
"row_count": 7
}
如需 CSV 格式，追加 --format csv。
新增指标（无需改代码）
在对应数据表的 reference 文件末尾追加 SQL 模板即可，无需修改脚本：
opinion.feeds相关 → 追加到references/feeds_templates.md- 新增数据表 → 新建
references/<table_name>_templates.md
安全说明
query_metrics.py 在执行前做如下校验：
--game_id格式：^[ue][0-9a-f]+$- 日期格式：
^\d{4}-\d{2}-\d{2}$ - SQL 不得含 DDL/DML 关键词（
DROP、DELETE、INSERT、UPDATE、CREATE、ALTER等） DATABRAIN_HOST只允许受信任域名- Token 仅通过环境变量注入，不接受命令行传入
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
DATABRAIN_TOKEN not set |
未注入 token | 通过服务端环境变量注入 |
DATABRAIN_HOST 不是受信任域名 |
host 不在白名单 | 使用 databrain.*.woa.com 或 databrain*.intlgame.com |
Invalid game_id |
ID 格式不符 | 用 game_search.py 重新查询 |
SQL contains forbidden keyword |
SQL 含 DDL/DML | 检查模板 SQL，只允许 SELECT |
row_count: 0 |
该游戏在该时间范围内无数据 | 确认游戏平台和日期范围 |
ModuleNotFoundError: httpx |
未安装依赖 | pip install httpx |
补充资源
- 声量/情绪/互动基础 SQL → references/feeds_templates.md（Step 2 构造查询时读取；包含表 Schema、关键字段说明）
- Mentions & Sentiment 全量指标口径 → references/mentions_sentiment.md（需要 DoD、Brand Health、情感分等复杂指标时读取）
- 社区指标（曝光/发帖/创作者/观看/互动）→ references/community.md（查询 Community 模块指标时读取；注意官号/玩家内容字段待确认）
- Game Store 评论评分 → references/game_store.md（查询 Steam 评论时读取；其他平台评分暂不可查）
- PR & News 指标 → references/pr_news.md（❌ BQ 表名待确认，当前不可执行）
- Social 过滤逻辑（官号/关键词/账号分类）→ references/social_filter_logic.md（需要按账号类型过滤时读取）
- Hashtag 趋势查询 → references/hashtag_trending.md（⚠️ BQ 表路径待确认）
- Meme 热梗查询 → references/meme.md（⚠️ 使用 tencent-databrain 非 prod 项目，待确认）
- 商店评分 SQL 口径 → references/store_score_templates.md（❌ API 无权限，需 BQ 直连）
- 查询脚本 → scripts/query_metrics.py（Step 3 执行 SQL 时调用）
- 游戏 ID 查询脚本 → scripts/game_search.py（game_id 未知时调用）