@storvia/sdk 0.10.7 → 0.10.9

package/dist/index.d.mts

@@ -57,12 +57,23 @@ interface WorldbookPatch {
 }
 interface AssetItem {
     id: number;
+    /** 素材 UUID，原数字 id 与图片 url 继续可用。 */
+    assetId: string;
     name: string;
+    nameI18n?: Record<string, string>;
     url: string;
     assetType: 'avatar' | 'icon';
     category: string;
+    /** 分类展示译名；分类筛选仍使用 category 原文。 */
+    categoryI18n?: Record<string, string> | null;
+    tags: AssetTag[];
 }
-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';
+interface AssetTag {
+    id: string;
+    label: string;
+    labelI18n?: Record<string, string> | null;
+}
+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' | 'ASR_BAD_AUDIO' | 'ASR_UPSTREAM_FAILED' | 'ASR_MODEL_UNAVAILABLE' | 'TTS_UNKNOWN_VOICE' | 'TTS_EMPTY_TEXT' | 'TTS_UPSTREAM_FAILED' | '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） */
@@ -420,12 +431,37 @@ declare function isRichFieldValue(v: unknown): v is RichFieldValue;
 /** 从 FieldValue 中提取原始值 */
 declare function extractFieldValue(v: FieldValue): string | number | boolean;
 type Gender = 'male' | 'female' | 'other';
