AI智能体驱动的修仙世界模拟器：规则与LLM融合的自主演化系统

1. 项目概述：一个由AI驱动的修仙世界模拟器

如果你和我一样，是个修仙小说迷，同时又对AI技术充满好奇，那么“修仙世界模拟器”这个项目，绝对会让你眼前一亮。它不是一个传统的、由开发者预设好所有剧情和任务的角色扮演游戏，而是一个真正意义上“活”着的世界。在这个世界里，每一个修士、每一个宗门，甚至每一场冲突，都是由底层规则和大型语言模型（LLM）共同驱动、自主演化出来的。你扮演的，不再是某个具体的修士，而是俯瞰众生、执掌规则的“天道”。

这个项目的核心魅力在于“涌现”。开发者搭建了一个严谨的修仙世界观框架，包括灵根、境界、功法、宗门、寿元等规则，然后将一个个由LLM驱动的智能体（Agent）投入其中。这些智能体拥有独立的性格、记忆和目标，他们会根据自己感知到的世界状态，做出修炼、社交、战斗、探索等决策。你永远无法预知下一秒会发生什么：一个默默无闻的外门弟子可能因一场奇遇而顿悟，两个交好的宗门可能因资源争夺而反目成仇，一场突如其来的天劫可能改变整个世界的格局。这种不确定性带来的沉浸感和故事性，是传统脚本游戏无法比拟的。

从技术角度看，它是一个典型的“AI原生”应用，完美融合了游戏模拟、智能体工作流和提示工程。后端使用Python和FastAPI构建模拟引擎，前端用Vue和TypeScript呈现动态世界，并通过PixiJS渲染地图。对于开发者而言，它提供了清晰的源码结构和API，便于二次开发；对于普通玩家，则提供了Docker一键部署的便捷体验。接下来，我将从设计思路、核心实现、实操部署到深度玩法，为你完整拆解这个迷人的项目。

2. 核心设计思路：规则与自由的精妙平衡

2.1 为何选择“规则+AI”的双驱动模式？

纯粹依赖LLM生成一个持续、稳定的虚拟世界是极其困难的。LLM擅长创造和联想，但缺乏持久的记忆和严谨的逻辑一致性，容易产生“幻觉”，导致世界设定崩坏或角色行为逻辑混乱。例如，一个角色可能上一秒还在练气期，下一秒就自称元婴老祖，这显然破坏了修仙体系的根基。

因此，项目采用了“规则为骨，AI为魂”的设计哲学。规则系统构成了世界的物理法则和基本逻辑，它确保：

• 数值稳定性：境界提升需要积累修为，战斗胜负基于属性计算，资源产出遵循经济规律。
• 因果一致性：角色的行动会产生明确且可追溯的结果，例如修炼会增长修为，战斗会消耗灵力。
• 框架约束：为AI的想象力划定一个合理且丰富的“沙盒”，防止其过度发散。

而AI系统则负责为世界注入灵魂，它赋予每个NPC：

• 人格与动机：每个角色有独特的性格（如谨慎、豪爽、阴险）、短期目标（如获取某件法宝）和长期追求（如飞升成仙）。
• 情境化决策：NPC会根据当前环境、自身状态和人际关系，实时决定下一步做什么。比如，一个性格“贪婪”的修士在秘境中看到宝物，更可能选择抢夺而非分享。
• 涌现式叙事：无数个拥有独立意志的个体在规则框架内互动，自然衍生出剧本无法编写的复杂剧情，如宗门联盟的建立与瓦解、跨越数代的恩怨情仇。

这种设计实现了“可控的涌现”。世界的发展既不受开发者完全掌控（有惊喜），也不会陷入完全的混沌无序（有逻辑）。

2.2 智能体工作流的设计解析

项目中每个修士都是一个独立的智能体，其决策循环是核心。一个典型的Agent工作流可以概括为“感知-思考-行动-结算”的循环。

