revenuecat-forecasting

预测

使用 revenuecat-charts 处理图表机制和指标解读。本技能介绍如何将它们转化为预测。优先使用 MCP get-chart-options-schema / get-chart-data，而不是 rc charts show——CLI 层面无法提供本操作指南所需的到期月份细分和筛选器。

根据需求选择相应部分：

• 逐月 MRR/ARR（包括反推支出，以及“一个月后”/“N 个月后”） → 使用下方的流失公式和步骤——短期预测是该公式的 N 次迭代，而不是净变动趋势
• 截至本月底/年底的收入 → 期间剩余时间的运行速率（不要运行 MRR 步骤）
• 低/基准/高情景或“N 个月后” → 情景预测（预测 MRR/订阅数时使用流失公式）
• 需求不明确（“预测”“预测未来”，未指定指标/时间范围）→ 默认预测 12 个月的 MRR，并运行 MRR 步骤；明确说明这一默认设置。对于年付占比较高的业务，状态快照不会涵盖所有预测月份——使用其中包含的到期月份，将没有到期记录的年度月份留为应付额为零（不要凭空补数据），保留滚动的短周期应付额和流入，并说明年度计划仅覆盖当前存量用户下一周期的情况。

流失公式

对于逐月 MRR 或 ARR——包括反推达到目标所需的支出或新增订阅数、用户已提供流失 MRR、支出或效率数据的情况，以及“一个月后 MRR 会是多少”或“两个月后会是多少”这类短期问题——某月的流失 MRR 为：

churned MRR[m] = MRR up for renewal in m × (1 − renewal rate)

短期预测（1–2 个月，或任何较小的 N）

“一个月后”“两个月后”或“下个月之前”仍然按流失公式计算——前推 N 个步骤， 而不是按剩余期间计算运行速率，也不是对近期净 MRR 变动取平均值。

1. 对窗口内涉及的每个日历月，读取 Status expiration_month 中的 Total MRR （例如，预测约 30 天后时，包含本月剩余时间 + 下个月；预测“两个月后”时，包含两个完整月份）。
2. 每个步骤：按期限计算 churn[m] = due[m] × (1 − rate)；将快照之后到期的 P1M/P3M 费用滚动计入； 年度订阅在空置月份的应到期金额设为零。
3. 仅添加近期新订阅／重新订阅／扩展带来的流入。
4. 按步骤更新存量：MRR[m+1] = MRR[m] − churn[m] + inflow[m]——N=1 时计算一次，N=2 时计算两次，依此类推。
5. 使用一个脚本。净变动／冻结的已流失 MRR 只能作为诊断差额出现——绝不能作为另一种方法来确定最终预测值，也绝不能使用 annual_base / 12。

正确示例——预测一个月后（N=2 时同理，在循环中计算两个月）：

# 应到期金额来自 Status expiration_month（measure=mrr），而不是 base/12
due_annual_next = 28316.52          # 例如 P1Y 的 10 月 Total MRR
due_monthly = monthly_base          # 持续订阅的 P1M 订阅
churn = due_annual_next * (1 - r_annual) + due_monthly * (1 - r_monthly) + ...
mrr_next = mrr_now - churn + inflow_run_rate

从 Subscription Retention 或 Cohort Explorer 获取续订率（仅使用图表字面值）—— 不能用 observed_churned ÷ base 计算，也不能使用 Set-to-Renew %。该比率适用于对应期限的应到期部分 （对于月付订阅，应到期金额约等于存量；对于季度及更长期限，绝不能先用 churned ÷ full base 计算，再将其应用于应到期部分——这会低估流失）。

从 Subscription Status 获取当前周期内有效订阅的“待续订 MRR”：

get-chart-data(
  project_id="<id>",
  chart_name="subscription_status",
  realtime=true,
  resolution="<id from options schema>",
  start_date="<YYYY-MM-DD>",
  end_date="<YYYY-MM-DD>",
  segment="expiration_month",
  selectors="{\"measure\": \"mrr\"}",  # JSON 字符串，不是对象；不能用 active_subscriptions
  limit_num_segments=24,               # 避免后续月份被合并到 Other
  # optional: filters="[{\"name\": \"product_duration\", \"values\": [\"P1Y\"]}]"
)

对 Retention／Cohort Explorer／MRR／MRR Movement 使用相同的 get-chart-data 模式——但不要 将仅适用于 Status 的字段（segment=expiration_month、limit_num_segments、 selectors.measure）复制到这些图表上；应根据各图表的选项架构获取 segment／filters／selectors （使用 "realtime": true 调用 get-chart-options-schema）。

每个分段表示当前有效订阅的周期结束所在的日历月。仅将 Total MRR 用作 due[m]。Set to Renew／Cancel／Billing Issue 是近期意向标签，不是续订率预测值。Status 仅是当前有效订阅存量的快照——仍需将新订阅／重新订阅／扩展作为流入，根据 MRR Movement（或用户的支出计划）进行建模。如果完全无法获取应到期金额，请询问续订计划，不要使用 annual_base / 12。

按期限计算应续费额和流失率

