技术手册 · SDK
从 Starter 开始
选择 H5 或 React 模板，理解 SDK 初始化与真实宿主、mock 的区别。
H5 和 React 两个模板可以在《AI玩家 SDK 使用教程》（语雀）里获取。下面说的 sdk/examples/ 是模板在 SDK 仓库里的目录。
两个模板均位于项目的 sdk/examples/ 目录。先使用原始模板跑通，再逐步替换页面结构。它们都是独立页面模板，不是全局 JS 脚本。
H5 starter
sdk/examples/charx-h5-starter 使用 HTML、CSS 和 JavaScript，没有构建步骤。页面入口是 index.html，脚本在 assets/app.js，样式在 assets/app.css，另有 panel-demo.html 用来检查扩展面板地址。
在仓库根目录运行 npx http-server ./sdk/examples/charx-h5-starter -p 5173 -c-1，然后打开 http://127.0.0.1:5173。请通过 HTTP 服务访问；直接双击 HTML 文件会受浏览器 ES Module 限制。
模板的 assets/app.js 从 jsDelivr 引用 @ai_wanjia/sdk@1.0.8。上传后仍需要加载这个外部依赖；静态包本身并不包含该 CDN 文件。
React starter
sdk/examples/charx-react-starter 使用 Vite、React 和 TypeScript。进入该目录，执行 npm ci 安装锁定依赖，再执行 npm run dev。打开终端显示的地址；模板默认开发地址为 http://127.0.0.1:5173。
首页 src/App.tsx 展示角色信息、变量、storage、聊天和 UI / Media / Game 调用。运行时选择逻辑在模板自己的 src/runtime/createSdkRuntime.ts 中。这个辅助函数和 AppSdk 类型是模板内部代码，不是 npm SDK 的公开导出。
当前模板依赖 @ai_wanjia/sdk@1.0.8，构建命令 npm run build 会先做 TypeScript 检查，再输出 dist/。它没有直接使用 CharxProvider；需要 SDK 提供的 React Hooks 时，参阅 React 集成。
初始化 SDK
在自己的打包项目中，从包根入口导入 CharxSdk，通过 getInstance() 获取实例，等待 init() 成功后再调用模块。下面是浏览器端 TypeScript 入口示例，要求页面已被平台宿主加载，且项目能解析 @ai_wanjia/sdk。
import { CharxSdk } from '@ai_wanjia/sdk'
async function main() {
const sdk = CharxSdk.getInstance()
await sdk.init()
const character = await sdk.character.getInfo()
console.log('当前角色', character.name)
console.log('宿主声明的能力', sdk.capabilities)
}
void main().catch((error: unknown) => {
console.error('连接平台失败', error)
})init() 发起握手并等待宿主返回会话令牌，当前 SDK 最长等待约 8 秒；重复初始化会复用进行中的握手。isReady 表示 SDK 握手是否完成。未初始化的普通调用会被拒绝。
对带能力声明的功能，使用 supports() 检查，例如 sdk.supports('chat.rewind')。capabilities 不是完整方法目录；未列出的接口不能仅凭名称推断是否可用，仍需处理宿主错误并实际联调。
真实宿主与 mock
| 运行方式 | 模板的行为 | 适合验证什么 |
|---|---|---|
| 直接打开本地 HTTP 页面 | 使用本地 mock | 布局、组件状态、按钮和示例数据 |
| 平台 iframe 中握手成功 | 使用真实 SDK | 与当前平台宿主的交互 |
| 平台 iframe 中握手未及时成功 | 模板约 3 秒后回退到 mock | 只能继续检查本地交互，不能证明接入成功 |
约 3 秒回退是 starter 自己的逻辑，与 SDK 的约 8 秒握手超时不同。联调时确认页面显示“平台 iframe”，并检查真实角色数据；出现“本地 mock”或控制台回退提示时，应先排查宿主连接。
mock 使用内存数据和预设回复，刷新会重建状态，不调用真实 AI，也不验证平台数据持久化。部分操作只是演示：两个模板的 mock 中 regenerate()、continue() 是空实现，messages.swipe() 会报错。不要据此判断正式功能是否可用。