prisma-next-quickstart

Prisma Next — 快速入门（采用）

编辑数据契约。其余交给 Prisma 处理。

这项技能将用户从零（或接近零）带到第一次成功执行 Prisma Next 查询。三种路径，最终都会汇聚到同一段入门流程：连接 → 写入 → 读取。编辑架构会在这段流程之后进行，而不是之前。

• 初次接触指南 — 用户首次进入 Prisma Next 项目（由 npx createprisma 这类脚手架工具创建、克隆了队友的仓库，或亲自运行 prisma-next init 后想迈出第一步），并询问 “我可以用 Prisma Next 做什么？”、“从哪里开始？” 或 “接下来做什么？”。目标是让他们了解契约、连接数据库、完成一行数据的往返操作，并让后续命令自然呈现。
• 全新项目 — 新项目，全新数据库。用户自行运行 prisma-next init。init 会使用示例模型初始化一个入门契约，因此数据库初始化后，这条路径便会加入初次接触指南的流程。
• 已有数据库 — 已有数据库，但还没有契约。使用 contract infer 从数据库推断契约，使用 db sign 对标记进行签名，然后针对现有表之一编写查询。

本技能不涵盖从其他 ORM（Drizzle、Prisma 6/7、Sequelize、TypeORM、Kysely、Knex、原始驱动）迁移。这些 ORM 有单独安装的技能。

适用场景

• 用户询问 “我可以用 Prisma Next 做什么？”、“接下来可以用 Prisma 做什么？”、“从哪里开始？”、“我应该先做什么？”，且磁盘上已存在 PN 项目。使用下方的初次接触指南路径。
• 用户刚运行 createprisma（或同类脚手架工具），并询问接下来该做什么。使用初次接触指南路径。
• 用户要启动新项目，并想使用 Prisma Next。使用全新项目路径。
• 用户已有数据库（没有 PN 契约），并想引入 PN。使用已有数据库路径。
• 用户输入 “prisma-next init”、“开始使用 PN”、“设置 PN”、“如何搭建项目脚手架”。使用全新项目路径。
• 用户说 “我有现成的 Postgres/Mongo，如何开始使用 PN？”。使用已有数据库路径。

不适用场景

• 用户已有 PN 项目，并想添加模型 → prisma-next-contract。
• 用户想从特定 ORM 迁移 → 安装 @prisma-next/migrate-from-<orm>-skill（单独提供）。
• 用户想在已有契约的项目中配置 db.ts → prisma-next-runtime。
• 用户想将 Prisma Next 集成到构建工具（Vite 插件、Next.js 等）→ prisma-next-build。

核心概念

• Contract：数据模型。可使用 contract.prisma（PSL，规范表层）或 contract.ts（TypeScript 构建器）编写。框架会读取它并生成两个产物：contract.json（运行时 IR）和 contract.d.ts（类型）。
• Target：底层存储。目前支持 postgres 或 mongodb。在执行 init 时选择，并内置于脚手架导入的 @prisma-next/<target> façade 中。
• 编写模式：编写 contract 的方式。psl（Prisma Schema Language，默认）或 typescript（程序化构建器，可选配合 Vite 插件，在 vite dev 期间自动生成产物——参见 prisma-next-build）。
• façade 包。 脚手架为每个 target 仅安装一个 façade——@prisma-next/postgres（或 @prisma-next/mongo）。用户代码从 façade 子路径导入（@prisma-next/postgres/config、@prisma-next/postgres/runtime、@prisma-next/postgres/contract-builder）。façade 内置了 family / target / adapter / driver 的连接配置；不要绕过它。完整列表请参见 prisma-next-contract。
• db.ts：运行时入口。它与 contract 源文件一起位于 src/prisma/db.ts。该文件会导入 contract 产物，并导出应用其余部分使用的 db 值。
• Marker：数据库中的一条 pn_meta_marker 记录，用于记录 contract 哈希。它使 PN 能够检测 contract 与实时数据库之间的偏差。由 db init（绿地项目／首次接入场景）或 db sign（棕地项目）创建。

