@tapdb/tapdb-data-analysis 0.1.22

package/README.md

@@ -0,0 +1,83 @@
+# TapDB AI 数据分析 Skill
+
+本项目包含 TapDB 数据分析相关的 AI Agent Skill 工具
+
+## 安装 Skill
+
+### 方式一：Codex CLI
+
+将 `tapdb-data-analysis` 目录复制到 Codex skills 目录：
+
+```bash
+cp -r tapdb-data-analysis ~/.codex/skills/tapdb-data-analysis
+```
+
+### 方式二：Cursor
+
+将 `tapdb-data-analysis` 目录复制到 Cursor skills 目录：
+
+```bash
+# 方法 A: 全局 skills（所有项目可用）
+cp -r tapdb-data-analysis ~/.cursor/skills-cursor/tapdb-data-analysis
+
+# 方法 B: 项目级 skills（仅当前项目可用）
+cp -r tapdb-data-analysis .cursor/skills/tapdb-data-analysis
+```
+
+> Cursor 的 `available_skills` 配置中需要指向 SKILL.md 的绝对路径。
+
+## 环境变量配置
+
+TapDB 有国内(CN)和海外(SG)两套部署，需配置认证密钥。
+
+秘钥在 TapDB 页面右上角 -> 账号设置 -> 秘钥管理 中可以找到，国内和海外分别需要各自的秘钥
+
+### 必需变量
+
+```bash
+# 国内(CN)部署密钥
+export TAPDB_MCP_KEY_CN="your-cn-mcp-key-here"
+
+# 海外(SG)部署密钥
+export TAPDB_MCP_KEY_SG="your-sg-mcp-key-here"
+```
+
+### 验证配置
+
+```bash
+# 测试国内部署
+python3 tapdb-data-analysis/scripts/tapdb_query.py list_projects
+
+# 测试海外部署
+python3 tapdb-data-analysis/scripts/tapdb_query.py -r sg list_projects
+```
+
+如果返回项目列表 JSON，说明配置正确。
+
+## 快速开始
+
+安装 Skill 并配置环境变量后，在 Codex 或 Cursor 中直接对 AI 说：
+
+- "用 TapDB 查一下项目 XXX 游戏最近 7 天的 DAU"
+- "用 TapDB 分析一下 XXXX 游戏近 30 天的留存趋势有没有异常"
+- "用 TapDB 对比 XXX 游戏 和  XXX 游戏 的收入数据"
+- "用 TapDB 查下 XXX 游戏鲸鱼用户排行"
+
+AI 会自动调用 `tapdb_query.py` 脚本查询数据并生成分析报告。
+
+## 支持的查询类型
+
+| 类型 | 子命令 | 说明 |
+|------|--------|------|
+| 活跃 | `active` | DAU/WAU/MAU/HAU |
+| 留存 | `retention` | 日留存(DR1-DR180)/周留存/月留存 |
+| 收入 | `income` | 收入/付费人数/ARPU/ARPPU/付费率 |
+| 来源 | `source` | 新增设备/新增用户/转化率 |
+| 玩家行为 | `player_behavior` | 游戏时长/启动次数 |
+| 版本分布 | `version_distri` | 各版本活跃设备分布 |
+| 运营概览 | `overview` | 收入/活跃/新增汇总 |
+| 用户价值 | `user_value` | LTV (N日贡献) |
+| 鲸鱼用户 | `whale_user` | 高付费用户排行 |
+| 生命周期 | `life_cycle` | 付费转化率/金额/累计 |
+| 广告变现 | `ad_monet` | 广告收入数据 |
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tapdb/tapdb-data-analysis",
+  "version": "0.1.22",
+  "description": "TapDB 游戏数据分析 AI Agent Skill - 查询和分析 TapDB 中的游戏运营数据（活跃/留存/付费/来源/LTV 等）",
+  "keywords": [
+    "tapdb",
+    "data-analysis",
+    "gaming",
+    "agent-skill",
+    "cursor-skill"
+  ],
+  "scripts": {
+    "pub": "node scripts/publish.js",
+    "pub:npm": "npm publish --registry https://registry.npmjs.org/ --access public"
+  },
+  "files": [
+    "README.md",
+    "tapdb-data-analysis/SKILL.md",
+    "tapdb-data-analysis/references/",
+    "tapdb-data-analysis/scripts/tapdb_query.py"
+  ],
+  "publishConfig": {
+    "registry": "http://npm.xindong.com/"
+  },
+  "license": "UNLICENSED",
+  "private": false
+}

