Nova Studio

📖 简介

Nova Studio 是一个面向个人/团队的 AI 视频/图像生成工作台。前端使用 Next.js 16 + React 19 静态导出（PWA），后端是轻量 Node.js 服务（server.js + SQLite + WebSocket），统一调度任务并代理图像生成 API。

开源版特性：

• 支持分别配置图片模型与文本模型，模型级独立保存 API Key 与 Base URL
• 用户自定义模型列表和 API 端点，后端按协议路由并透传已配置参数
• 所有配置存储在浏览器 localStorage
• 文字模型支持 Google（generateContent）和 OpenAI（Response 协议）
• 视频生成完全插件化：本体不内置任何视频上游协议，能力由插件包提供

当前版本：v3.4.0

📚 文档

所有文档都在 docs/ 目录下。

💎 赞助商

期待您的赞助

🖼️ UI 预览

生图工作台

宽屏	窄屏	手机版

视频工作台（插件化）

左侧表单完全由插件的 ui.schema.json 渲染——档位、分辨率、时长、素材槽都是插件申报的，本体不认识任何具体上游。凭据在「设置 → 插件」里按插件各填一份。

工作台	设置 → 插件

UI设计模式（图片切图 + 网页复刻）

从一张 UI 原图出发：AI 自动拆图 → 切图编辑器手动调整 → agent 多轮对话复刻网页 → 导出完整设计包。

① 待复刻原图	② 导入并开始拆图	③ 自动拆图 + 手动调整	④ 开始生成网页复刻

⑤ Agent 修改复刻	⑥ 多轮完成修改	⑦ 导出为压缩包	⑧ 实物展示

Agent 模式

询问	生成

GIF 生成

生成	微调

无限画布

预览	编辑

其他功能

反推提示词	提示词广场	我的素材	设置

✨ 功能特性

七大工作模式

视频工作台（插件化）

视频生成不内置任何具体上游协议——tab、任务队列、历史记录、素材上传、表单渲染由本体提供， 「向谁发什么请求、怎么轮询、结果在哪、表单长什么样」全部写在插件包里。

• 安装方式：管理员把插件目录放进 backend/plugins/，重启后端（或在设置里点「重新读取」）
• 插件是纯 JSON：三个文件（manifest.json / ui.schema.json / provider.json），不含可执行代码
• 出网需申报：permissions.hosts 之外的主机、以及所有内网地址一律被拒绝
• 凭据属于用户：apiKey / baseUrl 在「设置 → 插件」里填，存浏览器，不入库
• 设置页只读：只展示已装了哪些插件与加载失败的原因，装卸插件需要管理员操作服务器目录
• 参考实现：backend/plugins/ccode-h3/（MiniMax H3，8 个模型、首尾帧、参考图/视频/音频、超分档位）
• 产物地址原样透传：不替上游改写域名，视频链接就是上游返回的原生地址

📦 官方插件合集：nova-studio-plugins ——含最小插件模板，可直接 clone 进 backend/plugins/：

cd backend/plugins && git clone https://github.com/tianjiangqiji/nova-studio-plugins.git .

👉 想自己写插件（或让 AI 写）：docs/plugins/ （把 docs/plugins/LLM.md 整份喂给 AI 即可）

UI设计模式（图片切图 + 网页复刻）

把一张平面 UI 图拆解成可复用的切图资产，并进一步复刻为可预览的网页。仅宽屏模式可用，窄屏显示切换提示。

