prisma-next-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upgrade Prisma Next (user app)

升级Prisma Next（用户应用）

This skill upgrades a project that consumes Prisma Next via the public package API (

@prisma-next/postgres

@prisma-next/mongo

, the contract files in

prisma/

, etc.). If the project is itself a Prisma Next extension, use the

prisma-next-extension-upgrade

skill instead — or both, if the repo contains both an app and an extension package.

本技能用于升级通过公开包API（

@prisma-next/postgres

、

@prisma-next/mongo

、

prisma/

目录下的合约文件等）使用Prisma Next的项目。如果项目本身是Prisma Next扩展，请改用

prisma-next-extension-upgrade

技能——如果仓库同时包含应用和扩展包，则可同时使用这两个技能。

Step 0 — Ensure the skill is up to date

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

Before anything else, ensure this skill is installed at

@latest

and reload it. Bug fixes to old per-transition upgrade instructions ship in the latest skill release as part of its cumulative set; running against a stale skill can apply a known-broken translation.

If the agent runtime supports an in-session refresh, perform it now. Otherwise, exit and ask the user to re-install (

pnpm dlx skills add prisma/prisma-next/skills/upgrade --all

), then re-invoke. The upgrade-skill subpath is intentionally unpinned (always

main

) — the cumulative instruction set is the source of truth, and the latest release fixes apply to every prior transition.

在开始任何操作之前，请确保本技能已安装

@latest

版本并重新加载。针对旧过渡升级说明的Bug修复会随最新技能版本发布，包含在累积更新集中；使用过时的技能可能会应用已知存在问题的转换操作。

如果Agent运行时支持会话内刷新，请立即执行。否则，请退出并要求用户重新安装（

pnpm dlx skills add prisma/prisma-next/skills/upgrade --all

），然后重新调用。升级技能的子路径未固定版本（始终为

main

分支）——累积说明集是事实来源，最新发布的修复适用于所有先前的过渡版本。

Pre-flight — extension compatibility

预检 —— 扩展兼容性

Before changing any code, refuse to upgrade past any installed extension's pinned Prisma Next version. Extensions in Prisma Next pin every

