修仙世界模拟器：把 NPC 交给 LLM，把规则留给代码
基于 AI Agent 工作流的修仙世界模拟器，旨在还原智能、开放的仙侠世界。| An open-source Cultivation World Simulator using Agentic Workflow to create a dynamic, emerging Xianxia world.
秒懂
- 它是什么？
- 这是一个用 Python 写的修仙世界模拟器，每个修士都是独立的 LLM Agent，世界观规则由代码约束。它解决的是「让 AI 自由发挥但别乱来」这个矛盾，适合愿意自己配模型服务的开发者。
- 适合谁用？
- 如果你手上有可用的模型服务，并且想研究多 Agent 决策与规则系统如何协作，这个项目值得拉下来跑一遍，重点看 src/server/main.py 的启动流程和 /api/v1/query 系列接口。如果你只是想玩一个修仙游戏，Epic 桌面版更省事；如果你希望开箱即用、不想碰模型配置，源码和 Docker 两条路都会在设置页卡住你。
- 能商用吗？
- 请先确认。这个仓库使用的许可证不在我们自动归类的范围内，商用前请阅读仓库里的 LICENSE 文件。
- 还在维护吗？
- 在维护。仓库最近一次提交在 31 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
天道视角：这个项目到底在模拟什么
多数修仙题材游戏让你扮演修士，从炼气一路打到飞升。这个项目反过来，README 的定位是让你扮演「天道」，不参与角色成长，只观察一个由规则系统和 AI 共同驱动的世界自行演化。玩家能做的动作是降下天劫、魔改心灵这类外部干预，而不是替某个角色做决定。
目标用户因此分成两类。一类是对多 Agent 系统感兴趣的开发者，想看一堆独立 LLM 实例在共享世界里互相博弈会出什么结果。另一类是修仙题材的爱好者，愿意接受「没有主线剧本」这种玩法。README 明确写了没有预设剧本，宗门大战、正魔之争、天骄陨落都由世界逻辑自主推演，开发者自己也不知道下一秒会发生什么。这句话既是卖点也是风险提示：涌现叙事意味着你没法保证某一局一定精彩。
规则约束 AI：这套架构想解决的核心矛盾
纯 LLM 驱动的模拟很容易失控。模型会编造不存在的境界、凭空获得功法、把寿元设定忘干净。项目的应对方式是把世界观拆成一套硬性元素，README 列举了灵根、境界、功法、性格、宗门、丹药、兵器、武道会、拍卖会、寿元，AI 的决策被限制在这个框架内。
每个修士 Agent 的循环是「观测环境、做出决策」。性格、记忆、人际关系、行为逻辑都是独立维护的，所以同一个局势下不同修士会给出不同反应。宗门作为集体意志与个体 Agent 之间存在博弈与合作，这是 README 描述的主要张力来源。
需要说清楚的是，从仓库现有材料看不出规则层与 LLM 层的具体边界在哪里：哪些判定由代码直接给出结果、哪些交给模型自由生成。README 只说了「编入复杂灵活的修仙世界观与运行规则」，没有给出规则引擎的实现细节。想评估这套约束是否真的有效，只能读源码。
从源码跑起来：三条部署路径的实际差别
README 给了三条路径，适合的人群不一样。
Epic Games Store 桌面版是给只想玩的人准备的，免费获取安装后按设置页提示确认模型配置即可开局。如果你希望用自己的模型服务，设置页可以切换 DeepSeek、MiniMax、Ollama 等预设。
源码部署是 README 标注的推荐方式，需要 Python 3.10+、Node.js 18+ 和一个可用的模型服务。命令是三步：pip install -r requirements.txt 装后端依赖，cd web && npm install && cd .. 装前端依赖，然后 python src/server/main.py --dev 启动，这条命令会自动拉起前后端。开发模式下前端通常会自动打开，没打开就访问启动日志里显示的地址，README 说通常是 http://localhost:5173。
Docker 那条路 README 直接标了「未测试」，步骤是 git clone 之后 docker-compose up -d --build，前端在 http://localhost:8123。后端容器用 CWS_DATA_DIR=/data 统一持久化用户数据，包括设置、密钥、存档和日志，默认映射到宿主机的 ./docker-data，所以 docker compose down 之后再 up 数据还在。这个标注值得认真对待：作者自己没验证过的路径，你踩坑的概率不低。
三条路径有一个共同前提，首次进入都要先在设置页配置可用的模型预设，配置会保存到用户数据目录。这一步绕不过去。
外接 Agent 接入：/api/v1 命名空间怎么用
README 里有一段专门讲外接 API 和 Agent 接入，适合做自动化脚本或者实现「观察、决策、干预、再观察」的闭环。接口分成两个命名空间：只读查询走 /api/v1/query/*，受控写入走 /api/v1/command/*。
常用起点接口包括 GET /api/v1/query/runtime/status 查运行状态，GET /api/v1/query/world/state 取世界状态，GET /api/v1/query/events 取事件流，GET /api/v1/query/detail?type=avatar|region|sect&id=<target_id> 查具体对象详情。写入侧有 POST /api/v1/command/game/start 初始化对局，以及 /api/v1/command/avatar/* 和 /api/v1/command/world/* 两组操作。
README 给出的最小接入流程是：先查 runtime/status 判断当前状态，如果还没开局就调 game/start 初始化，然后轮询 world/state 和 events。这套设计把读和写分开，对做外部 Agent 的人来说是有利的，你可以在不改变世界状态的前提下反复采样。
不过 README 在介绍 events 接口的地方被截断了，事件流的具体字段结构和分页方式从现有材料看不出来，需要自己查接口文档或读代码。
哪里会卡住：几个需要提前知道的限制
模型服务是硬依赖。没有可用的 LLM 端点，这个模拟器跑不起来，因为每个修士的决策都要过模型。这意味着运行成本随世界规模和模拟时长线性增长，README 没有给出任何关于 token 消耗或并发上限的数据，这部分只能自己实测。
移动端适配不完整。README 在局域网访问那一节明确写了「移动端 UI 暂未完全适配，仅供尝鲜」。想在手机上玩的话，需要改两处配置：后端用环境变量启动，比如 PowerShell 里执行 $env:SERVER_HOST='0.0.0.0'; python src/server/main.py --dev，或者改只读配置 static/config.yml 里的 system.host；前端要改 web/vite.config.ts，在 server 块里加 host: '0.0.0.0'。改完确保手机和电脑在同一 WiFi 下。
许可证是 NOASSERTION。这意味着 GitHub 无法自动识别出标准许可证，仓库里的 LICENSE 文件具体写了什么条款，必须自己打开看。如果你打算把这个项目用于商业用途或者二次分发，这一步不能跳过。我在这里不给法律意见，只提醒这不是一个一眼能看清授权范围的仓库。
同类方案对比：它和通用 Agent 框架的分工不同
拿 LangGraph、AutoGen 这类通用多 Agent 框架来比，差别在约束从哪来。通用框架提供的是编排能力，Agent 之间怎么交互、状态怎么传递由你定义，世界规则要自己写。这个项目反过来，规则层和世界观是预置的，灵根、境界、寿元、宗门这些概念已经内建，你接入的是模型服务，不是从零搭一套模拟逻辑。
代价是灵活性。你没法轻易把修仙设定换成科幻或者现代都市背景，因为规则体系是围绕修仙构建的。如果你要的是通用的多 Agent 实验平台，通用框架更合适。如果你要的是一个已经有完整世界观、能直接观察涌现行为的沙盒，这个项目省掉了大量前期设计工作。
另一个区别在输出形态。通用框架通常给你日志和追踪，这个项目给你一个 PixiJS 渲染的前端，能看到角色面板、宗门界面、事件经历这些可视化内容。对调试多 Agent 系统来说，有可视化界面确实比翻日志直观，但也意味着前端依赖 Node.js 18+ 和 Vite，环境比纯 Python 项目重。
维护节奏与升级成本
从版本记录看，v4.0.0 在 2026 年 8 月 1 日发布，v4.0.1 在 8 月 2 日跟进，v3.9 在 7 月 19 日。大版本和小补丁挨得很近，说明 v4.0.0 发布后很快修了问题。仓库最后推送时间是 2026 年 8 月 16 日，距离 v4.0.1 大约两周，处于活跃状态。
对使用者的实际影响是：主版本号跳到 4 意味着可能有过结构性改动，如果你从 v3.x 升级过来，存档兼容性和配置格式都需要确认。README 提到配置会自动保存到用户数据目录，Docker 部署下这个目录由 CWS_DATA_DIR 控制，升级前备份 ./docker-data 是成本最低的保险。
依赖面也不小。后端 Python 3.10+ 加 FastAPI，前端 Vue 3、TypeScript、Vite、PixiJS。前端依赖的升级通常比后端更麻烦，如果这个项目锁定的 Vite 或 PixiJS 版本比较旧，你可能会在 npm install 阶段遇到需要手动处理的对等依赖问题。README 没有提供锁文件相关的说明。
编辑结论
如果你手上有可用的模型服务，并且想研究多 Agent 决策与规则系统如何协作，这个项目值得拉下来跑一遍，重点看 src/server/main.py 的启动流程和 /api/v1/query 系列接口。如果你只是想玩一个修仙游戏，Epic 桌面版更省事；如果你希望开箱即用、不想碰模型配置，源码和 Docker 两条路都会在设置页卡住你。上手前先确认三件事：模型预设里的 DeepSeek、MiniMax、Ollama 你能否访问；许可证文件是否包含你需要的授权条款；Docker 那条路径的「未测试」标注是否已经被后续提交改动。
社区笔记