chatkit

版本与兼容承诺

ChatKit 当前的版本号是 0.x。接口稳定之前，0.x 的 minor 版本可能包含破坏性变更，变更和迁移方法都会写进 CHANGELOG.md；patch 版本不包含破坏性变更。接入时建议锁定具体版本，升级前阅读该版本的 CHANGELOG.md，并在测试环境验证实际使用的功能。

截至 2026-10-15，公网 npm 已发布 0.1.0-alpha.1（alpha、latest 均指向它）。已发布包有 renderers.errors 映射；本站源码中新增的错误卡片文字覆盖、按码默认文案和回答等待提示接口尚未进入该包。页面示例与已部署站点也不能代替安装包的导出类型和版本说明。

可以依赖哪些接口

范围使用建议
包入口导出的组件、hooks、类型、运行时与适配器按所安装版本的类型定义和文档使用；升级时检查导出和签名变化
settings、features、slots、renderers、回调使用公开 props，不依赖组件内部状态
--chatkit-* 样式变量用于主题定制，见主题
事件名、载荷与 schemaVersion上报时保留版本字段；当前事件结构版本为 2，它与 npm 包版本是两个概念
CSS Modules 生成的类名、DOM 层级、未导出的内部模块不作为接入接口，可能随实现调整

具体入口见入口与导出。直接使用运行时还需自行管理订阅、历史加载和释放，不能照搬界面 hooks 的生命周期行为。

安装与升级

  • 以实际发布的版本和标签为准。alpha、next、latest 是安装标签，不代表固定的兼容周期；不要假设每个版本都经过同一套标签流转。
  • 升级时核对 peer 依赖（只有 react / react-dom ^18 || ^19），重点检查已用到的 props、导出、适配器请求与历史格式、事件载荷、主题和功能默认值。
  • 用目标版本在测试环境验证发送、停止、切换会话、历史恢复、错误处理与自定义内容，再发布业务应用。
  • 发现接口变更时按对应版本的更新说明迁移。当前不承诺自动兼容旧写法、开发环境废弃警告、固定的接口保留周期，也不预先承诺 1.0 之后新增功能的默认开关规则。

事件结构的当前约定是新增字段保持原字段含义，删除字段或改变含义时提升 schemaVersion。接入方解析事件时应允许未知字段，并对不支持的版本单独处理。