用途
该技能用于把应用从 Stream(GetStream)Chat 迁移到 CometChat,覆盖 React、Angular、React Native/Expo、iOS 等本技能包支持的平台。当用户提出“将我的应用从 GetStream/Stream 迁移到 CometChat”“替换 Stream Chat”“切换到 CometChat”,或 npx @cometchat/skills detect --json 报告 migrate_from 为 getstream 时使用。若应用同时使用 Sendbird 与 Stream,可依次运行两个迁移技能,合并为一份报告。若用户仅要求迁移数据(“只迁移数据”“导入 Stream 用户和消息”“不要改代码”,或应用已运行在 CometChat 上),则改走数据专用流程,只编写并运行数据脚本,不改动其他内容。
主要能力
- 检测与清单:通过
npx @cometchat/skills detect --json获取框架、Android 变体、是否已有 CometChat、迁移来源;按清单文件逐项 grep 记录 Stream 使用点(包、导入、客户端创建、connectUser、SDK 组件、事件订阅、频道查询、自定义附件、推送设备、Video、Feeds、环境变量、服务端令牌、webhook、测试/模拟),并分类为 UI SDK 模式、客户端模式或混合模式。 - 功能映射:对清单中每个 Stream 功能,在功能映射表中查找对应 CometChat 功能,并检查目标平台
features.json;若 UI Kit 缺失,再查 Chat SDK/REST 文档,两者皆无才标记为不支持。 - 代码替换:按概念映射逐文件替换,包括客户端/连接、频道列表、消息面板、成员频道、事件监听、附件/线程/表情、主题/国际化、视频、推送等;移除不再使用的 Stream 导入。
- 服务端迁移:将 Stream 令牌铸造替换为 CometChat 认证令牌端点(REST:先创建用户再创建认证令牌),映射 webhook,移除无对应项的服务端调用。
- 数据迁移脚本:生成
scripts/cometchat-migration/,导出 Stream 用户、频道、成员和消息,经同一toCometChatId()转换后通过 CometChat 数据导入 API 导入;先 dry-run 再正式导入。 - 卸载 Stream:移除所有 Stream 依赖、CSS 导入、国际化设置、环境变量、原生配置和 CI 密钥引用,更新应用自身文档,重命名 Stream 相关标识符。
- 验证与报告:修复引入的构建错误,生成
COMETCHAT_MIGRATION.md,并在回复末尾列出“已移除——CometChat 中不可用”和“你的行动项”两份清单。
使用方式
迁移请求本身即视为批准,技能会在单次交互中按顺序执行全部步骤:检测、清单、功能映射、安装 CometChat 并接入核心、逐文件替换、完全移除不支持功能、服务端迁移、编写并运行数据迁移脚本、卸载 Stream、验证、报告。在 git 仓库中会先创建 cometchat-migration 分支;不提交、不推送、不重写历史。凭据不询问、不预置,优先复用 .cometchat/config.json 或现有 CometChat 环境值,否则写入带占位符的环境/设置文件。仅三种情况会停止:未发现 Stream 使用、平台不在本技能包支持范围、构建在开始前已失败。数据导入脚本需要用户提供源密钥与 CometChat 凭据,这是单次交互契约允许的唯一提问;用户提供后由技能从环境变量运行导入,先 dry-run 再正式导入。
适用场景
适用于需要将现有 Stream Chat 应用整体迁移到 CometChat 的团队,覆盖 UI SDK 模式(使用 Stream 的 UI 组件渲染聊天)和客户端模式(自有 UI 基于低层客户端),以及混合模式。也适用于仅迁移数据、不改代码的场景。
限制
- 仅支持本技能包中列出的平台家族;Vue、Unity、.NET 等无对应家族时,只交付清单与功能映射报告,不做改动。
- 消息导入仅限 CometChat 6 个月保留窗口内的消息;更早消息需联系 CometChat 处理。
- CometChat 仅在最多 300 名成员的群组中发送回执和输入指示(无回执时上限 100,000),大频道行为会变化。
- UID/GUID 仅允许字母、数字、短横线和下划线,最长 100 字符,且转为小写;Stream 的 cid 含冒号、成员频道 ID 以
!members-开头、用户 ID 可能含@或.,需统一清洗。 - 1:1 聊天不是群组:由两名成员创建的成员频道应转为 CometChat 用户会话。
- 自定义附件和 extraData 需迁移到 CometChat 元数据/自定义消息,否则会静默丢失。
- 原生平台(Android、iOS、Flutter)迁移必须遵循原生构建参考并运行平台构建,否则不算完成。
- 无障碍功能(跳转链接、焦点管理、实时区域、键盘快捷键)不属于“缺失功能”,需在新布局中重新实现,不得列为已移除。
- 共享原生依赖(Reanimated、手势处理、SVG、图片选择器)在移除前需确认无其他导入方。
- 不得删除仅与 Stream 代码共享文件的非 Stream 代码,应重新接线。