---
name: bi-retention-analysis
description: 对留存执行完整的分析流程，算清楚用户留不留、留多少、有没有变化，含口径定义、取数、留存率计算，及可选的维度拆分与对比/归因。触发条件：对话涉及留存率分析、留存表现评估、留存变化归因等任务时触发，如出现「留存表现情况如何」「访问留存和使用留存对比怎么样」「不同国家的访问留存是否存在差异」「分维度后留存情况」「次日/第七日留存率变化」等相似问题时触发。
---

# bi-retention-analysis

对留存执行完整的分析流程，核心目标是**算清楚用户留不留、留多少、有没有变化**：定义口径 → 取数 → 计算留存率 →（可选）拆分维度 →（可选）对比/归因 → 解读与输出。

## 前置条件

开始执行前，确认以下信息已就绪：

- **留存锚点**明确，即作为 day0 的起算时间点（如注册日、首次访问、首次付费等）已定义
- **留存事件**已确定，即衡量「留下来」的行为（如再次访问、再次使用、再次付费等）口径清晰
- **留存窗口**已确定（如次日、7 日、30 日等），对应 day0 / dayn 口径清晰
- **数据获取能力**可用，能取到计算留存率所需的 CSV 或等价数据
- **分析范围**明确，包括时间窗口、对象范围，以及是否需要拆分维度或做对比

若留存锚点、留存事件或留存窗口不明确，需先回到规划阶段补充，或向用户确认后再开始执行。

## 分析原则

### 主要步骤

| 步骤 | 用途 | 是否必选 |
|------|------|----------|
| 定义口径 | 确定锚点、留存事件、留存窗口 | **必选**，见步骤 1 |
| 取数 | 按口径取 day0 / dayn 数据 | **必选**，见步骤 2 |
| 计算留存率 | 计算 day0 用户在 dayn 的留存率 | **必选**，见步骤 3 |
| 拆分维度 | 按渠道、端、国家、版本等分别计算 | **可选**，见步骤 4 |
| 对比/归因 | 跨时间、群体等维度对比留存差异 | **可选**，见步骤 5 |
| 解读 & 输出 | 留存曲线、关键节点、变化趋势、差异结论 | **必选**，见步骤 6 |

**典型产出**：留存率表、留存曲线、分维度留存对比。

**最短路径**：定义口径 → 取数 → 算留存率 → 看曲线 / 报数字（即步骤 1 → 2 → 3 → 6，跳过步骤 4、5）。

本 workflow 主要提供留存分析场景下的编排与数据衔接逻辑，各步骤的具体执行按相应分析方法的标准流程进行。

---

## 1. 定义口径

明确留存分析的三要素，这是后续取数与计算的基础：

| 要素 | 含义 | 常见取值 |
|------|------|----------|
| **锚点（day0）** | 用户被纳入留存统计的起算时间点 | 注册日、首次访问、首次付费等 |
| **留存事件** | 衡量「留下来」的目标行为 | 再次访问、再次使用、再次付费等 |
| **留存窗口** | 在锚点后第几天考察留存 | 次日（D1）、7 日（D7）、30 日（D30）等 |

要点：

- 同一分析可包含**多个留存窗口**（如同时看 D1/D7/D30 以绘制留存曲线）
- 同一分析可包含**多种留存事件**（如访问留存 vs 使用留存），需分别定义口径
- 口径一旦确定，后续取数、计算、对比须保持一致，避免分子分母错配

---

## 2. 取数

按步骤 1 确定的口径取数，准备留存率计算所需的数据。

### 数据准备

整理 CSV，包含：

- **第 0 天用户数**（分母，即锚点当日纳入统计的用户数，如当日新增用户数、当日首次访问用户数）
- **第 n 天留存用户数**（分子，即上述用户在 dayn 仍触发留存事件的用户数）
- 如需多个留存窗口或多种留存事件，分别取对应的分子列

示例：

```csv
date,当日新增用户数,次日访问用户数,7日访问用户数
2025-01-01,10000,3000,1500
2025-01-02,10500,3200,1600
```

若计划在步骤 4 拆分维度，取数时一并带出维度列（如渠道、端、国家、版本），或按维度分别取数。

---

## 3. 计算留存率

计算 day0 用户在后续第 n 天的留存率。

### 计算执行

- 对每个需要报告的留存率指标（如次日留存、第 7 日留存、访问留存 vs 使用留存）按留存率公式（dayn 留存用户数 / day0 用户数）或可用脚本进行计算
- 不遗漏任何必要的留存窗口与留存事件
- 多窗口时，输出可绘制留存曲线的结果（如 D1/D3/D7/D14/D30 各点留存率）
- 保存计算结果

