@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/conference/web/virtual-background.md

@@ -0,0 +1,197 @@
+---
+id: conference/virtual-background
+name: 虚拟背景
+product: conference
+platform: web
+tags: [virtual-background, blur, assetsPath, useVirtualBackgroundState]
+platforms: [web]
+related: [conference/device-control, conference/video-layout, conference/beauty-effects]
+api_docs:
+  - title: 虚拟背景
+    url: https://cloud.tencent.com/document/product/647/126935
+---
+
+# 虚拟背景
+
+## 功能说明
+
+虚拟背景负责会议中本地视频的背景增强能力，包括背景虚化、图片替换、模型资源初始化、浏览器支持性检测以及从预览到正式生效的完整链路。与基础美颜相比，它更依赖模型资源、浏览器能力和初始化流程。
+
+## 核心概念
+
+### 角色与操作
+
+| 角色 | 关键操作 | 说明 |
+|------|----------|------|
+| 当前参会人 | 选择背景模式 | 可以切换虚化、图片背景或关闭虚拟背景 |
+| 虚拟背景面板 | 管理模式与预览 | 承载背景模式选择、资源初始化和确认保存入口 |
+| 浏览器 / 模型运行时 | 提供支持能力 | 决定当前环境是否支持虚拟背景以及模型是否可初始化 |
+| 本地视频处理链 | 应用背景效果 | 将保存后的背景设置作用到本地视频流 |
+
+### 事件流
+
+| 阶段 | 参与方 | 关键动作 |
+|------|--------|----------|
+| 支持性检测 | 浏览器 / 客户端 | 先确认当前环境是否支持虚拟背景 |
+| 资源初始化 | 客户端 | 依据 `assetsPath` 等条件初始化背景模型资源 |
+| 效果预览 | 当前参会人 | 选择虚化或图片背景，并在本地画面上实时预览 |
+| 确认保存 | 当前参会人 | 将当前背景设置正式应用到会中视频流 |
+| 降级回退 | 客户端 | 不支持或初始化失败时回退到普通视频能力 |
+
+### 状态与数据
+
+| 数据 / 状态 | 说明 |
+|-------------|------|
+| `isSupported` | 表示当前浏览器是否支持虚拟背景能力 |
+| 初始化状态 | 标识模型资源是否已成功加载并可用 |
+| `assetsPath` | Web 端初始化模型资源时的重要前置条件 |
+| 当前背景模式 | 关闭、虚化、图片替换等模式 |
+| 预览态 / 已保存态 | 区分当前面板中试用效果与真正对外生效的设置 |
+
+### 状态机
+
+```text
+unsupported
+
+idle
+  → checking-support
+  → initializing
+  → previewing
+  → saved
+  → active
+  → cleared
+```
+
+## 前置条件
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+
+**前置状态**：
+- 已阅读 `conference/virtual-background`，明确当前能力的产品边界。
+- 已完成 `conference/login-auth`，确保当前页面具备稳定登录态。
+- 已根据业务流程接入会议上下文；需要房间状态时，优先通过 `conference/room-lifecycle` 统一承接。
+- 当前能力涉及媒体采集、渲染或浏览器权限时，请在 `HTTPS` 或 `localhost` 安全上下文下调试。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **先做支持性检测，再开放设置入口** —— 不支持的环境应直接降级，而不是让用户在无效面板里反复尝试。
+2. **把资源初始化作为显式前置步骤** —— `assetsPath`、模型资源和初始化结果应被明确管理。
+3. **区分预览效果与正式保存结果** —— 让用户确认满意后再真正应用到会中画面。
+4. **准备好不支持场景下的降级方案** —— 对不支持的浏览器应回到普通摄像头画面，而不是让视频链路中断。
+
+### ❌ NEVER
+
+1. **不要跳过初始化直接设置虚拟背景** —— 缺少模型资源时，效果很可能无法生效或表现异常。
+2. **不要默认所有浏览器都支持相同能力** —— 虚拟背景的兼容性明显强依赖浏览器和环境。
+3. **不要把虚拟背景与基础美颜混成同一份无边界的状态** —— 它们都作用于本地视频，但依赖与失败模式不同。
+
+## 代码示例
+### 初始化模型资源并保存虚拟背景效果
+
+```ts
+import { onMounted } from 'vue';
+import { useVirtualBackgroundState } from 'tuikit-atomicx-vue3/room';
+
+const { isSupported, initVirtualBackground, setVirtualBackground, saveVirtualBackground } = useVirtualBackgroundState();
+
+onMounted(async () => {
+  if (!isSupported()) return;
+  await initVirtualBackground({ assetsPath: 'https://cdn.example.com/assets' });
+  await setVirtualBackground({ enable: true, type: 'blur', level: 0.5 });
+  await saveVirtualBackground();
+});
+```
+
+## 调用时序
+```
+完成 login-auth 并准备本地视频
+   │
+   ▼
+调用 isSupported() 检查浏览器能力
+   │
+   ├─ 不支持 → 隐藏入口或走降级文案
+   └─ 支持
+       │
+       ▼
+initVirtualBackground({ assetsPath })
+       │
+       ▼
+setVirtualBackground(...) 做预览
+       │
+       ├─ 用户确认 → saveVirtualBackground()
+       └─ 用户取消 / 关闭 → 回退或关闭背景效果
+```
+
+## 平台特有注意事项
+### 1. `assetsPath` 是虚拟背景能否启动的关键前置条件
+必须先成功初始化 `assetsPath` 对应的模型或资源目录，否则虚拟背景功能无法正常工作。
+
+### 2. 兼容性检查必须放在渲染前
+浏览器对虚拟背景的支持差异明显，建议在页面入口或打开设置面板前先调用 `isSupported()` 做能力判断。
+
+### 3. 虚拟背景比基础美颜更吃性能
+在低性能设备上，虚拟背景更容易带来 CPU / GPU 压力；业务应允许快速关闭，并提供清晰的降级说明。
+
+## 代码生成约束
+### 编译必要条件
+- **通用条件**：见 [login-auth 平台 slice](login-auth.md)。
+- **额外导入**：至少需要导入 `useVirtualBackgroundState`。
+- **运行前提**：浏览器支持该能力、页面处于安全上下文，且 `assetsPath` 可访问。
+
+### 生成规则
+#### MUST（生成时必须包含）
+
+1. **在启用虚拟背景前先做能力检查与初始化** — 否则会出现入口可见但能力不可用的假状态。  
+   **Verify**: 检查是否存在 `isSupported()` 与 `initVirtualBackground(`。
+2. **把预览与最终保存分开处理** — 用户需要有确认生效的动作，而不是一改即永久保存。  
+   **Verify**: 检查是否同时存在 `setVirtualBackground(` 与 `saveVirtualBackground(`。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要跳过 `assetsPath` 初始化直接启用背景能力** — 功能无法正常启动。  
+   **Verify**: 检查是否先调用 `initVirtualBackground({ assetsPath })`。
+2. **不要忽略不支持浏览器的降级路径** — 低兼容环境会直接报错或白屏。  
+   **Verify**: 检查是否存在 `isSupported()` 判断和降级处理。
+
+### 集成检查点
+- 当前 slice 常与 `conference/device-control`、`conference/beauty-effects` 联动。
+- 集成方式通常是新增本地效果设置面板，不需要改动房间生命周期逻辑。
+- 如果业务同时接入美颜和虚拟背景，建议在 UI 和性能策略上给出统一入口与优先级。
+
+## 验证矩阵
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | 已导入 `useVirtualBackgroundState` | 检查 `import` 语句 | 虚拟背景 Hook 可解析 |
+| 2. 静态规则级 | 存在能力检查、初始化、保存链路 | 搜索 `isSupported` / `initVirtualBackground` / `saveVirtualBackground` | 形成完整启用流程 |
+| 3. 运行时级 | 支持浏览器可成功启用背景效果 | 在支持环境打开虚拟背景功能 | 能看到预览并保存效果 |
+| 4. 业务行为级 | 不支持或低性能环境有清晰降级 | 在不支持环境或低性能设备联调 | 页面能正确隐藏入口或提示降级 |
+
+## 排障指南
+
+### 常见问题
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 面板可打开但效果不可用 | 用户能看到背景设置入口，但切换后画面无变化 | 检查浏览器支持性检测和初始化是否真正成功 |
+| 初始化失败 | 选择背景时直接报错或模型资源加载失败 | 检查 `assetsPath`、资源可访问性以及初始化时机是否正确 |
+| 保存后效果丢失 | 当前会议里可见，重新进入面板或再次开会后失效 | 检查预览态和已保存态是否区分维护，并确认初始化完成后再恢复设置 |
+
+### 排障流程
+
+```text
+发现 虚拟背景 相关问题
+├── 第 1 步：确认当前环境是否支持虚拟背景，不支持时应直接走降级路径
+├── 第 2 步：检查 assetsPath 和模型初始化流程是否完整且已成功完成
+├── 第 3 步：确认当前背景设置是否仍停留在预览态，还是已经正式保存到视频流
+└── 第 4 步：若仍异常，再回查 device-control / video-layout / beauty-effects 的衔接是否正确
+```
+
+## 关联知识
+
+- **[conference/device-control](device-control.md)** —— 摄像头是否已准备好会直接影响虚拟背景是否具备可视化预览前提。
+- **[conference/video-layout](video-layout.md)** —— 背景效果最终体现为布局中的本地画面变化。
+- **[conference/beauty-effects](beauty-effects.md)** —— 与虚拟背景同属本地视频前处理，但初始化要求和失败模式不同。

