@tapdb/tapdb-data-analysis 0.1.29 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapdb/tapdb-data-analysis",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "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.31
 
 通过 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

@@ -14,10 +14,11 @@
 
 ### 数据失败处理
 
-1. **部分成功**：基于已有数据输出分析，注明缺失部分
-2. **全部失败**：如实告知原因，不编造分析
+1. **部分成功必须继续输出**：只要任一查询成功返回数据，就必须基于已有数据继续输出分析；在输出开头披露缺失（如 `⚠️ XX 数据未获取到（原因：…），以下分析基于已获取数据`）。**绝对不允许**在有成功数据的情况下声称“没有数据/没查到”。
+2. **全部失败才停止**：全部查询失败时，如实告知失败原因，格式：`查询失败：[具体错误原因]，请稍后重试或联系管理员`。**禁止**编造分析或让用户“自行准备数据”。
 3. **重试收敛**：同一查询连续失败 2 次即停止，标记为"数据未获取到"，继续用已有数据完成任务
 4. ❌ 禁止通过拆分时间范围来"绕过"失败的查询
+5. 更细的输出纪律见 `references/output_rules.md` 的「失败/输出纪律（最高优先级）」
 
 ---
 
@@ -145,7 +146,7 @@
 1. 查询特定维度的分组数据
 2. 识别各维度值的异常
 3. 计算贡献度（该维度值占整体比例 × 下降幅度）
-4. 返回 Top 问题维度值
+4. 返回 Top3-5 问题维度值（只输出异常维度，阈值过滤）
 
 **下钻诊断漏斗**（按优先级执行）：
 
@@ -181,6 +182,15 @@
    - ✅ 真问题 = 占比↑ AND 性能↓
    - ❌ 虚警 = 占比↑ BUT 性能不变（数学效应，忽略）
 
+**下钻噪音过滤阈值（硬规则，必须遵守）**：
+
+- **只输出异常维度**：未发现问题的维度值一律不展示；用 1 句话概括“其余维度差异不大/已过滤”
+- **阈值过滤**：
+  - 占比变化 < 5% 且性能变化 < 10% 的维度不报告
+  - 占比 < 5% 的小众维度不报告（除非性能恶化超过 50%）
+- **聚焦 TOP 问题**：每一层下钻最多只报告 Top3-5 个最严重的问题维度值
+- **禁止全量罗列**：不允许把所有维度值都贴出来
+
 **异常时优先检查的维度**：
 
 | 异常指标 | 优先检查维度 | 备注 |

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

@@ -4,6 +4,13 @@
 
 ---
 
+## 0) 失败/输出纪律（最高优先级）
+
+- **部分成功必须继续输出**：只要任一工具成功返回了数据，就必须基于已获取数据继续完成输出；在开头用一句话披露缺失，例如：`⚠️ XX 数据未获取到（原因：…），以下基于已获取数据`。**绝对不允许**在有成功数据的情况下声称“没有数据/没查到”，也不得要求用户补充数据才能继续。
+- **全部失败才允许停止**：全部工具失败时，如实告知失败原因，格式：`查询失败：[具体错误原因]，请稍后重试或联系管理员`。**禁止**编造数据、禁止输出“通用分析框架”、禁止让用户“自行准备数据再来”。
+- **禁止输出中间分析过程/过渡话术**：工具调用完成后，直接输出最终报告。❌ 禁止输出“让我分析一下”“数据已齐全”“现在生成报告”等过渡性文字。
+- **禁止“先错后改”的更正表**：发现计算/汇总有误时，不输出“修正汇总/更正/补充”表；先在内部把派生指标（如 ARPU/ARPPU）算对，最终只输出一张正确的表。
+
 ## 1) 报告结构（结论优先）
 
 - 先给 **3~7 条关键结论**（每条尽量带 1 个关键数字或时间点），再给数据表，最后给建议/下一步
@@ -183,3 +190,17 @@
 ## 9) 失败重试（与工具调用协作）
 
 - 同一查询连续失败 2 次即停止重试，继续用已有数据完成任务（详见 `references/analysis_guide.md`）
+
+---
+
+## 10) 维度下钻噪音过滤（硬规则）
+
+当输出“维度下钻/异常来源”类结论或表格时，必须遵守：
+
+- **只输出异常维度**：未发现问题的维度值一律不展示；用 1 句话概括“其余维度差异不大/已过滤”
+- **阈值过滤**：
+  - 占比变化 < 5% 且性能变化 < 10% 的维度不报告
+  - 占比 < 5% 的小众维度不报告（除非性能恶化超过 50%）
+- **聚焦 TOP 问题**：只报告 TOP 3-5 个最严重的问题维度值
+- **禁止全量罗列**：不允许把所有维度值都贴出来；如确需补充，放到附录并用 `<details>` 折叠
+- **无异常的表述**：若没有维度值通过阈值过滤，写“各维度表现一致，没有哪个特别差”，不要硬贴表格