代码仓库与项目目录规划

1. 仓库策略结论

平台采用多仓架构。前端、业务 API、异步任务、渲染、MCP、共享契约和基础设施分别维护，设计文档独立成仓。

选择多仓的原因：

• 各服务部署形态、扩容方式和发布周期不同；
• Render Worker 依赖 FFmpeg/Remotion，运行资源与普通服务不同；
• MCP 需要独立暴露和管理安全边界；
• Worker 需要按模型供应商和任务类型横向扩容；
• 共享协议通过 contracts 仓库统一维护，避免隐式耦合；
• 适配现有 GitLab 群组内多仓管理方式。

2. GitLab 群组

https://gitlab.ibox.art/ibox-era-sail/feishu-apps/narra-cine

3. 仓库清单

仓库	职责	主要技术
narra-cine-prototypes-doc	产品设计、架构、原型、接口与决策文档	Markdown、设计文件
narra-cine-web	用户端和管理端前端	Next.js、Tailwind CSS、shadcn/ui、Motion、Tiptap、React Flow
narra-cine-server	核心业务 API、认证、租户、项目和生产域	NestJS、PostgreSQL、Prisma、Redis
narra-cine-worker	Conductor Worker、模型调用、质检和异步任务	Node.js、TypeScript、Conductor
narra-cine-render	时间线渲染、转码、混音、字幕和媒体质检	Remotion、FFmpeg、FFprobe
narra-cine-mcp	面向 Agent 的 MCP Server	TypeScript、MCP SDK
narra-cine-contracts	API DTO、领域事件、工作流任务、TimelineSpec 和 MCP 契约	TypeScript、JSON Schema、Zod
narra-cine-infra	Docker、Conductor、Kubernetes、监控和 IaC	Docker Compose、Kubernetes、Terraform

4. 本地工作区

/Users/xhwx/work/coder/narra-cine/
├── narra-cine-prototypes-doc/
├── narra-cine-web/
├── narra-cine-server/
├── narra-cine-worker/
├── narra-cine-render/
├── narra-cine-mcp/
├── narra-cine-contracts/
└── narra-cine-infra/

每个目录对应一个独立 Git 仓库。

5. 仓库依赖关系

narra-cine-web ───────────┐
narra-cine-server ────────┼──> narra-cine-contracts
narra-cine-worker ────────┤
narra-cine-render ────────┤
narra-cine-mcp ───────────┘

narra-cine-server ────────> PostgreSQL / Redis / OSS / Conductor
narra-cine-worker ────────> Conductor / OSS / 火山引擎 / 百炼
narra-cine-render ────────> OSS / FFmpeg / Remotion
narra-cine-mcp ───────────> narra-cine-server Application API
narra-cine-infra ─────────> 所有部署单元

narra-cine-contracts 作为版本化 npm 包发布到 GitLab Package Registry，其他仓库通过明确版本依赖，不允许直接复制 DTO 和 Schema。

6. 各仓库未来目录

narra-cine-web

narra-cine-web/
├── src/
│   ├── app/
│   ├── features/
│   │   ├── auth/
│   │   ├── projects/
│   │   ├── story/
│   │   ├── script-editor/
│   │   ├── asset-library/
│   │   ├── shot-planner/
│   │   ├── generation-studio/
│   │   ├── workflow-viewer/
│   │   ├── music-library/
│   │   ├── timeline-editor/
│   │   └── settings/
│   ├── components/
│   ├── hooks/
│   └── lib/
├── public/
├── tests/
└── package.json

narra-cine-server

narra-cine-server/
├── src/
│   ├── modules/
│   │   ├── identity/
│   │   ├── tenant/
│   │   ├── workspace/
│   │   ├── project/
│   │   ├── story/
│   │   ├── script/
│   │   ├── character/
│   │   ├── scene/
│   │   ├── asset/
│   │   ├── shot/
│   │   ├── model/
│   │   ├── generation/
│   │   ├── workflow/
│   │   ├── music/
│   │   ├── timeline/
│   │   ├── render/
│   │   ├── review/
│   │   ├── billing/
│   │   └── audit/
│   ├── common/
│   ├── infrastructure/
│   └── main.ts
├── prisma/
├── tests/
└── package.json

narra-cine-worker

narra-cine-worker/
├── src/
│   ├── workers/
│   │   ├── story/
│   │   ├── prompt/
│   │   ├── generation/
│   │   ├── provider/
│   │   ├── quality/
│   │   ├── music/
│   │   └── notification/
│   ├── providers/
│   │   ├── volcengine/
│   │   └── bailian/
│   ├── idempotency/
│   └── main.ts
├── workflows/
├── tests/
└── package.json

narra-cine-render

narra-cine-render/
├── src/
│   ├── compositions/
│   ├── renderers/
│   ├── ffmpeg/
│   ├── proxy/
│   ├── audio-mixing/
│   ├── subtitles/
│   └── quality-check/
├── tests/
└── package.json

narra-cine-mcp

narra-cine-mcp/
├── src/
│   ├── auth/
│   ├── context/
│   ├── tools/
│   ├── resources/
│   ├── prompts/
│   ├── approvals/
│   └── main.ts
├── tests/
└── package.json

narra-cine-contracts

narra-cine-contracts/
├── src/
│   ├── api/
│   ├── domain/
│   ├── events/
│   ├── generation/
│   ├── workflows/
│   ├── timeline/
│   └── mcp/
├── schemas/
├── tests/
└── package.json

narra-cine-infra

narra-cine-infra/
├── docker/
├── conductor/
│   ├── workflows/
│   └── tasks/
├── kubernetes/
├── monitoring/
├── terraform/
└── scripts/

7. 跨仓约束

• contracts 只包含协议、Schema 和纯类型，不包含业务实现；
• Web 不连接数据库、Conductor 和模型供应商；
• MCP 不直接访问数据库，只调用 Server 对外的 Application API；
• Worker 不绕过 Server 随意修改领域状态，任务结果通过明确命令或内部 API 回写；
• Provider 密钥只存在 Server/Worker 的安全配置中；
• Render 仓库只消费 TimelineSpec 和资产引用，不承载项目业务逻辑；
• 每个仓库独立 CI、镜像、版本和变更日志；
• 跨仓破坏性协议变更必须先发布 contracts 新版本，再逐仓升级。

8. 分支与发布

• 默认分支：main；
• 功能开发：短生命周期 Feature Branch；
• 合并方式：Merge Request + Squash；
• npm 包：语义化版本；
• 服务镜像：Git SHA + 语义化 Release Tag；
• contracts 使用向后兼容策略，重大变更升级主版本；
• 基础设施通过环境目录区分开发、测试和生产。