更新日志

记录每次 Storvia SDK 发布的新增、变更与破坏性升级。破坏性变更会在对应版本下提供迁移方案。

SDK 安装与初始化请参考 SDK 接入。

v0.9.4 (2026-07-28)

新增

chat.continue() 支持 sceneKey — 续写时可以带上场景 key，和 send / generate / retry 一致。
- 被续写的消息当初是带 sceneKey 发出的，续写就要带上原样的 key：否则补写出来的后半段拿不到场景设定里的输出形式与格式要求，会和前半段对不上（前半段一句台词、后半段变成大段叙述）。
- 纯增量可选参数，不传 = 保持原有行为。详见对话 · 场景设定。

v0.9.3 (2026-07-28)

新增

物品栏批量删除 — inventory.removeBatch(items) 一次请求删除多个物品（参数为 [{ group, name }, ...]），不存在的物品静默跳过（幂等），分组保留；传空数组直接返回、不发请求。详见属性 · 物品栏。
物品栏总数上限 100 → 200 — SDK add 与平台面板共用同一上限；达到上限后新增仍会被拒绝，需先删除释放空间。

清理

移除 story_mode 残留 — 剧情模式自 v0.9.2 起已由「预设」取代，本次仅清理遗留的过期测试与契约文档描述，SDK 请求行为不变，接入方无需任何改动。

v0.9.2 (2026-07-25)

变更

「剧情模式」开关下线，改为「预设」 — 玩家现在在模型选择器里挑一套「预设」（一种文风），而不是开关剧情模式。平台内置 平时叙事（文风自然均衡，适用于大多数题材与剧情）和剧情（更强的叙事张力与场景描写，偏小说笔触）。
- 接入方无需改动任何代码：跟模型选择一样由平台统一管理，玩家选好后 SDK 的 send / generate / retry / continue（含预览）会自动带上当前选择。升级依赖并重新构建、重新上传资源包即可生效。
- 原来的剧情模式开关已移除，「剧情」成为预设列表里的一项——玩家侧从「开关」变成「在列表里选一个」。
- 预设列表由平台维护、可能随时增减，不要在游戏里硬编码预设名或做分支判断。
- 详见对话 · 预设。

新增

模型选项带上多语言显示名 — ModelOption 新增 name_i18n / description_i18n（形如 { zh, zh_Hant, en, ja, ko }）。如果你在游戏里自己渲染模型列表，可以按玩家语言取对应译文，缺对应语言时回退到原本的 name / description。
- 纯增量字段，不影响现有代码。

v0.9.1 (2026-07-20)

修复

本地预览 / dev 模式对话现在会携带上下文 — 此前预览模式每轮请求都不带对话历史，AI 看不到之前的任何对话（你说过「我叫小明」，下一句问「我叫什么」它必然不知道），多轮连贯性完全无法本地测试。现在 SDK 会在内存中保留对话历史，每次发送自动带上最近的消息，连同本轮在内最多 20 条，与正式玩法的上下文窗口对齐。创作台预览同样生效。
- 接入方无需改动：升级依赖后本地预览自动获得多轮上下文。
- 历史仅保存在内存中，刷新页面后清空；预览模式的其他限制（游戏状态不跨轮演进、无持久消息等）不变。

该修复只影响本地预览 / 创作台预览，正式发布的游戏行为不变——重新安装依赖即可生效，无需重新上传资源包。

v0.9.0 (2026-07-16)

新增

