@tencent-rtc/trtc-agent-skills 0.1.0

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

@@ -0,0 +1,99 @@
+---
+id: live/beauty
+name: 美颜
+product: live
+tags: [beauty, smooth, whiten, ruddy, BaseBeautyStore, filter]
+platforms: [ios, android, web, flutter]
+related: [live/anchor-preview, live/coguest-apply, live/device-control]
+---
+
+# 美颜
+
+## 功能说明
+
+`BaseBeautyStore` 是全局单例，提供磨皮、美白、红润三种基础美颜效果。通过调整 0–9 的强度参数作用于本地摄像头采集的视频流，效果实时生效。所有美颜参数通过 `BaseBeautyState` 统一管理，UI 订阅状态变化实现滑块与实际效果的同步。
+
+`BaseBeautyStore` 适用于主播开播和连麦观众两个场景，复用同一套接口。
+
+## 核心概念
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| `BaseBeautyStore` | 全局单例，整个 App 生命周期内唯一实例 |
+| `setSmoothLevel` | 设置磨皮强度；参数为浮点数，范围 0–9，0 为关闭，9 为最强 |
+| `setWhitenessLevel` | 设置美白强度；参数为浮点数，范围 0–9 |
+| `setRuddyLevel` | 设置红润强度；参数为浮点数，范围 0–9 |
+| `reset()` | 将所有美颜参数恢复为默认值（通常为 0） |
+| `BaseBeautyState` | 美颜状态容器；包含 `smoothLevel`、`whitenessLevel`、`ruddyLevel` 三个浮点数属性 |
+| `state` | 可订阅的状态属性，变化时通知 UI 更新滑块位置 |
+
+### UI 参数映射
+
+UI 控件（滑块）通常使用 `0.0–1.0` 的浮点范围，调用 SDK 前需乘以 9 转换：
+
+```
+SDK 参数 = UI 滑块值 × 9.0
+UI 滑块值 = SDK 参数 ÷ 9.0
+```
+
+> ⚠️ SDK 参数类型为浮点数，不是整数。传入 `4.5` 与传入 `4`（整数截断）效果不同。
+
+| UI 值 | SDK 参数值 | 效果 |
+|-------|--------|------|
+| 0.0 | 0.0 | 关闭效果 |
+| 0.5 | 4.5 | 中等强度 |
+| 1.0 | 9.0 | 最强效果 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **摄像头打开后再设置美颜** — `BaseBeautyStore` 作用于摄像头采集的视频流，必须在 `DeviceStore.openLocalCamera` 成功后调用美颜接口，否则设置不会生效。
+2. **订阅 `state` 更新 UI** — 订阅 `BaseBeautyStore` 的 `state` 状态变化，在状态变化时同步更新滑块位置，保证 UI 与实际效果一致。特别是调用 `reset()` 后需刷新所有滑块到初始值。
+3. **参数乘以 9.0 后传入浮点数** — UI 滑块值（0.0–1.0）必须映射到 SDK 参数范围（0.0–9.0），不要直接传 0.0–1.0 的值（实际效果几乎为 0）。参数类型是浮点数，不要转换为整数。
+4. **连麦观众复用同一单例** — 连麦场景中观众打开摄像头后，直接使用 `BaseBeautyStore` 即可，无需额外初始化。
+
+### ❌ NEVER
+
+1. **参数超过 9.0** — 传入大于 9.0 的值行为未定义，可能导致效果异常或崩溃。UI 层应做数值截断保护。
+2. **在摄像头关闭时调用美颜接口** — 无法作用于视频流，调用也不会报错，但下次摄像头打开时不会自动恢复上次设置，需重新赋值。
+3. **不做参数映射直接传 UI 值** — 直接将 0.0–1.0 的 UI 滑块值传给 SDK，实际强度极低（9 分之一），用户感知不到美颜效果。且参数类型是浮点数，不要转换为整数传入。
+
+## 排障指南
+
+### 常见错误码
+
+美颜接口本身无业务错误码，问题通常表现为效果不生效：
+
+| 现象 | 可能原因 | 处理建议 |
+|------|----------|----------|
+| 美颜无效果 | 摄像头未打开 | 确保 `openLocalCamera` 成功后再调用 |
+| 美颜无效果 | 参数传值错误（忘记 ×9） | 检查传入值是否在 1–9 范围内 |
+| 美颜无效果 | 授权问题 | 确认 AtomicXCore 授权包含美颜功能 |
+| 滑块与效果不同步 | 未订阅 `state` | 订阅状态变化，从 `state` 读取参数更新 UI |
+| `reset()` 后滑块未归零 | UI 未监听状态变化 | 订阅 `state` 变化，在 `reset()` 后自动刷新 UI |
+
+### 排障流程
+
+```
+美颜无效果
+├── 摄像头是否已打开？
+│   └─ 否 → 等待 openLocalCamera completion 回调后再设置美颜
+├── 参数是否正确？
+│   ├─ 打印 smoothLevel/whitenessLevel/ruddyLevel 值
+│   └─ 若值 < 1.0 → 确认是否做了 ×9 转换
+├── 授权是否包含美颜？
+│   └─ 检查 AtomicXCore 授权配置，联系腾讯云确认
+└── 真机测试
+    └─ 模拟器摄像头不支持，美颜效果只能在真机上验证
+
+reset() 后 UI 未更新
+└── 检查是否订阅了 BaseBeautyStore 的 state 变化
+    └── 在状态回调中更新所有滑块的值
+```
+
+## 关联知识
+
+- **[live/anchor-preview](live/anchor-preview.md)** — 主播预览时即可开启美颜
+- **[live/device-control](live/device-control.md)** — 摄像头打开是美颜生效的前提
+- **[live/coguest-apply](live/coguest-apply.md)** — 连麦观众打开摄像头后同样可使用美颜

