prisma-next-extension-upgrade

升级 Prisma Next（扩展）

此技能用于升级本身就是 Prisma Next 扩展的项目 — 这类包会使用框架 SPI（@prisma-next/contract、@prisma-next/framework-components、@prisma-next/migration-tools 等），并公开契约 / 中间件 / 编解码器 / 迁移接口，供下游应用通过 prisma-next.config.ts 安装。

如果要升级的项目是使用方应用（它在应用代码中导入 @prisma-next/postgres 或 @prisma-next/mongo），请改用 prisma-next-upgrade 技能 — 如果代码仓库同时包含使用方应用和扩展包，也可以两者都用；此时请先运行用户流程，再在同一会话中运行扩展流程。

步骤 0 — 确保技能已更新

在执行其他操作之前，请确保此技能已安装为 @latest 并重新加载。针对旧版升级说明的错误修复会随最新技能版本一并发布，并纳入累积指令集；使用过时的技能可能会应用已知有问题的转换。

具体来说：如果 Agent 运行时支持在会话中刷新，请立即执行。否则，请退出并让用户重新安装：

pnpm dlx skills add prisma/prisma-next/skills/extension-author --all

扩展作者技能的子路径有意不固定版本（始终为 main）— 累积指令集是唯一可信来源，最新版本中的修复适用于所有先前的转换。

然后重新调用此技能，再继续操作。

角色检测

当项目本身就是 Prisma Next 扩展时，适用此技能。判断依据：

• package.json 在 dependencies 或 peerDependencies 中声明了 @prisma-next/contract（或其他 SPI 包），并且
• 包的 name 符合 ^@.*/extension-（这是 @prisma-next/extension-pgvector 等包采用的仓库内约定），或者
• 同一单体仓库中某个相邻应用的 prisma-next.config.ts 将此包列为 extensions 条目。

如果项目还在自身的应用代码中使用 Prisma Next，请安装 prisma-next-upgrade 技能（pnpm dlx skills add prisma/prisma-next/skills/upgrade --all），然后先运行用户流程，再在同一会话中运行此流程。

如果无法明确判断，请询问用户要按哪种角色操作。

版本检测

• 起始版本。 从 pnpm-lock.yaml（或 package-lock.json / yarn.lock）读取当前安装的 Prisma Next 版本，检查任一 @prisma-next/* 条目的解析版本。如果锁文件中存在多个次版本不同的 @prisma-next/* 包，则以最低的次版本作为起始版本。
• 目标版本。 用户指定的版本，或通过 npm view @prisma-next/contract dist-tags.latest 获取的最新稳定版。

继续之前，请向用户报告这两个版本。

转换链

如果起始版本与目标版本之间跨越多个次版本（例如 0.6 → 0.8），请构建由多个单次版本升级组成的链：

0.6 → 0.7 → 0.8

按顺序完整应用每个步骤：升级版本、安装、执行说明、检查固定版本、验证、提交 — 完成当前步骤后再进入下一步。任一步骤失败，都要停止后续升级。

每一步的流程

此流程假设你是外部扩展作者——你的扩展位于独立仓库中，并从 npm 使用 @prisma-next/*。（prisma/prisma-next 单体仓库内的扩展通过 pnpm bump-minor / scripts/set-version.ts 升级版本，该脚本会将所有 workspace:<X.Y.Z> 规格统一改写为根版本；这些扩展不会运行此技能。）

对于链中的每个 (from, to) 步骤：

1. 升级 @prisma-next/* 依赖项。 将扩展 package.json 中的每个 @prisma-next/* 条目改写为精确的 <to> 版本（例如 "0.8.0"——不带 caret、波浪号、范围或 workspace: 规格；下文的精确固定规则会说明原因）。所有条目都应升级到相同版本。涵盖扩展当前使用的依赖字段——dependencies 和／或 peerDependencies——以及任何 optionalDependencies。扩展升级技能本身通过 pnpm dlx skills add 发布（参见步骤 0）；无需升级 @prisma-next/extension-upgrade-skill npm 条目。配套 CLI 工具是 @prisma-next/extension-author-tools——保持其固定版本与扩展 CI 当前使用的版本一致；升级它与框架升级相互独立，通常无需更改。

2. 安装。 运行 pnpm install（或项目用于管理 lockfile 的命令）。此时扩展源代码与新的 SPI 不兼容——<from> → <to> 的升级说明用于修复此问题。

3. 检查版本固定。 运行 pnpm exec prisma-next-check-pins（由 @prisma-next/extension-author-tools 提供）。此健全性检查会断言 dependencies、peerDependencies 和 optionalDependencies 中的每个 @prisma-next/* 条目都是单个精确版本字符串，并且所有条目使用相同版本。如果检查失败，说明升级步骤未改写所有规格——修复有问题的条目，然后重新运行检查，再继续操作。

4. 阅读升级说明。 从此技能包中加载 upgrades/<from>-to-<to>/instructions.md。解析 YAML frontmatter，并特别留意其中的 changes[] 数组。

5. 应用每项更改。 对于 changes[] 中的每个条目：

   • 如果条目包含 detection 块（glob + 内容谓词），则运行该检测。如果没有文件匹配，则跳过此更改。
   • 如果条目不包含 detection，则无条件应用此更改。
   • 如果条目指定了 script:（相对于 instructions.md 的路径），则从项目根目录调用：
     • *.ts → pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
     • *.sh → bash <skill>/upgrades/<from>-to-<to>/<script>
     • codemod → 按照脚本自身的 instructions.md 说明调用。
   • 如果条目没有 script，则直接按照 instructions.md 正文中的说明操作。

   如果 changes[] 为空（适用于没有扩展端破坏性更改的版本转换的占位结构），此子步骤无需操作——继续验证。

6. 验证。 运行 pnpm build && pnpm test（或项目中的等效命令——扩展 package.json 的 scripts 字段用于查找这些命令）。如果有任何检查失败，则停止升级链。不要自动回滚；向用户报告失败，并提供 frontmatter 中失败更改的 id、该更改操作过的文件路径，以及推断出的修复方法。

7. 提交。 创建一个提交，包含此步骤的更改：package.json 的版本升级、pnpm install 造成的 lockfile 变更，以及应用更改后产生的任何源文件改写。使用以下提交信息：

   chore: upgrade @prisma-next/* to <to-version>
   

   （如果扩展有自己的提交信息约定，则遵循该约定。）每一步单独提交——绝不合并多个步骤的提交。

继续下一步。重复上述流程。

精确固定规则

Prisma Next 扩展会将每个 @prisma-next/* 依赖固定为同一个精确版本（发布的 package.json 中不使用 ^、~、版本范围、通配符或 workspace: 说明符）。所有 @prisma-next/* 条目使用相同版本。只有针对新次要版本的升级成功运行后，才会更新固定版本。

prisma-next-check-pins（由 @prisma-next/extension-author-tools 提供 — 使用 pnpm add -D @prisma-next/extension-author-tools 安装）会强制执行此规则。在本地运行：

pnpm exec prisma-next-check-pins

将其与构建/测试步骤一起接入扩展的 CI，这样意外使用版本范围固定依赖时，PR 就会在合并前失败。

链条完成时

向用户报告：已应用的步骤数量、你创建的提交 SHA，以及任何尚待处理的后续事项。

失败情况

步骤失败时：

• 提供结构化错误，其中包含代码 PN-UPGRADE-NNNN、失败变更的 id、该变更涉及的文件路径（或锁文件、固定版本检查或验证命令），以及推断出的解决方法。
• 不要自动重试。
• 不要自动回滚提交。用户可以按需自行回退，以恢复干净状态。