# 墨木灵思

![Version](https://img.shields.io/badge/version-1.4.8-blue.svg)
![Python](https://img.shields.io/badge/python-3.11-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.121.0-green.svg)
![React](https://img.shields.io/badge/react-18.3.1-blue.svg)

## 1. 项目简介

### 项目概述

**墨木灵思**是一款基于大语言模型的智能小说创作平台，帮助作者从大纲、角色到章节一气呵成地完成创作，让 AI 成为可靠的写作搭档。

### 项目起源

长篇网文与原创小说创作往往面临设定繁杂、人物关系难梳理、章节衔接不连贯等问题。墨木灵思将 AI 能力融入创作全流程，把「灵感 → 大纲 → 角色 → 章节」串联为可管理的结构化工作流，降低创作门槛并提升产出效率。

### 项目定位

| 维度 | 说明 |
|------|------|
| **目标用户** | 网文作者、业余写作者、内容创作者、文学爱好者 |
| **适用场景** | 长篇连载、短篇创作、世界观搭建、同人续写、拆书仿写 |
| **部署形态** | 支持 Docker 一键部署，也可本地开发运行 |

### 核心价值

- 用 AI 辅助完成大纲、角色、世界观等前期设定，缩短冷启动时间
- 多模型灵活切换，适配不同文风与成本需求
- 角色关系、伏笔、职业体系等结构化管理能力，保持长篇一致性
- 多用户数据隔离，适合个人或小团队私有化部署

---

## 2. 整体架构与技术栈

### 系统架构

采用**前后端分离**架构：React 单页应用负责交互，FastAPI 提供 REST API，PostgreSQL 持久化业务数据；生产环境通过 Docker Compose 编排应用与数据库，前端构建产物由后端静态托管，统一对外暴露 HTTP 服务。

```mermaid
flowchart LR
  subgraph Client
    UI[React SPA]
  end
  subgraph Server
    API[FastAPI]
    AI[AI 服务层]
    DB[(PostgreSQL)]
    Vec[ChromaDB / Embedding]
  end
  UI -->|HTTP / API| API
  API --> AI
  API --> DB
  API --> Vec
  AI -->|OpenAI 兼容 API| Ext[外部 LLM]
```

### 技术栈

| 分类 | 技术 | 版本 / 说明 |
|------|------|-------------|
| **后端** | Python | 3.11 |
| | FastAPI | 0.121.0 |
| | SQLAlchemy + Alembic | 2.0.25 / 1.14.0 |
| | Uvicorn | 0.38.0 |
| **前端** | React | 18.3.1 |
| | TypeScript + Vite | — |
| | Ant Design | 5.x |
| | Zustand | 5.x |
| **数据库** | PostgreSQL | 18（推荐） |
| | SQLite | 可选（开发 / 轻量场景） |
| **AI 与向量** | OpenAI / Anthropic SDK | 多模型接入 |
| | ChromaDB + Sentence Transformers | 长期记忆与语义检索 |
| **部署** | Docker + Docker Compose | 一键编排 |
| | GitHub Actions | 镜像构建与发布 |

### 技术选型说明

- **FastAPI**：异步性能好，自带 OpenAPI 文档，适合 AI 类长耗时接口。
- **PostgreSQL**：支持多用户、复杂关系与并发，满足生产级数据隔离。
- **React + Ant Design**：组件丰富，适合复杂表单与可视化（关系图、时间线等）。
- **Docker Compose**：降低部署成本，数据库与应用一键拉起。

---

## 3. 项目目录概览

```
MuMuAINovel/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/               # REST API 路由
│   │   ├── models/            # 数据模型
│   │   ├── services/          # 业务逻辑（含 AI 调用）
│   │   ├── middleware/        # 中间件
│   │   ├── mcp/               # MCP 插件集成
│   │   └── main.py            # 应用入口
│   ├── alembic/               # 数据库迁移
│   ├── scripts/               # 初始化与运维脚本
│   ├── static/                # 前端构建产物（生产）
│   └── requirements.txt
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── pages/             # 页面
│   │   ├── components/        # 通用组件
│   │   ├── services/          # API 封装
│   │   ├── store/             # 状态管理
│   │   └── theme/             # 主题配置
│   └── package.json
├── images/                     # 文档与截图资源
├── storage/                    # 用户生成资源（如封面）
├── logs/                       # 运行日志
├── docker-compose.yml          # 容器编排
├── Dockerfile                  # 镜像构建
└── README.md
```

| 目录 | 作用 |
|------|------|
| `backend/app/api/` | 项目、章节、角色、提示词等业务接口 |
| `backend/app/services/` | AI 生成、润色、向量记忆等核心逻辑 |
| `frontend/src/pages/` | 书架、项目详情、设置、提示词模板等页面 |
| `backend/alembic/` | PostgreSQL / SQLite  schema 迁移 |
| `backend/scripts/` | 数据库初始化、入口脚本 |

---

## 4. 核心业务功能

- **智能创作向导**：根据题材与设定，AI 自动生成大纲、角色档案与世界观框架。
- **多 AI 模型支持**：接入 OpenAI、Claude、Gemini 等，支持自定义 Base URL（兼容中转 API）。
- **项目管理与书架**：多项目并行，支持导入导出，便于备份与迁移。
- **角色与组织管理**：人物卡片、关系图谱、组织架构可视化编辑。
- **职业等级体系**：可自定义修仙境界、魔法等级等成长体系。
- **章节创作与润色**：章节生成、续写、重写、字数控制及 diff 对比。
- **世界观与大纲**：结构化维护故事背景与情节脉络。
- **伏笔管理**：追踪未回收伏笔，可视化时间线提醒。
- **灵感模式**：快速生成创作点子与情节灵感。
- **提示词工坊**：浏览、导入社区 Prompt 模板，可视化编辑自有模板。
- **拆书功能**：分析既有作品结构，辅助仿写与续写。
- **封面生成**：基于项目信息 AI 生成封面图。
- **长期记忆**：基于 Embedding 的语义记忆，保持跨章节一致性。
- **用户与认证**：本地账户、邮箱验证、LinuxDO OAuth；多用户数据隔离。
- **系统设置**：SMTP、AI 密钥、主题等可在线配置。

---

## 5. 实际应用场景示例

### 适用行业与领域

- 网络文学与自媒体连载
- 游戏、动漫、影视衍生文案
- 教育培训中的创意写作练习
- 个人 IP 与世界观孵化

### 典型场景

**场景一：新人作者快速开书**  
输入题材与基调后，由向导生成大纲与主要角色，再逐章扩写；适合从零起步、需要结构指引的作者。

**场景二：长篇连载一致性维护**  
在数百章规模下，通过角色关系图、伏笔管理与向量记忆，减少人设崩坏与情节穿帮。

**场景三：拆书仿写与风格学习**  
导入参考作品或章节，分析结构后结合自身设定续写，用于练笔或同人向创作。

---

## 6. 帮助解决的核心问题

- **创作冷启动难**：自动生成大纲、角色与世界观，减少空白页焦虑。
- **设定易混乱**：关系图、职业体系、伏笔追踪让长篇设定可检索、可维护。
- **AI 调用分散**：统一配置多模型与 Prompt，降低切换成本。
- **协作与部署复杂**：Docker 私有化部署，数据留在自有环境。
- **章节质量不稳定**：润色、重写、分析建议一键应用，提升成稿效率。
- **提示词难以沉淀**：模板工坊与可视化编辑，复用优质 Prompt。

---

## 7. 快速开始

### 环境要求

| 方式 | 要求 |
|------|------|
| **Docker 部署（推荐）** | Docker 20.10+、Docker Compose 2.0+；至少一个 LLM API Key |
| **本地开发** | Python 3.11、Node.js 18+、PostgreSQL 18（或 SQLite）；稳定网络（调用外部 AI API） |

**硬件建议（个人使用）**：2 核 CPU、2 GB 内存、10 GB 磁盘；生产或小团队建议 4 核 / 8 GB 内存。项目依赖外部 AI API，无需本地 GPU。

### 安装步骤（Docker）

```bash
# 1. 获取项目代码
git clone <你的仓库地址>
cd MuMuAINovel

# 2. 配置环境变量
cp backend/.env.example .env
# 编辑 .env：至少配置 AI API Key、数据库密码等

# 3. 确认必要文件存在
# - .env
# - backend/scripts/init_postgres.sql
```

### 运行步骤

```bash
# 启动全部服务
docker compose up -d

# 查看状态与日志
docker compose ps
docker compose logs -f
```

### 访问地址

| 服务 | 默认地址 |
|------|----------|
| **Web 应用** | http://localhost:8000 |
| **API 文档（Swagger）** | http://localhost:8000/docs |
| **API 文档（ReDoc）** | http://localhost:8000/redoc |
| **PostgreSQL** | localhost:5432（容器内通过服务名 `postgres` 访问） |

> 若修改 `.env` 中 `APP_PORT`（例如 `10003`），访问地址为 `http://localhost:10003`。

### 默认账号

在 `.env` 中启用本地登录时，默认配置示例：

| 项 | 默认值 |
|----|--------|
| 用户名 | `admin` |
| 密码 | `admin123` |

**请在生产环境中立即修改默认密码。**

### 本地开发（可选）

**后端**

```bash
cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 配置 DATABASE_URL 与 AI Key 后启动
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**前端**

```bash
cd frontend
npm install
npm run dev
```

生产构建：`npm run build`，产物由后端 `backend/static` 托管。

### 必需配置示例

```bash
# 数据库（Docker 场景由 compose 注入，本地需自行填写）
POSTGRES_PASSWORD=your_secure_password

# AI 服务（至少配置一项）
OPENAI_API_KEY=your_key
OPENAI_BASE_URL=https://api.openai.com/v1
DEFAULT_AI_PROVIDER=openai
DEFAULT_MODEL=gpt-4o-mini

# 本地登录
LOCAL_AUTH_ENABLED=true
LOCAL_AUTH_USERNAME=admin
LOCAL_AUTH_PASSWORD=your_password
```

### 常见问题

| 问题 | 解决方案 |
|------|----------|
| 启动后无法访问 | 检查 `APP_PORT` 映射与防火墙；`docker compose ps` 确认容器健康 |
| 登录后 Cookie 未保存 | HTTP 部署时将 `SESSION_COOKIE_SECURE=false` 写入 `.env` 并重启 |
| AI 调用失败 | 核对 API Key、Base URL 及网络代理（`HTTP_PROXY` / `HTTPS_PROXY`） |
| 数据库连接失败 | 确认 PostgreSQL 容器已 healthy；检查 `DATABASE_URL` 用户名密码 |
| 自建镜像缺少 Embedding | 使用官方镜像或按文档将模型放入 `backend/embedding/` 目录 |

---

## 8. 运行示例截图

![image-20260518142402652](images/image-20260518142402652.png)

![image-20260518142411086](images/image-20260518142411086.png)

![image-20260518142620791](images/image-20260518142620791.png)

![image-20260518142641345](images/image-20260518142641345.png)

![image-20260518143108652](images/image-20260518143108652.png)

![image-20260518143113951](images/image-20260518143113951.png)

![image-20260518143117651](images/image-20260518143117651.png)

![image-20260518143121175](images/image-20260518143121175.png)

![image-20260518143125197](images/image-20260518143125197.png)

![image-20260518143134898](images/image-20260518143134898.png)