databrain-opinion-metrics

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

快速开始

收到请求时，按以下流程执行：

1. 解析意图 → 确认游戏名称、时间范围、指标类型
2. 确认 game_id → 若未知，调用 python scripts/game_search.py "游戏名" 获取 unified_edition_id
3. 查询指标 → 从 references/ 找到对应 SQL 模板 → 替换 <game_id>、<start_date>、<end_date> → 调用 python scripts/query_metrics.py --message "用户原始问题" --sql "..." ... 执行
4. 解读输出 → 解析 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 在执行前做如下校验：

1. --game_id 格式：^[ue][0-9a-f]+$
2. 日期格式：^\d{4}-\d{2}-\d{2}$
3. SQL 不得含 DDL/DML 关键词（DROP、DELETE、INSERT、UPDATE、CREATE、ALTER 等）
4. DATABRAIN_HOST 只允许受信任域名
5. 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 未知时调用）