TapDB AI 数据分析 Skill

本项目包含 TapDB 数据分析相关的 AI Agent Skill 工具

安装 Skill

方式一：Codex CLI

将 tapdb-data-analysis 目录复制到 Codex skills 目录：

cp -r tapdb-data-analysis ~/.codex/skills/tapdb-data-analysis

方式二：Cursor

将 tapdb-data-analysis 目录复制到 Cursor skills 目录：

# 方法 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 页面右上角 -> 账号设置 -> 秘钥管理 中可以找到，国内和海外分别需要各自的秘钥

必需变量

密钥必须写入 shell 配置文件（zsh 用户写 ~/.zshrc，bash 用户写 ~/.bashrc），以确保所有终端会话和 AI 工具都能读取到：

export TAPDB_MCP_KEY_CN="your-cn-mcp-key-here"   # 国内(CN)部署密钥
export TAPDB_MCP_KEY_SG="your-sg-mcp-key-here"   # 海外(SG)部署密钥

将上面两行写入对应的 shell 配置文件后执行 source 使其生效。

注意：仅在当前终端 export 而不写入配置文件的话，新终端窗口或 AI Agent 启动的 shell 会话将无法读取到密钥。Skill 在每次会话首次使用时会自动检查配置文件中是否存在密钥，如果缺失会自动写入。

验证配置

# 测试国内部署
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 游戏鲸鱼用户排行"
• "用 TapDB 查一下 XXX 游戏最近 30 天各媒体的买量成本和 ROI"

AI 会自动调用 tapdb_query.py 脚本查询数据并生成分析报告。

支持的查询类型

| 类型 | 子命令 | 说明 | |------|--------|------| | 活跃 | active | DAU/WAU/MAU/HAU | | 留存 | retention | 日留存(DR1-DR180)/周留存/月留存 | | 收入 | income | 收入/付费人数/ARPU/ARPPU/付费率 | | 来源 | source | 新增设备/新增用户/转化率 | | 玩家行为 | player_behavior | 游戏时长/启动次数 | | 版本分布 | version_distri | 各版本活跃设备分布 | | 用户价值 | user_value | LTV (N日贡献) | | 鲸鱼用户 | whale_user | 高付费用户排行 | | 生命周期 | life_cycle | 付费转化率/金额/累计 | | 买量成本 | cost | 花费/展示/点击/获客/留存/ROI（支持 --measurement-criteria device\|account 切换统计口径） | | 广告投放 | ad_data | 广告投放数据（cost 无数据时的回退方案） | | 广告变现 | ad_monet | 广告收入数据 |