@tapdb/tapdb-data-analysis 0.1.28 → 0.1.30

package/package.json

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

package/tapdb-data-analysis/SKILL.md

@@ -11,7 +11,7 @@ description: >
 
 # TapDB 数据分析
 
-> Skill 版本：v0.1.28
+> Skill 版本：v0.1.30
 
 通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏指标数据并分析。
 
@@ -67,7 +67,7 @@ npm view @tapdb/tapdb-data-analysis version --registry https://registry.npmjs.or
 1. 先查 60 天**汇总趋势**（当前30天 + 上一周期30天，优先周粒度）：DAU→`active -g time --quota dau --group-unit week`，收入→`income -g time --group-unit week`，留存→`retention -g activation_time --group-unit week`，新增→`source -g activation_time --group-unit week`
 2. 按 `analysis_guide.md` 异常检测方法判断，先检查节假日效应（周粒度无法定位时再按日）
 3. 需要定位异常日期/用户要求按日 → 对异常区间切到按日（`--group-unit day`），并缩小时间窗定位异常日期
-4. 需要解释原因 → 做维度下钻：`-g <维度> --limit 10`（一次只查一个维度；默认 Top10）
+4. 需要解释原因 → 做维度下钻：`-g <维度> --limit 10`（一次只查一个维度；Top10 仅作为候选池），报告只输出通过噪音过滤阈值的 Top3-5 异常维度（详见 `references/output_rules.md`「维度下钻噪音过滤」）
 5. 输出执行摘要式报告
 
 ### C: 版本/卡池/活动分析
@@ -163,16 +163,17 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 
 目标：用**最省 token** 的查询顺序先定位问题，再逐步下钻；避免一上来拉按日/全量/多维明细。
 
-- 第一次查询：只返回**汇总 + Top10**
+- 第一次查询：只返回**汇总 + Top10**（Top10 仅作为候选池）
   - 汇总：优先用更粗时间粒度（`--group-unit week/month`）或更窄时间窗，而不是直接按日拉满大范围
   - Top10：需要维度分布时，加 `--limit 10`（如 `-g activation_channel --limit 10`）
-- 维度分组：一次只下钻一个维度，只看 **Top10**（`--limit 10`）；需要更多再迭代
+- 维度分组：一次只下钻一个维度，查询最多 Top10（`--limit 10`）；报告只写通过阈值过滤的 Top3-5 异常维度（其余维度一句话概括“已检查，差异不大/已过滤”）
+- 下钻噪音过滤阈值：按 `references/output_rules.md`「维度下钻噪音过滤（硬规则）」执行（只报异常维度、Top3-5、阈值过滤；禁止全量罗列）
 - 按日明细：只在需要定位**异常日期**/用户明确要求**按日趋势**时使用；先用周/月趋势锁定区间，再切到 `day` 并缩小时间窗
 - 需要完整明细：只在必须时才用 `--no-truncate`，并同时缩小时间范围/limit，避免上下文爆炸
 
 ## 数据截断规则
 
-脚本**默认自动截断**，`_truncation` 字段含总行数、省略行数和关键列 min/max/avg。
+脚本**默认自动截断**，`_truncation` 字段包含总行数与省略行数。TapDB API 会在结果末尾附带**汇总行**（分组字段为 `null`），脚本截断时会保留该汇总行。
 
 | 场景 | 阈值 | 方式 |
 |------|------|------|
@@ -182,7 +183,7 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 
 - 不加 `--all-retention` 通常仅返回 `DR1-DR30 + DR60/90/120/150/180`；加上后会额外补齐 `DR31-DR59`（及对应 `_newDevice/_rate` 列）。
 
-- 分析时利用 `_truncation.summary` 统计量，不要仅基于可见行下结论
+- 汇总数据以 API 返回的汇总行为准（分组字段为 `null`），不要在本地再计算汇总
 - 多次查询：每次先提取关键数值再下一个查询，不累积原始数据
 - 版本分布：一次性查询，不按天拆分（除非用户要求"按日趋势"）
 - 需完整数据加 `--no-truncate`
