prisma-next-upgrade

升级 Prisma Next（用户应用）

此技能用于升级通过公开软件包 API（@prisma-next/postgres、@prisma-next/mongo、prisma/ 中的契约文件等）使用 Prisma Next 的项目。如果项目本身是 Prisma Next 扩展，请改用 prisma-next-extension-upgrade 技能；如果仓库同时包含应用和扩展软件包，也可以同时使用这两种技能。

步骤 0 — 确保技能为最新版本

在开始任何操作之前，请确保此技能已安装为 @latest，并重新加载。针对旧版本迁移的升级说明的错误修复，会作为累积内容随最新技能版本发布；使用过时的技能可能会应用已知有问题的迁移。

如果 Agent 运行时支持在会话中刷新，请立即执行。否则，请退出并让用户重新安装（pnpm dlx skills add prisma/prisma-next/skills/upgrade --all），然后重新调用。升级技能的子路径有意不固定版本（始终为 main）——累积指令集是唯一可信来源，而最新版本中的修复适用于所有先前的迁移。

升级前检查 — 扩展兼容性

在更改任何代码之前，如果升级目标版本高于任何已安装扩展固定的 Prisma Next 版本，则拒绝升级。Prisma Next 扩展会将每个 @prisma-next/* 依赖固定为单个精确版本（不使用插入符号，也不使用版本范围）；此固定版本是该扩展经过验证的最高版本。将用户应用升级到高于此固定版本的版本，会导致扩展的类型标识与应用的类型标识悄然不一致。

步骤：

1. 读取 prisma-next.config.ts（或项目根目录下可通过 TS 发现的等效文件），并列出其导入的扩展软件包。每个 extensions: [...] 条目都对应一个已安装的 npm 软件包。
2. 针对每个扩展，读取其位于 node_modules/<extension-package-name>/package.json 的已安装 package.json，查找 dependencies、peerDependencies 或 optionalDependencies 下的任何 @prisma-next/* 条目。按设计，这些条目都是精确版本固定值（例如 "0.7.0"），由扩展作者上次执行其自身升级时设定。
3. 计算所有扩展固定版本中的最低版本。 这是此应用在当前扩展组合下可升级到的最高 Prisma Next 版本。
4. 与用户指定的目标版本比较。 如果目标版本高于最低固定版本，则停止并以结构化消息列出每个版本落后的扩展及其固定版本，并提供两种方案：
   • (a) 等待版本落后的扩展发布兼容版本，然后重新运行。
   • (b) 使用 --to=<highest-reachable>（或用户用于设置目标版本的其他标志/选项）重新运行。

不要自动降低目标版本；不要跳过版本落后的扩展；不要升级到高于该版本的版本。如果用户明确要求忽略停止提示，请先清楚说明风险。

如果不存在 prisma-next.config.ts，或其中没有列出任何扩展，则跳过升级前检查。

角色检测

当项目使用 Prisma Next 时，此技能适用：

• package.json 在 dependencies / devDependencies 下声明了一个或多个 @prisma-next/* 软件包；并且
• 该软件包本身不是扩展（在 dependencies / peerDependencies 下没有 @prisma-next/contract（或其他 SPI）；名称不匹配 ^@.*/extension-；也未在同级应用的 prisma-next.config.ts 中引用）。

如果项目同时符合扩展作者角色，请安装 prisma-next-extension-upgrade 技能（pnpm dlx skills add prisma/prisma-next/skills/extension-author --all），并在同一会话中先运行此流程，再运行该技能。如果无法明确判断角色，请询问用户。

版本检测

• 起始版本。 通过检查任意 @prisma-next/* 包解析出的版本，从 pnpm-lock.yaml（或 package-lock.json / yarn.lock）中读取当前已安装的 Prisma Next 版本。如果锁文件显示多个 @prisma-next/* 包的次要版本号不同（这表示依赖已损坏），则以最低次要版本号作为起始版本。
• 目标版本。 用户指定的版本，或通过 npm view @prisma-next/postgres dist-tags.latest 查询到的最新稳定版本。

继续操作前，先向用户报告这两个版本。

升级链

如果起始版本与目标版本之间跨越多个次要版本（例如，0.6 → 0.8），则按每次升级一个次要版本构建升级链：

0.6 → 0.7 → 0.8

按顺序完整执行每一步：升级、安装、执行说明、验证、提交，然后再进入下一步。第一步失败时立即停止升级链；不得跳过失败步骤继续升级。

升级链的顺序不取决于安装了哪些扩展；预检已确认目标版本可达。

每步流程

对于升级链中的每个 (起始版本, 目标版本) 步骤：

1. 升级 @prisma-next/* 依赖。 将项目 package.json 中每个 @prisma-next/* 条目改为精确的 <目标版本>（不加插入符号或波浪号）。所有条目都升级到同一版本。涵盖 dependencies 和 devDependencies。升级技能本身通过 pnpm dlx skills add 提供，位于 .agents/skills/prisma-next-upgrade/（或 CLI 管理的等效目录）下；不存在需要升级的 @prisma-next/upgrade-skill npm 条目。

2. 安装。 运行 pnpm install（或项目用于管理锁文件的命令）。此时项目代码可能与新类型不兼容；升级说明用于修复此问题。

3. 阅读升级说明。 从此技能包中加载 upgrades/<起始版本>-to-<目标版本>/instructions.md。解析 YAML frontmatter，并特别关注其中的 changes[] 数组。

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

   • 如果条目包含 detection 块（glob + 内容谓词），则运行检测；没有匹配文件时跳过该变更。没有 detection → 无条件应用。
   • 如果条目指定了 script:（与 instructions.md 同目录的相对路径），则从项目根目录调用该脚本：通过 pnpm exec tsx <path> 运行 *.ts，通过 bash <path> 运行 *.sh，codemod 则按照脚本自身的说明运行。没有 script → 直接遵循正文说明。

   空的 changes[]（表示此迁移不包含用户侧破坏性变更的占位结构）不执行任何操作，直接进入验证。

5. 验证。 运行 pnpm typecheck && pnpm test（或项目中的等效命令；应从项目 package.json 的 scripts 字段中查找）。如果有任何检查失败，立即停止升级链。不得自动回滚；应向用户报告失败变更的 id（来自 frontmatter）、变更涉及的文件路径，以及推断出的修复方法。

6. 提交。 每个步骤单独提交，包含 package.json 的版本变更、锁文件变更，以及所有源码改写：

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

（或遵循项目自身的提交消息规范。）绝不要压缩多个步骤的提交。用户可以在合并时压缩提交；但进行中的历史必须按步骤保留，以便能够二分定位失败步骤。

然后继续下一步。

升级链完成后

向用户报告：已执行的步骤数、你创建的提交 SHA，以及尚未处理的后续事项（例如，升级前已有测试失败且升级后仍然失败）。

失败情况

步骤失败时，提供结构化错误，包含代码 PN-UPGRADE-NNNN、失败变更的 id、涉及的文件路径（或锁文件，或验证命令）以及推断出的修复方法。不要自动重试；不要自动回滚。用户可以自行还原，以清理当前状态。

如果触发了预检中止，则不要升级任何版本；项目应保持不变。