| name | bi-ltv-analysis |
| description | 评估单个用户或用户群体在生命周期内创造的收益。触发条件：当需要用户生命周期价值计算与分析时触发，如对话中涉及“LTV”、“LTV 分析”、“用户生命周期价值”、“人均收益测算”等等相近词语时调用。 |
bi-ltv-analysis
评估单个用户或用户群体在整个生命周期内创造的收入（或利润），典型用途。
执行步骤
Step 1：准备数据
根据分析任务需求与所给数据结构，明确 LTV 分析涉及的指标，即分析粒度（用户级 / 群体级）、收益口径（如购买、升级等行为产生的收入、利润等）以及生命周期（如时间窗口、某阶段流失率等），将取数结果保存为 CSV。
整理数据为 CSV 格式，采用“分组（用户/群体） × N天（生命周期与收益数据）”，数据应至少包括分析粒度对应的对象列、收益口径对应的收入数据列以及生命周期对应的数据列。
例如，对于用户级的 LTV 分析，分析数据示例如下，
用户ID,事件时间a,收入金额a,事件时间b,收入金额b
1,2025-04-25,26.0,2025-04-26,6.5
2,2025-04-25,6.5,NaN,NaN
对于群体级的 LTV 分析，数据示例如下，
群体类别,a阶段流失率,a阶段收入金额,b阶段流失率,b阶段收入金额
group_1,0.366,26.0,0.121,6.5
group_2,0.253,6.5,0.754,2.0
若上游步骤已产出可用汇总表则直接使用，否则按口径从明细聚合（按用户求和、按队列求和等）。
注意：若数据包含留存率、流失率等指标可以用于 LTV 分析，则统一使用流失率进行计算，若数据中仅包含留存率，则转化为流失率进行 LTV 计算和分析，一般情况，流失率=1-留存率。
Step 2：计算 LTV
LTV 计算公式一：
(LTV = ARPU \times 生命周期)
LTV 计算公式二：
(LTV = ARPU \times \frac{1}{流失率})
ARPU（Average Revenue Per User）：单位用户在指定统计范围内的平均收入。若 CSV 中收入列为阶段合计、且另有用户数列，则脚本按 (ARPU = 收入 / 用户数) 计算；若收入列已是人均口径，则无需 --users-col。
群体多阶段（含多列「阶段流失率 + 阶段收入金额」）：按阶段顺序，用存活率对收入加权求和：
[
LTV = \sum_{j} 收入_j \times \prod_{k<j}(1 - 流失率_k)
]
方式一：使用脚本
使用 <skill-dir>/scripts/ltv_calc.py 计算 LTV。结果写入 --output-file 指定的 CSV：第一列为输入中的分析对象列（--object-col），第二列为 LTV（默认列名 ltv）。
用户级（观测窗口内各阶段收入累计）：
python <skill-dir>/scripts/ltv_calc.py \
--input-file "<输入 CSV 路径>" \
--object-col "用户ID" \
--revenue-cols "收入金额a" "收入金额b" \
--output-file "<输出 CSV 路径>"
群体级（多阶段流失率 + 收入）：
python <skill-dir>/scripts/ltv_calc.py \
--input-file "<输入 CSV 路径>" \
--object-col "群体类别" \
--revenue-cols "a阶段收入金额" "b阶段收入金额" \
--churn-cols "a阶段流失率" "b阶段流失率" \
--output-file "<输出 CSV 路径>"
公式一（单列收入 + 生命周期 T）：
python <skill-dir>/scripts/ltv_calc.py \
--input-file "<输入 CSV 路径>" \
--object-col "群体类别" \
--revenue-col "a阶段收入金额" \
--users-col "用户数" \
--lifecycle 12 \
--formula lifecycle \
--output-file "<输出 CSV 路径>"
公式二（单列收入 + 单列流失率）：
python <skill-dir>/scripts/ltv_calc.py \
--input-file "<输入 CSV 路径>" \
--object-col "群体类别" \
--revenue-col "a阶段收入金额" \
--churn-col "a阶段流失率" \
--formula churn \
--output-file "<输出 CSV 路径>"
若数据列为留存率而非流失率，增加 --rate-is-retention（按 流失率 = 1 − 留存率 转换）。
参数说明：
| 参数 | 说明 | 默认值 |
|---|
--input-file | 输入数据文件路径（CSV） | （必填） |
--object-col | 分析对象列名（用户 ID、群体类别等） | （必填） |
--output-file | 输出 CSV 路径（两列：分析对象、LTV） | （必填） |
--ltv-col | 输出中 LTV 列名 | ltv |
--formula | cumulative / lifecycle / churn / stage_weighted；省略时按其它参数自动推断 | 自动推断 |
--revenue-cols | 多阶段收入列名（可多个） | — |
--churn-cols | 多阶段流失率列名，与 --revenue-cols 顺序一一对应 | — |
--revenue-col | 单列收入（公式一、二） | — |
--churn-col | 单列流失率（公式二） | — |
--lifecycle | 生命周期数值 T（公式一） | — |
--users-col | 用户数列（收入为合计时计算 ARPU） | — |
--rate-is-retention | 将流失率列按留存率处理并转换为流失率 | 否 |
