@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/anchor-room-config.md

@@ -0,0 +1,104 @@
+---
+id: live/anchor-room-config
+name: 直播间配置
+product: live
+tags: [room, config, metadata, LiveListStore, room-name, cover]
+platforms: [ios, android, web, flutter]
+related: [live/anchor-preview, live/anchor-lifecycle]
+---
+
+# 直播间配置
+
+## 功能说明
+
+在主播调用 `createLive` 开播之前，需要通过 `LiveInfo` 配置直播间的基本信息（房间名称、封面图、座位模板等）以及扩展的自定义元数据（MetaData）。配置完成后将 `LiveInfo` 传入 `LiveListStore` 的 `createLive` 方法完成直播间创建。
+
+开播后仍可通过 `updateLiveMetaData` 动态更新 MetaData，但仅限**房主和管理员**操作。
+
+## 核心概念
+
+### LiveInfo 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `liveID` | 字符串 | ✅ | 直播间唯一标识；ASCII 字符，长度 ≤ 48 字节 |
+| `liveName` | 字符串 | ❌ | 直播间名称；UTF-8 编码，长度 ≤ 30 字节（约 10 个汉字） |
+| `coverURL` | 字符串 | ❌ | 封面图 URL；建议宽高比 9:16，大小 ≤ 500KB |
+| `seatTemplate` | 枚举 `SeatTemplate` | ✅ | 连麦座位布局模板（如 `videoDynamicGrid9Seats`） |
+| `notice` | 字符串 | ❌ | 直播间公告文本 |
+| `isGiftEnabled` | 布尔值 | ❌ | 是否开启礼物功能，默认 `false` |
+
+### MetaData 约束
+
+MetaData 是附加在直播间上的键值对扩展信息，常用于存储自定义标签、分类、活动 ID 等。
+
+| 限制项 | 上限 | 超出时的错误 |
+|--------|------|-------------|
+| 键的数量 | 10 个 | 超出则更新失败 |
+| 单个键长度 | 50 字节 | 键过长则写入被拒绝 |
+| 单个值大小 | 2 KB | 超出则写入被拒绝 |
+| 所有值总大小 | 16 KB | 超出则更新失败 |
+
+### updateLiveMetaData 权限
+
+```
+房主（创建者）    ✅ 可调用
+管理员            ✅ 可调用
+普通成员/观众     ❌ 返回 -2300（权限不足）
+```
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **`createLive` 之前完成所有配置** — `LiveInfo` 中的 `liveID`、`liveName`、`seatTemplate` 在创建后无法通过普通接口修改；需修改时必须结束本场直播重新创建。
+2. **key 数量控制在 10 个以内** — 超过限制会导致 `updateLiveMetaData` 失败；定期清理不再使用的 key。
+3. **MetaData 值做大小校验** — 写入前在客户端侧计算 UTF-8 字节数，超过 2 KB 时截断或拆分存储，避免请求到达服务端才失败。
+4. **使用语义化 key 命名** — 如 `category`、`activityId`，避免使用随机字符串，便于维护和调试。
+
+### ❌ NEVER
+
+1. **单值超过 2 KB** — 如大段 JSON、Base64 图片数据不应存入 MetaData；应上传到 CDN 后存 URL。
+2. **非房主调用 `updateLiveMetaData`** — 观众或普通成员调用会返回 `-2300` 权限不足；须在 UI 层限制此操作入口。
+3. **将敏感信息存入 MetaData** — MetaData 对房间内所有成员可见，不应存储 token、密码等敏感字段。
+4. **在 `createLive` 回调成功之前使用 liveID 进行其他操作** — 房间创建是异步操作，回调成功前房间尚不存在于服务端。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2105` | 直播间 ID 非法 | `liveID` 须为 ASCII 字符且长度 ≤ 48 字节；检查是否含非法字符（如中文、空格） |
+| `-2107` | 直播间名称非法 | `liveName` 须为合法 UTF-8 字符串且长度 ≤ 30 字节（约 10 个汉字）；超长时截断处理 |
+| `-2300` | 权限不足 | 仅房主/管理员可调用 `updateLiveMetaData`；检查当前用户角色 |
+| `-2108` | 已在其他直播间 | 当前用户已在另一个房间中；需先调用 `endLive` 或 `leaveLive` 退出后再创建 |
+
+### 排障流程
+
+```
+createLive 失败
+├── 错误码 -2105（liveID 非法）
+│   ├── 检查 liveID 是否为纯 ASCII 字符
+│   ├── 检查长度是否 ≤ 48 字节
+│   └── 常见问题：含空格、中文、特殊符号
+├── 错误码 -2107（liveName 非法）
+│   ├── 检查 liveName UTF-8 编码后字节数是否 ≤ 30
+│   └── 1 个汉字 = 3 字节；10 个汉字 = 30 字节（恰好达到上限）
+└── 错误码 -2108（已在其他房间）
+    └── 调用 endLive / leaveLive 退出当前房间后重试
+
+updateLiveMetaData 失败
+├── 错误码 -2300（权限不足）
+│   └── 当前用户非房主/管理员，不可更新 MetaData
+├── MetaData 超出大小限制
+│   ├── 单值 > 2 KB → 减小值大小或改存 CDN URL
+│   └── 总大小 > 16 KB → 清理不必要的 key
+└── key 数量超过 10 个 → 删除旧 key 后再添加新 key
+```
+
+## 关联知识
+
+- **[live/anchor-preview](live/anchor-preview.md)** — 预览阶段获取 liveID，传入 LiveInfo
+- **[live/anchor-lifecycle](live/anchor-lifecycle.md)** — createLive 完整调用流程
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/knowledge-base/slices/live/audience-list.md

@@ -0,0 +1,86 @@
+---
+id: live/audience-list
+name: 观众列表
+product: live
+tags: [audience, list, count, LiveAudienceStore]
+platforms: [ios, android, web, flutter]
+related: [live/audience-watch, live/audience-manage]
+---
+
+# 观众列表
+
+## 功能说明
+
+`LiveAudienceStore` 是管理直播间实时观众信息的模块，提供观众列表快照拉取、实时进离场事件订阅以及观众人数展示功能。开发者可用它构建完整的观众列表与人数展示 UI。
+
+核心入口：
+- 通过 `LiveAudienceStore` 的 `create` 方法传入 liveID 创建实例
+- 调用 `fetchAudienceList` 拉取观众列表快照（通过成功/失败回调获取结果）
+- 订阅观众事件获取实时进离场通知
+
+**注意**：`audienceCount` 受每秒 40 条消息的频控限制，高并发场景下人数变更消息可能被丢弃，**仅用于 UI 展示，不可用于精确统计或计费**。
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **LiveAudienceStore** | 观众信息管理模块，每个直播间通过 `create` 方法传入 liveID 创建独立实例 |
+| **LiveUserInfo** | 单个观众数据结构；含 `userID`、`userName`、`avatarURL` 字段 |
+| **LiveAudienceState** | 当前状态快照；`audienceList` 为观众数组，`audienceCount` 为总人数 |
+| **LiveAudienceEvent** | 实时事件枚举；`.onAudienceJoined` 观众进场，`.onAudienceLeft` 观众离场 |
+| **fetchAudienceList** | 主动拉取当前观众列表快照，进房后调用一次获取初始数据 |
+| **audienceCount** | 当前观众总数，受频控影响可能不精确，仅用于 UI 展示 |
+| **频控 40 条/秒** | 每个直播间每秒最多处理 40 条消息；高并发时人数变更消息优先级低，可能被丢弃 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **进房成功后立即调用 fetchAudienceList** — 获取当前观众列表快照作为初始数据，之后通过事件增量更新，避免列表长时间为空。
+2. **订阅 LiveAudienceEvent 实时更新列表** — `onAudienceJoined` 时在列表头部插入新观众，`onAudienceLeft` 时移除，保持列表与实际状态同步。
+3. **audienceCount 仅用于 UI 展示** — 在观众人数标签上显示近似值可接受；不可将此值用于计费、权限判断或精确统计场景。
+4. **直播结束或退出时销毁 audienceStore** — 销毁/释放 `audienceStore` 实例，释放订阅和内部资源，防止内存泄漏。
+
+### ❌ NEVER
+
+1. **依赖 audienceCount 的精确值** — 频控策略（40条/秒）会丢弃低优先级消息，高并发时人数可能滞后或跳变，切勿用此值做业务逻辑判断。
+2. **不订阅事件只依赖轮询** — `LiveAudienceStore` 提供推送事件，轮询方式浪费带宽且延迟更高；应通过 `liveAudienceEventPublisher` 订阅增量变化。
+3. **进房前调用 fetchAudienceList** — 未进房时调用会返回错误或空数据，必须在 `joinLive` 成功后才可调用。
+4. **持有多个相同 liveID 的 LiveAudienceStore 实例** — 重复 `create` 同一 liveID 会导致重复订阅和事件重复处理；每个直播间只创建一个实例。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1002` | 未登录 | 确保通过 `LoginStore` 登录成功后再操作 |
+| 列表返回空 | 正常情况：当前直播间无观众 / 未进房就调用 | 确认已进房；检查是否在 `joinLive.success` 后调用 |
+| 人数显示不准确 | 频控丢弃消息（正常现象） | 仅展示，不依赖精确值；可提示"约 X 人在看" |
+| 观众列表不更新 | 未订阅观众事件 | 检查事件订阅是否被正确持有（未持有则会立即释放） |
+
+### 排障流程
+
+```
+观众列表为空
+├── 是否已进房（joinLive.success）？ → 否 → 先进房
+├── 是否调用了 fetchAudienceList？ → 否 → 补充调用
+├── 调用后仍为空 → 直播间确实无其他观众（正常）
+└── 网络问题 → 检查连接
+
+观众进离场后列表不刷新
+├── 是否订阅了观众事件？
+│       → 否 → 添加订阅
+│       → 是 → 检查事件订阅是否被正确持有（未持有则立即释放）
+└── 事件回调是否在主线程刷新 UI？ → 否 → 确保切换到主线程再更新 UI
+
+人数跳变 / 不准
+└── 正常现象（频控 40 条/秒）
+    └── 加"约"字前缀展示即可；不可用于精确业务逻辑
+```
+
+## 关联知识
+
+- **[live/audience-watch](live/audience-watch.md)** — 进房观看，是使用观众列表的前提
+- **[live/audience-manage](live/audience-manage.md)** — 踢人、设置管理员等管理操作
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/knowledge-base/slices/live/audience-manage.md

