跳到正文

宿主桥接协议 ​

大多数游戏不应该直接使用宿主桥接。请使用 @vifu/hub。

这个页面面向高级调试和宿主实现者。

生命周期 ​

  1. 游戏包加载。
  2. VifuHub SDK 安装消息监听器。
  3. VifuHub SDK 发送运行环境准备完成通知。
  4. 宿主发送初始化消息。
  5. hub.ready() resolve,hub.status().hostConnected 变成 true。

公开 VifuHub SDK 对应关系 ​

VifuHub SDK API桥接目的
hub.ready()等待宿主初始化。
hub.tool(...)声明可调用的工具定义。
hub.agent(...)为 NPC、导师、AI 伙伴或其他实体创建独立 Runtime Agent。
hub.run(...)为目标 agent 执行一次模型 / 工具循环。
hub.resources.*解析或读取声明过的运行环境资源。
hub.gameState.*保存 / 恢复游戏自己的状态。
hub.ai.*通过提供方选择和使用量限制调用 Vifu AI。
hub.dictionary.*、hub.voice.*、hub.review.*、hub.camera.*、hub.invoke(...)调用声明过的宿主能力。

Runtime Agent 工具注册表 ​

Agent Runtime 会按 agent 和 run 隔离工具。一个 agent 暴露的工具不会出现在另一个 agent 上,除非游戏明确在那里注册。

直接传给 hub.run(agent, input, { tools }) 的工具只属于这一次 run,请求结束后会清理。注册在 agent 上的持久工具会一直保留,直到 agent 被 dispose。

Companion session socket 仍然只承担低频 play-session 事件。Runtime tool call 使用专门的 runtime-skill Durable Object / WebSocket 通道。

策略 ​

宿主会拒绝未声明的调用。请使用 ai、data、media、bundle、links、save、dictionary、voice、camera、review 这类公开清单中的名称。

不要为了游戏或后端逻辑直接使用原始 window.parent.postMessage(...)。原始桥接消息是宿主实现细节,在同一个兼容系列内也可能变化。