宿主桥接协议

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

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

生命周期

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

公开 SDK 对应关系

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

Runtime Agent 工具注册表

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

直接传给 vifu.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(...)。原始桥接消息是宿主实现细节，在同一个兼容系列内也可能变化。