AI-Gamble：AI驱动的开源动态互动小说游戏生成器，沉浸式分支叙事与可视化故事线路

一、AI-Gamble是什么

AI-Gamble是一个开源的AI动态互动小说游戏生成器，核心依托大型语言模型（LLM）的强大生成能力，为用户打造“选择决定剧情”的沉浸式阅读体验。简单来说，它不是传统的固定剧情小说，而是一个能根据用户选择实时调整故事走向、生成独特内容的“智能故事引擎”。

项目以“未知与互动”为核心设计理念，用户只需选择心仪的故事类型（如东方玄幻、西方魔幻等），系统便会自动生成专属的故事开篇、虚拟作家、个性化书名，以及一张可视化的故事发展线路图。在阅读过程中，用户的每一次选择都会触发剧情分支切换，最终导向不同的结局，彻底打破传统小说“单向阅读”的局限，让用户从“读者”转变为“剧情主导者”。

作为开源项目，AI-Gamble的全部代码均公开在GitHub仓库中，支持开发者基于现有框架进行二次开发、功能拓展或技术学习。项目采用容器化部署方案，普通用户也能通过简单配置快速在本地运行，无需复杂的环境搭建流程。其本质是“AI生成技术”与“互动叙事模式”的结合，既保留了文学阅读的趣味性，又融入了游戏的互动性和探索性。

二、功能特色

AI-Gamble的核心竞争力在于其“AI驱动的动态互动体验”，围绕这一核心，项目设计了五大核心功能，覆盖从故事生成到阅读交互的全流程，具体如下：

1. 动态故事生成：AI主导的剧情创作

故事的核心内容完全由AI驱动生成，无需人工预设完整剧情。用户选择故事类型（如“东方玄幻”“西方魔幻”“都市悬疑”等）后，系统会调用OpenAI GPT，根据所选类型的文学特点、叙事逻辑，实时创作故事的开篇、情节发展节点及多重结局。

生成的故事具有高度独特性，即使选择同一故事类型，每次开启新游戏都会得到不同的剧情框架、人物设定和情节细节。例如选择“西方魔幻”类型，可能一次生成“骑士拯救被诅咒的王国”的剧情，另一次则是“巫师寻找失落的远古魔法”，彻底避免重复体验，保证每一次游戏都充满新鲜感。

2. 随机化作家与作品：增强代入感与趣味性

为了提升沉浸感，项目加入了“随机化虚拟作家与书名”功能。每次启动新游戏时，系统会根据所选故事类型，生成符合该类型风格的虚拟作家名称（如东方玄幻类型可能生成“墨尘子”，西方魔幻类型可能生成“艾琳娜·晨星”）和专属书名（如《玄脉觉醒：万域争锋》《暗影森林的魔法契约》）。

这一设计让每一次互动阅读都像开启一本“全新出版”的小说，虚拟作家的设定也让故事多了一层“专属创作”的仪式感，进一步拉近用户与故事的距离，提升整体体验的趣味性。

3. 可视化故事线路图：直观掌握剧情脉络

这是AI-Gamble的标志性功能之一。在游戏启动之初，后端会通过AI预先生成整个故事的完整结构（包括所有可能的分支节点和结局），并以“故事线路图（Story Map）”的形式通过Mermaid.js在前端渲染展示。

用户可以在阅读过程中随时查看线路图，直观了解当前所处的剧情节点、已解锁的分支、未探索的剧情方向以及最终可能达成的结局。这一设计既解决了传统分支叙事游戏“剧情混乱、忘记分支走向”的问题，又能激发用户的探索欲，促使其反复体验不同分支，解锁全部结局。

4. 分支叙事：选择决定故事走向

互动性的核心体现的分支叙事机制。在故事的关键节点，系统会给出2-3个不同的选择（如“选择与骑士同行”“独自潜入城堡”“与神秘人交易”），用户的选择会直接影响后续剧情的发展方向。

每个选择对应的剧情分支都是由AI独立生成的，确保分支之间的差异性和逻辑性——不同选择可能会遇到不同的人物、触发不同的事件，甚至改变故事的核心冲突和最终结局。例如在“都市悬疑”类型中，选择“相信警方”可能导向“法治解决”的结局，选择“私下调查”可能触发“危险对峙”的剧情，选择“与嫌疑人谈判”则可能解锁“反转真相”的结局。

5. 动态写作风格：风格与类型高度匹配