1. 感知：智能体首先获取其“感知范围”内的世界状态。这包括自身属性（健康、灵力、位置）、周围环境（所在地块类型、灵气浓度、附近其他角色）、所属组织状态（宗门资源、任务）以及近期世界大事件（如拍卖会公告）。
2. 思考：将感知到的信息，结合自身的长期记忆（过往经历、人际关系）和性格特质，通过LLM生成一个“思考链”。这个过程通常由一个精心设计的提示词驱动，引导AI分析现状、评估目标、权衡选项。例如：“你是一名筑基中期的剑修，性格孤傲。当前灵力充沛，但缺少一柄趁手的飞剑。感知到三百里外将举办一场拍卖会，其中有一柄‘青霜剑’拍卖。你的长期目标是结成金丹。请问你接下来打算做什么？”
3. 行动：根据思考结果，智能体从系统预定义的动作库中选择一个动作执行，如“前往拍卖会”、“就地打坐修炼”、“向同门师兄打听消息”。动作库是规则系统的一部分，确保了行动的可执行性和结果的可计算性。
4. 结算：世界引擎处理这个动作，更新游戏状态。例如，选择“前往拍卖会”会消耗游戏内时间，并可能触发“抵达拍卖会”事件，进入另一个决策节点。

提示：这里的LLM调用并非每次决策都进行，项目采用了“协程化决策机制”进行优化。简单说，就是将大量AI决策请求异步化、批量处理，并利用多线程加速，避免因等待单个AI响应而卡住整个世界的时间流逝。对于简单、高频的决策（如移动路径选择），可能会降级使用更快的规则AI或小模型。

2.3 天道视角与干预系统的设计考量

与传统RPG的“主角视角”不同，本项目让玩家扮演“天道”。这是一个非常巧妙的设计，它解决了几个关键问题：

• 降低认知负荷：玩家无需管理单个角色的繁琐属性和背包，而是从宏观层面观察世界演变，关注更有趣的势力消长和传奇故事。
• 增强叙事自由度：由于玩家不是故事中的角色，因此可以毫无心理负担地“干预”世界，比如给看顺眼的天才降下一场机缘，或者给魔道宗门制造一场天劫，观察其连锁反应，而不用担心“角色死亡”导致游戏结束。
• 契合模拟经营乐趣：天道视角更像是在经营一个动态的、充满故事性的沙盘，满足了玩家作为“世界观察者”和“幕后操纵者”的双重快感。

干预系统通过一套清晰的API暴露给玩家和外部程序。你可以通过前端UI进行手动干预，也可以通过调用/api/v1/command/下的接口进行自动化、程序化的干预，这为高级玩法和二次开发打开了大门。

3. 环境部署与核心配置实战

无论你是想体验还是开发，第一步都是把项目跑起来。项目提供了源码和Docker两种方式，我强烈建议开发者使用源码部署，便于调试和修改。

3.1 源码部署详解与避坑指南

假设你的开发环境是Windows（WSL2/Linux或macOS类似），以下是详细步骤：

第一步：克隆代码与前置准备

git clone https://github.com/4thfever/cultivation-world-simulator.git cd cultivation-world-simulator

确保你的Python版本在3.10或以上，Node.js版本在18或以上。可以使用python --version和node --version检查。

第二步：安装后端依赖后端依赖管理相对简单，但需要注意网络环境。

# 建议先升级pip并创建虚拟环境 python -m venv venv # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt

常见问题1：如果遇到某些包（如uvloop）安装失败，通常是编译环境问题。在Windows上，可以尝试安装 Microsoft C++ Build Tools 。或者，对于非必须的性能依赖，可以临时注释掉requirements.txt中相关行。常见问题2：httpx、aiohttp等网络库下载慢。可以配置国内镜像源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

第三步：安装前端依赖并构建前端依赖包较多，下载需要耐心。

cd web npm install

常见问题3：npm install卡住或失败。首先检查Node.js版本，其次可以切换npm镜像源：npm config set registry https://registry.npmmirror.com，然后删除node_modules和package-lock.json，重新执行npm install。

第四步：启动开发服务器回到项目根目录，运行：

python src/server/main.py --dev

这个--dev参数是关键，它会同时启动FastAPI后端服务器和Vite前端开发服务器。控制台会输出类似以下信息：

后端服务器运行在： http://127.0.0.1:8000 前端开发服务器运行在： http://localhost:5173 自动打开浏览器中...

此时，浏览器应自动打开http://localhost:5173。如果没有，请手动访问。

