@tapdb/tapdb-data-analysis 0.1.24 → 0.1.26

package/README.md

@@ -78,9 +78,7 @@ AI 会自动调用 `tapdb_query.py` 脚本查询数据并生成分析报告。
 | 来源 | `source` | 新增设备/新增用户/转化率 |
 | 玩家行为 | `player_behavior` | 游戏时长/启动次数 |
 | 版本分布 | `version_distri` | 各版本活跃设备分布 |
-| 运营概览 | `overview` | 收入/活跃/新增汇总 |
 | 用户价值 | `user_value` | LTV (N日贡献) |
 | 鲸鱼用户 | `whale_user` | 高付费用户排行 |
 | 生命周期 | `life_cycle` | 付费转化率/金额/累计 |
 | 广告变现 | `ad_monet` | 广告收入数据 |
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapdb/tapdb-data-analysis",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "TapDB 游戏数据分析 AI Agent Skill - 查询和分析 TapDB 中的游戏运营数据（活跃/留存/付费/来源/LTV 等）",
   "keywords": [
     "tapdb",

package/tapdb-data-analysis/SKILL.md

@@ -3,26 +3,26 @@ name: tapdb-data-analysis
 description: >
   TapDB 游戏数据分析技能。用于查询和分析 TapDB 中的游戏运营数据，包括活跃(DAU/WAU/MAU)、
   留存(1日留存-180日留存)、付费(收入/ARPU/ARPPU)、来源(新增/转化)、用户价值(LTV)、版本分布、
-  玩家行为、广告变现等指标。支持国内和海外两套数据源。
+  玩家行为、广告变现等指标。
   当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告时使用此技能。
   触发关键词：TapDB、DAU、MAU、留存、付费、收入、ARPU、LTV、活跃、新增、来源、玩家行为、
-  版本分布、鲸鱼用户、广告变现、运营概览、游戏数据分析。
+  版本分布、鲸鱼用户、广告变现、游戏数据分析。
 ---
 
 # TapDB 数据分析
 
-> Skill 版本：v0.1.24
+> Skill 版本：v0.1.25
 
-通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏的活跃、留存、付费、来源等指标数据并分析。
+通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏指标数据并分析。
 
 ## 环境要求
 
-- 查询脚本: `<SKILL_DIR>/scripts/tapdb_query.py`（纯标准库，无外部依赖）
-- Python 3（优先用 `python3`；如环境仅有 `python`，则用 `python`）
+- 查询脚本: `<SKILL_DIR>/scripts/tapdb_query.py`
+- Python 3（优先用 `python3`；否则用 `python`）
 - npm（用于 Skill 更新检查）
 - 认证密钥 `TAPDB_MCP_KEY_CN` / `TAPDB_MCP_KEY_SG`
 
-## 运行前检查（每次会话首次使用）
+## 运行前检查（每次讨论一个新话题或新一轮数据查询时使用）
 
 ### 1. Skill 更新
 
@@ -30,25 +30,13 @@ description: >
 npm view @tapdb/tapdb-data-analysis version --registry https://registry.npmjs.org/
 ```
 
-与本文件顶部 `Skill 版本` 对比，不同则更新：
+与本文件顶部 `Skill 版本` 对比，不同则更新本 Skill
 
-```bash
-cd /tmp && \
-npm pack @tapdb/tapdb-data-analysis@latest --registry https://registry.npmjs.org/ && \
-tar -xzf tapdb-tapdb-data-analysis-*.tgz && \
-cp -r package/tapdb-data-analysis/* <SKILL_DIR>/ && \
-rm -rf package tapdb-tapdb-data-analysis-*.tgz
-```
-
-更新后**重新读取** `<SKILL_DIR>/SKILL.md`，以新版本为准。告知用户"TapDB 数据分析 Skill 已更新到 vX.X.X"。详情：https://www.npmjs.com/package/@tapdb/tapdb-data-analysis
+更新后**重新读取** `<SKILL_DIR>/SKILL.md`，以新版本为准。告知用户"TapDB 数据分析 Skill 已更新到 vX.X.X"，并给出更新内容。
 
 ### 2. 环境变量
 
-```bash
-[ -z "$TAPDB_MCP_KEY_CN" ] && echo "❌ CN 未设置" || echo "✅ CN 已配置"
-[ -z "$TAPDB_MCP_KEY_SG" ] && echo "❌ SG 未设置" || echo "✅ SG 已配置"
-```
-
+检查 `TAPDB_MCP_KEY_CN` 和 `TAPDB_MCP_KEY_SG` 环境变量是否存在。
 缺少则**停止操作**，引导配置：秘钥在 **TapDB 页面右上角 → 账号设置 → 秘钥管理**。国内 CN/海外 SG 各需独立秘钥。用户提供后按步骤 3 写入 shell 配置文件并验证。
 
 ### 3. 持久化检查
@@ -57,15 +45,14 @@ rm -rf package tapdb-tapdb-data-analysis-*.tgz
 
 ## 工作流程
 
-1. **确认项目**: `list_projects` 获取项目列表（含 `id/name/appid/sticky/remark`）
+1. **确认项目**: `list_projects` 获取项目列表（含 `id/name/appid/sticky/remark`，若返回列表过长则先保存到本地再查找，避免截断导致找不到需要的项目）
    - 在 `name` 和 `remark` 中检索匹配，任一命中即为候选
    - 多候选时优先 `sticky: true`；仍有多个则对每个做轻量探测（如 7 天 DAU）：仅一个有数据→直接用；多个有数据→列出让用户选；全零→同样列出让用户选
 2. **识别场景**: 按「场景路由」判断分析路径
 3. **查看能力**: `describe <接口名>` 确认支持的指标/分组/过滤
 4. **调用脚本**: 查询数据
-5. **利用截断**: 输出中 `_truncation` 含总行数和 min/max/avg 统计量
-6. **分析**: 读 `references/metrics_glossary.md`（指标定义）、`references/analysis_guide.md`（方法论）和 `references/output_rules.md`（输出规范）
-7. **输出报告**: 按 `references/output_rules.md` 生成结论优先、可追溯的结构化报告
+5. **分析**: 读 `references/metrics_glossary.md`（指标定义）、`references/analysis_guide.md`（方法论）
+6. **输出报告**: 按 `references/output_rules.md` 生成结论优先、可追溯的结构化报告
 
 ## 场景路由
 
@@ -145,7 +132,6 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py life_cycle -p 2588 -s 2026-02-01 -e 2
 python3 <SKILL_DIR>/scripts/tapdb_query.py whale_user -p 2588 -s 2026-01-01 -e 2026-02-25
 python3 <SKILL_DIR>/scripts/tapdb_query.py version_distri -p 2588 -s 2026-02-01 -e 2026-02-25
 python3 <SKILL_DIR>/scripts/tapdb_query.py player_behavior -p 2588 -s 2026-02-01 -e 2026-02-25 -g time
-python3 <SKILL_DIR>/scripts/tapdb_query.py overview -p 2588 --app-id abc123 -s 2026-02-01 -e 2026-02-25
 python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"start_time":"2026-02-01 00:00:00.000","end_time":"2026-02-25 23:59:59.999","subject":"device","quota":"dau","group":{"col_name":"time","col_alias":"date","is_time":true,"trunc_unit":"day"},"is_de_water":false,"filters":[]}'
 ```
 
@@ -159,7 +145,6 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 | `source` | 来源/新增 | 通用参数 | `activation_time` |
 | `player_behavior` | 玩家行为 | `--quota behavior\|duration` | `time` |
 | `version_distri` | 版本分布 | 通用参数 | 按版本分组 |
-| `overview` | 运营概览 | `--app-id`, `--interval`, `--quota income\|active\|activation` | 独立接口 |
 | `user_value` | LTV | 通用参数 | `activation_time` |
 | `whale_user` | 鲸鱼用户 | 通用参数 | 无分组 |
 | `life_cycle` | 生命周期 | `--quota payment_amount\|payment_cvs_rate\|payment_cvs\|acc_payment` | `activation_time` |
@@ -171,13 +156,11 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 
 | 场景 | 阈值 | 方式 |
 |------|------|------|
-| 时间序列 | > 30 行 | 首5 + 尾5 |
+| 时间序列 | > 30 行 | 首15 + 尾15 |
 | 分组维度 | > 20 行 | 前20 |
 | 鲸鱼用户 | > 20 条 | 前20 |
-| 留存列 DR1-DR180 | 自动 | 仅 DR1/3/7/14/30/60/90 |
-| LTV 列 1-60_LTV | 自动 | 仅 LTV1/3/7/14/30/60/90 |
 
-- 不加 `--all-retention` 通常仅返回 `DR1-DR30 + DR60/90/120/150/180`；加上后会额外补齐 `DR31-DR59`（及对应 `_newDevice/_rate` 列）。对比列差异需同时加 `--no-truncate`。
+- 不加 `--all-retention` 通常仅返回 `DR1-DR30 + DR60/90/120/150/180`；加上后会额外补齐 `DR31-DR59`（及对应 `_newDevice/_rate` 列）。
 
 - 分析时利用 `_truncation.summary` 统计量，不要仅基于可见行下结论
 - 多次查询：每次先提取关键数值再下一个查询，不累积原始数据

package/tapdb-data-analysis/scripts/tapdb_query.py

@@ -12,7 +12,6 @@
 import argparse
 import json
 import os
-import re
 import sys
 import urllib.request
 import urllib.error
@@ -46,6 +45,13 @@ def get_config(region):
 
 def http_request(method, url, headers, body=None):
     try:
+        headers = dict(headers or {})
+        if not any(k.lower() == "user-agent" for k in headers):
+            headers["User-Agent"] = (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/122.0.0.0 Safari/537.36"
+            )
         data = json.dumps(body).encode("utf-8") if body else None
         req = urllib.request.Request(url, data=data, headers=headers, method=method)
         if data:
@@ -67,18 +73,14 @@ def output(data):
 
 # ── 数据截断 ────────────────────────────────────────────────
 
-_RE_DR = re.compile(r'^DR(\d+)')
-_RE_N_LTV = re.compile(r'^(\d+)_LTV$')
-_RETENTION_KEEP = {1, 3, 7, 14, 30, 60, 90}
-_LTV_KEEP = {1, 3, 7, 14, 30, 60, 90}
 _TIME_FIELDS = frozenset(("date", "time", "activation_time", "start_time",
                           "date_", "time_", "activation_time_", "start_time_"))
 
 _MAX_TIME_ROWS = 30
 _MAX_GROUP_ROWS = 20
 _MAX_WHALE_ROWS = 20
-_HEAD = 5
-_TAIL = 5
+_HEAD = 15
+_TAIL = 15
 
 
 def _numeric_summary(rows, limit=6):
@@ -95,33 +97,6 @@ def _numeric_summary(rows, limit=6):
     return out
 
 
-def _slim_columns(rows, cmd_type):
-    """Drop intermediate DR/LTV columns, keep key day columns only."""
-    if not rows or not isinstance(rows[0], dict):
-        return rows, None
-    sample = rows[0]
-    if cmd_type == "retention":
-        regex, keep_set, label = _RE_DR, _RETENTION_KEEP, "DR"
-    elif cmd_type == "user_value":
-        regex, keep_set, label = _RE_N_LTV, _LTV_KEEP, "LTV"
-    else:
-        return rows, None
-
-    matched = {}
-    for k in sample:
-        m = regex.match(k)
-        if m:
-            matched[k] = int(m.group(1))
-    kept_count = sum(1 for d in matched.values() if d in keep_set)
-    if len(matched) <= kept_count + 2:
-        return rows, None
-    keep_keys = {k for k in sample if k not in matched or matched.get(k) in keep_set}
-    removed = len(matched) - kept_count
-    rows = [{k: v for k, v in r.items() if k in keep_keys} for r in rows]
-    days = "/".join(str(d) for d in sorted(keep_set))
-    return rows, f"kept {label}{days}, removed {removed} other {label} columns"
-
-
 def _slim_rows(rows, cmd_type):
     """Truncate row count; time-series keeps head+tail, others keep head."""
     if not rows:
@@ -211,9 +186,6 @@ def truncate_response(resp, cmd_type=None):
         return resp
 
     info = {}
-    rows, col_msg = _slim_columns(rows, cmd_type)
-    if col_msg:
-        info["columns"] = col_msg
     rows, row_info = _slim_rows(rows, cmd_type)
     if row_info:
         info.update(row_info)
@@ -433,11 +405,6 @@ ENDPOINT_CAPS = {
         "description": "版本分布: 各版本活跃/新增设备数（专用接口，忽略 group 参数，固定按版本分组）",
         "returned_metrics": ["version", "allDevices", "newDevices", "upgradeDevices", "activeDevices", "NUDevices"],
     },
-    "overview": {
-        "description": "运营概览: 收入/活跃/新增汇总（需 app_id，独立接口不走通用分组）",
-        "quotas": ["income", "active", "activation"],
-        "extra_params": ["app_id (必需)", "interval (minute|hour|day|week|month)"],
-    },
     "user_value": {
         "description": "用户价值(LTV): N日贡献",
         "returned_metrics": ["activation", "N_LTV (1-60,90,120,150,180,210,240,270,300,330,360)"],
@@ -657,24 +624,6 @@ def cmd_player_behavior(args):
 def cmd_version_distri(args):
     do_query(args, "version_distri")
 
-
-def cmd_overview(args):
-    key, base_url = get_config(args.region)
-    body = {
-        "project_id": int(args.project_id),
-        "app_id": args.app_id,
-        "start_date": args.start,
-        "end_date": args.end,
-        "interval": args.interval,
-        "quota": args.quota,
-        "use_cache": not getattr(args, "no_cache", False),
-    }
-    result = http_request("POST", f"{base_url}/mcp/op/op_overview", {"MCP-KEY": key}, body)
-    if not getattr(args, "no_truncate", False):
-        result = truncate_response(result, "overview")
-    output(result)
-
-
 def cmd_user_value(args):
     do_query(args, "user_value")
 
@@ -773,18 +722,6 @@ def main():
     p = sub.add_parser("version_distri", help="版本分布: 各版本活跃设备数")
     add_common_args(p)
 
-    # overview
-    p = sub.add_parser("overview", help="运营概览: 收入/活跃/新增汇总")
-    p.add_argument("-p", "--project-id", required=True, help="项目ID")
-    p.add_argument("--app-id", required=True, help="应用ID (从 list_projects 获取)")
-    p.add_argument("-s", "--start", required=True, help="开始日期")
-    p.add_argument("-e", "--end", required=True, help="结束日期")
-    p.add_argument("--interval", default="day", choices=["minute", "hour", "day", "week", "month"],
-                    help="时间粒度 (默认 day)")
-    p.add_argument("--quota", default="income", choices=["income", "active", "activation"],
-                    help="概览类型 (默认 income)")
-    p.add_argument("--no-cache", action="store_true")
-
     # user_value (LTV)
     p = sub.add_parser("user_value", help="用户价值(LTV): N日贡献")
     add_common_args(p)
@@ -824,7 +761,6 @@ def main():
         "source": cmd_source,
         "player_behavior": cmd_player_behavior,
         "version_distri": cmd_version_distri,
-        "overview": cmd_overview,
         "user_value": cmd_user_value,
         "whale_user": cmd_whale_user,
         "life_cycle": cmd_life_cycle,