infometa databrain-opinion-summary
快速开始
- 解析意图 → 确认游戏名称、时间范围、报告语言（中/英）、可选渠道/语种过滤、摘要类型（默认
basic，约 1–5 分钟；用户明确要量化数据时用advanced，可能长达 30 分钟，启动前须向用户说明） - 确认 game_id 与平台 → 若未知，在本 skill 下执行 scripts/game_search.py 查询
game_id（即unified_edition_id）game_id以u开头 →--entity_type mobilee开头 → 一般为--entity_type pc；若为主机版且与 PC 版区分配置，再选console
- 创建并拉取报告 → 执行
scripts/get_opinion_summary.py（POST .../create_summary→ 轮询.../get_summary至task_status == success）；建议传入--message用户原问题 以便 operationLog 打点。create_summary必须带date_type（脚本默认day，适用于「单日 / 昨日」）；跨多天时按需改用--date_type week|month|custom - 呈现结果 → 将脚本 stdout 原文直接输出给用户，不要二次总结或改写；报告正文由后端 AI 生成，已含话题分类、评论量、互动量及跳转链接，改写会丢失关键数据；需要结构化字段时加
--json
环境变量
| 变量名 | 必填 | 说明 |
|---|---|---|
DATABRAIN_TOKEN |
是 | 认证 token；脚本中自动加 Bearer ，不要带前缀写在命令行 |
DATABRAIN_HOST |
否 | 显式 API 根 URL；不设则按 databrain.intlgame.com → databrain.woa.com → databrain-global.intlgame.com 尝试，与 databrain-opinion-metrics 一致 |
DATABRAIN_DISPLAY_HOST |
视平台而定 | 若需拼系统链接，由平台注入 |
Token 获取可参考舆情指标 skill：内网 https://databrain.woa.com/v2/user-center/personal-tokens-center，外网 https://databrain-global.intlgame.com/v2/user-center/personal-tokens-center。
Step 1：游戏 ID（本 skill 内 game_search）
在本 skill 根目录：
cd skills/databrain-opinion-summary
python scripts/game_search.py "游戏中文或英文名"
从 stdout 的 JSON 中取命中的 game_id 与 entity_name / game_name；默认每个关键词只返回 Top1，存在歧义时向用户确认。若存在 error 字段或 game_id 为 null，勿传入摘要脚本。
输出示例：
{
"games": [
{
"keyword": "某游戏",
"game_id": "e76337e746e1f95fdbf7e23c26010e448",
"entity_name": "Example Game"
}
]
}
（实现与 databrain-opinion-metrics/scripts/game_search.py 一致，便于本 skill 自包含。）
摘要模式选择
选择原则：默认走
basic，用户明确要求量化数据时才走advanced，并提前告知等待时间。
| 模式 | 何时使用 | 内容 | 预计等待 |
|---|---|---|---|
basic（默认） |
用户未特别说明时 | 正面 / 负面 / 中性话题摘要 + 可执行建议 | 约 1–5 分钟 |
advanced |
用户明确要求量化分析时 | 在 basic 基础上，每条话题额外附带评论量、互动量、点赞数（如 (357 Comments) [Engagement: 22714]） |
可能长达 30 分钟，视数据量而定 |
启动 advanced 前，务必向用户说明可能需要较长时间等待，避免误解任务卡住。
Step 2：生成舆情摘要报告
cd skills/databrain-opinion-summary
python scripts/get_opinion_summary.py \
--game_id e76337e746e1f95fdbf7e23c26010e448 \
--entity_type pc \
--start_date 2026-04-08 \
--end_date 2026-04-08 \
--date_type day \
--message "用户原始问题" \
--output_lang zh
常用可选参数：
| 参数 | 说明 |
|---|---|
--message |
用户原始问题，用于 operationLog 埋点（建议总是传入） |
--date_type |
create_summary 必填粒度，默认 day（昨日/单日）；多日范围可试 week / month / custom |
--language zh en |
只分析指定语种评论 |
--channel twitter reddit steam |
只分析指定社媒渠道 |
--top_n 10 |
各维度 Top N，默认 10 |
--output_lang en |
报告输出语言；默认 zh，欧美/全球游戏建议传 en |
--task_type advanced |
高级量化总结（含评论量、互动量等量化数据）；用户明确要求时传入；可配合 --prompt 自定义 |
--json |
stdout 输出完整 get_summary 的 data JSON，便于解析 |
id_type（unified_id / edition_id / unified_edition_id）由脚本根据 entity_type 与 game_id 长度自动选择。
安全说明
get_opinion_summary.py 在执行摘要请求前校验：
--game_id格式：^[ue][0-9a-f]+$--start_date/--end_date：YYYY-MM-DD，且end_date >= start_dateDATABRAIN_HOST仅允许受信任域名（与 metrics / game_search 一致）- Token 仅通过环境变量注入，不接受命令行传入
API 说明（脚本已实现）
| 步骤 | 方法 | 路径 |
|---|---|---|
| 创建任务 | POST | /api/v1/opinion_pc/summary/advanced/create_summary |
| 查询结果 | POST | /api/v1/opinion_pc/summary/advanced/get_summary |
请求体须包含 date_type（蛇形命名，如 day），不要使用 DateType 等错误字段名；缺省会导致 HTTP 400（校验提示 EditionUnifiedId / DateType 等，实为 JSON 字段未按约定绑定）。
创建成功返回 task_id；轮询直至 task_status 为 success，响应中含 report_zh / report_en。
依赖与本地开发
pip install -r requirements.txt
可在本 skill 根目录放置 .env 供本地调试（与 metrics skill 相同约定；服务端仍以环境变量为准）。
常见问题
| 现象 | 处理 |
|---|---|
DATABRAIN_TOKEN not set |
注入 token |
Invalid game_id |
使用 game_search.py 重新查询，确保为 u/e 开头的 hex |
Invalid --start_date / --end_date |
使用 YYYY-MM-DD |
game_search 返回 game_id: null |
换关键词或确认游戏是否收录 |
create_summary 全域名 HTTP 400、提示 DateType / edition 相关 |
确认 payload 含 date_type（默认脚本已传）；字段名须为 snake_case，勿用驼峰 DateType |
| 多域名均 create 失败（非 400） | 检查网络、token 权限、游戏是否在舆情侧可查 |
长时间 task_status 非 success |
basic 正常 1–5 分钟，advanced 可达 30 分钟；脚本最长等待约 7200s；属正常现象，请等待 |
task_status 为 failed / error |
队列或生成失败；可稍后重试（advanced 失败可降级为默认 basic 重试） |
| 正文为空 | 尝试 --json 查看原始字段；或切换 --output_lang |
打包与分发（清单）
独立分发本 skill 时建议包含：
SKILL.md、requirements.txt、.gitignore（可选）scripts/get_opinion_summary.py、scripts/game_search.py、scripts/report_log.py
运行要求：Python 3.9+（脚本使用内置类型注解语法）。安装依赖：pip install -r requirements.txt。勿将含 DATABRAIN_TOKEN 的 .env 打入制品。
工作目录：必须在 skill 根目录执行 python scripts/...，以便 get_opinion_summary 与同目录下的 report_log 可互相 import。
「相关资源」中指向仓库内其他 skill 的链接在仅拷贝本目录时可能失效，属可选参考，不影响本包内脚本运行。
相关资源
- 摘要脚本 → scripts/get_opinion_summary.py
- 游戏 ID 查询 → scripts/game_search.py
- 打点（内嵌，Agent 无感知） → scripts/report_log.py
- 同类设计参考 → ../databrain-opinion-metrics/SKILL.md
- 原始实现参考（同 API）→ ../opinion-query-slow/scripts/get_opinion_report.py