续写 — chat.continue({ topic? }) 把上一条没写完的 AI 回复补完（覆盖式更新原消息，不会新增一条）。
```
await storvia.chat.continue({
  onChunk: (text) => appendToLastMessage(text),
  onDone: (id, info) => console.log('续写完成', id, info?.truncated),
});
```
- 原回复被截断时免费（不扣费、不卡余额）；否则按正常对话扣费。
- 不传 topic = 续写整个会话里最新的那条 AI 消息；传 topic = 续写该支线最新的一条。
- 只能流式调用。
- 支持 extract 内容过滤规则（续写 extract 模式的消息时须带上原样规则）；续写是纯追加，不改写已存内容。
- 预览模式无持久消息，continue() 静默返回。
onDone 新增 truncated 信息 — 流式 send / generate / retry / continue 的 onDone 第二个参数带 { truncated }，告诉你这条回复是不是被模型截断了（没写完就停）。true 时调 chat.continue() 免费，可据此显示「继续」按钮：
```
await storvia.chat.send({
  message: '...',
  stream: true,
  onChunk: (text) => { /* ... */ },
  onDone: (id, info) => {
    if (info?.truncated) showContinueButton();
  },
});
```
老代码无需改动：onDone: (id) => {…} 照常工作，第二个参数是可选的。
chat.messages() 每条消息新增 truncated — 刷新 / 重进游戏后仍能判断哪条回复被截断，决定要不要给它显示「继续」按钮（user 消息恒 false）。
中断生成 — chat.cancel({ topic? }) 停止在途生成（停止按钮）→ { active, generationId? }。
```
const { active } = await storvia.chat.cancel();
if (!active) resetStoppingUI(); // 生成已跑完，取消来晚了（竞态）
```
- active: false = 生成已经跑完、取消信号来晚了：不会再收到 aborted 事件，正常的 done 已经在流里，应立即复位「停止中」这类 UI 状态。
- active: true = 已发出取消信号，等 onAborted 统一收尾，不要自己动本地流。
- 预览模式无在途生成，恒返回 { active: false }。

onAborted 回调 — 流式 send / generate / retry / continue / resume 新增可选回调，生成被中断时触发：

await storvia.chat.send({
  message: '...',
  stream: true,
  onChunk: (text) => { /* ... */ },
  onAborted: ({ id, persisted }) => {
    if (!persisted) restoreInputBox(); // 零内容中断，玩家的话得放回去
  },
});

字段	说明
`id`	AI 消息 uuid；`persisted:false` 时为空串
`persisted`	半截内容是否已入库。`false` = 还没吐出任何内容就停了，未入库也未扣费 —— 此时你必须把玩家刚发的输入放回输入框，否则玩家的话就丢了

提供 onAborted 后不再触发 onDone；未提供时降级为 onDone(id)，保证总有一个终态回调。

中断只要已经产生了内容就会计费：按量计费的模型按实际产生的 token 收费，按次计费的模型扣一整次。只有还没吐出任何内容就停（persisted:false）才不计费。

类型导出：ChatContinueOptions / ChatCancelOptions / ChatCancelResult / ChatDoneInfo / ChatDoneCallback / ChatAbortInfo / ChatAbortedCallback

变更

新增错误码 GENERATION_ABORTED（生成被用户主动中断）。中断不是失败，SDK 不会为它弹错误提示；若你自己在 catch 里统一弹错，建议把这个码排除掉。

升级依赖后必须重新构建、重新上传资源包才会生效。"@storvia/sdk": "^0.9.x" 重新安装即可拿到 0.9.0。

v0.8.5 (2026-07-08)

变更

打字机节奏放慢 — 平滑器默认参数由 tickMs 33 / baseLagMs 450 调整为 tickMs 100 / baseLagMs 1000，逐字更沉稳、不再「眼花缭乱」，并更好地吸收服务端更大粒度的攒批下发（后端攒批窗口同步放宽到 1000ms）。接入方无需改动；默认值已内置，SDK 不提供覆盖参数。

升级依赖后必须重新构建、重新上传资源包才会生效。"@storvia/sdk": "^0.8.x" 重新安装即可拿到 0.8.5。

v0.8.4 (2026-07-08)

新增

打字机平滑输出 — 服务端为降低资源开销，流式增量改为攒批下发（单批文本更大、频率更低）。SDK 内置平滑器把到达的大块文本按节拍小片吐给 onChunk，逐字观感与旧版一致，且自动适应服务端的攒批粒度。接入方无需改动；但请勿依赖 onChunk 单次回调的片段大小或频率（拼接结果不变）。
服务端终态错误即时透传 — 流式过程中服务端下发终态错误（如生成进程失联，新错误码 GENERATION_LOST）时，SDK 立即抛出 StorviaError。此前这类错误会先走完 10 次退避重连、约 2 分钟后才以 STREAM_INTERRUPTED 报错。

修复

流式连接结束但未收到终止事件时，已到达的文本现在保证在方法返回前全部通过 onChunk 吐出（此前末尾一小段可能延迟到达）。

升级依赖后必须重新构建、重新上传资源包才会生效。"@storvia/sdk": "^0.8.x" 重新安装即可拿到 0.8.4。

