cometchat

**Ground truth：**路由信息在 peers.yaml（数据）中；共享规则在 RULES.md 中。这是一个轻量分类器——仅负责检测和分发。这里不涉及工作流、凭据逻辑或组件细节；这些内容位于 cometchat-onboarding、解析出的所属系列技能以及 RULES.md 中。

使用场景

用户想在项目中添加 CometChat、升级现有项目，或将项目从 Sendbird / Stream 迁移过来。触发语句：“添加聊天”“添加 cometchat”“添加语音/视频通话”“将我的 v6 UI Kit 升级到 v7”“为我的 iOS 应用添加聊天”“用 Swift 添加聊天”“将我的 v4 iOS UI Kit 升级到 v5”。

如果这里找不到——获取资料，绝不猜测

这适用于每个 Agent 和每种安装模式，无论上方是否有匹配项。

• **需要的 CometChat API 不在上方的表格中？**打开解析出的所属系列的 core 技能 → references/docs-map.md，并按其中的指引前往文档页面。在任何文档 URL 末尾添加 .md，即可获取干净的 Markdown 版本。
• **绝不对 node_modules 使用 grep。绝不读取 *.d.ts。**它们暴露的是内部、不受支持且随版本变化的接口，并非公共 API——基于这些接口编写的代码会在下一个工具包版本中失效，而且往往在当前使用的版本中也无法正常运行。
• **绝不根据训练记忆作答。**UI Kit API 会随主版本变化。
• **如果文档确实没有涉及相关内容，请如实说明并停止。**如实回答“文档未说明此内容”是正确的。切勿编造看似合理的 API。

全文：RULES.md → “Fetch discipline”。

仅执行以下操作

