Vifu Hub SDK API 参考

引入和等待连接

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

await hub.ready();

console.log(hub.status());

所有平台能力都通过 hub 模块命名空间访问。ready() 会在 Vifu 中等待所需连接。普通本地浏览器中也应该有可运行的备用逻辑。

AI

const result = await hub.ai.generateText({
  model: "basic",
  messages: [{ role: "user", content: "玩家说: open blue door" }],
  tools: {
    openDoor: {
      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))
    }
  },
  maxSteps: 3
});

generateText 是多数游戏的默认 AI API。它接受 prompt 或 messages，也可以直接接受带 execute 的普通工具对象。Vifu 负责 provider 路由、额度和后端凭证。

model 是 Vifu 的模型层级名，不是提供方名称。当前公开文档使用 basic 和 quality。

选择哪个 AI API?

场景	API
游戏里只有一个当前 AI 流程	hub.ai.generateText(...)
当前请求需要临时工具	hub.ai.generateText({ tools })
多个独立运行时实体	hub.agent(...) + hub.run(...)

Runtime Agent

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]
});

Runtime Agent 是 NPC、导师、AI 伙伴、旁白或其他运行时实体。它有自己的工具、指令和 run session。 Vifu 会自动分配内部 runtime id；需要在日志和 trace 里更容易识别时，传 name。省略 mind 时，由用户或宿主选择当前 Mind。

const result = await hub.run(guard, "玩家请求打开蓝门。", {
  state: currentRoomSummary(),
  maxSteps: 3
});

如果只有这次请求能使用某些可见工具，可以把工具传给本次 run；这些工具只在本次请求中可用：

await hub.run(guard, "打开可见的门。", {
  tools: [openDoorTool]
});

资源

const episode = await hub.resources.readJson("episode");
const coverUrl = hub.resources.mediaUrl("cover");
const bundledAudio = hub.resources.fileUrl("./runtime-package/audio/intro.mp3");

hub.resources 会解析宿主管理的 URL 和令牌。

游戏状态

hub.gameState.configure({
  slotId: "autosave",
  source: "my-game",
  serialize: () => ({ room: "blue-door", inventory: ["key"] }),
  restore: (stateBlob) => restoreGame(stateBlob)
});

await hub.gameState.restore();
await hub.gameState.save({ reason: "level-complete" });

平台能力

const result = await hub.dictionary.lookup({
  text: "通っています",
  language: "ja"
});

平台能力使用对应的模块命名空间，例如 hub.dictionary、hub.voice、hub.review 和 hub.camera。