AI会根据用户选择的故事类型，自动生成对应的写作风格描述，并将其应用于整个故事的叙述中。例如：

• 东方玄幻类型：采用古风古韵的语言，多用“玄脉”“宗门”“法器”等专属词汇，叙事节奏偏恢弘大气；

• 西方魔幻类型：语言带有欧式奇幻风格，常用“魔法卷轴”“精灵族”“黑暗领主”等元素，叙事注重场景氛围感；

• 都市悬疑类型：语言简洁明快，多用心理描写和细节铺垫，营造紧张刺激的悬疑氛围。

动态写作风格的设计让故事的“代入感”进一步提升，避免了“所有类型故事一个语调”的违和感，让用户在阅读不同类型故事时，能获得对应的文学体验。

核心功能总结表

三、技术细节

AI-Gamble的技术架构围绕“高效、稳定、易部署”设计，采用前后端分离模式，结合AI生成能力与容器化技术，构建了完整的技术生态。以下从技术栈、项目结构、工作流程、API端点四个维度详细解析：

1. 核心技术栈

项目的技术栈覆盖后端、前端、AI引擎、部署四大模块，每个模块均选用成熟、高效的技术方案，具体如下表所示：

2. 项目结构

项目采用清晰的目录结构设计，便于开发者理解、维护和二次开发，核心目录如下（基于项目文档中的结构说明展开）：

.
├── app/        # FastAPI后端应用核心代码（整个项目的核心目录）
│  ├── api/      # API路由和端点定义，包含游戏创建、选择提交等接口的实现
│  ├── crud/      # 数据库增删改查（CRUD）操作，负责故事元数据、游戏状态的存储与读取
│  ├── models/     # SQLAlchemy数据模型，定义数据库表结构（如游戏表、故事元数据表等）
│  ├── schemas/    # Pydantic数据校验模型，确保API请求与响应的数据格式合规
│  ├── services/    # 核心业务逻辑层，包含故事生成、线路图构建等核心功能的实现
│  ├── main.py     # FastAPI应用入口，初始化服务、注册路由、连接数据库等
│  └── database.py   # 数据库连接与初始化配置，定义数据库URL、会话创建等
├── static/       # 静态文件目录，存放CSS、JavaScript、图片等前端资源
├── templates/     # HTML模板目录，存放前端页面的基础模板（如游戏主页面、故事展示页面）
├── .env.example    # 环境变量示例文件，包含OpenAI API密钥、数据库URL等配置项的示例
├── .gitignore     # Git版本控制忽略文件配置，指定无需提交的文件（如.env、依赖包目录等）
├── DESIGN.md      # 系统设计文档，详细说明项目的设计思路、架构图、核心流程等
├── docker-compose.yml # Docker服务编排配置，定义后端、数据库、缓存等服务的启动规则
├── Dockerfile     # Web服务的Docker镜像配置，指定镜像构建的基础环境、依赖安装步骤等
├── README.md      # 项目说明文档，包含项目介绍、快速开始、功能说明等（用户与开发者入门指南）
├── main.py       # 项目入口文件（根目录），初始化后端服务
├── package-lock.json  # npm依赖锁定文件，确保前端样式编译的依赖版本一致
├── package.json    # npm配置文件，定义前端样式编译（Tailwind CSS）的脚本命令
├── requirements.txt  # Python依赖包列表，包含FastAPI、SQLAlchemy等后端依赖
└── tailwind.config.js # Tailwind CSS配置文件，自定义前端样式主题、工具类等

3. 核心工作流程

AI-Gamble的核心工作流程围绕“用户选择→AI生成→前端展示”展开，从用户点击“开始游戏”到看到剧情内容，涉及前端、后端、AI引擎、数据库等多个模块的协同工作，具体流程如下（结合项目文档中的序列图详细说明）：

1. 用户发起操作：用户在前端页面选择故事类型（如“东方玄幻”），点击“开始游戏”按钮，触发互动流程。

2. 前端请求后端：前端（Vanilla JavaScript）通过POST请求调用/api/v1/game接口，将用户选择的故事类型传递给后端（FastAPI）。

3. 后端调用故事生成服务：后端接收到请求后，调用核心业务逻辑层（services/）的generate_initial_scene()方法，启动故事初始化流程。