0. 从 Sendbird 或 Stream（GetStream）迁移 → 直接转到该供应商的技能。不进行引导。 触发条件：“migrate my app to CometChat”、“migrate / switch / move from Sendbird|Stream|GetStream|Twilio”、“replace Sendbird|Stream Chat with CometChat”。运行 npx @cometchat/skills detect --json：每个 migrate_from 条目都会指出该供应商的 skill（cometchat-migrate-from-{sendbird,getstream,twilio}，在 peers.yaml 的 migrations: 中路由）；即使 detect 未检测到，用户明确提到的供应商也算。该技能会在一条提示词中完成整个迁移（检测 → 替换 → 移除 CometChat 不支持的内容 → 验证 → 列出最终移除的功能），并直接进入 <family> 核心技能。“Migrate to CometChat”既未检测到也未提及供应商 → 说明未发现 Sendbird/Stream 用量，然后继续执行规则 1/2。仅迁移数据（“migrate only my data from Sendbird|Stream”、“import my users/messages into CometChat”）→ 使用同一供应商技能的仅数据模式（references/data-only.md）：只要提及供应商即可（无需检测代码），且只会修改 scripts/cometchat-migration/ 并生成 COMETCHAT_MIGRATION.md 报告。Twilio 没有仅数据模式：说明这一点并提供完整迁移选项；对于仅数据请求，绝不要修改应用代码。在已设置 migrate_from 的仓库中仅提出“add chat” → 进行引导，在计划中注明该供应商并提供迁移选项。
1. 已经集成 + 提出具体请求 → 直接转到任务技能。不要运行引导。 运行 npx @cometchat/skills detect --json——以其结果为准：existing_cometchat: true 表示存在 CometChat UI Kit/SDK 依赖（@cometchat/chat-uikit-*/chat-sdk-*/calls-sdk-*、com.cometchat:*、cometchat_*、CometChatUIKitSwift）。如果无法运行，就在仓库中查找同一依赖。.cometchat/ 文件夹不是证据——安装程序和 dashboard CLI 都会创建它。（dashboard CLI @cometchat/skills-cli 没有 detect；RULES.md → “The CLI is a dashboard/API client only”。）存在依赖 ⇒ 计划/批准流程已经完成。将用户请求视为一项任务，而非集成：解析 <family>（规则 4），根据规则 5 的映射选择 <type>，直接打开对应技能。这是正在运行的应用中最常见的情况——“change my avatar”、“add a logout button”、“add polls”、“restyle the bubble”、“my custom view isn't showing”——这些都不是引导。如果仍将其送入关卡，就会重新询问用户已经回答过的问题；更糟的是没有相应分支，因为 Agent 会脱离流程，并根据 node_modules 猜测（AUDIT-106）。
2. 首次提出“add CometChat”（add chat / add calling / integrate cometchat）→ 必须始终先转到 cometchat-onboarding。 这是强制关卡，不可跳过：引导会在进入任何框架核心技能之前，执行与框架无关的 DISCOVER → UNDERSTAND → PLAN 流程（检测整个仓库、询问意图并提供推荐默认值、生成完整计划文档、设置修改/批准关卡）。随后，它会向框架核心技能传递范围明确的构建指令。首次提出添加请求时，不要直接转到 -core 技能——必须先经过引导关卡。（对于已经集成的仓库，引导会直接跳过；参见其 Re-entry 部分。）
3. 升级请求（“upgrade v6 to v7”、“v4 to v5”、“v5 to v6 Android”）属于版本协调，不是引导 → 直接转到 cometchat-<family>-migration（它就是用于版本协调的技能）。version_conflict 的 STOP 仍适用于添加请求；引导会在计划中指出冲突，并在交接前完成协调。
4. 只从项目解析一次 <family>，绝不凭空假设。 每个技能文件的命名格式都是 cometchat-<family>-<type>。从 peers.yaml 中匹配行的 dir_prefix 获取 <family>——使用 detect 探测结果的 framework，否则根据你读取的文件（package.json/lockfile、angular.json、settings.gradle(.kts) + app/build.gradle(.kts)、pubspec.yaml、*.xcodeproj/*.xcworkspace/Package.swift）匹配其 detect_signals：React web → react-v7；Angular（检测到 angular.json）→ angular-v5；React Native / Expo → react-native；Android（检测到 settings.gradle(.kts)）→ android-v6（仅有 calls-sdk-android / “calling from scratch”请求 → android-calls 行，cometchat-android-v5-calls-sdk）；Flutter（pubspec.yaml）→ flutter-v6；iOS → ios。将项目路由到其他系列的技能属于缺陷——将 React Native 应用送到 react-v7 技能会得到原生平台上不存在的 Web 专用 API（没有 UIKitSettingsBuilder，login 接受对象，回调是 on*Press 而非 on*Click）；反过来也同样行不通。如果检测到的框架没有匹配行，就说明该平台不在此技能包中——不要用最接近的平台替代。
5. 批准后，引导会交接给 cometchat-<family>-core。 只有批准的计划明确列出时，它才会引入其他已发布技能（渐进式披露）。始终在已解析的 <family> 下，按以下 <type> 路由：
   • 组件 → cometchat-<family>-components
   • 放置/布局 → cometchat-<family>-placement
   • 主题/品牌定制/自定义消息类型 → cometchat-<family>-customization
   • 功能（搜索、回执、回应、AI、审核等）→ cometchat-<family>-features
   • 语音/视频通话 → cometchat-<family>-calls
   • 推送通知 → cometchat-<family>-push（精简 + 文档优先——获取通知文档；实时送达需手动在设备上检查）
   • 升级现有大版本 → cometchat-<family>-migration
   • 框架适配（环境变量、SSR/islands、路由、原生构建配置）→ 在 react-v7（Vite/Next/CRA/React Router/Astro）、angular-v5、flutter-v6 上使用 cometchat-<family>-patterns。react-native：使用拆分的技能对 cometchat-react-native-expo-patterns（Expo）/ cometchat-react-native-bare-patterns（RN CLI/bare）——根据是否存在 expo 依赖来选择。iOS 和 Android 没有 patterns 技能。
   • 分析 / 指标 / 可观测性 / 监控 / 仪表板 / 向 Datadog·Segment·BigQuery 发送事件 → cometchat-analytics。
   • 审计 / 审查 / 对现有集成进行健康检查 → cometchat-audit（只读；将修复路由到负责的技能）。
   • 无障碍 / WCAG / 屏幕阅读器 / 键盘 → cometchat-a11y。本地化 / i18n / 翻译界面 / RTL → cometchat-i18n。（跨系列，适用于所有系列。）
   • 企业安全 / SSO / RBAC / 会话撤销 / 多租户 → cometchat-security（跨系列：服务端 + 访问控制模型；客户端登录仍由系列核心/生产技能负责）。数据驻留 / GDPR / 保留期限 / 审计日志 / eDiscovery → cometchat-compliance。本地部署 / 自托管 / 私有云 → cometchat-self-host。内容审核 / 安全 / 脏话 / 图片审核 → cometchat-moderation。这四项适用于所有系列（与引导一样）。
   • 生产环境加固 / 测试 / 故障排查 → 在所有 UI 系列（react-v7、angular-v5、react-native、ios、android-v6、flutter-v6）上使用 cometchat-<family>-{production,testing,troubleshooting}。events → android-v6、flutter-v6。
   • 仅限 react-native — cometchat-react-native-sdk（方法→契约回退映射；kit v5 移除了详情/管理屏幕，因此对于 RN，SDK 调用是主路径，而非备用方案）。
   • 仅限 android-v6 — 按群组划分的技能（根据 gradle 文件选择群组：kotlin-* = XML Views，compose-* = Jetpack Compose）：cometchat-android-v6-{kotlin,compose}-{components,placement,customization}；还有 builder-settings、extensions。无头 Chat SDK v5（自行构建 UI）→ cometchat-android-v5-sdk。
   • 无头 Calls SDK v5（从零开始构建通话，无 UI Kit——类似 meet 的通话或 1:1 响铃；通过引导中的通话优先树）→ cometchat-js-v5-sdk（Web）· cometchat-react-native-v5-sdk · cometchat-ios-v5-sdk · cometchat-android-v5-calls-sdk · cometchat-flutter-v5-sdk。如果尚未安装？运行 npx @cometchat/skills add --family <js|react-native|ios|android|flutter>-calls，即可在 UI Kit 技能旁添加该技能。预构建通话 UI 仍使用 cometchat-<family>-calls。
   • iOS 使用 SPM 集成：CocoaPods 正逐步停用（spec 仓库即将变为只读），因此 Podfile 仅是检测信号，绝不是安装说明。
   • 不在此技能包中——不要路由（采用“不在此技能包中”的处理方式）： 无头 JS Chat SDK 没有单独的技能（其方法是核心技能中各功能的回退方案）。如果批准的计划需要确实没有已发布技能支持的功能，就如实说明，提供 CometChat 文档 + 将计划作为规格说明，并引导至已发布的实现路径——绝不要路由到技能包中不存在的技能。 对于尚无核心技能的框架（目前为 Vue），引导仍会交付计划，并说明该平台的核心技能尚未构建。Angular 已有支持——@angular/core/angular.json 匹配 peers.yaml 中的 angular 行；应路由到该行的 dir_prefix + core 及其系列中的其余技能（v5 kit，已通过目录验证，版本对应 5.1.0）；绝不要告诉 Angular 用户其平台不受支持。
6. 不要在此处编写集成代码——引导负责规划，系列技能负责构建。 路由数据：peers.yaml。规则：RULES.md。此文件有意保持简短。