Communitygithub.com

Adrian7373/semantic-video-pipeline

用於在 Prisma Platform 上託管、部署或操作應用程式:專案、分支、預覽環境、服務及其版本、Prisma Postgres 資料庫、物件儲存儲存桶、環境變數、自訂網域、日誌或 GitHub 整合。觸發詞包含「Prisma Platform」、「Prisma Compute」、「Prisma Postgres」、「Prisma Storage」、「preview environment」、`prisma deploy`、`prisma dev`、`prisma auth`、`prisma project`、`prisma branch`、`prisma service`、`prisma postgres`、`prisma bucket`、`prisma git`、`prisma.config.ts`、promote、rollback。

semantic-video-pipeline 是什麼?

這是一個專門為 Prisma Platform 設計的 AI Agent 技能,其核心目標是提供關於 Prisma 託管、部署與操作的最新且準確的知識。它作為一個內置於 `prisma` 套件中的技能文檔,確保 Agent 的訓練資料與專案實際安裝的 Prisma 版本完全同步,避免了因平台快速迭代而導致的資訊過時。該技能涵蓋了 Prisma Platform 的核心概念,包括 Workspace、Project、Branch 等資源模型,並詳細說明了以 Branch 為基礎的預覽環境機制。技能內容深入解釋了透過 GitHub 整合或 CLI 進行部署的兩種方式,以及 Service、Version、Promote 和 Rollback 等關鍵操作。此外,它也闡述了 Compute Runtime 的運作機制(如服務休眠與喚醒)、Prisma Postgres 資料庫的管理、S3 相容物件儲存,以及一套嚴謹的環境變數解析規則。此技能不僅支援 Claude Code,也適用於其他支援 skills 機制的 AI Agent,開發者可透過 `prisma skills sync` 命令確保其知識始終為最新狀態。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-platform-core-concepts

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Prisma Platform 核心概念

每個分支的隔離基礎架構。

Prisma Platform 迭代快速,你關於它的訓練資料很可能已經過時。此技能內置於已安裝的 prisma 套件中,因此它描述了此專案擁有的確切版本:將它視為你記憶中關於 Prisma 託管的任何資訊的真相來源。如果此檔案 frontmatter 中的 metadata.library_version 與專案已安裝的 prisma 套件不符,請執行 prisma skills sync 並重新讀取。此處所有內容的更完整文件位於 prisma.io/docs;當某個概念需要比此檔案更深入的說明時,請查閱它。

此檔案分享了平台的結構、層級、關係和工作流程。它不是 CLI 參考文件:命令僅在工作流程需要時才會出現。若要了解命令表面,請執行 prisma --help,或針對下面命名的任何群組執行 prisma <group> --help;大多數命令接受 --json 以輸出機器可讀的內容。資料契約、遷移和查詢屬於 prisma-orm-core-concepts 技能;在程式碼中宣告服務和模組屬於 prisma-composer-core-concepts。

技術堆疊

一個 CLI 工具 prisma 作為一系列旨在共同使用的產品的前端:

產品它是什麼概念所在
Prisma ORM (Prisma 8)資料契約、型別查詢、遷移prisma-orm-core-concepts
Prisma Composer應用程式宣告:服務、資料庫、儲存桶、接線prisma-composer-core-concepts
Prisma Compute託管:在您的資料旁執行您的服務此技能
Prisma Postgres受管 PostgreSQL此技能
Prisma StorageS3 相容物件儲存此技能

每個已部署的應用程式都是一個 Composer 應用程式。 您的伺服器程式碼加上一個宣告其服務、資料庫和儲存桶的宣告檔 (module.ts)。該宣告是真相來源:部署會使平台與之收斂,重新部署僅套用差異,從模組中移除資源會在下一次部署時將其從平台中移除。沒有獨立的上線步驟,也不需要手動接線連接字串;Composer 會注入它們。

專案設定

CLI 包含此處命名的每個命令,但應用程式自身的程式碼需要安裝其依賴項。從以下開始:

npm install prisma @prisma/composer @prisma/composer-prisma-cloud

