clerk-billing

整合 CI 检查并提高 clerk-setup 的准确性 将检查器移入 scripts/，置于根 package.json 之下，用 Test 和 Check 工作流替换 逐项检查工作流和复合操作，并用 concurrently 运行所有检查。 修正 clerk-setup 中关于脚手架和引导支持的声明，按平台对 auth-controls 步骤进行门控，将 Core 2 检测移到 setup 之前，并 全程使用 Markdown 链接。在不变量检查器中于 init 之前捕获内联代码登录。 重新指向过时的 README 和同级技能引用。 Co-Authored-By: Claude Opus 5.5

docs(skills)：移除 keyless 品牌和已废弃的 SDK keyless 流程 对应 clerk/clerk#3209：描述行为（临时开发 密钥，无需账户）而非 keyless 品牌，并从 setup 文案中删除 框架列表。 - clerk-setup：将 SDK 的 'Keyless (Automatic)' 密钥路径（已在 @clerk/nextjs 7.8.0 中移除）替换为 clerk init 流程；修正 frontmatter 兼容性行；将版本提升至 2.5.0 - clerk-setup evals：按 'clerk init temporary development keys' 而非 'keyless dev mode' 评分 - clerk-cli + references：重命名 Keyless 章节/锚点，改写 文字；字面 CLI 表面（--keyless、.clerk/keyless.json、whoami 的 keyless 对象）有意保留 - clerk router、clerk-orgs、clerk-billing：单行改写

docs(skills)：keyless 是默认值——无需登录 CLI PR clerk/cli#395 使 keyless 成为未认证 clerk init 的默认值，并允许在无账户的情况下配置 keyless 实例。 更新那些仍声称 --keyless 是可选加入或 auth login 是前置条件的技能。 Co-Authored-By: Claude Fable 5

refactor(billing)：将 cli 命令从 config 换成 enable，以获得更清晰的启用说明

fix(billing)：从 b2c-patterns 参考中移除重复的 PricingTable 设置 'Full Pricing Page Setup' 片段重复了 SKILL.md 模式 1（基本的 渲染）。删除它；参考应扩展 B2C 特定模式，而非重复基本介绍。

fix(billing)：在参考中内联展示 Dashboard + CLI 两条路径，不回溯 SKILL.md 路径无关过于生硬。恢复内联的双路径提及（Dashboard URL 或 clerk config patch），使参考自包含，而不将 agent 引回 SKILL.md。

fix(billing)：使参考对 plan/feature 设置路径无关 参考应扩展模式，而非重定向回 SKILL.md 或规定设置路径。从 b2b-patterns 和 b2c-patterns 中删除 Dashboard/CLI 路径提及；SKILL.md 负责设置，参考专注于 plan 类型不变量和模式用法。

feat(billing)：在参考中为 plan/feature 创建添加 CLI 指引 在参考目前写着 'create plans in Dashboard' 的地方内联添加简短的 'or via clerk config patch, see SKILL.md → Agent-first' 指引。不重复完整侧边栏——参考保持专注于模式，SKILL.md 负责 CLI 流程。

fix(billing)：从技能内容中移除内部 Linear 工单引用 技能应不涉及 Clerk 团队内部工具。从 Notes 块中删除 AIE-823 链接和 'when the wrapper ships' 未来状态表述；只保留当前可用的内容。

fix(billing)：修正 Enable Billing 声明——它可通过 clerk config patch 工作 - 更新 STOP 提示框以展示两条路径（Dashboard 或使用 billing.user_enabled/organization_enabled 的 clerk config patch） - 更新 Quick Start 第 1 步以提及 CLI 替代方案 - 添加 'Enable Billing via CLI' 小节，附 PATCH 示例，展示自动创建 free_user/free_org 默认计划 - 从 Notes 中移除过时的 'Enable Billing toggle is Dashboard-only' 注意事项 - 说明顶层 features 操作和 plan-feature 附加可通过 PLAPI billing config handler 完全支持

feat(billing)：添加 agent-first CLI 侧边栏以实现程序化 billing 配置 - 新增 'Agent-first: Programmatic billing config' 章节，展示 clerk config pull/patch 流程 + 原始 clerk api PATCH 以实现完全控制 - 更新 STOP 提示框以澄清一旦启用 billing，CLI 即可编辑 plans/features（主开关仍仅限 Dashboard） - 说明订阅生命周期仍通过 PricingTable + webhooks 流转 - 引用 AIE-823 以说明未来友好包装器的替换 Closes AIE-930