v0.8.3 (2026-07-07)

新增

剧情模式（story mode） — 玩家可在 Storvia 内切换「剧情模式」，开启后 AI 回复会切换到更适合剧情叙事的风格。接入方无需改动任何代码：跟模型选择一样由平台统一管理，玩家切换后 SDK 的 send / generate / retry（含预览）会自动带上当前选择，升级依赖并重新构建即可生效。

已于 v0.9.2 下线：剧情模式开关被「预设」取代，「剧情」成为预设列表里的一项。见对话 · 预设。

升级依赖后必须重新构建、重新上传资源包才会生效。"@storvia/sdk": "^0.8.x" 重新安装即可拿到 0.8.3；若锁了具体版本号，请改为 "^0.8.3" 后再安装。

v0.8.2 (2026-07-05)

修复

流式解析健壮性 — 修复弱网 / 移动网络下流式回复的两类偶发问题（网络分片恰好切断一条事件时触发，手机上概率更高）：
- 流式 send / generate / retry 偶发「没有结局」：onDone 不触发、也不报错，体感为发送后一直无响应。
- onState 偶发丢一次状态更新：面板不刷新，要等下一条消息才恢复。
断线重连的确定性收尾 — 重连后若回复已在服务端完成，现在保证 onDone 一定触发（此前极端情况下可能静默返回、回调不来）。仅在该极端场景下 onDone 的 id 可能为空字符串，如需最终内容可用 chat.messages() 拉取最新消息。

修复在 SDK 内部，升级依赖后必须重新构建、重新上传资源包才会生效。注意：package.json 里若写的是 "@storvia/sdk": "^0.7.0"，它不会自动升到 0.8.x，请手动改为 "^0.8.2" 后再安装。

v0.8.1 (2026-07-03)

变更

移除 chat.active() — 查询「是否有在途生成」的探针方法已移除。chat.resume() 内部已处理「无在途生成」的情况（直接静默返回），进对话时无需先查询、直接调用 resume() 即可接管——有在途就实时续读，没有就静默跳过。
- 迁移：把 const { active } = await chat.active(); if (active) await chat.resume(...) 直接改成 await chat.resume(...)。
- 同时移除类型导出 ChatActiveResult。
- 详见对话 · 断线续传。

v0.8.0 (2026-06-27)

新增

断线续传 — 流式生成跑在服务端、与你的网络连接解耦，AI 回复时刷新、切后台、关 App / 浏览器、断网或弱网抖动都不会中断或丢内容。多数接入方无需改动，流式 send / generate / retry 自动从断点续读重连。
- onReconnecting 回调 — 流式 send / generate / retry 新增可选回调，中途断开自动重连时触发，可用来显示「正在重新连接 n/10」提示：
```
await storvia.chat.send({
  message: '...',
  stream: true,
  onChunk: (text) => { /* ... */ },
  onReconnecting: ({ attempt }) => showReconnectingTip(attempt),
});
```
  退避重连最多 10 次，期间生成在服务端继续跑；10 次都失败才抛 StorviaError（code: STREAM_INTERRUPTED）。
- chat.active({ topic? }) — 查会话（可按 topic）当前是否有在途生成 → { active, generationId? }。
- chat.resume({ topic?, onChunk, onDone, onState, onThinking, onReconnecting }) — 接管在途生成并实时续读（刷新 / 换设备 / 多端接力）。服务端已无在途生成则静默返回。
- 多设备接力：A 设备发起、B 设备 resume() 可看到同一段正在输出的内容。
- 类型导出：ChatResumeOptions / ChatActiveResult / ChatReconnectingCallback
- 详见对话 · 断线续传。

续传只对正式发布的持久会话有效；预览模式无在途生成，active() 恒返回 { active: false }、resume() 静默返回。

变更