@prisma-next/*

dependency to a single exact version (no carets, no ranges); that pin is the highest version the extension has been validated against. Upgrading the user app past that pin would silently desynchronise the extension's type identity from the app's.

Steps:

Read
prisma-next.config.ts
(or its TS-discoverable equivalent at the project root) and enumerate the list of extension packages it imports. Each
```
extensionPacks: [...]
```
entry corresponds to an installed npm package.
For each extension, read its installed
```
package.json
```
from
```
node_modules/<extension-package-name>/package.json
```
and find any
```
@prisma-next/*
```
entry under
```
dependencies
```
,
```
peerDependencies
```
, or
```
optionalDependencies
```
. By construction those entries are exact-version pins (e.g.
```
"0.7.0"
```
), set when the extension author last ran their own upgrade.
Compute the lowest pinned version across all extensions. That is the highest Prisma Next version reachable by this app on its current extension set.
Compare to the user's target. If the target exceeds the lowest pin, halt with a structured message naming each lagging extension and its pinned version, and offer two paths:
- (a) Wait for the lagging extension to publish a compatible release, then re-run.
- (b) Re-run with
```
--to=<highest-reachable>
```
  (or whatever flag/option the user is using to set the target).

Do not auto-downgrade the target; do not skip the lagging extension; do not bump past it. If the user explicitly overrides the halt, surface the risk clearly first.

prisma-next.config.ts

is absent or names no extensions, skip the pre-flight.

在修改任何代码之前，请勿升级到超过已安装扩展所固定的Prisma Next版本。Prisma Next中的扩展会将所有

@prisma-next/*

依赖项固定到单一精确版本（无插入符、无版本范围）；该固定版本是扩展已验证过的最高兼容版本。将用户应用升级到超过此固定版本会导致扩展的类型标识与应用的类型标识无声地不同步。

步骤：

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

请勿自动降级目标版本；请勿跳过滞后的扩展；请勿升级超过该版本。如果用户明确要求跳过停止操作，请先明确告知风险。

如果

prisma-next.config.ts

不存在或未指定任何扩展，则跳过预检步骤。

Role detection

角色检测

This skill applies when the project consumes Prisma Next:

package.json

declares one or more

@prisma-next/*

packages under

dependencies

devDependencies

, and

the package is not itself an extension (no
```
@prisma-next/contract
```
(or other SPI) under
```
dependencies
```
/
```
peerDependencies
```
; name does not match
```
^@.*/extension-
```
; not referenced from a sibling app's
```
prisma-next.config.ts
```
).

If the project also matches the extension-author role, install the

prisma-next-extension-upgrade

skill (

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

) and run this flow first, then that one in the same session. If detection is ambiguous, ask the user.

本技能适用于使用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

），并先运行本流程，再在同一会话中运行扩展作者流程。如果检测结果不明确，请询问用户。

Version detection

版本检测

From-version. Read the currently-installed Prisma Next version from
```
pnpm-lock.yaml
```
(or
```
package-lock.json
```
/
```
yarn.lock
```
) by inspecting the resolved version of any
```
@prisma-next/*
```
package. If the lockfile shows multiple
```
@prisma-next/*
```
packages at different minors (already broken), the lowest minor is the from-version.
To-version. Either the version the user specified, or the latest stable from
```
npm view @prisma-next/postgres dist-tags.latest
```
.

Report both back to the user before continuing.

起始版本。通过检查任何
```
@prisma-next/*
```
包的已解析版本，从
```
pnpm-lock.yaml
```
（或
```
package-lock.json
```
/
```
yarn.lock
```
）读取当前已安装的Prisma Next版本。如果锁文件显示多个
```
@prisma-next/*
```
包处于不同的小版本（已损坏状态），则最低的小版本为起始版本。
目标版本。要么是用户指定的版本，要么是从
```
npm view @prisma-next/postgres dist-tags.latest
```
获取的最新稳定版本。

在继续操作前，将两个版本都告知用户。

Transition chain

过渡链

If the from-to delta spans multiple minor versions (e.g.

0.6 → 0.8

), build the chain of one-minor steps:

text

0.6 → 0.7 → 0.8

Apply each step in order, fully: bump, install, run instructions, validate, commit — before moving to the next. Halt the chain on the first failed step; do not skip ahead.

The chain order does not depend on which extensions are installed; the pre-flight has already established the target is reachable.

如果起始版本到目标版本跨越多个小版本（例如

0.6 → 0.8

），则构建逐个小版本升级的链：

text

0.6 → 0.7 → 0.8

按顺序完整应用每个步骤：升级版本、安装依赖、执行升级说明、验证、提交——然后再进行下一步。在第一个失败的步骤处停止链；请勿跳过后续步骤。

链的顺序不依赖于已安装的扩展；预检步骤已确定目标版本是可达到的。

Per-step flow

单步骤流程

For each

(from, to)

step in the chain:

Bump
@prisma-next/*
deps. Rewrite every
```
@prisma-next/*
```
entry in the project's
```
package.json
```
to the exact
```
<to>
```
version (no caret, no tilde). All entries advance to the same version. Cover
```
dependencies
```
and
```
devDependencies
```
. The upgrade skill itself is delivered through
```
pnpm dlx skills add
```
and lives under
```
.agents/skills/prisma-next-upgrade/
```
(or the equivalent CLI-managed directory) — there is no
```
@prisma-next/upgrade-skill
```
npm entry to bump.
Install. Run
```
pnpm install
```
(or the project's lockfile-managing command). The project's code is now broken against the new types — the upgrade instructions for
```
<from> → <to>
```
exist to fix it.
Read the upgrade instructions. Load
```
upgrades/<from>-to-<to>/instructions.md
```
from this skill package. Parse the YAML frontmatter and pay particular attention to its
```
changes[]
```
array.
Apply each change. For each entry in
```
changes[]
```
:
- If the entry has a
```
detection
```
  block (glob + content predicate), run it; skip the change if no files match. No
```
detection
```
  → apply unconditionally.
- If the entry names a
```
script:
```
  (relative path next to
```
instructions.md
```
  ), invoke it from the project root:
```
*.ts
```
  via
```
pnpm exec tsx <path>
```
  ,
```
*.sh
```
  via
```
bash <path>
```
  , codemods per the script's own prose. No
```
script
```
  → follow the prose body directly.
Empty
```
changes[]
```
(placeholder shape for transitions with no user-side breaking changes) is a no-op — proceed to validation.
Validate. Run
```
pnpm typecheck && pnpm test
```
(or the project's equivalent — the
```
scripts
```
field of the project's
```
package.json
```
is the discovery surface). If anything is red, halt the chain. Do not auto-roll-back; surface the failure to the user with the failing change's
```
id
```
(from the frontmatter), the file paths the change operated on, and the inferred remediation.
Commit. One commit per step containing the
```
package.json
```
bump, lockfile churn, and any source rewrites:
text
```
chore: upgrade @prisma-next/* to <to-version>
```
(Or the project's own commit-message convention.) Never squash steps. The user may squash on merge; the in-flight history must be per-step so a failed step is bisectable.

Then move on to the next step.

针对链中的每个

(from, to)

步骤：

升级
@prisma-next/*
依赖。将项目
```
package.json
```
中的每个
```
@prisma-next/*
```
条目重写为精确的
```
<to>
```
版本（无插入符、无波浪号）。所有条目都升级到同一版本。覆盖
```
dependencies
```
和
```
devDependencies
```
。升级技能本身通过
```
pnpm dlx skills add
```
交付，存储在
```
.agents/skills/prisma-next-upgrade/
```
（或等效的CLI管理目录）下——不存在需要升级的
```
@prisma-next/upgrade-skill
```
npm条目。
安装依赖。运行
```
pnpm install
```
（或项目的锁文件管理命令）。此时项目代码与新类型不兼容——
```
<from> → <to>
```
的升级说明用于修复此问题。
读取升级说明。从本技能包中加载
```
upgrades/<from>-to-<to>/instructions.md
```
。解析YAML前置内容，尤其注意其
```
changes[]
```
数组。
应用每个变更。针对
```
changes[]
```
中的每个条目：
- 如果条目包含
```
detection
```
  块（通配符+内容谓词），则执行该块；如果没有匹配的文件，则跳过此变更。无
```
detection
```
  块则无条件应用。
- 如果条目指定了
```
script:
```
  （
```
instructions.md
```
  旁边的相对路径），则从项目根目录调用该脚本：
```
*.ts
```
  文件通过
```
pnpm exec tsx <path>
```
  执行，
```
*.sh
```
  文件通过
```
bash <path>
```
  执行，代码修改遵循脚本自身的说明。无
```
script
```
  则直接遵循文本说明。
空的
```
changes[]
```
（用于无用户端破坏性变更的过渡版本的占位符结构）表示无需操作——直接进入验证步骤。
验证。运行
```
pnpm typecheck && pnpm test
```
（或项目的等效命令——项目
```
package.json
```
的
```
scripts
```
字段是发现入口）。如果任何环节失败，则停止链。请勿自动回滚；向用户展示失败信息，包含失败变更的
```
id
```
（来自前置内容）、变更操作的文件路径，以及推断的修复方案。
提交代码。每个步骤单独提交一次，包含
```
package.json
```
的版本升级、锁文件的变更，以及任何源代码修改：
text
```
chore: upgrade @prisma-next/* to <to-version>
```
（或项目自身的提交消息规范）。切勿合并步骤。用户可在合并时合并提交；过程中的提交历史必须按步骤划分，以便在步骤失败时可进行二分查找定位问题。

然后进行下一步骤。

When the chain is done

链完成时

Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups (e.g. tests that were already red before the upgrade and still are).

向用户反馈：已应用的步骤数量、所做提交的SHA值，以及任何未完成的后续事项（例如升级前已失败且仍未修复的测试）。

Failure surfaces

失败场景

When a step fails: surface a structured error with code

PN-UPGRADE-NNNN

, the failing change's

id

, the file paths touched (or the lockfile, or the validation command), and the inferred remediation. Do not retry automatically; do not auto-roll-back. The user can revert if they want a clean slate.

If a pre-flight halt fires, do not bump anything; the project is left unchanged.

当步骤失败时：展示结构化错误，包含代码

PN-UPGRADE-NNNN

、失败变更的

id

、涉及的文件路径（或锁文件、验证命令），以及推断的修复方案。请勿自动重试；请勿自动回滚。用户可自行回滚以恢复干净状态。

如果预检步骤触发停止操作，则不进行任何版本升级；项目保持不变。