package/knowledge-base/slices/conference/web/webinar-interaction.md

@@ -0,0 +1,206 @@
+---
+id: conference/webinar-interaction
+name: Webinar 举手、上台与弹幕互动
+product: conference
+platform: web
+tags: [webinar, raise-hand, audience, participant, barrage, requestToOpenDevice]
+platforms: [web]
+related: [conference/room-lifecycle, conference/participant-management, conference/room-chat]
+---
+
+# Webinar 举手、上台与弹幕互动
+
+## 功能说明
+
+Webinar 互动负责研讨会房型中的观众举手、主持人审批、观众上台成为嘉宾、设备申请收口以及弹幕互动。它解决的是“观众如何申请发言、主持人如何处理申请、观众区如何低成本互动”，不是普通 Standard 会议的成员管理入口。
+
+Conference Core 中，观众举手本质上是 `requestToOpenDevice({ device: DeviceType.Microphone })`；主持人侧通过 `pendingDeviceApplications` 展示待处理申请，接受时先 `promoteToParticipant()`，再 `approveOpenDeviceRequest()`。
+
+## 核心概念
+
+| 能力 | 说明 |
+|------|------|
+| `RoomType.Webinar` | 研讨会房型，区分房主/管理员、嘉宾和观众 |
+| 观众举手 | 观众申请打开麦克风，进入待审批队列 |
+| `pendingDeviceApplications` | 主持人或管理员侧看到的设备申请列表 |
+| 上台 | 观众被提升为嘉宾/参会人后才能参与发言或开设备 |
+| 弹幕 | Webinar 低门槛互动入口，通常基于 live barrage 状态和组件 |
+| 禁言联动 | 弹幕输入和普通聊天一样需要联动 `localParticipant.isMessageDisabled` |
+
+## 前置条件
+
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+- Webinar 房间应使用 `RoomType.Webinar` 创建或加入。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **只在 Webinar 房型中启用举手和弹幕入口** —— Standard 会议优先使用成员管理和会中聊天。
+2. **观众端举手用 `requestToOpenDevice({ device: DeviceType.Microphone })`** —— 不要让观众直接 `openLocalMicrophone()` 绕过审批。
+3. **主持人接受申请时先上台再批准设备** —— 推荐顺序是 `promoteToParticipant()` → `approveOpenDeviceRequest()`。
+4. **拒绝、超时、已批准都要清理观众端举手状态** —— 避免按钮一直显示“已举手”。
+5. **弹幕输入必须联动禁言状态** —— `localParticipant.isMessageDisabled` 生效时，输入框和发送链路都要禁用。
+6. **弹幕未读数只在面板关闭时累积** —— 打开面板应清零，并在切房间时重置。
+
+### ❌ NEVER
+
+1. **不要把 Webinar 观众当作普通会议成员直接开麦/开摄** —— 观众发言必须经过申请和审批。
+2. **不要只批准设备而不提升角色** —— 观众仍可能没有上台权限，导致申请看似通过但设备不可用。
+3. **不要把 Webinar 弹幕直接套用普通会议 `GROUP${roomId}` 聊天逻辑** —— Webinar 弹幕应使用 live barrage 能力。
+
+## 代码示例
+
+### 观众举手与取消举手
+
+```ts
+import { ref, onMounted, onUnmounted } from 'vue';
+import {
+  DeviceType,
+  RoomParticipantEvent,
+  useRoomParticipantState,
+} from 'tuikit-atomicx-vue3/room';
+
+const {
+  requestToOpenDevice,
+  cancelOpenDeviceRequest,
+  subscribeEvent,
+  unsubscribeEvent,
+} = useRoomParticipantState();
+
+const isRaised = ref(false);
+
+export async function toggleRaiseHand() {
+  if (isRaised.value) {
+    await cancelOpenDeviceRequest({ device: DeviceType.Microphone });
+    isRaised.value = false;
+    return;
+  }
+
+  await requestToOpenDevice({ device: DeviceType.Microphone, timeout: 30 });
+  isRaised.value = true;
+}
+
+const resetRaised = () => {
+  isRaised.value = false;
+};
+
+onMounted(() => {
+  subscribeEvent(RoomParticipantEvent.onDeviceRequestApproved, resetRaised);
+  subscribeEvent(RoomParticipantEvent.onDeviceRequestRejected, resetRaised);
+  subscribeEvent(RoomParticipantEvent.onDeviceRequestTimeout, resetRaised);
+});
+
+onUnmounted(() => {
+  unsubscribeEvent(RoomParticipantEvent.onDeviceRequestApproved, resetRaised);
+  unsubscribeEvent(RoomParticipantEvent.onDeviceRequestRejected, resetRaised);
+  unsubscribeEvent(RoomParticipantEvent.onDeviceRequestTimeout, resetRaised);
+});
+```
+
+### 主持人处理举手列表
+
+```ts
+import { computed } from 'vue';
+import { useRoomParticipantState, type DeviceRequestInfo } from 'tuikit-atomicx-vue3/room';
+
+const {
+  pendingDeviceApplications,
+  promoteToParticipant,
+  approveOpenDeviceRequest,
+  rejectOpenDeviceRequest,
+} = useRoomParticipantState();
+
+const pendingCount = computed(() => pendingDeviceApplications.value.length);
+
+export async function approveRaiseHand(invitation: DeviceRequestInfo) {
+  await promoteToParticipant({ userId: invitation.senderUserId });
+  await approveOpenDeviceRequest({
+    device: invitation.deviceType,
+    userId: invitation.senderUserId,
+  });
+}
+
+export async function rejectRaiseHand(invitation: DeviceRequestInfo) {
+  await rejectOpenDeviceRequest({
+    device: invitation.deviceType,
+    userId: invitation.senderUserId,
+  });
+}
+```
+
+### Webinar 弹幕入口
+
+```vue
+<template>
+  <BarrageList class="message-list" />
+  <BarrageInput
+    class="message-input"
+    :disabled="localParticipant?.isMessageDisabled"
+  />
+</template>
+
+<script setup lang="ts">
+import { BarrageInput, BarrageList } from 'tuikit-atomicx-vue3/live';
+import { useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+
+const { localParticipant } = useRoomParticipantState();
+</script>
+```
+
+## 平台特有注意事项
+
+### 1. 举手不是直接开麦
+观众端只发起 `requestToOpenDevice()`，真实上台和设备批准由主持人/管理员处理。不要在观众点击举手后直接调用 `openLocalMicrophone()`。
+
+### 2. 接受申请要处理错误码
+嘉宾人数已满或权限不足时，`promoteToParticipant()` / `approveOpenDeviceRequest()` 可能失败。遇到 `ERR_ALL_SEAT_OCCUPIED` 和 `ERR_NO_PERMISSION` 时应给出明确提示。
+
+### 3. 弹幕和普通会议聊天不同源
+普通会议聊天使用 `tuikit-atomicx-vue3/chat` 的 `setActiveConversation(GROUP${roomId})`；Webinar 弹幕使用 `tuikit-atomicx-vue3/live` 的 `BarrageList`、`BarrageInput`、`useBarrageState()`。
+
+## 代码生成约束
+
+### MUST
+
+1. **观众举手使用 `requestToOpenDevice({ device: DeviceType.Microphone })`**。  
+   **Verify**: 检查是否存在 `requestToOpenDevice`。
+2. **主持人接受申请时先 `promoteToParticipant()` 再 `approveOpenDeviceRequest()`**。  
+   **Verify**: 检查接受处理函数里的调用顺序。
+3. **监听 approved/rejected/timeout 事件重置举手状态**。  
+   **Verify**: 检查 `RoomParticipantEvent.onDeviceRequest*` 监听。
+4. **Webinar 弹幕使用 live barrage 组件或状态**。  
+   **Verify**: 检查是否从 `tuikit-atomicx-vue3/live` 导入 `BarrageInput` / `BarrageList` / `useBarrageState`。
+
+### MUST NOT
+
+1. **不要让观众举手后直接开麦**。  
+   **Verify**: 检查观众举手函数中是否直接调用 `openLocalMicrophone()`。
+2. **不要用普通会议聊天会话替代 Webinar 弹幕**。  
+   **Verify**: Webinar 弹幕代码中不应只出现 `setActiveConversation(GROUP${roomId})`。
+
+## 验证矩阵
+
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | Webinar 相关 API 可解析 | 检查 `DeviceType`、`RoomParticipantEvent`、barrage 导入 | 类型可解析 |
+| 2. 静态规则级 | 接受举手顺序正确 | 阅读 `approveRaiseHand()` | 先上台再批准设备 |
+| 3. 运行时级 | 观众举手和取消可用 | 双账号 Webinar 联调 | 主持人侧出现待处理申请 |
+| 4. 业务行为级 | 弹幕禁言联动正确 | 禁言后尝试发送 | 输入或发送被拦截 |
+
+## 排障指南
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 观众举手后主持人看不到 | 待处理列表为空 | 检查是否在 Webinar 房型、是否调用 `requestToOpenDevice()` |
+| 主持人同意后观众仍不能发言 | 申请通过但麦克风不可用 | 检查是否先调用 `promoteToParticipant()` 再批准设备 |
+| 举手按钮状态不复位 | 拒绝或超时后仍显示已举手 | 监听 approved/rejected/timeout 事件并重置本地状态 |
+| 弹幕被禁言仍可输入 | UI 和真实权限不一致 | 绑定 `localParticipant.isMessageDisabled` 并拦截发送 |
+
+## 关联知识
+
+- **[conference/participant-management](participant-management.md)** —— 角色治理 + 全员禁言 / 禁设备等会控规则。
+- **[conference/room-chat](room-chat.md)** —— 普通会议聊天，与 Webinar 弹幕需要区分。

