cometchat-migrate-from-twilio

用途

本技能用于把应用从 Twilio Conversations（或已弃用的 Programmable Chat）迁移到 CometChat，适用于本技能包内任意平台，只需一次提示即可完成。当 npx @cometchat/skills detect --json 报告 migrate_from 为 twilio 时使用；Sendbird/Stream 应用应使用各自的技能。

主要能力

• 检测框架、是否已存在 CometChat、迁移来源，并解析目标家族（family）。
• 按 references/inventory.md 清点 Twilio 使用点（包、Client/Conversations.Client、访问令牌获取、会话创建/查询、消息发送/获取、参与者、监听器、媒体、属性、推送、令牌服务器等）。
• 按 references/feature-map.md 做功能映射，并通过目标家族的 features.json 与文档确认 CometChat 侧是否存在对应功能。
• 安装 CometChat 并按 cometchat-<family>-core 接入初始化与登录。
• 逐文件替换数据层：Twilio Client 初始化/令牌 → CometChat 初始化/登录；Conversation → 用户或群组会话；Participant → 群组成员；消息发送/获取 → CometChat 请求；监听器 → CometChat 监听器（卸载时移除）；媒体 → 附件；属性 → 元数据。保留应用 UI，在边界处映射。
• 完全移除不支持的功能（代码、UI 入口、状态、依赖、测试）并记录。
• 服务端替换：Twilio 访问令牌端点 → CometChat 认证令牌端点；Twilio webhook → CometChat webhook，无对应则删除并列出。
• 编写数据迁移脚本，并在用户提供凭据后运行导入。
• 卸载 Twilio 依赖、环境变量、原生配置、CI 密钥，更新应用文档并重命名 twilio* 标识符。
• 验证构建与运行，修复引入的错误，并生成 COMETCHAT_MIGRATION.md 报告。

使用方式

迁移请求本身即视为批准，需在一轮内按顺序执行全部步骤，不设计划/批准关卡、不提问，采用文档默认值并记录在“Defaults taken”下。在 cometchat-migration git 分支上工作，不提交/推送。数据导入脚本仅在最后、且用户提供凭据后运行；该凭据提示是“不提问”契约的唯一例外。凭据通过环境变量传入，绝不写入仓库文件：先 --dry-run（显示计数），再真实导入，最后报告结果。仅 CometChat 6 个月保留窗口内的消息可导入，更早消息需联系 CometChat。若用户拒绝提供凭据，则将运行导入列为待办事项。

适用场景

• 用户要求“将我的应用从 Twilio 迁移到 CometChat”“替换 Twilio Conversations”或“将我的应用迁移到 CometChat”，且检测到来源为 Twilio。
• 应用已有自有的聊天 UI，希望保留 UI 仅替换数据层。
• 若用户希望改用 CometChat 预置 UI，可提供替换为家族 UI Kit 的选项，但安全默认是仅替换数据层。

限制

• 仅当未发现 Twilio 使用、平台在本技能包中无对应家族、或应用在开始前就无法构建时才停止（记录并继续迁移，标注为既有问题）。
• CometChat 侧信息不得凭记忆：符号来自目标家族技能与目录，功能存在性来自 features.json，签名来自 cometchat-<family>-core/references/docs-map.md。
• 空 MCP 搜索结果视为“不确定”而非“不支持”，需换用 CometChat 词汇重查、实时抓取文档页、交叉核对家族目录；仅当目录缺失且实时文档抓取也无结果时才标记为 UNSUPPORTED。
• 身份标识需统一使用共享的 toCometChatId()，并处理 Twilio 身份字符串中 CometChat UID 不接受的字符（alpha-dash、≤100、小写）。
• 两个参与者的 Twilio 会话应映射为 CometChat 用户会话，而非两人群组。
• 访问令牌 ≠ Auth Key：Twilio 客户端令牌映射为 CometChat 认证令牌（服务端签发），绝不发布 Auth Key。
• 需移除所有监听器（卸载时）与功能入口，避免半移除状态。
• 验证要求：应用以家族常规命令构建、零 Twilio 残留、所有 CometChat 符号存在于目录、迁移功能在 features.json/文档中、UNSUPPORTED 项在报告中列出、客户端登录/令牌服务器/数据脚本使用同一 toCometChatId()。必须实际运行并读取日志，编译通过不等于应用可用；若无法在此启动，需说明并给出确切运行命令与观察要点。