用途:当 Prisma Next 仓库的 PR 对框架代码做了破坏性变更,并因此改动 examples/ 或 packages/3-extensions/ 中的测试以修复报错时,需按此技能为受影响的已发布技能包补写升级说明条目,供下游消费者与扩展作者运行对应的 agent 流程自动迁移代码。
主要能力:向 skills/upgrade/prisma-next-upgrade/(面向 @prisma-next/postgres、@prisma-next/mongo、prisma/ 契约文件等公共 API 用户)和 skills/extension-author/prisma-next-extension-upgrade/(面向使用框架 SPI 如 @prisma-next/contract、@prisma-next/framework-components、@prisma-next/migration-tools 的扩展作者)两个独立技能集群写入每条 transition 的 upgrade-instructions 条目。条目写入对应 upgrades/<M>-to-<M+1>/instructions.md 的 changes[] 数组,每项含 id、单行 summary、可选 detection(glob + 内容断言)及可选 script: 引用,脚本可为 TypeScript、shell 或 jscodeshift 风格 codemod。两集群内容不共享,跨受众变更在两边分别记录并复制脚本,不使用符号链接。
使用方式:先读根 package.json 的 version 确定当前已发布 minor M,得出进行中的过渡 M → M+1 与目录 upgrades/<M>-to-<M+1>/;用 origin/main..HEAD 的 git diff 判断受影响 substrate,按路由表(examples/ 对应 user 技能,packages/3-extensions/ 对应 extension 技能,两者都触及则各写一条)写入条目。发布前须执行验证:还原 substrate 到 PR 前状态,运行条目脚本或按 prose 操作,确认结果目录与 PR 分支状态一致且测试通过(pnpm test:examples 或 pnpm test --filter='./packages/3-extensions/*')。提交需包含条目目录、同目录脚本及 substrate 修复后状态,PR 描述需注明条目目录。
适用场景与限制:仅记录需要消费者采取行动的代码翻译变更;无消费者动作的变更不写入,纯 no-op 过渡以 changes: [] 记录。覆盖门禁 pnpm check:upgrade-coverage 只保证过渡目录存在,不保证本次 substrate diff 有对应条目,需人工复核。支持跳过发布(按单一版本步长链式目录)与 rebase 后重新判定归属目录;不负责 bump-install-validate 循环与扩展固定版本规则。机制相关工单为 TML-2519。