4. AI生成故事结构：故事生成服务向AI大语言模型（OpenAI GPT）发送指令，请求生成该故事类型对应的“完整故事结构”（包含开篇剧情、潜在分支节点、结局、写作风格、虚拟作家、书名等），并以JSON格式返回。

5. 存储故事元数据：故事生成服务将AI返回的虚拟作家、书名、故事线路图等元数据，通过CRUD模块存入数据库（由SQLAlchemy & SQLModel负责交互）。

6. 返回初始数据给前端：故事生成服务提取AI生成的“初始场景”剧情，连同数据库中存储的元数据（game_id、作家名、书名、故事线路图JSON）一起，通过后端接口返回给前端。

7. 前端渲染与展示：前端接收数据后，一方面通过Mermaid.js将故事线路图JSON渲染为可视化图表，另一方面将初始场景剧情、作家名、书名展示在页面上，完成整个初始化流程。

8. 后续分支交互：用户阅读初始场景后选择剧情分支，前端通过/api/v1/game/{game_id}/choice接口提交选择，后端重复“调用AI生成对应分支剧情→存储状态→返回数据”的流程，实现剧情的动态推进。

整个流程中，Redis作为SSE消息队列保障实时通信，确保AI生成剧情时前端能快速接收数据；数据库则负责持久化存储游戏状态，方便用户后续再次访问同一游戏（通过game_id查询）。

4. API端点说明

项目提供了一组RESTful API接口，用于管理游戏的创建、推进、查询与删除，接口设计简洁明了，便于前端调用或开发者二次开发，具体如下表所示：

这些API接口覆盖了游戏从创建到结束的全生命周期，开发者可基于这些接口拓展功能（如添加游戏存档、分享剧情等）。

四、应用场景

AI-Gamble的核心是“AI驱动的互动叙事”，其应用场景覆盖个人娱乐、创作辅助、技术学习等多个维度，既适合普通用户使用，也能为开发者、教育者提供价值：

1. 个人娱乐场景

这是最核心的应用场景。对于喜欢阅读、追求新鲜体验的用户来说，AI-Gamble提供了“永不重复”的互动阅读体验。用户可以根据自己的兴趣选择故事类型，在碎片化时间里（如通勤、休息时）开启一段剧情，通过选择主导故事走向，解锁不同结局。

相比传统小说，它更具互动性和探索欲；相比商业互动游戏，它无需下载庞大的安装包，通过浏览器即可访问，且剧情由AI生成，没有固定套路，适合喜欢“未知感”的用户。例如：

• 通勤时开启一段10分钟的“都市悬疑”剧情，利用碎片时间体验推理乐趣；

• 周末深入体验“西方魔幻”长篇剧情，反复选择不同分支，解锁所有隐藏结局。

2. 文学创作辅助场景

对于小说作者、编剧等创作者来说，AI-Gamble可作为“灵感工具”。创作者可以通过选择故事类型，让AI生成基础剧情框架和分支节点，从中获取创作灵感；也可以输入自定义的故事设定（如“主角是拥有时间回溯能力的医生”），让AI生成相关剧情，作为自己创作的参考。

例如，一位玄幻小说作者卡在“剧情分支设计”上，可通过AI-Gamble生成同类型故事的分支结构，参考其逻辑脉络；一位编剧需要快速构思多个短剧结局，可通过多次选择不同分支，获取AI生成的结局方案，再进行二次加工。

3. 教育与创意培养场景

在教育领域，AI-Gamble可用于“创意写作教学”或“逻辑思维培养”。例如：

• 中小学语文课堂：老师让学生选择故事类型，通过多次选择分支并观察剧情变化，理解“情节因果关系”，再让学生基于AI生成的框架，自己续写剧情，锻炼创意写作能力；

• 逻辑思维训练：学生在选择分支时，需要分析不同选择可能带来的后果（通过可视化线路图辅助），培养逻辑推理能力和决策思维。

此外，项目的开源属性也适合作为“编程教学案例”，让学生了解前后端分离、AI接口调用、容器化部署等技术的实际应用。

4. 开发者技术学习场景

对于想要学习AI应用开发、前后端分离、Docker部署的开发者来说，AI-Gamble是一个优质的开源学习案例。项目包含：

• AI大语言模型接口调用（OpenAI GPT）的实际应用；

• FastAPI框架的完整实践（路由设计、数据校验、数据库交互）；

• 前端原生JS与后端API的交互逻辑；

• Tailwind CSS的样式开发；

