cometchat-calls

真实依据： 各平台的 Calls SDK 和 docs/calls。官方文档： https://www.cometchat.com/docs/calls/javascript/overview · Docs MCP： claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp（也可以不使用 MCP，直接获取该 URL）。依赖这些信息之前，请先对照已安装的包或源代码验证符号。

在以下情况下使用此技能

• 顶层 cometchat 分发器的 Step 3.0 因 product === "voice-video" 或 chat-messaging+voice-video 而路由至此
• 用户明确要求实现通话功能：“添加通话”、“添加视频通话”、“添加语音通话”、“设置通话界面”、“集成 Calls SDK”、“添加 CallKit”
• 用户正在迭代现有的聊天集成，并在迭代菜单中选择了*“添加通话”*（cometchat 的 Step 7）

这是所有通话集成的入口。请勿直接调用各系列的 cometchat-{family}-calls 技能——此分发器会检测系列、选择集成模式（独立集成还是追加集成），并在满足相应前置条件后路由到正确的技能。

支持的系列：

系列	各系列技能	Calls SDK 包	当前稳定？
Web（React / Next.js / React Router / Astro）	cometchat-react-calls	@cometchat/calls-sdk-javascript	是
React Native（Expo 和 bare）	cometchat-native-calls	@cometchat/calls-sdk-react-native	是
Angular（12–15）	cometchat-angular-calls	@cometchat/calls-sdk-javascript	是
Android（V5 稳定版）	cometchat-android-v5-calls	com.cometchat:calls-sdk-android:5.x（Cloudsmith）	是
Android（V6 GA）	cometchat-android-v6-calls	chatuikit-{compose,kotlin}-android:6.0.+ + 显式添加 com.cometchat:calls-sdk-android:5.0.+ 对等依赖（“通话功能已整合”的宣传并不完整）	是——2026-05-25 GA，但开箱即用时存在缺陷：需要 5 项修正（W1–W5），包括对等依赖，且不能使用 CometChatCallButtons。请参阅各系列技能。
iOS（V5 稳定版）	cometchat-ios-calls	CometChatCallsSDK（SPM / CocoaPods）	是
Flutter（V5 稳定版）	cometchat-flutter-v5-calls（已存在）	cometchat_calls_sdk（Cloudsmith）	是
Flutter（V6 GA）	cometchat-flutter-v6-calls（已存在）	Calls 已整合到 cometchat_chat_uikit: ^6.0.1	是——2026-05-25 GA（需要显式配置一次 MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)，请参阅各系列技能）

状态： 全部九项通话技能（此分发器以及 react、native、angular、ios、android-v5、android-v6、flutter-v5、flutter-v6）均已编写，并依据各系列实际 SDK 接口完成源代码验证（反编译的 calls-sdk-android AAR、CometChatCallsSDK.swiftinterface、@cometchat/calls-sdk-{javascript,react-native} .d.ts 文件，以及 Flutter cometchat_calls_* pub-cache）。Android V5 包含 17 个预先编写的子技能，已整合到 cometchat-android-v5-calls/references/。各系列的关键注意事项：Android V6 需要 5 项修正（W1–W5）；Flutter V6 需要配置 MaterialApp(navigatorKey: CallNavigationContext.navigatorKey)；iOS 没有 CometChatCalls.login()（身份验证按会话进行，通过 generateToken 完成）。

澄清约定（所有编码 Agent）——请阅读 references/asking-questions.md。此技能中的每个“ask”/“AskUserQuestion”都遵循该约定：对于没有结构化提问功能的 Agent，请将问题呈现为编号文本列表并等待用户明确作答（绝不使用默认值或推断；自动模式不代表可以跳过提问）；按值或标签而非位置进行匹配，并接受自由文本作为备选答案。

为什么需要单独的通话分发器

聊天分发器（cometchat/SKILL.md）假定用户要添加聊天界面——它的位置术语、组件目录、框架技能和验证清单都围绕聊天设计。通话是另一种界面：

