架构总览
权威源：仓库
CLAUDE.md §1 / §5与docs/architecture.md。本页做导览。
仓库结构（pnpm workspace）
| 包 | 职责 |
|---|---|
apps/web | React 18 + Vite + Zustand + Tailwind + Radix 前端（@reelchair/web） |
apps/backend | Fastify REST API，部署在 Cloud Run，本地监听 3001（@reelchair/backend-app） |
firebase/functions | Cloud Functions 主代码库（Wave 11 后仅保留触发器 / 定时任务） |
firebase-plugins/functions | 插件专用 Cloud Functions，独立 firebase.json 与 emulator 端口 |
packages/core | 共享 TypeScript 类型 + Node Editor 类型 |
packages/shared | 共享工具（TS 源码直引，不构建） |
packages/plugin-sdk | 第三方插件接口契约 + 脚手架 |
packages/schema-registry | Schema 注册表 |
CI 构建顺序：core → schema-registry → web → backend-app。
前端 API-only（最重要的约束）
Firestore 是私有数据库。Cloud Functions / Fastify 才是公共 API。前端是 API 客户端，不是数据库客户端。
硬性规则（由 ESLint + scripts/check-api-only.sh 强制）：
- 前端不得直接写 Firestore（
setDoc/addDoc/updateDoc/deleteDoc）。 - 前端不得新增 Firestore 读查询；读操作走 REST API。
- 所有数据操作只能从
apps/web/src/data/导入，请求统一经data/client.ts（挂 Firebase ID Token，拆解{ ok, data }envelope）。 - 仅有的实时订阅白名单：entityNodes 侧边栏、frames 列表、agent 事件流。
需要「直接访问 Firestore」时，正确做法是提议新增 REST endpoint，而非绕过规则。
REST 后端 /api/v1/*（Wave 11）
apps/backend/src/server.ts 注册 src/routes/*.ts 下全部路由（projects、sequences/scenes、entityNodes、canvas、assets、ai、agent 等）。横切中间件：auth、idempotency、envelope，输出 { ok, data } 或 { ok:false, code, message }。
Cloud Functions 现仅保留触发器 / 定时器：Storage 触发（assets）、Firestore 触发（canvas、aiTasks）、Scheduler（pollVideoTasks）。新增服务端逻辑默认放进 Fastify REST API。
领域语义链
Project → Episode → Storyboard → Frame → Shot → Asset → Timeline → Export
Asset是统一媒体资源；资源真值是(storageProvider, storageKey)，不是uri。Timeline只消费Asset：生产链是 Shot → Asset → Timeline。- 序列实体用稀疏排序（10, 20, 30…）减少插入重排。
- 子实体的
projectId/episodeId是关系真值；父实体上的frameIds等是缓存字段。
内部命名是 Episode/Frame，user-facing 全部映射到 Sequence/Scene，见命名约定。
Agent 运行时（统一架构）
单例入口 apps/backend/src/agent/instance.ts（initAgent()），装配 SkillRegistry + ToolRegistry + 统一 ReAct loop + MemoryStore/ConversationStore。
- ReAct loop：绝大多数 skill（LLM 自由调度 tools）。
- LangGraph workflow：少数需确定性多阶段编排的 skill（如 sequence 合并、scene 实体规划），用
firestoreCheckpointer持久化，支持resume/interrupt。
Skill 采 folder-per-skill：agent/skills/<name>/ 下放 manifest.json + SKILL.md，新增 skill 无需改代码。
main 上的 V1/V2/V3 Agent 三套并存、单文件巨型 configCache 等，均为已废弃写法。请按 dev/pro 的统一架构认知，不要以 main 为锚点。
📝 后续将从
docs/canvas-architecture.md、docs/aiAssistant/、docs/aiGateway/迁移深度细节。