Vifu SDK

@vifu/sdk 是让 Vifu 上运行的游戏安全连接 Vifu Cloud 的公开浏览器 API。

游戏通过 SDK 完成这些事:

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

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

安装

npm

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

bash

npm install @vifu/sdk@alpha

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

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

CDN

可以从 jsDelivr 加载浏览器 build。部署游戏时使用精确版本：

html

<script src="https://cdn.jsdelivr.net/npm/@vifu/[email protected]/dist/browser/vifu-sdk.js"></script>
<script>
  const vifu = window.vifu;
</script>

基本模型

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

Runtime Agent

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

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

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

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

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

后续页面:

Vifu SDK ​

安装 ​

npm ​

CDN ​

基本模型 ​

Runtime Agent ​

Vifu SDK

安装

npm

CDN

基本模型

Runtime Agent