一个全TypeScript的AI漫剧生成Agent
从故事想法出发，用 LangGraph.js 编排多 Agent，生成故事大纲、角色设定、分镜脚本、角色图与镜头素材。
🎹
MiraFrame 是一个面向 AI 漫剧创作的全栈 Agent 项目。它不是简单调用一次大模型，而是把“故事大纲 → 角色设定 → 分镜脚本 → 角色图 → 镜头素材 → 导出”拆成可观察、可重试、可人工反馈的创作流水线。
这个项目特别适合正在从前端转向 AI Agent / AI 应用工程的同学：
•
前端、后端、Agent、共享类型全部使用 TypeScript。
•
前端使用 React + Vite + Zustand + TanStack Query，学习成本贴近常见前端项目。
•
后端使用 Nest.js，把 API、WebSocket、队列、数据库和 Agent 服务拆成清晰模块。
•
Agent 层使用 LangGraph.js，可以学习状态图、节点编排、人工反馈、重试和工作流恢复。
•
项目不是纯 Demo，有项目页、节点详情、设置面板、生成服务配置、失败重试等真实产品逻辑。
🎈
MiraFrame 目前定位为学习、演示和产品原型项目。它适合研究 AI Agent 工程化链路，不建议不经改造直接用于生产环境。
产品截图
项目列表与工作台
50%
50%
核心功能
•
项目管理：创建、查看、批量删除漫剧项目。
•
多阶段工作流：故事大纲、角色设定、分镜脚本、镜头画面、视频与导出。
•
节点详情：在项目页查看每个节点的产物、状态和错误信息。
•
可反馈节点：故事大纲、角色设定、分镜脚本支持用户输入修改意见。
•
生成服务设置：在 UI 中配置文本、图像、视频生成服务。
•
弱提示：未配置真实生成服务时，在入口页给出轻量提醒。
•
深浅色主题：默认跟随系统主题，用户切换后保存偏好。
•
Fake Provider：没有外部 API Key 时，也可以用 fake 模式跑通基础流程。
技术架构
代码块
Plain Text
MiraFrame/
├── packages/
│ ├── frontend/ # React 18 + Vite + Zustand + TanStack Query
│ ├── server/ # Nest.js API + WebSocket + Drizzle + BullMQ
│ ├── agent/ # LangGraph.js 工作流与 Agent 节点
│ └── shared/ # 共享类型、Zod Schema、常量
├── docs/screenshots/ # README 截图
├── docker-compose.yml
├── docker-compose.dev.yml
├── Dockerfile.server
├── Dockerfile.frontend
└── .env.example
依赖方向：
代码块
Plain Text
frontend ─┐
server ─┼──> shared
agent ─┘
server ──> agent
shared 是类型和 Schema 的单一数据源。前端拿它做类型约束，后端拿它做接口与数据校验，Agent 层也复用同一套阶段和状态定义。
工作流概览
MiraFrame 的生成流程不是一次性请求，而是一个可恢复的多阶段 Agent 图：
代码块
Plain Text
当前项目中保留了典型 AI Agent 应用会遇到的产品问题：
•
什么时候让用户反馈，什么时候让系统自动推进。
•
生成失败后如何展示错误，而不是一直停留在“生成中”。
•
右侧日志和节点详情输入框如何分工，避免重复交互。
•
配置不完整时如何弱提示，而不是直接阻断用户。
技术栈
#mEcMylSNgNVL text{white-space:pre}.fb0{stroke:var(--N900-FG, 0.15)}.fx0{stroke-miterlimit:10}.fa1{fill:#bbbfc4}.fx1{font:normal 400 12px MonospacedNumber,LarkHackSafariFont,LarkEmojiFont,LarkChineseQuote,-apple-system,BlinkMacSystemFont,Helvetica Neue,Tahoma,PingFang SC,Microsoft Yahei,Arial,Hiragino Sans GB,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji}.fx2{text-anchor:middle}.fx3{dominant-baseline:central}.fx4{stroke:none}.fc0{fill:var(--text-caption)}.fa2{fill:var(--text-link-disabled)}.fx5{font:400 normal 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"}.fx6{text-anchor:start}.fx7{dominant-baseline:alphabetic}.fc1{fill:rgb(0, 0, 0)}.fb1{fill:var(--N900-FG, 0.15)}.fa3{fill:var(--bg-body)}AB1234567891011121314层级语言包管理前端前端状态UI后端Agent 编排数据库ORM队列 / 缓存实时通信测试部署技术TypeScript 5.5+pnpm 9 workspaceReact 18, Vite 6, React Router 7Zustand 5, TanStack Query 5TailwindCSS 4, Radix UI, lucide-reactNest.js 11LangGraph.js v1.xPostgreSQL 16Drizzle ORM, drizzle-zodRedis 7, BullMQSocket.IOVitest, Testing Library, PlaywrightDocker Compose
快速开始
准备环境
需要安装：
•
Node.js >= 22
•
pnpm >= 9
•
Docker Desktop，或本地 PostgreSQL + Redis
启用 pnpm：
代码块
Plain Text
corepack enable
corepack prepare pnpm@9.12.0 --activate
启动数据库和 Redis
开发环境可以只用 Docker 启动基础设施：
代码块
Plain Text
docker compose -f docker-compose.dev.yml up -d
默认会启动：
•
PostgreSQL: localhost:5432
•
Redis: localhost:6379
•
数据库名: miraframe
配置环境变量
代码块
Plain Text
cp .env.example .env
如果要接入真实生成服务，可以改成：
代码块
Plain Text
TEXT_PROVIDER=openai
TEXT_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
TEXT_API_KEY=your_text_api_key
安装依赖
代码块
Plain Text
pnpm install
启动开发服务
后端：
代码块
Plain Text
前端：
代码块
Plain Text
pnpm --dir packages/frontend dev
常用命令
代码块
Markdown
# 类型检查
pnpm typecheck
# 单元测试
pnpm test
适合谁
•
想从前端转向 AI Agent 应用开发的工程师。
•
想学习 LangGraph.js 但不想只看抽象示例的同学。
•
想了解 AI 生成类产品如何处理状态、失败、重试、反馈和配置的人。
•
想做 AI 漫剧、短剧、分镜、图片/视频生成产品原型的团队。