@storvia/sdk 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -31,7 +31,7 @@ declare class HttpClient {
     delete<T>(path: string): Promise<T>;
     stream(path: string, body: unknown, onChunk: (text: string) => void, onDone: (id: string) => void, meta?: {
         modelName?: string;
-    }, onState?: (delta: unknown, full: unknown) => void, onThinking?: (status: 'start' | 'end') => void): Promise<void>;
+    }, onState?: (delta: unknown, full: unknown) => void, onThinking?: (status: 'start' | 'end') => void, onCreatedCharacters?: (names: string[]) => void): Promise<void>;
     /**
      * 读取完整响应文本，解析为 JSON 并返回 `{ raw, data }`：
      * - `raw` 是后端返回的整体（用于 debug 完整打印，含 success/code/message 等包装字段）
@@ -97,6 +97,13 @@ interface StateChanges {
 type ChatStateCallback = (delta: StateChanges, full: State | null) => void;
 /** 模型 reasoning 状态回调：'start' 表示开始思考，'end' 表示思考结束、开始输出正文 */
 type ChatThinkingCallback = (status: 'start' | 'end') => void;
+/**
+ * 新角色出场回调：本轮 AI 创造了之前从未出现过的「真·新角色」时触发。
+ * @param names 新角色名字数组（apply 后 current 里、apply 前 current∪dormant 都没有的）；
+ *   不含休眠恢复 / 被限额挤进 dormant 的角色。作者可据此弹「新角色出现」提示卡片。
+ * 非流式调用通过 ChatResponse.createdNames 获取，无需此回调。
+ */
+type ChatCreatedCharactersCallback = (names: string[]) => void;
 /**
  * 流式 + 入库内容过滤规则。提供后，服务端只保留 AI 回复中
  * `start..end` 之间的内容（多段会自动拼接），其余被丢弃。
@@ -126,6 +133,8 @@ interface ChatSendOptions {
     onState?: ChatStateCallback;
     /** 模型 reasoning 状态变更（'start' = 开始思考，'end' = 开始输出正文）；仅支持思考型模型 */
     onThinking?: ChatThinkingCallback;
