prisma-next-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 (

@prisma-next/contract

@prisma-next/framework-components

@prisma-next/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

@prisma-next/postgres

@prisma-next/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（

@prisma-next/contract

、

@prisma-next/framework-components

、

@prisma-next/migration-tools

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

prisma-next.config.ts

安装该扩展。

如果你要升级的项目是消费端应用（其应用代码中导入了

@prisma-next/postgres

或

@prisma-next/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-next/skills/extension-author --all

The extension-author 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.

Then re-invoke this skill before proceeding.

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

@latest

版本并重新加载。针对旧版本迁移升级说明的修复会随最新技能版本发布；使用过时的技能可能会应用已知存在问题的迁移操作。

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

bash

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

extension-author技能子路径故意未固定版本（始终指向

main

分支）——累积的指令集是权威来源，最新版本的修复适用于所有过往版本迁移。

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

Role detection

角色检测

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

package.json

declares

@prisma-next/contract

(or another SPI package) under

dependencies

peerDependencies

, and

the package's
```
name
```
matches
```
^@.*/extension-
```
(the in-tree convention used by
```
@prisma-next/extension-cipherstash
```
, etc.), or
the package is referenced as an
```
extensionPacks
```
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-next/skills/upgrade --all

) 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

中声明了

@prisma-next/contract

（或其他SPI包），且

包的
```
name
```
匹配
```
^@.*/extension-
```
（
```
@prisma-next/extension-cipherstash
```
等内部包遵循的命名约定），或
该包在同一 monorepo 中被兄弟应用的
```
prisma-next.config.ts
```
中的
```
extensionPacks
```
条目引用。

如果项目同时通过自身应用代码使用Prisma Next，请安装

prisma-next-upgrade

技能（

pnpm dlx skills add prisma/prisma-next/skills/upgrade --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/*
```
entry. If the lockfile shows multiple
```
@prisma-next/*
```
packages at different minors, the lowest minor is the from-version.
To-version. Either the version the user specified, or the latest stable from
```
npm view @prisma-next/contract dist-tags.latest
```
.

Report both back to the user before continuing.

起始版本：从
```
pnpm-lock.yaml
```
（或
```
package-lock.json
```
/
```
yarn.lock
```
）中读取当前安装的Prisma Next版本，查看任意
```
@prisma-next/*
```
条目的解析版本。如果锁文件显示多个
```
@prisma-next/*
```
包处于不同的小版本，则最低的小版本为起始版本。
目标版本：用户指定的版本，或从
```
npm view @prisma-next/contract 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, 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

按顺序完整执行每个步骤：升级依赖、安装、执行指令、检查版本锁定、验证、提交——再进入下一步。在第一个失败的步骤处停止迁移链。

Per-step flow

单步骤流程

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

@prisma-next/*

from npm. (Extensions inside the

prisma/prisma-next

monorepo itself are bumped via

pnpm bump-minor

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
@prisma-next/*
deps. Rewrite every
```
@prisma-next/*
```
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
```
@prisma-next/extension-upgrade-skill
```
npm entry to bump. The companion CLI tool is
```
@prisma-next/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-next-check-pins
```
(shipped by
```
@prisma-next/extension-author-tools
```
). This sanity check asserts that every
```
@prisma-next/*
```
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 @prisma-next/* 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获取

@prisma-next/*

依赖。（

prisma/prisma-next

monorepo内部的扩展通过

pnpm bump-minor

scripts/set-version.ts

进行版本升级，该工具会同步重写所有

workspace:<X.Y.Z>

规范，与根版本保持一致；这些扩展无需运行本技能。）

对于迁移链中的每个

(起始版本, 目标版本)

步骤：

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

进入下一步，重复上述流程。

Exact-pin rule

精确锁定规则

Prisma Next extensions pin every

@prisma-next/*

dependency to a single exact version (no

, no

, no range, no wildcard, no

workspace:

specifier in the published

package.json

). All

@prisma-next/*

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

prisma-next-check-pins

(shipped by

@prisma-next/extension-author-tools

— install with

pnpm add -D @prisma-next/extension-author-tools

) enforces the rule. Run it locally with:

bash

pnpm exec prisma-next-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扩展需将所有

@prisma-next/*

依赖锁定为单一精确版本（发布的

package.json

中不要使用

、

、版本范围、通配符或

workspace:

规范）。所有

@prisma-next/*

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

prisma-next-check-pins

（由

@prisma-next/extension-author-tools

提供——使用

pnpm add -D @prisma-next/extension-author-tools

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

bash

pnpm exec prisma-next-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
```
、变更涉及的文件路径（或锁文件、版本锁定检查、验证命令），以及推断的修复方案。
不要自动重试。
不要自动回滚提交。用户可自行回滚以恢复到干净状态。",