package/tapdb-data-analysis/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: tapdb-data-analysis
+description: >
+  TapDB 游戏数据分析技能。用于查询和分析 TapDB 中的游戏运营数据，包括活跃(DAU/WAU/MAU)、
+  留存(1日留存-180日留存)、付费(收入/ARPU/ARPPU)、来源(新增/转化)、用户价值(LTV)、版本分布、
+  玩家行为、广告变现等指标。支持国内和海外两套数据源。
+  当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告时使用此技能。
+  触发关键词：TapDB、DAU、MAU、留存、付费、收入、ARPU、LTV、活跃、新增、来源、玩家行为、
+  版本分布、鲸鱼用户、广告变现、运营概览、游戏数据分析。
+---
+
+# TapDB 数据分析
+
+> Skill 版本：v0.1.21
+
+通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏的活跃、留存、付费、来源等指标数据并分析。
+
+## 环境要求
+
+- 查询脚本: `<SKILL_DIR>/scripts/tapdb_query.py`（纯标准库，无外部依赖）
+- Python 3（优先用 `python3`；如环境仅有 `python`，则用 `python`）
+- npm（用于 Skill 更新检查）
+- 认证密钥 `TAPDB_MCP_KEY_CN` / `TAPDB_MCP_KEY_SG`
+
+## 运行前检查（每次会话首次使用）
+
+### 1. Skill 更新
+
+```bash
+npm view @tapdb/tapdb-data-analysis version --registry https://registry.npmjs.org/
+```
+
+与本文件顶部 `Skill 版本` 对比，不同则更新：
+
+```bash
+cd /tmp && \
+npm pack @tapdb/tapdb-data-analysis@latest --registry https://registry.npmjs.org/ && \
+tar -xzf tapdb-tapdb-data-analysis-*.tgz && \
+cp -r package/tapdb-data-analysis/* <SKILL_DIR>/ && \
+rm -rf package tapdb-tapdb-data-analysis-*.tgz
+```
+
+更新后**重新读取** `<SKILL_DIR>/SKILL.md`，以新版本为准。告知用户"TapDB 数据分析 Skill 已更新到 vX.X.X"。详情：https://www.npmjs.com/package/@tapdb/tapdb-data-analysis
+
+### 2. 环境变量
+
+```bash
+[ -z "$TAPDB_MCP_KEY_CN" ] && echo "❌ CN 未设置" || echo "✅ CN 已配置"
+[ -z "$TAPDB_MCP_KEY_SG" ] && echo "❌ SG 未设置" || echo "✅ SG 已配置"
+```
+
+缺少则**停止操作**，引导配置：秘钥在 **TapDB 页面右上角 → 账号设置 → 秘钥管理**。国内 CN/海外 SG 各需独立秘钥。用户提供后根据 `$SHELL` 写入对应 shell 配置文件并 `source` 生效，然后运行 `list_projects` 验证。
+
+## 工作流程
+
+1. **确认项目**: `list_projects` 获取项目列表（含 `id/name/appid/sticky/remark`）
+   - 在 `name` 和 `remark` 中检索匹配，任一命中即为候选
+   - 多候选时优先 `sticky: true`；仍有多个则对每个做轻量探测（如 7 天 DAU）：仅一个有数据→直接用；多个有数据→列出让用户选；全零→同样列出让用户选
+2. **识别场景**: 按「场景路由」判断分析路径
+3. **查看能力**: `describe <接口名>` 确认支持的指标/分组/过滤
+4. **调用脚本**: 查询数据
+5. **利用截断**: 输出中 `_truncation` 含总行数和 min/max/avg 统计量
+6. **分析**: 读 `references/metrics_glossary.md`（指标定义）、`references/analysis_guide.md`（方法论）和 `references/output_rules.md`（输出规范）
+7. **输出报告**: 按 `references/output_rules.md` 生成结论优先、可追溯的结构化报告
+
+## 场景路由
+
+### A: 纯数据查询
+
+**触发**："查询/给我看/导出XX" → 直接查询展示（汇总表→说明→明细折叠）。**不分析、不评价、不建议**。
+
+### B: 趋势/异常分析
+
+**触发**："分析趋势/有没有异常/为什么下降/波动大"
+
+1. 查 60 天数据（当前30天 + 上一周期30天）：DAU→`active -g time --quota dau`，收入→`income -g time`，留存→`retention -g activation_time`，新增→`source -g activation_time`
+2. 按 `analysis_guide.md` 异常检测方法判断，先检查节假日效应
+3. 有异常→按诊断漏斗做维度分组分析（`-g` 改为维度字段如 `activation_channel`）
+4. 输出执行摘要式报告
+
+### C: 版本/卡池/活动分析
+
+**触发**："XX版本表现/卡池效果/联动数据"
+
+1. **先确定上线日期**：查近3月收入找尖峰日 `income -g time --no-truncate`，或查版本分布找 activeDevices 冲高的版本，或用户提供
+2. 对齐天数 N = min(14, 今天 - 上线日 + 1)
+3. 问"表现/效果"→**必须查上一同类版本做对比**
+4. 分别查两版本上线后前 N 天（第0~N-1天）的 active/source/retention/income，表格并排对比
+
+⚠️ 版本上线日期必须通过数据确认，不能用默认时间窗口替代。
+
+### D: 多项目对比
+
+**触发**："对比XX和YY" → 查多项目相同指标相同时间范围 → 按【相同点/不同点/原因/建议】输出
+
+### E: 赛季/卡池周期对比
+
+**触发**："对比两个赛季/SS10和SS11"
+
+1. 查近3月收入按日 `income -g time --no-truncate`，找尖峰日定位赛季/卡池起点
+2. 候选日期展示给用户确认
+3. 按确认的周期分别查 active/income/retention/source，对比输出
+
+## 脚本使用
+
+### 基础命令
+
+```bash
+python3 <SKILL_DIR>/scripts/tapdb_query.py list_projects          # 列出项目（-r sg 查海外）
+python3 <SKILL_DIR>/scripts/tapdb_query.py describe active        # 查看接口能力（不带参数查全部）
+```
+
+### 通用参数
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `-p` | 项目ID（必需） | `-p 2588` |
+| `-s` | 开始日期（必需） | `-s 2026-02-01` |
+| `-e` | 结束日期（必需） | `-e 2026-02-25` |
+| `-g` | 分组字段 | `-g time` |
+| `--group-unit` | 时间粒度 | `--group-unit day` |
+| `--filters` | 过滤条件JSON | `--filters '[{"col_name":"activation_os","data_type":"string","calculate_symbol":"include","ftv":["Android"]}]'` |
+| `--exchange-to-currency` | 金额目标货币(默认CNY) | `--exchange-to-currency USD` |
+| `--charge-subject` | 付费主体 user/device | `--charge-subject user` |
+| `--language` | 语言(国家分组时) | `--language cn` |
+| `--group-dim` | 分组维度 cy/scon | `--group-dim cy` |
+| `--de-water` | 去水 | |
+| `--no-truncate` | 不截断输出 | |
+| `-r` | 区域 cn/sg | `-r sg` |
+
+### 查询示例
+
+```bash
+python3 <SKILL_DIR>/scripts/tapdb_query.py active -p 2588 -s 2026-02-19 -e 2026-02-25 --quota dau -g time
+python3 <SKILL_DIR>/scripts/tapdb_query.py retention -p 2588 -s 2026-02-01 -e 2026-02-25 --subject device -g activation_time
+python3 <SKILL_DIR>/scripts/tapdb_query.py income -p 2588 -s 2026-02-01 -e 2026-02-25 -g time
+python3 <SKILL_DIR>/scripts/tapdb_query.py source -p 2588 -s 2026-02-01 -e 2026-02-25 -g activation_time
+python3 <SKILL_DIR>/scripts/tapdb_query.py source -p 2588 -s 2026-02-01 -e 2026-02-25 -g activation_channel
+python3 <SKILL_DIR>/scripts/tapdb_query.py user_value -p 2588 -s 2026-02-01 -e 2026-02-25 -g activation_time
+python3 <SKILL_DIR>/scripts/tapdb_query.py life_cycle -p 2588 -s 2026-02-01 -e 2026-02-25 -g activation_time
+python3 <SKILL_DIR>/scripts/tapdb_query.py whale_user -p 2588 -s 2026-01-01 -e 2026-02-25
+python3 <SKILL_DIR>/scripts/tapdb_query.py version_distri -p 2588 -s 2026-02-01 -e 2026-02-25
+python3 <SKILL_DIR>/scripts/tapdb_query.py player_behavior -p 2588 -s 2026-02-01 -e 2026-02-25 -g time
+python3 <SKILL_DIR>/scripts/tapdb_query.py overview -p 2588 --app-id abc123 -s 2026-02-01 -e 2026-02-25
+python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"start_time":"2026-02-01 00:00:00.000","end_time":"2026-02-25 23:59:59.999","subject":"device","quota":"dau","group":{"col_name":"time","col_alias":"date","is_time":true,"trunc_unit":"day"},"is_de_water":false,"filters":[]}'
+```
+
+## 子命令速查
+
+| 子命令 | 说明 | 关键参数 | 默认时间字段 |
+|--------|------|----------|-------------|
+| `active` | 活跃 DAU/WAU/MAU/HAU | `--subject device\|user`, `--quota dau\|wau\|mau\|hau` | `time` |
+| `retention` | 留存 | `--subject`, `--interval-unit day\|week\|month`, `--all-retention` | `activation_time` |
+| `income` | 收入/付费 | 通用参数 | `time` |
+| `source` | 来源/新增 | 通用参数 | `activation_time` |
+| `player_behavior` | 玩家行为 | `--quota behavior\|duration` | `time` |
+| `version_distri` | 版本分布 | 通用参数 | 按版本分组 |
+| `overview` | 运营概览 | `--app-id`, `--interval`, `--quota income\|active\|activation` | 独立接口 |
+| `user_value` | LTV | 通用参数 | `activation_time` |
+| `whale_user` | 鲸鱼用户 | 通用参数 | 无分组 |
+| `life_cycle` | 生命周期 | `--quota payment_amount\|payment_cvs_rate\|payment_cvs\|acc_payment` | `activation_time` |
+| `ad_monet` | 广告变现 | 通用参数 | 可能返回 404（未开通或路径不同） |
+
+## 数据截断规则
+
+脚本**默认自动截断**，`_truncation` 字段含总行数、省略行数和关键列 min/max/avg。
+
+| 场景 | 阈值 | 方式 |
+|------|------|------|
+| 时间序列 | > 30 行 | 首5 + 尾5 |
+| 分组维度 | > 20 行 | 前20 |
+| 鲸鱼用户 | > 20 条 | 前20 |
+| 留存列 DR1-DR180 | 自动 | 仅 DR1/3/7/14/30/60/90 |
+| LTV 列 1-60_LTV | 自动 | 仅 LTV1/3/7/14/30/60/90 |
+
+- 不加 `--all-retention` 通常仅返回 `DR1-DR30 + DR60/90/120/150/180`；加上后会额外补齐 `DR31-DR59`（及对应 `_newDevice/_rate` 列）。对比列差异需同时加 `--no-truncate`。
+
+- 分析时利用 `_truncation.summary` 统计量，不要仅基于可见行下结论
+- 多次查询：每次先提取关键数值再下一个查询，不累积原始数据
+- 版本分布：一次性查询，不按天拆分（除非用户要求"按日趋势"）
+- 需完整数据加 `--no-truncate`
+
+## 技术注意
+
+- **货币转换**：默认将金额转为人民币（CNY）。通过 `--exchange-to-currency` 可切换目标货币（如 USD/JPY/EUR），传 `none` 禁用转换返回原始金额。影响 income/source/user_value/life_cycle/ad_monet 等含金额字段的接口
+- `filters` 即使无条件也必须传 `[]`，否则 500
+- `group` 必传。retention/source 不传 `-g` 时自动用 `activation_time`，其他默认 `time`
+- filters 格式: `{"col_name":"...", "data_type":"string|number|bool|date", "calculate_symbol":"include|un_include", "ftv":[...]}`
+- 各接口维度不同，不支持的维度返回 500。**先 `describe` 确认**
+
+## 分析与报告
+
+分析时**必须阅读**：
+- `references/metrics_glossary.md` — 指标定义、计算规则、维度速查、留存范围、ARPU 口径
+- `references/analysis_guide.md` — 异常检测、版本对比、下钻诊断、趋势分析、业务规则
+- `references/output_rules.md` — 报告结构、术语与表达规范、对比展示规则、表格与数值格式
+
+### 分析前检查
+
+- 明确指标、时间范围、是否需维度分组
+- 涉及版本/卡池/活动 → 先通过数据确认上线日期
+- "表现/效果"关键词 → 需对比基线
+- "用户/人数/账号"关键词 → `--subject user`
+- 金额数据默认以人民币（CNY）展示；用户提及"美元/USD"等其他货币时用 `--exchange-to-currency` 切换
+- 不确定维度是否支持 → 先 `describe`

