| 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 仍触发留存事件的用户数）
- 如需多个留存窗口或多种留存事件，分别取对应的分子列
示例：
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 结果已足够） |
| 单一对象无参照 | 只有一个时间点、一个群体，无对比参照物 |
对比执行（若启用）
- 基于步骤 3 / 4 的留存率结果，整理 对比分析用 CSV：
- 时间对比：每列对应一个时期，或一列时间序列供环比/同比计算
- 空间对比：每列对应一个国家/渠道/端/版本/cohort/留存类型（访问 vs 使用）等
- 选择合适比较维度（时间 / 空间 / 标准）与计算方式（绝对差值 / 相对差值）执行对比分析
- 多样本时按显著性检验规则执行
- 保存对比分析结果
示例（不同国家次日留存对比）：
业务日期,中国次日留存率,美国次日留存率
20251101,0.3856,0.4343
20251102,0.4288,0.4122
6. 解读 & 输出
完成以上步骤后，围绕留不留、留多少、有没有变化汇总并输出。
| 字段 | 说明 |
|---|
| 执行内容 | 本步骤做了什么（含跳过的可选步骤及原因） |
| 取数文件 | 原始数据路径 |
| 中间产物 | 分群 JSON（若执行）、对比用 CSV（若执行） |
| 计算结果 | 留存率及对比分析结果路径 |
| 结论 | 留存率水平、关键节点、变化趋势、群体差异及显著性 |
汇总结构建议：
- 分析范围：时间窗口、口径定义（锚点 / 留存事件 / 留存窗口）、是否拆分维度、是否做对比
- 留存率结果：整体及各维度/cohort 的留存率水平，含关键节点（如次日、第 7 日）与留存曲线
- 对比发现（若执行步骤 5）：时间变化幅度、群体间差异、显著性结论
- 业务解读：留存表现评价、关键驱动因素与可执行建议
- 局限与不确定性：样本量、口径差异、分群稳定性、未覆盖维度等
