| name | databrain-dashboard-service |
| display_name_en | Dashboard Analytics |
| display_name_zh | 经分数据分析 |
| description | Query first-party (经分) game metrics (active users, revenue, sales, retention, ARPU, CCU/PCU, ASP, refund, LTV, wishlist, game-specific feature data, ua impression, ua ctr, etc) for games with Dashboard permission. Uses real internal data, which supports drill-down analysis across dimensions such as channel, platform(Steam, IOS, XBox, etc), product, region, bundle, country, etc. And supports real-time data. |
| when_to_use | Activate this skill when the user asks for first-party dashboard metrics of a specific game — active_users, revenue, sales, retention, ARPU, new_users, CCU/PCU, refund, LTV, online_time, game-specific features, ua impression, ua ctr,etc — AND the game has Dashboard permission (determined by dashboard_white_games in agent_context). For games without permission, use databrain-intelligence instead. |
Skill: Dashboard Analytics (经分数据分析)
Environment Variables (Required)
| 变量名 | 是否必填 | 说明 |
|---|
DATABRAIN_TOKEN | 必填 | 认证 token（不含 Bearer 前缀） |
DATABRAIN_HOST | 必填 | API 主机地址 |
DATABRAIN_DISPLAY_HOST | 必填 | 系统链接展示域名 |
0. Skill Scope
- This skill → first-party dashboard data for games with Dashboard permission (dashboard_white_games)
- Games NOT in white_games → use
databrain-intelligence
- Miniclip games → ONLY via MCP tools, NOT
dashboard_metrics_query_tool
- Never expose internal routing labels (white_games etc.) in user-facing responses
1. Triggers
active_users, revenue, retention, ARPU, new_users, CCU/PCU/ACU, refund, LTV, online_time, churn, ASP, downloads, wishlist, crash, progression, FPS, coop, topup, realtime etc.
2. How to Call Tools
run_skill_script(
script_path="scripts/run_tool.py",
cli_args=["--tool", "<tool_name>", "--param1", "value1", ...]
)
Rules: --tool required; lists as JSON strings; date format YYYYMMDD (not YYYY-MM-DD); arg names must exactly match signature — unsupported args silently dropped.
3. Tool Inventory & Signatures
3.1 Core Tool: dashboard_metrics_query_tool (完整签名)
Query standard dashboard metrics (active users, churn, in-game revenue, ltv, new user, online time, realtime, refund, retention, return, login, revenue, sale, technical, wishlist, etc.).
game_names: List[str] = [] # game names (use "iegg" to auto-expand IEGG games)
start_date: str = None # YYYYMMDD. If needs information on game's release date, game event date, game version date, season start date, life cycle, and they are not provided in agent context, can use llm_websearch tool to get.
end_date: str = None # YYYYMMDD. If granularity is realtime, end_date should equal to start_date.
metrics: List[str] = [] # metric names (see metric rules below)
granularity: str = None # daily|weekly|monthly|realtime. Databrain系统的weekly和monthly只支持自然周/自然月，若是任意时间的周/月需换用daily
zone: List[str] = [] # zone/区服 filter. for example 日本服.
country: List[str] = [] # ISO country codes.
os: List[str] = [] # os filter, for example Steam, IOS, XBox, Android. 也支持聚合平台code：pc(所有pc平台的数据加总), mobile(所有mobile平台的数据加总), console(所有console平台的加总). Sometimes are called platform/平台/商店/store codes.
channel: List[str] = [] # channel filter.`channel` 不要传 OS code
bundle: List[str] = [] # bundle/包体 filter
region: List[str] = [] # region/区域 filter, 不同游戏可用的region codes在'Dashboard Game Codes and Filters'中找到
lang: List[str] = [] # language filter
category: List[str] = [] # only for pc/console games
product: List[str] = [] # only for pc/console games non-realtime sales. Sometimes are called version/版本 codes.
campaign: List[str] = [] # campaign filter (casual games only)
ua_network: List[str] = [] # UA network买量渠道 filter (casual games only)
by_country_topn_only: bool = False # set True for 'top country''by country' breakdown
top_countries_num: int = 10 # how many countries
top_countries_rank_by_metric: List[str] = [] # explicit rank-by metric
Filters:
Can input only one granularity but multiple filters (zone, country, os, channel, bundle, region, lang, product, campaign, ua_network) per tool call. All filters defaults to []. If needs to group by filters, use ["255"]. 全球/全平台/所有平台数据等于total数据，也用[]。
剔除/排除某个值（exclude）：在某个 filter 的值前加 ! 前缀即表示"剔除该值"，工具会查询"该维度全部值 - 被剔除值"的【汇总】（不按该维度分组）。例：lang=["!zh"]=除简中外所有语言汇总；zone=["!日本服"]=除日本服外所有区服汇总；channel=["!Steam"]。适用于 zone/os/channel/region/lang/category/product/bundle/campaign/ua_network（任何有按游戏枚举码表的 filter）。country 不支持（无法枚举全集，请改用 region 排除或显式列出国家）。同一个 filter 不要同时混用普通值和 ! 值。
⚠️ 指标选择规则（必须遵守）
- 实时指标口径：问实时类指标必须选择 realtime 指标，非 realtime 指标不支持 realtime 粒度。实时累计销量用
lifetime_base_game_units_sold_after_refund_realtime，当日实时销量用 units_sold_after_refund_realtime，实时累计收入用 lifetime_revenue_after_refund_realtime。
- PC/Console 累计lifetime指标 vs 日粒度：Databrain中lifetime类指标是从上线/预购日期起的数字加和，本身就是汇总指标。如问"某天/截止某天/累计/没有提及任何时间范围的总数据" → 只查该天 lifetime 指标；"某时间范围内/近N天/某月/今年/2025年/最近/上个月" → 用日/月粒度非累计指标，然后对数据做sum。
- PC/console 销量口径：用户未明确时段（如x游戏销量是多少）->默认查累计销量
lifetime_base_game_units_sold_after_refund（从上线/预购日期起的数字加和）；给了具体时段/日期则用 units_sold_after_refund + 对应粒度；若明确 DLC/版本/分产品升级销量则用 units_sold_after_refund_for_product；若查预购总量，需要查询从预购日期到上线日期的每日销量并计算加总。
- 收入口径：mobile 收入/销量有时间范围用
pay_amount；无时间范围用 lifetime_pay_amount；PC/console 收入无时段默认累计 lifetime_revenue_after_refund；有明确时段则用 revenue_after_refund + 对应粒度。Casual 游戏收入/销量统一用 advertisement_revenue（广告收入）。
- PCU/CCU/ACU 映射：PCU=
peak_concurrent_users_count，CCU/实时在线=online_users_count_realtime，ACU=average_concurrent_users_count。
- 留存默认口径：默认优先 new user retention（不是 active user retention），如next_day_new_users_retention_rate_daily、7_day_new_users_retention_rate_daily，加权用weighted， 如weighted_next_day_new_users_retention_rate_daily，weekly粒度用weekly指标，如next_week_new_users_retention_rate_weekly。Casual 游戏只有 new user retention，没有 active user retention。
- DAU/WAU/MAU 口径：月峰值 DAU 才用
peak_daily_active_users；明确"平均"时用 average_daily_active_users_in_week_or_month；其余 DAU/WAU/MAU 用 active_users_count（按 daily/weekly/monthly 粒度）。
- PC/console 付费用户：使用
in_game_paying_users 相关指标。
- 在线时长/Session：每活跃用户在线时长用
average_online_time；每活跃用户 session 数用 average_session_count。
- UA CTR/CVR：用
ua_ctr / ua_conversion_rate（UA 专用语义）。
- TNU 映射：TNU（total new users）对应
lifetime_new_users_count，某天的总新进 -> lifetime_new_users_count，某天的新进 -> new_users_count。
- 日粒度默认时间：未指定时间范围时，默认最近 7 天。
⚠️ MCP Tool Routing Rules (when to use MCP vs metrics_query_tool)
- MCP 适用场景: dashboard_metrics_query_tool 不支持的特性指标（crash players count/progression 通关率/coop 联机/fps 帧数/multiple_topup 多次充值/loss rate 折损率/register 注册率/bundle 绑定数/漏斗转化率/开黑等）
- MCP 固定两步: (1)
dashboard_mcp_describe_data_tool(game_code=xxx) 获取 JSON query → (2) dashboard_mcp_read_data_tool(game_code=xxx, query=<上一步 JSON>) 获取数据。不要自己拼 query。
- 崩溃: 崩溃率/崩溃数 →
dashboard_metrics_query_tool；崩溃玩家数 → MCP tools
- HOK 去小号留存: 与 general 留存指标不同，必须走 MCP
- HOK 注册/折损: register 注册率/启动注册率/loss rate 折损率 → MCP
- 游戏内最畅销商品 (DL2): → MCP
- 新老玩家付费对比 (DL2): topup_by_user_type → MCP
- 上次活跃 (DLTB/DL2): last_active_day → MCP
- FPS 帧数 (DLTB): → MCP
如果用户问了特别长尾的游戏内指标，比如某个消耗渠道，你试了MCP和databrain-datalab-analyst skill之后也都不支持，不要试图用整个游戏的数据来回答，可以告诉用户没有查到数据。
3.2 Other Tools (详见 reference/ 目录)
| Tool | Best For | Reference |
|---|
dashboard_mcp_describe_data_tool | Discover MCP cubes/measures/dimensions (step 1) | reference/dashboard_mcp_tools.md |
dashboard_mcp_read_data_tool | Execute MCP queries (step 2) | reference/dashboard_mcp_tools.md |
dashboard_metric_percentage_tool | Metric % by dimension (country/os/channel) | reference/dashboard_metric_percentage_tool.md |
dashboard_metrics_query_tool (metric lookup) | Quick metric-name lookup and mapping rules | reference/dashboard_metrics_query_tool_metric_reference.md |
📖 Before calling a 3.2 tool, read its reference/<filename>.md for full signature and constraints.
4. Key Rules
- Permission gate: Only for games in white_games. other games → intelligence.
- Per-game routing: Permission is per game, not global.
- Game code resolution: Resolve via
dashboard_game_code_and_filters in context.
- Miniclip MCP-only: Miniclip games MUST use MCP tools only.
- De-minor (去小号): NIKKE →
dashboard_metrics_query_tool; others → MCP tools.
- Period-over-period: Split into two independent API calls (current + previous), then compare.
- Derived metrics: Use
calculation_tool for computed values.
- Fallback transparency: If tool changes filters/date, explain
fallback_info.
5. Cross-skill Coordination
Routing rules: see soul.md §5. Sentiment → databrain-opinion-service.
6. Pitfalls
- Dashboard tools for non-whitelisted games
- Mixing dashboard + third-party metrics without noting source
dashboard_metrics_query_tool for Miniclip games- Wrong granularity for realtime
- Hardcoding tokens/hosts
- Passing
game_names to MCP tools (they need game_code)
- Passing
game_code to dashboard_metrics_query_tool (it needs game_names)
- Guessing/fabricating metric names without reading
reference/dashboard_metrics_query_tool_metric_reference.md first
