@storvia/sdk 0.9.7 → 0.9.9

package/dist/index.d.mts

@@ -11,7 +11,7 @@ interface AssetItem {
     assetType: 'avatar' | 'icon';
     category: string;
 }
-type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'VIOLATION_WORD_DETECTED' | 'CONTENT_FILTERED' | 'MODEL_REFUSAL' | 'STREAM_INTERRUPTED' | 'RATE_LIMITED' | 'GENERATING_IN_PROGRESS' | 'CONCURRENT_GENERATION_LIMIT' | 'INVENTORY_LIMIT' | 'CUSTOM_FIELDS_LIMIT' | 'MODEL_NOT_FOUND' | 'GAME_NOT_FOUND' | 'INVALID_REQUEST' | 'INVALID_EXTRACT_RULE' | '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' | 'GENERATION_LOST' | 'REPETITION_LOOP' | 'SAVE_FAILED' | 'FINALIZE_FAILED' | 'CONVERSATION_NOT_FOUND' | 'EMPTY_MESSAGE' | 'CONTINUE_MODEL_NOT_AVAILABLE' | 'CONTINUE_PROMPT_MISSING' | 'GENERATION_ABORTED';
+type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'VIOLATION_WORD_DETECTED' | 'CONTENT_FILTERED' | 'MODEL_REFUSAL' | 'STREAM_INTERRUPTED' | 'RATE_LIMITED' | 'GENERATING_IN_PROGRESS' | 'CONCURRENT_GENERATION_LIMIT' | 'INVENTORY_LIMIT' | 'CUSTOM_FIELDS_LIMIT' | 'MODEL_NOT_FOUND' | 'GAME_NOT_FOUND' | 'INVALID_REQUEST' | 'INVALID_EXTRACT_RULE' | 'INTERNAL_ERROR' | 'NOT_INITIALIZED' | 'NOT_SUPPORTED_IN_PREVIEW' | 'NETWORK_ERROR' | 'REQUEST_TIMEOUT' | 'MODEL_LOADING_TIMEOUT' | 'DAISY_CARD_REQUIRED' | 'MESSAGE_NOT_FOUND' | 'MESSAGE_TOO_OLD' | 'NO_MESSAGES_TO_DELETE' | 'GENERATION_TIMEOUT' | 'GENERATION_LOST' | 'REPETITION_LOOP' | 'SAVE_FAILED' | 'FINALIZE_FAILED' | 'CONVERSATION_NOT_FOUND' | 'EMPTY_MESSAGE' | 'CONTINUE_MODEL_NOT_AVAILABLE' | 'CONTINUE_PROMPT_MISSING' | 'GENERATION_ABORTED';
 /** AI 本轮的属性变更（仅包含发生改变的字段） */
 interface StateChanges {
     /** 世界状态变更（扁平 KV） */
@@ -504,8 +504,8 @@ declare class HttpClient {
     setToken(token: string): void;
     setDebug(enabled: boolean): void;
     private static readonly REQUEST_TIMEOUT;
-    private static readonly MODEL_LOADING_TIMEOUT;
-    private static readonly STREAM_INACTIVITY_TIMEOUT;
+    private static readonly INITIAL_TIMEOUT;
+    private static readonly RESUME_STALL_TIMEOUT;
     /** 非 StorviaError（通常是 fetch 网络层抛错）统一弹 NETWORK_ERROR toast */
     private maybeShowNetworkToast;
     /** 将 AbortError 转换为 StorviaError('REQUEST_TIMEOUT') */
@@ -688,6 +688,13 @@ declare class CharacterStateModule {
      * 系统自动保留字段元数据（type/min/max）并做范围钳位。
      */
     update(name: string, group: string, values: Record<string, string | number | boolean>): Promise<void>;
+    /**
+     * 删除该角色指定分组下的字段。传空数组直接返回，不发请求。
+     * 删到分组为空时分组本身仍保留（要连分组一起删用 [removeGroup]）。
+     */
+    remove(name: string, group: string, keys: string[]): Promise<void>;
+    /** 删除该角色的整个属性分组（连同组内所有字段）。分组不存在时是 no-op。 */
+    removeGroup(name: string, group: string): Promise<void>;
 }
 declare class CharactersModule {
     private http;
@@ -795,6 +802,13 @@ declare class PlayerStateModule {
     get(): Promise<Record<string, Record<string, FieldValue>>>;
     get(group: string): Promise<Record<string, FieldValue>>;
     update(group: string, values: Record<string, string | number | boolean>): Promise<void>;
+    /**
+     * 删除指定分组下的字段。传空数组直接返回，不发请求。
+     * 删到分组为空时分组本身仍保留（要连分组一起删用 [removeGroup]）。
+     */
+    remove(group: string, keys: string[]): Promise<void>;
+    /** 删除整个分组（连同组内所有字段）。分组不存在时是 no-op。 */
+    removeGroup(group: string): Promise<void>;
 }
 declare class PlayerModule {
     private http;
@@ -904,80 +918,6 @@ declare class MemoryModule {
     update(content: string): Promise<AISummary>;
 }
 
-interface DevConfig {
-    apiKey: string;
-    gameId: string;
-    /** 本地预览/dev：指定初始模型的展示名（display name）。不传则用第一个可用模型。 */
-    model?: string;
-}
-declare class StorviaSDK {
-    private http;
-    private baseUrl;
-    private gameId;
-    private conversationId;
-    private modelId;
-    private models;
-    /** 预设 id（per-model）；由宿主经 init / 'set-preset' 下发，每次生成请求自动带上 preset */
-    private presetId;
-    private accessToken;
-    private initialized;
-    private isPreview;
-    private previewConfig;
-    private bus;
-    chat: ChatModule;
-    characters: CharactersModule;
-    relationships: RelationshipsModule;
-    inventory: InventoryModule;
-    world: WorldModule;
-    player: PlayerModule;
-    custom: CustomModule;
-    save: SaveModule;
-    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;
-    /** 监听父页面发来的预览模式动态更新（envelope 'config-update' / 'set-model'） */
-    private listenForPreviewMessages;
-    /**
-     * 调用 POST /preview/initial-snapshot 拉取与正式发布等价的初始数据
-     * - 预览模式：传 game_config + game_state_override（来自 previewConfig）
-     * - dev 模式：HttpClient 自动带 x-api-key，后端按 game_id 反查
-     * 失败时返回 null（不阻塞 init，list/get 仍能用空 mem 工作）
-     */
-    private fetchPreviewSnapshot;
-    /** 重新拉 snapshot 并把结果灌进每个 module 的 mem（用于 update-config 后同步） */
-    private refreshPreviewSnapshot;
-    private fetchModels;
-    private authenticate;
-    initDev(devConfig: DevConfig): Promise<void>;
-    getAssets(type: 'avatar' | 'icon', category?: string): Promise<AssetItem[]>;
-}
-declare function createStorviaSDK(options?: {
-    dev?: DevConfig;
-}): Promise<StorviaSDK>;
-
-declare class StorviaError extends Error {
-    code: StorviaErrorCode;
-    /**
-     * 命中的违禁词列表，仅 `code === 'VIOLATION_WORD_DETECTED'` 时有值。
-     * 服务端以 `matched_words` 下发，SDK 转成 camelCase 挂在这里，
-     * 供游戏侧在自己的 UI 里高亮 / 提示具体是哪几个词。
-     */
-    matchedWords?: string[];
-    constructor(code: StorviaErrorCode, message: string, matchedWords?: string[]);
-}
-
 /**
  * 父子 iframe postMessage 协议类型
  *
@@ -1096,12 +1036,34 @@ interface NavigatePayload {
     target: 'wallet';
     reason?: 'insufficient_credits' | 'daisy_card_required';
 }
+/** 面板 tab 维度，供小组件声明这次改了哪块（宿主据此亮 badge） */
+declare const HOST_PANEL_SCOPES: readonly ["player", "characters", "inventory", "relations", "world"];
+type HostPanelScope = (typeof HOST_PANEL_SCOPES)[number];
+/**
+ * 子 → 父：请求宿主在主线（聊天页）弹一条 toast。
+ *
+ * 只在小组件**后台运行**时展示 —— 前台时玩家就在小组件里看着，不必再打断。
+ * 宿主把 text 当纯文本渲染（不解析 markdown / HTML）、截断、按小组件维度节流。
+ *
+ * 刻意不带 level / 图标：这是「消息通知」不是「结果通知」，成功✓失败✗的语义
+ * 对「你的信件已送达」这类内容是误导。要视觉区分就在文本里放 emoji。
+ */
+interface HostNotifyPayload {
+    text: string;
+}
+/**
+ * 子 → 父：小组件改过主线状态，请求宿主重拉 game_state 刷新聊天页面板。
+ * scope 只用于亮对应 tab 的 badge，宿主恒全量重拉。
+ */
+interface HostStateChangedPayload {
+    scope?: HostPanelScope[];
+}
 interface AckPayload {
     ok: boolean;
     error?: string;
 }
 type DownstreamMsg = ProtocolEnvelope<'init', InitPayload> | ProtocolEnvelope<'preview-init', PreviewInitPayload> | ProtocolEnvelope<'token-update', TokenUpdatePayload> | ProtocolEnvelope<'config-update', ConfigUpdatePayload> | ProtocolEnvelope<'set-model', SetModelPayload> | ProtocolEnvelope<'set-preset', SetPresetPayload> | 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<'model-change', SetModelPayload> | 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<'host-notify', HostNotifyPayload> | ProtocolEnvelope<'host-state-changed', HostStateChangedPayload> | 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;
@@ -1175,6 +1137,140 @@ declare class StorviaBus<TIn extends AnyEnvelope, TOut extends AnyEnvelope> {
     destroy(): void;
 }
 
+/**
+ * 小组件 → 主线（宿主聊天页）的联动通道。
+ *
+ * 两个能力都只发 postMessage 信号，不打后端：
+ * - [notify]        主线弹一条 toast（仅小组件**后台运行**时展示，前台时宿主静默丢弃）
+ * - [refreshPanel]  主线重拉 game_state 刷新游戏面板
+ *
+ * 面板能刷出内容的前提：小组件与主线**共享** player / characters / inventory /
+ * relationships / world 这几块状态（`sdk.player` / `sdk.characters` / `sdk.inventory` /
+ * `sdk.relationships` / `sdk.world` 写的就是主线那一份），所以先写再 refreshPanel 即可。
+ * `sdk.custom` / `sdk.save` 是小组件自己的沙盒，**不会**出现在主线面板上。
+ */
+/**
+ * toast 文本上限，超出截断。
+ * ⚠️ 三端对齐：Storvia `src/constants/limits.ts` 的 WIDGET_HOST_NOTIFY_MAX_LENGTH、
+ * App `lib/core/constants/app_limits.dart` 的 widgetHostNotifyMaxLength 须同值。
+ */
+declare const HOST_NOTIFY_MAX_LENGTH = 60;
+/**
+ * 两次 toast / 两次面板刷新的最小间隔。
+ * 这里只是第一道（省一次 postMessage），宿主侧还会独立再拦一道 —— 作者能绕过 SDK
+ * 直接 postMessage，节流的权威判定必须在宿主。
+ *
+ * 两个值差两个数量级是因为代价不同：notify 纯前端（发一条消息、宿主渲染一条 toast，
+ * toast 在宿主侧纵向堆叠不会互相覆盖），卡 1s 只为防刷屏；refreshPanel 每次都会让
+ * 宿主重拉一次会话详情，是真实后端请求，必须卡住。
+ */
+declare const HOST_NOTIFY_MIN_INTERVAL_MS = 1000;
+declare const HOST_REFRESH_MIN_INTERVAL_MS = 10000;
+declare class HostModule {
+    private send;
+    private isPreview;
+    /** 注入时间源，便于测试；生产恒 Date.now */
+    private now;
+    private lastNotifyAt;
+    private lastRefreshAt;
+    constructor(send: (msg: UpstreamMsg) => void, isPreview?: boolean, 
+    /** 注入时间源，便于测试；生产恒 Date.now */
+    now?: () => number);
+    /**
+     * 给主线聊天页发一条 toast。
+     *
+     * 返回是否真的发出去了：文本为空、或距上次不足 [HOST_NOTIFY_MIN_INTERVAL_MS] 时返回 false。
+     * 预览模式下没有主线可通知，降级为在小组件内部弹一条 SDK 自带 toast，方便作者调效果。
+     *
+     * 宿主渲染成不带状态图标的纯文本 toast —— 这是消息通知不是结果通知。
+     * 想强调语气就在文本里放 emoji（`sdk.host.notify('📮 你的信件已送达')`）。
+     */
+    notify(text: string): boolean;
+    /**
+     * 请求主线重拉 game_state 刷新面板（写完状态后调）。
+     *
+     * `scope` 声明这次改了哪几块，宿主据此亮对应 tab 的 badge；不传就只刷新不亮 badge。
+     * 返回是否真的发出去了：距上次不足 [HOST_REFRESH_MIN_INTERVAL_MS] 时返回 false。
+     * 预览模式下主线面板不存在，直接 no-op 返回 false。
+     */
+    refreshPanel(scope?: HostPanelScope[]): boolean;
+}
+
+interface DevConfig {
+    apiKey: string;
+    gameId: string;
+    /** 本地预览/dev：指定初始模型的展示名（display name）。不传则用第一个可用模型。 */
+    model?: string;
+}
+declare class StorviaSDK {
+    private http;
+    private baseUrl;
+    private gameId;
+    private conversationId;
+    private modelId;
+    private models;
+    /** 预设 id（per-model）；由宿主经 init / 'set-preset' 下发，每次生成请求自动带上 preset */
+    private presetId;
+    private accessToken;
+    private initialized;
+    private isPreview;
+    private previewConfig;
+    private bus;
+    chat: ChatModule;
+    characters: CharactersModule;
+    relationships: RelationshipsModule;
+    inventory: InventoryModule;
+    world: WorldModule;
+    player: PlayerModule;
+    custom: CustomModule;
+    save: SaveModule;
+    state: StateModule;
+    memory: MemoryModule;
+    host: HostModule;
+    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;
+    /** 监听父页面发来的预览模式动态更新（envelope 'config-update' / 'set-model'） */
+    private listenForPreviewMessages;
+    /**
+     * 调用 POST /preview/initial-snapshot 拉取与正式发布等价的初始数据
+     * - 预览模式：传 game_config + game_state_override（来自 previewConfig）
+     * - dev 模式：HttpClient 自动带 x-api-key，后端按 game_id 反查
+     * 失败时返回 null（不阻塞 init，list/get 仍能用空 mem 工作）
+     */
+    private fetchPreviewSnapshot;
+    /** 重新拉 snapshot 并把结果灌进每个 module 的 mem（用于 update-config 后同步） */
+    private refreshPreviewSnapshot;
+    private fetchModels;
+    private authenticate;
+    initDev(devConfig: DevConfig): Promise<void>;
+    getAssets(type: 'avatar' | 'icon', category?: string): Promise<AssetItem[]>;
+}
+declare function createStorviaSDK(options?: {
+    dev?: DevConfig;
+}): Promise<StorviaSDK>;
+
+declare class StorviaError extends Error {
+    code: StorviaErrorCode;
+    /**
+     * 命中的违禁词列表，仅 `code === 'VIOLATION_WORD_DETECTED'` 时有值。
+     * 服务端以 `matched_words` 下发，SDK 转成 camelCase 挂在这里，
+     * 供游戏侧在自己的 UI 里高亮 / 提示具体是哪几个词。
+     */
+    matchedWords?: string[];
+    constructor(code: StorviaErrorCode, message: string, matchedWords?: string[]);
+}
+
 /**
  * SDK 内置 Toast：参考主站 Toast.vue 样式
  * 用于在 HTTP 层捕获错误后自动提示用户
@@ -1193,4 +1289,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 ChatAbortInfo, type ChatAbortedCallback, type ChatCancelOptions, type ChatCancelResult, type ChatContinueOptions, type ChatDoneCallback, type ChatDoneInfo, 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 };
+export { type AISummary, type AckPayload, type AssetItem, type CharacterAddOptions, type CharacterDetail, type CharacterPersona, type CharacterUpdateOptions, type ChatAbortInfo, type ChatAbortedCallback, type ChatCancelOptions, type ChatCancelResult, type ChatContinueOptions, type ChatDoneCallback, type ChatDoneInfo, 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, HOST_NOTIFY_MAX_LENGTH, HOST_NOTIFY_MIN_INTERVAL_MS, HOST_PANEL_SCOPES, HOST_REFRESH_MIN_INTERVAL_MS, HostModule, type HostNotifyPayload, type HostPanelScope, type HostStateChangedPayload, 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 };