规范磁盘布局

所有使用 Prisma Next 的应用都采用相同的结构：

<app-root>/
├── prisma-next.config.ts             ← project config at repo root
├── src/
│   └── prisma/
│       ├── contract.prisma           ← (or contract.ts) — schema source you author
│       ├── contract.json             ← emitted by `contract emit` — do not edit
│       ├── contract.d.ts             ← emitted by `contract emit` — do not edit
│       └── db.ts                     ← runtime entry; the rest of `src/` imports from here
└── migrations/
    ├── snapshots/                    ← content-addressed contract store, shared across spaces
    │   └── <hex>/
    │       ├── contract.json
    │       └── contract.d.ts
    └── app/                          ← created on first `migration plan` / `db init`
        ├── refs/head.json
        └── <timestamp>_<slug>/
            ├── migration.json
            ├── ops.json
            └── migration.ts

需要牢记三点：

• src/prisma/ 是 contract 的存放位置——源文件、生成的产物和 db.ts 都放在同一目录中。src/ 的其余部分从 ./prisma/db（或根据文件深度从 ../prisma/db）导入。
• migrations/app/——app/ 部分是使用该框架的应用的空间 ID。你依赖的扩展会在 migrations/ 下拥有同级目录（每个扩展 contract-space 对应一个目录），但你不应写入这些目录——你的迁移文件只能放在 app/ 子树中。
• prisma-next.config.ts 位于仓库根目录，而不是 src/ 下。所有命令都会以配置文件所在目录为基准解析路径。

构建扩展包或聚合根单体仓库包的贡献者使用不同的布局——src/contract.{prisma,ts}（没有 prisma/ 子目录）+ migrations/<timestamp>_<slug>/（没有 app/ 部分）。这种区别是有意设计的；请参见 prisma-next-contract，了解适用于你的路径。

注意——prisma-next init 目前生成的布局不正确。 它会在仓库根目录下生成 prisma/contract.{prisma,ts} 和 prisma/db.ts，而不是放在 src/prisma/ 下。此问题已记录为 TML-2532。修复发布之前，可以在执行 init 时传入 --schema-path src/prisma/contract.prisma，或者在 init 之后将生成的 prisma/ 目录移入 src/prisma/，并更新 prisma-next.config.ts 中的 contract 路径，使其与之匹配。上述规范布局是演示示例所采用的布局，也是框架其余部分所预期的布局。

你的第一个闭环——连接、写入、读取

这项技能中的三条路径最终都会汇聚于此。项目搭建完成、数据库可访问后，第一步始终相同：使用契约已声明的任意模型，连接数据库、写入一条记录，再读回来。第一步先不要改动契约源文件——等往返读写成功后再扩展。

将代码片段写入 src/ 下的一个新文件中（例如 src/first-arc.ts），这样相对导入路径只需一层：

// src/first-arc.ts
import 'dotenv/config';
import { db } from './prisma/db';

// Write a row against the starter model. Adapt the field names to whatever
// model your contract source actually declares — read it first.
await db.orm.User.create({ email: '[email protected]' });

// Read it back.
const users = await db.orm.User.select('id', 'email').all();
console.log(users);

如果输出 [{ id: 1, email: '[email protected]' }]，说明项目已端到端连通，用户也从 “我有一个项目” 迈入了 “我正在构建” 的阶段。

db.orm.<Model> 是默认的 ORM 用法——以模型为形状，并基于契约提供完整类型；首次使用时会惰性连接数据库（它会通过运行时加载 dotenv/config 的环境读取 .env 中的 DATABASE_URL）。用户准备好后，可以通过更深入的 prisma-next-queries 技能了解其余功能（筛选器、联接、事务、SQL 构建器、原始 SQL、TypedSQL）。

**Mongo 目标：**上面的代码片段采用 SQL 目标的形式。在 @prisma-next/mongo 中，db.orm 使用集合的存储名称作为键（即 @@map(...)，如果没有 @@map，则使用小写模型名称），因此同一闭环应写为 await db.orm.users.create(...) / await db.orm.users.select('id', 'email').all()，而不是 db.orm.User。完整规则和改写方法见 prisma-next-queries § MongoDB ORM 寻址。

