技术手册 · SDK
联调与打包上传
在 localhost 联调独立界面，构建相对资源路径并按 ZIP 根目录规则上传验收。
独立界面先在本地调整，再进入平台联调，最后上传静态资源包。构建通过只能证明产物生成成功，接入和保存仍要在目标宿主检查。
localhost 联调
- 按从 Starter 开始启动本地 HTTP 服务，先直接访问页面，检查布局。
- 在角色编辑页右侧预览设置或测试页选择“本地调试界面”，填写实际入口，例如
http://localhost:5173/index.html。该地址只在当前浏览器保存，不是发布地址。 - 确认页面显示“平台 iframe”，并显示真实角色信息。若显示“本地 mock”，查看控制台握手或加载错误。
- 测试一次发送、流式回复、停止、变量写入和读取。涉及其他模块时，分别检查对应的真实效果。
localhost 指运行浏览器的这台机器。本机浏览器能访问，不代表手机也能访问。跨设备联调时需要使用该设备可达的开发地址，并单独核对宿主和网络条件。
若本地服务无法加载，先检查端口、服务是否启动以及地址是否能直接访问，再使用预览设置中的“重连”。服务连通也不等于 SDK 握手成功。
相对资源路径
平台托管资源会放到自己的目录下。页面内脚本、样式、图片和多页面跳转应相对于包内文件定位，避免依赖站点根目录的 /assets/... 或开发机地址。
H5 starter 的 assets/app.js 通过 import.meta.url 定位同一包内的 panel-demo.html。React starter 的 Vite 配置使用 base: './'，扩展面板按页面地址定位。保留这些相对路径策略，修改目录结构后重新验证。
相对路径不表示所有资源都已打入 ZIP。H5 starter 的 SDK 仍来自 CDN；你新增的外部图片、字体和音频也要检查上传后的可访问性。
build 与 ZIP 根目录
| 模板 | 构建步骤 | 压缩内容 |
|---|---|---|
| H5 starter | 无构建步骤 | 模板目录内的 index.html、panel-demo.html、assets/ 等页面资源 |
| React starter | 在模板目录运行 npm ci，然后 npm run build | dist/ 目录内的文件，保留生成的 assets/ 与 panel-demo.html |
ZIP 根目录必须直接有 index.html。压缩目录内的内容，不要额外包一层 charx-react-starter/、dist/ 或其他父目录。React 源码目录和 node_modules/ 不是上传产物。
macOS 上可以在 Finder 打开待打包目录，选择其中需要的页面文件和资源目录后压缩；随后打开 ZIP 检查第一层是否直接出现 index.html。不要只选中父目录进行压缩。
当前上传流程接受 .html、.htm 或 .zip。上传文件上限为 20 MiB，ZIP 解压后总大小上限为 50 MiB，文件数最多 1000 个；服务端还会检查路径和文件类型。单 HTML 上传只提供一个页面文件，多文件项目请打 ZIP。
上传后验收
- 在角色编辑页的“独立界面”区域上传 HTML/ZIP，并保存角色卡，让资源包绑定到当前角色。
- 在预览或测试页切换“我的界面”。该入口使用已保存的平台托管资源包；旧外部入口或未保存资源包不能代替这一步。
- 检查首页、样式、图片、字体、音频和扩展面板，没有缺失文件或开发地址依赖。
- 再次确认真实 SDK 握手，并检查发送、错误提示、停止、历史更新以及需要的变量和 storage 行为。
- 在实际面向用户的 Web 或 App 环境验收持久化、重新进入会话、会话切换与退出清理。涉及键盘、滚动和音频时，分别检查目标设备。
Creator 预览通过不能证明正式会话存档已保存；本地 mock 成功更不能代替上传后验收。本文已核对 SDK 测试、类型、构建和 React starter 构建，没有据此宣称所有宿主或移动真机功能等价。
角色审核与公开发布是后续独立步骤，见测试与提交审核。