一、基本信息
| 项目 | 内容 |
|---|---|
| 名称 | upgrade-stripe（Stripe API/SDK 版本升级指南 Skill） |
| 作者/维护者 | Stripe, Inc.（官方仓库 stripe/ai） |
| 来源链接 | https://github.com/stripe/ai/tree/main/skills/upgrade-stripe |
| 许可证 | MIT（GitHub API 确认，仓库根目录 LICENSE 文件核实） |
| GitHub Stars | 1,729（GitHub API 确认；为 stripe/ai 合集仓库整体数字，不代表本 Skill 单项热度，详见第六章说明） |
| Forks | 322（同为合集仓库整体数字） |
| 最新版本 | 无独立版本号；随仓库自动化“sync skills”流程从 docs.stripe.com/.well-known/skills 持续同步，本技能目录最近一次实质提交为 2026-07-30 |
| 安装方式 | Claude Code / Codex 官方插件市场一键安装，或通用 npx skills add 命令，详见第十章 |
项目自述名称：仓库标题为「Stripe AI」（含 SDK、MCP Server 与多个 Agent Skills），本文聚焦其中的
upgrade-stripe技能。
二、功能介绍与亮点
upgrade-stripe 是一份系统梳理 Stripe API、各语言 SDK、Stripe.js 与移动端 SDK 版本升级路径的指导手册：
- 区分变更类型：明确列出哪些改动向后兼容（新资源、新可选参数、响应新增字段等）、哪些是需要改代码的破坏性变更（字段改名/移除、行为变化、接口下线），并指向官方 Changelog
- 覆盖全语言 SDK 版本策略：动态类型语言（Python/Ruby/PHP/Node.js）如何用全局配置或按请求覆盖 API 版本；强类型语言（Java/Go/.NET）为何必须靠升级 SDK 本身来切版本，而不能单独指定
- 讲清 Stripe.js 的双年发布节奏：Acacia/Basil/Clover/Dahlia 各主版本与对应 API 版本自动配对、不可拆开使用，并给出脚本标签与 npm 两种加载方式
- 移动端 SDK 版本规则：iOS/Android 语义化版本含义、React Native 的 0.x.y 特殊模式（次版本号即可能含破坏性变更）
- 可执行的九步升级清单：从查 Changelog、升级 SDK 包、改
apiVersion参数，到用Stripe-Version请求头灰度测试、更新 webhook 处理逻辑，全流程可照做 - 测试先行的最佳实践：强调始终在代码中显式声明 API 版本而非依赖账户默认版本，并演示如何用
Stripe-Version头在不改账户默认设置的前提下测试新版本
亮点：内容随 Stripe 官方文档自动同步（sync-skills 工作流），最近一次同步在 2026-07-30；单文件 SKILL.md（约 5.6KB）覆盖服务端/前端/移动端全平台版本管理心智模型，是同仓库中少见的“横跨全技术栈”型参考指南。
三、适用场景
所属分类：集成与工作流自动化
- 已在生产环境接入 Stripe API 或某个语言 SDK、需要定期升级到新版本的开发团队
- 维护 Stripe 集成代码的 AI agent，在用户提出“升级一下 Stripe”或遇到 Stripe API 弃用警告时需要一份可靠的操作依据
- 计划切换 Stripe.js 大版本（如从 Basil 升级到 Dahlia）、需要同时协调前端脚本版本与后端 API 版本的团队
- 维护跨平台产品（服务端 + Web + iOS/Android）、需要理解各端版本策略差异以避免升级踩坑的团队
四、跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | 官方 README：claude plugin install stripe@claude-plugins-official，安装即接入官方插件市场 |
| Codex | ✅ 原生支持 | 官方 README：codex plugin add stripe@openai-curated，属 OpenAI 官方精选插件目录 |
| OpenClaw | ❓ 未验证 | 公开材料未提及；技能遵循标准 SKILL.md 格式，理论上可安装，但未见官方或第三方验证 |
| Hermes Agent | ❓ 未验证 | 公开材料未提及针对本技能的适配 |
五、推荐理由
Stripe 的 API 版本以日期命名、多年持续演进，服务端 SDK、Stripe.js、移动端 SDK 三条版本线各有各的规则——混用或漏看破坏性变更是接入 Stripe 的团队常见的运维事故来源。upgrade-stripe 把这套版本策略整理成一份紧凑、可执行的指南，且随官方文档自动同步、不会过时。对已接入 Stripe 的初中级开发者和负责维护该集成的 AI agent 来说，遇到升级需求时不必自己去啃分散在多篇官方文档里的版本规则，直接照着九步清单走即可，也能提前识别哪些改动是“免费”的、哪些需要真正改代码。
六、评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Stripe 官方出品；仓库整体 1,729 stars，该数字属整个 stripe/ai 合集仓库，不代表本 Skill 自身热度，子技能本身暂无独立于合集的第三方热度证据 |
| 可用性 | 9 | 单文件复制即用，无需额外配置或 API Key；文档含 Python/Ruby/JavaScript/curl 多语言代码示例与九步升级清单；本技能目录 2026-07-30 仍有实质提交，随官方文档持续同步 |
| 安全性 | 9 | 见下方检查清单 |
| 综合 | 8.3 | 三项均值 |
安全检查清单：
① 不执行任何 shell 命令——正文中出现的 npm update stripe、pip install --upgrade stripe 等命令是给用户/开发者参考的操作建议，技能本身不会自动运行
② 无联网外发行为，仅以文本形式引用 Stripe 官方文档链接（docs.stripe.com），不主动发起网络请求
③ 不要求任何 API Key 或凭据；代码示例中的 sk_test_xxx 均为占位符
④ 抓取的 SKILL.md 全文未发现可疑指令或 prompt injection 迹象
⑤ 作者为 Stripe 官方，信誉极高
⑥ License 明确（MIT）
⑦ 仓库整体近日仍有推送，本技能目录最近一次实质提交为 2026-07-30，无弃置风险
七、跟同类 Skills 相比的优势
| 技能 | 定位 | 与 upgrade-stripe 的差异 |
|---|---|---|
upgrade-stripe（本推荐） |
Stripe 官方出品的 API/SDK 版本升级指南，覆盖服务端、Stripe.js、移动端全平台 | 内容随官方文档自动同步，版本号与破坏性变更信息保持最新 |
hookdeck/webhook-skills（Hookdeck 团队，独立第三方） |
面向 200+ 服务商（含 Stripe）的 webhook 接收、签名校验、事件解析指导，提供 Express/Next.js/FastAPI 可运行示例 | 聚焦“接收端”实现细节（如何验证签名、解析事件），不涉及 API/SDK 版本迁移决策，与 upgrade-stripe 是互补关系而非竞争 |
qdrant-version-upgrade（Qdrant 官方，同一“版本升级指南”技能形态） |
引导 Qdrant 向量数据库自身版本升级 | 面向自托管基础设施的版本升级，而 upgrade-stripe 面向托管型第三方 API 的客户端集成版本适配，两者问题域不同但技能形态相近 |
upgrade-stripe 的差异化在于：它是这类“厂商版本升级指南”里少数由厂商自己维护、并接入自动化同步流程的一份，不依赖社区二次转载或个人仓库镜像去追更版本号。
八、用户评价
该技能目前在第三方平台尚无具名社区评价，但查到一篇独立的行为评测案例研究：研究者围绕 upgrade-stripe 做了正式的行为评估（发布于 dacharycarey.com，2026-02-27，作者自述该评测是其 Agent Skill 研究报告的一部分），发现模型在缺少精确 API 参考的情况下，容易编造出看似合理但实际不存在的方法名与常量（如虚构 params.SetStripeVersion()），且该问题在贴近真实场景的测试条件下比纯技能测试条件下更明显；研究同时验证了一份约 2000 token 的精简参考文件可以基本消除这一问题，而堆砌更详尽的参考文档反而会因跨 SDK 模式串扰而让效果变差。
九、其他补充
同仓库 stripe/ai 下还包含 connect-recommend（Connect 账户与分账配置推荐）、stripe-best-practices（全品类集成通用规范）、stripe-apps（Dashboard 扩展开发脚手架）、stripe-directory（第三方服务/供应商检索）、stripe-docs（文档检索）、stripe-projects（第三方基础设施与凭据置备）等姊妹技能，以及面向 LLM 框架的 @stripe/ai-sdk、@stripe/token-meter 两个 SDK 和一个官方托管 MCP Server（https://mcp.stripe.com），共同构成 Stripe 官方的 AI 集成工具体系。
十、安装使用方式
- Claude Code：
claude plugin install stripe@claude-plugins-official - Codex：
codex plugin add stripe@openai-curated - 通用手动安装：
npx skills add https://docs.stripe.com（注意：手动安装不会自动更新，需定期运行npx skills update -y），或直接将SKILL.md复制进 agent 的 skills 目录 - 触发方式：安装后无需重启，在对话中提到“升级 Stripe API 版本”“Stripe SDK 该怎么升级”“Stripe.js 要不要跟新版”等诉求时，Agent 会自动加载该技能
十一、注意事项
- 独立评测显示，在缺乏精确 API 方法签名参考的情况下，模型可能编造看似合理但实际不存在的 API 调用；生成的升级代码建议在合并前对照官方 SDK 文档或类型定义做一次核对，尤其是强类型语言（Java/Go/.NET）的具体方法名
- OpenClaw、Hermes Agent 的兼容性未获验证，如在这两个平台使用建议先做小范围测试
- 技能本身不含针对具体项目代码库的静态扫描能力，识别“哪些地方用了即将废弃的字段”仍需人工或搭配其他工具排查
- 该技能是 Stripe AI 工具体系的一部分，仓库整体 1,729 stars 反映的是整个
stripe/ai仓库热度而非本 Skill 单项，实际效果请以自身场景验证为准