# 基于 REST API 网关与状态机的多 AI 代理并行决策 SimCity 模拟架构 > 探讨如何通过 REST API 网关将经典 SimCity 模拟暴露为 headless 服务，利用 Cloudflare Durable Objects 实现状态机，支持多 AI 代理并行决策与游戏状态同步的工程化实现。 ## 元数据 - 路径: /posts/2026/02/12/rest-api-gateway-state-machine-ai-agents-simcity-parallel-decision/ - 发布时间: 2026-02-12T20:26:50+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 将经典城市模拟游戏 SimCity 转化为一个可供多 AI 代理并行操作的实验平台，是当前 AI 系统架构中的一个有趣挑战。本文以 Hallucinating Splines 项目为例，阐述如何通过 REST API 网关与状态机设计，构建一个支持多 AI 代理并行决策、状态同步的 headless 城市模拟服务，并提供可直接落地的工程参数与监控清单。 ### 核心观点：状态机是协调并行决策与状态同步的枢纽 在单机游戏中，状态管理相对简单；但在多 AI 代理并行的云端环境中，核心矛盾在于**如何让多个独立的决策流（AI 代理）安全、有序地操作同一个不断演进的游戏状态**。一个直观但低效的做法是采用全局锁，但这会严重限制并发性。Hallucinating Splines 的架构给出了一个优雅的答案：**将每个模拟城市实例封装为一个独立的状态机，并由 Cloudflare Durable Objects 承载**。 每个 Durable Object 是一个强一致性的、单线程的 JavaScript 运行时环境，它持有一个完整的 `HeadlessGame` 实例（即城市模拟状态）。所有对该城市的 API 请求（如建造、推进时间）都被路由到同一个 Durable Object 中顺序处理。这天然构成了一个状态机：外部“事件”（API 请求）触发内部“动作”（游戏引擎操作），并驱动游戏状态转移。这种设计确保了单个城市内部状态的线性一致性，完全避免了并发冲突。 ### 证据：从 API 端点到架构实现 Hallucinating Splines 的公开文档与代码库清晰展示了这一架构。其 REST API 提供了四个核心端点：创建 API 密钥、创建城市、执行动作（如 `build_coal_power`）、推进时间（以月为单位）。每个城市拥有唯一 ID，所有针对该城市的操作都通过 `Authorization` 头进行鉴权后执行。 在架构层面，项目明确划分为三层： 1. **引擎层（`src/`）**：基于 micropolisJS 改造的 headless 模拟引擎，确定性运行，无任何浏览器依赖。 2. **API 网关/服务层（`worker/`）**：使用 Cloudflare Workers 和 Hono 框架构建。关键设计在于，**每个城市对应一个 Durable Object**，城市元数据（如名称、种子、创建时间）存储在 D1（SQLite）数据库中，而地图快照等大型状态则序列化后存入 R2 对象存储。 3. **展示层（`site/`）**：Astro 构建的静态站点，用于展示城市画廊和排行榜。 这种架构使得“状态”有了明确的归属和生命周期。正如其文档所述，“每个城市都有自己的 Durable Object 持有活的 `HeadlessGame` 实例”，这为状态机的实现提供了基础设施保障。 ### 可落地参数与工程清单 基于上述分析，要构建一个类似的可供 AI 代理操作的模拟环境，以下是一份可落地的参数配置与工程监控清单。 #### 1. 状态机与 API 网关关键参数 * **Durable Object 单实例并发数**：保持为 1。这是保证状态一致性的基础，所有请求进入该对象的队列顺序执行。 * **状态快照频率**：建议每推进游戏时间 **12个月** 或每处理 **10个有效动作** 后，自动将完整游戏状态序列化并持久化到 R2（或类似对象存储）。这平衡了性能与故障恢复粒度。 * **动作队列深度监控**：为每个城市的 Durable Object 设置队列长度指标。当平均队列深度持续 >5 时告警，可能表明该 AI 代理决策频率过高或单个动作处理超时。 * **API 密钥与资源配额**： * 每个密钥同时活跃城市数上限：**5个**（仿照 Hallucinating Splines）。 * 密钥不活动失效时间：**14天**。对于长期实验，需设计定时“心跳”请求。 * 单城市动作频率限制：例如，每秒最多 **2个** 建造/规划类动作，防止模拟超速。 #### 2. 并行决策实现模式 多 AI 代理的“并行”体现在不同城市之间，而非单个城市内部。架构需支持： * **批量城市创建与初始化**：API 应支持通过单个请求（含种子列表）批量创建多个城市，并返回 ID 列表，供不同的 AI 代理认领。 * **全局状态聚合查询**：提供 `/v1/summary` 类端点，快速返回所有城市的元数据（如人口、预算、评分），供监控或元决策使用，避免轮询每个城市。 * **事件驱动的代理通知**（可选）：当城市达到特定状态（如破产、人口超过10万）时，可通过 Webhook 通知外部协调器，以触发新的 AI 决策流程。 #### 3. 容错与监控清单 * **必监控指标**： 1. Durable Object 激活/解激活速率。 2. 各 API 端点（`/actions`, `/advance`）的 P95/P99 延迟。 3. R2 快照存储的成功率与延迟。 4. 按城市统计的“游戏年/动作”比率，识别异常活跃或停滞的模拟。 * **故障回滚策略**： * 由于模拟是确定性的，任何错误都可以通过**重置到上一个已知好的快照（通过种子+快照时间点）** 来回滚。应在 API 中提供 `POST /v1/cities/{id}/rollback` 端点，支持回滚到指定时间戳。 * 对于因 AI 代理错误指令导致的“坏状态”（如连续建造导致破产），应设计“市长任期”概念，允许在不停用城市的情况下，将控制权移交给另一个 AI 代理，并从当前状态继续。 #### 4. 为 AI 代理优化的 API 设计 * **结构化观察空间**：`GET /v1/cities/{id}/observation` 应返回一个高度结构化的 JSON，包含地图瓦片编码、需求指数（住宅/商业/工业）、关键统计（资金、人口、污染）、可用动作空间等，直接作为强化学习的环境状态。 * **动作验证与建议**：在执行动作前，提供 `GET /v1/cities/{id}/buildable?action=zone_industrial` 端点，返回所有可执行该动作的坐标列表，减少无效请求。 * **确定性保证**：在创建城市时传入的 `seed` 参数，必须保证在任何服务器、任何时间点都能重现完全相同的初始地图和随机数序列。 ### 总结与展望 通过 REST API 网关将 SimCity 这类复杂模拟游戏封装为服务，其价值远超创建一个“游戏服务器”。它提供了一个**高度可控、可观测、可重复**的复杂系统实验床。AI 代理可以在此学习城市规划、多目标优化、长期决策，甚至多个代理之间可以尝试协作或竞争策略。 Hallucinating Splines 的实践证明了利用现代云原生服务（如 Cloudflare Durable Objects）可以较低成本构建此类系统。下一步的演进方向可能包括：引入更细粒度的权限控制让不同代理操作同一城市的不同区域；增加更丰富的外部事件模拟（如灾难、经济波动）；以及提供标准化的 OpenAI Gym 或 PettingZoo 接口，使其无缝接入主流强化学习框架。 最终，这类架构的目标是模糊游戏模拟与 AI 训练环境之间的界限，让经典游戏引擎焕发新生，成为驱动 AI 智能体进化的数字沙盒。 --- **资料来源** 1. Hallucinating Splines 官方文档 (https://hallucinatingsplines.com/docs) 2. Hallucinating Splines GitHub 仓库架构说明 (https://github.com/andrewedunn/hallucinating-splines) ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。