3.2 模型配置：项目的“灵魂”注入

项目启动后，最重要的一步是配置LLM模型。没有模型，所有NPC都将失去“灵魂”，世界无法演化。

1. 进入前端页面后，你应该会看到游戏主界面或设置界面。找到“设置”（通常是一个齿轮图标）。
2. 在设置中，找到“模型配置”或“LLM设置”部分。
3. 项目预设支持多种模型服务，你需要至少配置一个可用的：
   • DeepSeek/智谱AI等国内模型：你需要填入从对应平台申请的API Key和Base URL。
   • Ollama（本地运行）：如果你在本地运行了Ollama并拉取了如qwen2.5:7b之类的模型，可以将Base URL设置为http://localhost:11434/v1，API Key填ollama。
   • OpenAI格式兼容API：任何提供了兼容OpenAI接口的服务都可以，只需正确填写URL和Key。

配置示例（以Ollama本地模型为例）：

• 模型名称：qwen2.5:7b
• API Key：ollama
• Base URL：http://localhost:11434/v1

核心技巧：首次配置并成功测试连接后，设置会自动保存到用户数据目录（如Windows的AppData下）。这意味着下次启动时无需重复配置。对于开发者，建议初期使用响应速度较快的模型（如DeepSeek的快速模型），以便更快地进行调试和迭代。

3.3 Docker部署：最快捷的体验方式

对于只想快速体验、不关心代码的玩家，Docker是最佳选择。它封装了所有环境依赖，真正做到开箱即用。

# 1. 确保已安装Docker和Docker Compose # 2. 克隆项目 git clone https://github.com/4thfever/cultivation-world-simulator.git cd cultivation-world-simulator # 3. 一键启动 docker-compose up -d --build

启动完成后，访问http://localhost:8123即可。

Docker部署的注意事项：

• 数据持久化：容器内的用户数据（设置、存档、日志）通过卷映射保存在宿主机的./docker-data目录下。即使你删除并重建容器，这些数据也不会丢失。
• 模型配置仍需手动：Docker只解决了环境问题，LLM模型的API配置仍然需要你在启动后的Web界面中手动完成，步骤同源码部署。
• 性能考量：如果打算在Docker内运行本地大模型（如通过Ollama），需要确保宿主机有足够的GPU资源，并在docker-compose.yml中正确配置GPU透传（deploy.resources.reservations.devices），这相对复杂。对于初体验，更推荐使用云端的API模型。

4. 核心系统深度解析与二次开发指引

4.1 世界引擎与事件系统：时间如何流淌

世界的运转核心是一个离散事件驱动的引擎。游戏时间被划分为“刻”、“时”、“日”、“月”、“年”。每个“刻”是最小时间单位，引擎会推动所有活跃的智能体进行一轮“感知-思考-行动”循环。

关键目录：src/server/core/world.py和src/server/core/event.py

世界状态（WorldState）是一个全局单例，它维护着：

• 全局时间：当前游戏日期。
• 实体集合：所有角色（Avatar）、区域（Region）、宗门（Sect）的引用。
• 事件队列：一个按触发时间排序的优先队列。事件分为：
  • 定时事件：如每月初的“灵气潮汐”，每年的“天下武道会”。
  • 条件事件：当满足特定条件时触发，如某个区域修士数量超过阈值触发“洞府出世”。
  • 干预事件：由玩家（天道）或外部API调用触发的事件，如“降下天劫”。

引擎的主循环大致如下：

# 伪代码，展示逻辑 while world.is_running: # 1. 推进游戏时间 world.tick() # 2. 处理到期事件 current_events = event_queue.pop_until(world.current_time) for event in current_events: event.trigger() # 触发事件，可能产生新动作或修改世界状态 # 3. 驱动所有活跃Agent并行决策（协程化） tasks = [avatar.act() for avatar in active_avatars] results = await asyncio.gather(*tasks) # 4. 结算所有动作结果 for result in results: world.apply_action_result(result) # 5. 更新前端状态（通过WebSocket） broadcast_world_update()

这种设计保证了世界的并发性和扩展性。添加新的事件类型或动作类型，只需要实现相应的类并注册到系统中即可。

4.2 角色系统与AI决策：修士如何“思考”