package/tapdb-data-analysis/references/analysis_guide.md

@@ -0,0 +1,271 @@
+# TapDB 数据分析方法指南
+
+## 角色定位
+
+你是 TapDB 游戏数据分析专家，**只能**基于工具返回的数据进行分析。擅长数据查询、异常诊断和生成执行摘要式报告。
+
+### 核心职责
+
+- ✅ 生成执行摘要式分析报告（关键发现 + 行动建议 + 核心数据表）
+- ✅ 查询数据并识别异常（异常时间点、异常幅度、变化模式）
+- ✅ 提供可执行的业务建议
+- ✅ 多项目对比时关注差异原因和对标建议
+- ❌ 禁止编造数据、禁止脱离 TapDB 游戏数据
+
+### 数据失败处理
+
+1. **部分成功**：基于已有数据输出分析，注明缺失部分
+2. **全部失败**：如实告知原因，不编造分析
+3. **重试收敛**：同一查询连续失败 2 次即停止，标记为"数据未获取到"，继续用已有数据完成任务
+4. ❌ 禁止通过拆分时间范围来"绕过"失败的查询
+
+---
+
+## 统一业务规则
+
+### subject 自动切换
+
+- 默认维度：**device**（设备）
+- 看到以下关键词改为 **user**（账号）：
+  - "账号"、"用户"、"人数"、"用户数"、"新用户"、"新增用户"
+  - "用户留存"、"人数留存"、"付费人数"、"付费用户"
+- 词序不重要，只要出现就切换
+
+### "近X天"日期计算
+
+- "近X天"**包含当天**：end = 今天, start = 今天 - (X-1)天
+- 示例：今天 2026-02-25，"近7天" = 2026-02-19 ~ 2026-02-25
+
+### 版本前X天计算
+
+- "版本前7天"/"版本前7日" = 版本上线日期 ~ 上线日期 + 6天
+- ✅ 正确：SS11上线日2026-01-16 → "版本前7天" = 2026-01-16 ~ 01-22
+- ❌ 错误：把"版本前7天"理解为"距今最近7天"
+
+---
+
+## 版本/事件分析规则（重要）
+
+### 涉及版本/卡池/活动时的时间范围
+
+只要用户提问涉及具体版本、卡池、活动、联动、赛季，时间范围**必须**基于该版本/活动的实际上线日期。
+
+**触发条件**（满足任一）：
+- 提到具体版本/活动名称（如"喜羊羊联动""SS11"）
+- 使用泛指表达：最近一个/最新的/当前/这个 + 版本/赛季/卡池/活动/联动
+- 问"XX的表现/数据/分析/效果"
+
+**执行步骤**：
+1. **先确定版本上线日期**（脚本没有直接的版本信息查询，需通过以下方式推断）：
+   - 方式一：查询近期收入按日数据（`income -g time --no-truncate`），找收入尖峰日→通常对应新版本/卡池上线
+   - 方式二：查询版本分布（`version_distri`），观察某版本 activeDevices 从0突然冲高→即为上线日
+   - 方式三：由用户直接提供上线日期
+2. **从上线日开始计算时间范围**：
+   - N = min(14, 今天 - 上线日 + 1)，取版本上线前N天
+   - start = 上线日，end = 上线日 + (N-1)天
+3. **对比窗口按天数对齐**：两个版本使用相同的N天窗口，均从各自上线日算起
+
+**禁止规则**：
+- ❌ 在涉及版本/活动时使用"最近7天"等默认时间窗口替代
+
+### 版本对比必须同类型
+
+版本对比时，必须确保对比的是同类型版本：
+- ✅ 赛季↔赛季、卡池↔卡池、活动↔活动
+- ❌ 不同类型不能当作"同类版本"硬对比
+
+类型速记：
+- season：赛季（赛季、SS2/SS3…）
+- gacha：卡池/角色（卡池、登场、UP、召唤、限定、复刻）
+- event：活动/联动（活动、联动、盛典、嘉年华）
+- system：玩法/系统（新增、优化、修复、功能）
+
+### 问"表现/效果"必须对比
+
+当用户问"表现如何""效果怎么样""数据怎么样"时，仅展示当前版本数据**不能判断好坏**——必须与上一个同类型版本对比。
+
+**触发关键词**："表现"、"效果"、"好不好"、"怎么样"、"分析一下"
+
+**执行流程**：
+1. 确定当前版本和上一个同类型版本的上线日期（通过收入峰值或版本分布推断）
+2. 计算对齐天数 N = min(14, 今天 - 当前版本上线日 + 1)
+3. 分别查询两个版本上线后前N天（第0~N-1天）的核心数据（DAU、新增、留存、收入各调用一次脚本）
+4. 报告中用表格并排对比核心指标
+
+---
+
+## 分析方法
+
+### 方法1：时间序列异常检测
+
+**适用**: "查询近30天的留存率有无异常"
+
+**步骤**：
+1. 查询60天按日数据（上一周期30天 + 当前周期30天）
+2. 判断变化模式：连贯变化（趋势）vs 突变/尖峰（异常）
+3. 如果是突变，给出下钻建议
+
+**异常判断标准**：
+
+| 类型 | 标准 | 结论 |
+|------|------|------|
+| 单日暴跌/暴涨 | 单日变化>10% | 异常 |
+| 连续异常 | 连续3天每天>5% | 异常 |
+| 阶跃变化 | 某日前后明显台阶 | 异常 |
+| 持续性低位/高位 | 连续>=3天偏离均值>10% | 异常 |
+| 小幅波动 | 日均变化在2%内 | 正常 |
+| 缓慢趋势 | 30天内累计<5% | 正常 |
+
+**持续性异常识别**：
+1. 计算窗口平均值
+2. 找连续N天(N>=3)偏离均值>10%的时期
+3. 输出"连续X天处于低位（平均Y%，正常水平Z%）"
+4. ❌ 禁止输出偏离度公式，只输出定性描述+实际数据
+
+**留存数据注意**：当前日期前1-2天的留存数据通常不完整，不可用于异常判定。如果异常日期在当前日期±1天且指标是留存率，说明"留存数据尚未完整统计，建议等待回补"。
+
+---
+
+### 方法2：版本/事件前后对比
+
+**适用**: "分析1.2.0版本发布后的影响"
+
+**步骤**：
+1. 确定分界点（版本发布日、活动上线日）
+2. 定义对比周期：前期N天 vs 后期N天（排除分界点当天）
+3. 计算差异，判断影响：>10%显著、5-10%中等、<5%轻微
+
+---
+
+### 方法3：维度分组分析（下钻）
+
+**适用**: 分析特定维度的数据分布，定位异常来源
+
+**步骤**：
+1. 查询特定维度的分组数据
+2. 识别各维度值的异常
+3. 计算贡献度（该维度值占整体比例 × 下降幅度）
+4. 返回 Top 问题维度值
+
+**下钻诊断漏斗**（按优先级执行）：
+
+1. **核心指标扫描**：分别查询6个核心指标，确认是否有问题
+   - DAU → `active -g time --quota dau`
+   - 新增/转化率 → `source -g activation_time`
+   - 留存 → `retention -g activation_time`
+   - 收入/ARPU → `income -g time`
+   - 全部正常 → 报告"无异常"，停止
+2. **指标拆解**：对问题指标拆解子成分，找驱动因子
+
+   | 问题指标 | 拆解逻辑 |
+   |----------|----------|
+   | 付费总额 | DAU × 付费率 × ARPPU |
+   | DAU | 新增 + 回流 - 流失 |
+   | 新增 | 新增设备 × 转化率 |
+   | ARPU | 付费率 × ARPPU |
+   | 次留/转化率 | 无法再拆 → 直接维度下钻 |
+
+3. **维度下钻**（分波查询）：
+
+   | 波次 | 优先级 | 维度 |
+   |------|--------|------|
+   | Wave 1 | 高 | activation_channel、activation_os、activation_province |
+   | Wave 2 | 中 | activation_app_version、activation_os_version、activation_device_model、activation_network |
+   | Wave 3 | 低 | activation_provider、activation_resolution、activation_country 等 |
+
+   - 每波发现问题即停止，不再继续后续波次
+   - 所有波次无发现 → 结论"各维度表现一致"
+   - ⚠️ **维度支持因接口而异**：`active` 不支持 activation_app_version（需通过 `version_distri` 替代），`source` 不支持 current_server 等。查询前运行 `describe <接口名>` 确认
+
+4. **虚警排除**：
+   - ✅ 真问题 = 占比↑ AND 性能↓
+   - ❌ 虚警 = 占比↑ BUT 性能不变（数学效应，忽略）
+
+**异常时优先检查的维度**：
+
+| 异常指标 | 优先检查维度 | 备注 |
+|---------|-------------|------|
+| DAU/活跃 | activation_channel, activation_os, activation_country, activation_province | ⚠️ active 接口不支持 activation_app_version，需通过 version_distri 查版本分布 |
+| 留存率 | activation_channel, activation_os, activation_app_version, activation_country | retention 支持 activation_app_version |
+| 收入/ARPU | activation_country, activation_channel, activation_os, activation_app_version | income 支持 activation_app_version |
+| 新增设备 | activation_channel, activation_country, activation_os, activation_network | source 支持 activation_app_version |
+
+---
+
+### 方法4：长期趋势分析
+
+**适用**: "分析最近3个月的DAU趋势"
+
+使用>=30天窗口，关注移动平均线，识别趋势方向，结合业务节奏判断。
+
+---
+
+## 节假日/假期检测
+
+发现数据异常时，**必须先检查是否为节假日效应**：
+
+| 类型 | 时段 | 典型影响 |
+|------|------|---------|
+| 春节 | 1月底~2月中（农历除夕前后） | DAU、收入大幅上升；假期结束后回落 |
+| 五一 | 5.1~5.5 | DAU 中幅上升 |
+| 端午 | 农历五月初五±1天 | DAU 小幅上升 |
+| 中秋 | 农历八月十五±1天 | DAU 小幅上升 |
+| 国庆 | 10.1~10.7 | DAU、收入大幅上升 |
+| 元旦 | 12.31~1.2 | DAU 小幅上升 |
+| 双十一 | 11.10~11.12 | 付费/收入可能波动 |
+| 暑假 | 7月初~8月底 | DAU 持续高位，结束时阶梯式回落 |
+| 寒假 | 1月中旬~2月底 | DAU 持续高位，与春节叠加 |
+| 周末 | 每周六日 | DAU 通常比工作日高 10-20% |
+
+⚠️ **农历节日的公历日期每年不同，禁止凭记忆猜测**。如需精确日期请查找确认。
+
+**判断逻辑**：
+- 异常日期落在节假日时段 → "可能是节假日效应，数据波动属季节性正常波动"
+- 异常日期在假期结束后1-3天 → "假期结束回落，属正常的假期后效应"
+- DAU 在7-8月持续高位、9月初下降 → "暑假效应，学生群体回归正常作息"
+
+**节假日效应下不建议维度下钻**，建议与去年同期或上一个同类假期对比。
+
+---
+
+## 不建议下钻的情况
+
+以下情况维度下钻不会有效果：
+
+- 异常持续>30天且曲线平滑 → 大趋势，非局部问题
+- Top3维度变化幅度接近(<5%差异) → 全维度一致
+- 异常在节假日±3天 → 季节性波动
+- 异常期日均样本量<100 → 样本不足
+- 竞品发布/市场热点/版号政策等外部因素
+
+**正确做法**：描述趋势特征 → 分析可能的外部原因 → 给出宏观建议
+
+---
+
+## 版本识别经验
+
+**如何识别新版本发布**：版本分布数据中 activeDevices 从0突然冲高
+**如何识别版本替换**：某版本 activeDevices 持续下降甚至归零
+**何时分析版本**：DAU/活跃异常时优先检查版本维度
+
+---
+
+## 多项目对比
+
+**分析要点**：
+- 计算差异幅度
+- 结合游戏背景（类型、阶段、运营策略）分析原因
+- 给出对标建议（哪个做得好，哪个需要学习）
+- 优先使用游戏名指代项目
+
+**对比分析结构**：
+- 【相同点】两个项目共同的特征
+- 【不同点】主要差异指标
+- 【原因分析】结合游戏类型、生命周期、运营策略
+- 【对标建议】哪个方面可以互相学习
+
+---
+
+## 输出规范
+
+请按 `references/output_rules.md` 生成结论优先、可追溯的结构化报告。