宿主桥接协议
大多数游戏不应该直接使用宿主桥接。请使用 @vifu/hub。
这个页面面向高级调试和宿主实现者。
生命周期
- 游戏包加载。
- Vifu Hub SDK 安装消息监听器。
- Vifu Hub SDK 发送运行环境准备完成通知。
- 宿主发送初始化消息。
hub.ready()resolve，hub.status().hostConnected变成true。
公开 Vifu Hub SDK 对应关系
| Vifu Hub 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 工具注册表
Vifu 会按 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(...)。原始桥接消息是宿主实现细节，在同一个兼容系列内也可能变化。