stigg-credits

Stigg Credits — 基于额度的变现

此技能是额度端到端功能的权威指南：额度货币定义、额度发放（周期性 / 预付 / 促销 / 手动 / 透支）、运行时消耗（映射、自定义公式、账本）、自动充值、基于席位的额度池、计费集成和收入确认。静态的目录结构（作为权益附加到计划 / 附加项上的周期性额度发放）位于 stigg-pricing-modeling/references/credits-modeling.md；其他所有内容都在此处。

开始之前

根据总览 stigg 技能：先搜索。 额度功能发展迅速（自定义公式、透支机制、基于席位的额度池都是近期新增的功能）。编写内容前，使用 Mintlify Stigg 文档 MCP（search_stigg、query_docs_filesystem_stigg）确认具体信息。

心智模型 — 五个部分

                              ┌──────────────────────────────────┐
                              │   Credit currency (the unit)     │
                              │   "AI tokens", "API credits",    │
                              │   "compute units"                │
                              └────────────────┬─────────────────┘
                                               │ denominates
                                               ▼
   Grants funded by:        ┌──────────────────────────────────┐
   • Recurring (plan/addon)  │   Credit pool (per customer,    │
   • Prepaid (purchase)      │   per credit currency)          │
   • Promotional (zero cost) │   = balance + many grants       │
   • Manual                  └────────────────┬─────────────────┘
   • Overdraft (system)                       │ deducted by
                                              ▼
                              ┌──────────────────────────────────┐
                              │   Consumption mapping or         │
                              │   custom formula  (per plan)     │
                              │   metered feature → credits      │
                              └────────────────┬─────────────────┘
                                               │ records
                                               ▼
                              ┌──────────────────────────────────┐
                              │   Credit ledger (append-only)    │
                              │   grants, burns, expirations,    │
                              │   revocations, adjustments       │
                              └──────────────────────────────────┘

references/grants.md、references/consumption.md、references/ledger.md、references/auto-recharge.md、references/seat-pools.md、references/custom-formulas.md、references/billing-integration.md、references/revenue-recognition.md。

额度货币

额度货币（在 Stigg 应用的目录 UI 中称为“额度类型”）是你的消耗单位，例如 tokens、credits、compute units。客户使用计量功能时，会从以该货币计价的额度池中扣除额度。

• **完整的货币生命周期操作——定义、更新、归档、取消归档、列出，以及检查关联的计划 / 附加项——可通过 Stigg MCP（AI 辅助开发的首选方式）**或 Stigg 应用中的 Product Catalog → Credits 获取。端到端的额度消耗工作流（货币 → 计量功能 → 按计划划分的消耗映射 → 发放 → 用量报告）可完全通过 MCP 执行。编写内容前，请刷新实时 MCP 工具列表或查看文档——操作名称和字段结构以实时接口为准，而非本技能。
• 单数 / 复数显示名称，例如“token” / “tokens”；ID 不可变。归档前请检查依赖项——如果货币仍被有效计划或附加项引用，Stigg 会阻止归档。
• 不同货币之间不可互换——针对一种货币的用量不能消耗另一种货币。
• 不是计费货币。 自定义额度货币是消耗单位；有关多币种计费（USD/EUR/JPY），请参阅 stigg-pricing-modeling/references/price-localization.md。
• 目录侧的建模结构（作为权益附加到计划 / 附加项上的周期性额度发放）位于 stigg-pricing-modeling/references/credits-modeling.md。

额度池

每个 (customer, credit currency) 对应一个额度池（对于支持多个活跃产品的情况，还需按 resourceId 区分）。额度池包含多个额度块（也称为“发放”或“分配”），每个额度块都有 amount、生命周期日期（effective_at / expires_at）、category（付费 / 促销）、cost_basis（每额度的成本，用于收入确认）、priority（值越小，优先级越高）和 status。完整字段参考：references/grants.md。

五种额度发放类型