关注点	聊天分发器	通话分发器（本技能）
软件包	chat-uikit-* + chat-sdk-*	chat-sdk-* + calls-sdk-*（独立模式下不使用 UI Kit）
初始化	Chat SDK 初始化 + 登录	Chat SDK 初始化 + 登录 + Calls SDK 初始化（双 SDK 契约；在 iOS ≥5.0.2 上，优先使用基于文件的 CometChatCalls.initFromSettings，读取 cometchat-settings.json — AI Agent 遥测归因 — 而不是原始的 CallAppSettings 构建器；参见 cometchat-ios-calls §2）
位置问题	“聊天位于何处？”	“通话触发器位于何处？”+“通话记录位于何处？”
组件	Conversations、MessageList、Composer、Users、Groups	CallButtons、IncomingCall、OutgoingCall、OngoingCall、CallLogs
IncomingCall 挂载位置	聊天界面（用户聊天时响铃）	应用根节点 — 始终渲染，并监听整个应用
VoIP 推送（移动端）	可选扩展	独立模式下必须具备 — 通话不响铃就算不上产品
后台生命周期	除非添加通话功能，否则不适用	必须具备 — Android 前台服务 / iOS CallKit + PushKit

两个分发器共用 cometchat-{family}-core（初始化 + 登录 + 环境 + 主题令牌），但其他方面各不相同。

v4.1 通话集成的工作方式

与聊天分发器采用相同的对话模型 — 检测、收集、规划、编写、验证 — 但聚焦于通话。

步骤

步骤 1 — 检测系列 + 模式

如果用户来自顶层 cometchat 分发器，框架 + 凭据已位于 .cometchat/config.json 中。跳过检测并读取：

npx @cometchat/skills-cli config show --json

如果是直接调用（例如用户输入了 “为我的应用添加通话功能”），则运行：

npx @cometchat/skills-cli detect --json

系列检测方式与聊天分发器相同（reactjs、nextjs、react-router、astro、expo、react-native、angular、android、flutter、ios）。

根据项目状态选择集成模式：

信号	模式	执行内容
.cometchat/state.json 存在，且已接入聊天界面	增量式 — 在现有聊天基础上添加通话	使用对应系列在增量式部分中的 -calls 技能。修改现有 provider，在根节点挂载 IncomingCall。在聊天界面内添加通话按钮。VoIP 推送可选。
.cometchat/state.json 不存在（或没有聊天界面），且 product === "voice-video"	独立式 — 通话就是产品	使用对应系列在独立式部分中的 -calls 技能。不使用聊天 UI Kit。使用 CallButtons + IncomingCall + OngoingCall + CallLogs。VoIP 推送必须接入，不可选。添加 /calls 路由或平台对应方案以显示通话记录。
以上都不符合 — 用户想要通话，但情况不明确	询问	使用 AskUserQuestion 询问：“你是要在现有聊天集成旁添加通话功能，还是要构建一款以通话为先的应用？”

步骤 2 — 验证凭据

通话会复用 Chat SDK 凭据。如果 .env（Web/RN）、local.properties（Android）、Secrets.swift（iOS）、lib/cometchat_config.dart（Flutter）或 src/environments/environment.ts（Angular）中已有 appId / region / authKey，则跳过凭据设置。

如果缺少凭据，则转回 cometchat/SKILL.md 步骤 2 — 无论产品类型如何，凭据配置方式都相同。不要在此重复身份验证流程。

步骤 3 — 收集通话专属需求

步骤 3.0 — 通话模式（响铃还是会话）★

这是第一个通话专属问题。Calls SDK 支持两种截然不同的 UX 形式 — 必须先做选择，因为步骤 3 其余部分和各系列的脚手架都会有所不同。

按优先级顺序确定：

1. 仅根据明确的信号推断。 不要默认选择任何一种模式。在跳过提示前，用户必须清楚表明要采用哪一种。

用户表达了类似这样的意思……	模式
“1:1 通话”、“用户之间通话”、“电话”、“给朋友打电话”、“呼叫联系人”、“类似 FaceTime 的通话”、“类似 WhatsApp 的通话”	响铃
“朋友之间的群组通话”、“最多 N 人的电话会议”（小型群组，由一人发起呼叫）	响铃
“会议”、“Google Meet”、“类似 Zoom 的通话”、“预约会议”、“通过链接加入”、“会议室”、“会议室”、“网络研讨会”、“全体会议”、“虚拟课堂”	会话
“huddle”（Slack 风格——从频道即时加入）	会话
只有“通话”、“呼叫”、“集成通话”、“添加通话”、“设置通话”、“语音/视频通话”，且没有更多关于响铃还是会议的上下文	含糊不清——询问（不要默认）
信号混杂（“通话和会议”、“电话或视频会议”）	含糊不清——询问

