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

核心价值

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

2. 整体架构与技术栈

系统架构

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

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）

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

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

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

运行步骤

# 启动全部服务
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`

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

本地开发（可选）

后端

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

前端

cd frontend
npm install
npm run dev

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

必需配置示例

# 数据库（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/` 目录

README.md Unescape Escape

墨木灵思

1. 项目简介

项目概述

项目起源

项目定位