package/knowledge-base/slices/live/anchor-lifecycle.md

@@ -0,0 +1,122 @@
+---
+id: live/anchor-lifecycle
+name: 主播开播与结束生命周期
+product: live
+tags: [anchor, start, end, createLive, endLive, lifecycle]
+platforms: [ios, android, web, flutter]
+related: [live/anchor-room-config, live/anchor-preview, live/device-control]
+---
+
+# 主播开播与结束生命周期
+
+## 功能说明
+
+主播的完整生命周期包含两个核心动作：
+
+- **`createLive`**：在服务端创建直播间并开始推流，观众可加入收看。
+- **`endLive`**：结束直播、销毁服务端房间、停止推流。
+
+除主动结束外，还需监听 `liveListEventPublisher` 处理**被动结束**场景（如被踢出、网络异常等）。生命周期管理的正确性直接影响房间资源释放和用户体验。
+
+## 核心概念
+
+### createLive
+
+调用 `LiveListStore` 的 `createLive` 方法，传入直播信息对象，通过成功/失败回调获取结果。
+
+| 行为 | 说明 |
+|------|------|
+| 创建服务端房间 | 以 `liveID` 为唯一标识在服务端创建直播间 |
+| 开始推流 | 将本地摄像头/麦克风数据推送到 CDN |
+| 生成直播列表条目 | 直播间出现在观众的直播列表中 |
+
+**前置条件**：摄像头已打开（`openLocalCamera` 成功）+ `LiveInfo` 已配置。
+
+### endLive
+
+调用 `LiveListStore` 的 `endLive` 方法，传入直播间 ID，通过成功/失败回调获取结果。
+
+| 行为 | 说明 |
+|------|------|
+| 通知所有观众直播结束 | 触发观众端 `onLiveEnded` 事件 |
+| 销毁服务端房间 | 房间从直播列表消失 |
+| 停止推流 | 本地推流通道关闭 |
+
+### 被动结束事件（liveListEventPublisher）
+
+通过订阅 `LiveListStore` 的直播列表事件监听以下事件：
+
+| 事件 | 触发场景 | 处理建议 |
+|------|----------|----------|
+| `onLiveEnded(liveID:)` | 直播被服务端强制结束 / 主播在其他设备调用 endLive | 清理 UI，提示用户直播已结束 |
+| `onKickedOutOfLive(liveID:reason:)` | 主播被管理员踢出直播间 | 显示踢出原因，释放资源，返回首页 |
+
+### 正确的结束顺序
+
+直播中可能存在 PK（跨房连麦）、连线（观众上麦）、连麦等子会话，结束时必须按以下顺序操作，避免资源未释放：
+
+```
+1. 结束 PK（如有）         → endPK()
+2. 断开连线（如有）        → disconnectLink()
+3. 断开连麦（如有）        → stopCoguest()
+4. 关闭摄像头/麦克风       → 通过 DeviceStore 关闭本地摄像头和麦克风
+5. 结束直播               → 通过 LiveListStore 调用 endLive，传入 liveID
+6. 销毁 LiveCoreView       → 仅在 endLive 回调成功后
+```
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **严格遵守结束顺序** — 先结束所有子会话（PK → 连线 → 连麦），再关闭设备，最后调 `endLive`。乱序操作会导致远端用户状态异常或推流未真正停止。
+2. **监听 `onLiveEnded` 事件** — 直播可能因网络问题、服务端策略或管理员操作而被动结束；监听此事件以保证 UI 和资源的正确清理。
+3. **在 `endLive` 回调成功后才释放 `LiveCoreView`** — 回调前释放会导致内部推流管道异常，可能产生残留连接。
+4. **`createLive` 成功后再更新 UI 状态** — 创建是异步操作，在回调成功前不应向用户展示「正在直播」状态。
+
+### ❌ NEVER
+
+1. **`endLive` 回调前释放 `LiveCoreView`** — 视图持有底层推流资源；过早释放会导致 crash 或资源泄漏。
+2. **忽略 `onKickedOutOfLive` 事件** — 未处理此事件时，被踢出的主播仍停留在「直播中」界面，用户体验极差，且推流资源无法释放。
+3. **重复调用 `createLive`** — 同一 `liveID` 已存在直播间时再次调用会返回 `-2108`；用唯一 ID 或先调 `endLive` 销毁后再创建。
+4. **在子线程更新 UI** — `createLive` / `endLive` 的回调应在主线程处理 UI 变更；若不确定回调线程，确保切换到主线程再更新 UI。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2105` | 直播间 ID 非法 | `liveID` 须为 ASCII 字符且长度 ≤ 48 字节 |
+| `-2107` | 直播间名称非法 | `liveName` 须为合法 UTF-8 且长度 ≤ 30 字节 |
+| `-2108` | 已在其他直播间 | 先调用 `endLive` / `leaveLive` 退出当前房间再重试 |
+| `-2300` | 权限不足 | 操作需要房主权限（如 endLive 只有创建者可调用） |
+
+### 排障流程
+
+```
+createLive 失败
+├── 错误码 -2105 → liveID 含非法字符或超长，修正后重试
+├── 错误码 -2107 → liveName 超 30 字节，截短后重试
+├── 错误码 -2108 → 已在房间，先 endLive 退出再创建
+└── 其他错误    → 检查网络连接；抓取 error.message 上报
+
+endLive 无响应 / 超时
+├── 是否已有网络连接？→ 检查网络后重试
+├── 是否在子线程调用了 UI 操作？→ 移至主线程
+└── LiveCoreView 是否被提前释放？→ 确保在回调后才销毁视图
+
+主播被踢出后推流未停止
+└── 检查是否订阅了 onKickedOutOfLive
+    └── 订阅后调用正确结束顺序释放资源
+
+观众收不到 onLiveEnded 通知
+└── 检查主播是否调用了 endLive（而非直接 kill 进程）
+    └── 若 App 被强杀，服务端会在超时后自动触发房间销毁
+```
+
+## 关联知识
+
+- **[live/anchor-room-config](live/anchor-room-config.md)** — createLive 所需的 LiveInfo 配置
+- **[live/anchor-preview](live/anchor-preview.md)** — createLive 前的摄像头预览准备
+- **[live/device-control](live/device-control.md)** — 设备开关与结束顺序
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/knowledge-base/slices/live/anchor-preview.md

@@ -0,0 +1,90 @@
+---
+id: live/anchor-preview
+name: 主播预览
+product: live
+tags: [anchor, preview, LiveCoreView, pushView, camera]
+platforms: [ios, android, web, flutter]
+related: [live/device-control, live/anchor-room-config, live/beauty, live/audio]
+---
+
+# 主播预览
+
+## 功能说明
+
+主播预览是开播前的关键准备步骤。`LiveCoreView` 是专为直播场景设计的轻量级视图组件，通过指定推流模式（pushView）将摄像头采集的本地画面渲染到屏幕上，让主播在正式开播前确认画面效果。
+
+预览阶段**不会**推流到观众端，仅在本地渲染画面，直到调用 `createLive` 后才开始向外推流。
+
+## 核心概念
+
+| 概念 / 方法 | 说明 |
+|------------|------|
+| LiveCoreView（推流模式） | 创建主播推流视图；推流模式表示该视图用于采集和预览本地画面 |
+| `setLiveID` | 将视图绑定到指定直播间 ID；**必须在开启摄像头之前调用** |
+| DeviceStore `openLocalCamera` | 打开本地摄像头并将预览帧渲染到已绑定的 LiveCoreView；可指定前置/后置 |
+| DeviceStore `openLocalMicrophone` | 打开本地麦克风，采集音频（预览阶段可选，开播前必须打开）|
+
+### 预览 vs 推流
+
+```
+[预览阶段]  LiveCoreView(推流模式) + setLiveID + openLocalCamera
+               ↓ 仅本地渲染，不推流
+[开播阶段]  LiveListStore.createLive(liveInfo) 之后
+               ↓ 本地画面开始向观众推流
+```
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **创建 LiveCoreView 后必须立即调用 `setLiveID`** — 视图内部通过 liveID 关联底层推流通道；若跳过此步骤，摄像头画面无法渲染（出现黑屏）。
+2. **先打开设备，再依赖预览** — 调用 `openLocalCamera` 的成功回调确认后，再进行 UI 更新（如移除加载遮罩）。
+3. **提前申请系统权限** — 进入预览页面前通过系统权限检查 API 确认摄像头/麦克风权限（各平台方式不同 → 见平台文件），避免在 `openLocalCamera` 回调中才发现权限被拒导致用户体验差。
+4. **将 LiveCoreView 正确加入视图层级** — 将 LiveCoreView 添加到视图层级后设置好布局，否则视图不可见。
+
+### ❌ NEVER
+
+1. **忘记调用 `setLiveID`** — 这是最常见的黑屏原因；`LiveCoreView` 没有 liveID 绑定时摄像头数据无处渲染。
+2. **预览阶段调用 `createLive`** — `createLive` 会立即向服务端创建房间并开始推流，应在用户确认开播后才调用，不可在预览配置页面调用。
+3. **在 `openLocalCamera` completion 之前就调用 `createLive`** — 设备未就绪时开播会导致推流无画面。
+4. **跳过设备关闭直接销毁 LiveCoreView** — 退出预览页面时须先关闭摄像头与麦克风，再移除视图，否则可能出现资源泄漏。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1101` | 摄像头缺少系统授权 | 引导用户在「设置 > 隐私 > 摄像头」中开启权限 |
+| `-1105` | 麦克风缺少系统授权 | 引导用户在「设置 > 隐私 > 麦克风」中开启权限 |
+| `-1100` | 打开摄像头失败 | 重启 App 重试；持续失败则上报错误日志 |
+| `-1102` | 摄像头被其他进程占用 | 提示用户关闭 FaceTime / 系统相机等应用 |
+
+### 排障流程
+
+```
+预览黑屏
+├── setLiveID 是否已调用？
+│   └─ 否 → 在将 LiveCoreView 添加到视图层级之后、openLocalCamera 之前调用 setLiveID
+├── openLocalCamera 是否成功（成功回调）？
+│   ├─ 失败(-1101) → 摄像头权限被拒，引导用户去系统设置
+│   ├─ 失败(-1102) → 摄像头被占用，提示关闭其他应用
+│   └─ 失败(-1100) → 硬件失败，重试或上报
+├── LiveCoreView 是否已添加到视图层级并设置正确布局？
+│   └─ 否 → 检查视图层级，确认视图可见
+└── 模拟器/无摄像头设备？
+    └─ 是 → 部分平台模拟器不支持摄像头，切换真机测试
+
+预览有画面但没声音
+├── openLocalMicrophone 是否已调用？
+├── 麦克风权限是否已授予（-1105）？
+└── 是否被其他音频应用占用（-1106）？
+```
+
+## 关联知识
+
+- **[live/device-control](live/device-control.md)** — DeviceStore 设备管理完整 API
+- **[live/anchor-room-config](live/anchor-room-config.md)** — 直播间配置（setLiveID 所需的 liveID 来源）
+- **[live/anchor-lifecycle](live/anchor-lifecycle.md)** — 从预览到 createLive 开播的完整生命周期
+- **[live/beauty](live/beauty.md)** — 预览阶段启用美颜效果
+- **[live/audio](live/audio.md)** — 音频采集与配置