底部几行是关键。**“集成通话”或“我想在应用中加入通话”之类的通用表述，并不代表用户选择了响铃——而是说明用户尚未告知你他们想要什么。**请询问。

如果你确实能判断出明确意图，请用一句话确认，让用户有机会更正：

“明白了——将设置响铃（1:1／群组通话，并显示来电界面）。如果你想要的是会议室 URL，请告诉我，我会切换。”

**2. 如果有，请使用第 4 层的使用场景上下文。**使用场景通常能表明模式：

使用场景	模式
远程医疗服务提供方／患者（1:1 就诊）	响铃
市场平台买家 ↔ 卖家	响铃
客户支持（客服 Agent ↔ 客户）	响铃
直播／网络研讨会／全体会议	会话
团队 huddle／站会	会话

3. 只有在无法判断时——才询问。请逐字使用以下提示词——不要改写，也不要替换选项。选项 1 是“会话”；选项 2 是“响铃”：

• question： “你正在构建哪种通话体验？”
• header： “通话模式”
• multiSelect： false
• options（严格按照以下顺序显示——先会话，后响铃）：
  1. label: "会话 — 会议／会议室", description: "多位用户通过 ID 或链接加入同一会话。不响铃。类似 Google Meet、Zoom 或 Slack huddle。例如：预约会议、网络研讨会、团队 huddle、课堂通话。"
  2. label: "响铃 — 1:1 或群组通话", description: "一位用户呼叫另一位用户（或一个小型群组）。接收者的设备会响铃；他们可以接听或拒绝。类似电话。例如：WhatsApp、FaceTime、联系人之间的应用内语音／视频通话。"

**严格顺序规则：**将选项 1 显示在选项 2 之前。不要调整顺序。在 CometChat 的各产品界面中，已统一规定会话选项优先显示。

映射到模式值：

• “响铃” → mode === "ringing"
• “会话” → mode === "session"

这会决定第 6 步加载哪个按产品系列划分的参考文档：

模式	参考文档（按产品系列划分）	参考文档（Android V5）
ringing	cometchat-{family}-calls/references/ringing-integration.md	cometchat-android-v5-calls/references/ringing-integration.md
session	cometchat-{family}-calls/references/call-session.md	cometchat-android-v5-calls/references/join-session.md

关于工具包预构建 UI 的说明（旧版文档中称为“标准”模式）：UI Kit 的 <CometChatCallButtons /> + <CometChatIncomingCall /> + <CometChatOngoingCall /> 是工具包提供的响铃实现，不是第三种模式。如果用户选择响铃并且想使用工具包的预构建 UI（最常见的情况），按产品系列划分的脚手架会使用工具包组件，并将响铃参考文档视为架构上的权威依据。如果他们想基于 chat-SDK 信令构建自定义 UI，则响铃参考文档就是实施指南。 ⚠️ 群组通话不使用 Ringing 通道（已于 2026-05-15 验证，适用于所有套件）。套件中的 <CometChatCallButtons group={g}> 会通过 CometChat.sendCustomMessage 向群组发送一条自定义会议消息，其 type 为 "meeting"，而不是调用 CometChat.initiateCall。其他群组成员会在 <CometChatMessageList /> 中收到会议卡片（基于套件的接收方），或者通过 MessageListener.onCustomMessageReceived 收到一条 category: CATEGORY_CUSTOM 且 type: "meeting" 的消息（自定义 UI 接收方）。CallListener.onIncomingCallReceived 通道仅适用于 1:1 用户通话。如果用户需要群组通话，除了 ringing-integration.md 之外，还要加载 references/group-calls.md——群组通话有自己的架构，即使客户认为它是“群组的响铃”。

步骤 3.1 — 通话触发位置（从哪里开始通话）

