prisma-compute

Prisma Compute

引导代理完成 Prisma Compute 应用的创建、部署、运维以及特定框架的部署就绪检查。

Prisma Compute CLI 界面

使用 Prisma Platform CLI 执行 Compute 应用工作流：

bunx @prisma/cli@latest app deploy --help
bunx @prisma/cli@latest app --help
bunx @prisma/cli@latest build logs --help
bunx create-prisma@latest --help

使用 @prisma/cli@latest 部署 Compute 应用。使用 create-prisma@latest 搭建新项目脚手架。

发送反馈和报告 CLI 问题

CLI 内置了反馈通道。当命令崩溃（UNEXPECTED_ERROR）、故障无法通过排查解决，或用户要求向 Prisma 团队发送反馈时使用：

bunx @prisma/cli@latest feedback "app deploy crashed: <第一行错误>"
bunx @prisma/cli@latest feedback "喜欢部署流程" --email you@example.com

崩溃输出会自动指向此处：--json 崩溃信封会在 nextActions 中携带精确的预填充命令作为 recover 条目（直接运行即可），人类可读的崩溃输出末尾会显示 Tell us what happened: 提示。反馈默认匿名，除非传递了 --email，且仅附加 CLI 版本、Node 版本和操作系统平台/架构。消息中切勿包含密钥、连接 URL 或用户数据。

事实来源优先级

在决定编辑或运行什么时，按以下顺序使用证据：

1. 项目生成的脚本和配置，特别是 prisma.compute.ts、compute:deploy、框架配置和 package.json。
2. create-prisma 和 @prisma/cli 的 CLI 帮助输出。
3. 本地安装的包代码、生成的产物和类型定义。
4. 官方文档。

何时应用

在以下场景使用此技能：

• 创建可部署到 Prisma Compute 的新应用
• 将现有 TypeScript 应用部署到 Prisma Compute
• 创建或更新类型化的 prisma.compute.ts 部署配置
• 判断框架是否已为 Compute 就绪
• 调试 create-prisma --deploy、compute:deploy 或 app deploy
• 管理 Compute 应用日志、部署、环境变量和域名，以及列出平台分支（branch list；没有分支创建/删除命令）
• 检查 GitHub/Console 构建日志和 GitHub 推送部署状态
• 使用浏览器认证、多个已存储工作区或 Prisma 服务令牌执行非交互式部署
• 切换、选择、列出或注销 @prisma/cli 的本地 Prisma Platform 工作区
• 使用 @prisma/cli agent install|update|status 安装或更新 Prisma 技能
• 使用 @prisma/cli feedback 发送反馈或报告无法解决的 CLI 故障
• 使用 @prisma/compute-sdk 或 Management API 进行编程式部署

决策树

1. 现有项目部署或重新部署：
   阅读 references/app-deploy-cli.md。

2. 类型化 Compute 配置、monorepo、部署目标、应用根目录或构建/环境默认值：
   阅读 references/compute-config.md。

3. 特定框架的构建/运行时工作：
   阅读 references/frameworks.md。

4. 从脚手架创建新项目：
   阅读 references/create-prisma.md。

5. 编程式部署、SDK、API 或底层应用/部署概念：
   阅读 references/sdk-api.md。

6. 构建、认证、环境、部署或运行时故障：
   阅读 references/troubleshooting.md。

按优先级排序的规则

优先级	类别	影响	前缀
1	命令验证	严重	verify-
2	认证和工作区选择	严重	auth-
3	框架就绪	严重	framework-
4	运行时主机和端口绑定	严重	runtime-
5	类型化 Compute 配置	高	config-
6	分支、环境和数据库连接	高	env-
7	部署操作	高	deploy-
8	SDK 和 API 自动化	中	sdk-

快速规则

1. 命令验证

• verify-help-first - 工作时使用 CLI 帮助输出确认命令语法。
• verify-prisma-vs-platform-cli - 不要假设 ORM CLI 中存在 prisma app deploy；检查任务是否应使用 @prisma/cli。
• verify-generated-scripts - 当项目已有生成的 compute:deploy 脚本时，优先使用它。
• verify-public-url - 实际部署后，请求公共部署 URL，而不是信任本地或仅就绪检查。
• verify-config-support - 将 prisma.compute.ts 视为类型化 Compute 配置；在编辑或部署前检查项目的配置和生成的脚本。
• verify-auth-workspace-support - 使用 @prisma/cli auth workspace 命令进行本地工作区列表/使用/注销流程。

2. 认证和工作区选择

