OhMyGame架构深度解析:Renderer、本地Daemon与Pi Agent如何协同驱动AI游戏工作室
OhMyGame架构深度解析:Renderer、本地Daemon与Pi Agent如何协同驱动AI游戏工作室
OhMyGame 是一款开源的 AI 游戏工作室,在一个应用里完成游戏设计、素材生成、编码、试玩到发布。本文完整解析 OhMyGame 架构的三大核心:React Renderer 界面层、运行在本地的 Fastify Daemon 服务层,以及基于 Pi 的 Agent 智能体,讲清楚三者如何通过本地 HTTP + SSE 协同驱动整个工作室。
🗺️ 一张图看懂 OhMyGame 三层架构
整个系统的分层在官方运行时文档中有一张清晰的示意图(摘自 docs/runtime.md):
┌──────────── Desktop app / web renderer ─────────────┐
│ Conversation │ Live preview / watch │
└──────────────┬──────────────────────────────────────┘
│ local HTTP + SSE (127.0.0.1)
┌──────────────┴──────── Local daemon ────────────────┐
│ Pi agent · playtest · Asset Canvas · plugins · MCP │
│ project workspaces · preview dev server │
└──────────────┬──────────────────────────────────────┘
│ Publish (static build only)
┌──────────────┴──────── OhMyGame Cloud ──────────────┐
│ immutable deployments · Community │
└─────────────────────────────────────────────────────┘
三个关键结论:
- 界面(Renderer)与业务(Daemon)彻底分离,两者只通过本机回环地址通信;
- 除发布外一切都在本地运行,项目文件、模型密钥、对话历史都留在你的机器上;
- 云端只接收静态构建产物,用于生成可分享的发布链接和社区展示。
🖥️ Renderer 界面层:只负责"看"和"说"
Renderer 是全部 React 组件构成的前端,位于 src/renderer/。它有一个很克制的设计:没有任何 Node.js 权限,不能碰文件系统,只能向 Daemon 发请求。
纯前端的隔离设计
桌面端(Electron)中,主进程只管理窗口生命周期,真正干活的是 Daemon。Daemon 的地址和一个随进程随机生成的令牌,通过隔离的 preload 桥(src/desktop/preload.cts)传给 Renderer,见 src/renderer/runtime-connection.ts#L19-L25:
const desktop = window.ohMyGameDesktop;
snapshot = { status: "ready", runtime: { url: desktop.runtime.daemonUrl, token: desktop.runtime.token } };
所有网络请求集中在 src/renderer/api.ts(约 1500 行),统一携带令牌访问 Daemon。Renderer 拿不到密钥、不接触项目源码目录——这是"界面可随意刷新、数据永不丢失"的基础。
SSE 事件流:界面如何实时跟随 Agent
Agent 的思考、工具调用、文件修改等事件,并不直接把 Pi 的内部事件对象丢给前端,而是由 Daemon 归一化成一套精简的运行时事件流,通过 SSE(Server-Sent Events)推送给 Renderer。两个细节值得新手注意:
- 断线重连会自动重放最近事件,刷新页面不会丢失或重复对话轮次;
- 对话本身持久化在 Pi 的会话文件里,重启应用后项目、上下文原样恢复。
⚙️ 本地 Daemon:工作室的"中控室"
Daemon 是运行在 127.0.0.1 上的 Fastify 服务,入口在 src/daemon/server.ts(开发模式默认端口 43110,见 src/daemon/server.ts#L82)。它是整个工作室的"中控室":项目管理、对话会话、Canvas 画板、预览 dev server、插件系统、MCP 服务、试玩驱动,全部由它托管。
安全边界:令牌走 stdin,密钥不出本机
有两个对普通用户很实在的安全设计:
- 只监听回环地址。默认 host 就是
127.0.0.1(src/daemon/server.ts#L19),局域网内其他设备无法访问这个服务; - 访问令牌通过 stdin 传递而非环境变量。桌面端启动 Daemon 时把随机令牌从标准输入写入子进程,注释写得很直白:"同一用户的其他进程也能读到进程启动时的环境变量"(src/desktop/daemon-process.ts#L75-L78)。
此外,你配置的所有模型密钥都存放在本地 Daemon 中,永远不会进入 Agent 的工作区、你的游戏代码或 Renderer。这也是 BYOK(自带密钥)体验得以成立的前提。
桌面守护:DaemonSupervisor 自动拉起崩溃的 Daemon
桌面端由 src/desktop/daemon-supervisor.ts 中的 DaemonSupervisor 守护 Daemon 进程:它按"服务代际(generation)"管理实例,Daemon 意外退出时会自动重启并把现有界面重新接入新实例,避免 UI 指向一个死掉的地址;60 秒窗口内连续崩溃超过 2 次则停止自动重启并提示错误(src/desktop/daemon-supervisor.ts#L129-L132)。
每个工作区都是文件
OhMyGame 有一个让 Agent 如鱼得水的约定:Web 游戏就是普通 Web 项目,设计文档就是 Markdown,画板和资产库共享同一套 JSON 节点模型。每个工作区还附带 AGENTS.md 与 JSON Schema,Agent 编辑它们的方式和编辑代码完全一致,视觉编辑器读的也是同一份文件。
🤖 Pi Agent:把"做游戏"变成一连串工具调用
40+ 模型供应商与 BYOK
智能体内核是 Pi。它通过 ModelRuntime 接入 40 多家模型供应商——Anthropic、OpenAI、Google、DeepSeek、Qwen、OpenRouter、Bedrock 等,支持 API Key 或已有订阅登录,密钥只存在于本地 Daemon。启动时 src/daemon/pi-agent.ts#L36 还会初始化受管的 Pi 环境(全局设置、内置 Skill 等)。
游戏即工具调用
普通编码 Agent 只有读写文件和执行命令等工具,而 OhMyGame 把玩游戏本身、生成媒体都注册为普通工具:game_use(试玩)、图片 / 视频 / 3D / 语音生成、问卷提问、update_plan、插件服务等,与编码工具并列(媒体工具 ID 定义见 src/shared/contracts.ts#L1136)。正因如此,Agent 能在同一轮对话里串联起"起草设计稿 → 生成美术资产 → 写代码 → 启动预览试玩 → 发现问题再修"的完整闭环。
可替换的智能体运行时:Claude Code / Codex / OpenCode
如果你更习惯用 Claude Code、Codex 或 OpenCode 这类编程 CLI,OhMyGame 也支持把它们作为可替换的 Agent 运行时(实现在 src/daemon/agent-runtimes/)。Daemon 会把自家工具通过一个名为 ohmygame 的 MCP 工具服务器暴露给这些 CLI(工具名带 mcp__ohmygame__ 之类前缀),它们沿用各自的登录与权限策略,而 OhMyGame 继续负责历史记录、撤销、画布、媒体工具和插件,详见 docs/coding-agents.md 与 docs/agent-runtimes.md。
🔁 一次对话的完整链路
把三层串起来,你发出"做一个打砖块游戏"之后,数据流是这样走的:
- Renderer 将 Prompt 通过
127.0.0.1的 HTTP 请求发给本地 Daemon(携带进程令牌); - Daemon 把 Prompt 写入当前项目的 Pi 持久化会话;
- Pi Agent 规划并调用工具:编辑代码、
generate-image生成贴图、game_use试玩…… - Daemon 将思考、工具调用、文件变更等归一化为运行时事件,经 SSE 推给 Renderer;
- 界面实时渲染对话时间线、画板节点与实时预览(Daemon 托管的 per-project dev server);
- 试玩发现问题后 Agent 自动修复并重试,全程可观察;
- 点击发布时,只有静态构建产物上传云端,生成可分享的链接。
📂 源码地图:快速定位关键模块
| 模块 | 路径 | 职责 |
|---|---|---|
| Renderer 界面层 | src/renderer/ | React 界面、状态管理与 API 调用 |
| 桌面主进程 | src/desktop/ | 窗口、Daemon 启动与守护恢复 |
| 本地 Daemon | src/daemon/ | Fastify 服务、路由与会话管理 |
| Daemon 入口 | src/daemon/server.ts | 令牌、网络代理与启动流程 |
| HTTP 路由 | src/daemon/app.ts | 项目 / 插件 / 画板 / 工具任务等 API |
| Pi Agent 集成 | src/daemon/agent.ts | 智能体会话、事件归一化与检查点 |
| 智能体运行时 | src/daemon/agent-runtimes/ | Claude Code / Codex / OpenCode 驱动 |
| 共享契约 | src/shared/ | 类型定义、事件与 API 契约 |
| 运行时文档 | docs/runtime.md | 架构、进程与恢复行为说明 |
| 画布文件契约 | docs/canvas-agent.md | Canvas 的 Markdown / JSON 节点模型 |
🚀 从源码运行 OhMyGame(可选体验)
想亲手验证这套架构,用源码跑起来很快(需 Bun 1.4.2+ 与 Node.js 22.19+):
git clone --branch main https://gitcode.com/gh_mirrors/oh/ohmygame
cd ohmygame
bun install --frozen-lockfile
bun run dev # 启动 Web Renderer(43120) + 本地 Daemon(43110)
bun run dev:desktop 则以 Electron 桌面应用形态运行,由主进程自行拉起 Daemon 并等待 /health(见 src/daemon/app.ts#L1024)就绪后才放行界面。
📝 小结
OhMyGame 的架构可以用一句话概括:Renderer 管展示、Daemon 管一切本地事务、Pi Agent 管创造。三层之间以"回环地址 + 进程令牌 + SSE 事件流"相连,既保证了密钥与项目数据的本地隐私,又让 Agent 拥有完整的工具链去设计、构建并试玩你的游戏。理解了这个分层,你就抓住了它"一人游戏工作室"体验的技术底座。