@@ -192,6 +193,7 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 - **货币转换**：默认将金额转为人民币（CNY）。通过 `--exchange-to-currency` 可切换目标货币（如 USD/JPY/EUR），传 `none` 禁用转换返回原始金额。影响 income/source/user_value/life_cycle/ad_monet 等含金额字段的接口
 - `filters` 即使无条件也必须传 `[]`，否则 500
 - `group` 必传。retention/source 不传 `-g` 时自动用 `activation_time`，其他默认 `time`
+- `life_cycle` 在 `-g activation_os` 时仅支持 `--quota payment_cvs_rate`（其他 quota 会 500）
 - filters 格式: `{"col_name":"...", "data_type":"string|number|bool|date", "calculate_symbol":"include|un_include", "ftv":[...]}`
 - 各接口维度不同，不支持的维度返回 500。**先 `describe` 确认**
 

package/tapdb-data-analysis/references/analysis_guide.md

@@ -145,7 +145,7 @@
 1. 查询特定维度的分组数据
 2. 识别各维度值的异常
 3. 计算贡献度（该维度值占整体比例 × 下降幅度）
-4. 返回 Top 问题维度值
+4. 返回 Top3-5 问题维度值（只输出异常维度，阈值过滤）
 
 **下钻诊断漏斗**（按优先级执行）：
 
@@ -181,6 +181,15 @@
    - ✅ 真问题 = 占比↑ AND 性能↓
    - ❌ 虚警 = 占比↑ BUT 性能不变（数学效应，忽略）
 
+**下钻噪音过滤阈值（硬规则，必须遵守）**：
+
+- **只输出异常维度**：未发现问题的维度值一律不展示；用 1 句话概括“其余维度差异不大/已过滤”
+- **阈值过滤**：
+  - 占比变化 < 5% 且性能变化 < 10% 的维度不报告
+  - 占比 < 5% 的小众维度不报告（除非性能恶化超过 50%）
+- **聚焦 TOP 问题**：每一层下钻最多只报告 Top3-5 个最严重的问题维度值
+- **禁止全量罗列**：不允许把所有维度值都贴出来
+
 **异常时优先检查的维度**：
 
 | 异常指标 | 优先检查维度 | 备注 |

package/tapdb-data-analysis/references/output_rules.md

@@ -183,3 +183,17 @@
 ## 9) 失败重试（与工具调用协作）
 
 - 同一查询连续失败 2 次即停止重试，继续用已有数据完成任务（详见 `references/analysis_guide.md`）
+
+---
+
+## 10) 维度下钻噪音过滤（硬规则）
+
+当输出“维度下钻/异常来源”类结论或表格时，必须遵守：
+
+- **只输出异常维度**：未发现问题的维度值一律不展示；用 1 句话概括“其余维度差异不大/已过滤”
+- **阈值过滤**：
+  - 占比变化 < 5% 且性能变化 < 10% 的维度不报告
+  - 占比 < 5% 的小众维度不报告（除非性能恶化超过 50%）
+- **聚焦 TOP 问题**：只报告 TOP 3-5 个最严重的问题维度值
+- **禁止全量罗列**：不允许把所有维度值都贴出来；如确需补充，放到附录并用 `<details>` 折叠
+- **无异常的表述**：若没有维度值通过阈值过滤，写“各维度表现一致，没有哪个特别差”，不要硬贴表格

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

@@ -83,21 +83,7 @@ _HEAD = 15
 _TAIL = 15
 
 
-def _numeric_summary(rows, limit=6):
-    """Compute min/max/avg for first N numeric columns."""
-    if not rows:
-        return {}
-    keys = [k for k, v in rows[0].items() if isinstance(v, (int, float))][:limit]
-    out = {}
-    for k in keys:
-        vals = [r[k] for r in rows if isinstance(r.get(k), (int, float))]
-        if vals:
-            out[k] = {"min": min(vals), "max": max(vals),
-                       "avg": round(sum(vals) / len(vals), 2)}
-    return out
-
-
-def _slim_rows(rows, cmd_type):
+def _slim_rows(rows, cmd_type, group_alias=None):
     """Truncate row count; time-series keeps head+tail, others keep head."""
     if not rows:
         return rows, None
@@ -110,7 +96,24 @@ def _slim_rows(rows, cmd_type):
         rows = rows[:cap] + [f"... 省略 {omit} 条 ..."]
         return rows, {"total_rows": total, "omitted": omit}
 
