databrain-dashboard-service

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

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

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 天。

⚠️ 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