小组件

什么是小组件

小组件是一种特殊的沉浸创作模式：它可以嵌入到某个深度模式的游戏（下面称之为主线）里运行。

典型用途：

群聊
私聊
热搜
...

小组件与主线共享用户、消息、记忆、人设、属性；只有自己的 剧情设定、场景设定、自定义 几个区块是独立的私有沙盒。

创作流程

在创作台「创作模式」面板选择「沉浸创作」
勾选「可作为小组件」开关
你可以编辑的区块：
- 世界观及剧情设定：小组件本身的 LLM 设定（人设、行为规则、回复风格等）
- 场景设定：小组件自己的场景设定，类似于沉浸模式（不同场景下不同行为）
- 自定义属性：小组件的私有沙盒字段
- 封面、标题、标签、简介、开幕小剧场等基础信息

小组件能做什么

资源	小组件能读吗	小组件能写吗
主线消息	✅ 共用（按 topic 区分）	✅ 写自己 topic
主线 AI 记忆	✅	✅（与主线 LLM 同等待遇）
主线人设	✅	✅
主线角色 / 物品 / 关系 / 世界 / 玩家	✅	✅ AI 自动更新更新
自己的 `自定义` 属性	✅	✅

关键点：

小组件与主线共用深度模式的所有属性，在小组件中，还可以访问小组件专属的自定义属性
AI 会分别更新主线属性和小组件的自定义属性

沙盒数据

每次小组件被安装到某主线对话，会给你的小组件开一份私有沙盒，存放 custom 属性。

用户卸载小组件：沙盒数据保留（重新安装即恢复，不会丢失数据，也不会自动清理数据）
多次安装同一小组件：使用同一份沙盒

Topic 命名约定

小组件通过 SDK 调用聊天能力时必须传一个 topic，让自己的消息流与主线（storvia_chat_main）以及其他小组件区分开。

强制格式：<游戏 id>:<组件内部 topic>

前缀 = 游戏 id（game_id），即你这个小组件被发布后由平台分配的唯一标识。平台保证全局唯一，永远不会与别人的小组件撞。
- 还没发布拿不到 id？可以先把小组件以私有可见性发布一次，发布成功后即可在游戏详情页拿到 game_id，再回来填到 topic 里使用
后缀 = 你小组件内部自己用的 topic 名（自由命名，用来区分自己内部的多条对话流，如不同房间、不同会话）

// 推荐：用 game_id 作为前缀
const topic = `${gameId}:main`;            // 组件主聊天流
const topic = `${gameId}:room-${roomId}`;  // 多房间场景
const topic = `${gameId}:user-${userId}`;  // 多对一私聊

// 不推荐
const topic = "chat";              // 没前缀，必撞主线 / 其他组件
const topic = "widget:chat";       // 前缀不带游戏 id，多个小组件同名会撞

平台不会强制校验 topic 格式，但不按这个规范走，发生跨组件消息污染时责任自负。

读取消息历史（自己 / 主线 / 全部）

小组件通过 chat.messages({ topic, ... }) 拉消息时，topic 参数决定看到的范围：

传值	拿到的范围	典型用途
`${gameId}:xxx`（自己的 topic）	仅自己这个 topic 的消息	小组件正常聊天 / 翻看历史
`"storvia_chat_main"`	主线对话的消息	想让小组件「读懂主角现在在干嘛」
其他小组件的 topic	该组件的消息	一般用不到，不建议跨组件读
不传 / `null`	当前会话下所有 topic 的消息（主线 + 全部组件）	极少需要；通常是 bug

// 小组件自己的对话历史
await sdk.chat.messages({ topic: `${gameId}:main`, order: 'asc', limit: 20 });

// 主线对话历史（让群聊 / 私聊 widget 知道主角刚发生了什么）
await sdk.chat.messages({
  topic: 'storvia_chat_main',
  order: 'desc',
  limit: 10,
});

// 全部消息（不传 topic）—— 几乎用不到，注意会拿到所有 widget 的消息流
await sdk.chat.messages({ order: 'desc', limit: 20 });

不传 topic 会把当前 conversation 下所有 topic 的消息混在一起返回（主线 + 你自己 + 其他小组件）。除非确实需要"全景视角"，否则永远显式传 topic，避免拿到不该读的内容、上下文错乱。

SDK 调用

聊天、属性（创建、修改、删除）、玩家人设编辑、角色人设（创建、修改、删除）等功能和沉浸模式完全一样调用 SDK 即可。读写 custom 属性会自动落到你自己的沙盒，不需要做任何额外处理。

共享设置

以下设置不属于小组件，跟着当前主线对话走：

模型选择
温度
回复长度
回复语言

小组件

On this page