角色（Avatar）是世界的核心。其数据结构定义在src/server/models/avatar.py中，包含大量属性。

属性系统：

• 基础属性：力量、敏捷、灵力、根骨等，影响战斗、修炼效率。
• 境界系统：从练气、筑基、金丹到元婴、化神，每一层都有修为上限和突破瓶颈。
• 灵根系统：金、木、水、火、土、变异灵根，决定功法契合度和修炼速度。
• 特质与性格：由一组标签（如[“谨慎”， “重情”， “贪婪”]）描述，这些标签会作为上下文注入LLM提示词，深刻影响其决策倾向。

AI决策流程详解： 决策的入口通常在src/server/agents/avatar_agent.py的act方法中。一次完整的决策包含以下步骤：

1. 信息收集：调用get_perception()方法，收集角色视野内的所有相关信息。
2. 提示词构建：这是提示工程的核心。系统会从一个模板（如prompts/avatar_decision.jinja2）渲染出最终的提示词。模板中会插入：
   • 角色当前状态（属性、位置、装备）。
   • 短期记忆（最近几条经历）。
   • 长期目标。
   • 性格特质。
   • 感知到的环境信息。
   • 可用的动作列表及其规则描述。
3. 调用LLM：将构建好的提示词发送给配置的LLM，要求其以指定格式（通常是JSON）返回决策理由和选择的行为。
4. 动作解析与验证：解析LLM的返回结果，映射到系统预定义的动作（如action_move,action_meditate）。系统会验证该动作在当前状态下是否合法（例如，灵力不足无法施展某些法术）。
5. 执行与记录：执行动作，并将此次决策的关键信息（思考过程、选择的行为）存入角色的短期记忆，用于影响下一次决策。

实操心得：调试AI行为时，最有效的方法是查看日志。项目通常会将每个角色的决策提示词和LLM回复记录在日志文件中。当你发现某个角色的行为异常时，通过日志可以判断是提示词设计问题、LLM理解偏差，还是动作结算逻辑有Bug。

4.3 经济与物品系统：世界的运转基石

一个自洽的世界离不开经济系统。项目中的物品系统相对简洁但足够支撑起一个基本的经济循环。

物品分类：

• 消耗品：丹药（回复灵力、治疗伤势、辅助突破）、符箓（一次性效果）。
• 装备：武器（飞剑、法杖）、防具（道袍、内甲）、饰品（玉佩、戒指）。装备有品阶（凡、灵、宝、仙）和属性加成。
• 材料：草药、矿石、兽骨，用于炼丹和炼器。
• 货币：灵石。是修炼、交易、布阵的通用等价物。

交易机制： 交易主要通过“市场”区域和“拍卖会”大事件完成。

• 市场：每个城市区域有一个市场，NPC会根据自身需求（如需要某种丹药突破）和财产，发布买入或卖出订单。价格受供需关系影响有一个简单的浮动算法。
• 拍卖会：定期举行的全服事件，稀有物品会在这里出现。NPC会评估物品对自己的价值，并基于自身财力出价。这里往往能上演精彩的财力与心机的对决。

资源产出与消耗：

• 产出：通过“采集”、“狩猎”、“采矿”等生活技能从地图资源点获取。
• 消耗：修炼消耗灵石（聚灵阵）、炼丹炼器消耗材料、战斗消耗丹药和符箓。 这个循环驱动着NPC们去工作、交易、争夺，构成了世界动态的基础。

5. 高级玩法与API深度集成

当你熟悉了基本操作后，可以通过API将模拟器的能力集成到自己的自动化脚本或外部应用中，实现更高级的“天道”玩法。

5.1 外部控制API详解

项目提供了稳定的/api/v1/命名空间下的RESTful API，分为查询和命令两大类。

查询接口：用于获取世界状态，不会改变游戏。

• GET /api/v1/query/runtime/status：获取模拟器运行状态（是否运行、速度、当前时间）。
• GET /api/v1/query/world/state：获取世界概要（宗门列表、顶尖修士、近期大事件）。
• GET /api/v1/query/events：获取事件流，即世界日志。
• GET /api/v1/query/detail?type=avatar&id=<id>：获取指定角色的详细信息。

命令接口：用于干预世界，改变游戏进程。