这与聊天调度器的步骤 3a 原型问题不同。在通话界面询问触发位置意图：

询问用户（保留结构化格式——question/header/multiSelect/options[].label/options[].description）：

• question：“用户应如何在你的应用中开始通话？”

• header：“通话触发方式”

• multiSelect： false

• options（选项集因模式而异——仅显示与步骤 3.0 中 mode 相符的选项）：

  如果 mode === "ringing"——显示以下选项：

  1. label：“用户/联系人个人资料上的通话按钮”，description：“用户名旁的语音和视频按钮。适用于电商平台、社交、约会、医疗保健应用。”
  2. label：“常驻的 '/calls' 路由”，description：“专属通话页面，包含‘开始通话’选择器和通话记录。适用于远程医疗、虚拟活动、联络中心。”
  3. label：“嵌入聊天界面”，description：“聊天标题栏中的通话按钮——消息线程旁的语音和视频按钮。适用于已有聊天功能的应用。（仅限增量模式。）”
  4. label：“浮动小组件”，description：“始终可见的通话气泡——类似 Zoom 的浮动窗口。适用于支持/销售工具。”

  如果 mode === "session"——改为显示以下选项：

  1. label：“会议链接路由（'/meet/:sessionId'）”，description：“可分享的 URL，任何持有链接的人都能加入。适用于预定会议、网络研讨会、课堂。”
  2. label：“绑定频道的快速会话”，description：“会话以聊天频道/群组 ID 为键——频道中的任何人都能加入正在进行的快速会话。适用于团队协作应用。”
  3. label：“大厅/等候室路由”，description：“用户进入等候页面，由主持人准许加入。适用于远程医疗、客户支持。”
  4. label：“自定义 — 我会自行接入”，description：“只需提供 SDK 对接代码。我会自行决定界面。”

所选选项决定要加载哪个通话触发家族的 -calls 技能章节，以及要搭建什么样的脚手架。

然后单独询问通话记录——通话记录通常与触发界面不同：

• question：“通话记录应放在哪里？”
• header：“通话记录”
• options：
  1. label：“专属 /calls 路由（或屏幕）”，description：“推荐——完整的通话记录，可筛选，并可跳转到来电者的个人资料。”
  2. label：“放在通话触发界面中”，description：“通话按钮下方的精简列表。适用于通话量较少的场景。”
  3. label：“不显示通话记录”，description：“跳过——通话直接进行，不提供记录界面。”

步骤 4 — 检测必需的移动端前置条件

对于移动端系列（android、ios、expo、react-native、flutter），在独立模式下，VoIP 推送不可或缺——没有它，漏接的来电就不会响铃。检测已接入的内容，以便对应系列的 -calls 技能了解需要添加什么以及可以跳过什么：

Android：

• Firebase Cloud Messaging — 检查 app/ 中是否有 google-services.json，以及 app/build.gradle{.kts} 中是否有 id("com.google.gms.google-services")
• 服务注册 — 检查 AndroidManifest.xml 中是否有 <service android:name=".YourFirebaseMessagingService" ...>
• ConnectionService — 检查 AndroidManifest.xml 中是否有 android.permission.MANAGE_OWN_CALLS 和 BIND_TELECOM_CONNECTION_SERVICE
• 前台服务类型 — 检查是否有 <service android:foregroundServiceType="phoneCall|microphone|camera">（Android 14+ 若没有 phoneCall，会静默崩溃）

iOS：

• CallKit — 检查源代码中是否有 import CallKit，以及某处是否配置了 CXProvider
• PushKit — 检查是否有 import PushKit 和 PKPushRegistry 监听器（用于注册 VoIP 推送令牌）
• 功能 — 检查 Info.plist 和 entitlements 中是否有包含 voip、audio 和 remote-notification 的 Background Modes
• Info.plist 中的麦克风和摄像头使用说明字符串

React Native：

• package.json 中是否有 react-native-callkeep（CallKit + ConnectionService 桥接）
• 是否有 @react-native-firebase/messaging（Android）和 PushNotificationIOS 配置
• 是否有用于 iOS VoIP 推送令牌的 react-native-voip-push-notification

Flutter：