类型	来源	成本基础	常见周期
周期性	计划 / 附加项权益	付费（计划价格）	每个计费周期（每月 / 每年 / 等）
预付	客户预先购买	付费	一次性额度包
促销	手动发放，用于促成采用 / 激励	零（绝不影响收入）	一次性，通常有时限
手动调整	管理员添加或移除	付费或零（由管理员选择）	不定期
透支	系统生成；用于追踪负余额	不适用	自动创建、自动结算

建模结构（将周期性额度作为权益附加到计划或附加项）参见 stigg-pricing-modeling/references/credits-modeling.md。运行时的额度发放（预付 / 促销 / 手动）位于此处的 references/grants.md。

消耗 — 在套餐上配置

计量功能如何转换为积分，需在套餐上（以及每个附加项上）配置，而不是在功能或积分货币上配置。每个套餐都可以选择固定转换率（1 token = 1 credit）或基于维度的自定义公式（credits = 2.5 × input + 10 × output）。同一功能在不同套餐上采用不同规则，完全受支持。

路径：产品目录 → 套餐 → 选择套餐 → 编辑价格 → 设置价格 → 积分消耗（针对套餐中的每个计量功能）。

扣减顺序 — 多笔授予均符合条件时

事件消耗 N 个积分后，Stigg 会按以下顺序选择要扣减的授予：

1. 优先级 — 数值越小，优先级越高。
2. 到期日期 — 越早到期的授予越先扣减。
3. 类别 — 其他属性相同时，促销类先于付费类。
4. 生效日期 — 越早生效的越先扣减。
5. 创建日期 — 其他条件都相同时，越早创建的越先扣减。

如果单个事件所需的积分超过排名最高的授予额度，Stigg 会依次从下一笔、再下一笔授予中扣减，并且每笔被扣减的授予都会单独生成一条账本记录。references/consumption.md 中有完整示例。

透支 — 负余额

Stigg 支持负积分余额。当使用事件所需的积分超过客户持有的积分时，系统会自动创建一笔透支授予来记录差额。**始终启用，无法关闭。**透支授予：

• grant_type: OVERDRAFT、amount: 0，consumed_amount 等于差额。
• 每个 (customer, currency) 仅有一笔透支（按资源范围限定时，每个资源也仅有一笔）。
• 不能手动编辑或作废。
• 新积分到账时自动结清，可全额或部分结清。

详细行为和完整示例：references/consumption.md。

自定义消耗公式

对于可变成本的工作负载（多模型大模型操作、多输入处理、加权 Token 成本），可以定义自定义公式，而不是使用固定转换率：

credits_used = (a × documents) + (b × emails) + (c × images)
credits_used = (1.1 × model1_tokens) + (1.5 × model2_tokens) + (5 × model3_tokens)

在每个计量功能上配置，路径为产品目录 → 套餐 → 编辑价格 → 设置价格 → 积分消耗 → 计算模式：高级公式。完整机制见：references/custom-formulas.md。

自动充值

当客户余额低于阈值时自动购买积分，避免预付余额耗尽：

设置	作用
当积分余额低于	触发阈值。
然后将积分余额恢复至	充值后的目标余额。
将每月总支出限制为	每个周期内自动充值支出的硬性上限。
支出限额重置频率	限额重置的周期。
授予有效期	自动购买的积分保持有效的时长。
付款方式	自动充值所用的银行卡等方式。

需要处理的 Webhook 事件：

• automatic_recharge.operation.attempted — 每次尝试都会触发（成功或失败）。
• credits.automatic_recharge_limit_exceeded — 支出达到限额的 80%、90%、100% 时触发。
• automatic_recharge.configuration.changed — 配置启用或禁用时触发，包括由系统驱动的变更（例如付款失败）。

设置指南：references/auto-recharge.md。

基于席位的积分池

将周期性积分授予关联到计量席位功能，使积分随团队规模扩展：

“每个席位每月 1,000 个 AI 积分” → 5 个席位 = 每月 5,000 个积分 → 添加第 6 个席位后自动再发放 1,000 个积分。

