@tencentcloud/sdk-mcp 1.6.3 → 1.6.5

package/resource/knowledge/livekit/core-sdk/live/uni-app/host-interaction.md

@@ -0,0 +1,323 @@
+**AtomicXCore** 提供了 [CoHostState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState) 核心模块，用于处理**跨房连线**。本文档将指导您如何组合使用该工具，来完成直播场景下连线的完整流程。
+
+## 核心场景
+
+一次完整的“主播连线”通常包含两个核心阶段，其整体流程如下：
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 开播与观看 集成 **AtomicXCore**，并完成 **LiveCoreView** 的接入。
+
+### 步骤2：实现跨房连线
+
+此步骤的目标是让两个主播的画面出现在同一个视图中，我们将使用 [CoHostState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState) 来完成。
+
+#### 邀请方（主播 A）实现
+1. **发起连线邀请**
+
+   当主播 A 在界面上选择目标主播 B 并发起连线时，调用 `requestHostConnection` 方法。
+
+   ``` typescript
+   import { useCoHostState } from "@/uni_modules/tuikit-atomic-x/state/CoHostState"
+
+   const liveID = 'xxx' // 主播 A 的房间 ID
+   //通过 liveID 获取 CoHostState 的实例
+   const { requestHostConnection } = useCoHostState(liveID)
+
+   // 用户点击“连线”按钮，并选择了主播B
+   const inviteHostB = (targetHostLiveId: string) => {
+       requestHostConnection({
+         liveID, // 主播 A 的房间 ID
+         targetHostLiveID: targetHostLiveID, // 主播 B 的房间 ID
+         layoutTemplate: 'HOST_DYNAMIC_GRID', // 选择一个布局模版
+         timeout: 30, // 邀请超时时间
+         success: () => {
+           console.log("连线邀请已发送，等待对方处理...")
+         },
+         fail: (error) => {
+           console.log("邀请发送失败", error)
+           // 可以在这里进行弹窗提示
+         }
+       })
+   }
+   ```
+2. **监听邀请结果**
+
+   通过 `addCoHostListener` 订阅对应的事件，您可以接收到主播 B 的处理结果。
+
+   ``` typescript
+   import { useCoHostState } from "@/uni_modules/tuikit-atomic-x/state/CoHostState"
+   import { onMounted } from 'vue';
+
+   const liveID = 'xxx' // 主播 A 的房间 ID
+   //通过 liveID 获取 CoHostState 的实例
+   const { addCoHostListener } = useCoHostState(liveID)
+
+   onMounted(() => {
+       addCoHostListener(liveID, 'onCoHostRequestAccepted', (event) => {
+         const result = JSON.parse(event)
+         console.log('主播同意了您的连线邀请')
+       })
+       addCoHostListener(liveID, 'onCoHostRequestRejected', (event) => {
+         const result = JSON.parse(event)
+         console.log('主播拒绝了您的连线邀请')
+       })
+       addCoHostListener(liveID, 'onCoHostRequestTimeout', () => {
+         console.log('邀请超时，对方未回应')
+       })
+   })
+   ```
+
+#### 受邀方（主播 B）实现
+1. **接收连线邀请**
+
+   通过 `addCoHostListener` 订阅 `onCoHostRequestReceived` 事件，主播 B 可以监听到来自主播 A 的邀请。
+
+   ``` typescript
+   import { useCoHostState } from "@/uni_modules/tuikit-atomic-x/state/CoHostState"
+   import { onMounted } from 'vue';
+
+   const liveID = 'xxx' // 主播 B 的房间 ID
+   //通过 liveID 获取 CoHostState 的实例
+   const { addCoHostListener } = useCoHostState(liveID)
+
+   onMounted(() => {
+       addCoHostListener(liveID, 'onCoHostRequestReceived', (event) => {
+         const result = JSON.parse(event)
+         console.log('收到连线邀请')
+         // 可以在这里进行弹窗提示
+       })
+   })
+   ```
+2. **响应连线邀请**
+
+   当主播 B 在弹出的对话框中做出选择后，调用相应的方法。
+
+   ``` typescript
+   import { useCoHostState } from "@/uni_modules/tuikit-atomic-x/state/CoHostState"
+   import { onMounted } from 'vue';
+
+   const liveID = 'xxx' // 主播 B 的房间 ID
+   //通过 liveID 获取 CoHostState 的实例
+   const { acceptHostConnection, rejectHostConnection } = useCoHostState(liveID)
+
+   const acceptInvitation = () => {
+       acceptHostConnection({
+         liveID,
+         fromHostLiveId: 'xxx' // 从 onCoHostRequestReceived 事件中获取该数据
+       })
+    }
+
+   const rejectInvitation = () => {
+       rejectHostConnection({
+         liveID,
+         fromHostLiveId: 'xxx' // 从 onCoHostRequestReceived 事件中获取该数据
+       })
+    }
+   ```
+
+### 运行效果
+
+当您集成以上功能实现后，请分别使用主播 A 和主播 B 进行对应操作，运行效果如下，您可以参考下一章节 完善 UI 细节 来定制您想要的 UI 逻辑。
+
+## 完善 UI 细节
+
+您可以通过修改源码的方式，在视频流画面上添加自定义视图，用于显示昵称、头像等信息，或在他们关闭摄像头时提供占位图，以优化视觉体验。
+
+### 实现视频流画面的昵称显示
+
+#### 实现效果
+
+#### 实现方式
+- 创建自定义 UI 覆盖层组件 (`ParticipantOverlay.vue`)
+
+   这个组件是我们的“UI 贴纸”，它只负责根据数据渲染 UI，不关心视频。
+
+  - 在您的 `components` 目录下，创建一个新文件 `ParticipantOverlay.vue`。
+
+  - 将以下代码复制到文件中。
+
+      ``` typescript
+      <template>
+        <view class="overlay-container">
+          <!-- 遍历 seatList，为每个麦位成员创建独立的UI容器 -->
+          <view
+            v-for="participant in seatList"
+            :key="participant.userInfo.userID"
+            class="participant-ui-container"
+            :style="getParticipantStyle(participant)"
+          >
+            <!-- 条件渲染：根据摄像头状态显示不同UI -->
+            <!-- 1. 当摄像头关闭时，显示居中的头像和昵称 -->
+            <view v-if="participant.userInfo.cameraStatus === 'OFF'" class="avatar-placeholder">
+              <image class="avatar-image" :src="participant.userInfo.userAvatar || '/static/default-avatar.png'" mode="aspectFill"></image>
+              <text class="avatar-name">{{ participant.userInfo.userName || participant.userInfo.userID }}</text>
+            </view>
+            <!-- 2. 当摄像头开启时，显示左下角的昵称条 -->
+            <view v-if="participant.userInfo.cameraStatus === 'ON'" class="nickname-bar">
+              <text class="nickname-text">{{ participant.userInfo.userName || participant.userInfo.userID }}</text>
+            </view>
+          </view>
+        </view>
+      </template>
+      <script setup>
+      import { computed } from 'vue';
+      // 1. 接收来自父组件的核心数据：seatList 和 scale
+      const props = defineProps({
+        seatList: {
+          type: Array,
+          default: () => []
+        },
+        scale: {
+          type: Object,
+          default: () => ({ scaleX: 1, scaleY: 1 })
+        }
+      });
+
+      // 2. 定义一个方法来计算每个成员UI容器的精确位置和大小
+      const getParticipantStyle = (participant) => {
+        if (!participant || !participant.region) return {};
+        return {
+          position: 'absolute',
+          left: `${participant.region.x * props.scale.scaleX}px`,
+          top: `${participant.region.y * props.scale.scaleY}px`,
+          width: `${participant.region.w * props.scale.scaleX}px`,
+          height: `${participant.region.h * props.scale.scaleY}px`,
+        };
+      };
+      </script>
+
+      <style scoped>
+      .overlay-container {
+        pointer-events: none;
+      }
+
+      .participant-ui-container {
+        overflow: hidden;
+      }
+      .avatar-placeholder {
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        background-color: #2E323A;
+      }
+      .avatar-image {
+        width: 160rpx;
+        height: 160rpx;
+        border-radius: 80rpx;
+      }
+      .avatar-name {
+        margin-top: 20rpx;
+        font-size: 28rpx;
+        color: #FFFFFF;
+      }
+      .nickname-bar {
+        position: absolute;
+        left: 10rpx;
+        bottom: 10rpx;
+        background-color: rgba(0, 0, 0, 0.5);
+        padding: 4rpx 16rpx;
+        border-radius: 20rpx;
+      }
+      .nickname-text {
+        color: #FFFFFF;
+        font-size: 24rpx;
+      }
+      </style>
+      ```
+- **步骤 2**：在直播间页面中组合所有组件
+
+   这是将视频层和 `UI` 层“叠”在一起的关键步骤，同时需要解决 `nvue` 的布局问题。
+
+  - 打开您的直播间页面文件
+
+  - 按照以下结构和样式进行修改。
+
+      ``` typescript
+      <template>
+        <view class="page-container">
+          <view class="live-container">
+            <!-- 底层：视频渲染层 -->
+            <LiveCoreView
+              :liveID="xxx" // 对应直播间的 liveID
+              :viewType="xxx" // 主播端: PUSH_VIEW, 观众端: PLAY_VIEW
+              class="video-layer"
+            />
+            <!-- 上层：自定义UI覆盖层 -->
+            <ParticipantOverlay
+              :seatList="seatList"
+              :scale="scale"
+              class="ui-layer"
+            />
+          </view>
+          <!-- 页面的其他UI，如底部的操作栏 -->
+          <!-- <view class="bottom-controls">...</view> -->
+        </view>
+      </template>
+
+      <script setup>
+      import { ref, onMounted } from 'vue';
+      import ParticipantOverlay from '@/components/ParticipantOverlay.vue';
+      import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';
+      const liveID = 'xxx' // 当前直播间的 liveID
+      const { seatList } = useLiveSeatState(liveID);
+      const scale = ref({ scaleX: 1, scaleY: 1 });
+
+      onMounted(() => {
+        // 在此获取并设置正确的 scale 值。
+        // 这是保证UI对齐的关键。请根据您的项目实际逻辑实现。
+        // 示例：
+         const { windowWidth } = uni.getSystemInfoSync();
+         const designWidth = 750; // rpx 设计稿宽度
+         scale.value.scaleX = windowWidth / designWidth;
+         scale.value.scaleY = scale.value.scaleX;
+      });
+      </script>
+
+      <style scoped>
+      .page-container {
+        flex: 1;
+        background-color: #000;
+      }
+
+      .live-container {
+        flex: 1;
+        position: relative;
+      }
+      .video-layer,
+      .ui-layer {
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+      }
+
+      .video-layer {
+        z-index: 1;
+      }
+
+      .ui-layer {
+        z-index: 2;
+      }
+      </style>
+      ```
+
+## API 文档
+
+关于 [CoHostState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState) 及其相关类的所有公开接口、属性和方法的详细信息，请您参阅 AtomicXCore 框架的官方 API 文档。本指南使用到的相关 Store 如下：
+
+|**State**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|DeviceState|音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-DeviceState)|
+|CoHostState|主播跨房连线：支持多布局模板（动态网格等），发起 / 接受 / 拒绝连线，连麦主播互动管理。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState)|
+
+## 常见问题
+
+### **为什么发起了连线邀请，对方却没收到？**
+- 请检查 `targetHostLiveID` 是否正确，并且对方直播间处于正常开播状态。
+
+- 检查网络连接是否通畅，邀请信令有30秒的默认超时时间。

