把 ASC 与 RevenueCat 对齐：asc revenuecat-catalog-sync 订阅目录同步与审计完整指南

如果你用 RevenueCat 管理 App 内购，多半经历过这样的窘境：App Store Connect（ASC）里新增了一个订阅，RevenueCat 里却忘了配置，两边目录逐渐"漂移"，排查起来费时费力。app-store-connect-cli-skills 项目中的 asc revenuecat-catalog-sync 技能就是为了解决这个痛点——它基于 asc CLI 与 RevenueCat MCP，帮你完成 ASC 订阅目录与 RevenueCat 产品目录的同步与审计：先只读审计差异，再在确认后补齐缺失的 ASC 订阅/IAP 并建立映射。

这个技能解决什么问题？

在 iOS 订阅业务中，两个系统各有分工：

系统	职责
App Store Connect	商店侧的商品"事实来源"：订阅组、订阅、IAP、价格与地区
RevenueCat	应用侧的商业模式：产品（products）、权益（entitlements）、投放（offerings）、套餐（packages）

常见问题包括：

• 🕳️ 单侧缺失：ASC 有订阅但 RevenueCat 没建产品（或反过来）
• 🏷️ 映射冲突：productId 相同却类型不一致、挂错了平台应用
• 🧱 半成品状态：RevenueCat 里有映射，但 ASC 侧订阅还没通过审核所需的元数据、截图、价格矩阵

该技能定义在 SKILL.md，配套的完整执行模板在 examples.md，命令与工具边界说明见 references.md。

什么时候该用它？

适用场景（摘自技能文档 "When to use" 部分）：

1. 从零起步：已有 ASC 目录，想把 RevenueCat "引导"出来
2. 反向补齐：RevenueCat 规划好了产品，但 ASC 里订阅/IAP 还没建
3. 发布前漂移审计：上线前快速核对两边是否一致
4. 确定性映射：希望基于稳定标识符（而非显示名称）做产品映射

核心机制：以 productId 为唯一跨系统键

这是整个工作流最关键的一条规则：

ASC 的 productId == RevenueCat 的 store_identifier

配套原则：

• ✅ 商品上线后保持 productId 稳定
• ❌ 不要用显示名称（display name）当唯一标识——名字会改，标识符不会
• ✅ 匹配时优先按 store_identifier 精确查找

这样即使你换了显示名、换了语言，映射关系也不会断。

两种模式：先审计，后应用

1）审计模式（默认，只读）

流程是：读取 ASC 目录 → 读取 RevenueCat 目录 → 生成差异清单 → 输出计划。差异会分为三类：

• missing in ASC：RevenueCat 有、ASC 没有
• missing in RevenueCat：ASC 有、RevenueCat 没有
• mapping conflicts：标识符/类型/平台不匹配

审计请求到此为止，只给结论；只有明确要求"应用"时才会写数据，且需要你对完整差异清单给出一次明确确认。

读取 ASC 侧使用的典型命令（完整分页，避免漏数据）：

asc subscriptions groups list --app "APP_ID" --paginate --output json
asc iap list --app "APP_ID" --paginate --output json
asc subscriptions list --group-id "GROUP_ID" --paginate --output json

RevenueCat 侧则通过 MCP 工具读取，如 mcp_RC_list_apps、mcp_RC_list_products、mcp_RC_list_entitlements、mcp_RC_list_offerings、mcp_RC_list_packages。

2）应用模式（显式确认后执行）

获批后按固定顺序执行，保证每一步都有前置条件：

1. 确保 ASC 的订阅组 / 订阅 / IAP 存在
2. 确保 RevenueCat 的应用和产品存在
3. 确保权益（entitlements）和产品挂载
4. 确保 offerings / packages 及挂载
5. 回读验证，输出最终对账摘要

类型映射：ASC 商品如何对应 RevenueCat 产品

同步时需要做类型转换，规则很直接：

ASC 商品类型	RevenueCat 产品类型
订阅（subscription）	subscription
IAP CONSUMABLE	consumable
IAP NON_CONSUMABLE	non_consumable
IAP NON_RENEWING_SUBSCRIPTION	non_renewing_subscription

权益（entitlement）的推荐策略也值得记住：

• 订阅：每个订阅组一个权益（或用户提供显式映射）
• 非消耗型 IAP：每个产品一个权益
• 消耗型 IAP：默认不挂权益，除非你明确要求

补齐缺失 ASC 商品的正确姿势

这是该技能比"简单建个映射"高级得多的地方。应用模式中补齐 ASC 商品时，遵循严格的 零/一/多 规则：

• 零个精确匹配（全分页读取后确认不存在）→ 才执行创建
• 一个精确匹配 → 复用其 ID，绝不重复创建
• 多个匹配 → 停下来，要求你显式指定 ID

以创建订阅为例（条件分支，不是照抄执行）：

# 仅当全分页列表零匹配时执行
asc subscriptions setup \
  --app "APP_ID" \
  --group-id "GROUP_ID" \
  --reference-name "Monthly" \
  --product-id "com.example.premium.monthly" \
  --subscription-period ONE_MONTH \
  --review-screenshot "./review.png" \
  --price "3.99" \
  --price-territory "USA" \
  --territories "USA" \
  --no-verify \
  --output json