错误码更精细 — 对话失败时返回的错误码做了细化，方便你按原因精确处理，而不是都归到笼统的几个码。新增可捕获的错误码：
- GENERATION_TIMEOUT（生成超时）、REPETITION_LOOP（回复出现重复循环）、SAVE_FAILED（保存失败，本次不扣费）、FINALIZE_FAILED（回复处理失败）、CONVERSATION_NOT_FOUND（会话不存在）、EMPTY_MESSAGE（消息为空）、CONTINUE_MODEL_NOT_AVAILABLE / CONTINUE_PROMPT_MISSING
- 部分原本归到 CONTENT_FILTERED 的失败（如回复重复循环）、原本归到 STREAM_INTERRUPTED 的失败（如生成超时），现在有了各自独立的错误码
- 兼容性：升级到 0.8 即可按新错误码精确提示；仍用 0.7 的游戏会把这些新码当作未知码走 default 兜底（仍会显示提示文案，不会报错），建议升级到 0.8
- 详见对话 · 错误处理

v0.7.0 (2026-06-16)

破坏性变更

移除 SDK 内置的「模型 + 游戏设置」浮窗 — 模型选择、回复长度、温度等改由 Storvia 平台（网页端 / App）界面提供，游戏内不再出现 SDK 自带的设置悬浮按钮。
- 多数接入方无需改动：平台会在初始化时下发当前模型，并在玩家切换模型后实时同步，SDK 自动应用到后续对话。
- 若你此前依赖 SDK 自带浮窗让玩家选模型，现在交给平台即可，无需自行实现。

移除 storvia.syncSettings() — 设定同步由平台负责，SDK 不再提供该方法。

// 旧（v0.6.x）
await storvia.syncSettings();

// 新（v0.7.0）—— 删除该调用，设定同步由平台处理

新增

dev.model 参数 — 本地测试时指定初始模型：

const storvia = await createStorviaSDK({
  dev: {
    apiKey: "sk-storvia-xxxxxx",
    gameId: "your-game-id",
    model: "双子 · 3.1", // 模型展示名；不传则用第一个可用模型
  },
});

详见本地测试。

变更

本地预览 / dev 模式不再有 SDK 内置模型选择器；通过 dev.model 指定初始模型。

v0.6.1 (2026-06-08)

新增

onCreatedCharacters 回调 — 在 chat.send / chat.generate / chat.retry 流式调用中新增可选回调，本轮 AI 创造出新角色时触发，回调收到新角色名字数组，可用来提示玩家有新角色登场
- 签名：onCreatedCharacters?: (names: string[]) => void
- 非流式调用从 ChatResponse.createdNames 获取

await storvia.chat.send({
  message: '...',
  stream: true,
  onCreatedCharacters: (names) => {
    showNewCharacterCard(names);
  },
});

修复

修复在设置面板切换模型后选择未被记住的问题；现在所选模型会被保留，并与主站保持一致

v0.6.0 (2026-05-19)

小组件作者必读：编写或维护小组件必须升级到 ≥ 0.6.0。低版本会让 custom / save 写到主线 / 撞其他组件，造成数据污染。

新增

小组件沙盒自动路由 — custom / save 模块在每次请求自动追加 ?game_id=<gameId> 查询串，后端按 game_id 把读写隔离到该小组件自己的沙盒
- 作者无需修改任何代码，依旧调用 sdk.custom.set(...) / sdk.save.set(...)
- 主线场景（非小组件）行为不变
- 多个小组件之间天然隔离，不会互相覆盖
小组件能力公告 — 配合小组件章节上线；小组件可与主线共享角色 / 物品 / 世界 / 记忆 / 人设，并拥有自己独立的 custom / save 沙盒

破坏性变更

内部 CustomModule / SaveModule 构造函数新增 getGameId 参数（位置 3）。直接 new CustomModule(...) / new SaveModule(...) 的代码需要补上回调；通过 sdk.custom / sdk.save 使用的作者不受影响

v0.5.30 (2026-05-15)

新增

onThinking 回调 — 在 chat.send / chat.generate / chat.retry 流式调用中新增可选回调，监听模型 reasoning 状态
- 签名：onThinking?: (status: 'start' | 'end') => void
- 仅支持具备 reasoning 能力的模型（如 DeepSeek-R1 系列）；普通模型不会触发
- status === 'start'：模型进入思考态（开始产出 reasoning_content）
- status === 'end'：思考结束，开始输出正文 token
- 触发时机相对 onChunk：onThinking('start') → 思考期间持续触发 SSE 但不调 onChunk → onThinking('end') → onChunk(...) 开始
- 不会重复触发：每轮生成最多一次 start + 一次 end
- 用法示例：在 loading 气泡上切换"正在思考"提示 / 流光动画