• POST /api/v1/command/game/start：开始新游戏或加载存档。
• POST /api/v1/command/game/pause：暂停/继续游戏。
• POST /api/v1/command/avatar/intervene：对特定角色进行干预（如增加修为、添加特质、触发心魔）。
• POST /api/v1/command/world/trigger_event：直接触发一个世界事件（如开启一场拍卖会）。

所有成功响应格式为{"ok": true, "data": {...}}，失败则为{"ok": false, "detail": {"code": "...", "message": "..."}}。

5.2 构建一个自动化观察与干预脚本

假设你想写一个Python脚本，自动寻找“潜力股”修士并暗中资助他，可以这样操作：

import requests import time BASE_URL = "http://localhost:8000/api/v1" def find_potential_avatars(): """查找年龄小、境界提升快的潜力修士""" resp = requests.get(f"{BASE_URL}/query/world/state") world_state = resp.json()['data'] potentials = [] for avatar_id in world_state['top_avatars']: # 假设接口返回顶尖修士ID列表 detail_resp = requests.get(f"{BASE_URL}/query/detail?type=avatar&id={avatar_id}") avatar = detail_resp.json()['data'] # 简单策略：年龄<30岁，且境界在近一年内提升过 if avatar['age'] < 30 and avatar.get('recent_breakthrough'): # 计算一个潜力分数（示例） score = avatar['talent'] * 100 - avatar['age'] potentials.append((avatar_id, avatar['name'], score)) # 按分数降序排列 potentials.sort(key=lambda x: x[2], reverse=True) return potentials[:5] # 返回前5名 def intervene_avatar(avatar_id, resource_type, amount): """干预特定角色，给予资源""" payload = { "avatar_id": avatar_id, "intervention_type": "add_resource", "params": { "resource": resource_type, # 如 "spirit_stone", "pill_qi" "amount": amount } } resp = requests.post(f"{BASE_URL}/command/avatar/intervene", json=payload) return resp.json() def main_loop(): """主循环：每现实时间10分钟运行一次，寻找并资助潜力修士""" while True: print("开始扫描潜力修士...") candidates = find_potential_avatars() for avatar_id, name, score in candidates: print(f"资助修士 {name}(ID: {avatar_id})，潜力分数：{score}") # 资助1000灵石 result = intervene_avatar(avatar_id, "spirit_stone", 1000) if result['ok']: print(f" 资助成功！") else: print(f" 资助失败：{result['detail']['message']}") print("本轮干预结束，等待10分钟...\n") time.sleep(600) # 等待10分钟（现实时间） if __name__ == "__main__": # 首先确保游戏正在运行 status_resp = requests.get(f"{BASE_URL}/query/runtime/status") if not status_resp.json()['data']['is_running']: print("游戏未运行，正在启动新游戏...") start_resp = requests.post(f"{BASE_URL}/command/game/start", json={"mode": "new"}) main_loop()

这个脚本展示了如何通过API实现一个简单的“天道投资基金”自动化策略。你可以在此基础上扩展更复杂的策略，比如在正邪大战中平衡双方实力，或者专门打压某个过于嚣张的宗门。

5.3 与LangChain/AutoGen等智能体框架集成

项目的API设计使其可以轻松成为更复杂智能体工作流的一部分。例如，你可以使用LangChain创建一个更高级的“天道顾问”Agent：

1. 工具封装：将模拟器的查询和命令API封装成LangChain Tool。
2. 制定目标：给Agent一个宏观目标，如“维持世界正邪势力平衡”。
3. 自主决策：Agent会周期性地调用“查询世界状态”工具，分析当前局势（如魔道宗门实力增长过快），然后调用“触发事件”或“干预角色”工具，实施具体操作（如触发一个“正道联盟”事件，或给某个正道天才降下机缘）。
4. 观察反馈：行动后，再次查询世界状态，评估干预效果，并规划下一步。

这实现了“观察-决策-行动”的闭环，让外部的“超级AI”来扮演更复杂的天道角色，而模拟器本身则提供了一个高度拟真、反馈丰富的环境。

6. 常见问题排查与性能优化

在实际运行和开发过程中，你可能会遇到以下典型问题。

6.1 部署与启动问题

