修仙世界模拟器

🚀 快速开始

方式一：源码部署（开发模式，推荐）

适合需要修改代码或调试的开发者。

1. 安装依赖并启动

   # 1. 安装后端依赖
   pip install -r requirements.txt

   # 2. 安装前端依赖 (需 Node.js)
   cd web && npm install && cd ..

   # 3. 启动服务 (自动拉起前后端)
   python src/server/main.py --dev
   

2. 配置模型 在前端设置页选择模型预设（如 DeepSeek / MiniMax / Ollama）后，即可开始新游戏。配置会自动保存到用户数据目录。

3. 访问前端 开发模式会自动拉起前端开发服务器，请访问启动日志中显示的前端地址，通常为 http://localhost:5173。

方式二：Docker 一键部署（未测试）

无需配置环境，直接运行即可：

git clone https://github.com/4thfever/cultivation-world-simulator.git
cd cultivation-world-simulator
docker-compose up -d --build

访问前端：http://localhost:8123

后端容器通过 CWS_DATA_DIR=/data 统一持久化用户数据，包含设置、密钥、存档和日志。默认已映射到宿主机 ./docker-data，即使执行 docker compose down 后重新 up，这些数据也会保留。

<details> <summary><b>局域网/手机访问配置 (点击展开)</b></summary>

⚠️ 移动端 UI 暂未完全适配，仅供尝鲜。

1. 后端配置：推荐通过环境变量启动后端，例如 PowerShell 中执行 $env:SERVER_HOST='0.0.0.0'; python src/server/main.py --dev。如需改默认值，可编辑只读配置 static/config.yml 中的 system.host。
2. 前端配置：修改 web/vite.config.ts，在 server 块中添加 host: '0.0.0.0'。
3. 访问方式：确保手机与电脑在同一 WiFi 下，访问 http://<电脑局域网IP>:5173。

</details>

<details> <summary><b>外接 API / Agent/Claw 接入 (点击展开)</b></summary>

这部分适合做外部 agent / Claw 接入、自动化脚本，或者实现“观察 -> 决策 -> 干预 -> 再观察”的闭环游玩。

推荐直接围绕稳定命名空间开发：

• 只读查询：/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
• POST /api/v1/command/avatar/*
• POST /api/v1/command/world/*

最小接入流程通常是：

1. 先调用 GET /api/v1/query/runtime/status 判断当前运行状态。
2. 如未开局，调用 POST /api/v1/command/game/start 初始化。
3. 用 world/state、events、detail 拉取世界快照与目标信息。
4. 根据策略调用一个 command 执行干预。
5. 干预后重新 query，不要依赖本地缓存推断结果。

接口成功时通常返回：

{
  "ok": true,
  "data": {}
}

失败时会返回结构化错误，可读取 detail.code 与 detail.message 做程序判断。

补充说明：

• 应用设置仍通过 /api/settings* 与 /api/settings/llm* 管理，它们属于设置真源，不属于外接控制兼容层。
• 更完整的接口清单、分层设计与扩展约定请参考 docs/specs/external-control-api.md。

</details>

首次启动说明

• 无论使用源码还是 Docker，首次进入后都需要先在设置页配置可用的模型预设（如 DeepSeek / MiniMax / Ollama），再开始新游戏。
• 开发模式下，前端页面通常会自动打开；如果没有自动打开，请访问启动日志中显示的前端地址。

插件

感谢贡献者为本 repo 贡献插件。

• cultivation-world-simulator-api-skill
• cultivation-world-simulator-android