Stripe 集成最佳实践
为支付、订阅、平台业务、税务和安全集成选择合适的 Stripe API 与实现方式。
文件明确建议受限 API key、最小权限、密钥保管、轮换、Webhook 签名验证、OAuth state、2FA 和税务操作前确认，并避免自动创建或过期税务注册，显示出较强的安全与外部影响意识。扣 6 分：Stripe CLI 生成测试密钥的说明缺少权限边界与风险提示；未系统说明个人数据流、回滚方案和所有外部副作用；Connect 安全建议之间存在冲突。
集成路由、关键规则和失败陷阱写得较具体，且引用了配套 reference 文件。扣 13 分：Connect 部分同时要求 Accounts v2，又称 Standard 是更安全默认且不应推荐 Express/Custom，和前文 v2 dashboard 配置建议冲突；未提供针对该技能关键路径的专门测试、输入校验或可诊断失败反馈。静态评估按上限不超过 10 分。
描述覆盖支付、订阅、税务、Connect、Treasury 和安全等明确场景，路由表也有助于语义触发。扣 6 分：范围非常宽，缺少明确的非适用场景、输入输出约定和触发排除条件；未说明中文交互支持，也未讨论中国大陆网络访问 docs.stripe.com、npm 或 Stripe CLI 的可达性。
技能具有 front matter、分域 reference 文件、目录、安装说明、MIT 许可证和仓库级同步维护信号，结构清晰。扣 7 分：技能自身没有版本号、变更记录、明确维护责任人或稳定更新路径；部分安装和维护信息只在 README 中，故障排查、FAQ 和已知限制仍不完整。
规则可直接指导 API 选择、动态支付方式、税务前置条件、Connect 责任配置和密钥安全，核心任务大致可完成。扣 9 分：没有针对典型用户请求的完整可复制输出或端到端示例，若缺少外部文档访问仍需较多人工核验；Connect 的矛盾建议可能导致错误实现。静态评估按上限不超过 7 分。
文件包含大量指向 Stripe 官方文档的主张，并有仓库 CI 与技能同步工作流，具备一定审计线索。扣 6 分：CI 主要覆盖工具包而非该技能关键建议，没有提交的技能测试或第三方执行证据；无法从静态文件独立验证 API 版本、Metronome、Accounts v2 等时效性主张。静态评估按上限不超过 5 分。
- 修复 Connect 安全章节中 Accounts v2、Standard、Express 和 Custom 之间的冲突，并明确不同 API 版本下的适用配置。
- 对最新 API 版本、Metronome 和 Accounts v2 等时效性主张增加版本来源、更新时间和变更记录。
- 补充不适用场景、失败处理、端到端示例，以及中国大陆网络不可达时的替代路径。
- 使用 Stripe CLI 生成密钥前，应明确仅限 sandbox、权限范围和密钥生命周期。
这个 Skill 能做什么，适合哪些场景？
该技能用于构建、修改或审查各种 Stripe 集成。它覆盖一次性付款、Checkout、Payment Element、Setup Intents、订阅、Connect 平台、Stripe Tax、Treasury 财务账户以及密钥和 Webhook 安全。技能会根据业务场景推荐 API，并要求先阅读对应的参考文件。它还规定使用最新 Stripe API 版本，并优先推荐受限 API 密钥。
根据集成目标在 Checkout Sessions、PaymentIntents、Setup Intents、Accounts v2、Billing APIs、Metronome、Stripe Tax、Registrations API 和 v2 Financial Accounts 之间进行路由；提示读取 payments、connect、billing、tax、treasury 或 security 参考文件；检查启用自动税务前是否存在有效注册；指导动态支付方式、Checkout 会话标识、API 密钥、Webhook、OAuth、2FA 和 Connect 责任相关实现；可通过 npm 安装 Stripe CLI，并运行 stripe sandbox create 生成测试 API 密钥。
- 开发一次性支付流程的工程师，需要在 Checkout Sessions 与自定义支付界面之间选择合适的方案。
- 搭建市场平台的团队，需要配置 Connect Accounts v2 和控制器属性。
- 实现订阅或按用量计费的产品团队，需要选择 Billing APIs、Checkout Sessions 或 Metronome。
- 在多个国家或地区收取销售税、VAT 或 GST 的团队，需要核对 Stripe Tax、Registrations API 和有效税务注册。
- 审查生产环境 Stripe 集成的工程师，需要改进受限密钥、Webhook、OAuth、2FA 和 API 密钥管理。
- 迁移旧版或已弃用 Stripe API 的团队，需要依据最新 API 版本调整实现。
这个 Skill 有哪些优点和局限？
- 覆盖支付、订阅、Connect、税务、Treasury 和安全等常见 Stripe 集成领域。
- 提供明确的 API 路由表和关键实现规则。
- 强调税务注册、动态支付方式和受限 API 密钥等容易出错的事项。
- 基于 MIT 许可发布。
- SKILL.md 引用了多个未随用户提供的 references 文件，无法仅凭当前材料核验其全部细节。
- 没有提供测试套件、示例项目或平台兼容性测试证据。
- 技能主要提供决策和审查指导，不是独立的 Stripe SDK 或完整支付实现。
- 部分操作依赖 Stripe 文档、Stripe CLI 和网络访问。
如何安装这个 Skill？
在项目中运行 npx skills add https://docs.stripe.com 进行手动安装。手动安装的技能不会自动更新，可运行 npx skills update -y 获取最新版本。README 未说明如何只安装 monorepo 中的这一项技能。
如何使用这个 Skill？
将该技能放入 Agent Skills 兼容客户端可加载的技能目录，然后提出具体任务，例如：“审查我的 Stripe 订阅集成，检查 Checkout Sessions、automatic_tax、Webhook 和受限 API 密钥的使用。”回答集成问题或编写代码前，应先阅读对应的参考文件。最新 Stripe API 版本为 2026-06-24.dahlia；除非用户另有指定，应使用最新 API 版本和 SDK。
这个 Skill 与同类方案有什么区别？
技能明确区分 Checkout Sessions 与 PaymentIntents：一次性付款推荐 Checkout Sessions；自定义嵌入式支付界面推荐 Checkout Sessions 搭配 Payment Element；保存支付方式则推荐 Setup Intents。它还要求除 Terminal 外不要传入 payment_method_types，以启用动态支付方式。