# TapDB AI 数据分析 Skill

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

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

## 安装

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

```bash
# 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 国内和海外环境分别使用独立密钥：

```bash
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`，可显式配置：

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

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

## 验证

```bash
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` 同步通用知识库，并按功能模块读取当前预置埋点定义：

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

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

详细参数请运行：

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

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