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();

初始化

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

1. 从 Storvia 平台接收配置（API 地址、游戏 ID、用户身份、当前模型）
2. 鉴权并获取或创建用户存档
3. 加载模型列表，并应用平台下发的当前模型
4. 准备各功能模块（对话、角色、属性等）

建议用 try/catch 包裹：

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

本地调试

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

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

const storvia = await createStorviaSDK({
    dev: {
        apiKey: "sk-storvia-xxxxxx",
        gameId: "your-game-id",
        model: "超速DS · 4 · 直连", // 可选，本地测试用的初始模型（界面上显示的模型名，任一语言都行）；不传则用第一个可用模型
    },
});

SDK 模块一览

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

每个模块的详细 API 见 聊天 和 属性；storvia.host 只在小组件里有意义，见 小组件 · 通知主线 / 刷新主线面板。

调试

SDK 不开放 debug 日志开关。window.__STORVIA__ 是平台侧初始化通信用的对象，由平台自动注入并整体覆盖，往里写 debug: true 不会生效（dev 模式不读这个对象，平台模式下宿主也不会下发 debug 配置）。

排查问题请直接用浏览器开发者工具的 Network 面板查看 SDK 的请求与响应，SSE 流可以在响应的 EventStream 里逐条看。更多本地调试细节见 沉浸创作本地测试。

错误处理

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

花园币不足 / 需要雏菊卡

这两种情况由平台接管，不走 Toast：SDK 会通知平台，平台弹出自己的充值引导（网页端在游戏上方弹充值弹窗，玩家不用离开游戏；App 跳到钱包页）。

你不需要为它们写任何处理代码。注意即使调用了 setToastEnabled(false)，这两种情况依然会触发平台引导——这是平台级统一行为，不受该开关影响。

关闭内置 Toast

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

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

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

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

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

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

命中违禁词时拿到具体的词（SDK 0.9.7 起）

VIOLATION_WORD_DETECTED 抛出的错误上会多带一个 matchedWords 字段（string[]），列出这次命中的违禁词，方便你在自己的 UI 里精确提示玩家改哪儿：

try {
    await storvia.chat.send({ message: text, topic: "main" });
} catch (err) {
    if (err.code === "VIOLATION_WORD_DETECTED") {
        highlightInInput(err.matchedWords); // ['词A', '词B']
        return;
    }
    throw err;
}

发消息、预览、保存消息、编辑消息、修改角色人设、修改玩家人设都会带上这个字段。SDK 内置 toast 也会自动把词拼进文案（「内容包含不符合社区规范的用词「词A」「词B」，请修改后重试」），所以不接管错误 UI 的话什么都不用做。

以下是 SDK 可能抛出的全部错误码（与 StorviaErrorCode 类型一一对应）。

鉴权与配额

资源与请求

生成过程

网络与超时