OhMyGame架构深度解析:Renderer、本地Daemon与Pi Agent如何协同驱动AI游戏工作室

原创2026-10-22 22:57:172,312 阅读
文章标签:人工智能AI 应用AI Agent游戏开发代码智能体媒体生成

OhMyGame架构深度解析:Renderer、本地Daemon与Pi Agent如何协同驱动AI游戏工作室

OhMyGame 是一款开源的 AI 游戏工作室,在一个应用里完成游戏设计、素材生成、编码、试玩到发布。本文完整解析 OhMyGame 架构的三大核心:React Renderer 界面层、运行在本地的 Fastify Daemon 服务层,以及基于 Pi 的 Agent 智能体,讲清楚三者如何通过本地 HTTP + SSE 协同驱动整个工作室。

🗺️ 一张图看懂 OhMyGame 三层架构

OhMyGame 开源 AI 游戏工作室界面横幅

整个系统的分层在官方运行时文档中有一张清晰的示意图(摘自 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                  │
└─────────────────────────────────────────────────────┘

三个关键结论:

  1. 界面(Renderer)与业务(Daemon)彻底分离,两者只通过本机回环地址通信;
  2. 除发布外一切都在本地运行,项目文件、模型密钥、对话历史都留在你的机器上;
  3. 云端只接收静态构建产物,用于生成可分享的发布链接和社区展示。

🖥️ Renderer 界面层:只负责"看"和"说"

OhMyGame AI 游戏工作室项目管理工作台

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:工作室的"中控室"

OhMyGame AI 游戏工作室项目工作区文件与发布命令界面

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:把"做游戏"变成一连串工具调用

OhMyGame AI 游戏工作室首次启动模型供应商连接设置

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

OhMyGame AI 游戏代理设置页中的 Codex 编程智能体状态

如果你更习惯用 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。

🔁 一次对话的完整链路

把三层串起来,你发出"做一个打砖块游戏"之后,数据流是这样走的:

  1. Renderer 将 Prompt 通过 127.0.0.1 的 HTTP 请求发给本地 Daemon(携带进程令牌);
  2. Daemon 把 Prompt 写入当前项目的 Pi 持久化会话;
  3. Pi Agent 规划并调用工具:编辑代码、generate-image 生成贴图、game_use 试玩……
  4. Daemon 将思考、工具调用、文件变更等归一化为运行时事件,经 SSE 推给 Renderer;
  5. 界面实时渲染对话时间线、画板节点与实时预览(Daemon 托管的 per-project dev server);
  6. 试玩发现问题后 Agent 自动修复并重试,全程可观察;
  7. 点击发布时,只有静态构建产物上传云端,生成可分享的链接。

📂 源码地图:快速定位关键模块

模块 路径 职责
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 拥有完整的工具链去设计、构建并试玩你的游戏。理解了这个分层,你就抓住了它"一人游戏工作室"体验的技术底座。

登录后查看全文
ohmygame