SKILL.md
只读
名称
cmux-backend
描述
cmux 的后端 TypeScript 与云端虚拟机（Cloud VM）开发规范。适用于修改 web/app/api、web/services、后端脚本、云端 VM 生命周期、云厂商集成、Postgres、Stack Auth 付费门槛限制、数据库迁移（migrations）以及云厂商镜像构建脚本等场景。
cmux 后端
核心规范
- 位于
web/app/api/**、web/services/**路径下，以及涉及云厂商、数据库、身份验证、限流、重试、超时或遥测的后端脚本，后端 TypeScript 代码默认优先使用 Effect。 - 保持 Next 路由处理函数（route handlers）尽可能轻量：仅做请求解析，在边界处运行单个 Effect 程序，将类型化错误映射为 HTTP 响应，未预期的缺陷（defects）单独处理。
- 纯 TypeScript 仅适用于简单的数据结构、常量、配置文件、前端 React 代码，以及引入 Effect 只会增加繁琐仪式感而无法改善错误处理的轻量胶水代码。
- 云端虚拟机（Cloud VM）后端逻辑保留在 Vercel 路由处理函数和基于 Postgres 的 Effect 服务中。除非后续架构文档明确变更控制面，否则请勿重新引入 Rivet 或裸 Actor 协议。
- Postgres 是 VM 生命周期、活跃 VM 配额限制、幂等性及用量事件的唯一事实来源（source of truth）。
- 生产与预发环境的 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执行；切勿在 Vercel 构建或路由启动阶段触发迁移。本地开发环境继续保留由bun dev中根据CMUX_PORT派生的 Docker Postgres 链路。 - 启用后，创建 Cloud VM 的付费门槛卡点将使用 Stack Auth 的 Team 支付项（team payment items）。
密钥与凭据（Secrets）
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 环境变量，不包含云厂商构建密钥。如果存在 ~/.secrets/cmux.env，bun dev 会先加载它，然后再加载 ~/.secrets/cmuxterm-dev.env，因此针对 cmuxterm 的特定 Stack 设置会覆盖全局 cmux 密钥。在机器迁移过渡期，Web 开发加载器仍兼容旧版 ~/.secret/cmuxterm.env 和 ~/.secrets/cmuxterm.env 路径。
详细参考文档
- references/effect-boundaries.md：路由处理函数、服务、类型化错误、重试机制、依赖注入。
- references/cloud-vm-control-plane.md：VM 生命周期、数据库迁移、Postgres、云厂商幂等性、付费门槛卡点。