• auth-source-precedence - 非空的 PRISMA_SERVICE_TOKEN 是命令的活动认证源，本地 OAuth 工作区在执行时被忽略。如果设置了但为空，CLI 应失败而不是回退到存储的 OAuth。
• auth-multi-workspace - auth login 可以在同一台机器上存储多个工作区的 OAuth 会话。活动工作区指针选择普通命令使用哪个存储的 OAuth 授权。
• auth-list-before-switch - 使用 auth workspace list --json 检查本地会话。代理应优先使用 JSON 中的工作区 ID 而不是名称，因为名称可能不明确。
• auth-switch-explicitly - 使用 auth workspace use <id-or-name> 进行非交互式切换。仅当交互式选择器或恰好存在一个本地 OAuth 工作区时，才使用不带参数的 auth workspace use。
• auth-no-fallthrough - 如果活动 OAuth 工作区已注销或刷新失败，CLI 不应静默回退到其他缓存的工作区。运行 auth workspace use <id> 选择下一个工作区。
• auth-single-workspace-logout - 使用 auth workspace logout <id-or-name> 或 auth logout --workspace <id-or-name> 移除一个本地 OAuth 工作区会话。纯 auth logout 清除所有本地 OAuth 工作区会话。
• auth-service-token-switching - 当设置了 PRISMA_SERVICE_TOKEN 时，auth workspace use 不可用，因为服务令牌是活动认证源；取消设置环境变量以切换本地 OAuth 工作区。工作区注销仍然只清理本地 OAuth 状态。
• auth-storage-awareness - 本地 OAuth 凭据存储在平台认证文件中，工作区元数据存储在 sidecar 上下文文件中。项目固定信息存储在 .prisma/local.json 中，CLI 应用/项目状态存储在 prisma.compute.ts 附近的 .prisma/cli/state.json 中（如果存在）。

3. 框架就绪

• framework-cli-first - 根据 @prisma/cli app deploy 评估部署就绪状态，而不是根据 create-prisma 能搭建什么。
• framework-supported-cli-deploy - Compute 部署支持 nextjs、nuxt、astro、hono、nestjs、tanstack-start、custom 和 bun。
• framework-create-prisma-defaults-only - create-prisma 可以提供生成的默认值和 compute:deploy，但它不是现有应用的通用部署界面。
• framework-build-output - Compute 需要服务器入口点或框架产物，而不仅仅是静态输出。

4. 运行时主机和端口绑定

• runtime-bind-all-interfaces - 部署的服务器必须绑定所有接口（0.0.0.0 或框架等效项），而不是硬编码的 localhost 或 127.0.0.1。
• runtime-match-http-port - 应用必须在部署的 HTTP 端口上监听：尽可能读取 process.env.PORT，或传递匹配的 --http-port。
• runtime-readiness-port-only - Compute 就绪检查监听端口；仅回环的监听器可能看起来就绪，但公共入口无法到达。

5. 类型化 Compute 配置

• config-optional-simple-app - 部署普通的单个应用不需要 prisma.compute.ts；当没有持久配置时使用标志。
• config-init-formalizer - 使用 bunx @prisma/cli@latest init 生成新配置：它会检测框架，固定名称/框架/httpPort（以及 Bun/Hono 的入口），并提供项目链接。--format json 写入无依赖的 prisma.compute.json。init 在配置已存在时拒绝，从不搭建代码，也从不部署。
• config-use-prisma-compute-ts - 将可重用的部署默认值放在 prisma.compute.ts 中（使用 defineComputeConfig），而不是 prisma.config.ts。
• config-app-vs-apps - 对于单个部署目标使用 app，对于 monorepo 或多应用仓库使用 apps；只能定义一个。
• config-monorepo-roots - 对于 monorepo，使用 prisma.compute.ts 声明应用目标、根目录、框架默认值、入口点、端口和环境输入。
• config-targets - 在多应用配置中，@prisma/cli app deploy web 选择 apps.web 目标。如果没有 [app]，命令可以从当前目录推断目标；否则 deploy 可以运行所有目标，而 build/run 需要一个目标。
• config-region-new-app-only - 配置中的 region 仅是新创建应用的默认值；部署到现有应用会保留应用当前区域。
• config-custom-artifact - 对于预构建或自定义构建的产物，使用 framework: "custom" 配合 build.outputDirectory 和 build.entrypoint。
• config-no-project-branch-secrets - 不要在 prisma.compute.ts 中提交工作区、项目、分支、生产意图、服务令牌或密钥值；将这些放在标志、.prisma/local.json、环境存储或 CI 密钥中。应用级默认值如 region、root、framework、entry、httpPort 和非密钥环境文件路径属于配置。
• config-flags-win - 显式部署标志如 --framework、--entry、--http-port、--region 和 --env 会覆盖匹配的配置值。

6. 分支、环境和数据库