package/resource/knowledge/livekit/core-sdk/live/uni-app/integration.md

@@ -0,0 +1,312 @@
+本文档将帮助您使用 **AtomicXCore SDK** 的核心组件 **LiveCoreView**，快速构建一个包含主播开播和观众观看功能的基础直播 App。
+
+## **核心功能**
+
+**LiveCoreView** 是一个专为直播场景设计的轻量级 `UI` 组件，是您构建直播场景的核心，它封装了所有复杂的底层直播技术（例如推拉流、连麦、音视频渲染）。您可以将 LiveCoreView 作为直播画面的“画布”，专注于上层 UI 与交互的开发。
+
+通过下方的视图层级示意图，您可以直观了解 **LiveCoreView** 在直播界面中的位置和作用：
+
+## 准备工作
+
+### 步骤1：开通服务
+
+请参见 开通服务，获取体验版或付费版 SDK。
+
+### 步骤2：在当前项目中导入 AtomicXCore
+1. **安装组件**：打开 [AtomicXCore SDK](https://ext.dcloud.net.cn/plugin) ，单击**下载插件并导入 HBuilderX**，选择需要集成的项目并单击**确定**。
+
+2. **配置工程权限:** 请在应用的 manifest.json 文件的 app-plus > distribute 节点下，确保添加了以下必要的权限：
+
+  - Android 平台（`android` 节点）：在 `permissions` 数组中，请确保包含以下权限：
+
+      ``` json
+      "<uses-permission android:name=\"android.permission.RECORD_AUDIO\" />",
+      "<uses-permission android:name=\"android.permission.CAMERA\"/>"
+      ```
+  - iOS 平台（ios 节点）：在 `privacyDescription` 对象中，请确保包含以下描述：
+
+      ``` json
+      "NSCameraUsageDescription" : "应用需要访问您的相机以进行直播",
+      "NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行直播"
+      ```
+
+      在 `UIBackgroundModes` 数组中，添加 `audio` 以支持后台播放音频。
+
+      ``` json
+      "UIBackgroundModes" : [ "audio" ]
+      ```
+
+### 步骤3：实现登录逻辑
+
+在您的项目中调用 LoginState 中的 login 方法完成登录，**这是使用** `AtomicXCore` **所有功能的关键前提**。
+
+> **重要：**
+>
+> 推荐在您 App 自身的用户账户登录成功后，再调用 LoginState 中的 login 方法，以确保登录业务逻辑的清晰和一致。
+>
+
+``` typescript
+import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
+
+const { login } = useLoginState();
+
+const handleLogin = () => {
+    login({
+      sdkAppID: 1400000001,  // 替换为您的 SDKAppID
+      userID: "test_001",    // 替换为您的 UserID
+      userSig: "xxxxxxxxxx"  // 替换为您的 UserSig
+    })
+ }
+```
+
+**登录接口参数说明：**
+| <strong>参数</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| sdkAppID | number | 从 <a href="https://console.cloud.tencent.com/trtc">控制台</a> 获取，通常是以 <code>140</code> 或 <code>160</code> 开头的 10 位整数。 |
+| userID | string | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，<strong>请勿使用</strong> <code>1</code>、<code>123</code> <strong>等简单 ID</strong>。 |
+| userSig | string | 用于腾讯云鉴权的票据。请注意：<br>- 开发环境：您可以采用本地 <code>GenerateTestUserSig.genTestSig</code> 函数生成 userSig 或者通过 <a href="https://console.cloud.tencent.com/im/tool-usersig">UserSig 辅助工具</a> 生成临时的 UserSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参考 <a href="https://cloud.tencent.com/document/product/647/17275">服务端生成 UserSig</a>。<br>更多信息请参见 <a href="https://cloud.tencent.com/document/product/647/17275">如何计算及使用 UserSig</a>。 |
+
+## 搭建基础直播间
+
+### 步骤1：实现主播视频开播
+
+主播开播流程如下，您只需执行以下几步操作，即可快速搭建主播视频直播。
+
+1. **初始化主播推流的视图**
+
+   在您的主播页中，引入 `LiveCoreView` 组件，将 `viewType` 指定为 `PUSH_VIEW`（推流视图）， 并且为组件绑定当前直播 ID。
+
+   ``` typescript
+   <live-core-view :viewType="PUSH_VIEW" :liveID="xxx"></live-core-view>
+   ```
+2. **打开摄像头和麦克风**
+
+   通过调用 `DeviceState` 的 `openLocalCamera、openLocalMicrophone` 接口打开摄像头和麦克风，**您无需做额外操作，LiveCoreView 会自动预览当前摄像头的视频流**，示例代码如下：
+
+   ``` typescript
+    import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
+    import { onMounted } from 'vue';
+    const { openLocalCamera, openLocalMicrophone } = useDeviceState();
+    onMounted(() => {
+       openLocalMicrophone();
+       openLocalCamera({ isFront: true });
+     })
+   ```
+3. **开始直播**
+
+   通过调用 `LiveListState` 的 `createLive` 接口开始视频直播，完整示例代码如下：
+
+   ``` typescript
+   import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
+
+   const { createLive } = useLiveListState();
+
+   // 开始直播
+   const startLive = () => {
+       createLive({
+         liveInfo: {
+           liveID: 'xxx', // 设置直播的房间 id
+           liveName: 'text', // 设置直播的房间名称
+           seatLayoutTemplateID: 600, // 配置布局模板，默认：600 动态宫格布局
+           keepOwnerOnSeat: true, // 配置主播始终在麦位上
+         },
+         success: () => {
+           console.log('创建直播间成功')
+           //您可以在这里进行页面的跳转
+         },
+         fail: (error) => {
+           console.log('创建直播间失败', error)
+         }
+       });
+     };
+   ```
+
+   `LiveInfo` **参数说明:**
+
+   |**参数名**|**类型**|**属性**|**描述**|
+   |---------|---------|---------|---------|
+   |`liveID`|`string`|必填|直播间的唯一标识符|
+   |`liveName`|`string`|选填|直播间的标题|
+   |`notice`|`string`|选填|直播间的公告信息|
+   |`isMessageDisable`|`boolean`|选填|是否禁言（`true`：是，`false`：否）|
+   |`isPublicVisible`|`boolean`|选填|是否公开可见（`true`：是，`false`：否）|
+   |`isSeatEnabled`|`boolean`|选填|是否启用麦位功能（`true`：是，`false`：否）|
+   |`keepOwnerOnSeat`|`boolean`|选填|是否保持房主在麦位上|
+   |`maxSeatCount`|`number`|选填|最大麦位数量|
+   |`seatMode`|`string`|选填|上麦模式（`'FREE'`：自由上麦，`'APPLY'`：申请上麦）|
+   |`seatLayoutTemplateID`|`number`|必填|麦位布局模板 `ID`|
+   |`coverURL`|`string`|选填|直播间的封面图片地址|
+   |`backgroundURL`|`string`|选填|直播间的背景图片地址|
+   |`activityStatus`|`number`|选填|直播活动状态|
+   |`isGiftEnabled`|`boolean`|选填|是否启用礼物功能（`true`：是，`false`：否）|
+
+4. **结束直播**
+
+   直播结束后，主播可以调用 **LiveListState** 的 `endLive` 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。
+
+   ``` typescript
+   import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
+   import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
+   const { endLive } = useLiveListState();
+   const { closeLocalCamera, closeLocalMicrophone } = useDeviceState();
+
+   const stopLive = () => {
+       endLive({
+         success: () => {
+           // 关闭本地设备
+           closeLocalCamera();
+           closeLocalMicrophone()
+          },
+       });
+   }
+   ```
+
+### 步骤2：实现观众进房观看
+
+观众观看流程如下，通过简单几步操作，即可实现观众观看直播。
+
+1. **实现观众拉流页面**
+
+   在您的观众页中，引入 `LiveCoreView` 组件，将 `viewType` 指定为 `PLAY_VIEW`（拉流视图）， 并且为组件绑定当前直播 ID。
+
+   ``` typescript
+   <live-core-view :viewType="PLAY_VIEW" :liveID="xxx"></live-core-view>
+   ```
+2. **进入直播间观看**
+
+   通过调用 **LiveListState** 的 `joinLive` 接口加入直播，**您无需做额外操作，LiveCoreView 会自动播放当前房间的视频流**，完整示例代码如下：
+
+   ``` typescript
+   import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
+
+   const { joinLive } = useLiveListState();
+
+   // 加入直播
+   const handleJoinLive = () => {
+        joinLive({
+           liveID: 'xxx', // 与主播开播同样的 liveID
+           success: () => {
+             console.log('加入直播间成功')
+             //您可以在这里进行页面的跳转
+           },
+           fail: (error) => {
+             console.log('加入直播间失败', error)
+           }
+        })
+   }
+   ```
+3. **退出直播**
+
+   观众退出直播间时，需要调用 **LiveListState** 的 `leaveLive` 接口退出直播。SDK 会自动停止拉流并退出房间。
+
+   ``` typescript
+   import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
+
+   const { leaveLive } = useLiveListState();
+
+   // 离开直播
+   const exitLive = () => {
+        leaveLive({
+           success: () => {
+             console.log('离开直播间成功')
+             //您可以在这里进行页面的跳转
+           },
+           fail: (error) => {
+             console.log('离开直播间失败', error)
+           }
+        })
+   }
+   ```
+
+### 步骤3：监听直播事件
+
+在观众加入直播间后，您还需要处理一些房间内的“被动”事件。例如，主播主动结束了直播，或者观众因为违规等原因被踢出房间。如果不监听这些事件，观众端 UI 可能会停留在黑屏页面，影响用户体验。
+
+您可以通过订阅 `LiveListState` 提供的 `addLiveListListener` 来实现事件监听。
+``` typescript
+import { useLiveListState } from "@/uni_modules/tuikit-atomic-x/state/LiveListState";
+import { onMounted } from 'vue';
+const { addLiveListListener } = useLiveListState()
+
+onMounted(() => {
+    addLiveListListener('onLiveEnded',
+       (event) => {
+        const res = JSON.parse(event)
+        console.log("直播结束", res)
+        // 在这里处理直播间结束后的相关逻辑，例如关闭当前页面
+      }
+    )
+    addLiveListListener( 'onKickedOutOfLive',
+       (event) => {
+        const res = JSON.parse(event)
+        console.log("被踢出房间", res.reason)
+        // 可以根据被踢出房间的原因进行弹窗提示
+      }
+    )
+})
+```
+
+### 运行效果
+
+集成 **LiveCoreView** 后，您将得到一个纯净的视频渲染视图，它已具备完整的直播业务能力，但没有任何交互 UI。您可以参考下一章节 丰富直播场景 来完善直播场景。
+
+## 丰富直播场景
+
+当您完成了基础的直播功能后，您可以参考以下功能指南来为直播添加丰富的互动玩法。
+
+|**直播功能**|**功能介绍**|**功能 States**|**实现指南**|
+|---------|---------|---------|---------|
+|**实现观众音视频连线**|观众申请上麦，与主播进行实时视频互动。|[CoGuestState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState)|实现观众连线|
+|**实现主播跨房连线**|两个不同房间的主播进行连线，实现互动|[CoHostState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState)|实现主播连线|
+|**添加弹幕聊天功能**|观众可以在直播间发送和接收实时文字消息。|[BarrageState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState)|实现弹幕功能|
+|**构建礼物赠送系统**|观众可以向主播赠送虚拟礼物，增加互动和趣味性。|[GiftState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState)|实现礼物功能|
+
+## API 文档
+
+|**State**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|**LiveListState**|直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveListState)|
+|**DeviceState**|音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-DeviceState)|
+|**CoGuestState**|观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState)|
+|**CoHostState**|主播跨房连线：支持多布局模板（动态网格等），发起 / 接受 / 拒绝连线，连麦主播互动管理。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoHostState)|
+|**GiftState**|礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState)|
+|**BarrageState**|弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState)|
+|**LikeState**|点赞互动：发送点赞，监听点赞事件，同步总点赞数。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LikeState)|
+|**LiveAudienceState**|观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState)|
+|**AudioEffectState**|音频特效：变声（童声 / 男声）、混响（KTV 等）、耳返调节，实时切换特效。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-AudioEffectState)|
+|**BaseBeautyState**|基础美颜：调节磨皮 / 美白 / 红润（0-100 级），重置美颜状态，同步效果参数。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BaseBeautyState)|
+
+## 常见问题
+
+在使用 **AtomicXCore** 这样的原生能力 SDK 时，开发者经常会遇到 uni-app 跨端开发本身的一些共性问题，以下是一些常见问题及其解决方案，可以帮助您规避许多常见的“坑”。
+
+### 跨端兼容性问题
+- 问题：原生组件层级最高，遮挡弹窗。
+
+- 原因：像 `<video>`, `<map>`, `<live-player>` `LiveCoreView` 这类组件，是由原生渲染的，层级永远高于 WebView 渲染的普通组件。
+
+- 解决方案：
+
+  - 使用 `cover-view`：uni-app 提供了 `cover-view` 和 `cover-image`，它们可以覆盖在原生组件之上，但样式支持有限。
+
+  - 切换到 `nvue`：如果页面交互复杂，需要大量元素覆盖在原生组件上，建议将整个页面用 `nvue` 来编写。`nvue` 的所有组件都是原生渲染，不存在层级问题。
+
+### nvue 与 vue 的抉择问题
+- 问题：不知道什么时候该用 `nvue`，什么时候用 `vue`。
+
+- 选型建议：
+
+  - 默认用 `vue`：适合绝大多数业务和 UI 复杂的页面。
+
+  - 当遇到长列表滑动卡顿、复杂动画掉帧、需要覆盖原生组件等性能或层级问题时，再考虑将该页面重构为 `nvue`。直播、地图这类页面是 nvue 的绝佳应用场景。
+
+### 原生能力集成问题
+- 问题：插件调用失败或无响应。
+
+- 解决方案：
+
+  - 必须打包自定义基座：在开发调试原生插件时，不能使用标准基座，必须通过 `HBuilderX` > 运行 > 运行到手机或模拟器 > 制作自定义基座，然后选择这个自定义基座来运行。
+
+  - 检查权限：如本文档“准备工作”中所述，`manifest.json` 必须声明相机、麦克风等权限。
+
+  - 查看原生日志：这是终极调试手段。通过 `Android Studio (Logcat)` 或 `Xcode (Console)` 查看设备的原生日志，通常能发现最直接的错误信息。

