查询与解读 RevenueCat 图表数据并生成可分享的…

当需要查询 RevenueCat 的图表、订阅指标或 KPI，解读数据变化，或生成带筛选条件的 Dashboard 图表链接时使用。

适用场景

解决思路

1. 查询图表时遵循三步流程：先用 get-chart-options-schema 发现图表可用选项，再用 get-chart-data 配合正确选项获取数据，最后分析数据（非平凡运算用脚本处理）。
2. 通过 rc CLI 操作：rc charts list 列出图表，rc charts options <chart> 获取 schema，rc charts show <chart> 获取数据。
3. 为避免上下文过载，先用确定的时间范围和较粗的 resolution，再逐步收窄。
4. 把 get-chart-options-schema 当作每个图表的唯一事实来源，调用时始终传 "realtime": true；后续 get-chart-data 必须使用它返回的字符串 ID。
5. 理解 filters：每个 filter 有 id（后续作为 filter name）和 value_mode——inline_enum 必须用返回 options 的 id（用户提供的名称先用 list-products、list-offerings、list-apps 等对应列表工具解析）；inferred_standard 用 value_source 的标准代码（如 ISO 国家代码）；dynamic 的值来自项目实际观测数据且必须精确匹配。
6. 不要传显示名称、商店产品标识符、bundle ID 或猜测值，除非 schema 明确说明它们是合法值。
7. 理解 segments：segment 条目直接给出可用的维度 id，不列出值（图表会按它分组并输出所有值）；filters 和 segments 是每个图表各自独立的列表，不要假设可筛选的维度一定可分组（例如 conversion_to_paying 的 product_id 和 offering_identifier 可筛选但不可分组）。
8. 理解 user_selectors：图表专属开关，用于改变返回的指标或窗口；每个 selector 以 ID 为键传入 get-chart-data 的 selectors JSON 对象，通常包含允许的选项 ID 和默认值（如 revenue 图表的 revenue_type 可为 revenue、revenue_net_of_taxes、proceeds；conversion 图表用 conversion_timeframe 且默认 7_days）；呈现结果时说明非默认的 selector 选择。
9. resolutions 列出支持的时间粒度和字符串 ID，调用 get-chart-data 时必须传其中一个 resolution ID（如 "0" 表示天，"2" 表示月）。
10. 调用 get-chart-data 时始终设置 "realtime": true，并指定 start date、end date 和 resolution ID，且遵循先前 get-chart-options-schema 的指引。
11. 注意速率限制：不要一次查询过多图表。
12. 日期范围是闭区间（start_date 和 end_date 都包含在内）；当被要求「最近 N 天」时，end date 用今天，start date 为今天往前 (N-1) 天。
13. 用 filters 约束输出，格式为 JSON 编码的数组 [{"name": "<filter id>", "values": ["<value id>", ...]}]；同一 entry 内的值取 OR，不同 entry 之间取 AND（例：美国或英国的 App Store 收入为 "[{\"name\": \"store\", \"values\": [\"app_store\"]}, {\"name\": \"country\", \"values\": [\"US\", \"GB\"]}]"）；每个 filter name 最多一个 entry（重复会静默替换前一个）；filter 值不能含逗号。
14. 用 selectors 配置图表，格式为 JSON 编码对象，映射 selector ID 到 option ID，如 "{\"revenue_type\": \"proceeds\"}"；省略的 selector 用默认值，响应会在 user_selectors 中回显实际应用的值。
15. 用 segment 按可分组维度 ID 分组输出；注意分组会成倍放大输出，可用更粗的 resolution、更短的日期范围、limit_num_segments（保留前 N 大并把其余折叠为 "Other"）或 aggregate（只需每段汇总时）来保持响应精简。
16. 用 aggregate 处理只要汇总的问题（如总计或平均，例如「Q1 总收入」），优先于自己拉原始数据点计算；与 segment 结合可返回紧凑的每段汇总（如按国家平均）；输出中 values 为空，summary 只含这些运算。
17. 传 currency 把输出转换为某个货币单位（见响应中的 yaxis_currency）。
18. 读取输出：measures 列出图表返回的指标（显示名、单位、描述），多数图表返回多个（如 revenue 可能返回 Revenue、Transactions、Ad Impressions）。
19. 读取输出：values 是扁平的点数组 {cohort, measure, value, incomplete}，分组时还有 segment；cohort 是周期开始的 Unix 时间戳，measure 和 segment 是 measures 和 segments 数组的索引；第一个 segment 通常是 "is_total": true，绝不要把它与其他 segment 相加。
20. 读取输出：summary 按 measure 显示名保存 total 和 average，分组时按 segment 嵌套。
21. 读取输出：incomplete: true 的点覆盖不完整周期——当前周期，以及 start_date 落在周期中间时的第一个周期（因为 expand_periods 默认 false）；把它们排除在趋势或对比分析之外，并在呈现时说明；时点图表（MRR、actives、trials）忽略 expand_periods，其值是周期边界的快照，永远不会不完整。
22. 读取输出：annotations 列出用户在 dashboard 上标注的带日期备注（如发布、上线或实验）；解释数据变动时要检查它们。
23. 遇到无效的 filter、segment 或 selector 值会返回 400 parameter_error，消息中列出支持的 ID；此时重新阅读 options schema，不要靠猜测重试。
24. 分析时：分组响应包含 Total segment，limit_num_segments 会把前 N 之外的段折叠为 Other segment；用 Total 作为基线# 不要自己把各段相加。
25. 用脚本（如 jq 或简短 Python 脚本）对图表输出做复杂运算（增长率、段占比、跨调用合并数字），而不是靠推理心算。
26. 最近一个周期可能被标记为不完整；不要不说明就直接拿它与完整周期比较。
27. 在推测指标变动原因前，先检查可用的用户 annotations。
28. Cohort 图表衡量的是从首次出现起的累计窗口，由 selector 选择（conversion 图表用 conversion_timeframe，realized LTV 图表用 customer_lifetime），每次调用一个窗口；呈现结果时说明窗口，并在比较 cohort 时保持窗口不变。
29. 解读指标时记住订阅 App 由四股力量驱动：Acquisition（新客到达）、Conversion（转化为试用或付费）、Retention（留存时长）、Reactivation（唤回老用户）；收入净变化是这些力量的综合结果，给建议时始终用 benchmark 数据避免误诊。
30. 在告诉用户 RevenueCat 没有其所述指标的来源之前，先选可能的图表，调用 get-chart-options-schema 获取选项，再调用 get-chart-data 检查其 periods / measures——不熟悉的名字往往是某个图表内的一个 period 或 measure（schema 本身不列出这些）；get-benchmarks 中缺失只意味着没有同行百分位区间，不代表该值无法计算。
31. 查看之后：如果工具中没有任何匹配，或两种解读会产生实质不同的数字，请用户定义该指标，不要自己发明定义。
32. 在有用时提供 RevenueCat 图表链接（见 Dashboard URL Format 部分），并提供带筛选、分组、日期范围等的具体链接——例如被问及最近 3 个月的 proceeds 时，链接到 revenue 图表并设置最近 3 个月的自定义日期范围和 revenue_type selector 为 proceeds，而不是链接到普通 revenue 图表。
33. 涉及预测、预估或 run-rate 时，先加载 revenuecat-forecasting 技能再拉图表。
34. Revenue：被问及一般收入数字而无额外说明时，默认用 gross revenue（含税和商店佣金的收入）并说明。
35. Acquisition：用 New Customers 图表了解顶部漏斗的驱动量；按 Country 或 Apple Ads 维度分组有助于了解获客（RevenueCat 的 Apple Ads 集成会设置 campaign、ad group、keyword 等归因维度；开发者也可通过保留的 customer attributes 按客户手动设置这些归因维度）。
36. 不要把显式归因筛选返回的零结果当作整个渠道零用户或零活动的证据（例如 attribution_source = Organic 只表示被显式打上该值的用户，不含未打标用户或所有自然/非付费用户）；如果归因数据稀疏或缺失，明确说明，用「未归因」或「未显式打标」而不是假设这些用户来自某个渠道。
37. Conversion：转化定义因 App 模式而异（可能先转试用再转订阅，也可能直接转订阅）；用 Initial Conversion 图表看选定转化窗口内新客中开始订阅或试用的比例；用 Conversion to Paying 图表看选定窗口内新客中完成付款的比例。
38. Initial Conversion（开始试用或订阅）和 Conversion to Paying（完成付款）衡量不同事件，绝不要用一个代替另一个，也不要拿一个的值与另一个比较。
39. 可进一步用 New Trials 图表判断是否使用免费试用；Trial Conversion Rate 图表有助于了解试用转化本身的表现。
40. 筛选后的图表保留「所有新客」分母——例如按特定 product_id 筛选 Conversion to Paying 得到的是所有新客中转化为该产品的比例，而不是该产品自身的转化率；呈现筛选结果时说明这一注意事项。
41. Retention：Churn 图表显示每期流失的活跃订阅者百分比，但它混合了不同周期，难以解读或对标。
42. 想了解不同产品的长期留存时，看 Subscription Retention 图表或用 Cohort Explorer 图表的 retained_subscriptions measure，它返回随时间仍保持活跃（未过期）的订阅数。
43. 想了解订阅在生命周期中何时被取消（即关闭自动续订）时，用 Cohort Explorer 的 subscriptions_set_to_renew measure。
44. Subscription Retention 图表按周期报告每个 cohort 的续订情况，含计数和预计算比率（"Month N" / "Month N rate" 列）；单个周期可回答「续订过一次的比例」这类问题：首次续订对应与计划时长匹配的周期（月付为 Month 1，年付为 Year 1）；用 product_duration 筛选保持每次只读一种计划时长，用 subscription_type（new）排除产品变更和重新订阅；cohort 尚未有完整机会到达的周期会报告为不完整，不要当作零。
45. Reactivation：了解 Reactivation 的唯一真正方式是看 MRR Movement 图表和 Resubscription MRR。
46. 调查指标变动时按顺序执行：1) 量化变动——拉图表数据，确认幅度和时点。2) 检查配置——offerings、packages、products、paywalls 和 experiments 在指标中不可见，绝不要从图表推断它们；如果答案提到其中任何一项，本次运行中必须查证：用 list-experiments 查 status="stopped" 和 status="running"（若有实验在变动附近停止，调用 get-experiment-results 看哪个变体胜出）；用 list-offerings 且 limit: 100（默认 20 条很少覆盖真实项目），再对 is_current 的 id 调用 get-offering 且 expand: ["package.product"]（paywall_id: null 的 offering 没有 RevenueCat paywall，给 paywall 建议前先加载 revenuecat-paywall-design）；在说某产品已下架、不可用或不再销售前先调用 get-product-store-state，用平实语言报告商店状态，绝不用原始字段名；如果 experiments 和 offerings 解释不了，用 list-paywalls 查 paywall 变更。3) 检查 annotations——看图表响应中的 annotations 字段。4) 只有到这时才形成假设——以假设而非结论呈现；关于配置的未验证猜测是缺失的工具调用，绝不能作为标题结论。不要跳过第 2 步；调用后若结果无法解释变动，明确说明，而不是构造机制。
47. Populations 与分母：比率只描述其分母对应的人群，呈现前先确认这正是问题所指的人群。
48. 当某个 segment 主导分母时，混合比率描述的是该 segment 而非整个 App；重新按问题所指人群筛选查询，并以该数字为主。
49. 绝不要在把比率的分母称为膨胀或不具代表性的同时，又把它当作证据呈现；应改用筛选重新查询，而不是加注意事项。
50. 自己报告筛选后的数字，而不是建议用户去看筛选后的图表。
51. 分析对比：同类相比——任何两个相互比较的数字必须来自同一图表和指标，且转化窗口和 cohort 定义相同，日期范围也相同（除非是刻意的环比/同比对比）。
52. 如果对比的一方有指标而另一方没有，先用同一图表和设置查询缺失的一方再比较，不要用来自不同图表的值替代。
53. 对「{segment} 用户表现如何？」这类开放问题，不要止步于仅该 segment 的指标；拉取该 segment 和整体/未筛选基线在关键转化或收入质量指标上的数据，再相对基线判断表现；没有与基线对比就不要评价某 segment 为「健康」「表现不佳」等。
54. 不要把筛选后的新客 cohort 的收入或转化与所有 cohort 和续订的总 App 收入比较；如果拿不到匹配的基线，明确说明并避免方向性表现结论。
55. 当用户困惑于两个指标背离时，先说明各自统计的是什么，再解释差距。
56. 生成 Dashboard 链接：链接必须遵循 Dashboard URL Format，且必须基于此前一次成功的 get-chart-data 调用；若没有，先走上面的查询工作流。
57. 构造链接：以 https://app.revenuecat.com/projects/{project_id}/charts/{chart_name} 为基址；添加必需的 range 参数（日期范围）；添加 resolution 参数（不要信任默认值）；把筛选加为 filter 参数；如有分组加 segment 参数；按需加图表专属 selectors；对所有值做 URL 编码（空格 → +，冒号 → %3A 等）。
58. Dashboard URL 格式必须严格为 https://app.revenuecat.com/projects/{project_id}/charts/{chart_name}?range={range_value}：{project_id} 是短十六进制 ID（如 56965ae1），不是完整的 proj56965ae1；{chart_name} 与 get-chart-data 使用的图表名相同（revenue、churn、mrr、conversion_to_paying 等）；project ID 放在路径中，不作为查询参数。
59. range 参数为必需，格式 {preset}:{start_date}:{end_date}，start_date 和 end_date 用 YYYY-MM-DD，preset 用 Custom；始终用这个格式，不要用 start_date、end_date、chart_start 或 chart_end 参数；各部分之间的 : 必须 URL 编码为 %3A（例：range=Custom%3A2025-01-01%3A2025-12-31）。
60. resolution 参数取值：0 为日、1 为周、2 为月、3 为季、4 为年。
61. segment 参数用你在 get-chart-data 请求中使用的确切维度 ID（如 country、store、product_id、platform、offering_identifier）；各图表支持的 segment 不同，只链接你在该图表 get-chart-data 调用中成功用过的 segment。
62. filter 参数作为独立的查询 filter 参数传入，内容为 {dimension}%3A%3D%3A{value}，维度名用 get-chart-data 请求中使用的（如 filter=country%3A%3D%3AUS、filter=store%3A%3D%3Aapp_store、filter=product_id%3A%3D%3Aprodbb68905d98、filter=platform%3A%3D%3AiOS）；多个筛选就包含多个 filter 查询参数——同一维度的多个筛选为 OR，不同维度之间为 AND。
63. 图表专属 selectors 作为独立查询参数传入，名称和值与 get-chart-data 的 selectors 参数一致（示例：revenue 图表的 revenue_type 为 revenue、revenue_net_of_taxes 或 proceeds；conversion 图表的 conversion_timeframe 为 0_days、3_days、7_days、14_days、30_days 或 unbounded；realized LTV 图表的 customer_lifetime 为 7_days、14_days、30_days、3_months 到 24_months 或 unbounded）。
64. API 参数到 Dashboard 参数的映射：start_date + end_date → range=Custom%3A{start}%3A{end}（用 Custom preset）；segment → segment；filters（JSON 数组）→ 独立的 filter 查询参数；selectors（JSON 对象）→ 独立的查询参数。
65. 获取 project ID：用 list-projects 工具列出所有项目及其 ID；工具返回以 proj 开头的 ID（如 proj56965ae1），用于 dashboard URL 时去掉 proj 前缀，路径中只用 56965ae1。

适用边界 · 注意事项

• 需要预测、预估或 run-rate 时，应改用 revenuecat-forecasting 技能，而不是本技能的图表查询流程。
• 不要用本技能从图表推断 offerings、packages、products、paywalls 或 experiments 等配置——这些在指标中不可见，必须用对应工具查证。
• 不要在没有成功 get-chart-data 调用的情况下构造 Dashboard 链接。