package/knowledge-base/slices/live/coguest-apply.md

@@ -0,0 +1,105 @@
+---
+id: live/coguest-apply
+name: 观众申请连麦
+product: live
+tags: [coguest, apply, seat, mic, CoGuestStore, connect]
+platforms: [ios, android, web, flutter]
+related: [live/coguest-invite, live/device-control, live/beauty, live/audience-watch]
+---
+
+# 观众申请连麦
+
+## 功能说明 [必填]
+
+观众申请连麦（Apply-for-Seat）是直播场景中观众主动发起、主播审批的连麦流程。连麦管理器负责完整的信令管理，包含申请、审批、拒绝、取消和断开连麦等操作。整个流程通过主播端事件流和观众端事件流进行事件分发，视频渲染由视图代理提供。
+
+## 核心概念 [必填]
+
+### 角色与操作
+
+| 操作 | 发起方 | 说明 |
+|------|--------|------|
+| 发起连麦申请 | 观众 | 向主播发出连麦请求；可指定麦位（默认自动分配），需设置等待超时时长（秒） |
+| 取消申请 | 观众 | 在主播响应前撤回已发出的申请 |
+| 同意申请 | 主播 | 同意指定观众的连麦请求 |
+| 拒绝申请 | 主播 | 拒绝指定观众的连麦请求 |
+| 接受邀请 | 观众 | 接受主播发来的连麦邀请。注意：参数是邀请方（主播）的 ID，不是观众自己的 ID |
+| 拒绝邀请 | 观众 | 拒绝主播发来的连麦邀请。参数同上为邀请方 ID |
+| 断开连麦 | 双方均可 | 连麦中的任一方主动断开 |
+
+### 事件流
+
+| 事件流 | 接收方 | 关键事件 |
+|--------|--------|---------|
+| 主播端事件流 | 主播 | 收到观众申请、观众撤回申请、申请被其他主播处理、被邀请观众已响应、被邀请观众未响应 |
+| 观众端事件流 | 观众 | 收到主播邀请、主播取消邀请、申请被响应（同意/拒绝）、申请超时无响应、被踢下麦位 |
+
+### 状态与数据
+
+| 数据 | 说明 |
+|------|------|
+| 连麦中用户列表 | 当前所有正在连麦的用户 |
+| 待审批申请列表 | 已发起但主播尚未处理的申请 |
+
+### 状态机
+
+```
+观众端：        idle → applying → connected → idle
+主播端：        idle → reviewing（收到申请）→ idle（同意/拒绝后）
+```
+
+## 最佳实践 [必填]
+
+### ✅ ALWAYS
+
+1. **申请超时设置合理值（推荐 30 秒）** — 超时决定了观众等待审批的最长时间。超时过短（<10 秒）会导致主播来不及响应；过长（>60 秒）会让观众长时间等待。推荐默认值 30 秒，并在 UI 上展示倒计时。
+2. **申请通过后立即打开设备** — 收到"申请被同意"事件后，立刻打开摄像头和麦克风，减少连麦延迟。设备开启成功后画面才能被其他人看到。
+3. **断开连麦后立即关闭设备** — 断开连麦或收到断开事件后，立即关闭摄像头和麦克风，避免摄像头指示灯常亮、耗电及隐私问题。
+4. **主播端必须订阅主播事件流** — 主播必须监听主播端事件流才能收到观众的申请通知。若未订阅，观众申请会超时无响应。
+
+### ❌ NEVER
+
+1. **通过前开设备** — 在发出申请后、收到"同意"事件前就开启摄像头或麦克风，会导致观众在未获批时就推流，消耗流量且影响体验。必须等待"同意"事件。
+2. **忽略超时/失败回调** — 申请的失败分支（含超时场景）必须处理，向用户展示"申请超时，请重试"的提示，否则界面卡在"申请中"状态。
+3. **超过麦位上限仍继续申请** — 错误码 `-2340` 表示麦位已满。收到此错误时，应提示用户"当前连麦人数已达上限"，而非静默失败或重试。
+
+## 排障指南 [必填]
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2340` | 麦位已满，无法再接受新的连麦申请 | 提示观众"当前连麦人数已达上限，请稍后再试" |
+| 超时（无特定错误码）| 申请超时，主播未在规定时间内响应 | UI 展示"申请超时"，恢复申请按钮允许重试 |
+| 主播无响应 | 主播端未订阅事件流 | 检查主播端是否正确订阅了主播事件流，且订阅未被提前释放（→ 见各平台文件的排障细节） |
+
+### 排障流程
+
+```
+观众申请后无响应（一直等待）
+├── 主播端是否订阅了主播事件流？
+│       └─ 否 → 检查主播端订阅代码（→ 见平台文件的订阅生命周期管理）
+├── timeout 值是否太短？
+│       └─ 调整为 30 秒或更长
+└── 网络是否正常？
+        └─ 检查信令通道连通性
+
+观众申请被拒绝（错误码 -2340）
+└─ 麦位已满 → 提示用户稍后重试，不要自动循环重试
+
+连麦中断开后设备仍在运行
+└─ 确认断开回调/事件后调用了关闭摄像头 + 关闭麦克风
+
+连麦后画面黑屏
+├── 是否在"同意"事件后才开设备？
+│       └─ 否 → 移至"同意"事件回调内调用
+└── 视图代理是否正确返回并添加到界面？
+        └─ 检查视图代理实现（→ 见平台文件）
+```
+
+## 关联知识 [可选]
+
+- **[live/coguest-invite](live/coguest-invite.md)** — 主播主动邀请观众连麦的反向流程
+- **[live/device-control](live/device-control.md)** — 连麦通过后开设备、断开后关设备的具体操作
+- **[live/beauty](live/beauty.md)** — 连麦中主播/观众可叠加美颜效果
+- **[live/audience-watch](live/audience-watch.md)** — 非连麦观众观看连麦画面的拉流场景

package/knowledge-base/slices/live/device-control.md

@@ -0,0 +1,91 @@
+---
+id: live/device-control
+name: 设备管理
+product: live
+tags: [camera, microphone, device, DeviceStore, permission]
+platforms: [ios, android, web, flutter]
+related: [live/login-auth, live/anchor-preview, live/coguest-apply]
+---
+
+# 设备管理
+
+## 功能说明
+
+`DeviceStore` 是全局单例，统一管理摄像头和麦克风的生命周期。所有主播推流、连麦等场景均通过 `DeviceStore` 完成本地设备的打开、关闭与切换操作。
+
+`DeviceStore` 依赖 `LoginStore` 的登录态，必须在登录成功后才可调用其接口。
+
+## 核心概念
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| DeviceStore | 全局单例，整个应用生命周期内唯一实例 |
+| `openLocalCamera` | 打开本地摄像头；可指定前置或后置摄像头 |
+| `closeLocalCamera` | 关闭本地摄像头，释放硬件资源 |
+| `openLocalMicrophone` | 打开本地麦克风并开始采集音频 |
+| `closeLocalMicrophone` | 关闭本地麦克风，停止音频采集 |
+| `switchCamera` | 在不关闭摄像头的情况下切换前后摄像头 |
+| `setCaptureVolume` | 设置采集音量，range **[0, 100]** |
+| `setOutputVolume` | 设置播放音量，range **[0, 100]** |
+| `setAudioRoute` | 切换音频路由（扬声器 / 听筒） |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **先检查权限再打开设备** — 调用 `openLocalCamera` / `openLocalMicrophone` 前，通过系统权限检查 API 确认权限已授予（各平台方式不同 → 见平台文件）。权限被拒时引导用户前往系统设置，而非直接调用 SDK 方法（会触发 `-1101` / `-1105`）。
+2. **不用时关闭设备释放资源** — 主播退出直播间或 App 进入后台时调用 `closeLocalCamera()` 与 `closeLocalMicrophone()`，避免摄像头指示灯常亮、电量消耗过快，以及被系统强制中断。
+3. **连麦结束后及时关闭** — 观众连麦场景中，连麦结束（下麦）后立即关闭摄像头与麦克风，避免麦克风一直采集影响用户隐私体验。
+
+### ❌ NEVER
+
+1. **未登录时操作设备** — 在 `LoginStore` 登录成功之前调用 `DeviceStore` 接口会返回 `-1002`，设备不会正常打开。
+2. **忽略权限被拒回调** — 失败回调中的 `-1101` 摄像头缺授权 / `-1105` 麦克风缺授权必须处理，向用户展示引导弹窗或跳转系统设置入口，否则用户会看到黑屏或无声直播。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1100` | 打开摄像头失败（系统/硬件层面） | 检查设备是否完好；重启 App 重试 |
+| `-1101` | 摄像头缺少系统授权 | 引导用户在系统设置中开启摄像头权限 |
+| `-1102` | 摄像头被其他进程占用 | 提示用户关闭其他使用摄像头的应用（如 FaceTime） |
+| `-1103` | 设备无摄像头 | 部分平台模拟器不支持摄像头；提示用户使用真机测试 |
+| `-1104` | 打开麦克风失败（系统/硬件层面） | 检查设备是否完好；重启 App 重试 |
+| `-1105` | 麦克风缺少系统授权 | 引导用户在系统设置中开启麦克风权限 |
+| `-1106` | 麦克风被其他进程占用 | 关闭其他音频应用（电话、语音通话等） |
+| `-1107` | 设备无麦克风 | 检查外接麦克风连接状态 |
+
+### 排障流程
+
+```
+摄像头打不开
+├── 错误码 -1101（缺授权）
+│   ├── 首次使用 → 系统权限弹窗未弹出？
+│   │       └─ 检查是否已声明摄像头权限（各平台方式不同 → 见平台文件）
+│   └── 已拒绝 → 引导用户前往系统设置手动开启摄像头权限
+├── 错误码 -1102（被占用）
+│   └─ 提示用户关闭其他正在使用摄像头的应用
+├── 错误码 -1103（无摄像头）
+│   └─ 部分平台模拟器不支持摄像头，切换到真机测试
+├── 错误码 -1100（打开失败）
+│   ├── 重启应用重试
+│   └── 持续失败 → 抓取 error.message 上报
+└── 出现黑屏但无错误码
+    ├── 是否在 openLocalCamera 完成前就渲染了视图？→ 等待成功回调
+    └── 检查视图层级是否正确（预览 View 是否已添加到视图层级）
+
+麦克风打不开
+├── 错误码 -1105（缺授权）→ 引导前往系统设置开启麦克风权限
+├── 错误码 -1106（被占用）→ 关闭系统电话 / 其他语音应用
+├── 错误码 -1107（无麦克风）→ 检查外接设备
+└── 错误码 -1104（打开失败）→ 重试或上报
+```
+
+## 关联知识
+
+- **[live/login-auth](live/login-auth.md)** — DeviceStore 依赖登录态，需先完成登录
+- **[live/anchor-preview](live/anchor-preview.md)** — 摄像头打开后进行主播预览渲染
+- **[live/coguest-apply](live/coguest-apply.md)** — 连麦场景下观众需打开摄像头与麦克风
+- **[live/error-codes](live/error-codes.md)** — 完整设备错误码参考

