yi
318 lines
11 KiB
Markdown
318 lines
11 KiB
Markdown
# 墨木灵思
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## 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. 运行示例截图
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|