Hermes3D 3D场景实现原理:运行时事件如何变成办公室里走动的 AI Agent
Hermes3D 3D场景实现原理:运行时事件如何变成办公室里走动的 AI Agent
Hermes3D 是一个基于 Hermes Agents 的开源 3D 虚拟办公室,它把看不见的 AI Agent 工作过程,变成一间可以"走进去"的 3D 场景:Agent 会在工位上敲代码、去机房看 Pull Request、接电话、开会站会。本文带你完整拆解它的核心原理——运行时事件(runtime events)是如何一步步变成办公室里走动的 AI Agent 的。
一图看懂:从 Gateway 事件到 3D 办公室的完整链路
整个系统可以抽象成 5 层流水线:
Hermes Gateway(事件源头)
↓ WebSocket
Studio WS 代理(/api/gateway/ws,第二跳连接)
↓
runtimeEventBridge(事件分类:runtime-chat / runtime-agent)
↓
eventTriggers(事件归约 → 空间指令:去工位、去机房、打电话……)
↓
retro-office 3D 场景(导航网格寻路 + 碰撞避让 + 动画)
这条链路的关键设计是:3D 场景层从不直接处理原始事件,它只消费一份"提炼后的动画状态"(OfficeAnimationState)。这样既让渲染层可测试、可复现,也让 2D 像素办公室和 3D 办公室共享同一套 Agent 状态来源(见 ARCHITECTURE.md 中 Office flow 一节)。
第 1 步:Gateway 推送运行时事件流
Hermes3D 本身不是 Agent 运行时,它只是可视化与交互层。真正的 Agent 记录、会话、审批和运行事件都归属于后端的 Hermes Gateway。
浏览器并不会直连上游 Gateway,而是走"两跳"连接(这是项目的重要架构决策,详见 ARCHITECTURE.md 的 Core Boundaries 一节):
- 浏览器 → Studio:通过 HTTP + 同源 WebSocket
/api/gateway/ws连接。 - Studio → 上游 Gateway:由 Studio 服务端(server/gateway-proxy.js)在服务端打开第二条 WebSocket,把两端的帧互相转发。
这个设计让上游 URL 和 token 保持在服务端管理,也支持本地、远程、Tailscale 隧道等多种部署形态。事件流的具体格式可参考 docs/pi-chat-streaming.md。
第 2 步:事件分类——先分清"这是谁在干什么"
事件进入前端后,第一步是分类。核心入口是 runtimeEventBridge.ts 中的 classifyGatewayEventKind,它把每一帧事件归为四类:
| 事件类型 | 含义 | 对办公室的暗示 |
|---|---|---|
runtime-chat |
聊天流事件(用户消息 / 助手回复 / 思考) | Agent 在"工作"、"打字"或"思考" |
runtime-agent |
Agent 运行时流(工具调用、推理流等) | Agent 正在执行任务 |
summary-refresh |
摘要/状态快照刷新 | 更新 Agent 卡片与汇总 |
ignore |
无关事件 | 丢弃 |
分类器还会识别"推理流"(如 reason、think、analysis 等流名,见 runtimeEventBridge.ts),把思考类内容从普通文本流中区分出来——这决定了办公室里 Agent 头顶冒出的是"💭 思考"还是"💬 打字"气泡。
第 3 步:事件归约——把"流"变成"空间指令"
这是整个原理中最关键的一环,实现在 src/lib/office/eventTriggers.ts 中。它的核心思想写在源码注释里:
办公室动画分两遍推导:事件归约记录来自 Gateway 新流量的短命"闩锁"(latch);对账重建从当前 Agent 与对话状态恢复持久"滞留"(hold)。3D 场景只消费
buildOfficeAnimationState()的输出。
具体做法:
reduceOfficeAnimationTriggerEvent()(eventTriggers.ts):每收到一帧事件,根据事件类型更新"时间戳型"状态。例如:- 有
runId的事件 → 给该 Agent 盖上 5 秒的"工作中"时间戳(workingUntilByAgentId); - 助手流式输出 → 6 秒"打字中"时间戳;
- 推理内容 → 6 秒"思考中"时间戳;
- 执行审批请求/批准 → 标记等待审批。
- 有
reconcileOfficeAnimationTriggerState()(eventTriggers.ts):周期性"对账"。即使断线重连错过了部分事件,也能从 Agent 当前状态和最近聊天记录里重放出最近的用户意图(比如最后一条消息是"去工位"),恢复出正确的空间状态。buildOfficeAnimationState()(eventTriggers.ts):最终投影。它把带时间戳的中间状态压缩成场景真正需要的"现在时"布尔值:deskHoldByAgentId(留在工位)、githubHoldByAgentId(在机房看代码)、phoneBoothHoldByAgentId(在电话亭)……时间戳过期即自动失效,Agent 就"走开"。
第 4 步:自然语言意图解析——聊天内容直接指挥 Agent 走动
光有"工作中"还不够,Hermes3D 还让对话内容本身驱动空间行为。src/lib/office/deskDirectives.ts 被源码注释称为"办公室移动与房间意图的唯一自然语言入口"。
它会识别聊天消息中的意图并输出统一的 OfficeIntentSnapshot:
- "go to your desk" / "sit at your desk" → 回工位;
- 提到
server room、github、pull request、code review→ 去机房(Server Room)审代码; - "gym" 相关 → 去健身房练新技能;
- "review some PRs" → 机房 PR 审看;
- 打电话 / 发短信意图 → 电话亭、短信亭流程(含
needs_message→ready_to_call两阶段)。
解析结果带缓存(LRU,容量 250),避免每帧重复正则计算。这样,你在任何地方对 Agent 说"去机房看看那个 PR",办公室里对应的小人就会真的走过去的 🚶
第 5 步:3D 场景消费状态——寻路、碰撞与动画
在 OfficeScreen.tsx 中,buildOfficeAnimationState 的输出会与技能触发器(如"去点唱机")合并,形成最终的 officeAnimationState,再交给 RetroOffice3D.tsx(基于 Three.js + React Three Fiber)渲染。
让 Agent "走得像真的员工",靠的是两套系统:
- 导航网格寻路:buildNavGrid 按 25px 网格把会阻挡通行的家具(由
ITEM_METADATA.blocksNavigation统一声明)栅格化为障碍物,边界墙也会标记为不可通行;Agent 的目标点由 navigation 路由模块 解析——机房、电话亭、QA 实验室、健身房各有resolveXxxRoute目标解析器。 - 碰撞避让:NavigationSystem.tsx 用空间分桶(bucket)加速邻近查询,两个 Agent 距离小于两倍半径时互相推开,并会朝最顺的"漫游点"(ROAM_POINTS)重新规划路径——所以你偶尔会看到两个 Agent 撞肩后各自"绕路"的有趣细节。
另外,办公室被划分为多个"城区"(district.ts):本地办公室区、城市步道区、远程办公室区(remote: 前缀的 Agent 出现在远程区),这为多 Agent 协同的 Beta 特性做了空间上的隔离。
核心文件速查表
想深入源码?按这条顺序读最高效:
| 环节 | 文件 |
|---|---|
| 事件分类 | src/features/agents/state/runtimeEventBridge.ts |
| 事件→空间指令 | src/lib/office/eventTriggers.ts |
| 自然语言意图 | src/lib/office/deskDirectives.ts |
| 状态装配与渲染入口 | src/features/office/screens/OfficeScreen.tsx |
| 寻路与碰撞 | src/features/retro-office/core/navigation.ts、src/features/retro-office/systems/NavigationSystem.tsx |
| 服务端 WS 代理 | server/gateway-proxy.js |
| 2D 像素办公室(共享同一状态源) | src/features/pixel-office/ |
小结:为什么这样设计
Hermes3D 的 3D 场景之所以"活",来自一条清晰的单向数据流:Gateway 事件 → 分类 → 归约/对账 → 投影 → 场景消费。
- 派生状态而非复制状态:UI 永远从 Gateway 事件推导视图,不制造第二份"真相";
- 场景层无脑消费:3D 层只认"现在时"的布尔与时间戳,可测试、可复现,2D/3D 渲染器随时可换;
- 断线可恢复:对账机制让重连后的办公室能从聊天记录里"回忆"起 Agent 该在哪。
下次当你看着办公室里的小人接到消息后起身走向机房,背后正是这条事件流水线在无声运转 🏢✨