注意几个细节：

• subscriptions setup 会一次完成父级订阅、App Review 截图投递、完整价格矩阵和售卖地区
• 版本级的本地化（名称/描述）需要单独的 version 命令补齐——这部分 RevenueCat 帮不了你
• 如果已有订阅仍报 MISSING_METADATA，用 --repair 原子性重建价格矩阵

严格验证门：审计证据先于映射

技能对"什么时候可以创建/挂载 RevenueCat 产品"设了硬性闸门：

mkdir -p "./audit"
asc validate subscriptions --app "APP_ID" --strict --output json --pretty \
  > "./audit/subscriptions-validation.json"

asc validate iap --app "APP_ID" --strict --output json --pretty \
  > "./audit/iap-validation.json"

规则是：只要验证器报出警告、错误、MISSING_METADATA、审核截图未 COMPLETE、价格覆盖不全，就不允许映射对应的商品——哪怕这次运行一个写操作都没做。两个 JSON 文件留存为审计证据。这保证了"RevenueCat 里的映射存在"绝不等于"ASC 侧订阅已就绪"。

应用模式的安全护栏

该技能内置了几条值得所有自动化工作流借鉴的"安全默认值"：

• 🔒 永远从审计模式开始，即使最终要应用
• ✅ 写操作前必须拿到对完整当前差异的显式确认；差异无变化可复用先前批准
• 🚫 整个流程从不删除任何 ASC 或 RevenueCat 资源
• ⏭️ 单项失败不中断，继续处理后续项目，最后汇总所有失败

典型输出：一眼看懂对账结果

流程结束时会输出结构化摘要：

ASC: created groups=1 subscriptions=2 iap=1, skipped=14, failed=0
RC: created apps=0 products=3 entitlements=2 offerings=1 packages=2, skipped=27, failed=1
Attachments: entitlement_products=3 package_products=2
Failures:
- com.example.premium.annual: duplicate store_identifier exists on another RC app

created / skipped / failed 三类计数分开统计，失败项附带可操作的错误原因——这个格式也方便接入 CI 做机器解析。

常见坑与避坑清单

技能文档专门列出了高频踩坑点（Common pitfalls），翻译成人话就是：

坑	说明
用错 project_id / app ID	RevenueCat 里项目选错，产品全建到别处
挂错平台应用	产品建到了 app_store 应用下，而你的 App 在 mac_app_store
消耗型 IAP 挂权益	违反默认策略，导致应用侧权益逻辑混乱
跳过创建后回读	只信"创建成功"，不重新读取确认
ASC 没就绪就映射	本地化、审核截图、价格矩阵没齐就建 RC 产品
建完不验证 offering/package	产品存在但套餐挂载缺失，端上拉取 offering 失败

前置条件：开工前检查清单

开始同步前，请确认以下条件（缺一不可）：

1. asc 已认证：asc auth login 或配置了 ASC_* 环境变量
2. RevenueCat MCP 服务器已配置并认证（Cursor / VS Code 中支持 OAuth，也支持 API key）
3. 你手上有：ASC 应用 ID（APP_ID）、RevenueCat project_id、目标平台类型（app_store 或 mac_app_store）与 bundle ID
4. 应用变更时使用具备写权限的 RevenueCat API v2 key

如何安装这个技能

整个技能包基于 asc CLI 安装，一条命令：

asc install-skills

也可以通过 Agent Skills 安装器安装：

npx skills add rorkai/app-store-connect-cli-skills

如果你是 Claude Code 用户，仓库本身就是一个插件市场：

claude plugin marketplace add rorkai/app-store-connect-cli-skills
claude plugin install asc@rorkai

安装后技能自动生效——当你的请求涉及"核对 ASC 与 RevenueCat"、"补齐缺失订阅"这类任务时，Agent 会按本技能定义的审计→确认→应用→验证流程执行。

上手示例：一段话触发完整同步

技能设计上是"自然语言驱动"的，你可以直接对 Agent 说：

审计我的 App Store Connect 订阅和 IAP，与 RevenueCat 项目 PROJECT_ID 对比，列出两边各自缺失的内容；确认后补齐缺失项并建立映射。

Agent 会依次执行：全分页读取两侧目录 → 展示不写数据的差异计划 → 等待你的确认 → 按零/一/多规则补齐 ASC 商品 → 跑严格验证门 → 仅在验证通过后才创建 RevenueCat 产品与权益 → 输出最终对账摘要。完整执行模板（含只读审计、补齐订阅、同步一次性 IAP、CI 风格受控应用四个场景）见 examples.md。

小结

asc revenuecat-catalog-sync 的核心价值可以浓缩成三句话：

1. 以 productId 为唯一映射键，杜绝"名字一改映射就断"
2. 审计先行、显式确认、绝不删除，把写操作的风险压到最低
3. 严格验证门 + 审计证据留存，保证映射上的每个商品都是"商店侧就绪"的

如果你同时维护 ASC 与 RevenueCat 两套目录，这套审计→同步→验证的流程值得纳入发布前的固定动作——漂移在第一天发现的成本，远低于上线后排查。