闭环的前提条件。 到达闭环时，三条路径都会确保以下各项就绪：

• 仓库根目录下存在 prisma-next.config.ts，其中声明了目标和契约源文件（通常是 src/prisma/contract.prisma 或 src/prisma/contract.ts）。
• 契约源文件位于 src/prisma/contract.{prisma,ts}（由 init 创建的初始模型、由 contract infer 推断的契约，或由引导工具生成的其他契约）。
• 存在 src/prisma/db.ts，并且其中使用已生成的契约实例化了运行时。
• .env 中设置了 DATABASE_URL（或设置在运行时配置指定的位置）。
• 数据库已初始化（db init）或已签名标记（db sign），因此标记行已存在，且架构与契约相符。

以下三个工作流分别说明各自的路径如何让用户达到该状态。之后，三者都会使用上面的同一个闭环。

工作流——初次接触指引

触发语句：“我能用 Prisma Next 做什么？”、“接下来我能用 Prisma 做什么？”、“我该从哪里开始？”、“我刚运行了 createprisma”、“接下来呢？”，或任何类似说法——前提是磁盘上已有 PN 项目（由 createprisma、prisma-next init、队友或其他方式搭建）。

用户的高层意图是：“我想用这个叫作 Prisma Next 的东西，让应用连接数据库并运行起来。” 此工作流的目标是让用户以契约为起点，完成一次往返读写，并让后续命令随着用户下一步的需求自然出现。这是指引，不是导览，不是功能清单，也不是课程大纲。

概念 — 优先传达什么

Prisma Next 以契约为先。框架所做的一切——查询类型、迁移、运行时类型、漂移检测——都源自一个唯一的事实来源：契约。契约描述用户应用的数据模型。框架读取契约，并据此派生其余内容。首先传达这一点。

对 “Prisma Next 能做什么？” 的第一个回答，应说明契约路径，用一句话阐明其作用，然后引导用户让应用运行起来。不要一开始就罗列功能，也不要一开始就列出命令。可以这样开场：“你的契约位于 <path>。它描述了你的应用——查询类型、迁移和运行时类型都由它派生而来。我们先连接一个数据库，让你的应用真正能对其进行操作。”

完成引导后，第一个流程是连接 → 写入 → 读取。不是先编辑契约，也不是先规划迁移。用户的成就感来自于我的应用代码已经在数据库上运行了。

步骤 1 — 阅读项目，指出契约位置

在向用户介绍任何具体内容之前，先阅读：

• 仓库根目录下的 prisma-next.config.ts——配置了哪个目标（postgres / mongodb）、声明了哪个 contract: 路径，以及安装了哪些扩展。
• 配置声明的契约源文件（通常是 src/prisma/contract.prisma 或 src/prisma/contract.ts；早于 TML-2532 的项目可能将其放在 prisma/contract.{prisma,ts}——请检查配置中的 contract 字段）——查看是否存在初始模型。
• src/prisma/db.ts（与契约位于同一目录）——运行时入口。
• .env / .env.example——是否已设置 DATABASE_URL，还是只有示例值？
• 可选：运行 pnpm prisma-next db verify——实时数据库是否与契约一致？

然后向用户说明契约路径及其作用。例如：“你的契约位于 src/prisma/contract.prisma，目前声明了一个 User 模型。契约描述了你的应用——框架提供的每种查询类型、迁移和运行时类型都源自这个文件。接下来，我们来连接你的应用和数据库。” 具体措辞由 Agent 决定；重要的是，用户在第一次回复后知道契约在哪里，以及它是事实来源。

步骤 2 — 让用户的应用连接数据库并完成往返操作

目标是*“让你的应用真正能对数据库进行操作”，而不是“通过先决条件检查清单”*。具体做法取决于步骤 1 中已就绪的内容：

