# 输出规范（TapDB 数据分析）
> 目标：让非数据同学也能一眼看懂“发生了什么、影响多大、下一步做什么”。结论优先，数据作证；推断要明确标注为推测。
---
## 0) 失败/输出纪律（最高优先级）
- **部分成功必须继续输出**：只要任一工具成功返回了数据，就必须基于已获取数据继续完成输出；在开头用一句话披露缺失，例如：`⚠️ XX 数据未获取到（原因：…），以下基于已获取数据`。**绝对不允许**在有成功数据的情况下声称“没有数据/没查到”，也不得要求用户补充数据才能继续。
- **全部失败才允许停止**：全部工具失败时，如实告知失败原因，格式：`查询失败：[具体错误原因]，请稍后重试或联系管理员`。**禁止**编造数据、禁止输出“通用分析框架”、禁止让用户“自行准备数据再来”。
- **禁止输出中间分析过程/过渡话术**：工具调用完成后，直接输出最终报告。❌ 禁止输出“让我分析一下”“数据已齐全”“现在生成报告”等过渡性文字。
- **禁止“先错后改”的更正表**：发现计算/汇总有误时，不输出“修正汇总/更正/补充”表；先在内部把派生指标（如 ARPU/ARPPU）算对，最终只输出一张正确的表。
## 1) 报告结构（结论优先）
- 先给 **3~7 条关键结论**（每条尽量带 1 个关键数字或时间点），再给数据表，最后给建议/下一步
- 必须在显眼位置写清楚 **项目名（如有歧义再写项目ID）、时间范围、口径（device/user、去水、货币）**
- 仅“纯数据查询”场景：只展示数据与必要口径说明，不做评价/原因/建议（遵循 `SKILL.md` 的“先判定场景”规则）
**报告模板**：深度分析 / 正式报告场景使用 `assets/report_template.md` 中的统一模板；纯查询场景遵循第 7 节，不强制套模板。
**报告原则**：
- **结论优先**：每个分析先给出关键结论，再展开数据支撑
- **行动导向**：不仅指出问题，还要给出可执行建议
- **1屏原则**：执行摘要控制在 1 屏内可看完
- **金字塔原则**：最重要的放最前面，按影响程度递减
- **数据克制**：摘要只放关键数据，完整数据放附录
- **已查询数据不可遗漏**：所有成功返回的数据都必须在报告中体现
---
## 2) 证据与推断（必须区分）
- **数据事实**：可由查询结果直接验证 → 直接陈述并附数据
- **推断/假设**：需要进一步验证 → 使用 **“推测：”** 前缀，并写清依据（哪几条数据/现象支撑）
- ✅ “推测：收入下降可能与返场卡池吸引力不足有关，建议核实卡池内容”
- 每条行动建议需绑定：对应异常 + 预期影响 + 验证方式
- ❌ 禁止把推断写成确定事实
---
## 3) 术语与表述（必须遵守）
- ❌ 禁止使用 “pp”（百分点） → ✅ 对率类指标一律写成 **从 X% 到 Y%（X%→Y%）**
- ❌ 输出中尽量不要出现 `DR1/DR3/DR7` 等缩写 → ✅ 用 **次留/3留/7留/14留/30留**（需要时括号标注原字段名）
- **指标名称**：必须用 **中文指标名**（必要时括号标注常用缩写，如“日活跃用户数（DAU）”），**禁止直接用 API 字段/列名当作指标名**（如 `newDevice`/`incomes`/`payers_num`/`converted_rate`）。字段名如需追溯，优先放在数据附录的“字段映射”中；留存等少数固定缩写需要时可以在中文后括号标注原字段名。
- ❌ 禁止在报告中列出计算公式（行业常识，追问时才解释）
- ❌ 禁止“无结构性异常”等技术术语 → ✅ “各渠道/平台表现一致，没有哪个特别差”
- ❌ 禁止“真问题/虚警/数学效应/贡献度”等术语 → ✅ 用通俗描述替代
- **维度字段**：必须用 **中文名称（英文字段名）**，例如：渠道（activation_channel）
- **工具失败/缺失数据**：必须明确披露“XX 数据未获取到（原因：…）”，不得继续引用该数据
---
## 4) 对比与变化展示（消除歧义）
### 对比展示规则
- **率类指标**（转化率、留存率、付费率等）：用箭头 **(X%→Y%)**，不要写 “-6%/+2%”
- **量类指标**（DAU、收入、新增设备、人数等）：用相对变化 **+X%/-X%**，并同时给出绝对值
- 多版本/赛季对比：对齐 **上线后前 N 天（第0~N-1天）**；在表头标注 N 和起止日期
### 变化幅度描述
- <5%：小幅
- 5%–15%：中等
- 15%–30%：较大
- >30%：大幅
### 变化列颜色标记（仅“变化”列加底色）
- 正向变化：`+24.5%`
- 负向变化：`-21.7%`
- ❌ 禁止在表格内用任何 emoji 或特殊符号（📈📉💰✅⚠️ 等），用文字替代（emoji 仅用于标题和正文）
### 加粗规则
- 有明显变化且重要的指标行：加粗指标名和数值
- 非核心数据不加粗；不加粗整段文字
---
## 5) 表格与数值格式
- 表格优先（避免在正文逐条罗列对比数字）
- **结论中的金额**：必须在数值前加**货币符号**（如 `¥12.3万`、`$3,210`），并与本报告的货币口径一致
- **大数（金额/人数/设备等）**：优先用 **亿/万**（如 `1.2亿`、`356.8万`），不要用 `k/m/b`
- 小数额与原始值：用千分位（如 `1,234,567`）；如需同时展示“亿/万”和原始值，用括号补充原始值（千分位）
- 金额口径：默认 CNY；切换货币时在标题、表头或末尾元信息中注明（如 `货币：USD`）
- 百分比：保留 1 位小数（例如 12.3%）
- 数据排序：时间序列按日期倒序（最新在上）
- 超过 10 行的表用 `` 折叠，正文只展示关键节点
- 分组查询必须显示维度值列
- 日期列：所有行日期相同时可省略，在说明中标注
- 收入数据需体现占比或主要影响来源（如按渠道/国家拆分时）
### 指标展示顺序（固定）
1. **活跃**：日活跃用户数（DAU）
2. **新增**：新增设备数 → 转化设备数 → 转化率 → 新增账号数
3. **留存**：次日留存率 → 3日留存率 → 7日留存率（只展示率，不展示留存人数）
4. **付费**：收入 → 付费人数 → 付费率 → ARPU（每活跃用户收入） → ARPPU（每付费用户收入）
### “基本持平”指标展示
- 1–2 个持平：保留在表格
- 3 个及以上：不放表格，表格下方一句话概括：`> 还检查了XX、YY，差异不大。`
---
## 6) 口径与可追溯性
- **项目标识**：结论中默认只写项目名；仅当项目名有歧义/存在多候选项目时，在元信息或首次出现处补充项目ID
- **统计维度**：必须标注设备/账号维度（如“日活跃用户数（DAU，设备）”），不能只写“留存下降”
- **subject**：同表同 subject 标一次；混合时在指标名后括号标，如“日活跃用户数（DAU，账号）”
- **去水**：标注是否启用了 `--de-water`（脚本默认不去水），统一标注一次即可
- **货币**：默认 CNY；切换后必须在标题或表头注明
- **时间范围**：相同时末尾统一标注；不同时分表标
- **口径一致**：同对话同指标口径保持一致，换口径必须说明
- **版本对比表口径一致**：两张表必须使用相同的 subject、相同的列结构和列顺序
---
## 7) 纯查询展示规则（无需分析）
当任务仅为数据查询时：
1. **汇总表在前** → 关键数据说明 → 每日明细折叠在后
2. 关键数据说明只描述数据特征（趋势、峰谷、波动范围），不解释原因
3. 如果查询日期覆盖节假日，在说明中标注“本时段为XX期间，数据可能受节日效应影响”
**LTV / 生命周期专用展示**：不使用汇总+折叠结构，只输出一张完整明细表：
- 每行一天，日期倒序排列
- null 显示为 `-`
- 底部加总计/平均行 + LTV 倍数行（N_LTV平均 ÷ 1_LTV平均，格式 `×2.23`）
- 生命周期表头用中文：0→“当日”，1→“1日后”，2→“2日后”
---
## 8) 详细分析小节格式
每个小节：
1. **结论**（1–2 句）
2. **推测/建议**（标注“推测：”，放在表格前面）
3. **数据对比表**（佐证）
详细分析章节如有综合判断/总结性结论，**放在所有子章节之前**。
---
## 9) 失败重试（与工具调用协作）
- 同一查询连续失败 2 次即停止重试，继续用已有数据完成任务（详见 `references/analysis_guide.md`）
---
## 10) 维度下钻噪音过滤（硬规则）
当输出“维度下钻/异常来源”类结论或表格时，必须遵守：
- **只输出异常维度**：未发现问题的维度值一律不展示；用 1 句话概括“其余维度差异不大/已过滤”
- **阈值过滤**：
- 占比变化 < 5% 且性能变化 < 10% 的维度不报告
- 占比 < 5% 的小众维度不报告（除非性能恶化超过 50%）
- **聚焦 TOP 问题**：只报告 TOP 3-5 个最严重的问题维度值
- **禁止全量罗列**：不允许把所有维度值都贴出来；如确需补充，放到附录并用 `` 折叠
- **无异常的表述**：若没有维度值通过阈值过滤，写“各维度表现一致，没有哪个特别差”，不要硬贴表格