package/resource/knowledge/livekit/core-sdk/voice/android/{voice-co-guest-interaction.md → co-guest-interaction.md}

@@ -1,4 +1,4 @@
-**AtomicXCore** 提供了 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) 和 [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html) 模块，用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。本文档将指导您如何使用 `CoGuestStore `和 `LiveSeatStore` 在 `Android` 应用中快速实现语音连麦功能。
+**AtomicXCore** 提供了 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) 和 [LiveSeatStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html) 模块，用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。本文档将指导您如何使用 `CoGuestStore` 和 `LiveSeatStore` 在 `Android` 应用中快速实现语音连麦功能。
 
 ## 核心场景
 
@@ -515,10 +515,10 @@ seatStore.moveUserToSeat("userC",
 
 ### 如何在 UI 上实时刷新麦位信息（例如是否有人、是否静音）？
 
-您应该订阅 `LiveSeatState` 中的 `seatList` 属性，它是一个` List<SeatInfo>` 数组类型的响应式数据，每当数组变化时都会通知您重新渲染麦位列表。遍历此数组，您可以：
+您应该订阅 `LiveSeatState` 中的 `seatList` 属性，它是一个 `List<SeatInfo>` 数组类型的响应式数据，每当数组变化时都会通知您重新渲染麦位列表。遍历此数组，您可以：
 - 通过 `seatInfo.userInfo` 来获取麦位上用户信息。
 
-- 通过 `seatInfo.isLocked `判断麦位是否被锁定。
+- 通过 `seatInfo.isLocked` 判断麦位是否被锁定。
 
 - 通过 `seatInfo.userInfo.microphoneStatus` 判断麦上用户的麦克风状态。