prisma-8-extension-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upgrade Prisma Next (extension)

升级Prisma Next（扩展版）

This skill upgrades a project that is a Prisma Next extension — a package that consumes the framework SPI (

@internal/contract

@internal/framework-components

@internal/migration-tools

, etc.) and exposes contract / middleware / codec / migration surfaces that downstream apps install via

prisma-next.config.ts

If the project you are upgrading is a consumer app (it imports

@internal/postgres

@internal/mongo

from its application code), use the

prisma-next-upgrade

skill instead — or both, if the repo contains both a consumer app and an extension package, in which case run the user flow first then the extension flow in the same session.

本技能用于升级作为Prisma Next扩展的项目——即一个使用框架SPI（

@internal/contract

、

@internal/framework-components

、

@internal/migration-tools

等）并暴露契约/中间件/编解码器/迁移接口的包，下游应用可通过

prisma-next.config.ts

安装这些接口。

如果你要升级的项目是一个消费端应用（它在应用代码中导入

@internal/postgres

或

@internal/mongo

），请改用

prisma-next-upgrade

技能——如果仓库同时包含消费端应用和扩展包，则先运行用户流程，再在同一会话中运行扩展流程。

Step 0 — Ensure the skill is up to date

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

Before doing 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.

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

bash

pnpm dlx skills add prisma/prisma/skills --skill prisma-8-extension-upgrade -y