fix(billing)：处理评审反馈——features 优先、UserProfile、org: slug - 用 （B2C）替换自定义 AccountBillingPage，用 （B2B）替换 OrgBillingPage；内置组件负责计划切换、取消、支付方式 - 对 org 计划检查使用 'org:' slug 前缀（has({ plan: 'org:team' })），以在代码中与用户计划区分 - 在 Tiered Feature Gating 示例中优先使用 has({ feature }) 而非 has({ plan })；features 可在计划间移动而无需代码部署 - 移除 PricingTable Server Component 声明（它是客户端侧的） - 从核心技能路由中移除 'metered usage'（未发布） - 移除 Free Plan Fallback 章节（概念不正确） - 从非 setup 上下文中剥离 Stripe 泄漏；保留 setup 提及和事件名映射表 - 在核心路由和 B2B 章节标题中将 Per-Seat 改为 Seat-based 命名 - 去重 SKILL.md 和 b2b-patterns.md 之间的 seat-limit 内容 - 移除令人困惑的 experimental-subpath/underscore 注释 - 移除关于 /billing/features 404 的反提示 - 全文删除破折号

fix(billing)：重构 Membership-mode 错误特征行 旧行声称 " empty on B2C when Orgs are enabled | Membership required mode disables personal accounts"——但 如果 Membership required 开启，已登录用户会被路由到 choose-organization，根本不会进入 "user without active org" 状态，因此空渲染的表述是错误的。 Membership 模式对 billing 应用实际破坏的是 B2C + B2B 共存：个人计划订阅无法发生，因为 个人账户默认被禁用（自 2025-08-22 起）。该行已重写以具体描述该路径， 而非 PricingTable 渲染状态。

fix(billing)：添加 subscriptionItem.expired 事件，修正 webhook 环境变量 - 将 subscriptionItem.expired 添加到 SKILL.md 中的事件名表 以及 references/billing-webhooks.md 中的目录列表，以便处理器 可据此分支。 - 在技能引用它的 3 处（frontmatter 兼容性、Error Signatures 行、billing-webhooks.md Key Rules）将 CLERK_WEBHOOK_SECRET 重命名为 CLERK_WEBHOOK_SIGNING_SECRET。所有 SDK 包中 verifyWebhook 读取的规范环境 变量是 CLERK_WEBHOOK_SIGNING_SECRET；较短形式从未匹配， 并会在运行时产生 'Missing webhook signing secret'。

refactor(billing)：去重 SKILL.md，添加任务路由表 SKILL.md 有三个重叠的表覆盖相同错误（Error Signatures、Debugging has() Failures、Common Pitfalls），并重复了 已存在于 references/billing-webhooks.md 中的完整 70 行 webhook 处理器。主文件承担了维护负担 却未获得相应收益。 - 删除 'Debugging has() Failures' 章节——已被 Error Signatures 涵盖 - 删除 'Common Pitfalls' 表——已被 Error Signatures 涵盖 - 精简 'Checkout Flows'——移除已在 §1 中展示的重复 示例 - 将 §9 webhook 处理器从 4 个事件 + 中间件片段精简为 一个锚定事件；指向 references/billing-webhooks.md 获取 完整模板、TS 类型、中间件设置和状态表 - 添加 'What Do You Need?' 任务到参考的路由表，仿照 clerk-nextjs-patterns / clerk-orgs 惯例，使 agent 知道针对哪个关注点 该阅读哪个参考，而无需滚动到索引 SKILL.md：519 -> 450 行。无信息丢失；所有被删减的内容 在 Error Signatures 或 references/ 中都有规范归属。

fix(billing)：将 B2B 从 'per-seat pricing' 重构为 'seat-LIMIT plans' 该技能使用了 Stripe 风格的 'per-seat billing' 语言：'Clerk auto-increments seats per org member'、'Clerk manages per-seat pricing internally' 等。那不是 Clerk Billing 模型。 已对照 clerk_go 源码 + 公开文档验证： - 默认 B2B billing = seat-LIMIT plans：每个 org 计划有固定 价格和可选成员上限，在邀请/加入时强制执行 - 要向更大的 org 收取更多费用，按 seat cap 分层计划（starter 5 / team 10 / enterprise unlimited），而非按成员计量 - 'flag_per_seat_prices' 确实存在于 clerk_go 中，但受 flag 门控且 未 GA，因此超出本技能范围 这与 /docs/guides/billing/seat-limit-plans.mdx 一致。该 错误标签正是 Dylan 在 v1 评审中标记的表述——既然其余部分已清理干净， 现在值得精确表述。 更新： - Description、references 表、§6 关键模式、B2B vs B2C 表、See Also - b2b-patterns.md 概述 + 将 'Per-Seat Billing' 章节重命名为 'Seat-Limit Plans'，附准确的不变量和附加组件要求说明 - Plan Naming 表现在将列标记为 'Seat cap'；提及 Organization Plans 标签页 + Seat-based 开关 - Eval 3 expected_output + assertions 现在要求技能 纠正用户 'auto-incrementing seats' 的心智模型

