Vifu Hub SDK

@vifu/hub 是用于调用 Vifu Hub API 的官方浏览器工具，让 Vifu 上运行的游戏安全连接 Vifu Cloud。

游戏通过 Vifu Hub SDK 完成这些事:

调用 Vifu 管理的 AI。
把游戏自己执行的动作作为 AI tools 传给当前请求。
给 NPC、导师、AI 伙伴或其他互动实体绑定 Runtime Agent。
使用存档 / 读档、游戏数据、媒体和平台能力。
检查游戏在 Vifu 中是否已连接。

游戏代码不要直接请求 Vifu 后端、外部 AI 提供方或资源 URL。

安装

npm

使用打包工具或构建步骤的游戏，通过 npm 安装：

bash

npm install @vifu/hub@alpha

import * as hub from "@vifu/hub";

await hub.ready();

基本模型

API	使用场景
`hub.ai.generateText(...)`	游戏内文本、提示、NPC 对话和简单分类。
`hub.ai.generateText({ tools })`	为当前这一次 AI 请求暴露临时游戏动作。
`hub.tool(...)`	声明可复用的工具定义。
`hub.agent(...)`	为多个独立 NPC、导师、AI 伙伴或其他实体创建隔离的工具 / 指令 / 会话。
`hub.run(...)`	为指定 agent 执行一次模型 / 工具循环。
`hub.resources.*`	读取清单中声明的数据、媒体和随包文件。
`hub.gameState.*`	存档 / 读档流程。
`hub.invoke(...)`	低层平台能力调用。
`hub.status()`	检查游戏在 Vifu 中是否已连接。

Runtime Agent

多数游戏先用 hub.ai.generateText(...)。如果当前这次请求需要可见的游戏动作，直接传 tools 即可；不需要为了单个 NPC 对话创建 Runtime Agent。

Runtime Agent 适合多个独立实体同时存在的场景。它有自己的工具、指令和 run session。Companion 是其中一种面向用户的产品形态；NPC、Tutor、旁白、关卡导演或游戏对象也可以是其他 kind。

const openDoorTool = hub.tool({
  name: "open_door",
  description: "Open a visible door by color.",
  parameters: {
    type: "object",
    properties: {
      color: { type: "string", enum: ["blue", "red", "green"] }
    },
    required: ["color"],
    additionalProperties: false
  },
  execute: ({ color }) => openDoor(String(color))
});

const guard = hub.agent({
  name: "Blue Door Guard",
  kind: "npc",
  instructions: "You guard the current puzzle room.",
  tools: [openDoorTool]
});

const result = await hub.run(guard, "玩家说: open blue door", {
  state: currentRoomSummary(),
  maxSteps: 3
});

name 只是可读标签。Vifu 会自动分配内部 runtime id。省略 mind 时，由用户或宿主选择当前 Mind；只有游戏明确要绑定某个 Vifu Mind 时才设置它。

后续页面:

Vifu Hub SDK ​

安装 ​

npm ​

基本模型 ​

Runtime Agent ​

Vifu Hub SDK

安装

npm

基本模型

Runtime Agent