问题：前端页面空白或无法加载。

• 检查：浏览器开发者工具（F12）的Console和Network标签页，查看是否有JS报错或资源加载失败。
• 解决：
  1. 确认前端服务已正确启动（npm run dev）。
  2. 如果使用Docker，确认端口映射正确（前端默认8123）。
  3. 清除浏览器缓存或尝试无痕模式。

问题：游戏启动后，NPC不动或没有日志输出。

• 检查：后端控制台日志。重点查看LLM调用是否成功。
• 解决：
  1. 确认模型配置：在设置页面测试LLM连接是否成功。
  2. 检查API配额：如果使用云端API，可能额度已用尽或请求频率超限。
  3. 查看网络：确保后端服务能访问到你配置的LLM API地址（如api.deepseek.com）。

6.2 游戏运行与逻辑问题

问题：世界演化速度非常慢。

• 原因：这是最常见的问题，根源在于LLM API的响应速度。每个NPC每次决策都需要调用一次LLM，如果使用慢速模型或网络延迟高，游戏内时间推进就会极其缓慢。
• 优化方案：
  1. 使用更快的模型：在开发或体验时，优先选择响应速度快的API，如DeepSeek的快速模型、GPT-3.5-Turbo，或本地运行的轻量级模型（如Qwen2.5-7B-Instruct）。
  2. 调整模拟速度设置：前端通常有速度调节按钮（1x, 2x, 5x），但这只是UI更新频率，解决不了根本。需要优化后端。
  3. 启用缓存和降级：项目本身有决策缓存机制（相同情境下，NPC可能做出相同决策）。确保其开启。对于低重要性NPC，可以配置使用更便宜/更快的模型，甚至规则AI。
  4. 批量处理与异步：确认项目的“协程化决策机制”正常工作，它应该能并发处理数十个NPC的决策请求。

问题：NPC行为逻辑怪异，比如不断重复某个无意义动作。

• 检查：查看该NPC的决策日志。问题通常出在：
  1. 提示词设计：提示词未能提供足够有效的决策约束或上下文。
  2. LLM输出格式不稳定：LLM没有严格按照要求的JSON格式返回，导致动作解析失败，系统可能默认执行了一个安全但无意义的动作（如“等待”）。
  3. 动作前置条件不满足：NPC想执行动作A，但条件不满足（如灵力不足），系统又没有提供合适的备选方案。
• 解决：
  1. 优化提示词模板，加入更严格的输出格式要求和行为约束。
  2. 在代码中加强LLM响应的格式校验和错误处理，对解析失败的响应，可以给予NPC一个默认的合理行为（如“打坐恢复”），而不是卡住。
  3. 在动作定义中明确前置条件，并在提示词中告知NPC这些条件。

6.3 开发与扩展问题

问题：我想添加一个新的“动作”（比如“创立家族”），该如何入手？

1. 定义动作数据模型：在src/server/models/action.py中定义新的动作类，继承BaseAction，并实现check_prerequisites（检查前提条件）、execute（执行逻辑）、apply_results（结算结果）等方法。
2. 注册动作：在动作注册表（通常是src/server/core/action_registry.py）中注册这个新动作，使其能被系统识别和调用。
3. 暴露给AI：修改AI决策的提示词模板，将新动作的描述和规则加入到“可用动作列表”中。
4. 提供前端交互：如果希望玩家（天道）也能触发此动作，需要在对应的前端组件（如角色干预面板）中添加UI元素，并调用后端的命令接口。

问题：存档文件损坏或无法加载。

• 预防：定期备份存档文件。存档位置通常在用户数据目录下的saves/文件夹。
• 处理：尝试使用项目可能提供的存档修复工具（如果有）。或者，手动检查存档文件（JSON格式）的结构是否完整。最坏情况是回退到上一个自动备份的存档。

这个项目就像一个数字生态缸，你赋予它规则和初始条件，然后观察其中生命如何自行演化、竞争、合作、诞生传奇。它的魅力不在于通关，而在于观察和讲述那些由算法与规则共同谱写出的、独一无二的故事。无论是作为玩家体验“天道”的乐趣，还是作为开发者学习AI智能体与复杂系统模拟的绝佳案例，它都提供了极其丰富的可能性。