@storvia/sdk 0.9.6 → 0.9.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs.js +8 -125
- package/dist/index.d.mts +208 -77
- package/dist/index.esm.js +8 -125
- package/dist/index.umd.js +8 -125
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -11,7 +11,7 @@ interface AssetItem {
|
|
|
11
11
|
assetType: 'avatar' | 'icon';
|
|
12
12
|
category: string;
|
|
13
13
|
}
|
|
14
|
-
type StorviaErrorCode = 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'VIOLATION_WORD_DETECTED' | 'CONTENT_FILTERED' | 'MODEL_REFUSAL' | 'STREAM_INTERRUPTED' | 'RATE_LIMITED' | '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';
|
|
14
|
+
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';
|
|
15
15
|
/** AI 本轮的属性变更(仅包含发生改变的字段) */
|
|
16
16
|
interface StateChanges {
|
|
17
17
|
/** 世界状态变更(扁平 KV) */
|
|
@@ -105,7 +105,11 @@ type ChatAbortedCallback = (info: ChatAbortInfo) => void;
|
|
|
105
105
|
* 流式 + 入库内容过滤规则。提供后,服务端只保留 AI 回复中
|
|
106
106
|
* `start..end` 之间的内容(多段会自动拼接),其余被丢弃。
|
|
107
107
|
*
|
|
108
|
-
*
|
|
108
|
+
* ⚠️ **起止标记本身会被保留**,方便用正则精确解析:AI 输出 `想想...<reply>你好</reply>`
|
|
109
|
+
* 时,推送与入库都是 `<reply>你好</reply>`,而不是 `你好`。
|
|
110
|
+
*
|
|
111
|
+
* - 命中过任何 `start` → 推送 / 入库 = 提取拼接结果(含各段的起止标记)
|
|
112
|
+
* - 未闭合 `end` → 推送 / 入库 = `start` + 已生成部分(只有起始标记)
|
|
109
113
|
* - 完全没匹配到 → 兜底为原始干净文本(不至于得到空消息),便于排查 AI 是否按格式输出
|
|
110
114
|
*
|
|
111
115
|
* 适用场景:作者要求 AI 用 `<reply>...</reply>` 等标记包裹给玩家看的内容,
|
|
@@ -121,7 +125,7 @@ interface ChatSendOptions {
|
|
|
121
125
|
message: string;
|
|
122
126
|
topic?: string;
|
|
123
127
|
sceneKey?: string;
|
|
124
|
-
/** 内容过滤规则;流式与入库都只保留 start..end
|
|
128
|
+
/** 内容过滤规则;流式与入库都只保留 start..end 范围内的内容(**起止标记本身一并保留**,便于正则解析) */
|
|
125
129
|
extract?: ChatExtractRule;
|
|
126
130
|
stream?: boolean;
|
|
127
131
|
onChunk?: (text: string) => void;
|
|
@@ -145,7 +149,7 @@ interface ChatSaveOptions {
|
|
|
145
149
|
interface ChatGenerateOptions {
|
|
146
150
|
topic?: string;
|
|
147
151
|
sceneKey?: string;
|
|
148
|
-
/** 内容过滤规则;流式与入库都只保留 start..end
|
|
152
|
+
/** 内容过滤规则;流式与入库都只保留 start..end 范围内的内容(**起止标记本身一并保留**,便于正则解析) */
|
|
149
153
|
extract?: ChatExtractRule;
|
|
150
154
|
stream?: boolean;
|
|
151
155
|
onChunk?: (text: string) => void;
|
|
@@ -164,7 +168,7 @@ interface ChatGenerateOptions {
|
|
|
164
168
|
interface ChatRetryOptions {
|
|
165
169
|
topic?: string;
|
|
166
170
|
sceneKey?: string;
|
|
167
|
-
/** 内容过滤规则;流式与入库都只保留 start..end
|
|
171
|
+
/** 内容过滤规则;流式与入库都只保留 start..end 范围内的内容(**起止标记本身一并保留**,便于正则解析) */
|
|
168
172
|
extract?: ChatExtractRule;
|
|
169
173
|
stream?: boolean;
|
|
170
174
|
onChunk?: (text: string) => void;
|
|
@@ -220,7 +224,8 @@ interface ChatContinueOptions {
|
|
|
220
224
|
*/
|
|
221
225
|
sceneKey?: string;
|
|
222
226
|
/**
|
|
223
|
-
* 内容过滤规则;与 send/generate/retry 的 extract 语义一致,流式与入库都只保留 start..end
|
|
227
|
+
* 内容过滤规则;与 send/generate/retry 的 extract 语义一致,流式与入库都只保留 start..end 范围
|
|
228
|
+
* (起止标记本身一并保留)。
|
|
224
229
|
* 若被续写的消息是 extract 模式生成的,**必须传入原样的规则**,否则续写内容不会被抽取(标记外的
|
|
225
230
|
* 思考/旁白会流给玩家并入库)。续写是纯追加:已存内容不会被改写,只在其后接上新抽取的可见内容。
|
|
226
231
|
*/
|
|
@@ -683,6 +688,13 @@ declare class CharacterStateModule {
|
|
|
683
688
|
* 系统自动保留字段元数据(type/min/max)并做范围钳位。
|
|
684
689
|
*/
|
|
685
690
|
update(name: string, group: string, values: Record<string, string | number | boolean>): Promise<void>;
|
|
691
|
+
/**
|
|
692
|
+
* 删除该角色指定分组下的字段。传空数组直接返回,不发请求。
|
|
693
|
+
* 删到分组为空时分组本身仍保留(要连分组一起删用 [removeGroup])。
|
|
694
|
+
*/
|
|
695
|
+
remove(name: string, group: string, keys: string[]): Promise<void>;
|
|
696
|
+
/** 删除该角色的整个属性分组(连同组内所有字段)。分组不存在时是 no-op。 */
|
|
697
|
+
removeGroup(name: string, group: string): Promise<void>;
|
|
686
698
|
}
|
|
687
699
|
declare class CharactersModule {
|
|
688
700
|
private http;
|
|
@@ -698,10 +710,22 @@ declare class CharactersModule {
|
|
|
698
710
|
add(character: CharacterAddOptions): Promise<void>;
|
|
699
711
|
update(name: string, data: CharacterUpdateOptions): Promise<void>;
|
|
700
712
|
remove(name: string): Promise<void>;
|
|
713
|
+
/**
|
|
714
|
+
* 把 `source` 合并进已有角色 `target`,用于 AI 把同一个人写成两个名字的去重。
|
|
715
|
+
*
|
|
716
|
+
* 服务端做四件事:source 的属性并入 target、source 名字记进 target 的别名
|
|
717
|
+
* (以后 AI 再用旧名也能认回来)、关系边 source→target 重指并去重、删除 source。
|
|
718
|
+
*
|
|
719
|
+
* 约束:
|
|
720
|
+
* - 预设角色**不可作为 source 被合并掉**(作者资产),服务端返回 `PRESET_CHARACTER_LOCKED`
|
|
721
|
+
* - `target` 必须已存在(活跃或休眠都行),否则 404
|
|
722
|
+
* - 不能合并到自身
|
|
723
|
+
*/
|
|
724
|
+
merge(source: string, target: string): Promise<void>;
|
|
701
725
|
detail(name: string): Promise<CharacterDetail>;
|
|
702
726
|
/**
|
|
703
727
|
* 调整 NPC 的重要程度(0-100,越高越不容易被挤出场景)。
|
|
704
|
-
* 预设 NPC
|
|
728
|
+
* 预设 NPC 同样可改——服务端只对 remove / merge 上锁,priority 不锁。
|
|
705
729
|
* 超出范围会自动钳位到 0 或 100。
|
|
706
730
|
*/
|
|
707
731
|
setPriority(name: string, value: number): Promise<void>;
|
|
@@ -778,6 +802,13 @@ declare class PlayerStateModule {
|
|
|
778
802
|
get(): Promise<Record<string, Record<string, FieldValue>>>;
|
|
779
803
|
get(group: string): Promise<Record<string, FieldValue>>;
|
|
780
804
|
update(group: string, values: Record<string, string | number | boolean>): Promise<void>;
|
|
805
|
+
/**
|
|
806
|
+
* 删除指定分组下的字段。传空数组直接返回,不发请求。
|
|
807
|
+
* 删到分组为空时分组本身仍保留(要连分组一起删用 [removeGroup])。
|
|
808
|
+
*/
|
|
809
|
+
remove(group: string, keys: string[]): Promise<void>;
|
|
810
|
+
/** 删除整个分组(连同组内所有字段)。分组不存在时是 no-op。 */
|
|
811
|
+
removeGroup(group: string): Promise<void>;
|
|
781
812
|
}
|
|
782
813
|
declare class PlayerModule {
|
|
783
814
|
private http;
|
|
@@ -887,74 +918,6 @@ declare class MemoryModule {
|
|
|
887
918
|
update(content: string): Promise<AISummary>;
|
|
888
919
|
}
|
|
889
920
|
|
|
890
|
-
interface DevConfig {
|
|
891
|
-
apiKey: string;
|
|
892
|
-
gameId: string;
|
|
893
|
-
/** 本地预览/dev:指定初始模型的展示名(display name)。不传则用第一个可用模型。 */
|
|
894
|
-
model?: string;
|
|
895
|
-
}
|
|
896
|
-
declare class StorviaSDK {
|
|
897
|
-
private http;
|
|
898
|
-
private baseUrl;
|
|
899
|
-
private gameId;
|
|
900
|
-
private conversationId;
|
|
901
|
-
private modelId;
|
|
902
|
-
private models;
|
|
903
|
-
/** 预设 id(per-model);由宿主经 init / 'set-preset' 下发,每次生成请求自动带上 preset */
|
|
904
|
-
private presetId;
|
|
905
|
-
private accessToken;
|
|
906
|
-
private initialized;
|
|
907
|
-
private isPreview;
|
|
908
|
-
private previewConfig;
|
|
909
|
-
private bus;
|
|
910
|
-
chat: ChatModule;
|
|
911
|
-
characters: CharactersModule;
|
|
912
|
-
relationships: RelationshipsModule;
|
|
913
|
-
inventory: InventoryModule;
|
|
914
|
-
world: WorldModule;
|
|
915
|
-
player: PlayerModule;
|
|
916
|
-
custom: CustomModule;
|
|
917
|
-
save: SaveModule;
|
|
918
|
-
state: StateModule;
|
|
919
|
-
memory: MemoryModule;
|
|
920
|
-
init(): Promise<void>;
|
|
921
|
-
/**
|
|
922
|
-
* 监听宿主运行时下发的模型切换(envelope 'set-model')。
|
|
923
|
-
* 正式模式用:宿主已接管模型选择,用户在宿主 FAB 改模型时实时同步到 SDK。
|
|
924
|
-
* (预览模式的 set-model 在 listenForPreviewMessages 内单独处理。)
|
|
925
|
-
*/
|
|
926
|
-
private listenForModelChange;
|
|
927
|
-
/**
|
|
928
|
-
* 监听父页面 token 刷新(envelope 'token-update')。
|
|
929
|
-
* Supabase JWT 默认 1h 过期,父页面 session 自动刷新后转发新 token 进来,
|
|
930
|
-
* 否则 SDK 会一直用旧 token 请求被服务端 401。
|
|
931
|
-
*/
|
|
932
|
-
private listenForTokenUpdate;
|
|
933
|
-
/** 监听父页面发来的预览模式动态更新(envelope 'config-update' / 'set-model') */
|
|
934
|
-
private listenForPreviewMessages;
|
|
935
|
-
/**
|
|
936
|
-
* 调用 POST /preview/initial-snapshot 拉取与正式发布等价的初始数据
|
|
937
|
-
* - 预览模式:传 game_config + game_state_override(来自 previewConfig)
|
|
938
|
-
* - dev 模式:HttpClient 自动带 x-api-key,后端按 game_id 反查
|
|
939
|
-
* 失败时返回 null(不阻塞 init,list/get 仍能用空 mem 工作)
|
|
940
|
-
*/
|
|
941
|
-
private fetchPreviewSnapshot;
|
|
942
|
-
/** 重新拉 snapshot 并把结果灌进每个 module 的 mem(用于 update-config 后同步) */
|
|
943
|
-
private refreshPreviewSnapshot;
|
|
944
|
-
private fetchModels;
|
|
945
|
-
private authenticate;
|
|
946
|
-
initDev(devConfig: DevConfig): Promise<void>;
|
|
947
|
-
getAssets(type: 'avatar' | 'icon', category?: string): Promise<AssetItem[]>;
|
|
948
|
-
}
|
|
949
|
-
declare function createStorviaSDK(options?: {
|
|
950
|
-
dev?: DevConfig;
|
|
951
|
-
}): Promise<StorviaSDK>;
|
|
952
|
-
|
|
953
|
-
declare class StorviaError extends Error {
|
|
954
|
-
code: StorviaErrorCode;
|
|
955
|
-
constructor(code: StorviaErrorCode, message: string);
|
|
956
|
-
}
|
|
957
|
-
|
|
958
921
|
/**
|
|
959
922
|
* 父子 iframe postMessage 协议类型
|
|
960
923
|
*
|
|
@@ -1003,6 +966,11 @@ interface InitPayload {
|
|
|
1003
966
|
* metadata.presets + isUnrestricted 兜底。
|
|
1004
967
|
*/
|
|
1005
968
|
presetId?: string;
|
|
969
|
+
/**
|
|
970
|
+
* 宿主当前界面语言('zh' / 'zh-Hant' / 'en' / 'ja' / 'ko')。
|
|
971
|
+
* SDK 内置错误 toast 据此选文案;不下发时 SDK 退回 navigator.language,再兜到 zh。
|
|
972
|
+
*/
|
|
973
|
+
lang?: string;
|
|
1006
974
|
debug?: boolean;
|
|
1007
975
|
}
|
|
1008
976
|
interface PreviewConfig {
|
|
@@ -1028,6 +996,8 @@ interface PreviewInitPayload {
|
|
|
1028
996
|
selectedModelId?: string;
|
|
1029
997
|
/** 预览模式下宿主当前选中的预设 id 初始值;运行时切换走 'set-preset' */
|
|
1030
998
|
presetId?: string;
|
|
999
|
+
/** 宿主当前界面语言;SDK 内置错误 toast 据此选文案 */
|
|
1000
|
+
lang?: string;
|
|
1031
1001
|
debug?: boolean;
|
|
1032
1002
|
}
|
|
1033
1003
|
interface TokenUpdatePayload {
|
|
@@ -1057,16 +1027,43 @@ interface SdkErrorPayload {
|
|
|
1057
1027
|
/**
|
|
1058
1028
|
* 子 → 父:请求宿主跳转。当前仅支持 'wallet'(充值/钱包页),
|
|
1059
1029
|
* Web 主站 router.push('/wallet'),App 端跳 App 内钱包路由。
|
|
1030
|
+
*
|
|
1031
|
+
* `reason` 说明这次是被什么挡住的,宿主据此决定用哪种引导——SDK 自 0.9.7 起不再
|
|
1032
|
+
* 自绘「余额不足 / 需要雏菊卡」弹窗(平台级引导应由宿主用自己的组件 + i18n 出)。
|
|
1033
|
+
* 不带 reason 时宿主按原行为直接跳钱包页,所以老宿主收到新 SDK 的消息也不会失效。
|
|
1060
1034
|
*/
|
|
1061
1035
|
interface NavigatePayload {
|
|
1062
1036
|
target: 'wallet';
|
|
1037
|
+
reason?: 'insufficient_credits' | 'daisy_card_required';
|
|
1038
|
+
}
|
|
1039
|
+
/** 面板 tab 维度,供小组件声明这次改了哪块(宿主据此亮 badge) */
|
|
1040
|
+
declare const HOST_PANEL_SCOPES: readonly ["player", "characters", "inventory", "relations", "world"];
|
|
1041
|
+
type HostPanelScope = (typeof HOST_PANEL_SCOPES)[number];
|
|
1042
|
+
/**
|
|
1043
|
+
* 子 → 父:请求宿主在主线(聊天页)弹一条 toast。
|
|
1044
|
+
*
|
|
1045
|
+
* 只在小组件**后台运行**时展示 —— 前台时玩家就在小组件里看着,不必再打断。
|
|
1046
|
+
* 宿主把 text 当纯文本渲染(不解析 markdown / HTML)、截断、按小组件维度节流。
|
|
1047
|
+
*
|
|
1048
|
+
* 刻意不带 level / 图标:这是「消息通知」不是「结果通知」,成功✓失败✗的语义
|
|
1049
|
+
* 对「你的信件已送达」这类内容是误导。要视觉区分就在文本里放 emoji。
|
|
1050
|
+
*/
|
|
1051
|
+
interface HostNotifyPayload {
|
|
1052
|
+
text: string;
|
|
1053
|
+
}
|
|
1054
|
+
/**
|
|
1055
|
+
* 子 → 父:小组件改过主线状态,请求宿主重拉 game_state 刷新聊天页面板。
|
|
1056
|
+
* scope 只用于亮对应 tab 的 badge,宿主恒全量重拉。
|
|
1057
|
+
*/
|
|
1058
|
+
interface HostStateChangedPayload {
|
|
1059
|
+
scope?: HostPanelScope[];
|
|
1063
1060
|
}
|
|
1064
1061
|
interface AckPayload {
|
|
1065
1062
|
ok: boolean;
|
|
1066
1063
|
error?: string;
|
|
1067
1064
|
}
|
|
1068
1065
|
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>;
|
|
1069
|
-
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>;
|
|
1066
|
+
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>;
|
|
1070
1067
|
declare function isProtocolEnvelope(data: unknown): data is ProtocolEnvelope<string, unknown>;
|
|
1071
1068
|
declare function envelope<T extends string, P>(type: T, payload: P, opts?: {
|
|
1072
1069
|
id?: string;
|
|
@@ -1140,6 +1137,140 @@ declare class StorviaBus<TIn extends AnyEnvelope, TOut extends AnyEnvelope> {
|
|
|
1140
1137
|
destroy(): void;
|
|
1141
1138
|
}
|
|
1142
1139
|
|
|
1140
|
+
/**
|
|
1141
|
+
* 小组件 → 主线(宿主聊天页)的联动通道。
|
|
1142
|
+
*
|
|
1143
|
+
* 两个能力都只发 postMessage 信号,不打后端:
|
|
1144
|
+
* - [notify] 主线弹一条 toast(仅小组件**后台运行**时展示,前台时宿主静默丢弃)
|
|
1145
|
+
* - [refreshPanel] 主线重拉 game_state 刷新游戏面板
|
|
1146
|
+
*
|
|
1147
|
+
* 面板能刷出内容的前提:小组件与主线**共享** player / characters / inventory /
|
|
1148
|
+
* relationships / world 这几块状态(`sdk.player` / `sdk.characters` / `sdk.inventory` /
|
|
1149
|
+
* `sdk.relationships` / `sdk.world` 写的就是主线那一份),所以先写再 refreshPanel 即可。
|
|
1150
|
+
* `sdk.custom` / `sdk.save` 是小组件自己的沙盒,**不会**出现在主线面板上。
|
|
1151
|
+
*/
|
|
1152
|
+
/**
|
|
1153
|
+
* toast 文本上限,超出截断。
|
|
1154
|
+
* ⚠️ 三端对齐:Storvia `src/constants/limits.ts` 的 WIDGET_HOST_NOTIFY_MAX_LENGTH、
|
|
1155
|
+
* App `lib/core/constants/app_limits.dart` 的 widgetHostNotifyMaxLength 须同值。
|
|
1156
|
+
*/
|
|
1157
|
+
declare const HOST_NOTIFY_MAX_LENGTH = 60;
|
|
1158
|
+
/**
|
|
1159
|
+
* 两次 toast / 两次面板刷新的最小间隔。
|
|
1160
|
+
* 这里只是第一道(省一次 postMessage),宿主侧还会独立再拦一道 —— 作者能绕过 SDK
|
|
1161
|
+
* 直接 postMessage,节流的权威判定必须在宿主。
|
|
1162
|
+
*
|
|
1163
|
+
* 两个值差两个数量级是因为代价不同:notify 纯前端(发一条消息、宿主渲染一条 toast,
|
|
1164
|
+
* toast 在宿主侧纵向堆叠不会互相覆盖),卡 1s 只为防刷屏;refreshPanel 每次都会让
|
|
1165
|
+
* 宿主重拉一次会话详情,是真实后端请求,必须卡住。
|
|
1166
|
+
*/
|
|
1167
|
+
declare const HOST_NOTIFY_MIN_INTERVAL_MS = 1000;
|
|
1168
|
+
declare const HOST_REFRESH_MIN_INTERVAL_MS = 10000;
|
|
1169
|
+
declare class HostModule {
|
|
1170
|
+
private send;
|
|
1171
|
+
private isPreview;
|
|
1172
|
+
/** 注入时间源,便于测试;生产恒 Date.now */
|
|
1173
|
+
private now;
|
|
1174
|
+
private lastNotifyAt;
|
|
1175
|
+
private lastRefreshAt;
|
|
1176
|
+
constructor(send: (msg: UpstreamMsg) => void, isPreview?: boolean,
|
|
1177
|
+
/** 注入时间源,便于测试;生产恒 Date.now */
|
|
1178
|
+
now?: () => number);
|
|
1179
|
+
/**
|
|
1180
|
+
* 给主线聊天页发一条 toast。
|
|
1181
|
+
*
|
|
1182
|
+
* 返回是否真的发出去了:文本为空、或距上次不足 [HOST_NOTIFY_MIN_INTERVAL_MS] 时返回 false。
|
|
1183
|
+
* 预览模式下没有主线可通知,降级为在小组件内部弹一条 SDK 自带 toast,方便作者调效果。
|
|
1184
|
+
*
|
|
1185
|
+
* 宿主渲染成不带状态图标的纯文本 toast —— 这是消息通知不是结果通知。
|
|
1186
|
+
* 想强调语气就在文本里放 emoji(`sdk.host.notify('📮 你的信件已送达')`)。
|
|
1187
|
+
*/
|
|
1188
|
+
notify(text: string): boolean;
|
|
1189
|
+
/**
|
|
1190
|
+
* 请求主线重拉 game_state 刷新面板(写完状态后调)。
|
|
1191
|
+
*
|
|
1192
|
+
* `scope` 声明这次改了哪几块,宿主据此亮对应 tab 的 badge;不传就只刷新不亮 badge。
|
|
1193
|
+
* 返回是否真的发出去了:距上次不足 [HOST_REFRESH_MIN_INTERVAL_MS] 时返回 false。
|
|
1194
|
+
* 预览模式下主线面板不存在,直接 no-op 返回 false。
|
|
1195
|
+
*/
|
|
1196
|
+
refreshPanel(scope?: HostPanelScope[]): boolean;
|
|
1197
|
+
}
|
|
1198
|
+
|
|
1199
|
+
interface DevConfig {
|
|
1200
|
+
apiKey: string;
|
|
1201
|
+
gameId: string;
|
|
1202
|
+
/** 本地预览/dev:指定初始模型的展示名(display name)。不传则用第一个可用模型。 */
|
|
1203
|
+
model?: string;
|
|
1204
|
+
}
|
|
1205
|
+
declare class StorviaSDK {
|
|
1206
|
+
private http;
|
|
1207
|
+
private baseUrl;
|
|
1208
|
+
private gameId;
|
|
1209
|
+
private conversationId;
|
|
1210
|
+
private modelId;
|
|
1211
|
+
private models;
|
|
1212
|
+
/** 预设 id(per-model);由宿主经 init / 'set-preset' 下发,每次生成请求自动带上 preset */
|
|
1213
|
+
private presetId;
|
|
1214
|
+
private accessToken;
|
|
1215
|
+
private initialized;
|
|
1216
|
+
private isPreview;
|
|
1217
|
+
private previewConfig;
|
|
1218
|
+
private bus;
|
|
1219
|
+
chat: ChatModule;
|
|
1220
|
+
characters: CharactersModule;
|
|
1221
|
+
relationships: RelationshipsModule;
|
|
1222
|
+
inventory: InventoryModule;
|
|
1223
|
+
world: WorldModule;
|
|
1224
|
+
player: PlayerModule;
|
|
1225
|
+
custom: CustomModule;
|
|
1226
|
+
save: SaveModule;
|
|
1227
|
+
state: StateModule;
|
|
1228
|
+
memory: MemoryModule;
|
|
1229
|
+
host: HostModule;
|
|
1230
|
+
init(): Promise<void>;
|
|
1231
|
+
/**
|
|
1232
|
+
* 监听宿主运行时下发的模型切换(envelope 'set-model')。
|
|
1233
|
+
* 正式模式用:宿主已接管模型选择,用户在宿主 FAB 改模型时实时同步到 SDK。
|
|
1234
|
+
* (预览模式的 set-model 在 listenForPreviewMessages 内单独处理。)
|
|
1235
|
+
*/
|
|
1236
|
+
private listenForModelChange;
|
|
1237
|
+
/**
|
|
1238
|
+
* 监听父页面 token 刷新(envelope 'token-update')。
|
|
1239
|
+
* Supabase JWT 默认 1h 过期,父页面 session 自动刷新后转发新 token 进来,
|
|
1240
|
+
* 否则 SDK 会一直用旧 token 请求被服务端 401。
|
|
1241
|
+
*/
|
|
1242
|
+
private listenForTokenUpdate;
|
|
1243
|
+
/** 监听父页面发来的预览模式动态更新(envelope 'config-update' / 'set-model') */
|
|
1244
|
+
private listenForPreviewMessages;
|
|
1245
|
+
/**
|
|
1246
|
+
* 调用 POST /preview/initial-snapshot 拉取与正式发布等价的初始数据
|
|
1247
|
+
* - 预览模式:传 game_config + game_state_override(来自 previewConfig)
|
|
1248
|
+
* - dev 模式:HttpClient 自动带 x-api-key,后端按 game_id 反查
|
|
1249
|
+
* 失败时返回 null(不阻塞 init,list/get 仍能用空 mem 工作)
|
|
1250
|
+
*/
|
|
1251
|
+
private fetchPreviewSnapshot;
|
|
1252
|
+
/** 重新拉 snapshot 并把结果灌进每个 module 的 mem(用于 update-config 后同步) */
|
|
1253
|
+
private refreshPreviewSnapshot;
|
|
1254
|
+
private fetchModels;
|
|
1255
|
+
private authenticate;
|
|
1256
|
+
initDev(devConfig: DevConfig): Promise<void>;
|
|
1257
|
+
getAssets(type: 'avatar' | 'icon', category?: string): Promise<AssetItem[]>;
|
|
1258
|
+
}
|
|
1259
|
+
declare function createStorviaSDK(options?: {
|
|
1260
|
+
dev?: DevConfig;
|
|
1261
|
+
}): Promise<StorviaSDK>;
|
|
1262
|
+
|
|
1263
|
+
declare class StorviaError extends Error {
|
|
1264
|
+
code: StorviaErrorCode;
|
|
1265
|
+
/**
|
|
1266
|
+
* 命中的违禁词列表,仅 `code === 'VIOLATION_WORD_DETECTED'` 时有值。
|
|
1267
|
+
* 服务端以 `matched_words` 下发,SDK 转成 camelCase 挂在这里,
|
|
1268
|
+
* 供游戏侧在自己的 UI 里高亮 / 提示具体是哪几个词。
|
|
1269
|
+
*/
|
|
1270
|
+
matchedWords?: string[];
|
|
1271
|
+
constructor(code: StorviaErrorCode, message: string, matchedWords?: string[]);
|
|
1272
|
+
}
|
|
1273
|
+
|
|
1143
1274
|
/**
|
|
1144
1275
|
* SDK 内置 Toast:参考主站 Toast.vue 样式
|
|
1145
1276
|
* 用于在 HTTP 层捕获错误后自动提示用户
|
|
@@ -1158,4 +1289,4 @@ interface ToastAction {
|
|
|
1158
1289
|
*/
|
|
1159
1290
|
declare function showToast(message: string, type?: ToastType, duration?: number, action?: ToastAction): void;
|
|
1160
1291
|
|
|
1161
|
-
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 };
|
|
1292
|
+
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 };
|