package/knowledge-base/slices/live/error-codes.md

@@ -0,0 +1,167 @@
+---
+id: live/error-codes
+name: 错误码参考
+product: live
+tags: [error, error-code, troubleshoot, debug]
+platforms: [ios, android, web, flutter]
+related: [live/login-auth, live/device-control, live/anchor-preview, live/audience-watch, live/coguest-apply]
+---
+
+# 错误码参考
+
+## 功能说明
+
+本文档汇总 TRTC Live SDK 全量错误码，按功能分类整理，每条包含错误描述与处理建议。开发调试或线上排障时，优先根据错误码定位问题分类，再结合对应 slice 的排障流程深入排查。
+
+## 核心概念
+
+错误信息通过 SDK 错误回调返回，错误对象包含：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `code` | `Int` | 错误码（负数为客户端错误，正数为服务端错误） |
+| `message` | `String` | 错误描述文字，便于日志定位 |
+
+## 错误码分类总览
+
+### 通用错误（0 ~ -1 ~ -3301）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `0` | 操作成功 | — |
+| `-1` | 未分类错误 | 抓取 `error.message` 上报，联系技术支持 |
+| `-2` | 请求被限频，请稍后重试 | 加指数退避重试逻辑（建议最多 3 次）|
+| `-3` | 重复操作 | 检查是否有重复调用同一接口的逻辑 |
+| `-1000` | SDKAppID 未找到 / 不合法 | 核对控制台 App 列表中的 SDKAppID |
+| `-1001` | 参数不合法（含 UserSig 格式/过期） | 校验入参；重新从后端获取 UserSig |
+| `-1002` | 未登录，请先调用 Login 接口 | 确保在 `login` 成功回调后再调用其他接口 |
+| `-1003` | 音视频权限被拒 | 引导用户在系统设置中开启权限 |
+| `-1004` | 功能需要额外套餐 | 前往腾讯云控制台购买对应功能包 |
+| `-3301` | 网络受限 | 检查网络连通性；联系腾讯云技术支持 |
+
+### 设备错误（-1100 ~ -1109）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1100` | 打开摄像头失败（硬件/系统层面） | 重启 App 重试；持续失败则上报 |
+| `-1101` | 摄像头缺少系统授权 | 引导用户前往「设置 > 隐私 > 摄像头」开启 |
+| `-1102` | 摄像头被其他进程占用 | 提示用户关闭其他占用摄像头的应用 |
+| `-1103` | 设备无摄像头 | 提示用户使用真机；模拟器不支持摄像头 |
+| `-1104` | 打开麦克风失败（硬件/系统层面） | 重启 App 重试；持续失败则上报 |
+| `-1105` | 麦克风缺少系统授权 | 引导用户前往「设置 > 隐私 > 麦克风」开启 |
+| `-1106` | 麦克风被其他进程占用 | 提示用户关闭系统电话或其他语音应用 |
+| `-1107` | 设备无麦克风 | 检查外接麦克风连接状态 |
+| `-1108` | 屏幕共享对象获取失败 | 检查录屏权限 |
+| `-1109` | 屏幕共享启动失败 | 确认当前无其他屏幕共享正在进行 |
+
+### 房间错误（-2101 ~ -2108）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2101` | 需进房后才可使用此功能 | 确保先调用进房接口再执行房间内操作 |
+| `-2102` | 房主不可执行此退房操作 | 转让房主或解散房间后再退出 |
+| `-2103` | 当前房间类型不支持此操作 | 检查房间类型与操作的兼容性 |
+| `-2105` | 自定义房间 ID 不合法 | 使用可打印 ASCII（0x20-0x7e），最长 48 字节 |
+| `-2107` | 房间名称不合法 | 使用 UTF-8 编码，最长 30 字节 |
+| `-2108` | 当前用户已在其他房间内 | 先退出当前房间，或为不同场景创建独立实例 |
+
+### 权限与信令错误（-2200 ~ -2381）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-2200` | 用户不存在 | 核对 UserID 是否正确 |
+| `-2300` | 需要房主权限 | 仅房主可执行此操作 |
+| `-2301` | 需要房主或管理员权限 | 仅房主/管理员可执行此操作 |
+| `-2310` | 信令请求无权限 | 确认请求归属与权限角色 |
+| `-2311` | 请求 ID 无效或已处理 | 使用最新的请求 ID 重试 |
+| `-2312` | 重复的信令请求 | 避免对同一目标重复发送请求 |
+| `-2360` | 麦位音频已锁定 | 向房主或管理员申请解锁 |
+| `-2361` | 打开麦克风需房主/管理员批准 | 向房主/管理员申请上麦权限 |
+| `-2370` | 麦位视频已锁定 | 向房主或管理员申请解锁 |
+| `-2371` | 打开摄像头需房主/管理员批准 | 向房主/管理员申请视频权限 |
+| `-2372` | 屏幕共享被锁定 | 向房主或管理员申请解锁 |
+| `-2373` | 屏幕共享需批准 | 向房主/管理员申请屏幕共享权限 |
+| `-2380` | 当前房间已开启全员禁言 | 等待房主/管理员解除全员禁言 |
+| `-2381` | 当前用户被禁言 | 向房主/管理员申请解除禁言 |
+
+### REST API 公共错误（60xxx）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `60002` | HTTP 解析错误 | 核查请求 URL 格式 |
+| `60003` | JSON 解析失败 | 检查请求体 JSON 语法 |
+| `60004`~`60005` | 账号或签名不匹配 | 核对 SDKAppID / SecretKey |
+| `60006` | SDKAppID 无效 | 确认 SDKAppID 存在且未被禁用 |
+| `60007` | 接口调用频率超限 | 降低调用频率，添加重试退避 |
+| `60010` | 需要管理员账号 | 使用管理员账号调用此接口 |
+| `60012` | URL 中缺少 SDKAppID | 请求 URL 中补充 SDKAppID 参数 |
+| `60016` | SDKAppID 已被禁用 | 联系腾讯云技术支持 |
+| `60020` | 套餐已到期 | 前往控制台续费或购买套餐 |
+| `60021` | 请求来源 IP 未授权 | 将服务器 IP 加入白名单 |
+
+### REST API 私有错误（100xxx）
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `100001` | 服务内部错误 | 重试请求；持续失败联系技术支持 |
+| `100003` | 房间 ID 已被占用 | 更换房间 ID |
+| `100004` | 房间不存在 | 核对房间 ID 是否正确 |
+| `100008` | 房间已满员 | 尝试其他房间或等待空位 |
+| `100012` | 创建房间频率超限 | 同一房间 ID 创建请求间隔 ≥ 1 秒 |
+| `100018` | 进入房间需要密码 | 提供正确的房间密码 |
+| `100200` | 座位已锁定 | 尝试其他空闲座位 |
+| `100205` | 座位已达上限 | 等待座位空出 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **记录完整错误信息** — 同时保存 `error.code` 和 `error.message`，以及调用时的上下文（接口名、参数、时间戳），便于线上问题复现与排查。
+2. **按错误类型分类处理** — 区分用户可恢复错误（权限、参数）与需要上报的系统错误，给出差异化的用户提示。
+3. **对可重试错误加退避** — 对 `-2`（限频）、`100001`（服务内部错误）等可重试错误，使用指数退避策略（1s, 2s, 4s），最多重试 3 次。
+
+### ❌ NEVER
+
+1. **不要仅靠数字判断** — 错误码可能因 SDK 版本迭代而调整含义，始终结合 `error.message` 文字描述和当前文档双重确认。
+2. **不要静默吞掉错误** — 即使是预期内的错误（如用户主动拒绝权限），也需记录日志，便于统计和优化用户引导流程。
+
+## 排障指南
+
+### 排障流程
+
+```
+收到错误码
+    │
+    ├─ 0        → 操作成功，无需处理
+    │
+    ├─ -1000 ~ -1002（通用/登录类）
+    │       └─ 参考 live/login-auth 排障流程
+    │
+    ├─ -1100 ~ -1109（设备类）
+    │       └─ 参考 live/device-control 排障流程
+    │
+    ├─ -2101 ~ -2108（房间类）
+    │       └─ 检查进房状态 / 房间 ID 格式 / 操作时序
+    │
+    ├─ -2300 ~ -2381（权限/信令类）
+    │       ├─ 角色权限不足 → 检查用户角色（房主/管理员/普通用户）
+    │       └─ 禁言/锁定    → 引导用户向房主申请
+    │
+    ├─ 60xxx（REST API 公共）
+    │       └─ 检查 SDKAppID / SecretKey / 请求格式 / 套餐状态
+    │
+    ├─ 100xxx（REST API 私有）
+    │       └─ 检查房间状态 / 座位状态 / 重试逻辑
+    │
+    └─ 未知错误码
+            ├─ 记录 error.code + error.message + 调用上下文
+            └─ 提交至腾讯云技术支持
+```
+
+## 关联知识
+
+- **[live/login-auth](live/login-auth.md)** — 通用错误与登录相关错误码（-1000, -1001, -1002）
+- **[live/device-control](live/device-control.md)** — 设备错误码（-1100 ~ -1109）
+- **[live/anchor-preview](live/anchor-preview.md)** — 预览与推流相关错误
+- **[live/audience-watch](live/audience-watch.md)** — 拉流与观看相关错误
+- **[live/coguest-apply](live/coguest-apply.md)** — 连麦与权限信令相关错误码（-2360 ~ -2381）

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

