SDK 初始化
Storvia SDK 的引入、初始化和基本使用
引入 SDK
在 HTML 中通过 <script> 标签引入 SDK 文件：
<script src="js/storvia-sdk.js"></script>引入后，全局会多出一个 StorviaSDK 类。
初始化
const sdk = new StorviaSDK();
await sdk.init();init() 是一个异步方法，会自动完成以下步骤：
- 从 Storvia 平台接收配置（API 地址、游戏 ID、用户身份）
- 鉴权并获取或创建用户存档
- 加载模型列表和用户设置
- 在页面右下角挂载设置悬浮按钮
init() 必须在使用任何 SDK 功能之前调用。如果初始化失败（比如用户未登录），会抛出错误。建议用 try/catch 包裹：
try {
await sdk.init();
// 初始化成功，开始游戏
} catch (err) {
console.error('SDK 初始化失败:', err.message);
// 显示错误提示
}SDK 模块一览
初始化成功后，可以通过以下模块访问平台能力：
| 模块 | 访问方式 | 功能 |
|---|---|---|
| 对话 | sdk.chat | AI 对话（发送/保存/生成） |
| 角色 | sdk.characters | 角色 CRUD + 角色属性 |
| 玩家 | sdk.player | 玩家信息 + 玩家属性 |
| 关系 | sdk.relationships | 角色间关系 CRUD |
| 物品 | sdk.inventory | 物品栏 CRUD |
| 世界 | sdk.world | 世界状态读写 |
| 自定义 | sdk.custom | 自由读写任意数据 |
Debug 模式
在初始化前设置 debug: true，可以在浏览器控制台查看所有 SDK 请求和响应：
window.__STORVIA__ = {
...window.__STORVIA__,
debug: true,
};开启后，控制台会打印每个请求的方法、路径、参数和响应内容，方便调试。
Debug 模式仅用于开发调试，发布前建议移除。正式环境下 window.__STORVIA__ 由平台自动注入，不需要手动设置。
错误处理
SDK 的所有异步方法在出错时会抛出 StorviaError，包含错误码和消息：
try {
await sdk.chat.send({ message: '你好', topic: 'main' });
} catch (err) {
console.error(err.code, err.message);
// 常见错误码：
// UNAUTHORIZED — 用户未登录
// INSUFFICIENT_BALANCE — 花园币不足
// RATE_LIMITED — 请求太频繁
// GAME_NOT_FOUND — 游戏不存在
// INTERNAL_ERROR — 服务器错误
}| 错误码 | 含义 | 建议处理 |
|---|---|---|
UNAUTHORIZED | 用户未登录或 token 过期 | 提示用户重新登录 |
INSUFFICIENT_BALANCE | 花园币不足 | 提示用户充值 |
RATE_LIMITED | 请求频率过高 | 等待后重试 |
GAME_NOT_FOUND | 游戏或存档不存在 | 检查游戏是否已发布 |
INTERNAL_ERROR | 服务器内部错误 | 重试或联系管理员 |