stigg-pricing-modeling

Stigg 定价建模 — 构建目录

本技能涵盖完整的目录范围：产品、计划、附加组件、功能、收费项、优惠券和信用额度货币定义。不涵盖运行时门控（stigg-entitlements）或订阅生命周期（stigg-subscriptions）。

开始之前

根据总览技能 stigg 的要求：**先搜索。**目录建模变化很快，编写配置前，请使用 Mintlify Stigg 文档 MCP（search_stigg、query_docs_filesystem_stigg）或 Stigg MCP 服务的 search_docs 工具阅读当前页面。

MCP 优先的经验法则

尽量通过 Stigg MCP 执行所有目录操作。只要 MCP 支持，就不需要使用 UI。

原因：Stigg MCP 提供了用于目录建模的完整 Stigg API。Agent 会将“创建一个包含两个按量计费功能和 $49 基础收费项的 Pro 计划”转换为相应的 MCP 工具调用，无需点击或从 UI 复制粘贴。

目前 MCP 覆盖不完整的操作，按以下顺序依次处理：

1. Stigg MCP（mcp.stigg.io）——首选。参见 stigg-mcp。
2. Stigg CLI（brew install stiggio/tools/stigg — https://github.com/stiggio/stigg-cli）——仅在用户明确要求使用 CLI，或要求编写确定性脚本／CI 步骤时使用。
3. REST API——用于 SDK 尚未提供的操作。
4. Stigg UI（app.stigg.io）——最后手段，仅用于上述方式尚未覆盖的操作。请在技能的 MCP 覆盖矩阵中明确指出该操作，并链接到对应的 UI 页面。

权威的实时覆盖表位于 references/mcp-coverage-matrix.md。随着 MCP 覆盖范围扩大，请更新该文件；不要悄悄让技能逐渐变成“使用 UI”的说明。

目录概览

概念	含义	参考
产品	顶层产品线。用于关联计划、附加组件和客户旅程。控制每位客户可拥有一个还是多个订阅。	references/products.md
计划	产品中的一个等级。分为三种类型：Free、Paid、Custom。	references/plans.md
附加组件	对付费／自定义计划的模块化扩展。权益可叠加。	references/addons.md
功能	可设置门控的能力。类型包括：boolean、configuration（数值／枚举）、metered。	references/features.md
权益	计划或附加组件上的功能及其配置。（“每月 10,000 次 API 调用”。）	详见 plans/addons
收费项	计费内容：基础固定费用、按单位计费、按用量付费、预付承诺、最低消费、超额用量、积分收费。	references/charges-and-pricing-models.md
优惠券	应用于客户或特定订阅的折扣工具。	references/coupons.md
积分建模	目录侧积分——计划／附加组件上的积分发放、消耗映射。	references/credits-modeling.md（定义和运行时操作见 stigg-credits）
价格本地化	多币种／多区域计费。与自定义积分货币不同。	references/price-localization.md

选择合适的计划类型

目标	计划类型
免费增值等级，无需支付信息，可推动升级	Free
自助式付费产品（固定费用和／或按用量计费，可选试用）	Paid
由销售主导、按客户定价、权益可变	Custom

一个产品可以包含以上全部三种计划。客户通常在每个产品下有一个有效订阅（可配置；某些产品允许多个有效订阅并行，参见 references/products.md）。

选择合适的收费模式

目标	使用
可预测的月费	固定费用（例如每月 $49）
按选定的资源收费	按单位计费（例如每个席位每月 $10）
完全按用量计费	按用量计费——按需付费
客户预先承诺配额，之后进行差额结算	预付承诺
无论用量多少，都设定收入下限	最低消费
包含配额；超出配额后收费	超额用量（阶梯定价／分级定价／按单位计量）
基于积分的变现	积分收费
多区域定价	价格本地化（独立维度——叠加在收费模式之上）

详细机制、何时组合使用以及权衡取舍：references/charges-and-pricing-models.md。关于选择哪种模式的战略指导，请参阅 stigg-pricing-expert 技能——此技能用于执行已选定的模式。

功能——三种类型