期限	应续费额（状态可用）	应续费额（状态不可用）	流失率
P1Y	按 expiration_month 统计总 MRR（当前订阅和续订订阅）。较远月份为空时应保持为空，不要自行填充。	M 月上一年的 P1Y 新订阅 + 重新订阅（会遗漏续订周年日——请注明这一点）	留存率 Y1 / Cohort（使用留存率时，subscription_type = new）
P1M	近期到期分桶，之后每个月滚动 ≈ 稳定月度基数	稳定月度基数	留存率 / Cohort（或变动 churned / due，其中 due ≈ 基数）
P3M / 其他固定期限	近期分桶，之后滚动 ≈ 基数 / 期限月数	基数 / 期限月数	留存率 / Cohort（或变动 churned / due，绝不能用 churned / full base）

错误做法——将年度应续费额视为存量的固定比例：

annual_due = annual_base / 12          # 或 due_frac = {"annual": 1/12}

错误做法——反向求解残差，使建模流失额与观测值相符：

repeat_annual = observed_annual_churn - annual_due[m] * (1 - rate)
churn_annual = annual_due[m] * (1 - rate) + repeat_annual      # 然后用于预测

错误做法——固定期限的流失率以全部存量为分母：

rate = 1 - churned_P3M / p3m_base      # 然后 churn = (p3m_base/3) * (1 - rate)  → 低估

错误做法——出现缺口后改用第二种模型（混合 / 净变动 / “校准后”的流失）：

# 当 due*(1-rate) 与上个月的流失 MRR 不符时：
project(net_fn)  or  mrr *= (1 - blended_churn) + inflow   # 绝不能这样做

正确做法：

# due：subscription_status，measure=mrr，segment=expiration_month，filter product_duration=P1Y
annual_due = {"2026-11": 17.32, "2027-02": 6.66, ...}   # 每个到期月份的总 MRR
# rate：Subscription Retention Y1 或 Cohort Explorer，而非 Set-to-Renew %
churn_annual[m]  = annual_due[m] * (1 - renewal_rate_annual)

# 月度：下一周期按到期月份计算，之后 due ≈ 稳定月度基数
churn_monthly[m] = monthly_due[m] * (1 - renewal_rate_monthly)
# 季度：due ≈ p3m_base/3；流失率取自 Retention（或 churned_P3M / due，而非 / p3m_base）

步骤（仅适用于按月的 MRR/ARR）

对于剩余期间的收入运行率，请勿使用这些步骤——请改用该部分。

1. 拉取按 product_duration 细分的当前存量 MRR。
2. 按照上方的 get-chart-data 示例拉取 Subscription Status（选择器为 {"measure": "mrr"}，segment=expiration_month，limit_num_segments 设为较高值），并针对你建模的每种期限按 product_duration 进行筛选。仅将每个到期月份的 Total MRR 读入脚本，作为 due。按照 表格将快照日期之后的 P1M/P3M 应到期金额滚动到后续月份；年度到期月份留空。
3. 从 Subscription Retention 或 Cohort Explorer 拉取比率——不要使用 status 中的 Set-to-Renew %。 代码中的每个比率字面量都必须出现在之前的工具输出中。
4. 仅拉取用于新增 / 重新订阅 / 扩张运行率（流入）的 MRR Movement。不要将流失 MRR、净变动或混合流失率代入预测。脚本中的流失必须为 due[m] × (1 − rate)——绝不能使用 project(net_fn) / 基于净 MRR 变动的拟合 / mrr * (1 - blended_churn)。
5. 只使用一个形如 Correct 区块的脚本计算。如果第 1 个月的建模流失 ≠ 实际观测值，只将差值打印为诊断信息——不要再运行第二个经过校准、混合或基于净变动的预测，也不要添加残差。续订到期结果是核心答案。
6. 给出核心情景、范围及其影响因素，并在有差值时提供差值诊断。只有当所述假设都会让结果朝同一方向偏移时，才称某个数值为下限或上限。

剩余期间的运行率

对于“截至本月 / 年末的收入”等类似问题——不要使用上方的 MRR 步骤：

• 今天尚未结束。计算每日平均值时排除今天，或说明已将今天排除。
• 给出范围或说明观察到的每日波动情况。只给单点估算不构成预测。
• 用两种方法交叉验证——按已过天数推算，以及将上一期间的走势应用于当前期间——并说明采用哪种方法作为主要依据以及原因。
• 优先拆分出在剩余期间内已通过 Subscription Status 到期月份锁定的 MRR，而不是假设续订均匀分布。
• 在聊天答复中给出核心数据；不要只在图表或产物中提供。

情景预测

对于低 / 基准 / 高情景或“未来 N 个月”：

• 每个情景都要指出不同的驱动因素（获客率、续订率、逐步作用于现有基础的定价变更），不能只是对同一个数值乘以不同倍数。
• 确定一个核心情景；仅给出范围无法回答问题。
• 模拟中的每个续订率或留存率都必须来自针对该账户的图表查询。公开基准仅供参考，不能作为输入。
• “未来 N 个月”指从今天起算 N 个月。如果模型以最近一个完整月份为基准，请说明这一点并指出结束月份。
• 对于 MRR 或订阅者指标，留存方面使用上方的流失公式。

Prediction Explorer

Prediction Explorer 用于对群组 LTV 建模，而不是预测流失。问题涉及回本期或 LTV 交叉验证时可使用它；它不能替代上方的流失公式。