• pubspec.yaml 中是否有 flutter_callkit_incoming，或是否有连接到原生 CallKit/ConnectionService 的平台通道桥接
• 是否有用于 FCM 的 firebase_messaging
• 原生 Info.plist 和 AndroidManifest.xml 条目（Flutter 不会自动添加这些内容）

说明哪些内容已接入，哪些内容缺失。对应系列的 -calls 技能会补上缺失部分，不会假定这些内容已经存在。

步骤 5 — 展示计划并征得批准

在进行任何写入操作前，向用户明确展示：

• 将安装哪些软件包
• 将创建、修改或保持不变的文件
• 呼叫触发器将放置在哪里（注明文件路径）
• 呼叫日志将放置在哪里（如果选择了上文的选项 3，则注明“跳过”）
• 对于移动端：将添加哪些 VoIP 推送相关内容（FCM 服务、CallKit 提供程序、前台服务注册、清单权限、Info.plist 条目）
• 用户必须手动完成、而技能无法完成的事项（Android：在 Firebase 控制台中启用 FCM；iOS：将 VoIP Services 证书添加到 App Store Connect；Flutter：如果 minSdkVersion 低于平台最低要求，则提高该值）

等待用户明确批准。然后加载对应系列的 -calls 技能并运行其脚手架。

第 6 步 — 移交给对应平台系列的技能

从你的上下文中加载匹配的技能：

检测到的平台系列	要加载的技能
reactjs / nextjs / react-router / astro	cometchat-react-calls
expo / react-native	cometchat-native-calls
angular	cometchat-angular-calls
android + android_version === "v5"	cometchat-android-v5-calls
android + android_version === "v6"	cometchat-android-v6-calls
flutter + flutter_version === "v5"	cometchat-flutter-v5-calls（现有）
flutter + flutter_version === "v6"	cometchat-flutter-v6-calls（现有）
ios	cometchat-ios-calls

传递收集到的上下文：mode（第 3.0 步中的 ringing | session）、独立集成还是增量集成（第 1 步）、触发器位置（第 3.1 步）、日志位置，以及移动端前置条件状态。

对应平台系列的技能会加载匹配模式的参考资料作为主要蓝图：

mode	在对应平台系列的技能中加载的参考资料
ringing（1 对 1 用户通话）	references/ringing-integration.md（Android V5：名称相同）
session（会议室 URL，无聊天侧信令）	references/call-session.md（Android V5：references/join-session.md）

此外——如果收集到的上下文中 groupCalls === true（用户提到了“群组通话”“团队会议”“临时讨论”，或在第 3.1 步选择了 group 作为通话目标），还要加载对应平台系列技能中的 references/group-calls.md。群组通话使用的信令通道与 1 对 1 响铃不同——它们会广播自定义的 "meeting" 消息，而不是 CometChat.initiateCall。如果只加载 ringing-integration.md，生成的代码虽然能用于 1 对 1 通话，但会导致自定义 UI 接收端的群组通话静默失效。所有 8 个平台系列都提供 group-calls.md 参考资料。有关其底层语义，请参阅上面的第 3.0 步说明。

对应平台系列的技能负责编写代码；此调度器不负责。

如果对应平台系列的技能尚未加载到 Agent 的上下文中（即用户在 v4.1 之前安装了 @cometchat/skills，之后从未重新运行 npx @cometchat/skills add --family <family>），请告知用户一次：

“我刚刚已将 {family} 通话技能安装到你的工作区。请重新运行 /cometchat-calls 以继续——你的配置已保存在 .cometchat/config.json 中，因此下次运行会从代码生成开始，无需再次询问放置位置。”

与聊天调度器相同的热重载限制：Agent 会在会话开始时记录技能集，不会在会话中途重新加载。继续当前会话就意味着根据训练记忆编写通话代码——而对应平台系列的技能明确禁止这样做。

第 7 步 — 验证

对应平台系列的技能编写完代码后，运行：

npx @cometchat/skills-cli verify --calls --json

（验证器标志 --calls 随此调度器一同加入 CLI 2.4.0；它会检查双 SDK 初始化、IncomingCall 根挂载、移动端 VoIP 推送接线，以及用户选择的通话触发器和日志位置。）