• env-do-not-leak-secrets - 切勿打印完整的 DATABASE_URL、服务令牌或密钥值。
• env-deploy-loads-dotenv - 生成的部署脚本可能通过 prisma.compute.ts 或 --env .env 加载环境变量；重新部署前检查实际脚本/配置。
• env-migrations-separate - 重新部署脚本不运行迁移或种子数据。单独运行适当的 Prisma 数据库脚本。
• env-cli-token-name - @prisma/cli 使用 PRISMA_SERVICE_TOKEN 进行服务令牌认证。
• env-branch-scope - 分支部署、分支环境变量和分支数据库必须使用相同的分支名称；当目标是预览分支时，显式传递 --branch <git-name>。
• env-production-vs-preview - 生产环境使用 --role production，预览模板环境使用 --role preview，分支特定覆盖使用 --branch <git-name>。
• env-db-explicit - 通过数据库和项目环境命令显式连接数据库和环境；部署示例不应添加数据库设置，部署不会自动运行迁移、种子数据或为每个应用创建数据库。

7. 部署操作

• deploy-prod-intent - 仅当用户意图进行生产部署时使用 --prod --yes。应用的首次生产部署无需 --prod 即可自动提升；该标志用于后续生产分支部署。
• deploy-no-promote - 使用 app deploy --no-promote 进行构建后验证：它会构建一个候选版本，可通过其自己的 URL 访问，而不影响实时部署，稍后使用 app promote <deployment-id> 提升。
• deploy-github-default-branch - 当 Compute 应用连接到 GitHub 推送部署时，合并到默认分支是生产部署路径；检查部署记录或 GitHub 检查运行，而不是告诉用户重新部署已合并的 PR 分支或运行默认分支预览部署。
• deploy-build-logs - 使用 @prisma/cli build logs <build-id> 获取 GitHub/Console 构建输出。使用 app logs 获取运行时部署日志；两个 ID 不同。
• deploy-noninteractive-auth - 非交互式部署需要正确的活动存储 OAuth 工作区或受支持的服务令牌环境变量；切勿打印令牌。
• deploy-json-for-agents - 对于脚本和代理可读输出，使用 --json --no-interactive。
• deploy-create-project - 仅当用户希望部署创建并链接新项目时使用 --create-project <name>；它与 --project 和 PRISMA_PROJECT_ID 冲突。
• deploy-ops-targets - 应用 show/open/logs/list-deploys/promote/rollback/remove 和域名命令也可以接受来自 prisma.compute.ts 的 [app] 目标。
• deploy-report-cli-bugs - 遇到 UNEXPECTED_ERROR 或无法解决的故障时，使用反馈命令报告；参见上面的“发送反馈和报告 CLI 问题”。

8. SDK 和 API

• sdk-use-cli-first - 应用工作流优先使用 @prisma/cli app deploy；仅当用户构建底层自动化时，才使用 create-prisma 搭建新应用。
• sdk-result-handling - @prisma/compute-sdk 返回 Result 值；检查 isOk()/isErr() 而不是依赖异常。

推荐工作流

1. 检查项目：包管理器、模板/框架、package.json 脚本、Prisma 版本、Prisma 客户端位置、prisma.compute.ts 和现有的 compute:deploy。
2. 验证实际使用的包的 CLI 帮助输出。
3. 在项目/应用变更前验证认证上下文：auth whoami --json，当可能存在多个本地会话时，使用 auth workspace list --json。
4. 选择路径：
   • 现有应用部署：使用配置支持的目标（如果存在）、生成的 compute:deploy 或 @prisma/cli app build/run/deploy 标志
   • 新应用脚手架：create-prisma，然后使用生成的 compute:deploy 或 @prisma/cli app deploy
   • 底层自动化：@prisma/compute-sdk 或 Management API
5. 检查框架就绪状态以及主机/端口/环境/运行时要求，包括项目和分支范围。
6. 在可行时先运行本地构建或 app build。
7. 自动化时使用 JSON 输出部署，然后请求公共 URL 并总结应用 URL、应用 ID、部署 ID、项目 ID、工作区 ID 和后续步骤。
8. 对于 GitHub/Console 构建，在猜测构建失败原因之前，检查 Prisma Compute Deploy 检查运行或 build logs <build-id>。

避免

• 不要将 Compute 部署指南埋藏在通用的 prisma-cli 技能中。
• 不要仅仅为了部署而在现有应用内运行 create-prisma；使用生成的 compute:deploy 脚本或 @prisma/cli app deploy。
• 不要告诉用户每个 create-prisma 模板都可以自动部署。
• 不要使用占位符 DATABASE_URL 值进行部署。
• 不要假设 next start 是 Compute 运行时路径；Next.js 部署需要 standalone 输出。