• 所有配置都已就绪。 直接写入并读取一条记录（参见上文的第一个流程——连接、写入、读取）。根据契约中声明的模型调整代码片段。
• 未设置 DATABASE_URL。 让用户在 .env 中设置它（不要放在 prisma-next.config.ts 中——参见陷阱 5）。然后运行 pnpm prisma-next db init，将当前契约应用到该数据库并写入标记行。此时应用即可连接。
• 数据库可以连接，但尚未应用契约（缺少标记行；db verify 报告存在漂移）。运行 pnpm prisma-next db init。（快速开发迭代时也可以使用 db update——它更宽松，不会写入迁移历史，适合快速迭代架构的用户。若用户询问如何将架构变更应用到数据库，再介绍它；不要提前解释。）
• 契约为空（初始化时源文件留空）。添加一个包含两个字段的模型（例如 User { id, email }），运行 pnpm prisma-next contract emit，然后运行 pnpm prisma-next db init。保持最简——先完成往返操作，之后再扩展。

用户会在此处接触 db init（以及可选的 db update、contract emit），因为当前操作需要用到这些命令。他们会在使用过程中了解这些命令的作用。

第 3 步 — 往返读写一行数据

针对契约声明的任意模型，运行上方 你的第一个 arc — 连接、写入、读取 中的代码片段。当它打印出该行数据时，用户就从 “我有一个项目” 跨越到了 “我的应用正在使用我的数据库运行”。这就是成功。

第 4 步 — 引导用户进行下一步

现在询问用户想构建什么。根据下一步要做的事，引导他们使用相应的技能：

• 更多查询（筛选、联接、事务、原生 SQL、TypedSQL）→ prisma-next-queries。
• 添加模型、更改字段、添加关联 → prisma-next-contract。在该工作流中，他们会用到 contract emit 和 db update（或 migration plan + migrate）。
• 中间件、环境配置、多个目标 → prisma-next-runtime。
• Vite / Next.js / 开发服务器集成 → prisma-next-build。
• 他们现在想全面了解工具集——下方的 日常使用的命令 是一目了然的概要。

此流程中的反模式

• 先介绍功能或罗列能力。 用户问的是他们能做什么。让他们动手做。
• 尚未使用任何命令就列出命令。 命令对应具体操作；在操作需要时再介绍。
• 在运行第一个查询前就深入讲解迁移概念。 迁移固然存在，但其价值要到后面才会体现。
• 一次添加多个模型。 先添加一个，让一个查询成功运行，再迭代。
• 带用户逐一了解 prisma-next.config.ts 中的配置项。 脚手架的默认值是正确的；等用户需要修改时再介绍。
• 跳过契约的介绍。 哪怕只说一句——“你的契约位于 <path>，它是唯一事实来源”——也能帮助用户理解；没有这句话，后续工作流看起来就像一套彼此无关的仪式。

工作流 — 从零开始

核心是：prisma-next init 是一个 CLI 命令，可生成配置、架构、运行时、依赖项和契约生成步骤。它作用于当前工作目录——没有位置参数用于指定项目名称。先创建目录并 cd 进入，然后运行 init。

mkdir my-app && cd my-app
pnpm init                                          # if no package.json yet
pnpm dlx prisma-next init                          # interactive
# or non-interactive (CI / agent runs):
pnpm dlx prisma-next init --yes --target postgres --authoring psl

遥测默认启用，可选择退出。 CLI 默认会收集匿名使用数据。每条命令——包括 init——首次使用时都会在 stderr 上打印一次通知，随后发送数据；不会出现交互式征求同意的提示。你可以随时运行 prisma-next telemetry disable 选择退出，也可以使用 DO_NOT_TRACK=1 或 PRISMA_NEXT_DISABLE_TELEMETRY=1，或者在用户配置中（prisma-next 配置目录，不是 prisma-next.config.ts）设置 "enableTelemetry": false。运行 prisma-next telemetry status 查看当前生效的设置。这与 Agent 驱动的运行有关——CLI 会记录是由 Agent 调用了它。收集的数据、每位用户的配置路径以及如何彻底重置，都记录在 docs/Telemetry.md 中。