• AI 拆图：视觉模型识别切片与背景候选，结果先在确认弹窗里逐条勾选再落库；JSON 解析失败会自动发起一次无图修复重试
• 切图编辑器：画布缩放/平移、拖拽创建、框选多选、8 向缩放、四角圆角、吸附对齐、右键菜单、完整撤销重做（50 步）与快捷键
• 三种查看模式：原图（源图 + 轮廓）／挖洞（抠图后效果，本地生成不消耗额度）／仅切图（棋盘底）
• 四种资产处理：算法透明、AI 透明、算法 SVG 矢量化（imagetracerjs）、AI 重绘 SVG。四者各自独立可还原，互不覆盖；算法类支持批量，AI 类只能逐个触发（避免一次点击连续扣费）
• 背景补齐：在背景确认弹窗里调整蓝框（背景范围）与红框（移除区域），调用带蒙版的图片编辑补齐被前景遮挡的背景；产出「局部合成」与「AI 原图」两个结果供选择
• 网页复刻：多轮 AI agent 对话，产物是固定三文件（index.html / styles.css / script.js）+ 只读 assets/。agent 通过 read_file / edit_file 按行编辑，iframe 实时预览，上下文用量以 API 回报的 input_tokens 为准（140K 提醒 / 175K 拒绝）
• 导出：切图包 ZIP（PNG + 可选 SVG + manifest）或完整设计包（含源图、工作区元数据与 web/ 网页文件），并支持从导出包还原工作区
• 数据：工作区与图片存于 IndexedDB（nova-slice-db），纳入一键备份/恢复范围

⚠️ 「AI 补齐」（画笔蒙版局部重绘）暂未包含在本版本中。其请求管线与背景补齐共用且工作正常， 待编辑器组件的一处渲染时序缺陷修复后再开放。

图片编辑相关能力（AI 透明化、背景补齐）需要一个 OpenAI 协议的图片模型：它们依赖带 mask 的 /v1/images/edits，Gemini 与 Grok 协议没有该语义，因此不会出现在切图页的模型选择器里。

提示词广场

PROMPT_GALLERY_MODE 三种工作方式：

• 1 常驻：Tab 始终显示
• 2 私密：需要密码验证（密码来自后端环境变量 PROMPT_GALLERY_PASSWORD）
• 3 关闭：完全不显示

提示词内容由后端 backend/prompts.json 维护，支持敏感词过滤（backend/blacklist.json）。

模型系统

Nova Studio 采用用户自定义模型架构：

• 模型级配置：每个图片模型和文本模型都独立保存协议、显示名称、模型 ID、API Key 与 Base URL
• 图像模型：用户自由添加、编辑、删除，支持设置协议、显示名称、模型 ID、最大参考图数量、最大分辨率
• Image 2 额外参数：仅 OpenAI 图片模型显示，透明背景、质量、风格控件默认开启，用户可手动关闭
• 文字模型：支持自定义扩展，兼容 Gemini 和 OpenAI Response
• 默认模型：可为文本生图、图生图、反推提示词、Agent、AI 拆图、网页复刻、切图图片编辑等任务分别设置默认模型
• 多协议文本模型：OpenAI Responses / OpenAI Chat Completions / Anthropic Messages / Google Gemini 四种协议，均支持多轮工具调用（UI设计模式的网页复刻 agent 依赖此能力），统一经 /api/nova/proxy/text 转发

任务系统

• 提交后入队，服务端并发处理（默认上限 50，可通过 NOVA_TASK_CONCURRENCY 调整）
• 浏览器通过 WebSocket 实时接收任务/队列状态，断线自动重连，失败 5 次后回退 HTTP 轮询（30 秒间隔）
• 任务结果本地落盘（默认 backend/data/nova-images/，可用 NOVA_IMAGE_DIR 调整），HTTP 路由 /api/nova/images/:taskId/:index 直接提供
• 任务 TTL 12 小时（可通过 NOVA_TASK_TTL_HOURS 调整），过期自动清理（5 分钟一次）
• 服务重启时把残留"处理中"任务标记为失败并删除产物，避免幽灵任务

体验与工程化

• PWA（next-pwa），可安装到桌面
• 三端兼容 UI：桌面端、平板端、移动端自适应布局，提供一致的用户体验
• 暗色 / 亮色主题切换
• 宽屏 / 窄屏自适应布局（左侧垂直 Tab + 右侧内容）
• 历史任务持久化（IndexedDB / localStorage）
• 一键备份 / 恢复（JSZip 打包 localStorage + IndexedDB，支持跳过不兼容旧配置并恢复其余数据）
• 历史图片懒加载（@tanstack/react-virtual）
• 随机图、Toast 通知、确认对话框

📁 项目结构

