@tapdb/tapdb-data-analysis 0.1.29 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapdb/tapdb-data-analysis",
-  "version": "0.1.29",
+  "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.29
+> 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,10 +163,11 @@ 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，避免上下文爆炸
 

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>` 折叠
+- **无异常的表述**：若没有维度值通过阈值过滤，写“各维度表现一致，没有哪个特别差”，不要硬贴表格