+interface TtsSpeakOptions {
+    text: string;
+    character: string;
+}
+interface TtsAudio {
+    audio: Blob;
+    cached: boolean;
+}
+type AsrAudioFormat = 'wav' | 'mp3' | 'm4a' | 'webm' | 'ogg' | 'opus' | 'flac' | 'aac';
+interface AsrTranscribeOptions {
+    /** 文件或完整录音 Blob，最多 10MB；支持不超过 5 分钟的音频。 */
+    audio: Blob;
+    /** MIME 为空时显式指定文件格式。 */
+    format?: AsrAudioFormat;
+    /** 帮助识别专有名词的上下文，最多 400 字符。 */
+    context?: string;
+    /** 最多四个语言代码；留空自动识别。 */
+    languageHints?: string[];
+    /** 最多五十个专有名词，每项最多 64 字符。 */
+    hotwords?: string[];
+}
+interface AsrTranscription {
+    text: string;
+}
 interface CharacterPersona {
     name: string;
     avatar?: string;
     description?: string;
     introduction?: string;
     visibleAtStart?: boolean;
+    hasVoice?: boolean;
     userDescription?: string;
     gender?: Gender;
     isPreset?: boolean;
@@ -436,6 +472,7 @@ interface CharacterDetail {
     description?: string;
     introduction?: string;
     visibleAtStart?: boolean;
+    hasVoice?: boolean;
     userDescription?: string;
     gender?: Gender;
     isPreset?: boolean;
@@ -573,6 +610,10 @@ declare class HttpClient {
     private devApiKey;
     constructor(baseUrl: string, token: string, debug?: boolean, devApiKey?: string);
     setToken(token: string): void;
+    ttsClient(): HttpClient;
+    asrClient(): HttpClient;
+    postForm<T>(path: string, form: FormData, timeoutMs?: number): Promise<T>;
+    postAudio(path: string, body: unknown): Promise<Blob>;
     setDebug(enabled: boolean): void;
     private static readonly REQUEST_TIMEOUT;
     private static readonly INITIAL_TIMEOUT;
@@ -799,6 +840,8 @@ declare class CharactersModule {
     state: CharacterStateModule;
     private mem;
     constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialCharacters?: CharacterPersona[], initialStates?: Record<string, CharacterStateAttributes>);
+    /** 预览模式下当前角色名（关系模块判断别名是否被同名角色占用） */
+    previewNames(): string[];
     /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
     setInitial(initialCharacters: CharacterPersona[] | undefined, initialStates: Record<string, CharacterStateAttributes> | undefined): void;
     list(): Promise<CharacterPersona[]>;
@@ -831,10 +874,13 @@ declare class RelationshipsModule {
     private http;
     private getConversationId;
     private isPreview;
+    private getCharacterNames;
     private mem;
-    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialRelationships?: Relationship[]);
+    constructor(http: HttpClient, getConversationId: () => string, isPreview?: boolean, initialRelationships?: Relationship[], getCharacterNames?: () => string[]);
     /** 预览模式下重新灌入初始数据（previewConfig 变更时调用） */
     setInitial(initialRelationships: Relationship[] | undefined): void;
+    /** 玩家可传 "player" / "user" 等别名；线上由服务端归一，预览在内存里按同一规则归一 */
+    private entity;
     list(): Promise<Relationship[]>;
     get(from: string, to: string): Promise<Relationship>;
     add(relationship: Relationship): Promise<void>;
@@ -1321,10 +1367,29 @@ declare class HostModule {
     refreshMessages(): boolean;
 }
 
+/** 语音按需生成；studio/dev 预览也使用真实合成，按实际用量收费。 */
+declare class TtsModule {
+    private getHttp;
+    private getConversationId;
+    private getGameId;
+    private getVoice;
+    private isPreview;
+    private pending;
+    constructor(getHttp: () => HttpClient, getConversationId: () => string, getGameId: () => string, getVoice: (name: string) => Promise<string | undefined>, isPreview?: boolean);
+    speak(options: TtsSpeakOptions): Promise<TtsAudio>;
+}
+
+/** 上传录音识别为文本。与 TTS 一致，studio/dev 预览也使用真实识别并按用量收费。 */
+declare class AsrModule {
+    private getHttp;
+    constructor(getHttp: () => HttpClient);
+    transcribe(options: AsrTranscribeOptions): Promise<AsrTranscription>;
+}
+
 interface DevConfig {
     apiKey: string;
     gameId: string;
-    /** 本地预览/dev：指定初始模型的展示名（display name）。不传则用第一个可用模型。 */
+    /** 本地预览/dev：指定初始模型的展示名，任一语言都行（如 "DeepSeek V4 Flash · Direct"）。不传或匹配不到则用第一个可用模型。 */
     model?: string;
     /** 本地预览/dev：指定生效的预设 id。不传则由服务端回退到该模型的第一个预设。 */
     preset?: string;
@@ -1342,6 +1407,7 @@ declare class StorviaSDK {
     private initialized;
     private isPreview;
     private previewConfig;
+    private previewVoices;
     private bus;
     chat: ChatModule;
     characters: CharactersModule;
@@ -1354,6 +1420,8 @@ declare class StorviaSDK {
     state: StateModule;
     memory: MemoryModule;
     host: HostModule;
+    tts: TtsModule;
+    asr: AsrModule;
     init(): Promise<void>;
     /**
      * 监听宿主运行时下发的模型切换（envelope 'set-model'）。
@@ -1369,11 +1437,12 @@ declare class StorviaSDK {
     private listenForTokenUpdate;
     /** 监听父页面发来的预览模式动态更新（envelope 'config-update' / 'set-model'） */
     private listenForPreviewMessages;
+    private getCharacterVoice;
     /**
      * 调用 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 后同步） */
@@ -1415,4 +1484,10 @@ 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 ExtendWorldRuleEntry, type FieldValue, type Gender, HOST_NOTIFY_MAX_LENGTH, HOST_NOTIFY_MIN_INTERVAL_MS, HOST_PANEL_SCOPES, HOST_REFRESH_MIN_INTERVAL_MS, type HostMessagesChangedPayload, HostModule, type HostNotifyPayload, type HostPanelScope, type HostStateChangedPayload, type InitPayload, type InventoryAddOptions, type InventoryMoveOptions, type InventoryRemoveGroupOptions, type InventoryRemoveOptions, type InventoryState, type InventoryUpdateOptions, type ItemData, MAIN_CHAT_TOPIC, type OrientationPayload, PROTOCOL_VERSION, type PlayerPersona, type PresetWorldbookView, 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, type Worldbook, type WorldbookPatch, createStorviaSDK, envelope, extractFieldValue, isProtocolEnvelope, isRichFieldValue, setToastEnabled, showToast };
+/**
+ * 关系 from / to 里代表玩家本人的固定 id。与服务端 `_shared/game-state/constants.ts` 的 PLAYER_ENTITY_ID 同值。
+ * 写代码时用这个常量比较（`r.from === PLAYER_ID`），不要手写字面量。
+ */
+declare const PLAYER_ID = "\u73A9\u5BB6";
+
+export { type AISummary, type AckPayload, type AsrAudioFormat, type AsrTranscribeOptions, type AsrTranscription, type AssetItem, type AssetTag, 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 ExtendWorldRuleEntry, type FieldValue, type Gender, HOST_NOTIFY_MAX_LENGTH, HOST_NOTIFY_MIN_INTERVAL_MS, HOST_PANEL_SCOPES, HOST_REFRESH_MIN_INTERVAL_MS, type HostMessagesChangedPayload, HostModule, type HostNotifyPayload, type HostPanelScope, type HostStateChangedPayload, type InitPayload, type InventoryAddOptions, type InventoryMoveOptions, type InventoryRemoveGroupOptions, type InventoryRemoveOptions, type InventoryState, type InventoryUpdateOptions, type ItemData, MAIN_CHAT_TOPIC, type OrientationPayload, PLAYER_ID, PROTOCOL_VERSION, type PlayerPersona, type PresetWorldbookView, 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 TtsAudio, type TtsSpeakOptions, type UpstreamMsg, type Worldbook, type WorldbookPatch, createStorviaSDK, envelope, extractFieldValue, isProtocolEnvelope, isRichFieldValue, setToastEnabled, showToast };