await storvia.chat.send({
  message: '...',
  stream: true,
  onChunk: (text) => { /* ... */ },
  onThinking: (status) => {
    if (status === 'start') showThinkingIndicator();
    else hideThinkingIndicator();
  },
});

SSE 事件新增

{"type":"thinking","status":"start"|"end"} — 模型 reasoning 状态变更
- messages 边缘函数（主站聊天 /messages/conversations/:uuid/messages、/retry、/preview）
- world-engine 边缘函数（World SDK /chat、/generate、/retry、/preview）

v0.5.28 (2026-05-13)

新增

chat.delete({ uuid }) — 删除指定消息
- 不重算 state、不回溯后续消息、不调 AI、不扣费
- user / assistant 消息都可删除
- 仅删除该条消息本身，不会级联删除之后的消息
- 预览模式下不可用（预览消息不会持久化），抛 StorviaError（code: NOT_SUPPORTED_IN_PREVIEW）
- 详细 API 参考对话 · chat.delete()
chat.rollback({ uuid }) — 回溯到指定消息（删除其后所有消息 + 恢复 game_state 快照）
- 仅雏菊卡（sub_tier1）订阅有效用户可用；非订阅用户抛 StorviaError（code: DAISY_CARD_REQUIRED，HTTP 403）
- 命中 DAISY_CARD_REQUIRED 时 SDK 强制弹出钱包跳转 sheet（与 INSUFFICIENT_CREDITS 同款样式），「去开通」通过 bus 引导宿主跳转钱包页
- 仅可回溯 30 天内的消息（超期抛 MESSAGE_TOO_OLD）
- 目标消息保留，其后所有消息会被删除且无法恢复
- 若目标消息有 game_state_snapshot，会用快照覆写会话的 current / dormant 状态
- 不调 AI、不扣费
- 预览模式下不可用，抛 StorviaError（code: NOT_SUPPORTED_IN_PREVIEW）
- 详细 API 参考对话 · chat.rollback()

新增错误码

DAISY_CARD_REQUIRED / MESSAGE_NOT_FOUND / MESSAGE_TOO_OLD / NO_MESSAGES_TO_DELETE

v0.5.18 (2026-05-06)

新增

storvia.memory — SDK 新增 AI 记忆模块，读取/编辑当前会话的"AI 记忆"长期总结
- memory.get() → AISummary | null：读取记忆，首次未生成时返回 null
- memory.update(content) → AISummary：整体覆写记忆内容，自动 trim
- 返回结构 { content, updated_at }
- 详见永久记忆（该模块读写的即是后来界面上的「永久记忆」档）

v0.5.17 / 主站 v2.0.8 (2026-05-05)

新增

官方素材库 — 平台提供官方头像、物品图标素材，作者和玩家可在创作台、聊天页面、个人资料的图片选择器中「从素材库选择」
- 创作台预设角色头像、物品图标编辑器新增「从素材库选择」选项
- 聊天页面人设编辑器、物品栏编辑器从原本仅支持文件上传，升级为三种方式（本地上传 / URL / 素材库）
- 我的页面人设编辑同样支持三种图片选择方式
storvia.getAssets(type, category?) — SDK 新增顶层方法，作者代码中可按类型和分类拉取素材库内容
- 类型：'avatar'（头像）/ 'icon'（物品图标）
- 可选 category 参数按分类过滤
- 返回 AssetItem[]：{ id, name, url, assetType, category }
GM 后台素材库管理 — 新增「素材库管理」面板，支持添加素材、设置/切换分类、启停、排序
公开 API GET /world-engine/v1/assets — 支持 JWT 或 API Key 鉴权，可按 asset_type 和 category 过滤

创作台 (2026-05-05)

变更

场景设定移除 1000 字硬上限 — 创作台「场景设定」单条值不再有字数限制
- 字符计数器仍然显示当前长度，但不再变红、不再阻止保存
- 总字数统计逻辑保持不变：所有场景设定按最长那个计入「世界观/剧情设定」的 30000 字总上限

v0.5.16 (2026-05-05)

变更

