@tencentcloud/sdk-mcp 1.7.3 → 1.7.4

package/resource/knowledge/callkit/preset/harmonyos/api.md

@@ -0,0 +1,362 @@
+## 简介
+
+音视频通话功能通过 `CallStore` 实现用户之间的实时音视频互动。`CallStore` 提供了一套全面的 API 来管理整个通话生命周期。 在接入 `CallStore` 时，请务必了解以下运行时特性：
+- **异常处理（Error Handling）**：主动调用 API（如 `calls`）时，若因参数校验或状态冲突等导致调用本身失败，通常会以异步抛出错误事件或返回错误码的形式通知。网络或远端异常也会通过 `onCallEnded` 携带错误原因下发。
+
+- **线程模型与释放**：所有的状态更新（`CallState`）和事件回调（`CallEvent` / `CallEventListener`）通常**保证在主线程（Main Thread）触发**，可直接用于刷新 UI。全局单例模式下，请务必在组件销毁时（如 `deinit` / `onDestroy`）反注册监听器，避免内存泄漏。
+
+   > **重要：**
+   >
+   > 请在 SDK 初始化成功后，通过 **shared** 单例获取 `CallStore` 实例，不要尝试直接初始化，否则将无法接收通话状态更新。
+   >
+
+   > **说明：**
+   >
+   > 通话状态更新通过 **state** 发布者传递。订阅它以接收通话数据的实时更新。
+   >
+
+   > **警告：**
+   >
+   > 请确保在通话结束后正确处理 UI 状态，避免出现界面异常。
+   >
+
+## 功能特性
+- **发起音视频通话**：支持向单个或多个用户发起音频通话或视频通话，可配置超时时间、自定义数据等参数。
+
+- **接听/拒绝音视频通话**：收到来电邀请时，可选择接听或拒绝。
+
+- **挂断音视频通话**：结束当前正在进行的音视频通话。
+
+- **群组通话管理**：支持加入已存在的群组通话，或在通话中邀请其他用户加入。
+
+- **通话记录管理**：查询最近的通话记录（支持分页），删除指定的通话记录。
+
+- **事件驱动架构**：提供通话开始、收到邀请、通话结束等事件监听。
+
+- **状态订阅**：实时订阅当前通话状态，包括参与者列表、音量信息、网络质量等。
+
+## 可订阅数据
+
+**CallState** 的字段描述如下：
+| <strong>属性名</strong> | <strong>类型</strong> | <strong>描述</strong> |
+| --- | --- | --- |
+| activeCall | CallInfo | 当前活跃的通话信息。<br>【生命周期约定】：在触发 <code>onCallEnded</code> 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 <code>CallInfo.result</code> 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 <code>CallStore</code> 相关状态进行手动清理。 |
+| recentCalls | [CallInfo] | 最近通话记录列表。<br><strong>注意：</strong><br>每次调用 <code>queryRecentCalls</code> 后，该状态当前表现为<strong>覆盖更新</strong>，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。 |
+| cursor | String | 分页游标，用于查询更多通话记录。 |
+| selfInfo | CallParticipantInfo | 当前用户自身信息。 |
+| allParticipants | [CallParticipantInfo] | 当前通话所有参与者列表。 |
+| speakerVolumes | [String: Int] | 参与者音量信息，key 为用户 ID，value 为音量值。 |
+| networkQualities | [String: NetworkQuality] | 参与者网络质量信息，key 为用户 ID，value 为网络质量。 |
+
+## API 列表
+
+|**函数名**|**描述**|
+|---------|---------|
+|shared|获取 CallStore 单例实例。|
+|callEventPublisher|通话事件发布者。|
+|calls|发起通话。|
+|accept|接听通话。|
+|reject|拒绝通话。|
+|hangup|挂断通话。|
+|join|加入群组通话。|
+|invite|邀请用户加入通话。|
+|queryRecentCalls|查询最近通话记录。|
+|deleteRecentCalls|删除通话记录。|
+
+### 获取实例
+
+#### shared
+
+获取 CallStore 单例实例。
+
+### 观察状态和事件
+
+#### callEventPublisher
+
+通话事件发布者。
+
+### 通话操作
+
+#### calls
+
+向指定用户发起音频或视频通话，支持单人通话和多人通话。
+``` ets
+calls(
+  participantIds: string[],
+  mediaType: CallMediaType,
+  params: CallParams | undefined,
+): Promise<void> {
+  return this.impl.calls(participantIds, mediaType, params)
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|participantIds|[String]|被呼叫者 ID 列表，支持单人或多人。|
+|mediaType|CallMediaType|通话媒体类型（音频/视频）。|
+|params|CallParams?|通话参数配置。|
+
+#### accept
+
+接听通话。收到来电邀请时调用此方法接听通话。
+``` ets
+accept(): Promise<void> {
+  return this.impl.accept()
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+#### reject
+
+拒绝通话。收到来电邀请时调用此方法拒绝通话。
+``` ets
+reject(): Promise<void> {
+  return this.impl.reject()
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+#### hangup
+
+挂断并结束当前正在进行的通话。
+``` ets
+hangup(): Promise<void> {
+  return this.impl.hangup()
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+#### join
+
+使用特定的 Call ID 加入一个正在进行中的群组通话。
+``` ets
+join(callId: string): Promise<void> {
+  return this.impl.join(callId)
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|callId|String|要加入的通话 ID。|
+
+#### invite
+
+在通话进行中邀请其他用户加入。
+``` ets
+invite(
+  participantIds: string[],
+  params: CallParams | undefined,
+): Promise<void> {
+  return this.impl.invite(participantIds, params)
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|participantIds|[String]|被邀请者 ID 列表。|
+|params|CallParams?|通话参数配置。|
+
+### 通话记录
+
+#### queryRecentCalls
+
+查询最近的通话记录。
+【当前限制】：目前查询结果每次都会覆盖（重置） `state.recentCalls` 列表，而不是自动追加。
+``` ets
+queryRecentCalls(cursor: string, count: number): Promise<void> {
+  return this.impl.queryRecentCalls(cursor, count)
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|cursor|String|分页游标，首次查询时传空字符串。|
+|count|UInt|查询数量。|
+
+#### deleteRecentCalls
+
+删除指定的通话记录。
+``` ets
+deleteRecentCalls(callIdList: string[]): Promise<void> {
+  return this.impl.deleteRecentCalls(callIdList)
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|callIdList|[String]|要删除的通话 ID 列表。|
+
+## 数据结构
+
+### CallMediaType
+
+通话媒体类型，用于指定发起音频通话还是视频通话。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|audio|1|音频通话。|
+|video|2|视频通话。|
+
+### CallEndReason
+
+通话结束原因，用于标识音视频通话是如何结束的（正常挂断、拒绝、超时等）。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|unknown|0|未知原因。|
+|hangup|1|正常挂断。|
+|reject|2|拒绝接听。|
+|noResponse|3|无响应。|
+|offline|4|对方离线。|
+|lineBusy|5|对方忙线。|
+|canceled|6|通话被取消。|
+|otherDeviceAccepted|7|其他设备已接听。|
+|otherDeviceReject|8|其他设备已拒绝。|
+|endByServer|9|后台结束通话。|
+
+### CallDirection
+
+通话方向，用于标识通话是呼入、呼出还是未接来电。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|unknown|0|未知。|
+|missed|1|未接来电。|
+|incoming|2|呼入。|
+|outgoing|3|呼出。|
+
+### CallParticipantStatus
+
+通话参与者状态，用于标识参与者当前是等待中还是已接听。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|none|0|无状态（未在通话中）。|
+|waiting|1|等待中（呼叫中/被呼叫中）。|
+|accept|2|已接听。|
+
+### CloudRecordPolicy
+
+音视频通话的云端录制策略，用于配置某次通话是否开启云端录制。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|followConsoleConfig|0|跟随控制台的全局配置（默认）。|
+|enable|1|开启云端录制，覆盖控制台配置。|
+|disable|2|关闭云端录制，覆盖控制台配置。|
+
+### CallEventListener
+
+通话事件，用于接收通话过程中的各种事件通知。
+
+**方法**
+
+|**方法名**|**说明**|
+|---------|---------|
+|onCallStarted|通话事件开始启动的回调。<br>时机说明：它表示“当前已经成功进入通话流程（如发起了 `calls` 并被内部接受）”，但**并不表示音视频房间已经接通或建立**。建议仅用于做最初始的界面跳转（主叫侧）。|
+|onCallReceived|收到新通话邀请的回调。<br>字段建议：事件参数仅透传 `callId`、`mediaType` 和 `userData`。如果需要读取邀请人、房间 ID 或绑定的群组 ID 等全量信息，请在收到该事件后通过 `state.activeCall` 读取。|
+|onCallEnded|通话统一结束事件回调。<br>场景说明：无论是接通后挂断、未接听超时、被远端取消，还是其他设备已接听，都会最终触发此事件。开发者必须通过参数中的 `reason` 来判断具体的原因以展示对应的 UI 文案或进行分支处理。<br>获取通话时长：该事件的参数中不包含通话时长字段。如需获取通话时长，请在收到此回调时通过 `state.activeCall.duration` 读取，单位为秒。通话接通后 SDK 内部会每秒递增该值；通话结束时 `activeCall` 不会被立即置空，因此可在本回调中安全读取。|
+|onSuggestSwitchToCellular|当系统检测到 WiFi 质量较差并建议切换到蜂窝网络时触发的回调。|
+
+### CallParams
+
+通话参数配置，用于发起音视频通话时设置房间 ID、超时时间、自定义数据等参数。
+| <strong>属性</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| roomId | String | TRTC 房间 ID（CallStore 的媒体流管理使用了腾讯云 TRTC 服务）。可选参数。<br>不传时由服务端自动生成；如果业务需要指定或复用 TRTC 房间，可传入指定的字符串。 |
+| timeout | Int | 振铃超时时间（秒）。可选参数。<br>仅控制从发起呼叫（<code>calls</code>）到接听的未接听超时阶段。对已接通后的通话或 <code>invite</code> 操作不生效。<br>设为0时，将使用服务端默认值（30s）。 |
+| userData | String | 呼叫时附带的自定义透传数据。可选参数。<br>该数据主要通过被叫端的 <code>onCallReceived</code> 事件暴露给业务侧读取。<br><strong>注意：</strong><br>它不会进入长期的 <code>CallInfo</code> 状态，也不会被持久化到通话记录中。建议传入简短的 JSON 字符串。 |
+| chatGroupId | String | 腾讯云 IM 的群组 ID。可选参数。<br>仅在“群聊发起的通话”场景下需要传入，传入后系统会将信令路由并把该通话关联至此群组的通话记录，用于在该群聊中发送通话开始/结束等状态消息，以及在通话过程中邀请群成员加入。<br>一对一通话、或非固定群组的临时多人通话，请务必留空。<br><strong>注意：</strong><br>该字段在首次 <code>calls</code> 时生效，后续 <code>invite</code> 传参无法更改此通话绑定的群组。 |
+| isEphemeralCall | Bool | 无痕通话。可选参数。<br>设为 <code>true</code> 时，本次通话结束后不再产生通话消息，常见场景：1v1聊天中发起通话，不希望显示通话消息。 |
+| cloudRecordPolicy | CloudRecordPolicy | 本次通话的云端录制策略。生效前提是已经在控制台开通相关能力。<br>- followConsoleConfig（默认）：跟随控制台的全局配置。<br>- enable：强制开启云端录制，覆盖控制台的全局配置。<br>- disable：强制关闭云端录制，覆盖控制台的全局配置。 |
+| offlinePushTitle | string | 离线推送通知标题。<br>非空时覆盖默认标题（登录用户昵称）。 |
+| offlinePushDescription | string | 离线推送通知描述。<br>非空时覆盖默认描述。 |
+
+### CallParticipantInfo
+
+通话参与者信息，包含用户 ID、昵称、头像、参与状态、麦克风/摄像头开关状态等。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|id|String|用户 ID。|
+|name|String|用户昵称。|
+|avatarURL|String|用户头像 URL。|
+|remark|String|好友备注。|
+|status|CallParticipantStatus|参与者状态。|
+|isMicrophoneOpened|Bool|麦克风是否开启。|
+|isCameraOpened|Bool|摄像头是否开启。|
+
+### CallInfo
+
+通话信息，包含通话 ID、房间 ID、发起者、被邀请者、媒体类型、通话方向、开始时间、时长等完整信息。
+| <strong>属性</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| callId | String | 通话 ID。 |
+| roomId | String | 房间 ID。 |
+| inviterId | String | 发起者 ID。 |
+| inviteeIds | [String] | 被邀请者 ID 列表。 |
+| chatGroupId | String | Chat 群组 ID。 |
+| mediaType | CallMediaType? | 通话媒体类型。<br><strong>注意：</strong><br>在早期事件阶段、未知类型，或历史通话记录（recent calls）未完整回填该字段时可能为空（null / nil），业务需注意可选解包。 |
+| result | CallDirection | 通话方向/记录类型（如呼入、呼出、未接）。<br><strong>注意：</strong><br>这不代表通话挂断的具体原因，结束原因。 |
+| startTime | TimeInterval | 通话真正开始（接通）的时间戳。(单位：毫秒)。 |
+| duration | TimeInterval | 通话时长（秒）。 |
+
+### CallState
+
+通话状态数据，管理当前通话的实时数据状态。
+| <strong>属性</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| activeCall | CallInfo | 当前活跃的通话信息。<br>【生命周期约定】：在触发 <code>onCallEnded</code> 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 <code>CallInfo.result</code> 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 <code>CallStore</code> 相关状态进行手动清理。 |
+| recentCalls | [CallInfo] | 最近通话记录列表。<br><strong>注意：</strong><br>每次调用 <code>queryRecentCalls</code> 后，该状态当前表现为<strong>覆盖更新</strong>，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。 |
+| cursor | String | 分页游标，用于查询更多通话记录。 |
+| selfInfo | CallParticipantInfo | 当前用户自身信息。 |
+| allParticipants | [CallParticipantInfo] | 当前通话所有参与者列表。 |
+| speakerVolumes | [String: Int] | 参与者音量信息，key 为用户 ID，value 为音量值。 |
+| networkQualities | [String: NetworkQuality] | 参与者网络质量信息，key 为用户 ID，value 为网络质量。 |
+
+## 使用示例
+``` ets
+import AtomicXCore
+// 发起视频通话
+CallStore.shared.calls(participantIds: ["mike"], mediaType: .video, params: nil) { code, message in
+}
+```

package/resource/knowledge/callkit/preset/harmonyos/integration.md

@@ -0,0 +1,322 @@
+本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。
+
+## 准备工作
+
+### **环境要求**
+- 集成开发环境：6.0.0.858 或以上。
+
+- 手机操作系统：HarmonyOS 5.0.5 或以上。
+
+- API Version：17 或以上。
+
+### **开通服务**
+
+在使用腾讯云提供的音视频服务前，您需要前往控制台，为应用开通音视频服务。具体步骤参见 开通服务。开通服务后，请记录 `SDKAppID` 和 `SDKSecretKey` 在后续的步骤（登录）中会用到。
+
+## 快速接入
+
+### 步骤1：导入组件
+
+2. 在您的工程 `entry` 的 `oh-package.json5` 文件中，添加以下插件依赖。
+
+   ``` json
+   "dependencies": {
+       "@tencentcloud/atomicxcore": "^4.2.0",
+       "@tencentcloud/tuicallkit": "file:../../../call",
+   }
+   ```
+
+   > **说明：**
+   >
+   > call 目录可以放在任何位置，只要在 oh-package.json5 中正确设置相对路径即可。
+   >
+
+3. **oh-package.json5** 修改完毕后，执行以下命令，安装本地 TUIKit 组件。示例：
+
+   ``` bash
+   ohpm install
+   ```
+
+   ohpm install 会自动安装所需的依赖库。
+
+   > **注意：**
+   >
+   > - 使用本地集成方案时，如需升级时需要从 GitHub 获取最新的组件代码，覆盖您本地项目的 call 目录。
+   > - 当私有化修改和远端有冲突时，需要手动合并，处理冲突。
+
+### 步骤2：工程配置
+1. 权限配置：您需要在您工程 entry 的 module.json5 的 module 模块中，声明以下所需要的权限：
+
+   ``` json
+   "requestPermissions":[
+     {
+       "name" : "ohos.permission.INTERNET"
+     },
+     {
+       "name" : "ohos.permission.USE_BLUETOOTH"
+     },
+     {
+       "name" : "ohos.permission.GET_BUNDLE_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_NETWORK_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_WIFI_INFO"
+     },
+     {
+       "name" : "ohos.permission.MODIFY_AUDIO_SETTINGS"
+     },
+     {
+       "name" : "ohos.permission.MICROPHONE",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.CAMERA",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.KEEP_BACKGROUND_RUNNING"
+     },
+   ]
+   ```
+2. 模块声明：已有项目集成源码后，需在 build-profile.json5 文件声明模块：
+
+   ``` bash
+    "modules": [
+       {
+         "name": "entry",
+         "srcPath": "./entry",
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       },
+       {
+         "name": "tuicallkit",
+         "srcPath": "../call",  // 根据实际目录调整
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       }
+     ]
+   ```
+3. 将 **TUICallKit** 与应用主窗口（WindowStage）绑定，使整个 App 在启动后即具备全局接听来电与发起通话的能力，无需在业务页面中重复初始化。
+
+   ``` typescript
+   // 您工程的 EntryAbility.ets
+   import { UIAbility } from '@kit.AbilityKit';
+   import { window } from '@kit.ArkUI';
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   export default class EntryAbility extends UIAbility {
+     async onWindowStageCreate(windowStage: window.WindowStage): Promise<void> {
+       windowStage.loadContent('pages/Index');
+       // 把通话 UI 的承载窗口交给 TUICallKit 管理，建立来电监听
+       TUICallKit.createInstance(this.context).attach(windowStage);
+     }
+
+     onWindowStageDestroy(): void {
+       // 解除窗口绑定，释放资源
+       TUICallKit.createInstance(this.context).detach();
+     }
+   }
+   ```
+4. 声明 backgroundModes。在承载通话界面的 UIAbility（通常是 EntryAbility）下，给 module.json5 的 abilities 节点添加 backgroundModes：
+
+   ``` java
+   "abilities": [
+     {
+       "name": "EntryAbility",
+       // ... 其他配置保持不变
+       "backgroundModes": [
+         "audioRecording",
+         "audioPlayback"
+       ]
+     }
+   ]
+   ```
+
+### 步骤3：登录
+
+代码集成完成后，需要完成登录操作，这是**使用 TUICallKit 的关键步骤**。只有在登录成功后，才能正常使用 TUICallKit 的各项功能，因此请仔细检查相关参数配置是否正确：
+
+> **说明：**
+> 在示例代码中，直接进行了登录接口的调用。但在实际项目场景下，强烈推荐**您在完成自己的用户身份验证等相关登录操作后，再调用 TUICallKit 的登录服务**。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配您项目中现有的用户管理和权限控制体系。
+>
+
+【ArkTS】
+``` typescript
+import { LoginStore } from '@tencentcloud/atomicxcore'
+
+try {
+  await LoginStore.shared().login(
+    1400000000,     // 替换为您的 SDKAPPID
+    'userID',       // 替换为您的 UserID
+    'userSig',      // 替换为您的 UserSig
+  );
+  // login success
+} catch (error) {
+  // login error
+}
+```
+
+**登录接口参数说明：**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>sdkAppID</code> | <code>number</code> | 从 <a href="https://console.cloud.tencent.com/trtc">控制台</a> 获取，通常是以 <code>140</code> 或 <code>160</code> 开头的 10 位整数。 |
+| <code>userID</code> | <code>string</code> | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，<strong>请勿使用</strong> <code>1</code>、<code>123</code> <strong>等简单 ID</strong>。 |
+| <code>userSig</code> | <code>string</code> | 用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig。<br><strong>注意：</strong><br>- 开发环境：可以采用本地 <a href="https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/application/entry/src/main/ets/debug/GenerateTestUserSig.ts">GenerateTestUserSig.genTestSig</a> 函数生成 userSig 或者通过 <a href="https://console.cloud.tencent.com/im/tool-usersig">UserSig 辅助工具</a> 生成临时的 userSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig。 |
+
+### 步骤4：设置昵称和头像[可选]
+
+首次登录的用户没有头像和昵称信息，需要通过 `LoginStore` 的 `setSelfInfo` 接口设置个人信息：
+``` typescript
+import { LoginStore, UserProfile, ErrorInfo } from '@tencentcloud/atomicxcore';
+
+try {
+  await LoginStore.shared().setSelfInfo(new UserProfile('userID', 'userName', 'avatarURL'));
+  console.info("setSelfInfo success");
+} catch (error) {
+  const err = error as ErrorInfo;
+  console.error(`setSelfInfo failed [code: ${err.code}] ${err.message}`);
+}
+```
+
+**setSelfInfo 接口参数/返回值说明：**
+| 参数/返回值 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>userProfile</code> | <code>UserProfile</code> | 个人用户信息核心模型，包含：<br>- userID：要设置用户信息的用户 ID。<br>- nickname：昵称信息。<br>- avatarURL：头像链接。 |
+
+### 步骤5：发起通话
+
+拨打方可以通过调用 `calls` 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。`calls` 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。
+``` typescript
+import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
+import { ErrorInfo } from '@tencentcloud/atomicxcore';
+
+try {
+  await TUICallKit.createInstance(getContext(this)).calls(['mike'], CallMediaType.audio);
+  // 成功处理
+} catch (error) {
+  const err = error as ErrorInfo;
+  // 失败处理
+}
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|userIdList|string[]|目标用户的 userID 列表。|
+|mediaType|CallMediaType|通话的媒体类型，例如：视频通话、语音通话。|
+|params?|CallParams|通话扩展参数，例如：房间号、通话邀请超时时间等。|
+
+### 步骤6：接听通话
+
+接听端完成登录后，拨打端发起通话，接收端就可以收到通话邀请，同时伴随铃声和振动。
+
+## AI 助手：知识咨询与代码集成
+
+您在接入视频通话 SDK 过程中，可以通过 MCP 使用 AI 助手，快速完成知识咨询、报错排查和集成代码生成。支持 Web/Android/iOS/Flutter/uni-app/HarmonyOS 等平台，答案基于官方文档。适用于查询 CallKit 组件和无 UI SDK 用法以及集成文档等场景，[立即体验，提出您的第一个问题](https://cloud.tencent.com/document/product/647/129285)。
+
+## 更多功能
+
+### 开启来电横幅
+
+您可以通过调用 `enableIncomingBanner` 接口来开启/关闭来电横幅显示，该功能默认为关闭状态（false）。当被叫端收到来电时，默认展示全屏通话等待界面。启用此功能后，将首先显示一个横幅通知，然后根据需要切换到全屏通话界面。
+
+``` typescript
+import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+TUICallKit.createInstance(context).enableIncomingBanner(true);
+```
+
+**详情：**默认为 false，被叫端收到邀请后默认弹出全屏通话等待界面。开启后先展示一个横幅，然后根据需要拉起全屏通话界面。
+
+### 多人通话
+
+主叫方使用 `calls` 方法发起通话时，若被叫用户列表超过一人，则自动视为群组通话。其他成员可通过 `join` 方法加入该多人通话。
+- **发起多人通话：**使用 `calls` 方法发起通话时，若被叫用户列表（`userIdList`）超过一人，则自动视为群组通话。
+
+   ``` typescript
+   import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
+   import { ErrorInfo } from '@tencentcloud/atomicxcore';
+
+   try {
+     await TUICallKit.createInstance(getContext(this)).calls(['mike','tate'], CallMediaType.audio);
+     // 成功处理
+   } catch (error) {
+     const err = error as ErrorInfo;
+     // 失败处理
+   }
+   ```
+- **加入多人通话：**可使用 `join` 方法加入指定的群组通话。
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   await TUICallKit.createInstance(context).join('your_call_id');
+   ```
+   |参数|类型|说明|
+   |---------|---------|---------|
+   |callId|string|此次通话的唯一标识。|
+
+### 铃声设置
+
+您可通过以下方式设置默认铃声、来电静音模式、离线推送铃声：
+- **设置默认铃声（方式1）：**如果您通过源码依赖 TUICallKit 组件，您可以替换铃声资源文件（[发起呼叫时的铃音](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/call/src/main/resources/rawfile/phone_dialing.m4a)、[接到呼叫时的铃音](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/call/src/main/resources/rawfile/phone_ringing.mp3)）设置默认铃声。
+
+- **设置默认铃声（方式2）：**通过 `setCallingBell` 接口设置被叫端收到的来电铃声。
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   TUICallKit.createInstance(context).setCallingBell('***/callingBell.mp3');
+   ```
+
+   **详情：**这里仅限传入本地文件地址，需要确保该文件目录是应用可以访问的。铃声设置后与设备绑定，更换用户，铃声依旧会生效。如需恢复默认铃声，filePath 传空即可。
+
+   |参数|类型|说明|
+   |---------|---------|---------|
+   |filePath|string|铃声文件的路径。|
+
+- **来电静音模式：**您可以通过 `enableMuteMode` 接口设置静音模式。
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   TUICallKit.createInstance(context).enableMuteMode(true);
+   ```
+
+   **详情：**开启后，收到通话请求，不会播放来电铃声。
+
+## 自定义您的 UI
+
+### 替换图标按钮
+
+您可以直接替换 [src/main/resources/base/media](https://github.com/Tencent-RTC/TUIKit_Harmony/tree/main/call/src/main/resources/base/media) 文件夹下的图标，以确保整个 App 中的图标色调风格保持一致。以下列出了基本的功能按钮，您可以替换对应的图标以适配自己的业务场景。
+
+常用图标文件名列表
+| 图标 | 文件名称 | 说明 |
+| --- | --- | --- |
+|  | icon_dialing.png | 接听来电图标 |
+|  | icon_hangup.png | 挂断通话图标 |
+|  | icon_mute_on.png | 关闭麦克风图标 |
+|  | icon_handsfree.png | 关闭扬声器图标 |
+|  | icon_camera_off.png | 关闭摄像头图标 |
+
+## 常见问题
+
+### oh-package.json5 文件有没有示例配置可以参考？
+
+您可以参考 GitHub TUIKit_Harmony [application](https://github.com/Tencent-RTC/TUIKit_Harmony/tree/main/application) 工程中的 `oh-package.json5` 示例文件。