积分会进入共享池（而非按用户隔离）——整个组织共用一个余额。**需要集成 Stripe。**适用于同时包含积分权益和计量席位功能的套餐或附加项。配置方法见 references/seat-pools.md。

账单集成

Stigg 与你的账单系统协同工作，无需彻底替换现有系统。你的账单服务提供商（Stripe / Zuora / 自定义）负责付款、税费、发票和付款方式。Stigg 负责额度池、额度发放、消耗和管控。

资金发生变动时：

事件	Stigg 的响应
客户付款	Stigg 创建一笔已付款额度发放，包含金额、cost_basis 和日期，更新额度池，并写入账本。
发放促销额度	Stigg 创建一笔 cost_basis 为 0 的额度发放（不影响收入）。
退款 / 撤销	你在 Stigg 中撤销相应的额度发放，使递延收入 / 已确认收入保持一致。

系统边界（各自负责的内容）：

• 你的账单系统： 产品目录和价格、税费、开票、付款、退款、催收。
• Stigg： 额度类型（目录界面中称为“credit types”）、额度池、额度发放、实时消耗、账本、客户组件。

常见流程（自助充值、销售驱动的发票、自动充值）：references/billing-integration.md。

收入确认

Stigg 为财务团队提供可审计的记录。每笔额度发放都记录：amount_granted、amount_remaining、amount_consumed、expires_at、category、cost_basis（单价）。只追加账本会记录每次扣减 / 到期 / 撤销。

Deferred revenue   = amount_remaining × cost_basis      (paid grants only)
Recognized revenue = consumed_in_period × cost_basis
Breakage           = expired_in_period × cost_basis     (per your policy)

促销额度发放的 cost_basis 为 0 → 永远不会影响收入。完整的日记账分录模型和对账模式：references/revenue-recognition.md。

额度 Webhook

额度相关事件（credit.balance.low / .depleted、credit.grant.*、automatic_recharge.*）可用于驱动应用内通知、客户挽回活动和付款失败处理流程。有关负载格式、签名验证、重试语义和处理程序骨架，请参阅 stigg-webhooks。

不应使用此技能的情况

• 为非额度功能 / 计划 / 附加项建模 → stigg-pricing-modeling。
• 对布尔值 / 配置类功能进行运行时权益检查（不涉及额度）→ stigg-entitlements。
• 配置 / 取消订阅 → stigg-subscriptions。
• 判断额度是否适合作为定价模型 → stigg-pricing-expert。

常见错误

错误	修正方法
尝试禁用透支	无法配置。系统始终会记录赤字，而不会拒绝事件。请据此做好规划。
将促销的 cost_basis 设为非零	这会污染收入核算。促销额度的 cost_basis 必须为零。
在订阅开通前发放额度	这是允许的（额度池会保留），但大多数团队希望额度随计划生命周期变化——请确认预期。
随意为每次发放选择优先级数字	数字越小，优先级越高。请制定并遵循一套规则（例如：促销=1，定期=10，预付=20）。
忘记在计划上添加用量映射	映射位于计划上，而非功能上。将按量计费的功能添加到目录，并不会让现有计划自动使用额度抵扣该功能的用量——每个计划都需要单独配置映射。
在功能上而非计划上配置公式	功能定义要衡量的内容；计划决定如何将该衡量值换算为额度。不同计划可以对同一功能使用不同的费率／公式。
将每种 Token 模型的价格建模为独立功能	改用自定义公式——credits_used = w1 * tok1 + w2 * tok2。
配置自动充值时使用的支付方式失效	Stigg 会触发 automatic_recharge.configuration.changed 并禁用自动充值。请立即在应用中显示这一状态。
从头构建额度余额界面	Stigg 提供现成组件（额度余额、使用率、用量图表、发放记录表、自动充值状态、自动充值配置）——请参阅 stigg-widgets。
导出额度数据到 BI 时未包含 cost_basis	没有它就无法计算收入。导出时始终包含 cost_basis 和发放 ID。
将账本视为最终一致	账本仅追加且具有权威性。财务对账时请读取账本；不要根据单个事件重建账本。