@prisma/composer 是模組宣告匯入的內容;@prisma/composer-prisma-cloud 是 Prisma Cloud 目標,並附帶了 @prisma/orm-postgres。同級技能隨這些套件一起提供 (prisma-composer-core-concepts 在 @prisma/composer 中,prisma-orm-core-concepts 在 @prisma/orm-postgres 中),因此它們在執行此安裝以及 prisma skills sync 之後才會出現,而不是之前。

一個設定檔 prisma.config.ts 用於設定 CLI 及其執行的每個產品。每個頂層金鑰都是一個由一個產品擁有的區段,此 CLI 恰好辨識三個:orm、composer 和 skills。組合後的形狀如下:

import { definePrismaConfig } from "prisma/config";
import { defineConfig as composer } from "@prisma/composer/config";
import { nodeBuild } from "@prisma/composer/node/control";
import {
  prismaCloud,
  prismaState,
} from "@prisma/composer-prisma-cloud/control";
import { defineConfig as orm } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  composer: composer({
    extensions: [prismaCloud(), nodeBuild()],
    state: prismaState(),
  }),
  orm: orm({ contract: "./src/prisma/contract.prisma" }),
  skills: { agents: ["claude"] },
});

dev 和 deploy 僅讀取 composer 區段;其中的內容屬於 prisma-composer-core-concepts。不再讀取單獨的 prisma-composer.config.ts,並且會拒絕舊的設定,絕不會被靜默忽略:當沒有載入的 prisma.config.ts 宣告 composer 區段時,會出現 CONFIG.SECTION_MISSING;當該區段仍有 configPath 時,會出現 CONFIG.FIELD_RETIRED;當 prisma-composer.config.* 與宣告它的 prisma.config.ts 並存時,會出現 CONFIG.FILE_RETIRED。這三個錯誤都在 CLI 的 CLI.CONFIG_SECTION_INVALID 下出現。對於 CONFIG.SECTION_MISSING,請編寫該區段。對於另外兩種情況,請將舊檔案中的 extensions 和 state 移入該區段,然後刪除 configPath 欄位或舊檔案。

資源模型

  1. Workspace:帳戶邊界。成員、帳單和專案位於此處;auth 群組管理您在哪個 Workspace 中操作。
  2. Project:一個產品或程式碼庫。其區域在建立時選擇,之後不可變更;專案中的每個資源都繼承該區域。
  3. Branch:隔離邊界,以 git 分支命名。Branch 就是一個環境:它擁有自己的服務、自己的資料庫、自己的儲存桶以及自己的環境變數覆寫。
  4. 在 Branch 內部:services(HTTP 應用程式,部署為版本)、databases 和 buckets。

一個專案的第一個分支是 production 分支。之後的每個分支都是 preview 分支。Production 和 preview 恰好有兩個不同之處:它們解析的環境變數類別(見下文)以及生命週期(preview 可以被回收並拆除;production 不能)。

CLI 的呼叫會從目錄繫結解析其專案,該繫結在從目錄建立或連結到目錄時建立,並儲存在被 gitignore 的 .prisma/local.json 中。資源命令可以帶有旗標來顯式地定位另一個專案或分支。

分支即預覽環境

沒有單獨的「預覽環境」物件需要建立或設定。分支就是環境,而分支透過部署到它們而產生:

  1. 推送一個 git 分支(透過已連接的 GitHub 整合和儲存庫中的部署工作流程):工作流程會建置和部署,平台會即時建立分支環境。
  2. 從 CLI 部署一個階段:prisma deploy module.ts --stage pr-42 會建立一個名為 pr-42 的分支,並將相同的應用程式圖表部署到其中。階段名稱必須是有效的 git ref 名稱;無效的名稱會導致硬錯誤。

需要資料庫的預覽分支會獲得一個全新、空的資料庫,並以分支範圍的 DATABASE_URL 進行連接。預覽工作永遠無法接觸正式資料,除非您明確地指向它。Schema 來自您已提交的遷移;資料不會從正式環境跟隨過來。

預覽生命週期規則:

  1. 刪除上游 git 分支會拆除整個環境:服務、版本和資料庫,包括它們的資料。
  2. 空閒且未固定的預覽分支可能會被自動回收。固定一個預覽分支可使其免於空閒回收,但不會免於在其 git 分支被刪除時被拆除。
  3. production 分支永遠不會以這種方式被回收或拆除。