如果验证通过，就引导用户进入迭代菜单——形式与聊天调度器第 7 步相同，但提供通话专属选项：

• 添加功能（录制、屏幕共享、画中画、通话内聊天、自定义 UI）
• 自定义通话界面 / 参与者列表 / 控制面板
• 设置生产环境身份验证（由服务器生成令牌，通话流程中不使用 Auth Key）
• 运行诊断

硬性规则（每个按平台系列划分的 -calls 技能都必须遵守）

以下是面向生产环境、不可妥协的要求。调度器会在步骤 5 的计划中检查这些要求，并由各平台系列技能负责写入：

1. 双 SDK 契约。 Chat SDK 执行 initiateCall（发送 MessageType.CALL）；Calls SDK 执行 joinSession。两者不可互换。Android 技能会首先强调这一点——基于多平台 CometChat 数据训练的 Agent 可能会混淆 com.cometchat.chat.core.Call 和 com.cometchat.chat.models.Call，写出能编译却会悄无声息地出错的代码。
2. 在独立模式下接入 VoIP 推送，而不是只写在文档中。 CallKit + PushKit（iOS）、ConnectionService + FCM 高优先级推送（Android）、react-native-callkeep（RN）、flutter_callkit_incoming（Flutter）。仅有文档还不够——没有可用的推送，来电就不会响铃。
3. 正确处理前台／后台生命周期。 Android 14+ 上，持续通话若使用了错误的 foregroundServiceType，会导致应用悄无声息地崩溃；iOS 要求通过 CallKit 报告后台音频。相关内容必须写入 -calls 技能正文，而不能只放在“另请参阅”中。
4. 通话流程使用服务端签发的身份验证令牌。 生产环境的通话流程必须使用身份验证令牌，绝不能使用 Auth Key。技能会检测现有的令牌端点（方式与聊天调度器相同），并使用 loginWithAuthToken()。
5. 挂断时清理。 摄像头指示灯常亮／麦克风持续启用，是典型的“开发环境看起来正常，审核却失败”问题。每个平台系列技能都必须包含明确的资源释放清单。
6. 附带说明的权限请求。 麦克风、摄像头、屏幕录制（平台支持时）和通知。四项权限都必须提供用途说明字符串。
7. 独立模式下将 IncomingCall 挂载在应用根节点。 不要挂载在聊天界面上——通话就是整个产品，监听器必须始终处于活跃状态。
8. 用户要求“仅使用 SDK”时，遵从其要求（ENG-35711）。 如果开发者明确要求使用 Calls SDK，但不使用 UI Kit 组件——例如使用 “纯 SDK”、“不使用 UI Kit 组件”、“自行构建通话界面”、“仅使用 SDK 的方案” 等说法——各平台系列技能就绝不能搭建 CometChatCallButtons、CometChatIncomingCall、CometChatOutgoingCall 或 CometChatOngoingCall。信令使用 Chat SDK CometChat.initiateCall，并使用 Calls SDK joinSession（以及手写按钮／界面）呈现通话界面。绝不能因为“更简单”就悄悄改用 UI Kit 组件——两位测试人员已明确表示这会造成困扰。如果开发者的需求无法在不使用 UI Kit 组件的情况下实现，请明确询问：“这部分需要使用套件的 <CometChatXxx>——可以使用它，也可以选择手写等效实现。您希望采用哪种方式？” 不要替他们做决定。

反模式

