@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/ios/login-auth.md

@@ -0,0 +1,247 @@
+---
+id: live/login-auth
+platform: ios
+---
+
+# 登录与鉴权 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**Info.plist 权限声明**（推流场景必须配置，否则 iOS 14+ 设备调用设备接口时崩溃）
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问摄像头以进行视频直播</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>需要访问麦克风以进行语音直播</string>
+```
+
+**最低系统要求**：iOS 13.0+，Xcode 14.0+
+
+## API 调用（真实签名）
+
+```swift
+// 登录
+LoginStore.shared.login(
+    sdkAppID: Int32,              // ⚠️ Int32，不是 Int
+    userID: String,
+    userSig: String,
+    completion: CompletionClosure? // (Result<Void, ErrorInfo>) -> Void
+)
+
+// 登出
+LoginStore.shared.logout(completion: CompletionClosure?)
+
+// 更新用户资料
+LoginStore.shared.setSelfInfo(userProfile: UserProfile, completion: CompletionClosure?)
+
+// 状态订阅（Combine）
+LoginStore.shared.state          // StatePublisher<LoginState>
+// LoginState.loginStatus: LoginStatus
+// LoginState.loginUserInfo: UserProfile?
+
+// 被动事件订阅
+LoginStore.shared.loginEventPublisher  // PassthroughSubject<LoginEvent, Never>
+// LoginEvent.kickedOffline    — 被踢下线
+// LoginEvent.loginExpired     — 登录票据过期
+```
+
+**通用类型**
+```swift
+typealias CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+struct ErrorInfo {
+    var code: Int
+    var message: String
+}
+
+enum LoginEvent {
+    case kickedOffline
+    case loginExpired
+}
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `sdkAppID` | `Int32` | 腾讯云控制台的应用 ID（**Int32**，注意不是 Int） |
+| `userID` | `String` | 用户唯一标识，ASCII 字母/数字/`-`/`_`，≤ 32 字节 |
+| `userSig` | `String` | 后端签发的鉴权票据 |
+| `completion` | `CompletionClosure?` | 异步回调 `(Result<Void, ErrorInfo>) -> Void`，在主线程返回 |
+
+## 代码示例
+
+```swift
+import AtomicXCore
+import Combine
+
+// MARK: - 登录
+
+func login(sdkAppID: Int32,   // ⚠️ Int32
+           userID: String,
+           userSig: String) {
+    LoginStore.shared.login(sdkAppID: sdkAppID,
+                            userID: userID,
+                            userSig: userSig) { result in
+        switch result {
+        case .success:
+            print("[Login] 登录成功")
+            // 登录成功后可操作设备 / 进入房间
+
+        case .failure(let errorInfo):
+            // errorInfo 是 ErrorInfo 结构体，不是 Swift Error
+            print("[Login] 登录失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+            handleLoginError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 登出
+
+func logout() {
+    LoginStore.shared.logout { result in
+        switch result {
+        case .success:
+            print("[Login] 登出成功")
+        case .failure(let errorInfo):
+            print("[Login] 登出失败, code: \(errorInfo.code)")
+        }
+    }
+}
+
+// MARK: - 错误分类处理
+
+func handleLoginError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -1000:
+        print("SDKAppID 不合法，请检查控制台配置")
+    case -1001:
+        print("UserSig 已过期或参数不合法，请重新获取")
+    default:
+        print("未知登录错误：\(errorInfo.code) - \(errorInfo.message)")
+    }
+}
+
+// MARK: - 被动事件监听（踢下线 / 票据过期）
+
+var cancellables = Set<AnyCancellable>()
+
+func subscribeLoginEvents() {
+    LoginStore.shared.loginEventPublisher
+        .receive(on: DispatchQueue.main)
+        .sink { event in
+            switch event {
+            case .kickedOffline:
+                print("[Login] 被踢下线，需重新登录")
+                // 引导用户重新登录
+
+            case .loginExpired:
+                print("[Login] 登录票据已过期，需刷新 UserSig 后重新登录")
+                // 从业务后端刷新 UserSig 后重新调用 login
+            }
+        }
+        .store(in: &cancellables)
+}
+
+// MARK: - 状态查询（通过 state 订阅）
+
+func observeLoginState() {
+    LoginStore.shared.state
+        .receive(on: DispatchQueue.main)
+        .sink { loginState in
+            print("[Login] 状态: \(loginState.loginStatus)")
+            if let profile = loginState.loginUserInfo {
+                print("[Login] 当前用户: \(profile.userID)")
+            }
+        }
+        .store(in: &cancellables)
+}
+```
+
+**典型调用流程（从业务后端获取 UserSig 后登录）**：
+```swift
+// Step 1: 从业务后端获取 UserSig（伪代码）
+YourAPI.fetchUserSig(userID: "user_001") { userSig in
+    guard let userSig = userSig else { return }
+
+    // Step 2: 登录 SDK
+    // ⚠️ sdkAppID 必须传 Int32 字面量或显式转换
+    LoginStore.shared.login(sdkAppID: 1400000001,
+                            userID: "user_001",
+                            userSig: userSig) { result in
+        switch result {
+        case .success:
+            // Step 3: 登录成功后才可操作设备 / 进入房间
+            setupDevices()
+        case .failure(let errorInfo):
+            showAlert(message: "登录失败: \(errorInfo.message)")
+        }
+    }
+}
+```
+
+## 调用时序
+
+```
+App 启动
+    │
+    ▼
+从业务后端获取 UserSig
+    │
+    ├─ 失败 ──→ 展示网络错误，引导重试
+    │
+    ▼
+LoginStore.shared.login(sdkAppID: Int32, userID:, userSig:)
+    │
+    ├─ .failure(errorInfo)
+    │       ├─ code -1000 → 核查 SDKAppID（Int32）
+    │       ├─ code -1001 → 检查 UserSig 有效期 / UserID 格式
+    │       └─ 其他      → 上报日志，提示用户
+    │
+    └─ .success
+            │
+            ▼
+        订阅 loginEventPublisher（监听踢下线/过期）
+            │
+            ▼
+        进入主功能流程
+        （设备初始化 / 进入房间 / 开始推流）
+```
+
+## 平台特有注意事项
+
+### 1. sdkAppID 类型必须是 Int32
+Swift 类型推断会将整数字面量视为 `Int`。传入 `login()` 时若将 `Int` 变量隐式传递给 `Int32` 参数，编译器会报错：
+```swift
+let appID: Int = 1400000001     // ❌ 编译错误：不能将 Int 赋值给 Int32
+let appID: Int32 = 1400000001   // ✅ 正确
+// 或直接传字面量（Swift 自动推断 Int32）：
+LoginStore.shared.login(sdkAppID: 1400000001, ...)  // ✅ 字面量可自动匹配 Int32
+```
+
+### 2. ErrorInfo 是结构体，不是 Error 协议
+SDK 回调返回的是 `ErrorInfo` 结构体，**不是** `Swift.Error`。不可将其强转为 `Error` 或使用 `localizedDescription`：
+```swift
+case .failure(let errorInfo):
+    let code = errorInfo.code       // ✅ 直接访问 .code
+    let msg  = errorInfo.message    // ✅ 直接访问 .message
+    // errorInfo.localizedDescription  // ❌ 不存在此属性
+```
+
+### 3. Info.plist 权限缺失导致崩溃
+iOS 14+ 系统在首次访问相机/麦克风时，若未在 `Info.plist` 中声明 `NSCameraUsageDescription` 或 `NSMicrophoneUsageDescription`，App **直接崩溃**（不返回错误码）。务必在集成 SDK 时同步添加权限描述。
+
+### 4. 进入后台后网络断连
+App 切入后台超过约 30 秒后，iOS 系统可能中断 TCP 长连接，导致登录态失效并触发 `loginEventPublisher` 的 `.loginExpired` 事件。建议：
+- 订阅 `UIApplication.willEnterForegroundNotification`
+- 前台恢复时通过 `LoginStore.shared.state` 检查 `loginStatus`
+- 如已失效，刷新 UserSig 后重新调用 `login`
+
+### 5. UserSig 刷新策略
+UserSig 有有效期（建议后端配置 7 天），客户端应：
+- 在签发时记录过期时间戳（`exp` 字段）
+- App 启动或前台恢复时检查是否在有效期内
+- 距离过期 ≤ 1 小时时主动向后端刷新，避免直播中途 UserSig 失效中断推流

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

