GOD · Govern · Observe · Direct
🌩️ 像上帝一样，俯瞰一座由 Agent 组成的小镇。
暂停时间。操控环境。对某个灵魂发问。一键重置 —— 全部在一个屏幕里完成。
▶ 浏览器回放 · 无需安装、无需 API key · 本地运行
🌐 浏览器回放 · 🚀 快速开始 · 更新 · Roadmap · 亮点 · 核心能力 · 内置实验 · 公开站 · AtomGit 镜像 · 开发者文档 · 参与开发 · 🌏 English
大多数 agent-society demo 只能让你看着仿真自己跑完，GOD 把控制权交回到你手里。
在同一个屏幕里回放一次运行、向任意居民提问、改变接下来发生的事，再导出一个别人能照着复现的包。 它是用来检查 language-agent society 的，不负责声称它们有多接近真实社会。
god.cmd start 对齐 macOS/Linux 流程；AgentPack hub 与公开 replay 导出；JiuwenClaw 请求并行化。(#45 #49 #50)/ask + /intervene rail、
Agent Studio、Map Studio、统一 skill runtime。(#26 到 #31)| ⏯️ 暂停时间 任意 step replay、暂停、加速、自动推进。 |
💬 定向提问 在 live session 里向某个居民、群组或全镇发问。 |
🎛️ 引导下一步 注入指令，并检查 Agent 后续响应。 |
🪄 零代码上手 浏览器配置向导：模型、剧本、Agent 一站搞定。 |
🔄 重置运行状态 一条命令清掉旧数据，重新生成干净的小镇状态。 |
实时控制台：PKU 地图、step 控制、定向提问、居民列表全在一个界面里。
打开 公开站 在浏览器里逛一圈：精选回放、地图包、Agent 包和可下载实验。无需安装，也不用 API key。
从左到右：公开站首页、可下载地图包、可下载 Agent 包。
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start
Windows PowerShell：进入仓库根目录后运行 .\scripts\god.cmd start。
首次启动会自动装好依赖，打开 浏览器中的实验配置向导，然后等你填完。你不用手改 .env，也不用记命令行参数。
实验配置向导：模型配置、默认实验选择、自建实验发布都在同一个浏览器流程里。
| 🔌 1. 模型 填入 OpenAI 兼容的 API key、base URL 和模型名。 |
🧭 2. 选择 打开 GOD Town、打开 PKU Trump Visit，或新建实验。 |
🧪 3. 剧本 用自然语言描述世界：日期、天气、氛围、规则。 |
🤖 4. 生成 GOD agent 自动起草 agent profile 和 step 计划。 |
✏️ 5. 编辑 调整人物性格、关系、地点、步骤。 |
▶️ 6. 启动 发布为当前实验，直接进入控制台。 |
任意 OpenAI 兼容接口都可以。向导收尾后，脚本会打印类似这样的地址：
http://127.0.0.1:5174/pixel-replay/god_town/1
完整步骤见 快速开始 →
| 能力 | 你得到什么 | |
|---|---|---|
| 🎬 | 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 同样一条命令。 |
agentsociety/custom/maps/<map_id>/，刷新向导即出现新世界。自动发现、自动校验、热插拔。详见 docs/MAP_PACKAGES.zh-CN.md。quick_experiments/<hypothesis>/<experiment>/。选择或发布一个实验后，它就会成为 current。god.cmd start，与 macOS/Linux 一样一条命令。有想法？欢迎来 issue 和 PR 聊。
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 把三个概念分开：
| 层 | 职责 |
|---|---|
| 🎮 Control Room | React/Vite 控制台，replay、ask、intervention、status 都在这里。 |
| ⚙️ Backend | 本地 FastAPI，提供 live 和 replay API。 |
| 🗺️ Pixel Town | 像素小镇社会状态：地点、动作、消息、Agent 状态。 |
| 🤖 Agent Runtime | 独立进程的 LLM Agent，通过本地 WebSocket 连接。 |
./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 都只作用于这个当前实验。
公开站 上还有更多可下载场景，比如空城计、高考停电、霍格沃茨家长会。
.env 只保存本机模型、API、端口等配置，不再决定默认实验或地图。因此即使旧 .env 里残留 GOD_MAP_ID=pku，选择 GOD Town 时仍然会使用 the_ville 地图，不会串台。
晚春的工作日清晨 8:20，晴朗微风，气温 18°C。一座 200 多人的小镇，10 位常住居民彼此熟识但各过各的生活。它是一段日常生活切片，不是任务驱动的剧本。
➡️ 在配置向导选择 god_town 即可把它设为当前实验。 它固定绑定 hypothesis_god_town/experiment_1 和 the_ville 地图。
➡️ 完整的地点 / 居民 / 交互拆解见 hypothesis_god_town/experiment_1/。
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：年龄、家庭、住房、经济状况、健康、日常作息、技能、需求、担忧、秘密、社交圈、语言风格、小怪癖、短期/长期目标。
这是一个发生在风格化北大校园地图上的公共事件实验。Agent 会先在校门、教学楼、图书馆、未名湖、食堂、宿舍、百周年纪念讲堂等地点开始日常行动，然后在一次高关注访问事件中表现出注意、询问、聚集和讨论。
➡️ 在配置向导选择 pku_trump_visit 即可把它设为当前实验。 它固定绑定 hypothesis_pku_trump_visit/experiment_1 和 pku 地图。
➡️ 完整场景、角色、操作脚本和 replay 数据见 hypothesis_pku_trump_visit/experiment_1/。
PKU 校园地图：校门、教学楼、图书馆、未名湖、博雅塔、食堂、宿舍、百周年纪念讲堂，以及 PKU Trump Visit 的角色阵容。
GOD 会自动从 agentsociety/custom/maps/<map_id>/ 发现地图包。想加一张新地图？复制 agentsociety/custom/maps/_template/，替换 map.yaml、visuals/map.json、tileset PNG，以及可选的 characters/ 和 location_assets/，然后跑：
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>
配置向导会自动列出所有合法的地图包，完全不用改代码。v1 支持带 PNG tileset 的 Tiled JSON 地图，并要求一个 Collisions 层（0 表示可走）。PKU 校园地图包现在已经随仓库发布，路径是 agentsociety/custom/maps/pku/。完整契约见 docs/MAP_PACKAGES.zh-CN.md。
./scripts/god.sh start
会自动装好 Python、Node 依赖，启动完整栈，创建 live session，并先跑完第 1 步，让控制台打开时就是已初始化的小镇。改完代码刷新即可。
完整指南见 CONTRIBUTING.zh-CN.md →：分支策略、PR 检查表、代码风格，以及怎么提交一张新地图或新实验。
GOD 构建在开源研究和开源代码之上。仓库内集成了两份精简过的上游代码：
同时受 Generative Agents 与 OASIS 启发。
@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}
}
Apache-2.0。集成的上游代码各自保留了它们的 LICENSE / NOTICE，对应子树仍受其约束。
如果 GOD 对你有用，点个 ⭐ 能帮更多人找到它。