🎭 AI Visual Novel Engine (GraphRAG + Multi-Agent)

基于动态知识图谱与多智能体协同的生成式交互叙事引擎。 An Interactive Narrative Engine powered by GraphRAG and Dual-Agent Architecture.

📖 项目简介 (Introduction)

本项目是一个探索下一代交互式叙事的实验性引擎。不同于传统的“选择分支树”游戏，本引擎利用大语言模型 (LLM) 实时生成剧情，并结合 Neo4j 知识图谱 实现了具有“长时记忆”和“逻辑一致性”的动态世界。

系统采用 "Director-Writer" 双脑架构：Director 负责逻辑与剧情节拍控制，Writer 负责文学描写与演出，配合 GraphRAG 技术，有效解决了长文本生成中的幻觉与遗忘问题。

✨ 核心特性 (Key Features)

• 🧠 GraphRAG 记忆系统：
  • 利用 Neo4j 存储角色、地点、物品及剧情状态。
  • 采用 Vector Search (向量检索) + Graph Traversal (图遍历) 的混合检索策略，精准召回上下文。
• 🎬 双智能体架构 (Dual-Agent)：
  • Director Agent (逻辑脑)：分析玩家意图，管理剧情节拍 (Beats)，执行数据库增删改查。
  • Writer Agent (文笔脑)：根据导演指令生成沉浸式文本、立绘表情及环境描述。
• 🖼️ 智能视觉引擎：
  • 支持多模态输入（看图写剧本）与输出（文生图）。
  • 资产持久化：生成的图片自动绑定到图谱实体，实现“一次生成，永久复用”，大幅降低成本。
• 💾 全状态持久化：
  • 支持服务端存读档，完整保存图谱快照与客户端状态。
  • 支持多剧本并行游玩。

🛠️ 技术栈 (Tech Stack)

• Frontend: React, TypeScript, Tailwind CSS, Vite
• Backend: Python, FastAPI, Pydantic (Strict Schema)
• Database: Neo4j (Docker 部署)
• AI Integration:
  • Google Gemini (Pro/Flash/Imagen)
  • OpenAI (GPT-4o/DALL-E 3)
  • LangChain / Google GenAI SDK

🚀 快速开始 (Quick Start)

1. 环境准备

确保已安装：

• Docker & Docker Compose
• Python 3.9+
• Node.js 18+

2. 启动数据库

在项目根目录运行：

docker-compose up -d

这将启动 Neo4j 数据库（端口 7474/7687）。

3. 后端配置与启动

cd backend
# 创建虚拟环境
python -m venv venv
# 激活环境 (Windows)
venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt

# 配置环境变量 (复制 .env.example 并填入你的 API Key)
cp .env.example .env

# 启动服务
python -m app.main

后端服务将运行在 http://localhost:8000。

4. 前端启动

cd frontend
# 安装依赖
npm install
# 启动开发服务器
npm run dev

访问 http://localhost:5173 开始体验。

🎮 使用指南 (Usage)

1. 开始新游戏：
   • 输入一句话灵感（如“赛博朋克侦探故事”），点击 Start。
   • Architect Agent 会自动生成完整的世界观大纲、角色小传和初始谜题。
2. 游戏交互：
   • 在对话框输入行动（如“调查桌子”），或点击选项。
   • 观察控制台，可以看到 Director 如何思考并更新图谱状态。
3. 存读档：
   • 点击设置菜单 -> Save Game。存档保存于 backend/storage/saves。
   • 下次进入可直接 Load，恢复所有图谱状态和图片资源。

📂 目录结构 (Structure)

.
├── backend/
│   ├── app/
│   │   ├── api/        # Pydantic Models & Endpoints
│   │   ├── core/       # LLM Client & Prompts
│   │   └── services/   # GameEngine, KnowledgeOps, VisualResolver
│   ├── storage/        # 本地存档与图片资产
│   └── tests/          # 集成测试脚本
├── frontend/
│   ├── components/ # UI 组件 (Stage, DialogueBox)
│   ├── hooks/      # 核心逻辑 (useGameLogic, useVisualEngine)
│   └── services/   # API 通信
└── docker-compose.yml

⚠️ 常见问题 (FAQ)

• Q: 无法启动项目？

  • A: 项目没有验证过直接安装依赖来配置开发环境的情况，请检查由于疏忽没有写在后端requirements.txt中的依赖。

• Q: 图片加载失败？

  • A: 确保后端正常运行，且 backend/storage 目录有写入权限。

• Q: Neo4j 连接失败？

  • A: 检查 Docker 是否运行，以及 .env 中的端口配置（默认 17687）。

📜 License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.