技术手册 · SDK
选择 SDK 接入方式
区分 HTML 消息、全局 JavaScript 与独立页面，选择适合的接入方式。
@ai_wanjia/sdk 用于让自定义页面与平台宿主通信。页面负责布局和交互，角色设定、会话与 AI 请求仍由宿主处理。先确定要修改哪一层，再选择入口。
HTML 消息
HTML 消息是聊天记录内的一个展示片段，适合状态卡、选项或局部交互。它可能来自角色回复或正则替换，不等于一份独立页面资源包。其隔离方式和可用桥接接口由具体宿主决定，不能假定所有消息都能使用完整 npm SDK。
如果只需把固定格式的回复变成状态卡，从正则与美化开始；需要现成代码和效果预览可看美化实例。
全局 JS
全局 JS 在角色运行期间响应发送、消息变化和销毁等事件。使用宿主提供的 $charx.hooks 或 registerCharxHook，具体约定见全局 JavaScript Hook。
全局脚本有单独的校验和运行限制。不要把 npm 的导入代码直接粘进全局 JS 编辑器；npm CharxSdk 实例也不提供全局脚本的 hooks 属性。包中导出的 Hook 类型用于描述契约，不代表提供了 Hook 注册运行时。
独立页面
独立页面用于自定义整个聊天区域，例如游戏式界面、仪表盘或组件化聊天页。上传 HTML 或 ZIP 资源包，并在平台提供的环境内通过 SDK 与宿主通信。
推荐从维护中的 H5 或 React starter 开始。它们包含本地 mock，便于先调整界面；进入平台 iframe 并完成握手后才会连接真实宿主。详见从 Starter 开始和联调与打包上传。
选择建议
| 目标 | 推荐入口 | 需要验证的边界 |
|---|---|---|
| 把一条回复显示成状态卡 | HTML 消息、正则与 CSS | 消息内部样式和交互 |
| 发送前检查、收到消息后更新状态 | 全局 JS Hook | 事件触发、脚本限制与清理 |
| 自己组织整个聊天界面 | H5 starter + npm SDK | 握手、平台调用、资源路径 |
| 用 React 管理复杂界面 | React starter 或 React 集成 | Provider、消息状态、订阅清理 |
本栏目核对范围
本栏目 API 按仓库 @ai_wanjia/sdk 1.0.10 的公开入口、类型、实现和自动化测试核对。两个 starter 当前固定使用 1.0.8；它们的示例与构建验证不能证明 1.0.10 的新增接口已包含在 starter 中。使用新接口前，先核对项目实际安装版本。
SDK 提供某个方法，不代表每个宿主都实现了它。Creator 预览、正式 Web 聊天与 App 要分别验收；源码和构建通过不等于已经完成线上及真机测试。