技术手册 · SDK
SDK 核心模块
核对聊天、角色、模型、变量、存储、世界书、UI、媒体与游戏接口的用途和限制。
以下接口均通过 CharxSdk.getInstance() 获取的实例访问，调用前必须等待 init()。方法签名按仓库 SDK 1.0.10 核对；实际执行由宿主决定。类型从 @ai_wanjia/sdk 导入，不需要直接引用内部模块文件。
chat：消息与生成
| 方法 | 用途与返回值 |
|---|---|
send(text, options?) | 发送消息，返回 void；通过回调处理增量、完成和错误 |
sendStream(text, options?) | 返回 ChatSendTask，包含 requestId、done: Promise<Message> 和 stop() |
stop() | 请求停止当前生成 |
regenerate() / continue() | 请求宿主重新生成或继续生成 |
messages.getAll() / messages.list(options?) | 读取宿主返回的历史；分页可使用 limit、offset |
messages.edit(id, content) | 返回更新后的 Message |
messages.delete(id, options?) | 请求宿主确认并删除消息 |
rewind(id, options?) | 需要 chat.rewind 能力；用户取消时返回 false |
getInput() / setInput(text) | 读取或设置宿主输入内容 |
setGreetingIndex(index) / getGreetingIndex() | 设置或读取开场白索引；切换应在第一条用户消息发送前完成 |
generateRaw(messages, options?) | 后台生成文本，返回 Promise<string>，不追加聊天记录 |
injectPrompt(content) | 为下一次面向用户的生成注入提示词，下一次 chat.send() 后清除 |
insertSystemMessage(content) | 插入系统消息，返回 Message，不触发生成 |
getConversationId() | 读取当前宿主提供的会话 ID |
getLastDiagnostics() | 读取当前运行实例最近一次生成的诊断，可能为 null |
generateRaw() 的上下文选项为 includeCharacterContext；有会话上下文时默认包含角色上下文。它仍是 AI 请求，不因“后台”就代表免费。模型权限、计费和可用性由平台决定。
下面的函数可在页面按钮事件中调用；它会发送一条真实消息。onData 的参数是增量字符串，done 提供完成消息，失败时会拒绝。
import { CharxSdk, type Message } from '@ai_wanjia/sdk'
export async function sendMessage(text: string): Promise<Message> {
const sdk = CharxSdk.getInstance()
await sdk.init()
const task = sdk.chat.sendStream(text, {
onData: (chunk) => console.log('增量', chunk),
})
try {
return await task.done
} catch (error: unknown) {
console.error('发送失败', error)
throw error
}
}发送超时按流式活动重新计时，默认约 60 秒无活动后失败。task.stop() 带本次请求 ID 请求停止；sdk.chat.stop() 请求停止当前生成。停止请求返回不等于最终消息已经保存，仍需观察宿主消息与历史。
确认型删除、回溯的 ChatActionOptions.timeoutMs 默认或 null 表示不设包含确认等待的整体时限；正数表示最大毫秒数。删除取消可用公开函数 isChatActionCanceledError(error) 识别。兼容旧宿主时，即使删除调用返回 void，也应重新读历史确认结果。
Message.generationStatus 可为 pending、streaming、completed、failed 或 canceled，但它是可选字段。rewindReady: true 表示有精确恢复快照；false 的旧节点仍可能支持确认后重置，不能直接解释成绝对禁止回溯。Creator 预览不支持正式会话回溯。
兼容占位不是通用功能
chat.messages.swipe() 和 React 的 swipeMessage() 已被标记为兼容占位；当前 Creator 预览与 Web 聊天宿主可能拒绝调用。不要把它们作为可用的多候选切换能力。按用途选择重新生成、继续生成、编辑，或自行用变量管理候选状态。
setFirstMesIndex() 已弃用，使用 setGreetingIndex()。底层常量 EVENT 是 METHODS 的旧别名；METHODS.CHAT_MESSAGE_LIST 也已弃用，普通页面使用 messages.list()，无需手工拼 RPC。
character：角色与人设
getInfo() 返回公开角色信息，包括名称、头像、简介、开场白和标签等可选字段；不要把它当成完整角色卡或系统提示词读取接口。getPersona() 返回用户人设或 null。getSettings() 返回角色设置，当前公开类型包含可选 model。
model：选择宿主公开的模型
list() 返回 AIModelInfo[]，getCurrent() 返回当前模型配置名或 null，select(value) 选择模型，select(null) 恢复宿主默认模型。模型的 value 是平台配置名，不是供应商原始模型 ID。
onChanged(callback) 订阅模型变化并返回取消函数。界面可读取 pointsPerMessage、billingDescription 等信息展示费用；可选的健康指标或计费字段不存在时，不要自行补成零或健康。具体选择仍受宿主校验。
variable：会话变量
getAll() 返回变量表；get<T>(key) 返回值或 null；set()、setMany() 写入变量。increment(key, delta?) 和 decrement(key, delta?) 返回更新后的数值，默认变化量为 1。delete(key) 删除一个变量，clear() 清空变量，使用前应明确范围。
watch(key, callback) 接收新值和旧值；旧值初次可能为 undefined。watchAll(callback) 接收完整变量表。订阅依赖宿主推送，不会代替首次读取。泛型仅提供编译期类型，不验证宿主数据的实际格式。
下面的函数返回清理函数，页面或组件退出时必须调用它：
import { CharxSdk, type Unsubscribe } from '@ai_wanjia/sdk'
export async function observeVariables(): Promise<Unsubscribe> {
const sdk = CharxSdk.getInstance()
await sdk.init()
const unsubscribe = sdk.variable.watchAll((values) => console.log(values))
try {
console.log('当前变量', await sdk.variable.getAll())
return unsubscribe
} catch (error: unknown) {
unsubscribe()
throw error
}
}storage：宿主管理的持久化键值
set(key, value) 写入，get<T>(key) 读取值或 null，getOrDefault(key, defaultValue) 在缺值时返回默认值，但不会自动写入默认值。has()、keys()、remove()、clear() 分别用于判断、列举、删除和清空。
storage 访问当前会话的存档，作用域由宿主绑定；不能当作任意角色之间共享的账号存储。Creator 预览和 starter mock 也不能证明正式会话的持久化结果。需要确认保存时，应在正式宿主重新进入同一会话后回读。
worldbook：会话世界书覆盖
getAll() 返回会话、角色、条目数量及 entries。每项包含 entryKey、正文、关键词、启用状态和覆盖状态。后续操作使用返回的 entryKey，不要把列表位置当成条目键。
enable()、disable()、batchToggle() 控制条目启用；setContent(entryKey, content) 覆盖当前会话的条目正文；clearContent(entryKey) 清除该项正文覆盖；reset() 恢复全部条目的模板默认状态。它们不是角色卡模板编辑接口。
第三个参数 WorldbookContentOptions 可设置 enabled 和 activation（conditional 或 always）。SDK 先检查握手能力或 getAll() 返回的 worldbook.setContent.options 能力，不支持时会在修改前报错。不要静默忽略选项来冒充相同效果。条目启用也不等于每次生成必定注入，仍受触发条件与上下文预算影响。
ui：宿主界面交互
toast() 显示提示；alert() 等待确认；confirm() 返回布尔值；prompt() 返回输入文本，取消时为 null。后三者可传文本或对应选项对象，等待用户操作时不设整体倒计时。
openPanel() 接受 URL 或面板对象，对象的 mode 可为 fullscreen、sidebar、modal；closePanel() 请求关闭。hideChatInput()、showChatInput()、setTheme()、scrollToBottom() 请求宿主改变界面。
Toast、输入栏显隐、主题和滚动等使用单向通知，Promise 完成仅表示请求已发送。它们不能替代肉眼确认效果；App 原生输入栏与 Web 页面也应分别验证。
media：朗读与音频
speak(text, options?) 和 stopSpeak() 控制朗读。bgm 提供 play()、stop()、pause()、resume() 和 setVolume()；sfx 提供 play() 和 preload()。对应选项包括语音、速度、音量、循环或淡入淡出字段，实际播放效果取决于宿主实现、音频地址和运行环境。
先在用户点击按钮后验证播放，再检查目标设备上的暂停、退出与再次进入。mock 的本地音频或浏览器朗读不能证明平台语音和所有选项已经生效。
game：存档、成就与排行
save({ slot, description? }) 请求保存槽位；load({ slot }) 返回 Record<string, unknown> 快照；listSaves() 和 deleteSave(slot) 管理槽位。SDK 本身只转发调用，不能从返回类型推断它会自动恢复全部页面状态。
starter 在读取快照后主动把其中的 variables、storage 写回，但该示例格式不是任意宿主的通用保证。按当前宿主返回的快照验证恢复行为。
成就使用 achievements.unlock(id) / achievements.list()，排行使用 ranking.submit(score, options?) / ranking.getTop(options?) / ranking.getSelf(options?)。unlockAchievement()、listAchievements()、submitScore()、getTop()、getSelfRank() 是对应的便利方法。排行选项可带 category，列表查询还可带 limit。