@@ -0,0 +1,84 @@
+---
+id: live/gift
+name: 礼物
+product: live
+tags: [gift, send, receive, GiftStore, reward]
+platforms: [ios, android, web, flutter]
+related: [live/audience-watch, live/barrage]
+---
+
+# 礼物
+
+## 功能说明
+
+`GiftStore` 负责礼物面板数据拉取、礼物发送与接收事件处理。礼物列表从服务端拉取（含分类和价格），发送通过 `sendGift` 触发，接收端通过 `giftEventPublisher` 订阅 `.onReceiveGift` 事件驱动动画展示。
+
+**重要**：礼物扣费逻辑必须在**服务端回调**中完成，客户端仅负责 UI 展示，不可在客户端实现扣费。
+
+## 核心概念
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| `GiftStore.create(liveID)` | 创建或获取与指定直播间绑定的单例实例 |
+| `refreshUsableGifts` | 从服务端拉取礼物面板所需数据（分类列表 + 礼物详情）；建议在面板展示前调用 |
+| `sendGift(giftID, count)` | 发送指定数量的礼物；`count` 为正整数；成功时触发全房间的 `onReceiveGift` 广播 |
+| `giftEventPublisher` | 礼物事件发布器；订阅后接收房间内所有礼物事件（含自己发出的） |
+| `onReceiveGift` | 礼物事件类型；携带 `liveID`（字符串）、`gift`（Gift 对象）、`count`（正整数）、`sender`（发送者信息） |
+| `Gift` | 单个礼物数据模型；含 `giftID`、`name`、`desc`、`iconURL`、`resourceURL`（动画资源）、`level`、`coins`（价格） |
+| `GiftCategory` | 礼物分类模型；含 `categoryID`、`name`、`giftList`（Gift 数组） |
+| `GiftState` | 礼物模块状态容器；`usableGifts` 为服务端返回的可用礼物分类列表 |
+| `setLanguage` | 设置礼物名称/描述的语言（如 `"zh-CN"`、`"en"`）；需在 `refreshUsableGifts` 前调用 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **通过 `giftEventPublisher` 处理所有礼物 UI** — 礼物动画、连击计数、弹幕通知等所有 UI 逻辑都应订阅 `giftEventPublisher`。这是唯一能保证接收到所有礼物事件（包括他人发送的）的方式。
+2. **`sendGift` 回调仅处理错误** — `sendGift` 的 `completion` 只用于处理发送失败（如余额不足、网络错误）。成功后的礼物展示通过 `giftEventPublisher` 驱动，不要在 `completion` 成功分支里直接更新动画 UI。
+3. **面板展示前调用 `refreshUsableGifts`** — 礼物面板打开前先确保数据已拉取。可在进房时预加载，或在面板打开时懒加载，避免面板空白。
+4. **多语言场景先调用 `setLanguage`** — 国际化应用中，在 `refreshUsableGifts` 之前调用 `setLanguage`，否则礼物名称显示为默认语言。
+5. **礼物扣费通过服务端回调验证** — 客户端 `sendGift` 成功仅表示消息送达，实际扣费和到账须在服务端监听腾讯云礼物回调事件后处理。
+
+### ❌ NEVER
+
+1. **客户端实现扣费逻辑** — 不在客户端直接修改用户余额或金币数量，防止刷礼物作弊。扣费必须通过服务端回调处理。
+2. **在 `sendGift` 成功回调中展示动画** — 发送方的 UI 应与接收方保持一致，统一从 `giftEventPublisher` 消费，避免发送方和接收方动画时序不同步。
+3. **重复订阅 `giftEventPublisher`** — 每次进房只订阅一次；不要在页面显示等生命周期回调中重复订阅，否则同一礼物会触发多次动画。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-4001` | 余额不足 | 引导用户充值；在 UI 上展示充值入口 |
+| `-4002` | 礼物 ID 不存在 | 检查 `giftID` 是否来自 `refreshUsableGifts` 返回的列表 |
+| `-1002` | 未登录 | 确保登录成功后再操作 `GiftStore` |
+| 网络超时 | 发送超时无回调 | 展示重试按钮；不要自动重试以防重复扣费 |
+
+### 排障流程
+
+```
+发送失败
+├── -4001 余额不足 → 弹出充值引导
+├── -4002 礼物不存在 → 重新调用 refreshUsableGifts 刷新列表
+├── 网络错误 → 提示重试；避免自动重发
+└── completion 不回调
+    └── 检查 GiftStore 对应的 liveID 与当前房间是否一致
+
+giftEventPublisher 不触发
+├── 是否建立了订阅？ → 检查事件订阅是否已注册且订阅对象未被释放
+├── 发送成功但接收方没收到？
+│   ├── 接收方是否在同一房间？
+│   └── 订阅时机是否在发送之后？ → 确保进房后立即订阅
+└── 发送方自己也没收到？ → 核查 giftEventPublisher 订阅是否正确
+
+余额显示异常
+└── 客户端不维护余额，请检查服务端扣费回调逻辑
+```
+
+## 关联知识
+
+- **[live/audience-watch](live/audience-watch.md)** — 观众进房后初始化 GiftStore 订阅礼物事件
+- **[live/barrage](live/barrage.md)** — 礼物通知可通过弹幕区文本消息展示（BarrageStore 互补）
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考