+    /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
+    onCreatedCharacters?: ChatCreatedCharactersCallback;
 }
 interface ChatSaveOptions {
     role: 'user' | 'assistant';
@@ -144,6 +153,8 @@ interface ChatGenerateOptions {
     onState?: ChatStateCallback;
     /** 模型 reasoning 状态变更（'start' = 开始思考，'end' = 开始输出正文）；仅支持思考型模型 */
     onThinking?: ChatThinkingCallback;
+    /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
+    onCreatedCharacters?: ChatCreatedCharactersCallback;
 }
 interface ChatRetryOptions {
     topic?: string;
@@ -157,6 +168,8 @@ interface ChatRetryOptions {
     onState?: ChatStateCallback;
     /** 模型 reasoning 状态变更（'start' = 开始思考，'end' = 开始输出正文）；仅支持思考型模型 */
     onThinking?: ChatThinkingCallback;
+    /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
+    onCreatedCharacters?: ChatCreatedCharactersCallback;
 }
 interface ChatResponse {
     id: string;
@@ -165,6 +178,8 @@ interface ChatResponse {
     delta?: StateChanges;
     /** 合并后的完整状态快照，仅在有变更时出现；结构同 storvia.state.get() */
     full?: State;
+    /** 本轮出现的「真·新角色」名字数组，仅在有新角色时出现 */
+    createdNames?: string[];
 }
 interface ChatMessageCursor {
     uuid: string;
@@ -370,13 +385,6 @@ interface State {
     dormant: DormantState;
 }
 
-interface GameSettings {
-    temperature: number;
-    replyLength: string;
-    replyLanguage: string;
-    playerNote: string;
-}
-
 declare class ChatModule {
     private http;
     private getGameId;
@@ -384,9 +392,8 @@ declare class ChatModule {
     private getModelId;
     private isPreview;
     private previewConfig?;
-    private getSettings?;
     private getModelName?;
-    constructor(http: HttpClient, getGameId: () => string, getConversationId: () => string, getModelId: () => string, isPreview?: boolean, previewConfig?: Record<string, unknown>, getSettings?: () => GameSettings | null | undefined, getModelName?: () => string | undefined);
+    constructor(http: HttpClient, getGameId: () => string, getConversationId: () => string, getModelId: () => string, isPreview?: boolean, previewConfig?: Record<string, unknown>, getModelName?: () => string | undefined);
     /** 构造 http 层的元信息（用于 debug 日志标题显示） */
     private reqMeta;
     /** 更新预览配置（由父页面 postMessage 触发） */
@@ -676,10 +683,11 @@ declare class MemoryModule {
 interface DevConfig {
     apiKey: string;
     gameId: string;
+    /** 本地预览/dev：指定初始模型的展示名（display name）。不传则用第一个可用模型。 */
+    model?: string;
 }
 declare class StorviaSDK {
     private http;
-    private settingsSheet;
     private baseUrl;
     private gameId;
     private conversationId;
@@ -701,6 +709,12 @@ declare class StorviaSDK {
     state: StateModule;
     memory: MemoryModule;
     init(): Promise<void>;
+    /**
+     * 监听宿主运行时下发的模型切换（envelope 'set-model'）。
+     * 正式模式用：宿主已接管模型选择，用户在宿主 FAB 改模型时实时同步到 SDK。
+     * （预览模式的 set-model 在 listenForPreviewMessages 内单独处理。）
+     */
+    private listenForModelChange;
     /**
      * 监听父页面 token 刷新（envelope 'token-update'）。
      * Supabase JWT 默认 1h 过期，父页面 session 自动刷新后转发新 token 进来，
@@ -718,13 +732,8 @@ declare class StorviaSDK {
     private fetchPreviewSnapshot;
     /** 重新拉 snapshot 并把结果灌进每个 module 的 mem（用于 update-config 后同步） */
     private refreshPreviewSnapshot;
-    /** 保存设置到后端 */
-    private saveSettings;
-    /** 同步最新游戏设定到当前存档 */
-    syncSettings(): Promise<void>;
     private fetchModels;
     private authenticate;
-    private getSavedModelId;
     initDev(devConfig: DevConfig): Promise<void>;
     getAssets(type: 'avatar' | 'icon', category?: string): Promise<AssetItem[]>;
 }
@@ -772,6 +781,12 @@ interface InitPayload {
      * 待主站 / App 全部升级后改为必填，以彻底消除 /auth 端选错存档的漂移。
      */
     conversationId?: string;
+    /**
+     * 宿主（主站/App）已选中的模型 UUID。宿主已接管模型选择 → 正式模式优先用它，
+     * 盖过 SDK 自己的 localStorage / 列表首项。随 init 一起下发，避免「init 后单独发 set-model」
+     * 在 SDK 注册监听前到达而丢失的竞态。运行时切换仍走 envelope 'set-model'。
+     */
+    selectedModelId?: string;
     debug?: boolean;
 }
 interface PreviewConfig {
@@ -830,7 +845,7 @@ interface AckPayload {
     error?: string;
 }
 type DownstreamMsg = ProtocolEnvelope<'init', InitPayload> | ProtocolEnvelope<'preview-init', PreviewInitPayload> | ProtocolEnvelope<'token-update', TokenUpdatePayload> | ProtocolEnvelope<'config-update', ConfigUpdatePayload> | ProtocolEnvelope<'set-model', SetModelPayload> | ProtocolEnvelope<'orientation', OrientationPayload> | ProtocolEnvelope<'ack', AckPayload>;
-type UpstreamMsg = ProtocolEnvelope<'ready', ReadyPayload> | ProtocolEnvelope<'exit', Record<string, never>> | ProtocolEnvelope<'request-orientation', OrientationPayload> | ProtocolEnvelope<'error', SdkErrorPayload> | ProtocolEnvelope<'navigate', NavigatePayload> | ProtocolEnvelope<'ack', AckPayload>;
+type UpstreamMsg = ProtocolEnvelope<'ready', ReadyPayload> | ProtocolEnvelope<'exit', Record<string, never>> | ProtocolEnvelope<'request-orientation', OrientationPayload> | ProtocolEnvelope<'error', SdkErrorPayload> | ProtocolEnvelope<'navigate', NavigatePayload> | ProtocolEnvelope<'model-change', SetModelPayload> | ProtocolEnvelope<'ack', AckPayload>;
 declare function isProtocolEnvelope(data: unknown): data is ProtocolEnvelope<string, unknown>;
 declare function envelope<T extends string, P>(type: T, payload: P, opts?: {
     id?: string;