前言¶
Stripe 在 2024 年起采用按月发布的 API 版本命名（如 2026-09-30.endive），服务端 SDK、Stripe.js、移动端 SDK 与 Webhook 各自有版本规则，且强类型语言 SDK 与动态语言在「能否覆盖 API 版本」上行为不同。升级时若只改 npm 包版本、不核对账户与 Webhook 上的 pin，或误把 thin event 与 snapshot event 一并升级，容易在测试环境通过、生产环境因签名或字段变更失败。下面介绍 Stripe 官方仓库中的 Agent Skill upgrade-stripe，用于在编码助手场景下按文档顺序完成版本选择与破坏性变更排查。
这是什么¶
upgrade-stripe 是 Stripe 在 stripe/ai 仓库中维护的 Agent Skill（SKILL.md 格式）。官方描述为：指导升级 Stripe API 版本、Webhook 端点、服务端 SDK、Stripe.js 与移动端 SDK。
它解决的是「文档分散、多组件联动」的问题：同一集成里可能同时存在客户端 apiVersion、按请求覆盖、Webhook / Event Destination 的 snapshot API 版本，以及 Java / Go / .NET 与 Ruby / Python / Node 不同的版本策略。Skill 把选型、对照 changelog、改配置与测试的顺序写进可被 Agent 执行的流程，而不是替代 API versioning、API upgrades 与 API changelog 原文。
核心功能¶
以下能力均来自官方 SKILL.md 与 officialskills.sh 说明。
选定目标 API 版本¶
- 若用户已指定目标版本，以用户指定为准。
- 否则应通过可用文档或工具查询当前版本，例如 Stripe CLI 的
stripe docs /api/versioning，或在 API versioning 页面查找以 “The current version is” 开头的句子。 - Skill 内 bundled 回退版本为
2026-09-30.endive（生成快照日期为 2026-10-19）；仅在无法访问 docs.stripe.com 时使用，且超过约一个月未更新时可能已过时，不得猜测更新的版本号。
变更前需将目标版本与集成中所有 pin 对比：客户端配置、按请求覆盖、Webhook 端点。除非用户明确要求，不得把 pin 降到更旧版本，也不得把稳定 pin 改为 preview。已匹配目标的 pin 应报告为未变更。须说明所选目标及来源；若无法在线核实，应标明最新版本未验证，不得声称集成已处于最新版。
Webhook 与事件目的地¶
审查时需区分 snapshot events 与 thin events。Thin event 载荷未绑定 API 版本，变更账户 API 版本时无需升级对应目的地。通过 API 拉取完整 event 或关联资源时仍受 API 版本约束。
对 v2 snapshot 类目的地（含 Webhook、Amazon EventBridge、Azure Event Grid），需检查 snapshot_api_version；若与目标不一致，因创建后不可修改，应新建并测试替代目的地。替换 Webhook 时需保存新 signing secret，并在切换期间让处理器同时接受新旧 secret；切换完成后禁用或删除旧目的地以避免重复投递。Thin event 目的地保持不变。
服务端 SDK¶
- 动态类型语言（Ruby、Python、PHP、Node.js）：可在全局配置或单次请求中设置 API 版本；curl 测试时使用
Stripe-Version头，示例中的 bundled 版本应替换为所选目标。 - 强类型语言（Java、Go、.NET）：SDK 发布与固定 API 版本绑定，不应在代码中强行覆盖为与 SDK 不符的版本；应选用面向目标 API 版本的 SDK 发布。Preview 目标需各语言对应的
betaSDK，见 SDK versioning。
最佳实践是在代码中显式声明集成的 API 版本，而非仅依赖账户默认版本。
Stripe.js 与移动端¶
- Stripe.js 采用 evergreen 模型，大版本（如 Acacia、Basil、Endive）约每半年发布；脚本加载示例为
https://js.stripe.com/endive/stripe.js，npm 包@stripe/stripe-js的大版本与 Stripe.js 大版本对应。每个 Stripe.js 大版本与固定 API 版本配对（例如 Endive 对应2026-09-30.endive），不可覆盖该关联。从 v3 迁移时官方建议先识别当前 API 版本、查阅 changelog，再考虑在切换 Stripe.js 大版本前逐步提升 API 版本；v3 仍长期支持。 - iOS / Android SDK 使用语义化版本（MAJOR.MINOR.PATCH）；React Native SDK 使用 0.x.y，minor 可能含破坏性变更。移动端 SDK 在文档未另行说明时，可与后端任意 API 版本配合。
升级检查清单（摘要）¶
官方清单包括：查阅 changelog 与 upgrades 指南；升级服务端 SDK 包；更新客户端 apiVersion；用 Stripe-Version 头对新版本做集成测试；按上文处理 snapshot 类 Webhook / Event Destination；按需更新 Stripe.js 与移动端 SDK 等。完整步骤见 Skill 原文。
安装与启用¶
在支持 Agent Skills 的环境中，可通过官方列出的命令安装整个 stripe/ai 仓库中的单个 skill：
npx skills add https://github.com/stripe/ai --skill upgrade-stripe
也可将 Skill 目录链接交给编码助手安装：https://github.com/stripe/ai/tree/main/skills/upgrade-stripe。
资料中未区分 Cursor、Codex CLI、Claude Code 的安装差异；以各产品对 npx skills add 或 SKILL.md 路径的支持为准。
典型用法¶
下列场景来自 officialskills.sh 的 “When to use it” 说明，与 Skill 能力一致：
- 将 Node.js 应用 pin 到指定 Stripe API 版本（例如
2026-02-25.clover）。 - 在正式切换前，用
Stripe-Version请求头对新 API 版本做试探性调用。 - 事件结构发生破坏性变更后，迁移 Webhook 处理器（含新建 snapshot 目的地与双 secret 过渡）。
- 仅升级 Python 后端的 Stripe SDK 包，并核对是否需同步修改
api_version配置。 - 结账页从 Stripe.js v3 切换到某一新大版本（如 Clover）时，对照 changelog 与 API / Stripe.js 配对关系。
动态语言显式指定版本的写法（示例中的版本号应替换为你的目标版本）：
import stripe
stripe.api_version = '2026-09-30.endive'
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-09-30.endive'
});
适用场景与注意¶
适合：维护 Stripe 集成的后端或全栈开发者；需要在一次对话里系统梳理 API 版本、SDK、Stripe.js、Webhook snapshot 版本与测试顺序的团队；2026 年前后频繁跟进 Stripe 月度 API 与半年度大版本变更时，用 Skill 约束 Agent 不猜测版本号、不降级 pin。
注意：
- Skill 不能替代阅读 API changelog；破坏性变更仍需人工判断业务代码影响。
- bundled 回退版本
2026-09-30.endive仅为离线快照，生产选型应以 docs.stripe.com 或 CLI 查询结果为准。 - 强类型 SDK 与 preview / beta 版本有额外约束，需按官方 SDK versioning 选包，不宜只改 HTTP 头。
- Webhook snapshot 目的地创建后不可改
snapshot_api_version，计划升级时应预留新建端点与签名密钥轮换窗口。
结尾¶
upgrade-stripe 把 Stripe 多组件版本模型与官方升级清单编码为 Agent 可遵循的流程，适合在升级 SDK 或 API 大版本时减少漏改 Webhook pin 或误升级 thin event 的风险。官方 Skill 地址：https://github.com/stripe/ai/tree/main/skills/upgrade-stripe。