init 支持以下标志（运行 prisma-next init --help 查看权威说明）：

• --target <db> — postgres 或 mongodb。
• --authoring <style> — psl 或 typescript。
• --schema-path <path> — 默认为 prisma/contract.prisma（或 prisma/contract.ts）。传入 --schema-path src/prisma/contract.prisma（或 .../contract.ts），即可直接在规范的 src/prisma/ 位置搭建脚手架 — init 当前的默认值有误，详见 TML-2532。
• --force — 不经提示覆盖已有脚手架（在已搭建脚手架的目录中重新运行 init 会触发重新初始化流程 — --force 会跳过确认）。
• --write-env — 同时写入 .env（默认只写入 .env.example；.env 由你掌控）。
• --probe-db — 连接一次 DATABASE_URL，并检查服务版本是否达到目标的最低要求。
• --strict-probe — 如果探测失败，则初始化失败（未使用 --probe-db 时不执行任何操作）。
• --no-install — 跳过依赖安装和初始合约生成。
• --no-skill — 跳过 Prisma Next skills 安装（适用于隔离网络或受限环境）。技能集群始终安装在项目级别 — 绝不全局安装 — 以确保其版本与项目的 Prisma Next 版本一致。

init 成功运行时会写入：

• 项目根目录下的 prisma-next.config.ts。
• --schema-path 指定的合约源文件 — 如果你传入了规范路径覆盖值，则为 src/prisma/contract.prisma；如果接受了（目前有误的）默认值，则为 prisma/contract.prisma。
• 与合约源文件位于同一目录下的 db.ts。
• prisma-next.md — 人工编写的快速参考文档。
• .env.example（以及在使用 --write-env 时写入 .env）。
• 更新 package.json（依赖和脚本）以及 tsconfig.json（必需的编译器选项）。
• 安装依赖并运行一次 prisma-next contract emit。
• 将 Prisma Next skills 注册到本地 Agent 运行时。

如果你接受了 init 的默认值，结果在项目根目录下生成了 prisma/ 目录（TML-2532），只需移动一次并编辑一处配置即可清理：

mkdir -p src && mv prisma src/prisma
# Then update prisma-next.config.ts so `contract` reads
# 'src/prisma/contract.prisma' (or .ts) instead of 'prisma/contract.prisma'.
pnpm prisma-next contract emit   # re-emits contract.json + contract.d.ts under src/prisma/

请在运行 db init 之前完成此操作 — 写入标记行后，再调整结构会更麻烦。

init 成功后，接下来的路径会汇合到上文的 你的第一个流程 — 连接、写入、读取。init 已经生成了包含 User 和 Post 模型（两者之间有关联）的入门合约，并运行了一次 contract emit；剩下唯一的前置步骤是设置 DATABASE_URL 并初始化数据库。只需运行两条命令：

1. 在 .env 中设置 DATABASE_URL（从 .env.example 复制）。
2. 初始化数据库：pnpm prisma-next db init。使用 init 生成的入门合约创建表、索引和约束，并写入标记行。

然后针对 User 模型运行上文 你的第一个流程 中的代码片段。用户准备扩展合约时 — 添加更多模型、更改字段、添加关联 — 可接着使用 prisma-next-contract。需要更多查询时，可接着使用 prisma-next-queries。

为什么要先从查询入手，而不是先编辑架构。 init 特意附带 User 和 Post：用户不应该为了证明环境配置正常而必须设计架构。扩展合约是完成第一个流程之后的下一步，而不是实现该流程的组成部分。如果用户要求你直接跳到*“添加一个 Comment 模型”* — 当然可以 — 但如果不确定项目连接是否正确，请先针对 User 或 Post 成功执行一次查询。

工作流 — Brownfield-DB（现有数据库，没有契约）

概念：对于没有 PN 契约的现有数据库，contract infer 会遍历实时架构（表、列、索引、约束），并写入描述该架构的 PSL 契约。结果是一个起点，而不是最终契约——请检查并完善，然后运行 db sign，将当前契约哈希记录为标记（而不是让 db init 尝试从头重建架构）。

