营收预测测算
季度经营会或董事会预测材料之前，最费劲的不是把管线金额加起来，而是回答三个问题：
本季度能签多少（承诺 / 乐观 / 满管线三层分别是多少）、存的量还能留多少（队列 NRR/GRR）、
以及每个数字是用什么转化率、什么数据窗口、什么加权口径算出来的。
本工具把一份管线与历史成单数据，滚动成一份可复现的预测报告——
按阶段转化率 + 置信度权重拆出三层承诺并给区间（不给没有依据的单一数字）、
对存量队列做逐季复合的 NRR/GRR 投影并挑出「漏水队列」（近期队列净留存显著低于早期队列）、
对每一条输出显式披露口径，并按一组启发式规则（P1–P20）挑出需要先解释的预测问题，
逐条给出规则码、严重度、定位、说明与建议。
只给结构化提示，不替你做经营决策——预测评分只用于排序与提醒，真正结论要结合业务实际。
执行原则
- 先定基准日。 跑之前先确认
--as-of与--profile，它们决定目标季度窗口与先验；不要在未说明基准日的情况下把三个数字直接写进对外材料。 - 给区间不给单点。 三层预测以「下限 / 基准 / 上限」呈现并附口径；不要省略区间只报一个基准数，也不要把「满管线」当承诺对外说。
- 区分无法判定与没问题。 缺阶段历史时
P8/P9不命中，无队列时队列规则不参与判定；不要把「未命中」说成「已验证无问题」。 - 口径必须可复现。 每条数字都要说清用了什么转化率、什么窗口、什么加权；不要混用口径或用
--param改了阈值却不回显生效值。 - 只读不改数。 脚本只读输入文件，不替外部系统补数据；不要为了凑覆盖率自行回填缺失商机或金额。
何时使用
CRITICAL: 只要用户提出预测营收、估算回款、这季度能签多少、承诺和乐观分别是多少，就必须使用本 skill，即使看起来可以用别的方式解决。
- 用户给出一份管线 / 商机台账（CSV / JSON，含阶段、金额、预计签约日等字段），
说「帮我看看这季度能签多少 / 做个营收预测 / 承诺和乐观分别是多少」。 - 季度经营会、董事会 / 投委会预测材料：需要「承诺 / 乐观 / 满管线」三个数字加假设清单。
- 怀疑合并 NRR 掩盖了近期队列的漏水，想做队列分解。
- 想知道管线覆盖率够不够、承诺层有没有被少数大单或停滞商机撑起来。
- 需要一份口径可复现的预测报告（每条数字都能说清用了什么转化率与加权方式）。
不适用：已发生经营指标的历史体检（用 saas-metrics-report）；财务结账与 P&L 报表；
多年期战略财务规划与融资情景；定价方案设计；单笔商机的折扣审批；缺失数据的补全
（本工具只基于已有字段与历史做滚动，不替外部系统补数据）。
何时不该使用
| ✅ 使用本 skill | ❌ 不用（改用什么 / 理由） |
|---|---|
| 有管线台账，或含阶段历史与队列的工作区 | 要做已发生经营指标的历史体检 → 改用 saas-metrics-report |
| 要「承诺 / 乐观 / 满管线」三层数字与区间 | 要财务结账与 P&L 报表 → 属会计口径，本 skill 不做 |
| 要查漏水队列、看 NRR / GRR 投影 | 要做多年期战略财务规划与融资情景 → 超出单季滚动预测范围 |
| 要一份口径可复现的预测报告 | 要补全缺失数据 → 只基于已有字段与历史滚动，不替外部系统补数 |
| 经营会 / 董事会预测材料 | 单笔商机折扣审批 → 属 deal-desk，本 skill 不做 |
易混淆场景
| 用户说的 | 实际意图 | 正确路由 |
|---|---|---|
| 「这季度能签多少」 | 要一个能对外承诺的数字 | 给三层区间；覆盖率不足时提示承诺层缺乏支撑，不要只报基准值 |
| 「做个营收预测」 | 要完整报告 | 先确认 --as-of 与 --profile；缺失就先问，不要默认今天硬跑 |
| 「我们 NRR 怎么样」 | 可能是历史现状，也可能是未来投影 | 历史现状用 saas-metrics-report；未来投影才用本包 |
| 「为什么没命中更多问题」 | 可能是数据缺项 | 说明缺字段是「无法判定」而非「没问题」，并提示补哪些数据 |
怎么用
# CSV 管线台账（三层承诺预测 + 启发式规则）
python3 scripts/revenue_forecast_model.py --file 管线台账.csv
# JSON 预测工作区（可同时含管线、阶段历史与队列，做完整预测）
python3 scripts/revenue_forecast_model.py --file 预测工作区.json
# 指定基准日（决定目标季度窗口）与行业画像
python3 scripts/revenue_forecast_model.py --file 管线台账.csv --as-of 2026-04-01 --profile enterprise
# 覆盖阈值常量（可重复；保证口径可复现）
python3 scripts/revenue_forecast_model.py --file 工作区.json --param COVERAGE_FLOOR=2.5 --param LEAK_PP=4
# 输出 JSON
python3 scripts/revenue_forecast_model.py --file 工作区.json --json
# 用内置问题样例看效果
python3 scripts/revenue_forecast_model.py --sample
--file <路径>：CSV 管线台账 或 JSON 预测工作区（只读，不修改）。--sample：内置问题样例（同时含管线与队列，会命中多条规则）。--as-of YYYY-MM-DD：评估基准日，决定目标季度窗口与「关单日期是否过期」的判定，默认今天。--profile：行业画像（saas/enterprise/smb/services/api），缺历史转化率时用于先验。--horizon N：队列投影季度数，默认 4。--param NAME=VALUE：覆盖脚本顶部阈值常量（可重复）。--json：以 JSON 输出（含forecast/stage_conversions/cohorts/findings/assumptions）。- 退出码：
0= 未命中任何项；1= 有命中或用例错误。
按需读取
先读 00 路由索引 定位，再用 read_file(offset, limit) 只读命中章节；禁止整文件读取 references。
| 当前任务 | 读取内容 |
|---|---|
| 只有管线、没有队列时怎么给 | 01 §1 |
| 要接阶段历史与存量队列 | 01 §2 |
| 阶段名 / 日期 / 金额写法 | 01 §3 |
看某条规则码 P1–P20 确切含义 |
02 §1 |
| 看报告长什么样 / 退出码 | 03 §1 / §2 |
| 核对评分档位 | 03 §3 |
纠结用本包还是 saas-metrics-report |
04 §1 |
交付物模板：assets/营收预测报告模板.md。
高频摘要
- 三层预测：承诺
承诺级阶段 × 阶段转化率 × 时限概率 × 停滞折减；
乐观乐观级阶段 × 阶段转化率 × 时限概率；满管线全部商机 × 阶段转化率（不计时限 / 停滞）。 - 阶段转化率：有历史时取「近 4 季 ×70% + 近 12 季 ×30%」加权，缺历史时回落行业画像先验。
- 队列投影：逐季复合 NRR / GRR，
--horizon控制季度数（默认 4）；近期队列显著偏低即标「漏水」。 - 评分 =
max(0, 100 − (高×15 + 中×5 + 低×2))；≥90 优秀 / 75–89 良好 / 60–74 一般 / <60 较差。 - 退出码：
0未命中任何项；1命中项或用法错误。全部阈值可用--param NAME=VALUE覆盖并回显。
限制与免责
- 纯标准库 Python，只读输入文件，无网络请求，无
subprocess/eval/os.system。 - 预测评分与规则均为启发式加权结果，不是对经营结果的承诺：转化率、时限概率、留存曲线都是假设，
同一份数据在不同行业与阶段口径下含义可能完全不同，阈值必须按自身情况校准。请把它当作
「先看哪、口径是什么、哪里最脆弱」的排序工具，而不是结论。 - 缺失字段不判为问题：例如未提供阶段历史时，
P8/P9不会命中（是「无法判定」而非「没问题」）；
未提供队列时，队列类规则不参与判定。若希望覆盖更多规则，请在工作区中补齐相应数据。 - 本工具只做结构化提示，不构成财务、投资或经营决策建议。签约预测、留存口径、会计确认与收入确认
以正式合同、财务凭证与会计准则为准。 - 不支持财务结账与报表、多年期战略规划、定价方案设计、单笔商机折扣审批；也不处理非结构化文本。
- 本包为开源改编作品，来源与改动见
来源与许可.md，遵守 MIT 许可证（LICENSE.md）。
上游署名
本包为开源作品 alirezarezvani/claude-skills（MIT License，Copyright (c) 2025 Alireza Rezvani）中
commercial/skills/commercial-forecaster/ 的中文改编版本：代码完全重写，
三个上游脚本（bookings_forecaster.py / cohort_arr_projector.py / funnel_confidence_scorer.py）
整合为单个中文脚本，并移除了英文报告模板与 board-theatre 表述。详细来源、改动清单与二次分发要求见 来源与许可.md。
依赖
仅需 Python 3.8+，使用标准库，无需联网、无需安装第三方包。
免责声明
本包输出是基于给定假设与输入数据的推演，不是对经营结果的承诺，也不构成财务、投资或经营决策意见。
- 转化率、时限概率、留存曲线都是假设，同一份数据在不同行业与阶段口径下含义可能完全不同，阈值必须按自身情况校准。
- 预测评分与规则为启发式加权结果，请当作「先看哪、口径是什么、哪里最脆弱」的排序工具，而不是结论。
- 缺失字段不判为问题：未提供阶段历史时
P8/P9不命中，未提供队列时队列类规则不参与判定——是「无法判定」而非「没问题」。 - 签约预测、留存口径、会计确认与收入确认以正式合同、财务凭证与会计准则为准。
- 交付时可用
assets/营收预测报告模板.md，模板内含同样声明。
