SDK API 参考

创建和连接等待

import { createVifuSDK } from "@vifu/sdk";

const vifu = createVifuSDK();
await vifu.ready();

console.log(vifu.status());

ready() 会在 Vifu 中等待所需连接。普通本地浏览器中也应该有可运行的备用逻辑。

AI

const result = await vifu.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 流程	vifu.ai.generateText(...)
当前请求需要临时工具	vifu.ai.generateText({ tools })
多个独立运行时实体	vifu.agent(...) + vifu.run(...)

Runtime Agent

const openDoorTool = vifu.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 = vifu.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 vifu.run(guard, "玩家请求打开蓝门。", {
  state: currentRoomSummary(),
  maxSteps: 3
});

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

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

资源

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

不要在游戏代码中拼接 /v1/assets/runtime-* 或发布后的 URL。SDK 会隐藏宿主管理的 URL 和令牌。

游戏状态

await vifu.gameState.save("autosave", {
  room: "blue-door",
  inventory: ["key"]
});

const checkpoint = await vifu.gameState.load("autosave");

平台能力

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

通常优先使用高层 API，只在需要时使用 vifu.invoke。