@storvia/sdk 0.6.1 → 0.8.0

package/dist/index.d.mts

@@ -1,3 +1,15 @@
+/** 续读/重连共用的回调集合（与 stream() 的散参一一对应）。 */
+interface SSECallbacks {
+    onChunk: (text: string) => void;
+    onDone: (id: string) => void;
+    onState?: (delta: unknown, full: unknown) => void;
+    onThinking?: (status: 'start' | 'end') => void;
+    onCreatedCharacters?: (names: string[]) => void;
+    /** 每次发起重连前触发（attempt 从 1 递增），供 UI 提示「正在重新连接」。 */
+    onReconnect?: (info: {
+        attempt: number;
+    }) => void;
+}
 declare class HttpClient {
     private baseUrl;
     private token;
@@ -31,7 +43,28 @@ 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, onCreatedCharacters?: (names: string[]) => void): Promise<void>;
+    }, onState?: (delta: unknown, full: unknown) => void, onThinking?: (status: 'start' | 'end') => void, onCreatedCharacters?: (names: string[]) => void, resume?: {
+        conversationId: string;
+        topic?: string;
+    }, onReconnect?: (info: {
+        attempt: number;
+    }) => void): Promise<void>;
+    private static readonly RECONNECT_MAX_ATTEMPTS;
+    private static readonly RECONNECT_BACKOFF_CAP;
+    /**
+     * 重连循环：退避 → GET 续读 → 直到拿到终止事件 / 服务端报无在途 / 次数耗尽。
+     * 每次重连前回调 onReconnect 供 UI 提示「正在重新连接 n/10」。
+     */
+    private resumeLoop;
+    /**
+     * 公开续读入口：接管某会话/ topic 的在途生成（刷新 / 换设备 / 多端接力时用）。
+     * 无在途生成则静默返回。供 ChatModule.resume() 调用。
+     */
+    resumeStream(conversationId: string, topic: string | undefined, cb: SSECallbacks): Promise<void>;
+    /** 单次 GET 续读：拉一段 SSE 并分发。无在途生成（服务端回 JSON）返回 'inactive'；HTTP/网络失败抛出供上层退避。 */
+    private pumpGetStream;
+    /** 共享 SSE 读循环：解析 id:/data:，分发 content/state/thinking/done，跟踪 lastId。带无活动超时（cancel 后返回 'eof' 供重连）。 */
+    private pumpReader;
     /**
      * 读取完整响应文本，解析为 JSON 并返回 `{ raw, data }`：
      * - `raw` 是后端返回的整体（用于 debug 完整打印，含 success/code/message 等包装字段）
@@ -53,7 +86,7 @@ interface AssetItem {
     assetType: 'avatar' | 'icon';
     category: string;
 }
-type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'VIOLATION_WORD_DETECTED' | 'CONTENT_FILTERED' | 'MODEL_REFUSAL' | 'STREAM_INTERRUPTED' | 'RATE_LIMITED' | 'MODEL_NOT_FOUND' | 'GAME_NOT_FOUND' | 'INVALID_REQUEST' | 'INTERNAL_ERROR' | 'NOT_INITIALIZED' | 'NOT_SUPPORTED_IN_PREVIEW' | 'NETWORK_ERROR' | 'REQUEST_TIMEOUT' | 'MODEL_LOADING_TIMEOUT' | 'STREAM_INACTIVITY' | 'DAISY_CARD_REQUIRED' | 'MESSAGE_NOT_FOUND' | 'MESSAGE_TOO_OLD' | 'NO_MESSAGES_TO_DELETE';
+type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'VIOLATION_WORD_DETECTED' | 'CONTENT_FILTERED' | 'MODEL_REFUSAL' | 'STREAM_INTERRUPTED' | 'RATE_LIMITED' | 'MODEL_NOT_FOUND' | 'GAME_NOT_FOUND' | 'INVALID_REQUEST' | 'INTERNAL_ERROR' | 'NOT_INITIALIZED' | 'NOT_SUPPORTED_IN_PREVIEW' | 'NETWORK_ERROR' | 'REQUEST_TIMEOUT' | 'MODEL_LOADING_TIMEOUT' | 'STREAM_INACTIVITY' | 'DAISY_CARD_REQUIRED' | 'MESSAGE_NOT_FOUND' | 'MESSAGE_TOO_OLD' | 'NO_MESSAGES_TO_DELETE' | 'GENERATION_TIMEOUT' | 'REPETITION_LOOP' | 'SAVE_FAILED' | 'FINALIZE_FAILED' | 'CONVERSATION_NOT_FOUND' | 'EMPTY_MESSAGE' | 'CONTINUE_MODEL_NOT_AVAILABLE' | 'CONTINUE_PROMPT_MISSING';
 /** AI 本轮的属性变更（仅包含发生改变的字段） */
 interface StateChanges {
     /** 世界状态变更（扁平 KV） */
@@ -104,6 +137,14 @@ type ChatThinkingCallback = (status: 'start' | 'end') => void;
  * 非流式调用通过 ChatResponse.createdNames 获取，无需此回调。
  */
 type ChatCreatedCharactersCallback = (names: string[]) => void;
+/**
+ * 断线重连回调：流式生成中途断开（刷新/切后台/断网/弱网）后，SDK 自动经
+ * GET /conversations/:id/stream 续读，每次发起重连前触发。
+ * @param info.attempt 第几次重连尝试（从 1 递增，最多 10 次）
+ */
+type ChatReconnectingCallback = (info: {
+    attempt: number;
+}) => void;
 /**
  * 流式 + 入库内容过滤规则。提供后，服务端只保留 AI 回复中
  * `start..end` 之间的内容（多段会自动拼接），其余被丢弃。
@@ -135,6 +176,8 @@ interface ChatSendOptions {
     onThinking?: ChatThinkingCallback;
     /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
     onCreatedCharacters?: ChatCreatedCharactersCallback;
+    /** 仅流式：生成中途断开后 SDK 自动续读，每次重连前触发，供 UI 提示「正在重新连接」 */
+    onReconnecting?: ChatReconnectingCallback;
 }
 interface ChatSaveOptions {
     role: 'user' | 'assistant';
@@ -155,6 +198,8 @@ interface ChatGenerateOptions {
     onThinking?: ChatThinkingCallback;
     /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
     onCreatedCharacters?: ChatCreatedCharactersCallback;
+    /** 仅流式：生成中途断开后 SDK 自动续读，每次重连前触发，供 UI 提示「正在重新连接」 */
+    onReconnecting?: ChatReconnectingCallback;
 }
 interface ChatRetryOptions {
     topic?: string;
@@ -170,6 +215,8 @@ interface ChatRetryOptions {
     onThinking?: ChatThinkingCallback;
     /** 本轮出现「真·新角色」时触发；非流式调用通过 ChatResponse.createdNames 获取，无需此回调 */
     onCreatedCharacters?: ChatCreatedCharactersCallback;
+    /** 仅流式：生成中途断开后 SDK 自动续读，每次重连前触发，供 UI 提示「正在重新连接」 */
+    onReconnecting?: ChatReconnectingCallback;
 }
 interface ChatResponse {
     id: string;
@@ -181,6 +228,26 @@ interface ChatResponse {
     /** 本轮出现的「真·新角色」名字数组，仅在有新角色时出现 */
     createdNames?: string[];
 }
+/** chat.active() 返回：该会话/ topic 当前是否有在途生成。 */
+interface ChatActiveResult {
+    /** 是否有正在进行的生成 */
+    active: boolean;
+    /** 在途生成的 id（active 为 true 时存在） */
+    generationId?: string;
+}
+/**
+ * chat.resume() 选项：接管会话/ topic 的在途生成（刷新 / 换设备 / 多端接力）。
+ * 流式回调与 send 一致；无在途生成时静默返回。
+ */
+interface ChatResumeOptions {
+    topic?: string;
+    onChunk?: (text: string) => void;
+    onDone?: (id: string) => void;
+    onState?: ChatStateCallback;
+    onThinking?: ChatThinkingCallback;
+    onCreatedCharacters?: ChatCreatedCharactersCallback;
+    onReconnecting?: ChatReconnectingCallback;
+}
 interface ChatMessageCursor {
     uuid: string;
     createdAt: string;
@@ -385,13 +452,6 @@ interface State {
     dormant: DormantState;
 }
 
-interface GameSettings {
-    temperature: number;
-    replyLength: string;
-    replyLanguage: string;
-    playerNote: string;
-}
-
 declare class ChatModule {
     private http;
     private getGameId;
@@ -399,9 +459,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 触发） */
@@ -452,6 +511,21 @@ declare class ChatModule {
      * - 该消息本身不会被删除；它之后的所有消息会被删除
      */
     rollback(options: ChatRollbackOptions): Promise<ChatRollbackResponse>;
+    /**
+     * 查询当前会话（可按 topic）是否有正在进行的生成。
+     * 进入对话 / 刷新 / 换设备后先调它，命中再用 resume() 接管在途流。
+     * 预览模式无在途生成，恒返回 { active: false }。
+     */
+    active(options?: {
+        topic?: string;
+    }): Promise<ChatActiveResult>;
+    /**
+     * 接管会话/ topic 的在途生成并续读（刷新、换设备、多端接力时用）。
+     * - 生成跑在 chat-worker、产物在 Redis 流，与发起请求的连接解耦；从头实时接上正在输出的内容。
+     * - 续读中途再断会自动重连续读；服务端已无在途生成（已跑完）则静默返回。
+     * 预览模式无在途生成，直接返回。
+     */
+    resume(options?: ChatResumeOptions): Promise<void>;
     /** 预览模式：发到 /preview 端点
      *  - 创作台预览：父页面已注入 previewConfig，请求体塞 prompt_config，服务端不查库
      *  - 本地预览 / dev：无 previewConfig，请求体塞 game_id，服务端按 hash_id 查 prompts
@@ -691,10 +765,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;
@@ -716,18 +791,18 @@ 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 进来，
      * 否则 SDK 会一直用旧 token 请求被服务端 401。
      */
     private listenForTokenUpdate;
-    /**
-     * 用户在 SDK 内置选择器里切换模型时统一入口：
-     * 更新内部 modelId，并把选择回传给宿主（主站/App），实现双向同步与持久化。
-     * dev 模式没有 bus（无父页面），此时仅更新本地。
-     */
-    private handleLocalModelChange;
     /** 监听父页面发来的预览模式动态更新（envelope 'config-update' / 'set-model'） */
     private listenForPreviewMessages;
     /**
@@ -739,13 +814,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[]>;
 }
@@ -793,6 +863,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 {
@@ -943,4 +1019,4 @@ interface ToastAction {
  */
 declare function showToast(message: string, type?: ToastType, duration?: number, action?: ToastAction): void;
 
-export { type AISummary, type AckPayload, type AssetItem, type CharacterAddOptions, type CharacterDetail, type CharacterPersona, type CharacterUpdateOptions, type ChatGenerateOptions, type ChatMessage, type ChatMessageCursor, type ChatMessagesOptions, type ChatMessagesResponse, type ChatResponse, type ChatRetryOptions, type ChatSaveOptions, type ChatSendOptions, type ChatStateCallback, type ConfigUpdatePayload, type CurrentState, type DormantState, type DownstreamMsg, type FieldValue, type Gender, type InitPayload, type InventoryAddOptions, type InventoryMoveOptions, type InventoryRemoveGroupOptions, type InventoryRemoveOptions, type InventoryState, type InventoryUpdateOptions, type ItemData, type OrientationPayload, PROTOCOL_VERSION, type PlayerPersona, type PreviewConfig, type PreviewInitPayload, type ProtocolEnvelope, type ReadyPayload, type Relationship, type RichFieldValue, type SdkErrorPayload, type SetModelPayload, type State, type StateChanges, StorviaBus, type StorviaBusOptions, StorviaError, type StorviaErrorCode, StorviaSDK, type TokenUpdatePayload, type UpstreamMsg, createStorviaSDK, envelope, extractFieldValue, isProtocolEnvelope, isRichFieldValue, setToastEnabled, showToast };
+export { type AISummary, type AckPayload, type AssetItem, type CharacterAddOptions, type CharacterDetail, type CharacterPersona, type CharacterUpdateOptions, type ChatActiveResult, type ChatGenerateOptions, type ChatMessage, type ChatMessageCursor, type ChatMessagesOptions, type ChatMessagesResponse, type ChatReconnectingCallback, type ChatResponse, type ChatResumeOptions, type ChatRetryOptions, type ChatSaveOptions, type ChatSendOptions, type ChatStateCallback, type ConfigUpdatePayload, type CurrentState, type DormantState, type DownstreamMsg, type FieldValue, type Gender, type InitPayload, type InventoryAddOptions, type InventoryMoveOptions, type InventoryRemoveGroupOptions, type InventoryRemoveOptions, type InventoryState, type InventoryUpdateOptions, type ItemData, type OrientationPayload, PROTOCOL_VERSION, type PlayerPersona, type PreviewConfig, type PreviewInitPayload, type ProtocolEnvelope, type ReadyPayload, type Relationship, type RichFieldValue, type SdkErrorPayload, type SetModelPayload, type State, type StateChanges, StorviaBus, type StorviaBusOptions, StorviaError, type StorviaErrorCode, StorviaSDK, type TokenUpdatePayload, type UpstreamMsg, createStorviaSDK, envelope, extractFieldValue, isProtocolEnvelope, isRichFieldValue, setToastEnabled, showToast };