类型	适用场景	权益是……
布尔型	开／关能力（“高级支持”）	授予或拒绝
配置型	数值或枚举值（“席位数”“可用模板”）	一个值
计量型	跟踪用量（“API 调用次数／月”）	一个值，可选用量重置周期（每小时／每天／每周／每月）和计量聚合方式（求和／计数／去重计数／平均值／最小值／最大值）

通过权益将功能关联到计划／附加项。同一功能在不同计划上可以有不同的权益（例如，“API 调用次数”在 Starter 上为 1k，在 Pro 上为 10k，在 Enterprise 上为无限）。

自定义积分货币与价格本地化

这两个概念容易混淆——它们是不同的概念。

• 自定义积分货币——定义一种用量单位（例如“AI 令牌”“API 积分”）。客户使用计量型功能时，会从以该货币计价的积分池中扣除。**与计费货币无关。**请参阅 references/credits-modeling.md 和 stigg-credits 技能。
• 价格本地化——多币种计费（例如，向欧盟客户显示／收取 EUR 价格，向日本客户显示／收取 JPY 价格）。这是叠加在任何定价模式之上的独立维度。请参阅 references/price-localization.md。

最常见的做法是：单个产品使用一种自定义积分货币进行积分计价，同时在付费计划中提供多种本地化计费货币。

草稿、版本与发布

计划和附加项的编辑采用草稿 → 已发布版本流程：

• 打开草稿，进行编辑，然后发布，使其成为新的有效版本。
• 旧版本上的现有订阅将继续沿用旧版本，直到你迁移它们（详见 stigg-subscriptions/references/plan-version-migration.md）。
• 发布时，根据发布计划端点选择迁移策略（例如仅 NEW_CUSTOMERS，或强制迁移）。
• 附加项也有类似的草稿／发布流程——流程相同。

编写发布逻辑前，务必重新获取当前的草稿／发布文档页面。可用的迁移类型和副作用会不断变化。

目录建模工作流

通过 MCP 完成的典型端到端流程：

1. Define features.            ← reusable building blocks
2. Group features (optional).  ← for shared entitlements across plans
3. Create the product.         ← anchors plans & add-ons
4. Create plans.               ← assign feature entitlements + charges
5. Create add-ons.             ← additive entitlements + their own charges
6. (Optional) Define coupons.
7. (Optional) Configure price localization.
8. Publish.                    ← chooses migration policy for existing subs

每个步骤都应先搜索文档，再调用 MCP。顺序很重要，因为计划和附加项会引用功能，而附加项会引用计划以确定兼容性。

不适用此技能的场景

• 运行时权益检查（getMeteredEntitlement、getBooleanEntitlement、getEntitlement，以及它们返回的 entitlement.hasAccess 属性）→ 使用 stigg-entitlements。
• 配置、更新或取消订阅 → 使用 stigg-subscriptions。
• 为客户的产品选择适合哪种变现模式 → 使用 stigg-pricing-expert。
• 在生产环境中操作积分授予、账本和自动充值 → 使用 stigg-credits。（此技能涵盖目录中积分货币和积分收费的建模。）

常见错误

错误	修正方法
未创建草稿就直接编辑已发布的计划	始终遵循“起草 → 编辑 → 发布”的流程；发布时为现有订阅选择迁移类型。
忘记附加项与计划之间的兼容性规则	附加项按计划声明兼容性；确保该附加项列在计划的兼容附加项中。
将“自定义额度货币”当作计费货币	自定义额度货币 = 消耗单位（令牌、额度）。计费货币 = USD/EUR 等——请参阅价格本地化。
将按席位计费建模为计量功能	使用按单位收费的配置功能。计量功能用于跟踪一段时间内的消耗。
设置与计费周期不匹配的用量重置频率	重置频率应与客户账单的周期保持一致——按月计费通常应每月重置。
为本应属于附加项权益的内容设置计划级权益	如果属于可选项或需要额外付费，应将其建模为附加项，以便叠加使用并单独定价。
MCP 支持的操作却使用了 UI	默认使用 MCP。如果发现覆盖范围缺失，请更新 references/mcp-coverage-matrix.md；目标是让 UI 后备方案减至零。