| name | databrain-opinion-metrics |
| version | 2.1.0 |
| description | 查询游戏舆情核心指标。支持声量、情绪分布、Brand Health、互动量、分渠道/分语种分布、Steam 评论评分、社区指标等。当用户询问游戏的"舆情"、"口碑"、"声量"、"情绪"、"评分"、"社媒表现"、"正负面评价"、"玩家讨论"、"Brand Health"时触发。 |
| author | databrain-team |
| metadata | {"openclaw":{"requires":{"env":"[Truncated]"}}} |
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"}]
}
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 |
补充资源
