SDK 初始化

已有项目接入

纯 HTML 项目（无构建工具）

直接通过 CDN 引入，无需 npm 或构建工具：

<script src="https://cdn.jsdelivr.net/npm/@storvia/sdk/dist/index.umd.js"></script>
<script type="module">
    const storvia = await window.createStorviaSDK();
</script>

npm 项目（Vue / React 等）

安装 SDK：

npm install @storvia/sdk

在入口文件中导入：

import { createStorviaSDK } from "@storvia/sdk";

const storvia = await createStorviaSDK();

使用构建工具（Vite 等）时，需在 vite.config.js 中设置 base: './'，确保打包后资源使用相对路径。详见快速开始。

初始化

createStorviaSDK() 是异步工厂函数，会自动完成以下步骤：

从 Storvia 平台接收配置（API 地址、游戏 ID、用户身份）
鉴权并获取或创建用户存档
加载模型列表和用户设置
在页面右下角挂载设置悬浮按钮

建议用 try/catch 包裹：

try {
    const storvia = await createStorviaSDK();
    // 初始化成功，开始游戏
} catch (err) {
    console.error("SDK 初始化失败:", err.message);
}

本地调试

本地开发时 SDK 无法从平台获取配置，可通过 API Key 进入 dev 模式：

在创作台将游戏发布为私有
获取 gameId：进入游戏详情页，点击右上角「⋯」菜单，选择「复制游戏 ID」
在创作台「API 密钥」页面生成一个 API Key
本地代码传入 dev 配置：

const storvia = await createStorviaSDK({
    dev: {
        apiKey: "sk-storvia-xxxxxx",
        gameId: "your-game-id",
    },
});

dev 模式走预览模式：AI 对话正常工作（消耗创作者花园币），游戏状态不持久化。API Key 不要提交到 git，上传 ZIP 时平台会自动扫描并拦截。

SDK 模块一览

初始化成功后，可以通过以下模块访问平台能力：

模块	访问方式	功能
对话	`storvia.chat`	AI 对话（发送/保存/生成）
角色	`storvia.characters`	角色列表 + 角色属性读写
玩家	`storvia.player`	玩家信息 + 玩家属性读写
关系	`storvia.relationships`	角色间关系 CRUD
物品	`storvia.inventory`	物品栏 CRUD（上限 20）
世界	`storvia.world`	世界状态读写
扩展属性	`storvia.custom`	文本/数值字段读写（上限 40，AI 追踪可在创作台或者SDK控制）
存档	`storvia.save`	游戏运行状态持久化（任意 JSON，独立配额，不注入 AI）

每个模块的详细 API 见聊天和属性。

Debug 模式

在初始化前设置 debug: true，可以在浏览器控制台查看所有 SDK 请求和响应：

window.__STORVIA__ = {
    ...window.__STORVIA__,
    debug: true,
};

Debug 模式仅用于开发调试，发布前建议移除。正式环境下 window.__STORVIA__ 由平台自动注入，不需要手动设置。

错误处理

SDK 会自动捕获常见错误（余额不足、频率限制、登录失效等）并以 Toast 通知的形式展示给用户，无需在业务代码中逐一处理。

关闭内置 Toast

如果你想完全自己接管错误提示 UI（例如用自己的 toast 组件、对话框，或者直接静默处理），可以调用 setToastEnabled(false) 关闭 SDK 内置的 toast：

import { setToastEnabled } from "@storvia/sdk";

// 关闭所有内置 toast（包括错误、成功、信息提示）
setToastEnabled(false);

// 需要时可以再开回来
setToastEnabled(true);

这是一个全局开关，会同时关闭所有类型的 toast（error / success / warning / info），无法只静默某一类。关闭后请务必通过 try/catch 自己处理错误，否则用户将完全得不到反馈。

如果需要在特定操作出错时执行自定义逻辑（如跳转页面、记录日志），可以用 try/catch 捕获：

try {
    await storvia.chat.send({ message: "你好", topic: "main" });
} catch (err) {
    // err.message 是可读的错误描述
    console.error("发送失败:", err.message);
}

以下是 SDK 可能抛出的错误码，供参考：

错误码	含义
`UNAUTHORIZED`	用户未登录或 token 过期
`INSUFFICIENT_CREDITS`	花园币不足
`RATE_LIMITED`	请求频率过高
`GAME_NOT_FOUND`	游戏或存档不存在
`INVENTORY_LIMIT`	物品栏已满（上限 20）
`CUSTOM_FIELDS_LIMIT`	扩展属性字段已满（上限 40）
`REQUEST_TIMEOUT`	请求超时（60 秒内未收到服务器响应）
`MODEL_LOADING_TIMEOUT`	模型响应超时（180 秒内未收到第一个 token）
`STREAM_INACTIVITY`	流式连接中断（60 秒内未收到任何数据）
`INTERNAL_ERROR`	服务器内部错误

SDK 初始化

On this page