fix(billing)：修正线格式对象字面量（commerce_* 而非 billing_*） billing-webhooks.md 中的载荷示例使用 'billing_subscription'、 'billing_payer'、'billing_subscription_item'、'billing_payment_attempt' 作为 `object` 字段值。真实线格式使用 'commerce_*' （已对照 @clerk/backend/src/api/resources/JSON.ts 和实时 GET /billing/plans 返回 "object":"commerce_plan" 验证）。 任何编写 `if (evt.data.object === 'billing_subscription')` 的 agent 都永远不会匹配真实 webhook 事件——静默失败。 添加 eval 4 断言以在未来捕获此幻觉。

fix(billing)：凸显 User Plans 与 Organization Plans 标签页区别 三种此前未覆盖的静默失败模式： - 错误标签页创建计划。Dashboard Billing → Plans 有两个标签页 （User Plans / Organization Plans），slug 按标签页限定， 且计划无法在标签页之间移动。在 Organization Plans 下创建 `pro` 并渲染默认 （for="user"）会产生 空表且无错误。Quick Start 第 2 步现在指出 标签页匹配；b2c-patterns.md 和 b2b-patterns.md 均照此处理。 - Membership required 模式静默破坏 B2C。如果启用 Organizations 而未设置 `Membership optional`，个人账户会被禁用， 且 会排除没有活跃 org 的用户——无控制台 警告。b2c-patterns.md 现在以此前置条件 + dashboard 快捷 URL 开头。 - Features 是按计划的，而非全局的。/billing/features 返回 404；features 位于每个计划的编辑页面内，且同一 slug 可附加 到多个计划。Quick Start 第 3 步澄清了这一点；eval 6 断言相应更新。 还添加了一个紧凑的 "Dashboard shortcuts" 表，因为每个设置 操作都需要访问 Dashboard，且快捷 URL 比点击路径说明更可靠。

fix(billing)：记录 billing-disabled 错误 + 修正 v7+ 版本说明 Agent 在编写 时未凸显 Dashboard 前置条件，导致用户卡在 'cannot_render_billing_disabled' 错误上且无法诊断。Clerk CLI 和 Backend API 目前无法切换 billing（clerk_go#18260 是后续将实现的功能）；Dashboard 是 唯一路径。 变更： - SKILL.md 顶部的 STOP 块指出仅限 Dashboard 的启用方式 并附精确深链接 - Quick Start 第 1 步引用用户若跳过将遇到的错误特征 - 新增 'Error Signatures' 章节，包含 cannot_render_billing_disabled 以及另外 5 个常见症状，映射到根因 + 修复 - 版本说明从 'v6+ (Core 3)' 更正为 'v7+ (Core 3)'—— v6 是 Core 2，那里的 billing 以 __unstable_* API 发布 - Eval 1 和 9 断言收紧：agent 必须凸显 Dashboard 链接 + 错误代码，且不得声称 CLI/BAPI 可启用 billing

fix(billing)：移除 Stripe Billing 幻觉，与文档对齐 Clerk Billing 是与 Stripe Billing 不同的产品——Plans 不会 同步到 Stripe Products，PricingTable 打开 Clerk 的应用内结账 抽屉（而非 Stripe Checkout），且 per-seat pricing 由 Clerk 内部 管理，每个 payer 每个 Plan 只有一个活跃 SubscriptionItem。 还修复： - 移除 subscriptionItem.created（不是真实事件；目录有 9 项） - useSubscription 导入：去掉 __experimental_ 前缀（子路径即是信号） - PricingTable props：完整列表，包括用于 B2B 的 for="organization" - 添加 CheckoutButton 章节（此前完全缺失） - 根据评审反馈从 SKILL.md 中删除 Beta 警告 - 凸显 Dev gateway，使技能不会错误地要求 Stripe 账户 - 重写 eval 断言以捕获错误心智模型，而非 将其编码（例如 evals 1、3、7、9、10、11）