预览模式不可用方法的报错统一 — chat.retry / chat.edit / state.get 在预览模式下现在都抛出 StorviaError，错误码统一为 NOT_SUPPORTED_IN_PREVIEW
- 之前 chat.retry 和 chat.edit 抛的是普通 Error，无法通过 err.code 统一捕获
- 现在调用方可以用 if (err.code === 'NOT_SUPPORTED_IN_PREVIEW') 一段代码处理这三个方法的预览模式失败
- 错误消息也统一：明确告知"需要发布后在 Storvia 平台测试"
文档强化 — 在 chat.retry / chat.edit / state.get / storvia.save 的文档中加入醒目警告
- 三个预览不可用的方法：明确标注「需要发布后在 Storvia 平台测试」
- storvia.save：明确禁止存放图片本体（base64 / dataURL / 二进制），只能存 URL / 路径，否则会因超过 256KB 上限导致存档丢失

v0.5.15 (2026-05-05)

新增

chat.send / generate / retry 新增 extract 选项 — 流式 + 入库内容过滤
- 提供 { start, end } 起止标记，AI 回复中只有 start..end 之间的内容会被推送给前端 + 写入数据库；其余（思考、旁白、元数据）会被丢弃
- 多段 start..end 自动拼接为一条消息
- 流式过滤：SSE 推送也只下发范围内内容，跨 chunk 拆分的标签可正确处理（不会把 </re 误当作正文 emit）
- fallback 行为：AI 一次都没输出 start 时，自动回退保存原始干净文本（避免空消息），便于排查 prompt 问题
- 起止标记是字面量字符串（非正则），支持中文 / emoji 等任意 UTF-8
- 长度上限 64 字符；start === end 会被拒绝

v0.5.14 (2026-05-05)

新增

chat.edit({ uuid, content }) — 编辑指定消息的文本内容
- 不重新调 AI、不重算 state、不扣费；仅覆写 content，role / topic / status 均保持不变
- user / assistant 消息都可编辑
- 预览模式下不可用（预览消息不会持久化）
- 详细 API 参考对话 · chat.edit()

v0.5.8 (2026-04-27)

新增

chat.send / generate / retry 响应新增 delta / full 字段
- 非流式调用：AI 本轮有属性变更时，ChatResponse 携带 delta（本轮增量）+ full（完整状态快照）
- 流式调用新增 onState 回调：AI 本轮有属性变更时触发，参数为 (delta, full)
- 不再需要每次对话后手动调 storvia.state.get() 来获取最新状态
类型导出：State / CurrentState / DormantState / StateChanges / ChatStateCallback

v0.5.6 (2026-04-27)

新增

storvia.state.get() — 一次性读取当前会话所有模块（world / player / characters / inventory / relationships）的合并快照
- 返回 { current, previous, dormant } 三部分：当前状态、上一轮快照、休眠区角色
- 适合渲染整体属性面板、做存档导出、或调试时观察当前游戏状态
- 预览模式下不可用
- 详细 API 请参考属性 · storvia.state

v0.5.5 (2026-04-25)

新增

custom.setInject(key, inject) — 单独切换某个 key 的 AI 追踪状态（不修改值），分组的 setInject 等价于整组开关
custom.set(data, { inject }) — set 新增可选 inject 选项，一次性把这次写入的所有 key 标记为对应 inject 状态
custom.getInject() — 同步读取当前所有顶层 key 的 inject 状态
创作台分组级 AI 追踪开关 — 分组 header 加 AI 开关，开启后组内所有子字段整组注入；移除子字段独立 inject 开关

v0.5.3 (2026-04-25)

新增

storvia.save — 游戏存档模块，专供游戏运行状态持久化
- 支持任意合法 JSON（嵌套对象、数组、布尔等）
- 永不注入 AI，AI 完全感知不到
- 独立配额，不计入 custom 的 40 字段上限
- 整体覆写语义（get → 修改 → set）
- 序列化后大小上限 256KB
- 详细 API 请参考属性 · storvia.save

v0.5.2 (2026-04-24)

新增

chat.messages(options) — 获取聊天记录
- 支持按 topic 过滤
- 双向游标分页（order: 'asc' | 'desc'），适配"游戏内聊天框向上翻阅更旧消息"与"历史记录页向下翻阅更新消息"两种场景
- limit 范围 1–50，默认 20
- 预览模式下返回空数组，不影响测试
- 详细 API 请参考聊天 · chat.messages()

更新日志

On this page