@tapdb/tapdb-data-analysis 0.1.22

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

@@ -0,0 +1,143 @@
+# TapDB 核心业务指标详解
+
+> **通用说明**：① 去重=同一用户/设备在统计周期内只计一次 ② 统计维度=账号(user) vs 设备(device) ③ 去水=过滤异常/作弊数据（脚本默认不去水，需加 `--de-water`） ④ 标注 ✨ 的字段由API直接返回，无需手动计算
+
+---
+
+## 基础指标
+
+| 指标 | 字段 | 定义 | 要点 |
+|------|------|------|------|
+| 新增设备 | newDevice | 首次完成 SDK 初始化的设备数（设备维度） | 卸载重装不算新增 |
+| 转化设备 | convertedDevice | 登录过账号的新增设备数 | ⚠️ 按设备新增日记录，非登录日（11-01新增+11-05登录→算11-01转化） |
+| 转化率 | converted_rate ✨ | 转化设备÷新增设备（API返回小数，如0.8333=83.33%） | |
+| 新增用户 | newUser | 首次登录的用户数（账号维度） | 与新增设备不同，统计的是账号 |
+
+## 活跃指标
+
+| 指标 | 定义 |
+|------|------|
+| DAU/WAU/MAU | 日/周/月内打开游戏的去重用户数（账号维度） |
+| 活跃设备 (active_devices) | 统计期内至少打开一次应用的去重设备数 |
+| 打开次数 | 打开应用的总次数（不去重，后台→前台算一次） |
+
+**用户生命周期分类**：新用户（首次打开在统计期内）| 老用户（首次打开在统计期前，期内仍活跃）| 回流用户（曾流失，期内重新活跃）| 流失用户（超N天未打开）| 沉默用户（注册后从未打开）
+
+### 时长指标
+
+- 使用时长：应用内总停留时间（所有用户累计）
+- 平均使用时长 ✨：总时长÷打开次数
+- 人均使用时长 ✨：总时长÷活跃用户数
+
+## 留存指标
+
+API 直接返回 DRx_rate/WRx_rate/MRx_rate（小数形式，如 0.7656=76.56%），**无需手动计算**。
+
+- DR1=次日留存、DR3=3日留存、DR7=7日留存、DR30=30日留存
+- 通用公式：DR_N = D_N回访÷D0新增
+- 常见周期：DR1/DR3/DR7/DR14/DR30/DR60/DR90
+- 留存曲线应逐步下降；某节点异常下降需重点分析
+
+### 留存指标范围（重要）
+
+查询留存数据时，**必须明确需要哪些留存指标**：
+
+**关键指标（默认，10个左右）**：
+- 日留存：DR1、DR3、DR7、DR14、DR30
+- 周留存：WR1、WR4
+- 月留存：MR1、MR3、MR6
+- 用途：日常分析、趋势监控
+- 数据量：适中，不会超限
+
+**所有指标（谨慎使用，180+个）**：
+- 日留存：DR1-DR180（180个）| 周留存：WR1-WR26（26个）| 月留存：MR1-MR12（12个）
+- 用途：特定留存天数分析（如60日留存、90日留存）
+- ⚠️ 数据量极大，容易导致超限
+
+**严格规则**：
+- 默认不加 `--all-retention`（仅返回关键10个指标）
+- 仅当用户明确要求"60日留存""所有留存""完整留存""DR60"等才启用 `--all-retention`
+- 不要因为查询多个维度或多个项目就自动启用全量留存
+
+| 参数 | 返回字段数 | 数据量 |
+|-----|---------|--------|
+| 默认（关键指标） | 约30字段 | 适中 |
+| `--all-retention` | 约200+字段 | 极大，慎用 |
+
+### 留存展示规则
+
+- 默认只展示留存率，不展示留存人数
+- 留存率 = DR1 ÷ DR1_newDevice × 100%
+- 字段名固定为 `_newDevice`，含义取决于 subject（device→设备数，user→用户数）
+- 若 API 返回了 `_rate` 字段，直接使用；否则手动计算
+- 当前日期前1-2天的留存数据通常不完整，标注"数据未完全回补"
+
+## 付费指标
+
+所有付费指标基于 charge 事件统计（核心字段：charge_amount、user_id）。
+
+| 指标 | 字段 | 定义 |
+|------|------|------|
+| 收入 | incomes | charge_amount 求和 |
+| 付费人数 | payers_num | countdistinct(user_id) |
+| 付费次数 | pay_times | count() |
+| ARPU ✨ | — | 收入÷活跃用户数(user_login) |
+| ARPPU ✨ | — | 收入÷付费用户数 |
+| 首日ARPU ✨ | — | 首日付费÷新增设备 |
+| 首日ARPPU ✨ | — | 首日付费÷首日付费人数 |
+| 付费率 ✨ | _rate字段 | 付费人数÷活跃用户数（小数） |
+| 首日付费用户 | firstChargeuser | 新增当天付费的新增用户数 |
+| 首日付费金额 | firstChargeAmount | 新增用户首日付费金额 |
+| 新增付费人数 | newChargeUser | 首次付费的用户数（不限新增时间） |
+| 新增总付费 | newTotalChargeAmount | 首次付费用户的总付费金额 |
+| 退款金额/次数/人数 | refunds/refund_times/refunders_num | 退款数据 |
+
+### ARPU/ARPPU 计算口径（重要！防止计算错误）
+
+- **ARPU 永远用日均口径**：ARPU = 日均收入 ÷ 日均DAU
+  - 周/月ARPU = 各日ARPU的均值，或 总收入÷天数÷日均DAU
+- **ARPPU 永远用日均口径**：ARPPU = 日均收入 ÷ 日均付费人数
+- ❌ **禁止用周/月去重活跃用户数做分母**：工具返回的汇总行 active_users 是去重后的累计值（如7天去重195,663），不等于日均DAU（如155,768），用它做分母会得到错误的ARPU
+- ❌ 错误：周总收入(12,230,904) ÷ 周去重活跃(195,663) = 62.46 → 这不是ARPU
+- ✅ 正确：日均收入(1,747,272) ÷ 日均DAU(155,768) = 11.22 → 这才是日均ARPU
+
+### LTV (Life Time Value)
+
+N日内人均累计付费金额（LTV1/3/7/14/30/60/90）。通过 `user_value` 子命令查询。
+
+### 玩家行为指标
+
+- 游戏时长：游戏内总停留时间
+- 平均游戏时长：总时长÷活跃用户数
+- 启动次数：打开应用总次数
+
+## 维度与环境字段速查
+
+| 类别 | 字段 | 说明 |
+|------|------|------|
+| 设备型号 | activation_device_model | 设备兼容性分析 |
+| 操作系统 | activation_os | Android/iOS/Windows/macOS |
+| 系统版本 | activation_os_version | — |
+| 应用版本 | activation_app_version | ⚠️ 版本分布≠版本发布记录（发布记录需另行获取） |
+| 分包渠道 | activation_channel | TapTap/App Store等 |
+| 广告渠道 | first_ad_conversion_link_id | 广告投放下载链接 |
+| UTM来源 | utmsrc | ⚠️ 所有接口均不支持此维度的分组/过滤 |
+| 国家/地区 | activation_country | — |
+| 省份 | activation_province | 仅国内 |
+| 次大陆 | activation_country + `--group-dim scon` | 东亚/东南亚等（非独立字段，通过 activation_country 分组 + scon 模式实现） |
+| 网络方式 | activation_network | WiFi/4G/5G/3G |
+| 运营商 | activation_provider | — |
+| 屏幕分辨率 | activation_resolution | — |
+| 首次/当前服务器 | first_server / current_server | — |
+| 支付来源 | payment_source | 支付订单来源渠道（income 接口支持分组/过滤） |
+| 去水 | is_de_water | 脚本默认**不去水**（需加 `--de-water` 开启） |
+
+### 维度平台兼容性（必须遵守）
+
+- `activation_app_version`、`activation_device_model` **仅适用于移动平台**（iOS/Android），不可用于桌面渠道（TapPC/Steam等）
+- TapPC/Steam/Epic/GOG 等渠道**仅存在于桌面平台**（Windows/Mac）
+- 跨平台安全维度：activation_os、activation_channel、activation_country、activation_province、activation_network
+
+### 各接口维度支持差异
+
+不同查询子命令支持的分组/过滤维度不同，使用不支持的维度会返回 500 错误。**查询前运行 `describe <接口名>` 确认**。

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