@@ -0,0 +1,92 @@
+---
+id: live/audience-manage
+name: 观众管理
+product: live
+tags: [manage, kick, admin, administrator, LiveAudienceStore]
+platforms: [ios, android, web, flutter]
+related: [live/audience-list, live/barrage]
+---
+
+# 观众管理
+
+## 功能说明
+
+观众管理涵盖直播间的权限控制与成员管控，包括：将观众踢出直播间（`kickUserOutOfRoom`）、设置/撤销管理员（`setAdministrator` / `revokeAdministrator`）。所有管理操作通过 `LiveAudienceStore` 执行，操作权限遵循严格的层级关系：**房主 > 管理员 > 普通观众**。
+
+## 核心概念
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| `kickUserOutOfRoom` | 将指定用户踢出直播间，传入目标 userID，通过成功/失败回调获取结果；被踢用户收到 `onKickedOutOfLive` 回调；需管理员或房主权限 |
+| `setAdministrator` | 将指定观众设置为管理员，传入目标 userID，通过成功/失败回调获取结果；仅房主可调用 |
+| `revokeAdministrator` | 撤销指定用户的管理员权限，传入目标 userID，通过成功/失败回调获取结果；仅房主可调用 |
+| 权限层级 | 房主（Owner）> 管理员（Admin）> 普通观众（Audience） |
+| `onKickedOutOfLive` | 被踢用户收到的回调通知；客户端须监听此事件并执行退房操作 |
+
+### 权限矩阵
+
+| 操作 | 房主 | 管理员 | 普通观众 |
+|------|------|--------|---------|
+| 踢出观众 | ✅ | ✅ | ❌ |
+| 设置管理员 | ✅ | ❌ | ❌ |
+| 撤销管理员 | ✅ | ❌ | ❌ |
+| 踢出管理员 | ✅ | ❌ | ❌ |
+
+> 管理员**无法**踢出其他管理员，也无法踢出房主。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **操作前校验当前用户权限** — 调用 `kickUserOutOfRoom` / `setAdministrator` 前，检查当前用户的角色（房主或管理员），在 UI 层控制按钮的可见性，避免因权限不足触发 `-2300` / `-2301` 错误。
+2. **监听 `onKickedOutOfLive` 执行退房** — 被踢用户必须在收到 `onKickedOutOfLive` 回调时立即调用退房接口并跳转到离开直播间页面，给出友好提示（如"您已被主播移出直播间"）。
+3. **操作前弹出二次确认** — 踢人操作不可撤销，建议弹出确认对话框，防止误操作。
+4. **管理员数量做业务侧限制** — SDK 层面不限制管理员数量，但业务侧建议设置合理上限（如最多 5 名管理员），避免权限滥用。
+
+### ❌ NEVER
+
+1. **普通观众调用管理操作** — 权限不足时调用会返回 `-2300`（需房主权限）或 `-2301`（需房主或管理员权限），且不执行任何操作。
+2. **不监听 `onKickedOutOfLive` 直接忽略** — 被踢用户若不退房，虽然消息接收会中断，但可能仍保持一定的连接态，造成状态不一致。
+3. **客户端缓存权限状态而不实时获取** — 管理员权限可随时被房主撤销，不要在本地长期缓存权限，应在每次操作前从 `LiveAudienceStore` 获取最新状态。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2300` | 权限不足，该操作仅房主可执行 | 确认当前用户是房主；隐藏非房主用户的管理员设置按钮 |
+| `-2301` | 权限不足，该操作需房主或管理员权限 | 确认当前用户角色；普通观众不展示踢人入口 |
+| `-2302` | 目标用户不在房间内 | 刷新观众列表后重试；用户可能已主动离开 |
+| `-1002` | 未登录 | 确保登录成功后再执行管理操作 |
+
+### 排障流程
+
+```
+踢人操作失败
+├── -2300 权限不足（需房主）
+│   └── 检查当前用户是否为房主，管理员无法踢出其他管理员
+├── -2301 权限不足（需房主或管理员）
+│   └── 检查当前用户角色；普通观众不能踢人
+├── -2302 用户不在房间
+│   └── 刷新观众列表，目标用户可能已离开
+└── completion 不回调
+    └── 检查网络连接和 liveID 是否正确
+
+设置管理员失败
+├── -2300 → 仅房主可操作
+└── 目标用户已是管理员 → 检查用户当前角色后重试
+
+被踢后仍在房间
+└── 检查是否正确监听并处理 onKickedOutOfLive 回调
+    └── 确认收到回调后调用了 exitLiveRoom
+
+管理员权限突然失效
+└── 房主可能已撤销管理员权限 → 不要缓存权限，每次操作前实时校验
+```
+
+## 关联知识
+
+- **[live/audience-list](live/audience-list.md)** — 获取观众列表，管理操作的数据来源
+- **[live/barrage](live/barrage.md)** — `disableSendMessage` 禁言操作位于 BarrageStore
+- **[live/error-codes](live/error-codes.md)** — 完整权限错误码参考

package/knowledge-base/slices/live/audience-watch.md

@@ -0,0 +1,85 @@
+---
+id: live/audience-watch
+name: 观众观看
+product: live
+tags: [audience, watch, join, leave, playView, LiveCoreView]
+platforms: [ios, android, web, flutter]
+related: [live/live-list, live/login-auth, live/barrage, live/gift]
+---
+
+# 观众观看
+
+## 功能说明
+
+观众通过 `LiveCoreView` 进入直播间并拉流观看。整个流程围绕三个核心 API：`setLiveID` 绑定直播间、`joinLive` 进房拉流、`leaveLive` 退出释放资源。
+
+核心入口：依次调用 `LiveCoreView` 的 `setLiveID` 绑定直播间、`joinLive` 进房拉流、`leaveLive` 退出释放资源。每个方法通过成功/失败回调返回结果。
+
+观众使用 `.playView` 视图类型，只拉流不推流，不会触发摄像头/麦克风权限申请。被踢出直播间时会收到 `onKickedOutOfLive` 事件，必须监听并处理。
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **LiveCoreView** | 直播核心视图组件，封装了拉流、连麦、礼物等所有 UI 与逻辑 |
+| **.playView** | 观众视图类型，仅拉取主播视频流，不启用摄像头或麦克风 |
+| **setLiveID** | 绑定目标直播间 ID，必须在 `joinLive` 之前调用 |
+| **joinLive** | 进入直播间并开始拉流；成功回调后才可使用弹幕、礼物等功能 |
+| **leaveLive** | 退出直播间并释放所有媒体资源；页面销毁时必须调用 |
+| **onKickedOutOfLive** | 观众被主播或管理员移出直播间时触发的事件 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **joinLive 之前必须调用 setLiveID** — `LiveCoreView` 需要先知道目标直播间才能建立连接，顺序错误会导致进房失败或黑屏。
+2. **在 joinLive 成功回调后再启用其他功能** — 弹幕发送、礼物、连麦申请等均依赖进房成功的会话上下文，提前调用会报未进房错误。
+3. **退出时先断开连麦再 leaveLive** — 若观众正处于连麦状态，直接调用 `leaveLive` 会残留上行流；应先调用连麦断开接口（`disConnect`），待回调后再 `leaveLive`。
+4. **处理 onKickedOutOfLive 事件** — 收到此事件后立即退出播放页、清理 `LiveCoreView`，并向用户展示提示（如"您已被移出直播间"）。
+5. **App 进入后台时清理播放资源** — 系统在 App 后台时间过长后可能回收媒体资源，应在 App 切到后台时停播，切回前台时重新进房或恢复。
+
+### ❌ NEVER
+
+1. **在 joinLive 成功前操作直播功能** — 弹幕、礼物、连麦等功能必须等待 `joinLive` 的成功回调，不可在进房请求未完成时调用。
+2. **忘记调用 leaveLive** — 若页面销毁时未调用 `leaveLive`，媒体流不会释放，占用带宽与解码资源，还会导致后续进房冲突。
+3. **将同一个 LiveCoreView 复用给不同直播间** — 应在每次进新直播间前销毁旧实例，或在 `leaveLive` 成功后重新 `setLiveID`，不可不退房直接绑定新 ID。
+4. **忽略进房失败** — 网络抖动、直播间已结束等原因均可导致 `joinLive` 失败，必须在失败回调中处理并给用户反馈。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1002` | 未登录 | 确保 `LoginStore` 的 `login` 成功后再进房 |
+| `-2001` | 直播间不存在 / 已结束 | 直播已下播，返回列表页并刷新 |
+| `-2003` | 重复进房 | 调用 `leaveLive` 后再重新 `joinLive` |
+| 黑屏但无错误码 | `setLiveID` 未在 `joinLive` 前调用 | 检查调用顺序：setLiveID → joinLive |
+| 被踢后 UI 无响应 | 未订阅 `onKickedOutOfLive` | 注册事件监听，收到事件后执行退出逻辑 |
+
+### 排障流程
+
+```
+进房后黑屏
+├── 是否先调用了 setLiveID？ → 否 → 补充调用，重新进房
+├── joinLive 是否返回成功？ → 否 → 查看错误码
+│       ├─ -1002 → 先登录
+│       ├─ -2001 → 直播已结束，返回列表
+│       └─ -2003 → 先 leaveLive 再 joinLive
+└── 成功但画面黑 → 检查 .playView 是否已添加到视图层级且尺寸非零
+
+被踢出后没有提示
+└── 确认已订阅 onKickedOutOfLive 并在回调中执行退出 + Toast
+
+退出页面后内存/CPU 未下降
+└── 确认页面销毁时已调用 leaveLive
+    └── 若处于连麦状态 → 先 disConnect → 再 leaveLive
+```
+
+## 关联知识
+
+- **[live/live-list](live/live-list.md)** — 从直播列表获取 liveID 后进入观看
+- **[live/login-auth](live/login-auth.md)** — 进房前必须完成登录鉴权
+- **[live/barrage](live/barrage.md)** — 进房成功后可使用弹幕功能
+- **[live/gift](live/gift.md)** — 进房成功后可发送礼物
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/knowledge-base/slices/live/audio.md

