> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/XiaoLuoLYG/GOD) · [上游 README](https://github.com/XiaoLuoLYG/GOD/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

GOD logo  GOD · Govern · Observe · Direct

GOD — Govern · Observe · Direct

🌩️ 像上帝一样，俯瞰一座由 Agent 组成的小镇。
暂停时间。操控环境。对某个灵魂发问。一键重置 —— 全部在一个屏幕里完成。

▶ 浏览器回放  ·  无需安装、无需 API key  ·  本地运行

🌐 浏览器回放 · 🚀 快速开始 · 更新 · Roadmap · 亮点 · 核心能力 · 内置实验 · 公开站 · 开发者文档 · 参与开发 · 🌏 English

Release Live replay Python React Vite No-Code Setup License PRs welcome

--- > 大多数 agent-society demo 只能让你看着仿真自己跑完，GOD 把控制权交回到你手里。 > > 在同一个屏幕里回放一次运行、向任意居民提问、改变接下来发生的事，再导出一个别人能照着复现的包。 > 它是用来检查 language-agent society 的，不负责声称它们有多接近真实社会。 ## 🗓️ 更新 - **2026-06-11 · [v0.2.0](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.2.0)：** 公开站与浏览器回放； Experiment / Map / Agent 包 hub 与 ZIP 导入导出；Windows 一键启动；首次启动硬化。([#64](https://github.com/XiaoLuoLYG/GOD/pull/64) [#65](https://github.com/XiaoLuoLYG/GOD/pull/65)) - **2026-06-06 · 公开站与资源包：** 重做公开站与前端；站点资源包改走 release assets；地图包预览页。 ([#61](https://github.com/XiaoLuoLYG/GOD/pull/61) [#62](https://github.com/XiaoLuoLYG/GOD/pull/62) [#63](https://github.com/XiaoLuoLYG/GOD/pull/63)) - **2026-06-01 · 可移植包：** 统一 ExperimentPack 下载；GOD 包导入导出；精选实验库。([#57](https://github.com/XiaoLuoLYG/GOD/pull/57) [#59](https://github.com/XiaoLuoLYG/GOD/pull/59) [#60](https://github.com/XiaoLuoLYG/GOD/pull/60)) - **2026-05-30 · Windows 启动器与 hub：** `god.cmd start` 对齐 macOS/Linux 流程；AgentPack hub 与公开 replay 导出；JiuwenClaw 请求并行化。([#45](https://github.com/XiaoLuoLYG/GOD/pull/45) [#49](https://github.com/XiaoLuoLYG/GOD/pull/49) [#50](https://github.com/XiaoLuoLYG/GOD/pull/50)) - **2026-05 · 操作台与 Studio：** 双语控制台、地图优先 `/ask` + `/intervene` rail、 Agent Studio、Map Studio、统一 skill runtime。([#26](https://github.com/XiaoLuoLYG/GOD/pull/26) 到 [#31](https://github.com/XiaoLuoLYG/GOD/pull/31)) - **2026-05-21 · [v0.1.0](https://github.com/XiaoLuoLYG/GOD/releases/tag/v0.1.0)：** 首个打标发布，内置两个实验和 PKU 校园地图。([#21](https://github.com/XiaoLuoLYG/GOD/pull/21) [#24](https://github.com/XiaoLuoLYG/GOD/pull/24)) ## ✨ 亮点
⏯️
暂停时间
任意 step replay、暂停、加速、自动推进。		 💬
定向提问
在 live session 里向某个居民、群组或全镇发问。		 🎛️
引导下一步
注入指令，并检查 Agent 后续响应。		 🪄
零代码上手
浏览器配置向导：模型、剧本、Agent 一站搞定。		 🔄
重置运行状态
一条命令清掉旧数据，重新生成干净的小镇状态。
## 🖼️ 截图

GOD 控制台

实时控制台：PKU 地图、step 控制、定向提问、居民列表全在一个界面里。

## 🌐 浏览器回放 打开 [**公开站**](https://xiaoluolyg.github.io/GOD/zh/) 在浏览器里逛一圈：精选回放、地图包、Agent 包和可下载实验。无需安装，也不用 API key。

GOD 公开站   GOD 地图包   GOD Agent 包

从左到右：公开站首页、可下载地图包、可下载 Agent 包。

## 🚀 快速开始 ```bash git clone https://github.com/XiaoLuoLYG/GOD.git cd GOD ./scripts/god.sh start ``` Windows PowerShell：进入仓库根目录后运行 `.\scripts\god.cmd start`。 首次启动会自动装好依赖，打开 **浏览器中的实验配置向导**，然后等你填完。你不用手改 `.env`，也不用记命令行参数。

GOD 实验配置向导

实验配置向导：模型配置、默认实验选择、自建实验发布都在同一个浏览器流程里。

🔌
1. 模型
填入 OpenAI 兼容的 API key、base URL 和模型名。		 🧭
2. 选择
打开 GOD Town、打开 PKU Trump Visit，或新建实验。		 🧪
3. 剧本
用自然语言描述世界：日期、天气、氛围、规则。		 🤖
4. 生成
GOD agent 自动起草 agent profile 和 step 计划。		 ✏️
5. 编辑
调整人物性格、关系、地点、步骤。		 ▶️
6. 启动
发布为当前实验，直接进入控制台。
任意 OpenAI 兼容接口都可以。向导收尾后，脚本会打印类似这样的地址： ```text http://127.0.0.1:5174/pixel-replay/god_town/1 ``` 完整步骤见 **[快速开始 →](QUICKSTART.zh-CN.md)** ## 🧩 核心能力 | | 能力 | 你得到什么 | | --- | --- | --- | | 🎬 | **Replay 控制** | 按 step 拖动、暂停、跳转、自动推进，live 或已记录 replay 都行。 | | 💬 | **定向提问** | 用自然语言向某个 Agent、某组人或全镇提问。 | | 🎛️ | **实时干预** | 给即将执行的 step 注入指令，Agent 下一回合就读得到。 | | ⌨️ | **命令输入器** | 在地图上直接输入 `/ask` 或 `/intervene`，用 `@Name #id` 自动补全目标。 | | 🪄 | **零代码配置向导** | 浏览器里配置模型 + 剧本，让 GOD 生成 Agent 和 step，编辑后启动。 | | 🧬 | **Agent Studio** | 用地图感知的向导新增 / 编辑居民：seed、身份、外貌、性格、日程、review 一步步完成。 | | 🧭 | **地图工作台** | 生成或上传地图草稿，校准地点与碰撞层，校验后发布为本地地图包。 | | 🧼 | **一键重开** | 一条命令清掉 replay 数据，孵化一座干净的小镇。 | | 🗺️ | **像素小镇世界** | 地点、动作、消息、状态都是结构化、replay 友好的。 | | 🧱 | **唯一当前实验** | `.env` 只保存模型、API、端口等本机配置；`.god/current_experiment.json` 保存唯一 active 实验。 | | 🌐 | **浏览器回放** | GitHub Pages 上的精选回放，无需本地安装或 API key。 | | 📦 | **资源包库** | Experiment / Map / Agent 包导入导出；公开站还有更多可下载场景。 | | 🪟 | **Windows 启动器** | PowerShell 下 `god.cmd start`，与 macOS/Linux 同样一条命令。 | ## 🛣️ Roadmap ### ✅ 已完成 - [x] 🗺️ **可拔插地图包**：把一个文件夹丢到 `agentsociety/custom/maps//`，刷新向导即出现新世界。自动发现、自动校验、热插拔。详见 [`docs/MAP_PACKAGES.zh-CN.md`](docs/MAP_PACKAGES.zh-CN.md)。 - [x] 🏫 **PKU 校园地图**：PKU 地图包已经作为一等地图随仓库发布，和 The Ville 一起可选。 - [x] 🪄 **零代码配置向导**：浏览器流程，模型配置、内置实验选择、自建实验生成 / 编辑 / 发布，一台空机器到真实的小镇。 - [x] 🧪 **可复现实验**：实验以普通文件夹形式发布，位于 `quick_experiments///`。选择或发布一个实验后，它就会成为 current。 - [x] 🎮 **控制台命令 rail**：replay 控制、居民列表、Live Console、定向 Ask 和 Intervene 都合并在一个地图优先的操作界面里。 - [x] 🧬 **Agent Studio v1**：地图感知的新增 / 编辑 Agent 流程，包含结构化 profile metadata、ID 校验、Setup 集成和 sprite 生成支持。 - [x] 🧭 **Map Studio v1**：prompt / 参考图生成地图草稿，锚点与碰撞层校准，地图包校验、发布，以及返回 Setup 的 handoff。 - [x] 🌏 **双语运行时 UI**：setup、replay、地图、状态、动作和系统事件中的产品侧文本支持 English / 中文。 - [x] 🔌 **Agent skill-runtime 路径**：随仓库发布的 JiuwenClaw adapter 现在以 AgentSociety skill runtime 作为标准执行路径。 - [x] 🌐 **公开站与浏览器回放**：GitHub Pages 托管精选回放、地图包、Agent 包和可下载实验，无需本地安装或 API key。 - [x] 📦 **可移植包与导入导出**：Experiment / Map / Agent 包支持 ZIP 导入导出，通过 release assets 分发。 - [x] 🪟 **Windows 一键启动**：`god.cmd start`，与 macOS/Linux 一样一条命令。 ### 🛣️ 未完成 / 进行中 - [ ] 🤖 **可拔插 Agent 运行时**：让 LLM runtime 和 persona 模板能像地图一样干净地替换。 - [ ] 🧪 **多实验编排**：在同一个控制台里跑实验、对照组、重复试验和 ablation。 - [ ] 🗺️ **实时地图生成**：地图随事件、修缮、阻塞、人群动态演化。 - [ ] 🌦️ **事件响应世界**：天气、事故、节日、谣言、供应短缺影响 Agent 行为。 - [ ] 🌐 **大规模仿真**：接入 AgentSociety 的批量 Agent、分片运行、采样 replay 和性能友好的 replay 摘要。 - [ ] 📊 **实验评估**：跨实验指标、行为差异、干预效果分析和可分享报告。 - [ ] 📝 **操作员工作流**：每个 step 的笔记、标签、书签、保存命令宏和关键事件摘要。 - [ ] 🌍 **托管 live 控制台**：一个可以真正操控运行（而不只是看回放）的托管 demo，外加社区场景模板。 有想法？欢迎来 [issue 和 PR](#-参与开发) 聊。 ## 🏗️ 架构 ```mermaid flowchart LR O["Operator"]:::operator UI["Control Room"]:::surface API["Live API"]:::core RT["Agent Runtime"]:::runtime TOWN["Pixel Town"]:::world CFG[["Experiment Files"]]:::data DB[("Replay Store")]:::data O --> UI UI <-->|"commands / updates"| API API -->|"prompts"| RT RT -->|"actions"| TOWN TOWN -->|"frames"| DB CFG -->|"scenario"| API classDef operator fill:#fff7ed,stroke:#f59e0b,color:#7c2d12,stroke-width:2px; classDef surface fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px; classDef core fill:#ecfeff,stroke:#0891b2,color:#164e63,stroke-width:2px; classDef runtime fill:#f0fdf4,stroke:#22c55e,color:#14532d,stroke-width:2px; classDef world fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:2px; classDef data fill:#fdf2f8,stroke:#db2777,color:#831843,stroke-width:2px; ``` GOD 是 local-first：控制台、后端、runtime bridge、实验文件和 replay store 都运行在本机。唯一外部服务是你选择的模型接口。 GOD 把三个概念分开： - **Experiment** 是可玩的实验设定：地图、智能体、场景上下文和 step 计划。 - **Replay** 是实验被运行之后可以观看的结果。 - **本地运行状态** 是 SQLite replay store、日志、agent snapshot 等机器数据；它不属于 ExperimentPack，也不应该提交到仓库。 | 层 | 职责 | | --- | --- | | 🎮 **Control Room** | React/Vite 控制台，replay、ask、intervention、status 都在这里。 | | ⚙️ **Backend** | 本地 FastAPI，提供 live 和 replay API。 | | 🗺️ **Pixel Town** | 像素小镇社会状态：地点、动作、消息、Agent 状态。 | | 🤖 **Agent Runtime** | 独立进程的 LLM Agent，通过本地 WebSocket 连接。 | ## ⚙️ 常用命令 ```bash ./scripts/god.sh start # 启动完整栈（可重复执行） ./scripts/god.sh configure # 打开配置向导，切换默认实验或新建实验 ./scripts/god.sh restart # 先干净停止，再重新启动 ./scripts/god.sh new-run # 清空当前实验的本地运行状态，并开一个新的 session ./scripts/god.sh status # 查看端口、URL、模型状态 ./scripts/god.sh stop # 停止所有服务 ./scripts/god.sh tail # 跟随日志 ./scripts/god.sh open # 在浏览器里打开前端页面 ``` Windows 下把 `./scripts/god.sh` 替换成 `.\scripts\god.cmd` 即可。 ## 🧪 内置实验 GOD 现在内置两个默认实验，并且和你自己发布的实验使用同一套 current model。配置向导会把你选择的实验写到 `.god/current_experiment.json`；之后 `start`、`open`、`new-run` 都只作用于这个当前实验。 [**公开站**](https://xiaoluolyg.github.io/GOD/zh/experiments/) 上还有更多可下载场景，比如空城计、高考停电、霍格沃茨家长会。 `.env` 只保存本机模型、API、端口等配置，不再决定默认实验或地图。因此即使旧 `.env` 里残留 `GOD_MAP_ID=pku`，选择 GOD Town 时仍然会使用 `the_ville` 地图，不会串台。 ### 🏘️ The Ville 的一个普通工作日 晚春的工作日清晨 8:20，晴朗微风，气温 18°C。一座 200 多人的小镇，**10 位常住居民彼此熟识但各过各的生活**。它是一段日常生活切片，不是任务驱动的剧本。 ➡️ **在配置向导选择 `god_town` 即可把它设为当前实验。** 它固定绑定 `hypothesis_god_town/experiment_1` 和 `the_ville` 地图。 ➡️ 完整的地点 / 居民 / 交互拆解见 [`hypothesis_god_town/experiment_1/`](agentsociety/quick_experiments/hypothesis_god_town/experiment_1/README.md)。

The Ville 地图

The Ville 地图：10 位居民在家、学校、图书馆、咖啡馆、公园、市场、药房、酒馆、宿舍之间度过普通一天。

🗺️ 10 个地点 · 65 个 location-scoped 交互
🏠
家
做饭 · 睡觉 · 整理 · 阅读 · 居家办公 · 视频家人		 🏫
学校
上课 / 教书 · 批改 · 课后答疑		 📚
图书馆
阅读 · 学习 · 查资料 · 借还书		 ☕
Hobbs Cafe
简餐 · 咖啡聊天 · 值班 · 随性碰头		 🌳
Johnson Park
散步 · 见友 · 晨练 · 公共播报
🛠️
供给店
修理 · 上货 · 借工具 · 顾客接待		 🛒
市场
买食物 · 议价 · 送单 · 和老客闲聊		 💊
药房
买药 · 续方 · 量血压 · 上门准备		 🍻
酒馆
社交 · 看比赛 · 主持小活动		 🛏️
宿舍
休息 · 自习 · 公共区休闲 · 视频家里
👥 10 位居民，每个人都有真实生活
🧭
Alice · 34
社区协调员		 🛠️
Bob · 45
市场五金店主		 📖
Charlie · 39
中学历史老师		 💊
Dana · 41
社区药房护理员		 ☕
Elena · 36
咖啡馆老板
🎒
Farah · 16
高中学生		 📮
George · 68
退休邮递员		 💻
Hana · 28
远程软件工程师		 🦺
Ivan · 52
社区安全志愿者		 🍅
Mei · 47
市场蔬果摊主
每位居民都有完整 profile：年龄、家庭、住房、经济状况、健康、日常作息、技能、需求、担忧、秘密、社交圈、语言风格、小怪癖、短期/长期目标。 ### 🏫 PKU Trump Visit 这是一个发生在风格化北大校园地图上的公共事件实验。Agent 会先在校门、教学楼、图书馆、未名湖、食堂、宿舍、百周年纪念讲堂等地点开始日常行动，然后在一次高关注访问事件中表现出注意、询问、聚集和讨论。 ➡️ **在配置向导选择 `pku_trump_visit` 即可把它设为当前实验。** 它固定绑定 `hypothesis_pku_trump_visit/experiment_1` 和 `pku` 地图。 ➡️ 完整场景、角色、操作脚本和 replay 数据见 [`hypothesis_pku_trump_visit/experiment_1/`](agentsociety/quick_experiments/hypothesis_pku_trump_visit/experiment_1/README.md)。

PKU 校园地图

PKU 校园地图：校门、教学楼、图书馆、未名湖、博雅塔、食堂、宿舍、百周年纪念讲堂，以及 PKU Trump Visit 的角色阵容。

## 🗺️ 可拔插地图包 GOD 会自动从 `agentsociety/custom/maps//` 发现地图包。想加一张新地图？复制 [`agentsociety/custom/maps/_template/`](agentsociety/custom/maps/_template/README.zh-CN.md)，替换 `map.yaml`、`visuals/map.json`、tileset PNG，以及可选的 `characters/` 和 `location_assets/`，然后跑： ```bash cd agentsociety uv run python scripts/validate_map_package.py custom/maps/ ``` 配置向导会自动列出所有合法的地图包，完全不用改代码。v1 支持带 PNG tileset 的 Tiled JSON 地图，并要求一个 `Collisions` 层（`0` 表示可走）。PKU 校园地图包现在已经随仓库发布，路径是 `agentsociety/custom/maps/pku/`。完整契约见 [docs/MAP_PACKAGES.zh-CN.md](docs/MAP_PACKAGES.zh-CN.md)。 ## 🤝 参与开发 ```bash ./scripts/god.sh start ``` 会自动装好 Python、Node 依赖，启动完整栈，创建 live session，并先跑完第 1 步，让控制台打开时就是已初始化的小镇。改完代码刷新即可。 完整指南见 **[CONTRIBUTING.zh-CN.md →](CONTRIBUTING.zh-CN.md)**：分支策略、PR 检查表、代码风格，以及怎么提交一张新地图或新实验。 ## 🙌 致谢 GOD 构建在开源研究和开源代码之上。仓库内集成了两份精简过的上游代码： - [AgentSociety](https://github.com/tsinghua-fib-lab/AgentSociety)：大规模 generative-agent 模拟框架。 - [JiuwenClaw](https://github.com/openJiuwen-ai/jiuwenclaw)：进程外 Agent runtime。 同时受 [Generative Agents](https://arxiv.org/abs/2304.03442) 与 [OASIS](https://github.com/camel-ai/oasis) 启发。 ## 📚 引用 ```bibtex @article{piao2025agentsociety, title = {AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society}, author = {Piao et al.}, journal = {arXiv preprint arXiv:2502.08691}, year = {2025} } @misc{park2023generativeagents, title = {Generative Agents: Interactive Simulacra of Human Behavior}, author = {Joon Sung Park and Joseph C. O'Brien and Carrie J. Cai and Meredith Ringel Morris and Percy Liang and Michael S. Bernstein}, year = {2023}, eprint = {2304.03442}, archivePrefix = {arXiv}, primaryClass = {cs.HC}, url = {https://arxiv.org/abs/2304.03442} } ``` ## ⭐ Star History Star History Chart ## 📄 License [Apache-2.0](LICENSE)。集成的上游代码各自保留了它们的 LICENSE / NOTICE，对应子树仍受其约束。

如果 GOD 对你有用，点个 ⭐ 能帮更多人找到它。