@@ -0,0 +1,185 @@
+# 输出规范（TapDB 数据分析）
+
+> 目标：让非数据同学也能一眼看懂“发生了什么、影响多大、下一步做什么”。结论优先，数据作证；推断要明确标注为推测。
+
+---
+
+## 1) 报告结构（结论优先）
+
+- 先给 **3~7 条关键结论**（每条尽量带 1 个关键数字或时间点），再给数据表，最后给建议/下一步
+- 必须在显眼位置写清楚 **项目名（如有歧义再写项目ID）、时间范围、口径（device/user、去水、货币）**
+- 仅“数据查询”场景：只展示数据与必要口径说明，不做评价/原因/建议（遵循 `SKILL.md` 场景 A）
+
+**执行摘要式报告模板**：
+
+```
+# [游戏名] 数据分析 - 执行摘要
+
+## 一、核心结论（按重要性排序）
+1. [最重要发现]
+2. [第二重要发现]
+3. [风险或机会点]
+
+## 二、立即行动项（按紧急度排序）
+- [最紧急行动]
+- [重要行动]
+- [改进建议]
+
+## 三、关键数据速览
+| 指标 | 当前值 | 对比值 | 变化 |
+|-----|--------|--------|------|
+| ...按固定顺序展示... |
+
+## 四、详细分析
+
+**综合判断**：[1-3句概括]
+
+### 4.1 [对应核心结论1的主题]
+**结论**：[1-2句]
+**推测：** [放在表格前面]
+| 数据对比表 |
+
+### 4.2 [对应核心结论2]
+...
+
+## 五、数据附录（可选）
+<details>
+<summary>点击查看完整数据</summary>
+...
+</details>
+
+*数据时间：xxxx年xx月xx日～xx日 | subject：device/user | 去水：是/否 | 货币：CNY/USD/...*
+```
+
+**报告原则**：
+- **结论优先**：每个分析先给出关键结论，再展开数据支撑
+- **行动导向**：不仅指出问题，还要给出可执行建议
+- **1屏原则**：执行摘要控制在 1 屏内可看完
+- **金字塔原则**：最重要的放最前面，按影响程度递减
+- **数据克制**：摘要只放关键数据，完整数据放附录
+- **已查询数据不可遗漏**：所有成功返回的数据都必须在报告中体现
+
+---
+
+## 2) 证据与推断（必须区分）
+
+- **数据事实**：可由查询结果直接验证 → 直接陈述并附数据
+- **推断/假设**：需要进一步验证 → 使用 **“推测：”** 前缀，并写清依据（哪几条数据/现象支撑）
+  - ✅ “推测：收入下降可能与返场卡池吸引力不足有关，建议核实卡池内容”
+- 每条行动建议需绑定：对应异常 + 预期影响 + 验证方式
+- ❌ 禁止把推断写成确定事实
+
+---
+
+## 3) 术语与表述（必须遵守）
+
+- ❌ 禁止使用 “pp”（百分点） → ✅ 对率类指标一律写成 **从 X% 到 Y%（X%→Y%）**
+- ❌ 输出中尽量不要出现 `DR1/DR3/DR7` 等缩写 → ✅ 用 **次留/3留/7留/14留/30留**（需要时括号标注原字段名）
+- **指标名称**：必须用 **中文指标名**（必要时括号标注常用缩写，如“日活跃用户数（DAU）”），**禁止直接用 API 字段/列名当作指标名**（如 `newDevice`/`incomes`/`payers_num`/`converted_rate`）。字段名如需追溯，优先放在数据附录的“字段映射”中；留存等少数固定缩写需要时可以在中文后括号标注原字段名。
+- ❌ 禁止在报告中列出计算公式（行业常识，追问时才解释）
+- ❌ 禁止“无结构性异常”等技术术语 → ✅ “各渠道/平台表现一致，没有哪个特别差”
+- ❌ 禁止“真问题/虚警/数学效应/贡献度”等术语 → ✅ 用通俗描述替代
+- **维度字段**：必须用 **中文名称（英文字段名）**，例如：渠道（activation_channel）
+- **工具失败/缺失数据**：必须明确披露“XX 数据未获取到（原因：…）”，不得继续引用该数据
+
+---
+
+## 4) 对比与变化展示（消除歧义）
+
+### 对比展示规则
+
+- **率类指标**（转化率、留存率、付费率等）：用箭头 **(X%→Y%)**，不要写 “-6%/+2%”
+- **量类指标**（DAU、收入、新增设备、人数等）：用相对变化 **+X%/-X%**，并同时给出绝对值
+- 多版本/赛季对比：对齐 **上线后前 N 天（第0~N-1天）**；在表头标注 N 和起止日期
+
+### 变化幅度描述
+
+- <5%：小幅
+- 5%–15%：中等
+- 15%–30%：较大
+- >30%：大幅
+
+### 变化列颜色标记（仅“变化”列加底色）
+
+- 正向变化：`<span style="background-color:#e6f4ea;padding:2px 4px">+24.5%</span>`
+- 负向变化：`<span style="background-color:#fce8e6;padding:2px 4px">-21.7%</span>`
+- ❌ 禁止在表格内用任何 emoji 或特殊符号（📈📉💰✅⚠️ 等），用文字替代（emoji 仅用于标题和正文）
+
+### 加粗规则
+
+- 有明显变化且重要的指标行：加粗指标名和数值
+- 非核心数据不加粗；不加粗整段文字
+
+---
+
+## 5) 表格与数值格式
+
+- 表格优先（避免在正文逐条罗列对比数字）
+- **结论中的金额**：必须在数值前加**货币符号**（如 `¥12.3万`、`$3,210`），并与本报告的货币口径一致
+- **大数（金额/人数/设备等）**：优先用 **亿/万**（如 `1.2亿`、`356.8万`），不要用 `k/m/b`
+- 小数额与原始值：用千分位（如 `1,234,567`）；如需同时展示“亿/万”和原始值，用括号补充原始值（千分位）
+- 金额口径：默认 CNY；切换货币时在标题、表头或末尾元信息中注明（如 `货币：USD`）
+- 百分比：保留 1 位小数（例如 12.3%）
+- 数据排序：时间序列按日期倒序（最新在上）
+- 超过 10 行的表用 `<details>` 折叠，正文只展示关键节点
+- 分组查询必须显示维度值列
+- 日期列：所有行日期相同时可省略，在说明中标注
+- 收入数据需体现占比或贡献度（如按渠道/国家拆分时）
+
+### 指标展示顺序（固定）
+
+1. **活跃**：日活跃用户数（DAU）
+2. **新增**：新增设备数 → 转化设备数 → 转化率 → 新增账号数
+3. **留存**：次日留存率 → 3日留存率 → 7日留存率（只展示率，不展示留存人数）
+4. **付费**：收入 → 付费人数 → 付费率 → ARPU（每活跃用户收入） → ARPPU（每付费用户收入）
+
+### “基本持平”指标展示
+
+- 1–2 个持平：保留在表格
+- 3 个及以上：不放表格，表格下方一句话概括：`> 还检查了XX、YY，差异不大。`
+
+---
+
+## 6) 口径与可追溯性
+
+- **项目标识**：结论中默认只写项目名；仅当项目名有歧义/存在多候选项目时，在元信息或首次出现处补充项目ID
+- **统计维度**：必须标注设备/账号维度（如“日活跃用户数（DAU，设备）”），不能只写“留存下降”
+- **subject**：同表同 subject 标一次；混合时在指标名后括号标，如“日活跃用户数（DAU，账号）”
+- **去水**：标注是否启用了 `--de-water`（脚本默认不去水），统一标注一次即可
+- **货币**：默认 CNY；切换后必须在标题或表头注明
+- **时间范围**：相同时末尾统一标注；不同时分表标
+- **口径一致**：同对话同指标口径保持一致，换口径必须说明
+- **版本对比表口径一致**：两张表必须使用相同的 subject、相同的列结构和列顺序
+
+---
+
+## 7) 纯查询展示规则（无需分析）
+
+当任务仅为数据查询时：
+
+1. **汇总表在前** → 关键数据说明 → 每日明细折叠在后
+2. 关键数据说明只描述数据特征（趋势、峰谷、波动范围），不解释原因
+3. 如果查询日期覆盖节假日，在说明中标注“本时段为XX期间，数据可能受节日效应影响”
+
+**LTV / 生命周期专用展示**：不使用汇总+折叠结构，只输出一张完整明细表：
+- 每行一天，日期倒序排列
+- null 显示为 `-`
+- 底部加总计/平均行 + LTV 倍数行（N_LTV平均 ÷ 1_LTV平均，格式 `×2.23`）
+- 生命周期表头用中文：0→“当日”，1→“1日后”，2→“2日后”
+
+---
+
+## 8) 详细分析小节格式
+
+每个小节：
+1. **结论**（1–2 句）
+2. **推测/建议**（标注“推测：”，放在表格前面）
+3. **数据对比表**（佐证）
+
+详细分析章节如有综合判断/总结性结论，**放在所有子章节之前**。
+
+---
+
+## 9) 失败重试（与工具调用协作）
+
+- 同一查询连续失败 2 次即停止重试，继续用已有数据完成任务（详见 `references/analysis_guide.md`）

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

@@ -0,0 +1,9 @@
+# 运行前检查
+
+本页内容已合并进 `tapdb-data-analysis/SKILL.md` 的「运行前检查（每次会话首次使用）」章节，以避免重复维护与规则漂移。
+
+请以 `tapdb-data-analysis/SKILL.md` 为准完成：
+
+1. Skill 更新检查与更新流程
+2. 环境变量检查（`TAPDB_MCP_KEY_CN` / `TAPDB_MCP_KEY_SG`）
+3. `list_projects` 验证秘钥有效性（海外用 `-r sg`）