@@ -0,0 +1,116 @@
+---
+id: live/audio
+name: 音效管理
+product: live
+tags: [audio, voice, effect, changer, reverb, ear-monitor, AudioEffectStore]
+platforms: [ios, android, web, flutter]
+related: [live/anchor-preview, live/device-control]
+---
+
+# 音效管理
+
+## 功能说明
+
+`AudioEffectStore` 是全局单例，统一管理主播端的音效能力，包括采集音量、耳返、变声、混响四大功能模块。所有音效设置在整个直播生命周期内持续生效，直播结束后须调用 `reset()` 恢复默认值。
+
+采集音量（`setCaptureVolume`）通过 `DeviceStore` 控制，影响观众收到的音量；耳返音量（`setVoiceEarMonitorVolume`）仅影响主播本人通过耳机听到的声音，两者相互独立。
+
+## 核心概念
+
+| 方法 / 属性 | 归属 | 说明 |
+|-------------|------|------|
+| `AudioEffectStore` | `AudioEffectStore` | 全局单例，整个 App 生命周期内唯一实例 |
+| `DeviceStore` | `DeviceStore` | 全局单例；采集音量由此控制 |
+| `setCaptureVolume` | `DeviceStore` | 设置麦克风采集音量；范围 `0–100`，默认 `100` |
+| `setVoiceEarMonitorEnable` | `AudioEffectStore` | 开启 / 关闭耳返；须插入**有线耳机**才有效（蓝牙耳机不支持） |
+| `setVoiceEarMonitorVolume` | `AudioEffectStore` | 设置耳返音量；范围 `0–100`，默认 `100` |
+| `setAudioChangerType` | `AudioEffectStore` | 设置变声效果；传 `none` 还原 |
+| `setAudioReverbType` | `AudioEffectStore` | 设置混响效果；传 `none` 还原 |
+| `reset()` | `AudioEffectStore` | 重置所有音效参数为默认值 |
+
+### AudioChangerType 枚举
+
+| 值 | 说明 |
+|----|------|
+| `none` | 原声（无变声） |
+| `child` | 儿童音 |
+| `littleGirl` | 萝莉音 |
+| `man` | 男声 |
+| `ethereal` | 空灵 |
+| `cold` | 冷酷 |
+| `foreignerr` | 外国腔 |
+| `heavyMachinery` | 重型机械 |
+| `heavyMetal` | 重金属 |
+| `strongCurrent` | 强电流 |
+| `fatso` | 肥仔 |
+| `trappedBeast` | 困兽 |
+
+### AudioReverbType 枚举
+
+| 值 | 说明 |
+|----|------|
+| `none` | 无混响 |
+| `ktv` | KTV |
+| `smallRoom` | 小房间 |
+| `auditorium` | 礼堂 |
+| `loud` | 大型会场 |
+| `deep` | 深沉 |
+| `magnetic` | 磁性 |
+| `metallic` | 金属感 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **直播结束后调用 `reset()`** — `AudioEffectStore` 是全局单例，音效参数在 App 整个生命周期内持久存在。离房后音效虽自动失效，但本地 `AudioEffectState` 不会重置；主动调用 `reset()` 可保持状态干净，避免下次开播时 UI 显示残留旧值。
+2. **两个 Store 都是全局单例，各司其职** — 采集音量走 `DeviceStore.setCaptureVolume`，其余音效走 `AudioEffectStore`。不要混淆两个单例的职责。
+3. **耳返仅支持有线耳机** — 蓝牙耳机（AirPods 等）**不支持**耳返。开启耳返时，先通过系统音频路由 API 确认当前输出路由包含有线耳机，否则开启后无声音。应向用户提示"请插入有线耳机"，不要基于蓝牙耳机判断。
+4. **音量范围 0–100，超出范围截断** — `setCaptureVolume` 和 `setVoiceEarMonitorVolume` 的有效范围均为 `0–100`；默认值为 `100`（即原始音量）。UI 滑块的 `maximumValue` 应设为 `100`，不是 `150`。
+
+### ❌ NEVER
+
+1. **直播结束不调 `reset()`** — 遗漏重置不影响实际音效（离房后自动失效），但会导致 `AudioEffectState` 保持上次的值，下次开播时 UI 面板显示残留状态，造成困惑。
+2. **在未插有线耳机时向用户展示耳返开关** — 蓝牙耳机不支持耳返；有线耳机未插入时耳返无效，应先通过系统音频路由 API 检测有线耳机再决定是否展示该控件，避免用户困惑。
+3. **将采集音量和耳返音量混用** — 两个音量控制的是不同端点（观众听到的 vs 主播自己听到的），不要用同一个 Slider 同时控制两者。
+
+## 排障指南
+
+### 常见错误码
+
+音效模块通常不返回业务错误码，异常表现为效果不生效。常见排障场景：
+
+| 现象 | 可能原因 | 处理建议 |
+|------|----------|----------|
+| 耳返无声 | 未插入有线耳机 / 使用了蓝牙耳机 | 蓝牙耳机不支持耳返；通过系统音频路由 API 检查当前输出设备，确认包含有线耳机 |
+| 采集音量异常（观众听到音量过大/过小） | `setCaptureVolume` 值偏差或未调用 | 检查是否已调用 `DeviceStore.setCaptureVolume`，有效范围 0–100，默认值 100 |
+| 变声/混响在新一场直播中意外生效 | 直播结束时未调 `reset()` | 在直播结束（下播/退房）时调用 `AudioEffectStore.reset()` |
+| 变声效果不生效 | 麦克风未打开 | 确保 `DeviceStore.openLocalMicrophone` 已成功回调 |
+
+### 排障流程
+
+```
+耳返无声
+├── 是否已调用 setVoiceEarMonitorEnable(true)？
+│       └─ 否 → 补充调用
+├── 是否使用有线耳机？
+│       ├─ 蓝牙耳机 → 不支持耳返，提示用户换有线耳机
+│       └─ 通过系统音频路由 API 检查当前输出设备
+│               ├─ 无有线耳机输出 → 提示用户插入有线耳机
+│               └─ 有耳机但仍无声 → 检查 earMonitorVolume 是否为 0
+└── 重置后重新开启
+        └─ reset() → setVoiceEarMonitorEnable(true) → setVoiceEarMonitorVolume(100)
+
+变声/混响上次直播残留
+├── 确认直播结束时未调 reset()
+└─ 在下播/退房回调中补充 AudioEffectStore.reset()
+
+采集音量过大/过小
+├── 检查 DeviceStore 的 state.captureVolume 当前值
+├── 调用 setCaptureVolume(100) 恢复默认
+└── 若仍异常 → 检查是否有其他地方覆盖写入了 captureVolume
+```
+
+## 关联知识
+
+- **[live/device-control](live/device-control.md)** — `DeviceStore` 管理麦克风开关，音效须在麦克风打开后才生效
+- **[live/anchor-preview](live/anchor-preview.md)** — 主播预览阶段可预设音效，开播后立即生效

