SuperAPI AI 工具集

backend-building-swarm

编程与开发

查看项目

更新于 11-06 17:19

技能介绍

用途

该技能用于在已有 webapp-building-swarm 生成的前端项目上追加后端能力,采用在 worktree 中原位嫁接的方式,不替换或修改前端文件。它基于 swarm-workspace 的两层文件系统契约(共享协调仓库加每个子代理的 worktree)。

前置条件是存在由 webapp-building-swarm 创建的共享仓库,默认路径为 /mnt/agents/output/app。

主要能力

基础能力(Hono 服务、tRPC、contracts)在首次运行 --features 时自动安装。特性可增量安装:

  • db:Drizzle ORM + MySQL,新增 db/、api/queries/connection.ts、drizzle.config.ts,并提供 DATABASE_URL 环境变量与 db/seed.ts 种子脚本。
  • auth:Kimi OAuth + 用户管理,新增 api/kimi/、认证路由,以及 Login 页面、useAuth、AuthLayout、TRPCProvider 等客户端补丁,并自动把 Login/NotFound 路由接入 App.tsx。依赖 db,会自动包含。

不带 --features 时默认安装 auth(即 db + auth)。

使用方式

初始化脚本位于 /app/.agents/skills/backend-building-swarm/scripts/init.sh,需在由 swarm-workspace 的 setup-local.sh 创建的后端 worktree 中运行:

PROJECT_PATH=$HOME/app-backend bash /app/.agents/skills/backend-building-swarm/scripts/init.sh "<app-title>" [--features db,auth | --template]

脚本在当前分支提交,不创建 worktree、不执行合并。重入安全:.backend-features.json 清单控制重复运行,后续添加 --features auth 只安装增量部分。由嫁接管理的认证 UI 每次都会重新植入,而 schema.ts、seed.ts、connection.ts、drizzle.config.ts 等可由用户扩展的文件不会覆盖已有内容。

执行路径分两种,--features 与 --template 互斥:

  • --features db,auth(默认):适用于 frontend-only 模板,执行完整嫁接,包括复制 api/contracts/db、改写 vite/tsconfig、自动接入 main.tsx/App.tsx、portal 调用与提交。
  • --template:适用于已自带 .backend-features.json 与预置目录的 fullstack 模板,只做 portal 调用、写入 .env、npm install 与提交。项目内存在 .backend-features.json 时会自动选用该模式。

worktree 创建示例(由子代理执行):

NODE_MODULES_SRC=/app/.agents/skills/backend-building-swarm/scripts/template/node_modules bash /app/.agents/skills/swarm-workspace/scripts/setup-local.sh <branch> $HOME/app-<branch>

每个子代理必须使用唯一本地路径,避免 worktree 元数据冲突。不要运行 git worktree prune。

.prepare-template.sh 仅用于镜像构建期,生成 scripts/template/node_modules/。

工作流与常用命令

整体顺序由 vibecoding-webapp-swarm 负责,后端嫁接是其阶段之一:先初始化前端,再创建后端 worktree 并运行 init.sh,由主代理把 backend 分支合并进集成线,使页面代理继承 tRPC 客户端与 contracts。增量特性可通过重新运行 init.sh 并指定 --features 完成。

常用命令包括 npm run dev(开发服务器,端口 3000)、npm run build、npm start、npm run check、npm run format、npm run test,以及 db 特性下的 npm run db:push、db:generate、db:migrate。命令应在 worktree($HOME/app-<branch>)中运行,而不是在共享协调仓库中运行。

适用场景与限制

适用于在 swarm 协作流程中为前端应用补充类型安全 API、数据库与 OAuth 登录。限制与注意事项:不要直接在共享仓库运行 init.sh 或 npm 安装/构建;忘记合并 backend 分支会导致页面代理缺失 tRPC 客户端;数据库实体类型应使用 typeof table.$inferSelect,不要手写接口;不要写原生 SQL;不要修改 api/lib/、api/kimi/ 及认证客户端文件;不要创建注册页(OAuth 首次登录自动建用户);不要修改 .env 与初始化生成的框架文件;不要更改默认端口 3000;不要使用 db:push --force,也不要用删表方式修复迁移失败。