mkdir my-app && cd my-app
pnpm init
pnpm dlx prisma-next init --yes --target postgres --authoring psl
# scaffold lands; you'll overwrite the starter schema below

然后，在 .env 中设置 DATABASE_URL：

pnpm prisma-next contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

（注意：标志是 --output，不是 --out。运行 prisma-next contract infer --help 可查看完整用法。）

Agent 应在此处暂停并阅读推断出的 PSL。以下情况表明需要重新编写：

• PN 无法分类的表（例如，可表示为关系的旧版关联表）。
• PN 推断类型有误的列（例如，你希望使用 pgvector.Vector(length: 1536) 这类扩展类型，但推断结果是 String）。
• PN 无法识别的 @unique / @index 提示缺失。
• 你希望为字段设置别名。

然后重新生成并签名：

pnpm prisma-next contract emit
pnpm prisma-next db sign
pnpm prisma-next db verify   # confirms the DB matches the contract; reports drift if not

接着运行上文 你的第一个完整流程 — 连接、写入、读取 中的代码片段，用现有表之一替换入门模型。流程相同，只有到达这一步的路径不同。

日常使用的命令

这是一张参考表——不是要对用户照本宣科的脚本。工作流会根据用户下一步的需要，在相应位置介绍命令；这张表适用于用户希望全面了解时（通常在第一次往返操作之后），也可供刚开始了解 Prisma Next 的人快速浏览。如需查看标志级别的详细信息，请运行 <command> --help；帮助输出是权威信息来源。

想要执行的操作	命令	进阶技能
首次将当前契约应用到数据库	prisma-next db init	此技能
编辑契约源文件后重新生成 contract.json + contract.d.ts	prisma-next contract emit	prisma-next-contract
仅用于开发的快速架构同步（不保留迁移历史）	prisma-next db update	prisma-next-migrations
根据契约差异规划迁移	prisma-next migration plan --name <slug>	prisma-next-migrations
应用待处理的迁移	prisma-next migrate	prisma-next-migrations
检查实时数据库	prisma-next db schema	prisma-next-debug
确认数据库与契约匹配（漂移检查）	prisma-next db verify	prisma-next-debug
将现有数据库纳入 PN 契约	prisma-next contract infer --db "$DATABASE_URL"	此技能（brownfield）
解读结构化错误信封	（读取 code / why / fix 字段）	prisma-next-debug
报告错误或请求功能	（通过反馈技能提交）	prisma-next-feedback

决策 — 使用 PSL 还是 TypeScript 编写

• PSL（contract.prisma）——默认选项。简洁、声明式，熟悉 Prisma 的人都能轻松上手。推荐用于大多数项目。
• TypeScript（contract.ts）——程序化构建器。适用于契约确实由程序计算的情况（例如各租户有不同变体的多租户场景）、需要在多个文件间复用契约片段，或扩展需要 PSL 尚未支持的结构（例如 pgvector 的参数化存储类型注册）。配合 prisma-next-build 中的 Vite 插件，可在保存时自动生成。

之后可在同一目录中重新运行 prisma-next init，切换编写方式。初始化流程会检测现有脚手架，并提示是否重新初始化（在非交互式运行中使用 --force 跳过提示）。现有契约内容不会自动转换——你需要手动使用目标语言重新编写。

常见误区

