🌍 WorldBox — 上帝模拟器

一款基于大语言模型（LLM）驱动的极简文字"上帝模拟器"。玩家扮演造物主，向世界发出神谕，LLM 负责推演世界的演变结果，并将新的世界状态实时展示在浏览器中。

✨ 功能特性

自动演变：世界按设定的时间间隔（Tick）自动推演，呈现自然生态、人口、科技等属性的变化。
神谕输入：玩家可随时输入自然语言指令（神谕），LLM 会优先结算神谕影响后再叠加自然演变。
动态状态面板：世界状态以嵌套分类卡片展示，数值上升/下降/新增时有高亮动画提示。
Raw JSON 日志：实时展示每一轮 LLM 返回的原始 JSON，方便调试。
明/暗主题切换：支持深色与浅色主题，偏好保存于本地存储。
可配置参数：API 地址、Key、模型、AI 创造力（Temperature）、Tick 间隔均可在设置面板中修改并持久化。
服务端默认配置：管理员可在服务器的 .env 文件中预设 API 地址、Key 和模型，用户无需填写即可直接使用；未配置时行为与之前完全一致，仍需用户自行填写。
URL 自动规范化：无论用户填写的是 https://api.openai.com、https://api.openai.com/v1 还是完整路径，服务端均能自动修正为正确的 Chat Completions 端点；格式错误时会明确提示。
兼容任意 OpenAI 兼容接口：只要提供符合 OpenAI Chat Completions 规范的 API 即可，支持 OpenAI、Azure、本地部署模型等。

🛠 技术栈

| 层次 | 技术 | |------|------| | 后端 | Node.js (≥18) + Express + dotenv | | 前端 | 纯 HTML/CSS/JavaScript（无框架） | | AI | 任意 OpenAI 兼容 Chat Completions API | | 测试 | Node.js 内置 node:test |

📋 前置条件

Node.js >= 18.0.0
可用的 OpenAI 兼容 API（如 OpenAI、Azure OpenAI、本地 Ollama 等）及对应 API Key

🚀 安装与启动

# 克隆仓库
git clone https://github.com/HaveCake/worldbox.git
cd worldbox

# 安装依赖
npm install

# （可选）配置服务端默认 API 凭据，详见下方"服务端默认配置"一节
cp .env.example .env
# 然后编辑 .env，填入你的 DEFAULT_API_URL / DEFAULT_API_KEY / DEFAULT_MODEL

# 启动服务器（默认端口 3000）
npm start

启动后在浏览器中访问：

http://localhost:3000

如需自定义端口，可设置环境变量：

PORT=8080 npm start

⚙️ 配置

前端用户配置

首次打开页面后，点击右上角的 ⚙️ 设置 按钮，填写以下参数：

| 参数 | 说明 | 示例 | |------|------|------| | API Base URL | LLM 接口地址，支持多种格式（见下方说明） | https://api.openai.com | | API Key | 对应 API 的鉴权 Key | sk-... | | Model | 使用的模型名称 | gpt-4o | | AI 创造力 (Temperature) | 控制 LLM 输出随机性，范围 0–2 | 1.2 | | Tick 间隔（秒） | 世界自动演变的时间间隔 | 10 |

API Base URL 格式：以下写法均被自动识别并修正，无需手动补全路径：

https://api.openai.com

https://api.openai.com/v1

https://api.openai.com/v1/chat/completions

若服务端已配置默认值，三个字段均可留空，留空时将使用服务器默认配置。

配置保存于浏览器的 localStorage，刷新页面后自动恢复。

服务端默认配置（可选）

适用于自用或给受信任用户使用的场景：在服务器上预设 API 凭据，用户无需在前端填写任何 API 信息即可直接使用。

复制模板文件：
```
cp .env.example .env
```

编辑 .env，填入你的默认值：

DEFAULT_API_URL=https://api.openai.com
DEFAULT_API_KEY=sk-your-key-here
DEFAULT_MODEL=gpt-4o

重启服务器，配置即生效。

说明：

三个环境变量均为可选，可只设置部分。

用户在前端填写的值优先级更高，会覆盖服务端默认值。

未配置且用户也未填写时，/evolve 接口仍会返回 400 错误，提示用户填写。

.env 文件已加入 .gitignore，不会被提交到版本库。

🎮 使用说明

完成配置后，世界将按 Tick 间隔自动演变，倒计时显示在控制栏左侧。
在底部输入框键入神谕（自然语言指令），点击 ⚡ 发送神谕 或按 Enter，可立即触发一次带指令的演变。
点击 ⏸ 暂停 可暂停自动演变，再次点击恢复。
世界状态面板中，各属性卡片会以颜色动画区分上升（绿色）、下降（红色）、新增（黄色）。
展开/收起各大类分类，可聚焦关注特定领域的状态。

🔌 API 参考

`POST /evolve`

触发一次世界演变推演。

请求体（JSON）：

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | apiUrl | string | ⚠️ 条件必填 | LLM API 地址（多种格式均支持）；若服务端已设置 DEFAULT_API_URL 则可省略 | | apiKey | string | ⚠️ 条件必填 | API 鉴权 Key；若服务端已设置 DEFAULT_API_KEY 则可省略 | | model | string | ⚠️ 条件必填 | 模型名称；若服务端已设置 DEFAULT_MODEL 则可省略 | | current_state | object | ✅ | 当前世界状态 JSON 对象 | | user_prompt | string | ❌ | 玩家神谕（为空时进行自然演变） | | temperature | number | ❌ | LLM 温度参数（0–2） |

成功响应（200）：

返回推演后的新世界状态 JSON 对象，格式为嵌套结构：

{
  "自然生态": { "树木": 120, "环境质量": 98 },
  "人类社会": { "人口": 52, "食物": 85 }
}

错误响应：

| 状态码 | 说明 | |--------|------| | 400 | 缺少必填字段，或 apiUrl 格式无效 | | 500 | 服务器内部错误 | | 502 | LLM 返回无效内容 |

📁 项目结构

worldbox/
├── public/
│   └── index.html      # 单页前端应用
├── test/
│   └── server.test.js  # 后端单元测试
├── server.js           # Express 后端入口
├── .env.example        # 服务端默认配置模板（复制为 .env 后填入真实值）
├── package.json
└── README.md

.env 文件（真实密钥）已加入 .gitignore，不会被提交到版本库。

🧪 运行测试

npm test

测试使用 Node.js 内置 node:test 模块，无需额外安装依赖。

📄 许可证

本项目基于 GPL-3.0 License 开源。

Worldbox

Install / Use

README