# ai-novel

**Repository Path**: baymax2018/ai-novel

## Basic Information

- **Project Name**: ai-novel
- **Description**: AI生图、漫画生成、小说生成平台。一句话写小说、一键出图转漫画、社区展示的开源 AI 创作 SaaS（Next.js + FastAPI）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 虾米AI（NovelComic AI）

> 一句话写出爆款小说，一键生成漫画与插图，并发布到社区。

面向创作者的开源 **AI 内容生产 SaaS**：输入创意 → 生成世界观 / 角色 / 大纲 / 章节 → 文生图与角色肖像 → 小说转漫画 → 社区展示与互动。

[界面预览](#界面预览) · [功能特性](#功能特性) · [技术栈](#技术栈) · [快速开始](#快速开始) · [配置说明](#配置说明) · [对话模型](#对话模型llm怎么填) · [生图模型](#生图模型怎么填) · [开发指南](#开发指南) · [架构概览](#架构概览)

---

## 界面预览

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133430_269.png" alt="首页与社区发现" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133508_132.png" alt="AI 工作台 · 图片生成" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133516_917.png" alt="我的资产" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133530_023.png" alt="控制台 · 项目管理" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133557_748.png" alt="小说转漫画预览" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_133607_586.png" alt="章节编辑与 AI 功能" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_134458_803.png" alt="page_agent1" width="900" />
</p>

<p align="center">
  <img src="pic/ScreenShot_2026-07-22_134509_925.png" alt="page_agent2" width="900" />
</p>

---

## 功能特性

### AI 小说创作

- **一句话生成全链路**：世界观 → 角色 → 大纲 → 章节
- **SSE 流式输出**：章节生成、续写、改写、段落重生实时吐字
- **富文本编辑器**：Tiptap 编辑、自动保存、Markdown 导出
- **版本历史**：编辑自动快照，一键回滚
- **长篇一致性**：Story Bible / Chapter Memory，降低人物与剧情漂移
- **预设改写动作**：更好表达、更刺激、加甜、加悬念、多对话、描写更生动等

### AI 图片生成

- **Image Studio / 工作台文生图**：项目级与会话级出图
- **角色参考图与肖像**：生成、锁定，服务后续漫画一致性
- **多 Provider 图像网关**：火山 Seedream、OpenAI 兼容、ComfyUI、Replicate 等
- **套餐门控模型预设**：按计划开放不同图像模型

### 小说转漫画

- 章节场景分析 → 分镜 → 分格 / 整页出图
- Celery 多队列异步渲染，Redis 推送进度与取消
- 角色外观 / 种子 / 参考图等一致性机制

### 社区与运营

- 故事 / 漫画 / 图片作品公开发布与发现页
- 公开阅读、点赞、收藏、评论、关注
- 管理后台：用户、审核、Prompt / 成本可观测、运营发布

### Agent 与产品化

- **PageAgent**：页面内 GUI Agent，自然语言操控界面（可选，环境变量开关）
- **AI Workspace**：对话式创作入口（故事 + 图像工具调用）
- **JWT 鉴权**：Access + Refresh Token
- **积分 / 订阅计费**：Credits 台账 + Stripe 架构（可选）
- **中英双语**：前端 i18n + `Accept-Language` + 双语 Prompt

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Next.js 15（App Router）、React 19、TypeScript、TailwindCSS、shadcn/ui、Zustand、Tiptap、Framer Motion、page-agent |
| 后端 | FastAPI、Python 3.12、SQLAlchemy（async）、Alembic、Pydantic v2、Celery |
| 数据 | PostgreSQL 16、Redis 7 |
| 存储 | 腾讯云 COS（未配置时开发环境可回退 data URI） |
| AI | OpenAI 兼容 LLM（DeepSeek / Qwen / OpenAI / Moonshot / Ollama / vLLM 等） |
| 图像 | Volcengine Seedream、OpenAI 兼容图像 API、ComfyUI、Replicate |
| 工程 | pnpm workspace、Turborepo、Docker Compose |

---

## 仓库结构

```text
apps/
  web/                 Next.js 前端
  api/                 FastAPI 后端 + Celery worker 入口
packages/
  types/               共享 TypeScript 类型
infra/
  nginx/               反向代理参考配置
docs/                  文档与进度笔记
docker-compose.yml     PostgreSQL / Redis / API / Worker
.env.example           根目录环境变量示例（含前端公开变量）
apps/api/.env.example  后端完整环境变量示例
```

---

## 快速开始

### 环境要求

- Node.js **20+**
- pnpm **9+**（仓库已锁定 `pnpm@9.15.4`）
- Python **3.12+**（声明 `>=3.11`，推荐 3.12）
- Docker（推荐，用于 PostgreSQL / Redis）

### 1. 克隆与安装

```bash
git clone https://gitee.com/NineteenForty1s/ai-novel.git
cd ai-novel

# 前端依赖
pnpm install

# 后端依赖
cd apps/api
pip install -e ".[dev]"
cd ../..
```

### 2. 配置环境变量

```bash
# 后端
cp apps/api/.env.example apps/api/.env

# 前端（Next.js 读取 apps/web 下的本地 env）
cp .env.example apps/web/.env.local
```

至少填写：

```env
# apps/api/.env
DATABASE_URL=postgresql+asyncpg://novelcomic:novelcomic@localhost:5432/novelcomic
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=请换成随机字符串
JWT_SECRET_KEY=请换成足够长的随机字符串
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=你的密钥
LLM_MODEL=deepseek-chat

# apps/web/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

本地开发时，前端请使用与 CORS 一致的主机名（`localhost` 或 `127.0.0.1`，不要混用）。

### 3. 启动基础设施

```bash
docker-compose up -d postgres redis
```

### 4. 数据库迁移

```bash
python -m alembic -c apps/api/alembic.ini upgrade head
```

### 5. 启动开发服务

需要同时运行：**API**、**前端**，以及（出图 / 漫画时）**Celery Worker**。

```bash
# 终端 1 — API
cd apps/api
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 终端 2 — 前端
pnpm --filter @novelcomic/web dev

# 终端 3 — Worker（图片生成 / 漫画流水线需要）
cd apps/api
celery -A app.core.celery_app worker -Q story_generation,image_generation,image_generation_high,manga_render,email,cleanup,default -c 2 --loglevel=info
```

也可从仓库根目录使用：

```bash
pnpm dev   # Turborepo 并行启动已配置的前端/相关脚本
```

### 6. 打开应用

| 服务 | 地址 |
|------|------|
| 前端 | http://localhost:3000 |
| API | http://localhost:8000 |
| OpenAPI 文档 | http://localhost:8000/docs |

---

## 配置说明

完整变量列表见 [`apps/api/.env.example`](apps/api/.env.example) 与根目录 [`.env.example`](.env.example)。

### 总览

| 类别 | 关键变量 | 说明 |
|------|-----------|------|
| 核心 | `DATABASE_URL` / `REDIS_URL` | PostgreSQL、Redis |
| 鉴权 | `SECRET_KEY` / `JWT_SECRET_KEY` | 生产环境必须更换；弱密钥在 `ENVIRONMENT=production` 时会被拒绝 |
| **对话 / 小说 LLM** | `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL` | 故事生成、改写、Agent 对话等（OpenAI 兼容） |
| **生图模型** | `IMAGE_PROVIDER` + 对应 Provider 的 `*_IMAGE_*` / `COMFYUI_*` / `REPLICATE_API_KEY` | Image Studio、肖像、漫画出图 |
| 存储 | `COS_*` | 腾讯云 COS；不配则开发态可用 data URI（不适合生产） |
| 支付 | `STRIPE_*` | 可选 |

---

### 对话模型（LLM）怎么填

故事生成、续写改写、大纲/世界观、AI Workspace 对话等，都读 **`apps/api/.env`** 里这三项：

```env
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-你的密钥
LLM_MODEL=deepseek-chat
```

要求：**OpenAI 兼容**的 Chat Completions 接口（`/v1/chat/completions`）。换厂商时改 URL + Key + 模型名即可。

| 厂商 | `LLM_BASE_URL` 示例 | `LLM_MODEL` 示例 |
|------|---------------------|------------------|
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` / `deepseek-reasoner` |
| 通义 Qwen（DashScope） | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` / `qwen-max` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` / `gpt-4o-mini` |
| Moonshot | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` 等 |
| 本地 Ollama | `http://127.0.0.1:11434/v1` | 如 `llama3.1`（需 Ollama 已拉取模型） |
| 自建 vLLM | `http://127.0.0.1:8001/v1` | 你部署的模型名 |

改完后**重启 API**（以及依赖 LLM 的进程）生效。  
前端 **PageAgent** 是另一套配置（见下文），与这里的 `LLM_*` **互不影响**。

---

### 生图模型怎么填

图片生成、角色肖像、漫画分格/整页出图走 **Image Gateway**，配置同样在 **`apps/api/.env`**。  
出图任务跑在 **Celery Worker** 上，只起 API 不起 Worker 时，对话可以工作，但生图/漫画会排队不执行。

#### 1. 选默认 Provider

```env
# 可选: openai_compatible | volcengine | comfyui | replicate
IMAGE_PROVIDER=openai_compatible
```

未在前端指定模型时，系统用这个默认值；漫画侧 Prompt 语言也会参考所选模型（火山 → 中文，其它 → 英文）。

#### 2. 按 Provider 填写密钥与模型（四选一或多选）

**A. OpenAI 兼容图像 API**（GPT-Image、各类中转）

```env
IMAGE_PROVIDER=openai_compatible
OPENAI_IMAGE_BASE_URL=https://api.openai.com/v1
OPENAI_IMAGE_API_KEY=sk-你的密钥
OPENAI_IMAGE_MODEL=gpt-image-1
```

**B. 火山引擎 Seedream（豆包）**

```env
IMAGE_PROVIDER=volcengine
VOLCENGINE_IMAGE_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
VOLCENGINE_IMAGE_API_KEY=你的方舟 API Key
VOLCENGINE_IMAGE_MODEL=doubao-seedream-5-0-260128
```

**C. 本地 ComfyUI**

```env
IMAGE_PROVIDER=comfyui
COMFYUI_URL=http://127.0.0.1:8188
# COMFYUI_API_KEY=   # 若你的 ComfyUI 开了鉴权再填
IMAGE_DEFAULT_MODEL=anime-xl
```

**D. Replicate**

```env
IMAGE_PROVIDER=replicate
REPLICATE_API_KEY=你的 Replicate Token
```

填好对应密钥后，Studio 往往会**自动发现**可用预设；也可手动覆盖：

```env
# 可选：JSON 数组，覆盖自动发现的模型列表（方便多模型并存）
IMAGE_MODEL_PRESETS=[{"id":"volc","label":"豆包 Seedream","provider":"volcengine","model":"doubao-seedream-5-0-260128"},{"id":"gpt","label":"GPT Image","provider":"openai_compatible","model":"gpt-image-1"}]
```

改完后**重启 API + Worker**。若完全不配任何图像密钥，对话/写小说仍可用，Image Studio / 漫画出图会报未配置模型。

---

### 前端（`apps/web/.env.local`）

| 变量 | 说明 |
|------|------|
| `NEXT_PUBLIC_API_URL` | 后端地址，默认 `http://localhost:8000` |
| `NEXT_PUBLIC_APP_URL` | 前端地址 |
| `NEXT_PUBLIC_COS_PUBLIC_BASE_URL` | 可选，COS / CDN 公网前缀 |
| `NEXT_PUBLIC_PAGE_AGENT_ENABLED` | `true` 时启用 PageAgent |
| `NEXT_PUBLIC_PAGE_AGENT_MODEL` / `BASE_URL` / `API_KEY` | **仅 PageAgent** 所用模型（与后端 `LLM_*` 独立） |

PageAgent 示例：

```env
NEXT_PUBLIC_PAGE_AGENT_ENABLED=true
NEXT_PUBLIC_PAGE_AGENT_MODEL=qwen-plus
NEXT_PUBLIC_PAGE_AGENT_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
NEXT_PUBLIC_PAGE_AGENT_API_KEY=你的密钥
```

#### PageAgent 安全提示

PageAgent 在**浏览器端**初始化，相关 `NEXT_PUBLIC_*` 密钥会暴露给前端。生产环境请使用**专用、权限受限**的密钥，或仅在演示环境开启。文档：[PageAgent Quick Start](https://alibaba.github.io/page-agent/docs/introduction/quick-start)。

### Docker 一键起后端依赖服务

```bash
# 仅数据库与缓存
docker-compose up -d postgres redis

# API + Worker + 依赖（需准备好 apps/api/.env）
docker-compose up
```

---

## 开发指南

### 常用命令

```bash
# Monorepo
pnpm install
pnpm build
pnpm lint
pnpm format

# 前端
pnpm --filter @novelcomic/web dev
pnpm --filter @novelcomic/web build
pnpm --filter @novelcomic/web lint
pnpm --filter @novelcomic/web exec tsc --noEmit

# 后端
uvicorn app.main:app --reload --app-dir apps/api
python -m alembic -c apps/api/alembic.ini upgrade head
python -m alembic -c apps/api/alembic.ini revision --autogenerate -m "message"
python -m pytest apps/api
python -m ruff check apps/api
```

### API 模块一览

路由位于 `apps/api/app/api/routes/`，主要包括：

- `auth` — 注册 / 登录 / 刷新
- `projects` / `project_image` — 项目与项目级出图
- `stories` — 故事生成与章节编辑（含 SSE）
- `comics` — 漫画生成与任务状态
- `community` — 社区发现与互动
- `billing` — 积分 / 订阅
- `admin` — 管理后台
- `images` / `health` — 图像与健康检查

更完整的接口定义以运行中的 **Swagger** 为准：`http://localhost:8000/docs`。

---

## 架构概览

```text
浏览器 (Next.js)
  ├─ SSE：章节流式生成 / Agent 对话
  ├─ REST：项目、社区、计费、管理
  └─ 可选 PageAgent（页面 GUI Agent）
        │
        ▼
FastAPI
  ├─ LLM Provider（OpenAI 兼容）
  ├─ Image Gateway（多 Provider）
  ├─ 同步业务 + SSE
  └─ 投递 Celery 任务
        │
        ▼
Celery Worker  ← Redis（Broker / 进度事件）
  ├─ story_generation / manga_render
  └─ image_generation / image_generation_high / …
        │
        ▼
PostgreSQL · 腾讯云 COS（可选）
```

**设计要点：**

- 路由 / 服务 / Schema / Model 分层
- 长任务走 Celery；进度经 Redis Pub/Sub + 事件列表回放
- 进程崩溃后启动时对账，清理卡在 `generating` 的状态
- 前端 `api.ts` 统一鉴权、`Accept-Language`，以及 401 单飞 Refresh

---

## 路线图

- [x] Monorepo 与鉴权
- [x] AI 小说生成（流式）与章节编辑器
- [x] 文生图 / Image Gateway / 角色肖像
- [x] 小说转漫画流水线与角色一致性
- [x] 社区发布与互动
- [x] 积分计费与管理后台
- [x] PageAgent 页面 GUI Agent（可选）
- [ ] 更完善的部署文档与 Helm / 一键云部署
- [ ] 插件化 Prompt / 模型市场
- [ ] 更细的漫画页编辑器与导出能力

---

## 贡献

欢迎 Issue 与 Pull Request。提交前建议：

1. 保持改动聚焦，避免无关格式化大扫荡
2. 前端跑通 `lint` / `tsc`；后端跑通相关测试或至少 `ruff`
3. **不要提交** `.env`、密钥、真实用户数据或生产配置
4. 若改动流式协议或鉴权行为，请同步说明前后端契约

---

## 安全与合规

- 切勿将 `LLM_API_KEY`、`JWT_SECRET_KEY`、COS / Stripe 密钥提交到 Git
- `ENVIRONMENT=production` 时请使用强随机密钥
- PageAgent 的浏览器端密钥需按最小权限原则配置
- 开源部署时请自行遵守所用 LLM / 图像服务商的服务条款与内容安全要求

---

## License

本项目采用 **非商业源码许可**（详见 [LICENSE](./LICENSE)）：

- 允许：个人学习、研究、非商业使用与修改分发（需保留版权与许可声明）
- 禁止：未经书面授权的任何商业使用（含售卖、SaaS 收费、公司商业项目等）
- 商业合作请联系作者单独授权

> 注意：这不是 MIT。仓库已改为禁止商用的源码公开许可。