1. 不要尝试从此分发器添加 apply-feature calls 调用。 该 CLI 命令是 v4 聊天流程路径——它只会返回 npm 安装命令，仅此而已。此分发器会端到端地完成实际集成。如果用户处于 chat-messaging+voice-video 模式，聊天流程已经运行；只需在此进入增量模式。切勿在此技能中调用 apply-feature calls。
2. 不要加载 cometchat-components 或 cometchat-placement（聊天目录）。 它们是面向聊天的。各平台系列的 -calls 技能有自己的组件列表（CallButtons、IncomingCall、OutgoingCall、OngoingCall、CallLogs）和自己的放置术语（呼叫触发器、日志界面、根监听器）。加载聊天目录会把聊天假设带入通话代码。
3. 不要询问聊天原型问题（“消息应用 / Marketplace / SaaS / …”）。这种分类针对的是聊天所在的位置。通话放置关注的是呼叫触发器所在的位置 + 日志所在的位置 + 是否必须使用 VoIP 推送。术语和建议都不同。
4. 独立模式下不要跳过 VoIP 推送，即使用户说“我稍后再添加”。没有来电响铃的通话算不上产品。若未接入 VoIP 推送（或至少完成脚手架搭建，并在通话屏幕上显示清晰的 TODO 和红色横幅警告），分发器会拒绝独立模式脚手架。
5. 不要混用 V5 和 V6 版本组（Android、Flutter）。Calls SDK 的坐标不同——V5 Android 将 calls-sdk-android 作为单独的 Cloudsmith 依赖发布；V6 则将通话功能并入统一的 chatuikit-{compose,kotlin}-android 软件包。Flutter 也一样。请从 .cometchat/config.json 读取 android_version / flutter_version，并路由到匹配的版本组技能。

权威参考资料

各平台系列的 -calls 技能会引用以下来源。分发器本身不编写代码；编写代码的是各平台系列的技能。要确认技能针对的 SDK 签名，请检查各平台系列已发布的 SDK 工件 + 公开文档（这些是事实来源——早期草稿曾指向本地 ~/Downloads/calls-sdk/ 克隆，但该目录已不存在；请改用已安装/已发布的软件包）：

• Android V5： com.cometchat:calls-sdk-android:5.x（反编译 Maven AAR，或使用 javap 检查 Gradle 缓存中的类）+ 文档。17 个子主题已归入 cometchat-android-v5-calls/references/{recording,screen-sharing,picture-in-picture,background-handling,voip-calling,audio-controls,video-controls,participant-management,custom-ui,in-call-chat,call-logs,session-settings,event-listeners,join-session,ringing-integration,setup}.md。
• iOS V5： CometChatCallsSDK 5.x——解析后的框架中的 .swiftinterface（SPM 的 .build/artifacts/… 或 CocoaPods 的 Pods/…；增量集成时，它作为内置依赖随 CometChatUIKitSwift 一起提供）+ 文档。
• JavaScript（Web）： @cometchat/calls-sdk-javascript@5——软件包 .d.ts（node_modules/@cometchat/calls-sdk-javascript/dist/index.d.ts）+ 文档。
• React Native： @cometchat/calls-sdk-react-native@5——软件包 .d.ts + @cometchat/calls-lib-webrtc（Cloudsmith）+ 文档。
• Flutter： cometchat_calls_sdk（V5：配套使用 cometchat_calls_uikit:^5.0；V6：并入 cometchat_chat_uikit:^6.0）——pub 缓存中的源代码，以及 cometchat-flutter-v5-calls / cometchat-flutter-v6-calls 技能（已依据该源代码审核）。
• Angular： 在 Angular Inputs/Outputs 中封装相同的 JS Calls SDK（@cometchat/calls-sdk-javascript）——通过 @cometchat/chat-uikit-angular 的 .d.ts 和 JS SDK 的 .d.ts 进行核验。

两种调用模式（响铃 + 会话）——以及工具包为响铃预置的 UI

命名说明（ENG-35699 后续说明）： 本节下方将三行分别标记为“标准”“响铃”和“通话会话”，但从架构上看只有两种模式：响铃（由信令驱动）和会话（由 URL 驱动）。“标准”是工具包为响铃预置的 UI（使用 <CometChatCallButtons> + <CometChatIncomingCall>），并非第三种架构模式。上方的第 3.0 步提示词询问响铃还是会话——这是关键决策。“标准”行是在响铃模式中最常见的渲染方式。

CometChat 支持两种底层通话工作流；下表仅为路由目的，将响铃拆分为“标准（工具包预置 UI）”和“响铃（基于信令的自定义 UI）”：

行	底层模式	驱动方式	适用场景	各系列参考资料
标准	响铃	UI Kit（CometChatCallButtons + CometChatIncomingCall）	80% 的场景——使用预置 UI 的聊天驱动通话	各系列的 SKILL.md 中均有介绍
响铃（自定义 UI）	响铃	Chat SDK 通话实体 + Calls SDK 会话	基于 CometChat 信令构建自定义来电／去电 UI	references/ringing-integration.md
通话会话	会话	直接调用 Calls SDK 的 joinSession（无响铃）	会议室 URL、计划通话、会议室	references/call-session.md