兩種部署方式

GitHub(推薦)。 兩個部分,都是必需的:連接到儲存庫的 Prisma GitHub App,以及儲存庫中執行 prisma/cloud-deploy-action 的 GitHub Actions 工作流程。平台不會在建置時推送。工作流程在儲存庫自己的 Actions 中建置,並使用從執行階段的 OIDC token 交換而來的短期憑證進行部署;此連接授權了該交換,並且在其 git 分支被刪除時也會拆除預覽環境。在 Console 中匯入儲存庫會開啟一個新增工作流程的設定 pull request。prisma git connect 僅建立連接,因此從 CLI 連接的儲存庫需要自行新增工作流程。最小的 .github/workflows/prisma-deploy.yml:

name: prisma-deploy
on:
  push:
permissions:
  contents: read
  id-token: write
jobs:
  deploy:
    if: github.ref_type == 'branch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - uses: oven-sh/setup-bun@v2
      - uses: prisma/cloud-deploy-action@v1
        with:
          build-command: npm run build

從那時起,每次推送帶有該工作流程檔案的分支時,都會執行該工作流程;GitHub 從推送的 commit 中讀取工作流程,因此在新增檔案之前建立的分支在包含該檔案之前不會部署任何內容。推送至預設分支會部署 production;推送至任何其他分支會建立或更新該分支的預覽環境,因此每個分支都會自動獲得預覽環境。 開啟 pull request 本身不會部署任何內容;預覽環境追蹤分支推送。一個已連接但沒有工作流程的儲存庫會從平台獲得分支簿記和預覽環境拆除,但不會進行建置。

CLI。 prisma deploy module.ts 直接部署 production;加上 --stage <name> 用於預覽環境。使用 prisma auth login(互動式)進行一次身分驗證,或為 CI 和其他無人值守執行設定 PRISMA_SERVICE_TOKEN(加上當 token 可以看到多個 workspace 時的 PRISMA_WORKSPACE_ID)。首次部署會建立以您的模組命名的專案;該名稱在 workspace 中必須是唯一的,而 --name 會以不同的名稱進行部署。

兩條路徑都會收斂到同一個宣告,因此它們是相互冪等的:一個儲存庫可以連接到 GitHub,並且仍然可以從 CLI 部署。

服務和版本

Service 是分支內一個可透過穩定 URL 存取的 HTTP 應用程式。每次部署服務都會建立一個新的不可變 version;在任何時候,恰好有一個版本在穩定 URL 之後處於活躍狀態。可以單獨檢查、啟動、停止和刪除版本,並且可以讀取或追蹤版本的日誌;service 群組涵蓋了所有這些操作。

版本之間的兩個重要轉換:

  1. Promote 透過使用 production 類別的環境變數重建版本,將其帶入 production。在預覽分支上建立的版本永遠不會將預覽設定帶入 production。
  2. Rollback 將 production 指向先前的版本。在流量切換之前,已停止的目標會被啟動並進行健康檢查,因此 rollback 是零停機時間的。

自訂網域 僅附加到服務的 production 分支。工作流程:新增網域,建立平台報告的 CNAME 記錄,然後等待 DNS 驗證和憑證佈建;因 DNS 缺失而失敗的驗證會在記錄存在後重試。

Compute Runtime

服務運行在 Bun 上,緊鄰它們的 Prisma Postgres 資料庫。無需編寫容器映像,也無需在本地安裝平台模擬器。

執行時期沒有全域的 Temporal(標準的 Node 24 也沒有)。讀取 ORM DateTime 欄位的程式碼可以編譯和部署,然後在第一次讀取時拋出錯誤。可以新增 temporal-polyfill 依賴項並在服務入口點加入 import 'temporal-polyfill/full/global',或者使用 *String 欄位類型,例如 TimestamptzString。