1. 运行 prisma-next init <project-name> 并传入位置参数。 init 会在当前工作目录中运行；它不接受位置参数形式的项目名称。mkdir foo && cd foo && pnpm dlx prisma-next init。
2. 以为 init 会连接数据库。 它只会搭建文件结构、安装依赖（并运行初始的 contract emit）。你需要通过 db init / db update / migrate 进行连接。如果 init 成功但查询失败，问题出在 DATABASE_URL，而不是 init。
3. 把推断出的 PSL 当作最终合约。 contract infer 会生成一个起点。不要在未阅读合约的情况下运行 db sign。
4. 编辑合约后忘记生成产物。 在运行 contract emit 之前，合约产物（contract.json、contract.d.ts）都已过时。如果类型检查器提示某个模型“不存在”，说明你跳过了 emit。
5. 在 prisma-next.config.ts 而不是 .env 中设置 DATABASE_URL。 配置会通过 dotenv/config 自动读取 .env。将 URL 硬编码会泄露凭据，并绕过按环境设置的覆盖项。请参阅 prisma-next-runtime。
6. 手动编辑 contract.json 或 contract.d.ts。 它们是生成的产物；下次运行 contract emit 时，你的更改会被覆盖。请改为编辑源文件。
7. 在 contract infer 中使用 --out。 正确的标志是 --output。

Prisma Next 目前尚不支持的功能

• 从其他 ORM 迁移。 Prisma Next 无法将你的架构从 Drizzle / Prisma 6/7 / Sequelize / TypeORM / Kysely / Knex / 原始驱动迁移过来。解决方法：如果存在适用于你的源的 @prisma-next/migrate-from-<orm>-skill，请安装它；或者将源视为棕地数据库，并从中运行 contract infer。如果你需要内置的引导式迁移流程，请通过 prisma-next-feedback skill 提交功能请求。
• 类似 prisma db push 的生产同步。 db update 是快速开发路径；生产环境请使用迁移（migration plan + migrate）。PN 特意不提供“无需迁移即可推送到生产环境”的操作入口——请参阅 prisma-next-migrations。
• Studio / GUI 数据库浏览器。 使用 prisma-next db schema 查看实时数据库的 CLI 树状摘要。如果你需要交互式界面，请通过 prisma-next-feedback skill 提交功能请求。

参考文件

此 skill 刻意仅包含正文；有关标志的详细信息，请以 prisma-next init --help、contract infer --help 和 db sign --help 为准。如有疑问，请运行 --help 并阅读实际命令的说明，不要根据此 skill 猜测。

检查清单

• 在提出命令之前，确认适用的路径（首次接触导览 / 全新项目 / 既有项目）。
• **首次接触导览：**向用户说明契约路径，并解释其作用（查询类型、迁移和运行时类型的唯一可信来源），然后再提出命令。
• **所有路径：**先完成 你的第一个完整流程 的前置条件（配置、契约源、db.ts、DATABASE_URL、标记行），再编写应用代码。
• **所有路径：**运行第一个完整流程——针对起始模型（或推断出的模型）执行一次 create 和一次 select，并确认往返流程正常运行。
• **所有路径：**在第一个完整流程中，不要编辑契约源。扩展架构是下一步，而不是第一步。
• **所有路径：**不要一开始就介绍功能、罗列能力或背诵 CLI 命令。只在用户当前需要时提供命令。
• 确认用户的目标（postgres / mongodb）和编写模式（psl / typescript）。
• **首次接触导览：**在提出任何建议之前，先查看 prisma-next.config.ts、契约源、db.ts 和 .env——不要假设脚手架工具或队友留下了什么。
• **全新项目路径：**在项目目录中运行 prisma-next init——不要提供位置参数形式的项目名称。
• **所有路径：**项目最终应采用规范布局：src/prisma/contract.{prisma,ts} + src/prisma/db.ts + migrations/app/；如果 init 创建了顶层 prisma/ 目录，还要将脚手架生成的目录移出该位置（TML-2532）。
• **既有项目路径：**运行 contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma，检查结果，然后运行 contract emit + db sign。
• 在 .env 中设置 DATABASE_URL，并确认该值可访问。
• 初始化数据库（全新项目 / 首次接触导览运行 db init；既有项目运行 db sign 签署标记）。
• 不要手动编辑 contract.json 或 contract.d.ts。
• 不要在 prisma-next.config.ts 中设置 DATABASE_URL。
• 确认用户了解其工作流的下一项技能用途（通常先用 prisma-next-queries 执行更多查询，准备扩展架构后再用 prisma-next-contract）。