• Docker容器化部署的完整配置。

开发者可以通过阅读源码、运行项目、修改功能，快速掌握这些技术的核心用法，甚至基于项目进行二次开发（如集成其他AI模型、添加多语言支持等）。

5. 线上社区与活动场景

线上社区、游戏公会或品牌方可以利用AI-Gamble举办互动活动。例如：

• 社区发起“共同创作故事”活动，让用户轮流提交分支选择，共同推进一段剧情，最终生成社区专属故事；

• 品牌方定制专属故事类型（如结合品牌理念的“环保主题玄幻故事”），让用户在互动阅读中了解品牌，提升品牌好感度。

五、安装使用方法

AI-Gamble采用Docker容器化部署，简化了环境搭建流程，普通用户无需具备专业的编程知识，只需按照以下步骤操作，即可在本地运行项目：

1. 先决条件

在开始前，需确保本地环境已安装以下工具：

• Docker：用于构建和运行容器（支持Windows、macOS、Linux系统）；

• Docker Compose：用于编排多个服务（后端、数据库、缓存等），通常随Docker一起安装；

• 浏览器：用于访问应用（推荐Chrome、Firefox、Edge等现代浏览器）；

• OpenAI API密钥：用于调用GPT模型生成故事，需提前在OpenAI官网申请。

2. 配置步骤

步骤1：获取项目源码

首先，需要将项目源码克隆到本地。打开终端（Windows用命令提示符或PowerShell，macOS/Linux用终端），执行以下命令：

git clone https://github.com/xiamuceer-j/AI-Gamble.git

克隆完成后，进入项目根目录：

cd AI-Gamble

步骤2：创建并配置环境变量文件

项目使用.env文件管理敏感配置（如OpenAI API密钥），项目提供了示例文件.env.example，需基于该文件创建自己的.env文件：

• Windows系统：在终端中执行以下命令，复制示例文件为.env：

  copy .env.example .env

• macOS/Linux系统：在终端中执行以下命令：

  cp .env.example .env

创建完成后，用文本编辑器（如记事本、VS Code）打开.env文件，修改以下核心配置项：

• OPENAI_API_KEY=your_api_key：将your_api_key替换为你自己的OpenAI API密钥；

• 其他配置项（如数据库URL、Redis配置、服务端口等）可保持默认，若需自定义（如修改访问端口），可根据注释说明修改。

3. 启动项目

步骤1：构建并启动Docker服务

在项目根目录下，执行以下Docker Compose命令，构建镜像并启动所有服务：

docker-compose up --build

• 该命令会自动下载所需的基础镜像（如Python、Redis等），安装项目依赖，启动后端服务、数据库、Redis缓存等；

• 首次运行时，由于需要下载镜像和依赖，耗时可能较长（取决于网络速度），请耐心等待；

• 启动成功后，终端会显示各服务的运行日志，若没有报错（如“ERROR”“Failed”等提示），则说明服务启动正常。

步骤2：编译前端样式（可选）

如果不需要修改前端样式，可跳过此步骤，直接访问应用。若需要自定义前端样式（如修改颜色、字体），则需额外启动前端样式编译服务：

打开一个新的终端（保持之前的终端运行，不要关闭），进入项目根目录，执行以下命令：

# 先安装前端依赖（仅首次需要）
npm install
# 启动样式编译服务，实时监听Tailwind CSS文件修改
npm run build

该命令会启动Tailwind CSS的编译服务，实时将修改后的样式文件编译为静态CSS，确保前端页面能及时显示修改效果。

步骤3：访问应用

打开浏览器，在地址栏输入以下地址，即可进入AI-Gamble应用：

http://localhost:1888

若在.env文件中修改了服务端口，则需将1888替换为修改后的端口。

步骤4：开始互动阅读

进入应用后，操作流程如下：

1. 在首页选择喜欢的故事类型（如“东方玄幻”“西方魔幻”“都市悬疑”）；

2. 点击“开始游戏”按钮，系统会自动生成虚拟作家、书名、初始剧情和可视化故事线路图；

3. 阅读初始剧情后，在关键节点选择心仪的分支选项；

4. 系统会根据选择生成下一段剧情，同时更新故事线路图，展示当前所处节点；

5. 重复步骤3-4，直到达成某个结局；

6. 若想重新体验，可返回首页选择新的故事类型，或删除当前游戏会话，重新开始。

4. 关闭项目