空閒的服務會 休眠:平台在一段短時間不活動後會快照其記憶體,並在下一個請求到來時從快照恢復。請求處理不受影響,但請求生命週期之外的背景工作(setTimeout、setInterval、未等待的 promise)可能會在半途中被中斷。@prisma/compute 套件提供了兩個保持喚醒的基本功能:

  1. waitUntil(promise, { signal }) 使實例保持喚醒,直到 promise 被解決。
  2. using guard = new KeepAwakeGuard({ signal }) 在一個範圍內保持實例喚醒;在 using 不可用的地方,在 finally 區塊中呼叫 .release()。

傳遞 AbortSignal.timeout(ms) 作為成本邊界:訊號會釋放 guard,但不會取消您的工作。不要在服務內部基於 setInterval 構建排程器;休眠會使它們默默變得不穩定。

Prisma Postgres

對您的應用程式來說,Prisma Postgres 資料庫是一個帶有連接字串的常規 PostgreSQL 資料庫:任何用戶端都可以使用,包括 Prisma ORM、psql、Kysely 和 Drizzle。在純 PostgreSQL 之上,每個資料庫都具有內建連接池(無需運行 PgBouncer)、可選的查詢快取和自動備份。

資料庫通常來自部署宣告了資料庫的模組。也可以直接建立它們,在這種情況下,連接 URL 只會列印一次。可以為每個資料庫建立和輪換額外的連接字串;每個秘密在建立時只會顯示一次,之後無法再次讀取。備份是自動的、可列舉和可還原的,並且可以查詢每個資料庫的使用量指標;postgres 群組涵蓋了所有這些操作。

物件儲存

儲存桶是 S3 相容的物件儲存,位於專案內部,可選擇與分支關聯(省略時為專案的預設分支)。儲存桶不能被重新命名。

存取金鑰是具有 read 或 read_write 角色的儲存桶範圍憑證。建立一個金鑰會列印一次存取金鑰 ID、秘密、端點和提供者儲存桶名稱;遺失的秘密會被撤銷並重新建立,永遠無法恢復。bucket 群組管理儲存桶及其金鑰。

在 Compute 上,Bun 內建的 S3 用戶端會從環境中讀取 S3_ENDPOINT、S3_BUCKET、S3_ACCESS_KEY_ID 和 S3_SECRET_ACCESS_KEY,因此在模組中宣告的儲存桶無需用戶端設定。在本地,Composer 宣告的儲存桶會得到一個具有相同 S3 表面的本地替代品;針對它所編寫的程式碼可以在平台上不變地運行。

環境變數

設定有兩個獨立的軸:

軸值意義
類別production, preview哪些分支會解析它:production 類別的值會到達 production 分支,preview 類別的值會到達每個 preview 分支
範圍專案範本, 分支覆寫範本適用於其類別的所有分支;覆寫將值固定到一個命名的 preview 分支

需要注意的規則:

  1. 分支覆寫僅存在於 preview 類別。Production 設定始終是專案範本;沒有任何方法可以為某個 production 部署賦予一個特殊值。
  2. 值是僅寫入的。列出顯示名稱和範圍,永遠不會顯示值,也沒有一個 API 會返回它們。要更改一個值,您必須重新寫入它。
  3. 一個值在寫入時只能有一個類別。若要為 production 和 preview 提供不同的值,請寫入兩個值。
  4. dev 將專案範本解析為 preview 類別,除非一個分支覆寫將其指向 production 類別。這在 Console 中用於預覽環境的「Dev 模式」切換,該切換會為一個分支建立覆寫。

在 Compute 上,環境變數可在服務啟動時供替代使用。在 Composer 的 module.ts 中,使用 ${{ env.SOME_KEY }}。

日誌

每個服務版本會串流其 stdout 和 stderr。日誌可以即時追蹤,並按版本或服務名稱進行時序過濾或搜尋。log 群組涵蓋了所有這些操作,以及為資源刪除、部署和其他平台事件提供的平台日誌。

Prisma ORM 整合

ORM 和託管之間的整合層很薄:Prisma ORM 產生用戶端,僅此而已。資料連接是 Prisma Postgres 的連接字串,Prisma ORM 對 Prisma Postgres 一無所知,反之亦然。將 DATABASE_URL 設定為 ORM 的 datasource 就足夠了;沒有 Prisma ORM 特定的平台功能,考慮到 ORM 是未來的遷移引擎,沒有進一步的整合計劃。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能