SDK API 参考

工具@vifu/[email protected]

Protocolcompanion.plugin.v1

运行环境Browser

状态公开 alpha

API

API	用途
createVifuSDK(options)	创建 SDK 实例。游戏中使用 transport: "auto"。
context(name, definition)	注册 companion 可读取的游戏状态。
command(name, definition)	注册 companion 可以请求的应用拥有动作。
observe(type, data, options)	上报普通玩法事实。
signal(type, definition)	定义希望 companion 关注的少量关键时刻。
Vifu.resources.readJson(id) / Vifu.resources.readText(id)	读取宿主管理的运行时资源。
Vifu.resources.dataUrl(id) / Vifu.resources.mediaUrl(id) / Vifu.resources.fileUrl(path)	解析宿主管理的运行时 URL。
invoke(capabilityId, args)	请求宿主或后端拥有的平台能力。
status()	返回 SDK 版本、协议、传输方式和 host 连接状态。
isHostConnected()	host 初始化后返回 true。

Context

companion.context("scene.current", {
  description: "Current scene and objective",
  read: () => ({ scene: "market", objective: "Ask for water" })
});

read 返回的值会进入 prompt。不要包含 token、隐藏答案或私有笔记。

Command

companion.action("dialogue.repeat", {
  title: "Repeat line",
  inputSchema: { type: "object", properties: {}, additionalProperties: false },
  handler: () => ({ ok: true })
});

Command 应该保持小而明确，并且对玩家有可见效果。

Resource

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

resource 是宿主管理运行时数据和媒体的公开入口。SDK 会把运行时 base URL、预览路由和 token 留在 host adapter 内部。游戏代码不要直接构造 /v1/assets/runtime-* 或 /preview-* URL。

Invoke

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

await Vifu.services.invoke("host.game_state.persist", {
  slotId: "autosave",
  stateBlob: { cardId: "card-1" },
  source: "anki-runtime"
});

invoke(capabilityId, args) 用来请求宿主或后端拥有的平台能力。不要把平台能力注册成游戏 command，也不要为每个功能新增公开 SDK wrapper 或直接发送 postMessage。