package/knowledge-base/slices/live/barrage.md

@@ -0,0 +1,88 @@
+---
+id: live/barrage
+name: 弹幕
+product: live
+tags: [barrage, message, chat, mute, BarrageStore, danmu]
+platforms: [ios, android, web, flutter]
+related: [live/audience-watch, live/audience-manage]
+---
+
+# 弹幕
+
+## 功能说明
+
+`BarrageStore` 是直播间弹幕/聊天的核心模块，负责文本消息与自定义消息的收发、本地提示插入，以及用户禁言管理。所有弹幕消息通过 `BarrageState.messageList` 统一分发，UI 层订阅该状态进行渲染。
+
+`BarrageStore` 实例与直播间 `liveID` 绑定，相同 `liveID` 的多次 `create` 调用返回同一实例。
+
+## 核心概念
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| `BarrageStore.create(liveID)` | 创建或获取与指定直播间绑定的单例实例 |
+| `sendTextMessage(text, extensionInfo)` | 向房间内所有用户广播纯文本弹幕；`extensionInfo` 可附加扩展字段；通过成功/失败回调返回结果 |
+| `sendCustomMessage(businessID, data)` | 发送自定义业务消息；`data` 为 JSON 格式字符串，`businessID` 区分消息类型；通过成功/失败回调返回结果 |
+| `appendLocalTip(message)` | 向本地消息列表插入仅本端可见的系统提示，不广播给其他用户 |
+| `disableSendMessage(userID, isDisable)` | 对指定用户单独禁言（`true`）或解除禁言（`false`）；状态在用户重新进房后仍生效；通过成功/失败回调返回结果 |
+| `Barrage` | 单条弹幕数据模型；包含发送者信息、`textContent` / `data` 内容、`messageType` 分类 |
+| `BarrageState` | 弹幕模块状态容器；`messageList` 是 UI 渲染的唯一数据源 |
+| `BarrageState.messageList` | 按时间排序的完整消息数组；SDK 每次更新时下发完整列表 |
+
+> **全员禁言**：通过 `LiveListStore` 的 `updateLiveInfo` 方法（设置 `modifyFlag` 为 `isMessageDisable`）控制，与 `disableSendMessage` 是不同接口，作用范围不同。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **批处理更新（300ms 节流）** — 高并发弹幕场景下 SDK 可能以 30+ 次/秒的频率下发更新。务必对 `messageList` 变化做 300ms 节流处理，将刷新频率降至 3~4 次/秒，避免主线程过载。
+2. **循环缓冲限制消息上限（500 条）** — 长时间直播中 `messageList` 会持续增长。在 UI 层维护一个固定大小（推荐 500 条）的循环缓冲区，超出后丢弃最旧消息，防止内存无限膨胀。
+3. **启用异步渲染优化** — 弹幕 Cell 开启异步渲染，将绘制工作移至后台线程，主线程只做布局，显著降低掉帧率。
+4. **`appendLocalTip` 用于系统通知** — 用户进入/离开直播间、礼物特效等本地通知使用 `appendLocalTip` 插入，无需走网络，也不污染其他用户视图。
+5. **`sendCustomMessage` 携带 businessID** — 自定义消息务必设置清晰的 `businessID`（如 `"gift_notify"`、`"like_action"`），接收端通过 `businessID` 过滤处理，避免业务逻辑混淆。
+
+### ❌ NEVER
+
+1. **每条弹幕到达立即刷新 UI** — 不做节流直接刷新列表，高峰期会造成 UI 卡顿甚至 ANR。
+2. **无限累积消息到内存** — 不对 `messageList` 做截断，长播场景下内存占用会线性增长直至被系统终止。
+3. **在非主线程直接操作 UI** — 订阅 `messageList` 变化后，确保所有 UI 操作切换到主线程执行。
+4. **用 `appendLocalTip` 替代网络消息** — `appendLocalTip` 只在本地生效，不要用它发送需要其他用户看到的消息。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2380` | 全员禁言（房主已开启全局禁言） | UI 提示"直播间已开启全员禁言"，隐藏发送入口 |
+| `-2381` | 当前用户已被单独禁言 | UI 提示"您已被禁止发言"，隐藏发送入口 |
+| `-2382` | 消息内容违规（敏感词过滤） | 提示用户修改内容后重试 |
+| `-1002` | 未登录即调用 | 确保 `LoginStore` 登录成功后再初始化 `BarrageStore` |
+
+### 排障流程
+
+```
+弹幕不显示
+├── messageList 有数据但 UI 不更新
+│   ├── 是否在主线程更新 UI？ → 确保 UI 操作在主线程执行
+│   └── 是否未订阅 BarrageState？ → 检查状态订阅是否建立
+├── messageList 始终为空
+│   ├── BarrageStore.create(liveID) 的 liveID 是否与进房 ID 一致？
+│   └── 登录态是否正常？ → 检查 LoginStore 的 isLogin 状态
+└── 历史消息不显示
+    └── BarrageStore 创建时机太晚 → 在进房前创建实例以接收历史消息
+
+发送失败
+├── -2380 全员禁言 → 检查 LiveListStore.liveInfo.isMessageDisable
+├── -2381 已被禁言 → 检查当前用户禁言状态
+├── -2382 内容违规 → 提示用户修改内容
+├── 网络错误 → 检查网络连接，retry 1次
+└── completion 一直不回调
+    └── 检查 liveID 对应的房间是否存在且已加入
+```
+
+## 关联知识
+
+- **[live/audience-watch](live/audience-watch.md)** — 观众进房后需初始化 BarrageStore 接收弹幕
+- **[live/audience-manage](live/audience-manage.md)** — 禁言用户依赖管理员/房主权限
+- **[live/gift](live/gift.md)** — 礼物通知常通过弹幕区展示
+- **[live/error-codes](live/error-codes.md)** — 完整消息错误码参考