如何组织 5 个 App 的 pnpm Monorepo?TapCanvas Web、API 与 Agents 工程实践全解

原创2026-11-02 19:36:261,646 阅读
文章标签:人工智能AI 应用AI Agent前端媒体生成后端多模态工作流自动化LLM 网关音视频DeepSeek

如何组织 5 个 App 的 pnpm Monorepo?TapCanvas Web、API 与 Agents 工程实践全解

TapCanvas 是面向 AI 影视、漫剧与多模态内容生产的 Agent 原生无限画布。它用一个 pnpm Monorepo 同时管理 Web 前端、API 后端、Agents 命令行和模型网关等多个应用,本文带你拆解这套 Monorepo 工程实践:目录如何划分、workspace 边界如何划定、前后端共享契约如何复用,以及一条命令启动全栈的技巧。

TapCanvas 高层架构图:画布、Agents 与工作流内核协作

一、先盘点: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

TapCanvas 无限画布界面:章节、资产与分镜节点

这套职责边界在 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/*/*

这里有两个值得学习的点:

  1. 用排除式 glob 处理"异类":!apps/director-desk 把一个自带 npm 锁文件的独立子项目排除出 workspace,避免两套锁文件互相污染;
  2. 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 之间的代码风格保持了一致。

TapCanvas 创作流水线视图:角色与场景资产阶段

五、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 的这份工程实践。

登录后查看全文
TapCanvas