更新日志

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

v0.6.0 (2026-05-19)

新增

• 小组件沙盒自动路由 — 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 }
  • 详见 AI 记忆

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

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