除非用户明确提出“自定义来电 UI”（→ 响铃自定义模式）或“会议链接／使用 sessionId 加入”（→ 通话会话模式），否则响铃默认采用标准渲染方式。第 4 层用例可体现用户需要的模式——广播和团队碰头会使用通话会话；远程医疗、市场平台和客服支持使用标准模式或响铃自定义模式。

用例集成模式（第 4 层）

如果用户清楚描述了其产品，请引导至匹配的用例参考资料，以获取针对性的 CallSettings + UX + 合规提示：

• 远程医疗／虚拟问诊 → references/use-case-telehealth.md — 服务提供者／患者流程、双方同意录音、等候室、HIPAA 说明
• 市场平台（买家 ↔ 卖家） → references/use-case-marketplace.md — 不透明 UID、有时限的访问权限、防欺诈启发式规则
• 客户支持／服务台 → references/use-case-support.md — Agent 队列、自动录音以供 QA、通话后的 CSAT
• 广播／网络研讨会／市民大会 → references/use-case-broadcast.md — 锁定 SIDEBAR、参会者默认静音、举手提问、支持 100 人以上的 RTMP 桥接
• 团队碰头会／站会／协作 → references/use-case-team.md — TILE 布局、自愿加入、录音自动发布到频道

每份用例文档都涵盖端到端流程 + 推荐的 CallSettings + 基于角色的 UI + 验证清单。将这些内容应用于各系列的 -calls 技能之上，不要重复架构工作。

迁移指南

对于升级的客户，或希望在现有聊天安装基础上增加通话功能的客户，每个系列的通话技能都包含：

• references/migration-v4-to-v5.md — Calls SDK v4 → v5（可直接替换；v5 API 支持细粒度事件监听器和更简单的初始化）
• references/add-calls-to-existing-chat.md — 在现有聊天界面上增量集成（初始化顺序、登录顺序、IncomingCall 挂载、服务端推送设置）

请引用正确的系列。Web 参考资料（cometchat-react-calls）是 migration-v4-to-v5 的权威文档；其他系列的配套文档仅补充各系列特有的差异。

服务端推送模板（Tier 3）

VoIP 推送接入因平台而异。三个标准模板位于各平台系列的 references/ 目录下：

• iOS APNs PushKit（.p8 令牌认证）— cometchat-ios-calls/references/server-apns-pushkit.md
• Android FCM HTTP v1（仅数据，优先级 HIGH）— cometchat-android-v5-calls/references/server-fcm-voip.md（V6 对应版本使用 Compose IncomingCallActivity）
• Web Push VAPID（尽力而为的浏览器来电提醒）— cometchat-react-calls/references/server-web-push-vapid.md（对应的 Angular 版本）

混合平台（RN、Flutter）提供 references/server-push-bridge.md，根据 Platform.OS / Platform.is{iOS,Android} 转到相应的标准模板。

此分发器不涵盖的内容

• 实际代码。 各平台系列的 -calls 技能负责编写集成代码。此分发器负责路由。
• AI Agent 或自带 Agent 的工作流。 这是完全不同的使用场景，不在范围内；顶层 cometchat 分发器的 Step 3.0 会将这些请求路由到文档。
• 通话审核功能（征得同意后录音的提示词、通话内聊天的脏话过滤等）。与聊天分发器的情况相同——审核功能仅限控制面板配置。
• 通话分析仪表板——CometChat 控制面板会显示这些数据，无需进行集成。

返回聊天分发器的说明

如果用户直接调用了 /cometchat-calls，但项目尚未进行任何集成（没有 .cometchat/config.json，也没有聊天界面），并且他们误选了增量模式，请重定向：

“看起来你还没有集成 CometChat。对于以通话为主的应用，这没问题——我现在会运行独立通话流程。如果你还想添加聊天，请先运行 /cometchat 设置聊天，然后再回来添加通话。”

不要从这里自动路由到 cometchat/SKILL.md——由用户决定哪个功能是主流程（这里的“调用”也算双关）。