若需关闭应用，只需回到启动Docker服务的终端，按下Ctrl + C组合键，即可停止所有服务。若需彻底删除容器和镜像，可执行以下命令（可选）：

# 停止并删除容器、网络
docker-compose down
# 若需删除镜像，执行以下命令（替换镜像名，可通过docker images查看）
docker rmi ai-gamble-web

六、常见问题解答（FAQ）

1. 启动项目时提示“OpenAI API密钥错误”，该怎么办？

• 检查.env文件中的OPENAI_API_KEY是否正确，确保没有多余的空格或符号；

• 确认API密钥是否有效，可登录OpenAI官网查看密钥状态（是否过期、是否有足够的额度）；

• 若使用的是代理服务器，需在.env文件中添加代理配置（如OPENAI_BASE_URL=你的代理地址），确保后端能正常访问OpenAI接口。

2. 启动后访问http://localhost:1888无法打开页面，可能是什么原因？

• 检查Docker服务是否启动成功，终端是否有“端口被占用”的报错（如“port 1888 is already allocated”），若有，需修改.env文件中的PORT配置（如改为1889），重新执行docker-compose up --build；

• 确认浏览器是否支持Mermaid.js（推荐使用现代浏览器，避免使用IE等老旧浏览器）；

• 检查本地防火墙是否阻止了该端口的访问，可暂时关闭防火墙后重试。

3. 故事生成速度很慢，该如何优化？

• 故事生成速度主要取决于OpenAI API的响应速度，可尝试更换网络环境（如使用更快的网络）；

• 若使用的是GPT-4模型，可在.env文件中修改为GPT-3.5模型（如OPENAI_MODEL=gpt-3.5-turbo），GPT-3.5的响应速度更快，且成本更低；

• 检查Redis服务是否正常运行（终端日志中是否有Redis相关报错），Redis作为缓存和消息队列，异常会影响生成效率。

4. 修改前端样式后，页面没有生效，该怎么办？

• 确保已执行npm install安装前端依赖，且npm run build命令正在运行（实时监听样式修改）；

• 清除浏览器缓存（按Ctrl + Shift + R强制刷新），避免浏览器加载旧的样式文件；

• 检查tailwind.config.js配置是否正确，确保自定义样式已添加到配置中。

5. 能否自定义故事类型（如添加“科幻末世”“古风言情”类型）？

• 可以。需修改后端services/目录下的故事生成逻辑，添加新的故事类型描述（如“科幻末世”的核心元素、写作风格）；

• 在前端页面的“故事类型选择”模块，添加新的类型选项，确保前端能将新类型参数传递给后端；

• 若需让AI更精准地生成对应类型的故事，可在调用OpenAI API时，增加该类型的专属提示词（Prompt）。

6. 如何保存游戏进度，下次继续玩？

• 项目会自动将游戏状态存储在数据库中，每个游戏对应一个唯一的game_id；

• 下次访问应用时，可通过调用GET /api/v1/game/{game_id}接口（或在前端添加对应的“加载游戏”功能），查询并恢复之前的游戏进度；

• 若未手动删除游戏（调用DELETE接口），游戏状态会一直保存在数据库中。

7. 项目支持部署到服务器上，供多人访问吗？

• 支持。只需在服务器上安装Docker和Docker Compose，按照本地运行的步骤配置环境变量、启动服务；

• 确保服务器开放对应的端口（如1888），并配置防火墙规则，允许外部访问；

• 若访问人数较多，可优化Redis缓存配置、增加服务器资源（CPU、内存），确保服务稳定。

七、相关链接

• 项目GitHub仓库：https://github.com/xiamuceer-j/AI-Gamble

八、总结

AI-Gamble是一款基于LLM的开源动态互动小说游戏，核心依托OpenAI GPT的生成能力，结合FastAPI、Tailwind CSS、Docker等成熟技术，构建了“动态故事生成、分支叙事、可视化线路图”三大核心亮点，为用户提供了从“被动阅读”到“主动主导”的沉浸式体验。项目的功能设计兼顾了趣味性与实用性，既适合普通用户作为娱乐工具，也能为创作者、教育者、开发者提供价值；容器化部署方案降低了使用门槛，开源属性则为二次开发提供了无限可能。无论是想体验新鲜的互动阅读，还是学习AI应用开发、前后端分离技术，AI-Gamble都是一个值得尝试的优质项目。