Hermes3D 3D场景实现原理:运行时事件如何变成办公室里走动的 AI Agent

原创2026-11-02 22:23:342,463 阅读

Hermes3D 3D场景实现原理:运行时事件如何变成办公室里走动的 AI Agent

Hermes3D 是一个基于 Hermes Agents 的开源 3D 虚拟办公室,它把看不见的 AI Agent 工作过程,变成一间可以"走进去"的 3D 场景:Agent 会在工位上敲代码、去机房看 Pull Request、接电话、开会站会。本文带你完整拆解它的核心原理——运行时事件(runtime events)是如何一步步变成办公室里走动的 AI Agent 的。

Hermes3D 3D 虚拟办公室中的 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 一节)。

Hermes3D 办公室背景场景,Agent 在其中走动协作

第 1 步:Gateway 推送运行时事件流

Hermes3D 本身不是 Agent 运行时,它只是可视化与交互层。真正的 Agent 记录、会话、审批和运行事件都归属于后端的 Hermes Gateway。

浏览器并不会直连上游 Gateway,而是走"两跳"连接(这是项目的重要架构决策,详见 ARCHITECTURE.md 的 Core Boundaries 一节):

  1. 浏览器 → Studio:通过 HTTP + 同源 WebSocket /api/gateway/ws 连接。
  2. 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 "走得像真的员工",靠的是两套系统:

  1. 导航网格寻路:buildNavGrid 按 25px 网格把会阻挡通行的家具(由 ITEM_METADATA.blocksNavigation 统一声明)栅格化为障碍物,边界墙也会标记为不可通行;Agent 的目标点由 navigation 路由模块 解析——机房、电话亭、QA 实验室、健身房各有 resolveXxxRoute 目标解析器。
  2. 碰撞避让: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 该在哪。

下次当你看着办公室里的小人接到消息后起身走向机房,背后正是这条事件流水线在无声运转 🏢✨

登录后查看全文
Hermes3D