TapDB AI 数据分析 Skill

TapDB 数据查询与分析 Skill，支持常用运营指标和 TapDB 的事件分析、物理事件与属性维护、虚拟属性、用户分群、标签、报表与看板能力，并提供埋点指引（事件接入与登记、埋点方案与上报自查，覆盖预置事件与自定义事件）。

本版本不提供任意 SQL 查询、表发现或分析 SQL 导出功能。

安装

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

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

# Cursor
cp -r tapdb-data-analysis ~/.cursor/skills-cursor/tapdb-data-analysis

也可以安装发布的 npm 包后，从包内复制同名目录。

环境变量

TapDB 国内和海外环境分别使用独立密钥：

export TAPDB_MCP_KEY_CN="your-cn-mcp-key"
export TAPDB_MCP_KEY_SG="your-sg-mcp-key"

建议把变量写入 ~/.zshrc 或 ~/.bashrc，再重新加载 shell 配置。

Python CA 证书

CLI 优先使用 Python/系统默认 CA。如果当前 Python 的证书库为空且环境中已安装 certifi，会自动回退到 certifi CA。

如仍返回 certificate_verify_failed，可显式配置：

python3 -m pip install --user certifi
export SSL_CERT_FILE="$(python3 -m certifi)"

也可修复当前 Python 安装的系统证书。不要通过关闭 TLS 证书校验规避问题。

验证

python3 tapdb-data-analysis/scripts/tapdb_query.py --help
python3 tapdb-data-analysis/scripts/tapdb_query.py describe
python3 tapdb-data-analysis/scripts/tapdb_query.py list_projects -r cn
python3 tapdb-data-analysis/scripts/tapdb_query.py list_projects -r sg

完整命令列表

| 命令 | 类型 | 说明 | |---|---|---| | list_projects | 项目与知识 | 列出当前可访问的项目 | | download_skills | 项目与知识 | 下载项目 Skills zip | | skills_last_modified | 项目与知识 | 查询项目 Skills 最后修改时间 | | sync_skills | 项目与知识 | 同步项目 Skills 到本地 | | sync_common_skills | 项目与知识 | 同步通用知识库(埋点指南)到本地（自动判断版本，有更新才下载） | | common_skills_last_modified | 项目与知识 | 查询通用知识库最后修改时间 | | download_common_skills | 项目与知识 | 下载通用知识库 zip | | season_info | 项目与知识 | 获取版本和赛季信息 | | mani_events | 项目与知识 | 获取运营事件列表 | | active | 运营指标 | 查询 DAU、WAU、MAU、HAU | | op_overview | 运营指标 | 查询收入、活跃、新增概览 | | retention | 运营指标 | 查询留存数据 | | income | 运营指标 | 查询收入、付费人数、ARPU、ARPPU | | source | 运营指标 | 查询新增来源数据 | | player_behavior | 运营指标 | 查询游戏时长和启动次数 | | version_distri | 运营指标 | 查询版本分布 | | user_value | 运营指标 | 查询 LTV 和用户价值 | | whale_user | 运营指标 | 查询高付费用户排行 | | life_cycle | 运营指标 | 查询用户生命周期指标 | | cost | 广告与买量 | 查询买量成本 | | ad_data | 广告与买量 | 查询广告投放数据 | | ad_monet | 广告与买量 | 查询广告变现数据 | | bury_point_overview | 埋点排查 | 查询埋点接收、入库、异常、失败概览 | | bury_point_error_detail | 埋点排查 | 查询指定事件的错误字段和错误码明细 | | bury_point_real_time_status | 埋点排查 | 查询实时埋点监测开关状态 | | bury_point_real_time_switch | 埋点排查 | 开启或关闭实时上报明细监测 | | bury_point_real_time_detail | 埋点排查 | 查询实时上报明细 | | describe | 帮助 | 查看全部命令或指定命令的能力与参数 | | raw | 调试 | 调用指定 MCP API 路径；隐藏调试入口，常规查询应使用类型化命令 | | list_events | 元数据 | 列出物理、衍生、虚拟事件 | | list_props | 元数据 | 列出事件、账号、设备、用户属性 | | event_save | 元数据写入 | 新增物理事件 | | event_edit | 元数据写入 | 修改物理事件显示信息和属性关联 | | property_save | 元数据写入 | 新增物理属性 | | property_edit | 元数据写入 | 修改物理属性显示信息 | | event_quotas | 事件分析 | 获取事件分析可用指标 | | event_properties | 事件分析 | 获取指定事件可用属性 | | virtual_property_save | 元数据写入 | 校验并新建计算虚拟属性 | | list_clusters | 分群 | 列出用户分群 | | cluster_save | 分群 | 新增用户分群 | | cluster_edit | 分群 | 编辑用户分群 | | list_tags | 标签 | 列出用户标签 | | tag_info | 标签 | 查询用户标签详情 | | tag_save | 标签 | 新增用户标签 | | tag_edit | 标签 | 编辑用户标签 | | folder_list | 看板 | 获取看板文件夹列表 | | folder_save | 看板 | 新建看板文件夹 | | dashboard_save | 看板 | 新建看板 | | dashboard_share_detail | 看板 | 查看看板分享配置 | | dashboard_save_share | 看板 | 保存并回读验证看板分享设置 | | report_save | 报表 | 创建报表 | | report_edit | 报表 | 编辑报表 | | report_list | 报表 | 列出报表 | | dashboard_add_reports | 看板 | 添加或更新看板报表及布局 | | dashboard_report_setting | 看板 | 配置看板内报表的显示设置 | | dashboard_detail | 看板 | 获取看板详情与报表列表 | | report_detail | 报表 | 获取报表查询配置 | | dashboard_analysis | 看板 | 执行看板报表查询 | | event_analysis | 事件分析 | 执行独立事件分析查询 |

埋点指引

完整的埋点工作流见 tapdb-data-analysis/references/tracking_guide.md。具备项目代码访问权限时，应先扫描代码并识别实际功能模块，再使用 sync_common_skills 同步通用知识库，并按功能模块读取当前预置埋点定义：

python3 tapdb-data-analysis/scripts/tapdb_query.py sync_common_skills -r cn
ls .tapdb/skills/common/

预置事件的业务定义应以同步后的通用知识库为准；SDK 调用方式及自定义事件规范应根据当前平台与 SDK 版本查阅 TapTap 开发者中心。

详细参数请运行：

python3 tapdb-data-analysis/scripts/tapdb_query.py describe <command>

完整工作流与约束见 tapdb-data-analysis/SKILL.md 和 tapdb-data-analysis/references/。