fix(billing)：修正 webhook 载荷结构和 useSubscription API 代码示例解构了 billing webhook 载荷顶层 不存在的字段。已对照 @clerk/backend 中的 SDK 类型验证 （BillingSubscriptionWebhookEventJSON、 BillingSubscriptionItemWebhookEventJSON、BillingPayerJSON）。 Webhook 载荷修正（SKILL.md Pattern 9、billing-webhooks.md、 b2b-patterns.md）： - 订阅实体位于 evt.data.payer，带 user_id? 和 organization_id?（而非 evt.data.user_id / evt.data.org_id） - 订阅 id 是 evt.data.id（而非单独的 subscription_id 字段） - Plan slug 是嵌套的：订阅事件上为 evt.data.items[i].plan?.slug， subscriptionItem 事件上为 evt.data.plan?.slug - seats 不作为顶层字段存在；从 items.length 推导 seat 数量（每个 seat 一个订阅项） - subscriptionItem 事件仅携带该项；无 subscription_id 反向引用，因此按 payer 加 plan slug 匹配 - 载荷参考现在展示实际嵌套 schema，含 payer、 items[]、items[i].plan、payment_source_id 等 useSubscription hook 修正（SKILL.md Pattern 7、b2c-patterns.md）： - 从 @clerk/nextjs/experimental 导入为 __experimental_useSubscription （Billing 是 Beta，该 hook 尚未从 @clerk/nextjs 导出） - 返回类型使用 isLoading，而非 isLoaded - 续订日期是 subscription.nextPayment?.date（一个 Date 对象）， 而非 subscription.currentPeriodEnd（后者在 BillingSubscriptionResource 上不存在） 事件目录修正： - 将 subscriptionItem.created 重新加回 setup 列表（10 项， 而非 9 项）。根据 SDK 类型它存在。 - 移除不正确的 "no subscriptionItem.created event" 注释。 - 将 subscriptionItem.created 行添加到 Clerk vs Stripe 表。 还： - 移除 See Also 中重复的 clerk-setup 条目。

fix(billing)：修正 webhook 事件目录并向 updated 处理器添加 seats - 移除 subscriptionItem.created（根据文档不是真实 Clerk 事件） - 移除 subscription.canceled（取消以 subscriptionItem.canceled 触发） - 将 paymentAttempt.created / paymentAttempt.updated 添加到 setup 列表 - 添加解释性注释，澄清不存在 subscription.canceled 和 subscriptionItem.created 事件 - 将 SKILL.md 事件表中的 canceled 行重新标记为 'Subscription item canceled' 以匹配实际事件语义 - 从 subscription.updated 解构 seats，使 B2B per-seat 变更 传播到数据库 已对照 clerk.com/docs/nextjs/guides/development/webhooks/billing 验证。

fix(billing)：使用 has() 和 useSubscription() 而非 sessionClaims SKILL.md Pattern 7 和 b2c-patterns.md 此前教导 agent 直接读取 sessionClaims.metadata.plan，根据 Clerk 文档这不是受支持的路径。 授权应通过 has({ plan })，仅显示详情通过 useSubscription()。 - 用 has({ plan }) + useSubscription() 替换 sessionClaims 查找 - 更新 eval 5 以断言新模式并明确拒绝 sessionClaims.metadata.plan - 解决技能教授 sessionClaims 但 evals 2 和 6 对其扣分的矛盾

test(billing)：收紧 evals 1、4、6 的断言 用针对 Clerk 特定知识的区分性断言替换 以正确性为重点的断言： - eval 1（pricing）：检查 Beta 警告、SDK 版本固定、 显式 Stripe 连接前置条件、Plans 必须存在的前置条件， 以及对 @clerk/billing 导入和直接 Stripe API 调用的否定断言。 - eval 4（webhooks）：验证 agent 使用来自 @clerk/nextjs/webhooks 的 verifyWebhook（而非原始 svix），使用 camelCase 事件名 如 subscriptionItem.pastDue（而非 past_due），通过 createRouteMatcher 将 webhook 路由标记为公开，并使用异步中间件 回调。 - eval 6（feature gating）：验证决策规则解释 （feature vs plan）、Dashboard → Features slug 匹配警告， 以及 billing-gates-permissions 陷阱。 本地 eval 运行中测得的差异（3 个 evals，各单次运行）： 使用技能 100% 通过率 vs 不使用 68%——+32pp 区分度， 高于此前基于正确性断言的 +17pp。

test(billing)：将 evals 迁移到 agentskills.io 断言格式 - 根据 https://agentskills.io 规范将 `expectations` 重命名为 `assertions` - 添加 `files: []` 字段以与新格式保持一致 - 保留 `scaffold` 作为 eval 运行器用于选择 起始模板的自定义扩展（来自 clerk-nextjs-patterns 的 nextjs-basic-auth） - 收紧单个断言，使其更具体且可验证： 精确导入路径、精确方法调用、具体事件名 12 个 evals，共 64 个断言。已准备好用于新的 skill-creator eval 框架，该框架期望基于断言的格式。

feat(billing)：添加 clerk-billing 技能 涵盖 Clerk Billing 功能集： - `` 组件用法 - `has({ plan })` 和 `has({ feature })` 门控（服务端 + 客户端） - 带组织的 B2B per-seat billing - Billing webhook 事件处理（订阅生命周期） - 升级/降级流程和调试 `has()` 失败 - 全程使用 Core 3 语法（异步中间件、auth.protect） 结构： - SKILL.md 含 10 个关键模式和常见陷阱表 - references/ 含 b2c、b2b、components、webhooks 的深入探讨 - evals/ 含 12 个 evals，覆盖推荐 + 实现测试 解决了测得的差距：无专用技能时 billing 被推荐的比例为 6.3%， 而有专用技能时为 89.6%。