SKILL.md
唯讀
名稱
cmux-backend
描述
cmux 的後端 TypeScript 與雲端 VM 開發規範。適用於修改 web/app/api、web/services、後端腳本、Cloud VM 生命週期、服務商整合、Postgres、Stack Auth 計費門禁、資料庫遷移或服務商映像檔建置腳本等場景。
cmux 後端
核心規範
- 在
web/app/api/**、web/services/**以及涉及服務商、資料庫、身份驗證、速率限制、重試、逾時或遙測（telemetry）的後端腳本中，後端 TypeScript 預設使用 Effect。 - 保持 Next route handler 輕量：僅進行請求解析，在邊界處執行單一 Effect 程序，將型別化錯誤（typed errors）映射至 HTTP 回應，並單獨處理未預期的缺陷（defects）。
- 原生 TypeScript 僅用於簡單的資料結構、常數、設定檔、前端 React，以及缺乏 Effect 也無損錯誤處理機制的輕量銜接程式碼。
- Cloud VM 後端邏輯應保留在 Vercel route handlers 以及由 Postgres 支援的 Effect 服務中。除非後續的架構文件明確調整控制面（control plane），否則請勿重新引入 Rivet 或原始 actor 協定。
- Postgres 是 VM 生命週期、活躍 VM 配額限制、冪等性（idempotency）以及使用率事件的唯一真實來源（source of truth）。
- 生產環境與 Staging 環境的 Cloud VM Postgres 採用 Vercel Marketplace AWS Aurora PostgreSQL OIDC/RDS IAM 路徑，執行階段環境變數包含
CMUX_DB_DRIVER=aws-rds-iam、AWS_ROLE_ARN、AWS_REGION、PGHOST、PGPORT、PGUSER、PGDATABASE。 - 請透過
bun db:migrate:aws-rds-iam執行生產/Staging 環境的資料庫遷移；切勿在 Vercel 建置（build）或路由啟動時執行。本機開發環境則保留由bun dev觸發、基於CMUX_PORT的 Docker Postgres 路徑。 - 啟用時，Cloud VM 的建立計費門禁會採用 Stack Auth 團隊付款項目。
密鑰設定
Cloud VM 的建置、測試及本機開發腳本會從 ~/.secrets/cmux.env 讀取服務商密鑰：E2B_API_KEY、FREESTYLE_API_KEY，以及 web/scripts/build-cloud-vm-images.ts 在建立 Freestyle 快照時所需的 R2 上傳變數。
set -a
source ~/.secrets/cmux.env
set +a
~/.secrets/cmuxterm-dev.env 存放本機 Stack/web 環境變數，不包含服務商建置金鑰。bun dev 會優先載入 ~/.secrets/cmux.env（若存在），接著再載入 ~/.secrets/cmuxterm-dev.env，因此 cmuxterm 特定的 Stack 設定會覆蓋更廣泛的 cmux 密鑰。在機器遷移期間，Web 開發載入器仍支援舊版路徑 ~/.secret/cmuxterm.env 與 ~/.secrets/cmuxterm.env。
詳細參考文件
- references/effect-boundaries.md: route handlers、services、型別化錯誤、重試、相依性注入（dependency injection）。
- references/cloud-vm-control-plane.md: VM 生命週期、資料庫遷移、Postgres、服務商冪等性、計費門禁。
