VTEX IO app 的 manifest.json…

当需要定义或修改 VTEX IO app 的 manifest.json 契约（身份、builders、dependencies、peerDependencies、billingOptions）时，用最小、正确、可发布的契约保证 app 可 link、publish、安装和升级。

适用场景

解决思路

1. 把 manifest.json 视为 app 契约：在其中声明身份、builders、dependencies、peerDependencies 以及其他 app 或平台依赖的高层能力。
2. 仅在 app 真正拥有某能力时才添加对应 builder；builders 不是未来工作的占位符。
3. 保持契约狭窄：若 manifest 开始表示互不相关的关注点，把这些关注点拆成独立 app，而不是创建一个 catch-all app。
4. 仅把可以安全地随当前 app 契约自动安装的 app 放入 dependencies。
5. 把必须已在环境中存在、保持外部管理、或声明了 billingOptions 的 app 放入 peerDependencies。
6. 保持命名和版本可发布：vendor、name、version 必须组成稳定身份，能安全 link、publish 和被消费。
7. 保持 billingOptions 与 app 的商业契约一致；若 app 有计费含义，在 manifest 中显式声明，不要留下隐式定价行为。
8. 声明 billingOptions 的 app 不能通过 dependencies 消费；若当前 app 需要可计费 app，用 peerDependencies 建模，并要求 account 或 edition owner 手动安装。
9. Edition apps 是 app 契约的组合，不是契约的例外；保持每个底层 app 契约显式、狭窄且 semver-safe，以便在 host environments 中组合可预测。
10. manifest.json 可以声明 app 级 permissions 和 configuration surfaces，但详细 policy modeling 属于安全类技能，详细 settingsSchema 设计属于 app-settings 类技能。
11. Builder 归属：app 契约包含后端运行时能力时声明 node。
12. Builder 归属：app 契约包含 GraphQL schema 暴露时声明 graphql。
13. Builder 归属：app 契约包含 React bundles 时声明 react。
14. Builder 归属：app 契约包含 Admin UI surfaces 时声明 admin。
15. Builder 归属：app 契约包含 Store Framework block registration 时声明 store。
16. Builder 归属：app 契约包含 localized message bundles 时声明 messages。
17. Builder 归属：app 契约包含 storefront pixel injection 时声明 pixel。
18. Builder 归属：app 契约包含 Master Data schema assets 时声明 masterdata。
19. 契约边界启发式 1：若能力随此 app 发布、版本化并维护，在此声明其 builder。
20. 契约边界启发式 2：若能力仅从另一个 app 消费，声明 dependency，而不是重复 builder。
21. 契约边界启发式 3：若能力引入独立 runtime、security model 或 release cadence，考虑拆分到另一个 app。
22. 硬约束：若 app 发布任何可处理的 VTEX IO 能力，manifest.json 必须声明对应 builder；不要只依赖文件夹存在，也不要假设 VTEX IO 会从仓库结构推断能力。
23. 对称地，不要为 app 实际未发布的能力声明 builders。
24. 检测：若看到被维护的 /node、/react、/graphql、/admin、/store、/messages、/pixel 或 /masterdata 目录，停止并确认 manifest.json 中存在匹配 builder；若 builder 存在但能力不存在，停止并删除 builder 或把能力移回范围。
25. 硬约束：vendor、name、version 必须标识有效的 VTEX IO app 契约；app name 使用 kebab-case，vendor 与 ownership 一致，version 使用完整 semantic versioning。
26. 检测：若看到大写字符、下划线、非 semver 版本，或 vendor/name 变更混入不相关工作，停止并确认该变更是否有意且 release-safe。
27. 硬约束：若 app 发布 store/blocks.json、store/routes.json、store/templates/ 或 store/contentSchemas.json（即在 Store Framework 意义上的 content-holding app），必须把 version 字段视为面向商家的字段。
28. 对 content-holding app 执行 vtex release major 会改变 vtex.pages-graphql 查找每次 Site Editor 编辑、自定义路由和每模板渲染缓存所用的 key prefix。
29. vtex.pages-graphql 按 vendor.app@MAJOR.x:template 对商家内容建 key；patch 和 minor bump 保留 key，major bump 改变 key；major bump 后旧内容对 resolver 不可见，storefront 回退到默认 vtex.store-theme 内容。
30. 官方恢复路径：在 vtex.pages-graphql@2.x 中执行 updateThemeIds mutation；在安装新 major 后、promote 前，于带 production-flag 的 dev workspace 中执行，以把所有 Site Editor 编辑、Pages 和 Redirects 从旧 major 重新 key 到新 major。
31. 检测：在批准对 manifest 的 builders 中声明 “store”（或发布 store/ 下任何文件）的 app 执行 vtex release major 前，停止并要求在带 production-flag 的 dev workspace 中给出明确的 updateThemeIds 迁移计划。
32. 在 production account 上安装此类 app 的任何新 MAJOR 前，也应用同样的 updateThemeIds 迁移要求。
33. 对 content-holding app，vtex release patch 和 vtex release minor 会保留内容 key，可安全使用。
34. 不要在 content-holding app 上直接把 vtex release major、vtex publish、vtex install acme.store-theme@5.0.0 推到 master；否则 Site Editor 编辑会不可见并回退到默认主题。
35. 硬约束：dependencies 只用于此 app 应作为其契约一部分安装且可安全自动安装的 app。
36. peerDependencies 用于必须已存在于环境、应保持外部管理或声明 billingOptions 的 app。
37. 这是 app 与 VTEX IO workspace 其余部分的核心契约边界；错误分类会导致安装损坏、隐藏耦合和只在 link 或 publish 后出现的环境特定行为。
38. builder-hub 会拒绝 dependencies 中包含声明 billingOptions 的 app。
39. 检测：若 app 需要在每个环境中都依赖另一个 app 才能运行，停止并确认它属于 dependencies 还是 peerDependencies。
40. 检测：若目标 app 声明 billingOptions，停止并将其移到 peerDependencies。
41. 检测：若 app 仅与平台能力、host app、edition-managed app 或 account 应手动管理的 paid app 集成，停止并使其不进入 dependencies。
42. 首选模式：先为 app 决定最小可用契约，然后只声明该契约所需的 identity 和 builders。
43. 可用于聚焦的 service-plus-GraphQL app 的推荐 manifest 结构：vendor、name、version、title、description、builders（如 node、graphql、messages）、billingOptions、dependencies（如 vtex.search-graphql: 0.x）、peerDependencies（如 vtex.store: 2.x）。
44. 推荐契约拆分：reviews-platform/ 包含 manifest.json、node/、graphql/、messages/；reviews-storefront/ 包含 manifest.json、react/、store/。
45. 当 backend/API 契约与 storefront 契约具有不同 ownership、release cadence 或 integration boundaries 时，使用上述拆分。
46. 避免常见失败：不要为尚未拥有的 aspirational capabilities 声明 builders，否则契约比真实实现更宽。
47. 避免常见失败：不要用一个大型 manifest 表示 backend runtime、frontend rendering、settings、policies 和 integration concerns；应分离到多个技能或 app。
48. 避免常见失败：不要把 host-level apps 放入 dependencies；它们通常应保持为 peerDependencies。
49. 避免常见失败：不要锁定精确 dependency 版本；使用 major-version ranges，如 0.x、1.x、3.x。
50. 避免常见失败：不要把 manifest.json 当作 runtime 或 security details 的倾倒场；这些属于更具体的技能。
51. 避免常见失败：不要在此建模 settingsSchema；此技能只用于决定 app 级配置是否属于契约。
52. 审查清单：确认 manifest 只描述此 app 实际拥有并发布的能力。
53. 审查清单：确认每个已发布能力都有匹配的 builder 声明。
54. 审查清单：确认 app identity 可发布：有效 vendor、kebab-case name、完整 semver version。
55. 审查清单：若 app 有 billing 行为，确认 billingOptions 显式且与 app 契约一致。
56. 审查清单：确认 dependencies 与 peerDependencies 按安装意图分离。
57. 审查清单：评估把契约拆成两个 app 是否能减少不相关关注点或发布耦合。
58. 审查清单：确认 runtime、route、GraphQL implementation、frontend 和 security details 不放在此技能范围内。
59. 审查清单：若 app 发布 store/ 下任何文件，确认已审查任何计划中的 major version bump 的商家侧影响。
60. 相关技能：当 app 声明 store builder 且版本变更必须保留或迁移 Site Editor 内容时，使用 vtex-io-storefront-theme-versioning。
61. 相关技能：当问题在于 theme app 的 store/ 文件应拥有什么时，使用 vtex-io-storefront-theme-app。
62. 参考官方文档：Manifest、Builders、Dependencies、Billing Options、Creating the New App。

适用边界 · 注意事项

• 不用于 service runtime 行为，如 service.json、memory、workers、route exposure。
• 不用于 HTTP handler 实现、middleware 组合、event processing、GraphQL schema/resolver/data-fetching 实现，以及 storefront/admin/render-runtime 前端行为。
• 不用于 policy modeling 和 security boundary enforcement；详细 settingsSchema 设计应使用 app-settings 技能。