nova-image-studio/
├── frontend/                 # Next.js 前端（React 19 + TS）
│   ├── src/
│   │   ├── app/              # 根页面 layout.tsx / page.tsx
│   │   ├── components/       # 业务组件 + shadcn/ui 基础组件
│   │   │   ├── workspace/    # 主工作台壳、Tab、Header、结果区
│   │   │   ├── agent/        # Agent 模式相关组件
│   │   │   ├── plugin/       # 视频插件宿主：schema 表单、素材槽、历史、进度
│   │   │   ├── settings/     # 设置页分区（插件清单与凭据）
│   │   │   ├── slice/        # UI设计模式：切图编辑器、资产面板、网页复刻
│   │   │   └── ui/           # shadcn 风格 UI 基础件
│   │   ├── hooks/            # useQueueStatus / useAgentChat / useGifWorkflow / ...
│   │   ├── lib/              # 客户端工具、API 客户端、WebSocket、备份
│   │   │   ├── plugin-*.ts   # 插件 schema 求解、任务客户端、历史、上传
│   │   │   ├── slice-*.ts    # 切图几何/裁剪/矢量化/导出/AI 客户端
│   │   │   └── web-agent/    # 网页复刻 agent：虚拟文件系统、工具、主循环
│   │   └── test/             # vitest 配置与用例
│   ├── public/               # PWA 图标、静态资源
│   ├── next.config.ts        # 静态导出 + next-pwa 配置
│   ├── package.json
│   └── vitest.config.ts
├── backend/
│   ├── server.js             # Node 服务（HTTP + WS + SQLite + 任务队列）
│   ├── plugin-runtime/       # 视频插件运行时：注册表、校验、模板、执行、素材、自检 CLI
│   ├── plugins/              # 已安装的视频插件（管理员放置）
│   │   └── ccode-h3/         # 参考实现：MiniMax H3
│   ├── prompts.json          # 提示词广场内容
│   ├── blacklist.json        # 敏感词
│   ├── .env.example
│   └── package.json
├── docs/
│   ├── images/               # README 截图
│   └── plugins/              # 视频插件开发文档（含喂给 AI 的 LLM.md）
├── scripts/
│   ├── pack.js               # 打包：build + 汇总到 out.zip
│   └── generate-icons.js     # 生成 PWA 图标
├── package.json              # npm workspaces 根
├── LICENSE                   # AGPL-3.0 许可证
└── README.md

生产构建会输出到 frontend/out/，由后端 server.js 静态托管。

🚀 部署指南

# 0. clone 仓库
git clone https://github.com/tianjiangqiji/nova-image-studio.git
cd nova-image-studio

# 1. 复制 Docker 专用环境变量到项目根目录（挂载为 /app/.env）
cp backend/.env.docker.example .env
# 按需编辑 .env（限流、广场密码等）

# 2. 复制配置文件到根目录（compose 会挂到容器内）
cp backend/blacklist.json blacklist.json
cp backend/prompts.json prompts.json
# 若仓库里没有这两份文件：touch blacklist.json prompts.json 后自行填写

# 3. 创建数据目录和插件目录
mkdir -p data
mkdir -p plugins
# 把内置插件复制到宿主机（挂载会覆盖镜像内插件目录，不复制的话内置插件会消失）
cp -r backend/plugins/ccode-h3 plugins/

# 4. 启动服务
docker compose up -d

# 运行期最少需要：
# docker-compose.yml、.env、blacklist.json、prompts.json、data/、plugins/

docker compose restart

docker compose down
docker compose pull
docker compose up -d --force-recreate

npm ci
npm run build

frontend/out/
backend/server.js
backend/package.json
backend/package-lock.json
backend/prompts.json
backend/blacklist.json
backend/.env          # 按生产环境调整（cwd=backend）

NODE_ENV=production
NOVA_TASK_DB=./data/nova-tasks.sqlite
NOVA_IMAGE_DIR=./data/nova-images

cd backend && npm ci --omit=dev   # 必须本地装 better-sqlite3 原生模块
cd ..
npm start                         # 等价于 cd backend && node server.js

npm run go

# 1. 克隆仓库
git clone https://github.com/tianjiangqiji/nova-image-studio.git
cd nova-image-studio