-    has_time = bool(_TIME_FIELDS & set(rows[0].keys()))
+    total = len(rows)
+
+    # TapDB API often appends a summary row at the end (group field is null).
+    # Keep that row (API-provided) when truncating.
+    summary_row = None
+    group_key = group_alias
+    if group_key and isinstance(rows[-1], dict) and group_key in rows[-1] and rows[-1].get(group_key) is None:
+        summary_row = rows[-1]
+        rows = rows[:-1]
+    else:
+        # Best-effort fallback when caller didn't provide group_alias.
+        for time_key in _TIME_FIELDS:
+            if time_key in rows[-1] and rows[-1].get(time_key) is None:
+                summary_row = rows[-1]
+                rows = rows[:-1]
+                break
+
+    has_time = bool(rows and (_TIME_FIELDS & set(rows[0].keys())))
     if cmd_type == "whale_user":
         cap = _MAX_WHALE_ROWS
     elif has_time:
@@ -118,17 +121,19 @@ def _slim_rows(rows, cmd_type):
     else:
         cap = _MAX_GROUP_ROWS
     if len(rows) <= cap:
+        if summary_row is not None:
+            return rows + [summary_row], None
         return rows, None
 
-    total = len(rows)
-    summary = _numeric_summary(rows)
     if has_time:
-        omit = total - _HEAD - _TAIL
+        omit = len(rows) - _HEAD - _TAIL
         rows = rows[:_HEAD] + [{"_": f"... 省略 {omit} 行 ..."}] + rows[-_TAIL:]
     else:
-        omit = total - cap
+        omit = len(rows) - cap
         rows = rows[:cap] + [{"_": f"... 省略 {omit} 行 ..."}]
-    return rows, {"total_rows": total, "omitted": omit, "summary": summary}
+    if summary_row is not None:
+        rows.append(summary_row)
+    return rows, {"total_rows": total, "omitted": omit}
 
 
 def _list_of_lists_to_dicts(lol):
@@ -177,7 +182,7 @@ def _rebuild(resp, path, rows, info):
     return result
 
 
-def truncate_response(resp, cmd_type=None):
+def truncate_response(resp, cmd_type=None, group_alias=None):
     """Truncate API response to save context window tokens."""
     if not resp or (isinstance(resp, dict) and resp.get("error")):
         return resp
@@ -186,7 +191,7 @@ def truncate_response(resp, cmd_type=None):
         return resp
 
     info = {}
-    rows, row_info = _slim_rows(rows, cmd_type)
+    rows, row_info = _slim_rows(rows, cmd_type, group_alias=group_alias)
     if row_info:
         info.update(row_info)
     if not info:
@@ -466,7 +471,7 @@ ENDPOINT_CAPS = {
             "lang_system": "过滤值会自动翻译，可直接用展示名",
         },
         "group_notes": {
-            "activation_os": "分组仅支持 time/activation_time/activation_os 三个维度",
+            "activation_os": "仅当 quota=payment_cvs_rate 时支持；（建议改用 time/activation_time）",
         },
         "unsupported_note": "分组仅支持 time/activation_time/activation_os；过滤不支持 activation_app_version/first_server/current_server/utmsrc/login_type/payment_source",
     },
@@ -572,7 +577,10 @@ def do_query(args, endpoint_path, extra=None, cmd_type=None):
     url = f"{base_url}/mcp/op/{endpoint_path}"
     result = http_request("POST", url, {"MCP-KEY": key}, body)
     if not getattr(args, "no_truncate", False):
-        result = truncate_response(result, cmd_type or endpoint_path)
+        group_alias = None
+        if isinstance(body.get("group"), dict):
+            group_alias = body["group"].get("col_alias")
+        result = truncate_response(result, cmd_type or endpoint_path, group_alias=group_alias)
     output(result)
 
 
@@ -633,6 +641,13 @@ def cmd_whale_user(args):
 
 
 def cmd_life_cycle(args):
+    if getattr(args, "group_by", None) == "activation_os" and getattr(args, "quota", None) != "payment_cvs_rate":
+        output({
+            "error": True,
+            "message": "life_cycle 接口在 -g activation_os 时仅支持 --quota payment_cvs_rate（其他 quota 会 500）",
+            "hint": "请改用 --quota payment_cvs_rate 或改用 -g time / -g activation_time",
+        })
+        return
     do_query(args, "life_cycle", {"quota": args.quota})