@tapdb/tapdb-data-analysis 0.1.25 → 0.1.27

package/package.json

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

package/tapdb-data-analysis/SKILL.md

@@ -3,7 +3,7 @@ name: tapdb-data-analysis
 description: >
   TapDB 游戏数据分析技能。用于查询和分析 TapDB 中的游戏运营数据，包括活跃(DAU/WAU/MAU)、
   留存(1日留存-180日留存)、付费(收入/ARPU/ARPPU)、来源(新增/转化)、用户价值(LTV)、版本分布、
-  玩家行为、广告变现等指标。支持国内和海外两套数据源。
+  玩家行为、广告变现等指标。
   当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告时使用此技能。
   触发关键词：TapDB、DAU、MAU、留存、付费、收入、ARPU、LTV、活跃、新增、来源、玩家行为、
   版本分布、鲸鱼用户、广告变现、游戏数据分析。
@@ -11,18 +11,18 @@ description: >
 
 # TapDB 数据分析
 
-> Skill 版本：v0.1.25
+> Skill 版本：v0.1.27
 
-通过 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` 生成结论优先、可追溯的结构化报告
 
 ## 场景路由
 
@@ -132,6 +119,13 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py describe active        # 查看接口
 | `--no-truncate` | 不截断输出 | |
 | `-r` | 区域 cn/sg | `-r sg` |
 
+### 时间范围硬规则（必须遵守）
+
+- ✅ 连续时间范围直接查询
+- ✅ TapDB 单次查询最长 **180 天**（包含起止日）
+- ❌ 不要把时间范围按周拆分成多次查询（需要周粒度：用 `--group-unit week` **一次性**范围查询）
+- ⚠️ 仅当用户明确要求“按日趋势/按天对比/定位异常日期”时才按天拆分；否则保持一次范围查询
+
 ### 查询示例
 
 ```bash
@@ -169,13 +163,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
@@ -74,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):
@@ -102,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:
@@ -218,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)