@tencent-rtc/trtc-agent-skills 0.1.0

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

@@ -0,0 +1,257 @@
+---
+id: live/anchor-room-config
+platform: ios
+---
+
+# 直播间配置 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**前置状态**：
+- `LoginStore.shared` 登录成功（须完成登录）
+- 摄像头/麦克风设备已打开（`DeviceStore.shared.openLocalCamera` 成功）
+
+## API 调用（真实签名）
+
+```swift
+// 构建直播间配置
+// ⚠️ LiveInfo 必须通过 init(seatTemplate:) 初始化，不是 LiveInfo()
+var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+liveInfo.liveID       = "your-live-id"
+liveInfo.liveName     = "直播间名称"
+liveInfo.coverURL     = "https://cdn.example.com/cover.jpg"
+liveInfo.notice       = "欢迎来到我的直播间"
+liveInfo.isPublicVisible = true
+
+// 创建直播间
+// ⚠️ 第一参数无标签（unnamed），completion 返回 LiveInfo
+LiveListStore.shared.createLive(_ liveInfo: LiveInfo,
+                                completion: LiveInfoCompletionClosure?)
+// LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+
+// 更新直播间元数据（仅房主/管理员可调用）
+LiveListStore.shared.updateLiveMetaData(_ metaData: [String: String],
+                                        completion: CompletionClosure?)
+
+// 更新直播间基础信息
+LiveListStore.shared.updateLiveInfo(_ liveInfo: LiveInfo,
+                                    modifyFlag: LiveInfo.ModifyFlag,
+                                    completion: CompletionClosure?)
+```
+
+**LiveInfo 初始化与关键字段**
+```swift
+struct LiveInfo {
+    // ⚠️ 正确初始化方式：必须传 seatTemplate
+    init(seatTemplate: SeatLayoutTemplate)
+
+    var liveID: String
+    var liveName: String
+    var coverURL: String
+    var backgroundURL: String
+    var notice: String
+    var seatTemplate: SeatLayoutTemplate  // 座位布局模板
+    var seatMode: TakeSeatMode           // .apply 或 .free
+    var isPublicVisible: Bool
+    var isGiftEnabled: Bool
+    var isMessageDisable: Bool
+    var categoryList: [NSNumber]
+    var metaData: [String: String]
+}
+
+enum SeatLayoutTemplate {
+    case videoDynamicGrid9Seats   // 9格视频动态布局（最常用）
+    case videoDynamicFloat7Seats  // 7格视频浮动布局
+    case videoFixedGrid9Seats
+    case videoFixedFloat7Seats
+    case videoLandscape4Seats
+    case audioSalon(seatCount: Int)
+    case karaoke(seatCount: Int)
+}
+
+// createLive 的回调类型
+typealias LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `liveInfo.seatTemplate` | `SeatLayoutTemplate` | 必须通过 `init(seatTemplate:)` 传入，不可省略 |
+| `liveID` | `String` | 直播间唯一 ID；仅含 ASCII，长度 ≤ 48 字节 |
+| `liveName` | `String` | 显示名称；UTF-8，长度 ≤ 30 字节（约 10 个汉字） |
+| `metaData` | `[String: String]` | 键值对扩展信息；最多 10 key，单值 ≤ 2 KB，总 ≤ 16 KB |
+
+## 代码示例
+
+```swift
+import AtomicXCore
+
+// MARK: - 创建直播间
+
+func createLive(liveID: String, liveName: String, coverURL: String) {
+    // ✅ 正确：使用 init(seatTemplate:) 初始化
+    var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+    liveInfo.liveID       = liveID
+    liveInfo.liveName     = liveName.isEmpty ? "我的直播间" : liveName
+    liveInfo.coverURL     = coverURL
+    liveInfo.isPublicVisible = true
+
+    // ⚠️ createLive 第一参数无标签，completion 返回 LiveInfo（不是 Void）
+    LiveListStore.shared.createLive(liveInfo) { result in
+        switch result {
+        case .success(let createdLiveInfo):
+            // 回调返回完整 LiveInfo（含服务端写入的字段，如 createTime）
+            print("[RoomConfig] 直播间创建成功, liveID: \(createdLiveInfo.liveID)")
+            print("[RoomConfig] 创建时间: \(createdLiveInfo.createTime)")
+            // 跳转直播中页面
+
+        case .failure(let errorInfo):
+            handleCreateLiveError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 参数校验
+
+func validateLiveName(_ name: String) -> Bool {
+    // liveName 限制：UTF-8 字节数 ≤ 30
+    let byteCount = name.utf8.count
+    guard byteCount <= 30 else {
+        print("[RoomConfig] 名称超过 30 字节（约 10 个汉字），当前 \(byteCount) 字节")
+        return false
+    }
+    return true
+}
+
+// MARK: - 更新直播间元数据（开播后动态更新）
+
+func updateMetaData(_ updates: [String: String]) {
+    LiveListStore.shared.updateLiveMetaData(updates) { result in
+        switch result {
+        case .success:
+            print("[RoomConfig] MetaData 更新成功")
+        case .failure(let errorInfo):
+            if errorInfo.code == -2300 {
+                print("[RoomConfig] 权限不足，仅房主/管理员可更新 MetaData")
+            } else {
+                print("[RoomConfig] MetaData 更新失败, code: \(errorInfo.code)")
+            }
+        }
+    }
+}
+
+// MARK: - MetaData 校验（最多 10 key，单值 ≤ 2KB，总 ≤ 16KB）
+
+func buildValidatedMetaData(_ raw: [String: String]) -> [String: String] {
+    var validated: [String: String] = [:]
+    let maxKeyCount  = 10
+    let maxValueBytes = 2 * 1024    // 2 KB
+    let maxTotalBytes = 16 * 1024   // 16 KB
+    var totalBytes    = 0
+
+    for (key, value) in raw.prefix(maxKeyCount) {
+        let valueBytes = value.utf8.count
+        guard valueBytes <= maxValueBytes else {
+            print("[RoomConfig] key '\(key)' 值超过 2KB，已跳过")
+            continue
+        }
+        guard totalBytes + valueBytes <= maxTotalBytes else {
+            print("[RoomConfig] MetaData 总大小超过 16KB，已停止添加")
+            break
+        }
+        validated[key] = value
+        totalBytes += valueBytes
+    }
+    return validated
+}
+
+// MARK: - 错误处理
+
+func handleCreateLiveError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -2105: print("直播间 ID 格式非法（须为 ASCII，≤ 48 字节）")
+    case -2107: print("直播间名称非法（UTF-8，≤ 30 字节）")
+    case -2108: print("您已在其他直播间，请先退出后再试")
+    default:    print("创建失败（code: \(errorInfo.code)）: \(errorInfo.message)")
+    }
+}
+```
+
+## 调用时序
+
+```
+设备已就绪（openLocalCamera + openLocalMicrophone 成功）
+        │
+        ▼
+构建 LiveInfo
+// ⚠️ 必须：LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+// 设置 liveID / liveName / coverURL 等字段
+        │
+        ▼
+客户端校验
+├── liveName UTF-8 字节数 ≤ 30？
+├── MetaData 单值 ≤ 2KB？
+└── MetaData 总大小 ≤ 16KB？
+        │
+        ▼
+// ⚠️ 第一参数无标签
+LiveListStore.shared.createLive(liveInfo) { result in ... }
+        │
+        ├─ .failure(errorInfo)
+        │       ├─ code -2105 → liveID 格式错误
+        │       ├─ code -2107 → liveName 超长/非法
+        │       └─ code -2108 → 已在其他房间
+        │
+        └─ .success(createdLiveInfo)   ← 包含服务端写入字段
+                │
+                ▼
+        进入直播中状态
+        （监听 liveListEventPublisher 生命周期事件）
+```
+
+## 平台特有注意事项
+
+### 1. LiveInfo 必须用 `init(seatTemplate:)` 初始化
+`LiveInfo` **没有无参初始化方法**（`LiveInfo()` 不正确）。必须传入 `SeatLayoutTemplate`：
+```swift
+// ✅ 正确
+var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+
+// ❌ 错误：LiveInfo() 无此初始化方法
+var liveInfo = LiveInfo()
+```
+
+### 2. createLive 第一参数无标签
+`createLive` 签名为 `createLive(_ liveInfo: LiveInfo, completion:)`，第一参数**无标签**：
+```swift
+// ✅ 正确（无标签）
+LiveListStore.shared.createLive(liveInfo) { result in ... }
+
+// ❌ 错误（带标签）
+LiveListStore.shared.createLive(liveInfo: liveInfo) { ... }
+```
+
+### 3. createLive completion 返回 LiveInfo，不是 Void
+`LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void`，成功时回调携带服务端确认后的 `LiveInfo`（含 `createTime` 等服务端字段），应使用该对象而非本地构建的对象：
+```swift
+case .success(let createdLiveInfo):  // ✅ 使用服务端返回的 LiveInfo
+    navigateToLiveRoom(liveInfo: createdLiveInfo)
+```
+
+### 4. liveName 字节数计算
+Swift 中汉字使用 UTF-8 编码，每个汉字占 3 字节：
+```swift
+let byteCount = liveName.utf8.count  // ✅ 字节数（正确）
+let charCount = liveName.count       // ❌ 字符数不等于字节数
+```
+30 字节 ≈ 10 个汉字 = 30 个英文字母。
+
+### 5. liveID 生成建议
+建议在服务端生成 liveID 并下发：
+- 仅含字母、数字、下划线、连字符
+- 长度控制在 8~32 字节
+- 示例：`live_10001_1711593600`

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

@@ -0,0 +1,353 @@
+---
+id: live/audience-list
+platform: ios
+---
+
+# 观众列表 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**最低系统要求**：iOS 13.0+，Xcode 14.0+
+
+**前置登录与进房**：必须在 `LoginStore.shared.login` 成功且 `liveCoreView.joinLive` 成功后才可调用 `fetchAudienceList`。
+
+## API 调用
+
+```swift
+// 创建观众列表模块（每个直播间独立实例）
+let audienceStore = LiveAudienceStore.create(liveID: String)
+
+// 拉取当前观众列表快照
+audienceStore.fetchAudienceList(completion: CompletionClosure?)
+// CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+// ErrorInfo: .code: Int, .message: String
+
+// 订阅观众实时事件（Combine）
+audienceStore.liveAudienceEventPublisher  // PassthroughSubject<LiveAudienceEvent, Never>
+
+// 订阅状态变化（包含 audienceList 和 audienceCount）
+audienceStore.state  // StatePublisher<LiveAudienceState>
+```
+
+**LiveUserInfo 字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `userID` | `String` | 用户唯一 ID |
+| `userName` | `String` | 显示名称 |
+| `avatarURL` | `String` | 头像 URL |
+
+**LiveAudienceState 字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `audienceList` | `[LiveUserInfo]` | 当前观众数组快照 |
+| `audienceCount` | `UInt` | 观众总数（近似值，受频控影响） |
+| `messageBannedUserList` | `[LiveUserInfo]` | 已被禁言的用户列表 |
+
+**LiveAudienceEvent 枚举**
+
+| 事件 | 说明 |
+|------|------|
+| `.onAudienceJoined(audience: LiveUserInfo)` | 有观众进入直播间 |
+| `.onAudienceLeft(audience: LiveUserInfo)` | 有观众离开直播间 |
+| `.onAudienceMessageDisabled(audience: LiveUserInfo, isDisable: Bool)` | 某观众禁言状态变更 |
+| `.onOwnerJoined(owner: LiveUserInfo)` | 房主进入直播间（4.1.0+） |
+| `.onOwnerLeft(owner: LiveUserInfo)` | 房主离开直播间（4.1.0+） |
+| `.onAdminJoined(admin: LiveUserInfo)` | 管理员进入直播间（4.1.0+） |
+| `.onAdminLeft(admin: LiveUserInfo)` | 管理员离开直播间（4.1.0+） |
+
+> **MUST**: switch LiveAudienceEvent 时必须添加 `default` 分支，因为枚举可能在后续版本继续扩展。
+
+## 代码示例
+
+### 1. 创建、拉取列表与订阅事件
+
+```swift
+import AtomicXCore
+import Combine
+import UIKit
+
+final class AudienceListViewModel {
+
+    // MARK: - Properties
+
+    private(set) var audienceList: [LiveUserInfo] = []
+    private(set) var audienceCount: UInt = 0
+
+    private var audienceStore: LiveAudienceStore?
+    private var cancellables = Set<AnyCancellable>()
+
+    // UI 刷新回调（通知 ViewController）
+    var onListUpdated: (() -> Void)?
+    var onCountUpdated: ((UInt) -> Void)?
+
+    // MARK: - 初始化（进房成功后调用）
+
+    func setup(liveID: String) {
+        // Step 1: 创建 LiveAudienceStore 实例
+        audienceStore = LiveAudienceStore.create(liveID: liveID)
+
+        // Step 2: 订阅实时事件
+        subscribeEvents()
+
+        // Step 3: 拉取初始列表快照
+        fetchInitialList()
+    }
+
+    // MARK: - 销毁（退出直播间时调用）
+
+    func teardown() {
+        cancellables.removeAll()
+        audienceStore = nil
+        audienceList = []
+        audienceCount = 0
+    }
+
+    // MARK: - 订阅实时进离场事件
+
+    private func subscribeEvents() {
+        audienceStore?.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self = self else { return }
+                switch event {
+                case .onAudienceJoined(let audience):
+                    self.handleAudienceJoined(audience)
+                case .onAudienceLeft(let audience):
+                    self.handleAudienceLeft(audience)
+                case .onAudienceMessageDisabled(let audience, let isDisable):
+                    // 禁言状态变更，可在此刷新 UI 标记
+                    print("[AudienceList] 用户 \(audience.userID) 禁言状态变更: \(isDisable)")
+                default:
+                    break  // 兼容 4.1.0+ 新增 case（onOwnerJoined/Left, onAdminJoined/Left）
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    // MARK: - 拉取初始列表
+
+    private func fetchInitialList() {
+        audienceStore?.fetchAudienceList { [weak self] result in
+            DispatchQueue.main.async {
+                guard let self = self else { return }
+                switch result {
+                case .success:
+                    // 从 state.value 中取最新快照（state 是 StatePublisher，必须通过 .value 访问）
+                    self.audienceList = self.audienceStore?.state.value.audienceList ?? []
+                    self.audienceCount = self.audienceStore?.state.value.audienceCount ?? 0
+                    self.onListUpdated?()
+                    self.onCountUpdated?(self.audienceCount)
+                case .failure(let error):
+                    print("[AudienceList] fetchAudienceList failed code=\(error.code) msg=\(error.message)")
+                }
+            }
+        }
+    }
+
+    // MARK: - 事件处理
+
+    private func handleAudienceJoined(_ audience: LiveUserInfo) {
+        // 避免重复插入
+        guard !audienceList.contains(where: { $0.userID == audience.userID }) else { return }
+        audienceList.insert(audience, at: 0)   // 新观众插入列表头部
+        audienceCount = audienceStore?.state.value.audienceCount ?? audienceCount + 1
+        onListUpdated?()
+        onCountUpdated?(audienceCount)
+    }
+
+    private func handleAudienceLeft(_ audience: LiveUserInfo) {
+        audienceList.removeAll { $0.userID == audience.userID }
+        audienceCount = audienceStore?.state.value.audienceCount ?? (audienceCount > 0 ? audienceCount - 1 : 0)
+        onListUpdated?()
+        onCountUpdated?(audienceCount)
+    }
+}
+```
+
+### 2. 单列 UICollectionView 展示
+
+```swift
+import UIKit
+
+final class AudienceListViewController: UIViewController {
+
+    private let viewModel = AudienceListViewModel()
+
+    // MARK: - UI
+
+    private lazy var countLabel: UILabel = {
+        let label = UILabel()
+        label.font = .systemFont(ofSize: 14, weight: .medium)
+        label.textColor = .white
+        return label
+    }()
+
+    private lazy var collectionView: UICollectionView = {
+        let layout = UICollectionViewFlowLayout()
+        layout.scrollDirection = .vertical
+        layout.itemSize = CGSize(width: UIScreen.main.bounds.width, height: 60)
+        layout.minimumLineSpacing = 0
+        let cv = UICollectionView(frame: .zero, collectionViewLayout: layout)
+        cv.register(AudienceCell.self, forCellWithReuseIdentifier: "AudienceCell")
+        cv.dataSource = self
+        cv.backgroundColor = .clear
+        return cv
+    }()
+
+    // MARK: - Setup
+
+    init(liveID: String) {
+        super.init(nibName: nil, bundle: nil)
+        viewModel.setup(liveID: liveID)
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        setupUI()
+        bindViewModel()
+    }
+
+    deinit {
+        viewModel.teardown()
+    }
+
+    private func setupUI() {
+        view.addSubview(countLabel)
+        view.addSubview(collectionView)
+        // 布局代码省略
+    }
+
+    private func bindViewModel() {
+        viewModel.onListUpdated = { [weak self] in
+            self?.collectionView.reloadData()
+        }
+        viewModel.onCountUpdated = { [weak self] count in
+            // ⚠️ 人数仅展示，加"约"字说明非精确值
+            self?.countLabel.text = "约 \(count) 人在看"
+        }
+    }
+}
+
+extension AudienceListViewController: UICollectionViewDataSource {
+    func collectionView(_ cv: UICollectionView,
+                        numberOfItemsInSection section: Int) -> Int {
+        viewModel.audienceList.count
+    }
+
+    func collectionView(_ cv: UICollectionView,
+                        cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
+        let cell = cv.dequeueReusableCell(withReuseIdentifier: "AudienceCell",
+                                          for: indexPath) as! AudienceCell
+        cell.configure(with: viewModel.audienceList[indexPath.item])
+        return cell
+    }
+}
+
+// MARK: - 双列布局（可选）
+
+extension AudienceListViewController {
+    /// 切换为双列显示（适合大观众列表）
+    func switchToDoubleColumnLayout() {
+        guard let layout = collectionView.collectionViewLayout
+                as? UICollectionViewFlowLayout else { return }
+        let padding: CGFloat = 8
+        let itemWidth = (UIScreen.main.bounds.width - padding * 3) / 2
+        layout.itemSize = CGSize(width: itemWidth, height: 56)
+        layout.minimumInteritemSpacing = padding
+        layout.minimumLineSpacing = padding
+        layout.sectionInset = UIEdgeInsets(top: padding, left: padding,
+                                           bottom: padding, right: padding)
+        collectionView.reloadData()
+    }
+}
+
+// MARK: - Cell
+
+final class AudienceCell: UICollectionViewCell {
+
+    private let avatarImageView = UIImageView()
+    private let nameLabel = UILabel()
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupUI()
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    private func setupUI() {
+        avatarImageView.layer.cornerRadius = 20
+        avatarImageView.clipsToBounds = true
+        contentView.addSubview(avatarImageView)
+        contentView.addSubview(nameLabel)
+        // 布局代码省略
+    }
+
+    func configure(with user: LiveUserInfo) {
+        nameLabel.text = user.userName
+        // 加载头像（使用业务图片加载框架）
+        if let url = URL(string: user.avatarURL) {
+            // e.g. avatarImageView.sd_setImage(with: url)
+            _ = url  // 占位
+        }
+    }
+}
+```
+
+## 调用时序
+
+```
+LoginStore.login 成功
+    │
+    ▼
+liveCoreView.joinLive 成功
+    │
+    ▼
+LiveAudienceStore.create(liveID:)       ← 每个直播间独立实例
+    │
+    ▼
+audienceStore.liveAudienceEventPublisher 订阅（PassthroughSubject）
+    │
+    ▼
+audienceStore.fetchAudienceList          ← 获取初始快照
+    │
+    ├─ .failure(ErrorInfo) → 检查登录态 / 进房状态（error.code / error.message）
+    └─ .success → 读取 state.audienceList → reloadData
+            │
+            ▼
+        实时事件推送
+        ├─ .onAudienceJoined(audience:) → 插入列表头 → reloadData
+        ├─ .onAudienceLeft(audience:)   → 移除列表项 → reloadData
+        └─ .onAudienceMessageDisabled(audience:isDisable:) → 更新禁言标记
+            │
+            ▼
+        退出直播间
+        └─ audienceStore = nil（释放订阅与资源）
+```
+
+## 平台特有注意事项
+
+### 1. AnyCancellable 必须存储在实例变量中
+
+若将 `liveAudienceEventPublisher.sink` 返回的 `AnyCancellable` 存在局部变量而非 `Set<AnyCancellable>` 实例变量中，订阅会在函数返回后立即释放，导致后续所有事件静默丢弃。务必使用 `.store(in: &cancellables)` 持久化订阅。
+
+### 2. 主线程刷新 UI
+
+`liveAudienceEventPublisher` 的事件可能在后台线程分发。始终使用 `.receive(on: DispatchQueue.main)` 切换到主线程再更新 `audienceList` 和 `collectionView`，否则会触发 `UIKit` 主线程访问警告或崩溃。
+
+### 3. audienceCount 类型为 UInt
+
+`LiveAudienceState.audienceCount` 是 `UInt` 类型（非 `Int`）。UI 展示时建议显示"约 X 人在看"，而非精确数字。由于频控（40条/秒），在万人以上直播间中 `audienceCount` 可能与实际值相差数百，不要用它做业务逻辑判断（如活动奖励门槛）。
+
+### 4. 离场延迟：90 秒心跳窗口
+
+观众因网络断开（非主动退出）时，系统需等待约 90 秒心跳超时后才会触发 `onAudienceLeft`。UI 上观众头像可能在对方已断网后仍显示数分钟，属正常现象，无需特殊处理。