@@ -0,0 +1,82 @@
+---
+id: live/live-list
+name: 直播列表
+product: live
+tags: [list, fetch, category, slide-play, LiveListStore]
+platforms: [ios, android, web, flutter]
+related: [live/audience-watch, live/login-auth]
+---
+
+# 直播列表
+
+## 功能说明
+
+`LiveListStore` 是负责查询直播间列表的全局单例，观众端通过它拉取当前正在开播的直播列表、支持分页加载与分类筛选，并可根据 `seatLayoutTemplateID` 区分语聊房（1–199）与视频直播（200–999）。
+
+核心入口：调用 `LiveListStore` 的 `fetchLiveList` 方法，传入分页游标（cursor）和拉取数量（count），通过成功/失败回调获取结果。
+
+拉取到列表后，将 `liveID` 传给 `LiveCoreView` 实现滑动播放。**每个列表 Cell 必须持有独立的 `LiveCoreView` 实例**，严禁跨 Cell 复用同一实例。
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **LiveListStore** | 全局单例，负责列表拉取与直播状态监听 |
+| **LiveListState** | 当前状态快照；`liveList` 保存已拉取的 `LiveInfo` 列表，`currentLive` 保存正在观看的直播信息 |
+| **LiveListEvent** | 异步事件；`onLiveEnded` 表示直播结束，`onKickedOutOfLive` 表示被移出直播间 |
+| **LiveInfo** | 单条直播数据；含 `liveID`、`categoryList`、`seatLayoutTemplateID`、`metaData` 等字段 |
+| **cursor** | 分页游标字符串；首次请求传空字符串 `""`，后续传上一次返回值；返回空字符串表示已到末页 |
+| **count** | 单次拉取数量，推荐值 20，不宜超过 50 |
+| **categoryList** | 直播分类标签数组，用于客户端筛选，不参与服务端过滤 |
+| **seatLayoutTemplateID** | 房间类型标识；1–199 为语聊房，200–999 为视频直播 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **使用 cursor 分页加载** — 首次传 `""`, 每次成功回调后保存返回的新 cursor；当返回 cursor 为空字符串时停止加载更多。
+2. **每个滑动列表 Cell 持有独立 LiveCoreView** — 在列表 Cell 初始化时创建 `LiveCoreView` 并添加到视图层级，Cell 间绝不共享实例。
+3. **在 Cell 可见/不可见时管理播放生命周期** — Cell 可见时调用 `setLiveID` + 预加载，Cell 不可见时立即停止播放并释放资源，防止内存堆积。
+4. **客户端按 seatLayoutTemplateID 或 liveID 前缀过滤** — 服务端不按类型过滤，需在回调中对 `liveList` 做本地筛选再渲染。
+5. **订阅 LiveListEvent.onLiveEnded** — 直播结束时及时从列表中移除对应条目并刷新 UI，避免用户点击已结束的直播间。
+
+### ❌ NEVER
+
+1. **一次性拉取全部列表** — 直播间数量可能很大，无分页地全量请求会导致超时与内存压力。
+2. **复用同一个 LiveCoreView 给多个 Cell** — 内部状态不可共享，复用会导致画面撕裂、音频冲突或崩溃。
+3. **在列表页同时播放多路流** — 滑动列表场景下同时解码多路视频会大幅消耗 CPU/GPU，应确保任意时刻只有当前可见 Cell 在播放。
+4. **忽略 onKickedOutOfLive 事件** — 用户被踢出后若不处理，UI 会停留在空播放状态且无任何提示。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1002` | 未登录 | 确保 `LoginStore` 的 `login` 成功后再调用 `fetchLiveList` |
+| 列表返回空 | 正常情况：当前无开播直播 | 展示"暂无直播"空态 UI；检查 categoryList 筛选条件是否过严 |
+| 列表卡顿/内存增长 | Cell 复用时 LiveCoreView 未释放 | 在 Cell 不可见时调用停播接口；确认每个 Cell 使用独立实例 |
+
+### 排障流程
+
+```
+fetchLiveList 拉不到数据
+├── 是否已登录？ → 否 → 先完成 LoginStore.login
+├── cursor 是否正确传递？ → 检查首次是否传 ""
+├── 网络是否可用？ → 检查连接与防火墙
+└── 返回空列表（非错误）→ 当前确实无开播直播，展示空态
+
+列表显示后滑动卡顿
+├── 检查每个 Cell 是否独立持有 LiveCoreView
+├── 检查 Cell 不可见时是否停播
+└── 检查是否在主线程刷新 UI
+
+收到 onLiveEnded / onKickedOutOfLive 后 UI 无变化
+└── 确认已订阅 LiveListEvent 并在回调中刷新列表
+```
+
+## 关联知识
+
+- **[live/audience-watch](live/audience-watch.md)** — 从列表选中直播间后进房观看
+- **[live/login-auth](live/login-auth.md)** — fetchLiveList 需登录态，必须先完成鉴权
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/knowledge-base/slices/live/login-auth.md

@@ -0,0 +1,78 @@
+---
+id: live/login-auth
+name: 登录与鉴权
+product: live
+tags: [login, auth, SDKAppID, UserID, UserSig, LoginStore]
+platforms: [ios, android, web, flutter]
+related: [live/device-control, live/anchor-preview, live/audience-watch]
+---
+
+# 登录与鉴权
+
+## 功能说明
+
+`LoginStore` 是所有 Live 功能的前置依赖，负责完成 TRTC SDK 的初始化与用户身份鉴权。所有主播推流、观众拉流、连麦等能力均需在登录成功后才可调用。
+
+核心入口：调用 LoginStore 的 `login` 方法，传入 SDKAppID、UserID、UserSig，通过回调获取登录结果。
+
+登录成功后 LoginStore 作为全局单例持有会话状态，其他 Store（DeviceStore、RoomStore 等）依赖其登录态运行。
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **SDKAppID** | 腾讯云控制台创建应用后分配的唯一数字 ID，用于区分不同应用的流量与计费 |
+| **UserID** | 业务侧自定义的用户唯一标识，仅允许 ASCII 字母、数字、连字符 `-`、下划线 `_`，长度 ≤ 32 字节 |
+| **UserSig** | 由业务后端使用 SecretKey 签发的鉴权票据，具有有效期（建议 7 天），过期后需重新签发 |
+| **LoginStore** | SDK 全局单例，持有登录态；登录成功后其他 Store 方可使用 |
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **在业务后端生成 UserSig** — 将 SDKSecretKey 保管在服务器端，客户端通过接口获取 UserSig，禁止在客户端直接使用 SecretKey 签发。
+2. **登录成功后才调用其他 API** — 在 `login` 的成功回调中再初始化 DeviceStore、进入房间等操作，避免因登录未完成导致 `-1002` 错误。
+3. **声明系统权限** — 推流场景需在各平台声明相机与麦克风权限（各平台方式不同 → 见平台文件），否则调用设备接口时会被系统拒绝或崩溃。
+4. **监听登录状态变化** — 注册登录状态变更回调，处理后台断连、UserSig 过期等场景，及时触发重新登录或 UI 提示。
+
+### ❌ NEVER
+
+1. **客户端硬编码 SecretKey** — 一旦 App 包被逆向，SecretKey 泄露将导致所有用户的 UserSig 可被伪造，造成安全事故。
+2. **使用过期 UserSig** — 过期票据会导致登录失败（`-1001`），需在签发时记录有效期并在到期前刷新。
+3. **忽略登录回调错误** — 失败回调必须处理，至少向用户展示提示并上报错误日志，不可静默忽略导致后续所有功能异常。
+
+## 排障指南
+
+### 常见错误码
+
+| 错误码 | 描述 | 处理建议 |
+|--------|------|----------|
+| `-1000` | SDKAppID 未找到 / 不合法 | 核对控制台 App 列表中的 SDKAppID，确认传入类型为 `Int` |
+| `-1001` | 参数不合法（含 UserSig 过期/格式错误） | 检查 UserID 是否包含非法字符；重新从后端获取最新 UserSig |
+| `-1002` | 未登录，调用了需要登录态的 API | 确保在 `login` 成功回调后再调用其他接口 |
+
+### 排障流程
+
+```
+登录失败
+├── 错误码 -1000
+│   ├── 检查 SDKAppID 是否与控制台一致
+│   └── 确认 SDKAppID 类型为 Int（非 String）
+├── 错误码 -1001
+│   ├── UserSig 是否已过期？→ 重新签发
+│   ├── UserID 是否含非 ASCII 字符或超过 32 字节？→ 修正
+│   └── UserSig 是否由正确 SDKAppID 对应的 SecretKey 签发？→ 核对
+├── 错误码 -1002（其他接口返回）
+│   ├── 是否在 login 完成前调用了其他接口？→ 移入登录成功回调中
+│   └── 登录态是否已失效（后台断连/UserSig 过期）？→ 重新登录
+└── 其他
+    ├── 检查网络连通性（是否能访问 trtc.io）
+    └── 抓取完整 error.code + error.message 上报
+```
+
+## 关联知识
+
+- **[live/device-control](live/device-control.md)** — 登录成功后初始化摄像头与麦克风
+- **[live/anchor-preview](live/anchor-preview.md)** — 主播预览需先完成登录
+- **[live/audience-watch](live/audience-watch.md)** — 观众观看流同样依赖登录态
+- **[live/error-codes](live/error-codes.md)** — 完整错误码参考

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tencent-rtc/trtc-agent-skills",
+  "version": "0.1.0",
+  "description": "Installer for the TRTC Agent Skills suite (Chat, Call, RTC Engine, Live, Conference) + knowledge base, with one-command MCP setup for Claude Code / Cursor / CodeBuddy / Codex.",
+  "bin": {
+    "trtc-agent-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "knowledge-base/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "trtc",
+    "real-time-communication",
+    "video-conference",
+    "live-streaming",
+    "chat",
+    "webrtc",
+    "sdk-integration",
+    "ai-skill",
+    "mcp"
+  ],
+  "author": {
+    "name": "Tencent TRTC Team"
+  },
+  "homepage": "https://trtc.io",
+  "repository": "https://git.woa.com/jackyixue/trtc-ai-integration",
+  "license": "MIT"
+}