# 2. 安装依赖（自动安装根、frontend、backend）
npm install

# 3. 复制后端环境变量（本地 cwd=backend，使用相对路径 ./data/...）
cp backend/.env.example backend/.env
# Windows: Copy-Item backend/.env.example backend/.env
# 确认 backend/.env 中：
#   NOVA_TASK_DB=./data/nova-tasks.sqlite
#   NOVA_IMAGE_DIR=./data/nova-images

# 4. 启动开发模式（等同于 build 后用 production 模式跑 server.js）
npm run dev

npm run dev:frontend   # 仅启动 Next.js dev server（HMR，不走静态导出）
npm run dev:backend    # 仅启动后端 server.js
npm run build          # 构建前端静态产物到 frontend/out/
npm start              # 直接跑后端 server.js
npm run lint           # 前端 ESLint
npm test               # 前端 Vitest watch
npm run test:run       # 前端 Vitest 单次
npm run go             # 打包：build + 汇总到根 out.zip

docker build -t nova-image-studio:latest .

docker tag nova-image-studio:latest tianjiangqiji/nova-image-studio:latest

docker push tianjiangqiji/nova-image-studio:latest

⚙️ 环境变量

.env 修改后大部分运行时配置实时生效（任务并发、限流、队列容量、接单开关、广场模式、素材体积上限），无需重启；PORT、HOSTNAME、NODE_ENV、NOVA_TASK_DB、NOVA_IMAGE_DIR、NOVA_PLUGINS_DIR 这类启动级配置仍需重启。

📡 API 速览

后端暴露在 /api/nova/* 路径下，前端在同源调用。

任务状态

• 排队中：等待调度
• processing：正在调用上游 API
• completed：成功，result.images 包含产物链接
• failed：失败，详见 error
• expired：超过 TTL

❓ 常见问题

为什么生产环境不用 next start？ 项目使用 output: 'export'，构建产物是纯静态 out/。server.js 同时托管静态文件 + 任务 API，不再依赖 next start。

只部署 out/ 能用吗？ UI 可以打开，但任务提交、Agent、历史同步全部依赖 /api/nova/*，必须运行 server.js。

数据库需要单独备份吗？ 首次部署不需要，服务启动会自建。任务数据要保留就备份数据目录（本地 backend/data/，Docker 宿主机 ./data/）里的 nova-tasks.sqlite（含 WAL/SHM）以及 nova-images/。重启后残留任务会被自动标记为失败并清理产物。

如何临时停止接收新任务（不停服务）？ 编辑 .env：

NOVA_ACCEPT_NEW_TASKS=false

保存即生效。等待在飞任务完成后即可重启升级。再次开启设为 true 或留空。

任务多久会过期？ 默认创建后 12 小时（可通过 NOVA_TASK_TTL_HOURS 配置修改）；前端在拿到结果后会调用 /ack 续期 2 分钟，给下载留时间。超过 TTL 服务端删除数据库记录与产物图片。

🙏 致谢

本项目的无限画布工作区功能基于 infinite-canvas 项目开发，感谢原作者 basketikun 的开源贡献。

本项目的 UI设计模式（图片切图）功能参考 image-to-slice 项目实现，感谢原作者 50kg 的开源贡献。原项目是 Figma 插件，本项目移植了其中与 Figma 无关的核心切图流程，并重写了 UI、模型配置与数据存储。

切图的本地 SVG 矢量化基于 imagetracerjs。

感谢 Linux.do 社区的支持。

☕ 赞助支持

如果这个项目对你有帮助，欢迎通过爱发电赞助支持，你的每一份鼓励都是持续更新的动力！

📬 联系方式

邮箱：[email protected]

Star History

📄 许可证

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）开源许可证。

这意味着：

• ✅ 你可以自由使用、修改和分发本软件
• ✅ 你可以将本软件用于商业用途
• ⚠️ 如果你修改了本软件并通过网络提供服务，你必须公开修改后的源代码
• ⚠️ 基于本软件的衍生作品必须使用相同的 AGPL-3.0 许可证

详细条款请参阅 LICENSE 文件。