@tapdb/tapdb-data-analysis 0.1.22 → 0.1.25

package/README.md

@@ -34,14 +34,17 @@ TapDB 有国内(CN)和海外(SG)两套部署，需配置认证密钥。
 
 ### 必需变量
 
-```bash
-# 国内(CN)部署密钥
-export TAPDB_MCP_KEY_CN="your-cn-mcp-key-here"
+密钥**必须写入 shell 配置文件**（zsh 用户写 `~/.zshrc`，bash 用户写 `~/.bashrc`），以确保所有终端会话和 AI 工具都能读取到：
 
-# 海外(SG)部署密钥
-export TAPDB_MCP_KEY_SG="your-sg-mcp-key-here"
+```bash
+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 在每次会话首次使用时会自动检查配置文件中是否存在密钥，如果缺失会自动写入。
+
 ### 验证配置
 
 ```bash
@@ -75,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.22",
+  "version": "0.1.25",
   "description": "TapDB 游戏数据分析 AI Agent Skill - 查询和分析 TapDB 中的游戏运营数据（活跃/留存/付费/来源/LTV 等）",
   "keywords": [
     "tapdb",

package/tapdb-data-analysis/SKILL.md

@@ -6,12 +6,12 @@ description: >
   玩家行为、广告变现等指标。支持国内和海外两套数据源。
   当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告时使用此技能。
   触发关键词：TapDB、DAU、MAU、留存、付费、收入、ARPU、LTV、活跃、新增、来源、玩家行为、
-  版本分布、鲸鱼用户、广告变现、运营概览、游戏数据分析。
+  版本分布、鲸鱼用户、广告变现、游戏数据分析。
 ---
 
 # TapDB 数据分析
 
-> Skill 版本：v0.1.21
+> Skill 版本：v0.1.25
 
 通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏的活跃、留存、付费、来源等指标数据并分析。
 
@@ -49,7 +49,11 @@ rm -rf package tapdb-tapdb-data-analysis-*.tgz
 [ -z "$TAPDB_MCP_KEY_SG" ] && echo "❌ SG 未设置" || echo "✅ SG 已配置"
 ```
 
-缺少则**停止操作**，引导配置：秘钥在 **TapDB 页面右上角 → 账号设置 → 秘钥管理**。国内 CN/海外 SG 各需独立秘钥。用户提供后根据 `$SHELL` 写入对应 shell 配置文件并 `source` 生效，然后运行 `list_projects` 验证。
+缺少则**停止操作**，引导配置：秘钥在 **TapDB 页面右上角 → 账号设置 → 秘钥管理**。国内 CN/海外 SG 各需独立秘钥。用户提供后按步骤 3 写入 shell 配置文件并验证。
+
+### 3. 持久化检查
+
+环境变量必须写入 shell 配置文件（根据 `$SHELL` 判断，zsh → `~/.zshrc`，bash → `~/.bashrc`），确保重启终端 / 新会话后仍可用。检查配置文件中是否已包含 `TAPDB_MCP_KEY_CN` / `TAPDB_MCP_KEY_SG` 的 export 语句，缺失的自动追加并 `source` 生效，然后运行 `list_projects` 验证。
 
 ## 工作流程
 
@@ -141,7 +145,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":[]}'
 ```
 
@@ -155,7 +158,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` |

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

@@ -46,6 +46,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:
@@ -433,11 +440,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 +659,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 +757,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 +796,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,