Databrain Dashboard Service

Skill: Dashboard Analytics (经分数据分析)

Environment Variables (Required)

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 不要同时混用普通值和 ! 值。

⚠️ 指标选择规则（必须遵守）

1. 实时指标口径：问实时类指标必须选择 realtime 指标，非 realtime 指标不支持 realtime 粒度。实时累计销量用 lifetime_base_game_units_sold_after_refund_realtime，当日实时销量用 units_sold_after_refund_realtime，实时累计收入用 lifetime_revenue_after_refund_realtime。
2. PC/Console 累计lifetime指标 vs 日粒度：Databrain中lifetime类指标是从上线/预购日期起的数字加和，本身就是汇总指标。如问"某天/截止某天/累计/没有提及任何时间范围的总数据" → 只查该天 lifetime 指标；"某时间范围内/近N天/某月/今年/2025年/最近/上个月" → 用日/月粒度非累计指标，然后对数据做sum。
3. PC/console 销量口径：用户未明确时段（如x游戏销量是多少）->默认查累计销量 lifetime_base_game_units_sold_after_refund（从上线/预购日期起的数字加和）；给了具体时段/日期则用 units_sold_after_refund + 对应粒度；若明确 DLC/版本/分产品升级销量则用 units_sold_after_refund_for_product；若查预购总量，需要查询从预购日期到上线日期的每日销量并计算加总。
4. 收入口径：mobile 收入/销量有时间范围用 pay_amount；无时间范围用 lifetime_pay_amount；PC/console 收入无时段默认累计 lifetime_revenue_after_refund；有明确时段则用 revenue_after_refund + 对应粒度。Casual 游戏收入/销量统一用 advertisement_revenue（广告收入）。
5. PCU/CCU/ACU 映射：PCU=peak_concurrent_users_count，CCU/实时在线=online_users_count_realtime，ACU=average_concurrent_users_count。
6. 留存默认口径：默认优先 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。
7. 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 粒度）。
8. PC/console 付费用户：使用 in_game_paying_users 相关指标。
9. 在线时长/Session：每活跃用户在线时长用 average_online_time；每活跃用户 session 数用 average_session_count。
10. UA CTR/CVR：用 ua_ctr / ua_conversion_rate（UA 专用语义）。
11. TNU 映射：TNU（total new users）对应 lifetime_new_users_count，某天的总新进 -> lifetime_new_users_count，某天的新进 -> new_users_count。
12. 日粒度默认时间：未指定时间范围时，默认最近 7 天。
13. Country/Region/Zone 选择：查地区/国家数据优先 country code；查不到再用 region code；仅当用户明确问"区服/日服"时用 zone code。
14. 退款率口径：无时间范围用 lifetime_refund_rate；有时间范围用 refund_rate + daily/monthly。
15. 月峰值 DAU 补充：仅月粒度时用 peak_daily_active_users；非月粒度峰值 DAU 需查 active_users_count daily 再取 max。
16. 自然量/付费用户占比：用 dashboard_metrics_query_tool，不要用 percentage tool。
17. 国家维度 Top 国家请求：对"by country/top country/头部国家/分国家/各国/国家维度/国家分布/国家排名"类请求，必须设置 by_country_topn_only=True。
18. Top 国家排序指标参数：当用户明确表达"按某指标给国家排序"（如"按 metric_a 排的头部国家 / top countries by metric_a/top10销量国家"）时才设置 top_countries_rank_by_metric=metric_a；若只是查询"头部国家的 metric_a"，保持 top_countries_rank_by_metric 默认值，会按系统默认metric排序。
19. 默认指标兜底：若用户未指定 metrics，或仅询问游戏总体表现，默认查询 peak_concurrent_users_count, revenue, paying_users_count（mobile）/sales（非 mobile）, active_users_count。
20. PC/console 最新销量/收入：针对刚上线3个月内的游戏问最新销量/收入，取上线以来的每日收入和截止当天的realtime lifetime sales/revenue，realtime指标可以给到最新一个小时的数字，更精准。
21. 如果用户问xx国家版的数据（包含"版"字眼），需要使用channel维度查询，不要使用by country查询。
22. 如果问有多少用户买了升级版，查该升级版的sales而不是player number。
23. 如果问游戏活跃用户表现，查日活跃DAU/月活跃MAU, 最高同时在线Peak concurrent users,平均同时在线（Average concurrent users）和 average online time.
24. 如果用户问上线以来的数据，但游戏有预购机制，则需要查询上线日期后的daily数值加总，不能使用cumulative指标，因为cumulative仅统计从预购开始的收入。
25. Mobile LTV 默认口径：问 mobile 游戏的 LTV 时，默认同时查询 2 日、3 日、7 日 LTV（average_2_day_revenue_ltv_daily、average_3_day_revenue_ltv_daily、average_7_day_revenue_ltv_daily）。
26. Wishlist 默认口径：问 PC/Console 游戏的 wishlist/愿望单数据时，默认同时查询 total_wishlist_count（愿望单总量）和 total_wishlist_coversion_rate_daily（愿望单转化率）。
27. Churn 默认口径：问流失/churn 数据时，默认同时查询 active_users_churn_rate（流失率）和 active_users_churn_count（流失人数）。
28. For other metrics not listed above, you MUST first read reference/dashboard_metrics_query_tool_metric_reference.md to look up the correct metric names. Do NOT guess or fabricate metric names

⚠️ 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/ 目录)

📖 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