# TapTap Data Skills

一键安装 TapTap 数据团队维护的 Skill（数据与埋点查询、分析、报告等），同步所需 Skill 资产与 MCP 服务，并适配本机检测到的 AI 编辑器（Claude Code / Codex CLI / OpenClaw / Cursor）。

npm 包只包含安装器与公开 catalog；`SKILL.md`、知识库、references、脚本和同级配置文件会在安装/更新时通过 DView MCP 服务鉴权下载，不再随 npm 包发布。

> **建议使用命令行手动安装，避免 Token 泄露。**

## 1. 选择要安装的 Skill

```bash
npx @taptap/data-skills@latest list --available
```

当前可安装的 Skill：

| Skill | 说明 | 详情 |
| --- | --- | --- |
| `taptap-data-analysis` | TapTap 业务数据查询，适用于指标口径、基础下钻分析。 | [§5.1](#51-taptap-data-analysis) |
| `taptap-data-tracking-analysis` | TapTap 埋点事件分析，支持 PV/UV/CTR 与维度拆分，覆盖客户端、TapSDK、Maker IDE、APM 等场景。使用该 Skill 需一并安装 `dw-tracking-search`。 | [§5.2](#52-taptap-data-tracking-analysis) |
| `dw-tracking-search` | TapTap 埋点查找，支持跨平台点位查询，返回上报字段、查询 SQL、元数据链接等信息。 | [§5.3](#53-dw-tracking-search) |
| `taptap-data-find-table` | TapTap 数仓公共层找表，适用于按分析/开发场景推荐 DWD/DIM/DWS/DWT 表、用法和避坑。 | [§5.4](#54-taptap-data-find-table) |
| `taptap-data-report` | TapTap 数据报告与可视化生成，适用于把已有数据结果渲染成本地报告包、图表或看板。 | [§5.5](#55-taptap-data-report) |
| `dw-bitable-sync` | 把飞书多维表格导入为后续可以直接分析的数据表。 | [§5.6](#56-dw-bitable-sync) |

## 2. 安装 Skill

```bash
npx @taptap/data-skills@latest add <skill-name>
```

首次执行会从 DView MCP 服务下载 Skill bundle，安装 `SKILL.md`、链接受管资产并写入编辑器 MCP 配置；再次执行只做增量同步。

安装补充说明：

**2.1 鉴权与 OpenClaw**

默认使用 SSO，首次会拉起浏览器登录。**OpenClaw / 容器 / CI 等无浏览器时**，会提示输入 `DVIEW_MCP_TOKEN`【Token 可以在「DView平台」-「Data AI Agent 权限管理」中自助创建】。

以 OpenClaw 为例，首次安装可能出现两次交互，之后无需重复配置：

1. 输入 `DVIEW_MCP_TOKEN`（隐藏输入，不进入 shell history）
2. 若未安装 `openclaw-mcp-tools` plugin，会询问是否自动安装。输入 `y` 后会执行 `openclaw plugins install` 与 `openclaw config set`，完成后按提示重启：
   ```bash
   openclaw gateway restart
   ```

> 若 `openclaw-mcp-tools` plugin 已存在，data-skills 不会覆盖现有配置；它会打印命令，供你手动追加 server entry。

**2.2 `taptap-data-analysis` Skill 旧版本迁移**

已安装过该 Skill 的用户，可以用下面命令升级迁移到 `@taptap/data-skills`：

```bash
npm config delete @taptap:registry --location=user
npx @taptap/data-skills@latest migrate
```

**2.3 指定编辑器**

默认安装到本机检测到的所有 host，也可以显式指定：

```bash
npx @taptap/data-skills@latest add <name...> --agent claude-code cursor
```

`<name...>` 可传一个或多个 skill 名，多个 skill 会顺序安装并复用同一次认证结果。

支持的 host：`claude-code` / `cursor` / `codex` / `openclaw`

## 3. 管理已安装的 Skill

```bash
npx @taptap/data-skills@latest list --available     # Skill 清单（包含安装信息）
npx @taptap/data-skills@latest info <name>          # 某个 skill 详情
npx @taptap/data-skills@latest update [<name...>]   # 升级到最新版（空 = 全部）
npx @taptap/data-skills@latest remove <name>        # 卸载
```

## 4. 排障

```bash
npx @taptap/data-skills@latest doctor                       # 一键自检
npx @taptap/data-skills@latest doctor --report > report.md  # 脱敏报告（无 token / 主机名 / 私有路径）
```

把 `report.md` 发给 TapTap 数据团队 maintainer 即可定位大部分问题。

## 5. Skill 详情

### 5.1 `taptap-data-analysis`

**用途**：用自然语言查询 TapTap 业务核心指标（DAU、留存、下载、新增等），覆盖指标口径解释、按维度下钻和数仓表查询。

**典型问法**：

- 指标查询："昨天 DAU 多少？" / "上周留存率趋势" / "Maker 日活多少" / "PC DAU 多少"
- 下钻分析："DAU 为什么下降了" / "按平台看 DNU" / "按渠道拆分留存" / "PC 游戏下载 Top 10"
- 表 / SQL 查询："XX 表有哪些字段" / "帮我写个按渠道看 DNU 的 SQL"
- 概念 / 口径："小游戏和 Maker 有什么区别？" / "DAU 的口径是什么？" / "留存怎么算的？"

**覆盖业务域与主要指标**：

| 业务域 | 主要指标 |
| --- | --- |
| TapTap 大盘活跃新增（移动端） | DAU / DNU / MAU / 留存 / LT / 版本覆盖 / 渗透率 / 使用时长 / 唤活 等 |
| 商店（移动端） | 下载数 / 更新数 / 预约数 / 完成率 / 资源位 等 |
| TapTap Maker | Maker 日活 / Maker 小游戏 / 创作者 / 论坛 / Maker IDE 创作 等 |
| 小游戏 | 小游戏 DAU / 渗透率 / 留存 / LT / 启动 / 排行 / 新进游戏量 / 广告曝光 / 广告收入 / eCPM / 人均曝光 / 接入游戏数 / 可提现余额 / 风险监控 等 |
| TapTap PC | PC DAU / PC DNU / PC 留存 / PC 游戏下载 / PC 更新 / PC 启动 / PC 预约 等 |
| Ops ⚠️ | 游戏运营 / 促活拉新 / 首发 / 用户画像 / SDK 激活 / Steam 直购·心愿单 / PC 游戏 DAU·DNU·留存 / DLC·捆绑包商品漏斗与订单 等 |
| 社区内容 | 内容曝光 / 点击 / uvCTR / 互动（点赞 / 回复 / 分享 / 收藏）/ 发布内容数 / 发布作者数 / 社区核心活跃 / 留存 / 渗透率 等 |
| TapSDK ⚠️ | 活跃设备数 / 活跃游戏数 / 活跃厂商数 / 累计活跃 / API 调用次数与成功率 等（含移动端与 TapTap PC 端两套独立体系） |

> 暂不覆盖：云玩 / 搜索 / 沙盒（规划中）。

> ⚠️ **域触发词限制（Domain Gate）**：`TapSDK` 和 `Ops` 两个域的指标与其他域存在名称相似性，为避免路由混淆，Skill 要求问题中必须出现明确触发词才能路由到该域：
> - **TapSDK 域**：问题需包含 `TapSDK` 或 `SDK`（不区分大小写）
> - **Ops 域**：问题需包含 `Ops`（不区分大小写）
>
> 例：问"活跃游戏数"不会路由到 TapSDK；需改为"**TapSDK** 活跃游戏数"。查 Ops 指标时需说"**Ops** SDK激活数"或"**Ops** 全链路"。

**不适用**：

- 埋点事件分析（PV / UV / CTR、控件 / 展位 / object_type）→ 使用 `taptap-data-tracking-analysis`
- 修改 SQL 代码、数仓建表、BI 工具操作

**调用方式**：自然语言提问即可，或显式输入 `/taptap-data-analysis`。

---

### 5.2 `taptap-data-tracking-analysis`

**用途**：TapTap 埋点分析中的**事件分析**功能 —— 输出 PV / UV / CTR、聚合指标、按维度拆分等结果，并提供埋点口径解释。

> ⚠️ 当前仅覆盖事件分析；漏斗 / 留存 / 路径 / 归因 / 用户细查均不支持，相关问题会被拒答并引导到 DView 平台。

**覆盖场景**：

| 场景 | 信号示例 | 典型问法 |
| --- | --- | --- |
| 客户端业务（Android / iOS / PC / Web） | 埋点 / 展位 / 控件 / 按钮 / object_type / page_booth | "昨天 Android 下载按钮点击 UV" / "最近 7 天 Android 首页推荐位游戏卡片曝光 PV 趋势" |
| TapSDK | TapPayment / TapLogin / sdk_project | "昨天 Android TapPayment 支付成功 UV" / "昨天 Android TapLogin 登录成功 UV" |
| APM 技术 | 应用性能监控 | "Android 最近 3 天启动时长 P95" / "昨天 Android crash 次数按 app 版本 Top 5" |
| Maker 创作 | Maker IDE 创作 | "Maker 上周创作数据趋势" |

> 如有疑问请咨询数据团队。

**两类用法**：

- **取数（query）**："PC 端首页推荐展位的曝光 UV 是多少" → 跑 SQL 出数。需明确**平台**（android / ios / pc / web）与**时间范围**（如最近 7 天 / 2026-04-22 单日），缺失时 Skill 会主动追问。
- **问口径（definition）**："这个埋点的触发时机是什么 / 主键参数有哪些" → 仅基于元数据回答，不跑 SQL。

**不适用**：业务聚合指标（DAU / LT / 全站留存等）请用 `taptap-data-analysis`；数仓维度表 / BI 工具操作 / 设计文档撰写不在覆盖范围。

**依赖**：需同时安装 `dw-tracking-search`（埋点查找前置），由本 Skill 自动调用，用户无需直接使用。

**调用方式**：自然语言提问即可，或显式输入 `/taptap-data-tracking-analysis`。

---

### 5.3 `dw-tracking-search`

作为 `taptap-data-tracking-analysis` 的埋点查找前置依赖，由上层 Skill 自动调用，用户通常无需直接使用。也支持独立查询：用自然语言问"游戏详情页下有哪些埋点？" / "点击下载这个事件有哪些参数？"，返回结构化的埋点点位、上报字段与元数据链接。

---

### 5.4 `taptap-data-find-table`

**用途**：根据自然语言场景推荐 TapTap 数仓公共层（DWD / DIM / DWS / DWT）表，说明推荐理由、典型用法、配套维表和使用避坑。

**典型问法**：

- "Android / iOS 留存用哪张表？"
- "想按设备粒度看游戏下载来源，用哪张表？"
- "近实时技术日志分析应该查什么表？"
- "tap_dw.dws_uad_device_active_nd 怎么用，有没有示例 SQL？"

**不适用**：

- 业务指标直接取数、趋势分析、下钻归因 → 使用 `taptap-data-analysis`
- 埋点点位、事件参数、上报字段查询 → 使用 `dw-tracking-search`
- 出图、做报告、生成看板 → 使用 `taptap-data-report`

**依赖**：需要 `taptap-data-query` MCP server，用于记录问答链路。

**调用方式**：自然语言提问即可，或显式输入 `/taptap-data-find-table`。

---

### 5.5 `taptap-data-report`

**用途**：把已经准备好的数据、查询结果或上游 Skill 的分析结果生成报告、图表或看板。默认产出本地报告资产包，包含 `chart.yaml`、`queries.yaml`、`meta.yaml`、`report.md`、`report.html`。

**典型问法**：

- "帮我生成一份 DAU 趋势报告"
- "把这组查询结果做成可视化"
- "根据刚才的分析结果出一个看板"
- "继续修改这份报告的图表和结论"

**不适用**：

- 直接查询业务指标、跑 SQL、分析原因 → 使用 `taptap-data-analysis`
- 查找 DWD / DIM / DWS / DWT 公共层表 → 使用 `taptap-data-find-table`
- 埋点事件 PV / UV / CTR 分析 → 使用 `taptap-data-tracking-analysis`

**依赖**：需要 `taptap-data-query` MCP server。默认只生成本地报告包；只有用户明确要求上传、读取或删除 OSS 报告时，才会使用云端文件工具。

**调用方式**：自然语言提问即可，或显式输入 `/taptap-data-report`。

---

### 5.6 `dw-bitable-sync`

**用途**：把一个飞书多维表格变成后续可以直接分析的数据表。适合临时把项目排期、运营名单、人工维护清单等表格导入数仓，之后继续让 AI 帮你查数或分析。

**典型问法**：

- "把这个飞书多维表格同步到数仓：https://xxx.feishu.cn/base/..."
- "把知识库里的这个多维表格同步到数仓：https://xxx.feishu.cn/wiki/..."

**使用方式**：

- 复制飞书多维表格的 `/base/` 链接，或知识库中指向多维表格的 `/wiki/` 链接发给 AI。
- AI 会先预览字段映射和可能的提醒，不会直接写入。
- 你回复确认后，才会开始同步。
- 完成后会告诉你生成的数据表名，可以继续追问分析问题。

**不适用**：

- 指向文档、电子表格等非多维表格节点的飞书 `/wiki/` 链接。
- 定时或自动同步；当前是一次性导入。
- 没有访问权限的多维表格；首次使用时可能需要按提示完成授权。

**调用方式**：自然语言提供飞书多维表格 `/base/` 或 `/wiki/` URL 即可，或显式输入 `/dw-bitable-sync`。