若已规划拆分维度，可在此步先算整体留存率，维度拆分在步骤 4 展开。

---

## 4. （可选）拆分维度

根据分析要求，判断是否需要按维度分别计算留存率：

**需要拆分** → 按维度分别计算，完成后进入步骤 5
**无需拆分** → **跳过本步骤**，直接进入步骤 5（最短路径在此跳过）

### 判断依据

| 信号 | 示例 |
|------|------|
| 按已有维度拆分 | 「按渠道/端/国家/版本看留存」（维度已在数据中，直接分组计算） |
| 需发现未知用户子结构 | 「哪些用户群体留存更高」「用户自然分群后的留存差异」（走聚类分群） |
| 多维特征综合分群 | 需结合多个用户属性（消费、活跃、渠道等）划分群体再算留存（走聚类分群） |

| 信号 | 示例 |
|------|------|
| 仅看整体 | 「整体次日留存如何」 |
| 仅关注时间趋势 | 「最近一周留存率变化」（走步骤 5 时间对比，无需拆分维度） |

### 拆分执行（若启用）

- **按已有维度拆分**：以维度列（渠道 / 端 / 国家 / 版本等）为分组键，对每个维度值分别按步骤 3 计算留存率
- **按用户特征分群**：整理用户级 CSV（对象标识列 + 分群特征列），对用户进行分群并将结果保存为 JSON，再按用户 ID 关联留存数据，**按群分别准备** day0 / dayn 用户数后计算留存率
- 保留各维度 / cohort 及总体（若需要）的结果，供步骤 5 对比与步骤 6 输出

---

## 5. （可选）对比 / 归因

根据分析要求，判断是否需对不同时间、群体、地区等进行留存率对比：

**需要对比** → 进行对比分析，完成后进入步骤 6
**不需要对比** → **跳过本步骤**，直接进入步骤 6

### 判断依据

| 信号 | 示例 |
|------|------|
| 时间维度对比 | 「环比/同比变化」「最近 vs 历史」「留存率是否下降」 |
| 群体/空间维度对比 | 「不同国家/渠道/端/版本/实验组留存差异」「访问留存 vs 使用留存」「A 群 vs B 群」 |
| 显式对比/差异/优劣 | 「对比」「差异」「哪个更高/更低」「是否显著」 |

| 信号 | 示例 |
|------|------|
| 仅报告当前水平 | 「当前次日留存是多少」「整体留存表现如何」（步骤 3 结果已足够） |
| 单一对象无参照 | 只有一个时间点、一个群体，无对比参照物 |

### 对比执行（若启用）

1. 基于步骤 3 / 4 的留存率结果，整理 **对比分析用 CSV**：
   - 时间对比：每列对应一个时期，或一列时间序列供环比/同比计算
   - 空间对比：每列对应一个国家/渠道/端/版本/cohort/留存类型（访问 vs 使用）等
2. 选择合适比较维度（时间 / 空间 / 标准）与计算方式（绝对差值 / 相对差值）执行对比分析
3. 多样本时按显著性检验规则执行
4. 保存对比分析结果

示例（不同国家次日留存对比）：

```csv
业务日期,中国次日留存率,美国次日留存率
20251101,0.3856,0.4343
20251102,0.4288,0.4122
```

---

## 6. 解读 & 输出

完成以上步骤后，围绕**留不留、留多少、有没有变化**汇总并输出。

| 字段 | 说明 |
|------|------|
| 执行内容 | 本步骤做了什么（含跳过的可选步骤及原因） |
| 取数文件 | 原始数据路径 |
| 中间产物 | 分群 JSON（若执行）、对比用 CSV（若执行） |
| 计算结果 | 留存率及对比分析结果路径 |
| 结论 | 留存率水平、关键节点、变化趋势、群体差异及显著性 |

汇总结构建议：

1. **分析范围**：时间窗口、口径定义（锚点 / 留存事件 / 留存窗口）、是否拆分维度、是否做对比
2. **留存率结果**：整体及各维度/cohort 的留存率水平，含关键节点（如次日、第 7 日）与**留存曲线**
3. **对比发现**（若执行步骤 5）：时间变化幅度、群体间差异、显著性结论
4. **业务解读**：留存表现评价、关键驱动因素与可执行建议
5. **局限与不确定性**：样本量、口径差异、分群稳定性、未覆盖维度等