The extension-author skill install is intentionally unpinned (always

main

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

Then re-invoke this skill before proceeding.

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

@latest

版本并重新加载。针对旧过渡升级指令的修复会随最新技能版本一起发布，使用过时的技能可能会应用已知存在问题的转换操作。

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

bash

pnpm dlx skills add prisma/prisma/skills --skill prisma-8-extension-upgrade -y

扩展作者技能的安装故意不固定版本（始终使用

main

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

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

Role detection

角色检测

This skill applies when the project is a Prisma Next extension. Heuristics:

package.json

declares

@internal/contract

(or another SPI package) under

dependencies

peerDependencies

, and

the package's
```
name
```
matches
```
^@.*/extension-
```
(the in-tree convention used by
```
@internal/extension-pgvector
```
, etc.), or
the package is referenced as an
```
extensions
```
entry from a sibling app's
```
prisma-next.config.ts
```
in the same monorepo.

If the project additionally consumes Prisma Next from its own app code, install the

prisma-next-upgrade

skill (

pnpm dlx skills add prisma/prisma/skills --skill prisma-next-upgrade -y

) and run the user flow first, then this flow in the same session.

If detection is ambiguous, ask the user which role to operate under.

本技能适用于项目是Prisma Next扩展的场景。判断依据：

package.json

在

dependencies

或

peerDependencies

中声明了

@internal/contract

（或其他SPI包），且

包的
```
name
```
匹配
```
^@.*/extension-
```
（
```
@internal/extension-pgvector
```
等内部包使用的约定），或
该包在同一单体仓库中被兄弟应用的
```
prisma-next.config.ts
```
的
```
extensions
```
条目引用。

如果该项目同时在自身应用代码中使用Prisma Next，请安装

prisma-next-upgrade

技能（

pnpm dlx skills add prisma/prisma/skills --skill prisma-next-upgrade -y

），先运行用户流程，再在同一会话中运行本流程。

如果检测结果不明确，请询问用户要以哪个角色操作。

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
```
@internal/*
```
entry. If the lockfile shows multiple
```
@internal/*
```
packages at different minors, the lowest minor is the from-version.
To-version. Either the version the user specified, or whatever
```
npm view @internal/contract dist-tags.latest
```
reports. Do not assume that is a stable version: while Prisma 8 is a release candidate,
```
latest
```
tracks the newest release,
```
8.0.0-rc.N
```
included. If the user wants a stable version specifically, they must name it.

Report both back to the user before continuing.

起始版本：从
```
pnpm-lock.yaml
```
（或
```
package-lock.json
```
/
```
yarn.lock
```
）中读取当前安装的Prisma Next版本，检查任意
```
@internal/*
```
条目已解析的版本。如果锁文件显示多个
```
@internal/*
```
包处于不同的小版本，取最低的小版本作为起始版本。
目标版本：要么是用户指定的版本，要么是
```
npm view @internal/contract dist-tags.latest
```
返回的版本。不要假设这是稳定版本：当Prisma 8处于候选发布阶段时，
```
latest
```
会跟踪最新发布版本，包括
```
8.0.0-rc.N
```
。如果用户明确想要稳定版本，必须指定具体版本。

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

Transition chain

过渡链

If the from-to delta spans more than one release (e.g.

0.6 → 0.8

), build the chain of steps between them:

text

0.6 → 0.7 → 0.8

The

upgrades/

directories in this package name the steps — read the chain off the directory names rather than deriving it arithmetically. Each directory is

<from>-to-<to>

. A step is one minor while the version line is stable (

0.7-to-0.8

); on the v8 release-candidate line a step is one release candidate (

8.0.0-rc.1-to-8.0.0-rc.2

), because an RC may carry breaking changes and each one needs its own translation. Moving onto the RC line from the last stable minor is a single step of its own (

0.17-to-8.0.0-rc.1

Apply each step in order, fully: bump, install, run instructions, check pins, validate, commit — before moving to the next. Halt the chain on the first failed step.

如果起始版本到目标版本的跨度超过一个版本（例如

0.6 → 0.8

），构建它们之间的步骤链：

text

0.6 → 0.7 → 0.8

本包中的

upgrades/

目录命名了各个步骤——从目录名称读取步骤链，而非通过计算推导。每个目录的格式为

<from>-to-<to>

。在版本线稳定时，一个步骤对应一个小版本（

0.7-to-0.8

）；在v8候选发布线上，一个步骤对应一个候选版本（

8.0.0-rc.1-to-8.0.0-rc.2

），因为候选版本可能包含破坏性变更，每个版本都需要单独的转换操作。从最后一个稳定小版本切换到候选发布线是一个独立的步骤（

0.17-to-8.0.0-rc.1

）。

按顺序完整应用每个步骤：升级依赖、安装、执行指令、检查版本固定、验证、提交——然后再进行下一步。在第一个失败的步骤处停止整个流程。

Per-step flow

单步骤流程

This flow assumes you are an external extension author — your extension lives in its own repo and consumes

@internal/*

from npm. (Extensions inside the

prisma/prisma

monorepo itself are bumped via

pnpm bump-version

scripts/set-version.ts

, which rewrites every

workspace:<X.Y.Z>

spec in lockstep with the root version; they do not run this skill.)

For each

(from, to)

step in the chain:

Bump
@internal/*
deps. Rewrite every
```
@internal/*
```
entry in the extension's
```
package.json
```
to the exact
```
<to>
```
version (e.g.
```
"0.8.0"
```
— no caret, no tilde, no range, no
```
workspace:
```
specifier; the exact-pin rule below details why). All entries advance to the same version. Cover whichever dep field(s) the extension uses today —
```
dependencies
```
and/or
```
peerDependencies
```
— and any
```
optionalDependencies
```
. The extension-upgrade skill itself ships via
```
pnpm dlx skills add
```
(see Step 0); there is no
```
@internal/extension-upgrade-skill
```
npm entry to bump. The companion CLI tool is
```
@internal/extension-author-tools
```
— leave its pin at the version the extension's CI is currently using; bumping it is independent of the framework upgrade and is normally a no-op.
Install. Run
```
pnpm install
```
(or the project's lockfile-managing command). The extension's source is now broken against the new SPI — the upgrade instructions for
```
<from> → <to>
```
exist to fix it.
Check pins. Run
```
pnpm exec prisma-8-check-pins
```
(shipped by
```
@internal/extension-author-tools
```
). This sanity check asserts that every
```
@internal/*
```
entry across
```
dependencies
```
,
```
peerDependencies
```
, and
```
optionalDependencies
```
is a single exact-version string and that all entries share the same version. If the check fails, the bump step did not rewrite every spec — fix the offending entries and re-run before proceeding.
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 (a glob + content predicate), run it. If no files match, skip this change.
- If the entry has no
```
detection
```
  , apply unconditionally.
- If the entry names a
```
script:
```
  (a relative path next to
```
instructions.md
```
  ), invoke it from the project root:
  - ```
  *.ts
```
  →
```
  pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
```
- ```
*.sh
```
    →
```
bash <skill>/upgrades/<from>-to-<to>/<script>
```
  - codemods → invoke per the script's own
```
instructions.md
```
    prose.
- If the entry has no
```
script
```
  , follow the prose body in
```
instructions.md
```
  directly.
If
```
changes[]
```
is empty (the placeholder shape for transitions with no extension-side breaking changes), this sub-step is a no-op — proceed to validation.
Validate. Run
```
pnpm build && pnpm test
```
(or the project's equivalent — the
```
scripts
```
field of the extension'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. Create one commit containing this step's changes: the
```
package.json
```
bump, the lockfile churn from
```
pnpm install
```
, and any source-file rewrites from the applied changes. Use the message:
text
```
chore: upgrade @internal/* to <to-version>
```
(Or the extension's own commit-message convention, if it has one.) One commit per step — never squash steps.

Move on to the next step. Repeat.

本流程假设你是外部扩展作者——你的扩展位于自己的仓库中，并从npm获取

@internal/*

依赖。（

prisma/prisma

单体仓库内部的扩展通过

pnpm bump-version

scripts/set-version.ts

升级，该工具会同步重写所有

workspace:<X.Y.Z>

规范与根版本；它们不使用本技能。）

对于链中的每个

(from, to)

步骤：

升级
@internal/*
依赖：将扩展
```
package.json
```
中的所有
```
@internal/*
```
条目重写为精确的
```
<to>
```
版本（例如
```
"0.8.0"
```
——不要使用脱字符
```
^
```
、波浪号
```
~
```
、版本范围、
```
workspace:
```
规范；下方的精确固定规则会说明原因）。所有条目都升级到同一版本。覆盖扩展当前使用的所有依赖字段——
```
dependencies
```
和/或
```
peerDependencies
```
——以及任何
```
optionalDependencies
```
。扩展升级技能本身通过
```
pnpm dlx skills add
```
安装（见步骤0）；没有
```
@internal/extension-upgrade-skill
```
的npm条目需要升级。配套CLI工具是
```
@internal/extension-author-tools
```
——保留其版本为扩展CI当前使用的版本；升级它与框架升级是独立的，通常无需操作。
安装依赖：运行
```
pnpm install
```
（或项目的锁文件管理命令）。此时扩展的源代码与新SPI不兼容——
```
<from> → <to>
```
的升级指令就是用来修复这个问题的。
检查版本固定：运行
```
pnpm exec prisma-8-check-pins
```
（由
```
@internal/extension-author-tools
```
提供）。这个检查会验证
```
dependencies
```
、
```
peerDependencies
```
和
```
optionalDependencies
```
中的所有
```
@internal/*
```
条目是否为单一精确版本字符串，且所有条目版本一致。如果检查失败，说明升级步骤没有重写所有规范——修复有问题的条目后重新运行检查，再继续操作。
读取升级指令：从本技能包中加载
```
upgrades/<from>-to-<to>/instructions.md
```
。解析YAML前置内容，尤其注意其
```
changes[]
```
数组。
应用每个变更：对于
```
changes[]
```
中的每个条目：
- 如果条目包含
```
detection
```
  块（通配符+内容谓词），执行该检测。如果没有匹配文件，跳过此变更。
- 如果条目没有
```
detection
```
  块，无条件应用。
- 如果条目指定了
```
script:
```
  （
```
instructions.md
```
  旁边的相对路径），从项目根目录调用它：
  - ```
  *.ts
```
  →
```
  pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
```
- ```
*.sh
```
    →
```
bash <skill>/upgrades/<from>-to-<to>/<script>
```
  - 代码修改工具 → 按照脚本自身
```
instructions.md
```
    中的说明调用。
- 如果条目没有
```
script
```
  ，直接遵循
```
instructions.md
```
  中的文字说明。
如果
```
changes[]
```
为空（表示该过渡版本对扩展无破坏性变更的占位符），此子步骤无需操作——直接进入验证环节。
验证：运行
```
pnpm build && pnpm test
```
（或项目的等效命令——扩展
```
package.json
```
的
```
scripts
```
字段是查找入口）。如果任何环节失败，停止整个流程。不要自动回滚；向用户展示失败信息，包括失败变更的
```
id
```
（来自前置内容）、变更操作的文件路径，以及推断的修复方案。
提交代码：创建一个包含此步骤所有变更的提交：
```
package.json
```
的版本升级、
```
pnpm install
```
导致的锁文件变更，以及应用变更带来的源代码修改。使用以下提交信息：
text
```
chore: upgrade @internal/* to <to-version>
```
（如果扩展有自己的提交信息约定，使用其约定。）每个步骤单独提交——绝不要合并多个步骤的提交。

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

Exact-pin rule

精确固定规则

Prisma Next extensions pin every

@internal/*

dependency to a single exact version (no

, no

, no range, no wildcard, no

workspace:

specifier in the published

package.json

). All

@internal/*

entries share the same version. The pin advances only after a successful upgrade run against the new minor.

prisma-8-check-pins

(shipped by

@internal/extension-author-tools

— install with

pnpm add -D @internal/extension-author-tools

) enforces the rule. Run it locally with:

bash

pnpm exec prisma-8-check-pins

Wire it into the extension's CI alongside the build/test step so an accidental range pin fails the PR before it lands.

Prisma Next扩展会将所有

@internal/*

依赖固定到单一精确版本（已发布的

package.json

中不要使用

、

、版本范围、通配符、

workspace:

规范）。所有

@internal/*

条目使用同一版本。只有在针对新小版本的升级运行成功后，才会更新固定版本。

prisma-8-check-pins

（由

@internal/extension-author-tools

提供——使用

pnpm add -D @internal/extension-author-tools

安装）会强制执行此规则。本地运行命令：

bash

pnpm exec prisma-8-check-pins

将其集成到扩展的CI流程中，与构建/测试步骤一起运行，这样意外的范围版本固定会在PR合并前导致失败。

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.

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

Failure surfaces

失败场景

When a step fails:

Surface a structured error with code
```
PN-UPGRADE-NNNN
```
, the failing change's
```
id
```
, the file paths the change touched (or the lockfile, or the pin check, or the validation command), and the inferred remediation.
Do not retry automatically.
Do not auto-roll-back the commit. The user can revert if they want a clean slate.

当步骤失败时：

展示结构化错误，包含错误码
```
PN-UPGRADE-NNNN
```
、失败变更的
```
id
```
、变更涉及的文件路径（或锁文件、版本固定检查、验证命令），以及推断的修复方案。
不要自动重试。
不要自动回滚提交。用户可以自行撤销以恢复到干净状态。