如何组织 5 个 App 的 pnpm Monorepo?TapCanvas Web、API 与 Agents 工程实践全解
如何组织 5 个 App 的 pnpm Monorepo?TapCanvas Web、API 与 Agents 工程实践全解
TapCanvas 是面向 AI 影视、漫剧与多模态内容生产的 Agent 原生无限画布。它用一个 pnpm Monorepo 同时管理 Web 前端、API 后端、Agents 命令行和模型网关等多个应用,本文带你拆解这套 Monorepo 工程实践:目录如何划分、workspace 边界如何划定、前后端共享契约如何复用,以及一条命令启动全栈的技巧。
一、先盘点:5 个 App 各管一摊
TapCanvas 的 apps/ 目录下共有 5 个主应用(外加一个独立子项目),每个 App 职责清晰、互不越界:
| 目录 | 名称 | 技术栈 | 职责 |
|---|---|---|---|
| apps/web/ | @tapcanvas/web |
React + Vite | 无限画布、流水线视图、画布执行 |
| apps/hono-api/ | @tapcanvas/api |
Hono + NestJS + Prisma | 协议、权限、任务账本与交付证据 |
| apps/agents-cli/ | agents |
TypeScript CLI | DeepSeek Harness 的 TapCanvas Bridge |
| apps/new-api/ | new-api |
Go(Gin) | 多模型网关:渠道接入、计量与模型下发 |
| apps/media-worker/ | media-worker |
Go + gRPC | 媒体合成与转码 Worker |
这套职责边界在 README.md 中有一句话总结:apps/web 负责交互与确定性画布执行,apps/hono-api 负责协议、权限、任务与事实证据,apps/agents-cli 是 Agents Bridge,apps/new-api 负责模型网关。
二、一个 pnpm-workspace.yaml 划定 Monorepo 边界
Monorepo 的"根"就是这两个文件:
- pnpm-workspace.yaml:用 4 行 glob 定义了所有参与 pnpm 管理的包
- package.json:根包
tapcanvas-workspace,声明packageManager: pnpm@10.8.1并统一入口脚本
workspace 声明非常精炼:
packages:
- apps/*
- "!apps/director-desk"
- packages/*
- packages/*/*
这里有两个值得学习的点:
- 用排除式 glob 处理"异类":
!apps/director-desk把一个自带 npm 锁文件的独立子项目排除出 workspace,避免两套锁文件互相污染; packages/*/*二级通配:TapCanvas 把共享契约拆成 packages/schemas/ 下的几十个细粒度小包(如shot-table-protocol、storyboard-director-protocol),二级 glob 让它们全部自动纳入,新增契约包无需改配置。
三、根 package.json:全栈命令的"控制面板"
根 package.json 里几乎不放实现,只放透传脚本,用 pnpm --filter 精确指定目标 App:
pnpm dev:web # pnpm --filter @tapcanvas/web dev
pnpm build:api # pnpm --filter @tapcanvas/api build
pnpm test:agents # pnpm --filter agents test
pnpm build、pnpm test 则会串联执行 Web、API、Agents 三个包的全量构建与测试。开发者只需要记住根目录的短命令,具体执行交给 filter,这是 pnpm Monorepo 最推荐的做法——命令收敛在根,依赖留在各包。
另外注意根 dependencies 里只共享了一个 zod:共享依赖要克制,能不共享就不共享,避免"一个包升版、全站重建"。
四、TypeScript 三兄弟如何互通:共享契约 + 严格基线
Web、API、Agents 都是 TypeScript,但 TapCanvas 没有让它们互相 import 源码,而是走"契约包"路线:
- 共享契约集中在 packages/schemas/:约 40 个协议包,分别定义画布节点、分镜、镜头表、工作流内核等前后端共享的数据结构;
- 通过 tsconfig paths 精确映射:apps/web/tsconfig.json 和 apps/hono-api/tsconfig.json 都把
@tapcanvas/shot-table-protocol等别名直接指向../../packages/schemas/...的具体入口文件,编译期即校验,不产生运行时依赖; - 统一编译基线:tsconfig.base.json 全局开启
strict: true,各 App 继承,杜绝"前端松、后端严"的双标类型。
配合仓库级 AGENTS.md 中"禁止 any、禁止隐式回退、统一与简洁优先"的强约束,多 App 之间的代码风格保持了一致。
五、Go 服务如何放进 pnpm Monorepo?
new-api(Go,见 apps/new-api/go.mod)和 media-worker(Go + gRPC)没有 package.json,天然不在 pnpm workspace 内,而是靠目录约定"同居":
- 各自维护独立的
go.mod依赖与 Dockerfile; - 统一纳入根目录 docker-compose.yml 编排,和 Web/API 一起起停;
- 构建走 scripts/dev.sh:首次 Docker 启动会逐个构建
new-api → agents-bridge → api → web → media-worker五个镜像——脚本注释里写明了原因:冷构建并发会撑爆 8 GiB 的 Docker VM,串行构建更稳。
💡 实践要点:Monorepo 不等于"同一个包管理器"。不同语言的技术栈用目录 + CI/编排层做统一,比强行塞进同一 workspace 更简单。
六、为什么 director-desk 被排除在 workspace 外?
apps/director-desk/ 是一个独立的三维导演台子项目(自带 npm 锁文件与独立依赖版本),被 !apps/director-desk 显式排除。它的构建不依赖主 workspace,而是由 Web 的 predev/prebuild 钩子通过 build-director-desk.mjs 触发(见 apps/web/package.json)。
这体现了一个务实原则:外部引入、许可独立的子项目,用"黑盒集成"而非"深度合并",版本升级、依赖锁定互不干扰。
七、一条命令跑全栈:本地开发体验
TapCanvas 把多 App 联调的复杂度全部收进了 scripts/dev.sh:
# 本地模式:同时拉起 API 与 Web,HMR 最快
./scripts/dev.sh local --install
# Docker 模式:生成一次性随机密钥 → 逐个构建镜像 → compose up
./scripts/dev.sh docker
Docker 模式下脚本还会自动完成:识别 docker compose 或 docker-compose、生成并校验强随机密钥(写入被 Git 排除的私有 .env,永不打印)、构建完成后输出统一入口 Web http://localhost:5175 / API :8788 / 模型网关 :4455。停止服务则用 ./scripts/dev.sh docker-down,数据卷保留。
八、最佳实践速览
| 实践 | 出处 | 收益 |
|---|---|---|
| 4 行 glob + 排除式声明 workspace | pnpm-workspace.yaml | 新增包零配置,异类不污染 |
根脚本只做 --filter 透传 |
package.json | 命令收敛,依赖自治 |
| 契约独立成包 + tsconfig paths | packages/schemas/ | 前后端类型编译期对齐 |
| 不同语言服务靠目录 + 编排层统一 | docker-compose.yml | Go 与 Node 各管各的 |
| 一键启动脚本封装密钥与构建顺序 | scripts/dev.sh | 新人 3 分钟跑起全栈 |
这套 pnpm Monorepo 组织方式的核心思路可以总结为三句话:目录即边界,契约即协作,脚本即入口。当你需要同时管理前端、后端、CLI 甚至 Go 服务时,不妨直接参考 TapCanvas 的这份工程实践。


