@tencent-rtc/mcp 1.3.9 → 1.4.1

package/resource/doc/livekit/live/ios/workflow.md

@@ -1,454 +0,0 @@
-# Native Live AtomicXCore Code Generation Workflow Instructions (iOS)
-
-## 🚨 Core Principles (Highest Priority)
-
-**The Agent MUST ensure that the generated code compiles and runs successfully. Delivering uncompilable code to the user is strictly prohibited!**
-
-### ⚠️ Mandatory Compilation Verification (Must be executed, cannot be omitted)
-
-**🚫 Prohibited Actions**:
-- ❌ DO NOT assume code is correct based only on `read_lints` checks.
-- ❌ DO NOT use `grep` to filter compilation output (this will cause commands to be skipped).
-- ❌ DO NOT deliver code without compilation verification.
-
-**✅ The Only Correct Way to Verify**:
-
-```bash
-# Step 1: Install dependencies (if needed)
-cd <ProjectDir> && pod install
-
-# Step 2: Compile verification (use tail to limit output)
-cd <ProjectDir> && xcodebuild build \
-  -scheme <SchemeName> \
-  -workspace <WorkspaceName>.xcworkspace \
-  -destination 'generic/platform=iOS' \
-  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
-```
-
-**Judging Criteria**:
-- ✅ Output contains `BUILD SUCCEEDED` → Compilation passed, ready for delivery.
-- ❌ Output contains `BUILD FAILED` or `error:` → Must fix and recompile.
-
-**Common Errors & Fixes**:
-| Error Keyword | Reason | Fix |
-|---------------|--------|-----|
-| `No such module 'xxx'` | Missing Pod dependency | Add to Podfile and run `pod install`. |
-| `Cannot find 'xxx' in scope` | Missing import | Add `import xxx`. |
-| `Use of unresolved identifier` | Incorrect API name | Consult documentation for correct API. |
-| `NSCameraUsageDescription` | Missing Info.plist permission | Add permission description. |
-
-**Verification Loop (Must Follow)**:
-```
-Execute Compilation → Failure → Analyze Error → Fix Code → Re-execute Compilation → ... → BUILD SUCCEEDED → Deliver
-```
-
----
-
-## 📋 Instruction Purpose & Architecture
-
-Provides the Agent with a **code generation blueprint** for implementing core features of Native (iOS) Live AtomicXCore.
-
-**Core Architecture**:
-* **Container**: `LiveCoreView` (View layer)
-* **State**: `Store` (Data-driven)
-* **Events**: `Publisher` (Combine subscription)
-
-**Feature Dependency Logic (Important)**:
-1. **Base First**: Basic live streaming (Broadcasting/Viewing/List) must be completed first using the base tool (`get_native_live_uikit_integration`).
-2. **Interaction Overlay**: If requirements include "Co-guesting", "PK", or "Audience List", the interaction tool (`get_native_live_uikit_interaction`) must be called **after** basic features are completed.
-3. **Empty Project Handling**: If the user requests interaction features in an empty project, the Agent **MUST implement basic features first**, then add interaction capabilities.
-
----
-
-## ⚙️ Automated Workflow Steps (Must be created as TODO tasks)
-
-**🚨 The Agent MUST create the following steps as a TODO task list, complete them one by one, and check them off:**
-
-### Step 1: Preparation
-1. **Generate Credentials**: Call the `get_usersig` tool to generate test credentials.
-    * Host: `anchor001`, `anchor002`, `anchor003`
-    * Audience: `user001`, `user002`, `user003`
-2. **Environment Check**: Check `Podfile` and add the following dependency if missing:
-    ```ruby
-    pod 'AtomicXCore'
-    ```
-3. **Permission Injection**: Add Camera and Microphone permission descriptions in `Info.plist`:
-    ```xml
-    <key>NSCameraUsageDescription</key>
-    <string>Needs camera access to record video.</string>
-    <key>NSMicrophoneUsageDescription</key>
-    <string>Needs microphone access to record audio.</string>
-    ```
-
-### Step 2: Code Generation
-**PRIORITIZE and EXCLUSIVELY** use the **real-time documentation content** returned by this tool for code generation.
-* **Host Only**: Generate `AnchorViewController`.
-* **Audience Only**: Generate `AudienceViewController`.
-* **Host + Audience**: Generate `MainViewController` (Entry selection) + `AnchorViewController` + `AudienceViewController`.
-
-### Step 3: 🚨 Compilation Verification (Mandatory, cannot be skipped)
-**This step MUST be executed as a standalone TODO task, cannot be omitted or merged!**
-
-**Execution Command**:
-```bash
-cd <ProjectDir>/ios && pod install && \
-xcodebuild build -scheme <SchemeName> -workspace <WorkspaceName>.xcworkspace \
-  -destination 'platform=iOS Simulator,name=iPhone 16' \
-  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
-```
-
-**Judgment & Handling**:
-* Output contains **BUILD SUCCEEDED** → Proceed to Step 4.
-* Output contains **BUILD FAILED** or **error:** → Analyze error → Fix code → **Re-execute this command**, loop until success.
-
-### Step 4: Deliver Results
-Deliver the code after confirming compilation passes.
-
----
-
-## 🚫 Code Generation Constraints (Strictly Follow)
-
-### 1. General Code Constraints
-* **Strictly Prohibited to Modify Imports**: Import paths in the documentation are verified; DO NOT modify them.
-* **Strictly Prohibited to Fabricate APIs**: If an API is not in the documentation, DO NOT invent method or parameter names.
-* **MUST Consult API Docs**: For data model fields (e.g., `LiveInfo`), visit the documentation to confirm field names (e.g., confirm it's `liveOwner.userName` and not `name`).
-
-### 2. 🧩 Store & Publisher Management Constraints (Lifecycle Safety)
-**Core Reason**: SDK uses Combine's `Publisher` for state subscription. Incorrect lifecycle management leads to listener failure or memory leaks.
-
-* **Subscription Management Principle**: All `AnyCancellable` **MUST be declared as member variables** of the ViewController in `cancellableSet`.
-* **No Ignoring Return Values**: Prohibited to not store the `AnyCancellable` returned by `.sink {}`.
-* **Pairing Principle**: Setup subscriptions in `viewDidLoad`; they will be automatically released when the `cancellableSet` is deinitialized.
-
-### 3. ⏱️ Timeout Limits (Critical)
-**Strictly adhere to the following parameter limits, prioritizing values from documentation examples:**
-
-#### A. Co-guesting (`CoGuestStore`)
-* **Rules**:
-    * Optional parameter; if not filled, timeout is not checked.
-    * If filled, the range MUST be between **5 - 1800 seconds**.
-* **Correct Examples**:
-    ```swift
-    // ✅ Recommended: Follow doc examples (e.g., 30s)
-    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 30) { ... }
-    // ✅ Valid: No timeout check
-    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 0) { ... }
-    ```
-* **Incorrect Examples**: ❌ `timeout: 3` (too short), ❌ `timeout: 2000` (too long).
-
-#### B. Co-hosting/PK (`CoHostStore`)
-* **Rules**:
-    * **Maximum 30 seconds** (Hard limit).
-* **Correct Examples**:
-    ```swift
-    // ✅ Recommended: Use maximum value
-    CoHostStore.shared.requestHostConnection(..., timeout: 30) { ... }
-    ```
-* **Incorrect Examples**: ❌ `timeout: 60` (will cause request failure).
-
-### 4. 🎨 Extra Feature Constraints (Beauty/Audio/UI)
-
-#### A. Audio Effects
-* **Voice Changer Enum (`AudioChangerType`)**:
-    * ✅ **Allowed**: `.child, .littleGirl, .man, .ethereal`, etc.
-    * ❌ **Prohibited**: `.uncle, .loli, .girl, .boy` (deprecated or incorrect).
-* **Reverb Enum (`AudioReverbType`)**:
-    * ✅ **Allowed**: `.ktv, .smallRoom, .metallic`, etc.
-    * ❌ **Prohibited**: `.room, .hall, .low`.
-
-#### B. Beauty
-* **Parameter Range**: **0.0 - 9.0** (Float).
-    * ❌ NOT 0-1 (Float), and NOT 0-100 (Int).
-* **UI Mapping Formula**: `sliderValue / 100.0 * 9.0`.
-
-#### C. Barrage, Gift & Layout (Barrage, Gift & UI)
-* **Layering Requirements**: Barrage list and full-screen gift animations MUST overlay **on top** of the video layer `LiveCoreView` using a `UIView`.
-* **Split Screen Prohibited**: Strictly prohibited to split the screen (e.g., video on top, barrage at bottom); MUST use overlay mode.
-
-##### Barrage Input
-* **Position**: Fixed at the bottom left of the screen, in the same row as function buttons (Gift, Co-guest, etc.).
-* **Style**: Semi-transparent rounded background + placeholder text "Say something...".
-* **Keyboard Adaptation**:
-    * When the keyboard is raised, the input box **must remain in its original position** and is prohibited from moving up with the keyboard.
-    * The `LiveCoreView` constraint must be fixed to `edges.equalToSuperview()`, prohibiting distortion or upward shifting.
-    * **Strictly Prohibited** to use `UIScrollView.contentInsetAdjustmentBehavior` or automatic constraint adjustments.
-
-##### Barrage Display Flow
-```
-Sending Barrage:
-User input → Click Send/Enter → BarrageStore.sendTextMessage(text) → Insert into local barrage list immediately
-
-Receiving Barrage:
-Subscribe to BarrageStore.barrageState.$barrageList → New message received → Insert into barrage list → Scroll to bottom
-```
-* **Data Source**: Subscribe to `BarrageStore.shared.barrageState.$barrageList`.
-* **Local Echo**: Insert into the local barrage list **immediately** after successful sending, without waiting for server callback.
-* **Scrolling Behavior**: Automatically scroll to the bottom when a new message arrives (`scrollToRow(at: lastIndex, animated: true)`).
-* **Message Format**: `[Nickname]: [Message Content]`, nickname uses theme color, content uses white.
-
-* **Gift Barrage**: **If the user needs gift barrage integration**, when `onReceiveGift` is triggered, a gift message MUST be inserted into the barrage list on **both host and audience sides**. DO NOT display only on the audience side.
-
-##### Full-screen Gift Animation
-**⚠️ MANDATORY**: Full-screen gift animation is a **mandatory requirement** when integrating gift features and cannot be omitted.
-
-* **Layering**: The full-screen gift animation view MUST overlay **on top** of the `LiveCoreView` using a separate `UIView` container.
-* **Layout**: Constrained to `edges.equalToSuperview()`, covering the entire screen.
-* **Dual-side Sync**: Upon receiving the `.onReceiveGift` event, the full-screen animation MUST be played on **both host and audience sides**. Playing only on the audience side is strictly prohibited.
-
-##### ⚠️ SVGA Animation Playback (Mandatory use of SVGAPlayer, Strictly Prohibited to use UIImageView)
-**Strictly Prohibited to use UIImageView/Kingfisher to load .svga files**. SVGA is a vector animation format, not a normal image; UIImageView cannot play it.
-
-* **Dependency Configuration** (Podfile):
-```ruby
-pod 'SVGAPlayer'
-```
-
-* **Core Playback Logic (MUST use SVGAParser + SVGAPlayer)**:
-```swift
-import SVGAPlayer
-
-// ❌ Incorrect: Using UIImageView to load SVGA (cannot play animation)
-// imageView.kf.setImage(with: URL(string: gift.resourceURL))
-
-// ✅ Correct: Using SVGAParser to parse + SVGAPlayer to play
-svgaParser.parse(with: url) { [weak self] videoItem in
-    guard let videoItem = videoItem else { return }
-    self?.svgaPlayer.videoItem = videoItem
-    self?.svgaPlayer.startAnimation()  // Start playing animation
-}
-```
-
-* **Full Implementation Example (Within ViewController)**:
-```swift
-import UIKit
-import AtomicXCore
-import Combine
-import SVGAPlayer
-
-class LiveRoomViewController: UIViewController, SVGAPlayerDelegate {
-    private var cancellables = Set<AnyCancellable>()
-    
-    // SVGA Player Components
-    private let svgaPlayer = SVGAPlayer()
-    private let svgaParser = SVGAParser()
-    
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        setupSVGAPlayer()
-        subscribeGiftEvents()
-    }
-    
-    // 1. Initialize SVGAPlayer
-    private func setupSVGAPlayer() {
-        svgaPlayer.delegate = self
-        svgaPlayer.loops = 1              // Play once
-        svgaPlayer.clearsAfterStop = true // Clear automatically after stopping
-        svgaPlayer.frame = view.bounds    // Full screen
-        svgaPlayer.isHidden = true
-        view.addSubview(svgaPlayer)
-        // Ensure svgaPlayer is at the top level
-        view.bringSubviewToFront(svgaPlayer)
-    }
-    
-    // 2. Subscribe to Gift Events
-    private func subscribeGiftEvents() {
-        let giftStore = GiftStore.create(liveID: liveId)
-        giftStore.giftEventPublisher
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] event in
-                guard case .onReceiveGift(_, let gift, let count, let sender) = event else { return }
-                
-                // Play full-screen gift animation
-                if !gift.resourceURL.isEmpty, let url = URL(string: gift.resourceURL) {
-                    self?.playGiftAnimation(from: url)
-                }
-                
-                // (Optional) Insert gift message into barrage list
-                // let tipText = "\(sender.userName) sent \(gift.name) x \(count)"
-                // barrageStore.appendLocalTip(message: tipText)
-            }
-            .store(in: &cancellables)
-    }
-    
-    // 3. Use SVGAParser to parse and play animation
-    private func playGiftAnimation(from url: URL) {
-        svgaParser.parse(with: url, completionBlock: { [weak self] videoItem in
-            guard let self = self, let videoItem = videoItem else { return }
-            DispatchQueue.main.async {
-                self.svgaPlayer.videoItem = videoItem
-                self.svgaPlayer.isHidden = false
-                self.svgaPlayer.startAnimation()
-            }
-        }, failureBlock: { error in
-            print("SVGA Parse Failed: \(error?.localizedDescription ?? "")")
-        })
-    }
-    
-    // 4. SVGAPlayerDelegate - Playback Finished Callback
-    func svgaPlayerDidFinishedAnimation(_ player: SVGAPlayer!) {
-        svgaPlayer.isHidden = true
-    }
-}
-```
-
-* **Key Checkpoints**:
-    1. ✅ Import `import SVGAPlayer`
-    2. ✅ Use `SVGAParser().parse(with: url)` to parse animation URL
-    3. ✅ Use `SVGAPlayer().startAnimation()` to play animation
-    4. ✅ Implement `SVGAPlayerDelegate` to handle playback end
-    5. ❌ PROHIBITED to use `UIImageView`/`Kingfisher`/`SDWebImage` to load .svga files
-
-### 🎨 Default UI/UX Design & Interaction Specifications (Only applies if user doesn't specify)
-
-**⚠️ Note: The following specifications are only executed as default standards when the user does not provide specific UI design or requirements.**
-
-### 1. Global Aesthetics
-* **Immersive Dark**: The background of the live page must be `.black`, and the video layer (`LiveCoreView`) must **fill the entire screen** (`edges.equalToSuperview()`) and be at the bottom layer.
-* **Safe Area**: All floating UIs must be constrained within the `safeAreaLayoutGuide`, strictly prohibiting being blocked by notches or the bottom Home bar.
-* **Text Readability**: White text above the video (e.g., barrage, ID) must have a **black shadow** (`shadowColor = .black, offset = 0x1`).
-* **Error Prompts**: Use **Toast** uniformly; prohibit the use of modal Alerts that interrupt the user.
-
-### 2. Component Standards
-* **Glass Capsule (Top)**:
-    * **Style**: **Frosted glass background** (`UIBlurEffect.dark`) + **full rounded corners**.
-    * **Application**: Only used at the top left to display "Host Avatar + ID + Popularity".
-* **Flat Buttons**:
-    * **Style**: **"Text + Rounded Rectangle Background"**. Minimalist flat design, background color is semi-transparent black or theme color.
-    * **Close Button**: Special case, use a circular frosted glass icon.
-* **Floating Panels**:
-    * **Style**: Only top rounded corners (`maskedCorners = [.layerMinXMinYCorner, .layerMaxXMinYCorner]`).
-    * **Taboo**: Solid color backgrounds at the bottom are prohibited; floating feeling must be maintained.
-
-### 3. Live Room Layout Blueprint
-**⚠️ Dynamic Layout Principle: Only render function buttons that the user has actually integrated. If a user did not request a feature (e.g., PK/Beauty), DO NOT add corresponding empty buttons.**
-
-#### A. Top Bar
-* **Left [Room Info]**: Wrapped in a **frosted capsule** [Host Avatar | Host Nickname].
-* **Right [Control Area]**: Horizontally arranged [Online Audience Count] + [Close Icon (X)].
-
-#### B. Bottom Bar - Dynamically switches based on state
-* **Preview Mode**:
-    * Content **aligned to the right**: [Beauty] [Audio Effects] [Start Live (Main Button)].
-* **Anchor Live Mode**:
-    * **Left**: [Barrage List (Transparent Background)] + [Chat Input Box].
-    * **Right**: Function array [Beauty] [Audio Effects] [Co-hosting] [PK].
-* **Audience Live Mode**:
-    * **Left**: [Barrage List] + [Chat Input Box].
-    * **Right**: [Gift] [Apply for Co-guesting].
-
-### 4. Home Layout & Interaction
-
-#### A. Home Reference Layout
-```
-┌─────────────────────────────┐
-│       AtomicXCore Live       │
-│                             │
-│  Live Room ID                │
-│  ┌─────────────────────────┐│
-│  │ live_000001             ││  ← Input Box (with left padding, semi-transparent background)
-│  └─────────────────────────┘│
-│                             │
-│  Host Broadcasting           │
-│  (Click to login as anchor001)│
-│                             │
-│  Audience Viewing            │
-│  (Click to login as user001)  │
-│                             │
-│       [ 📋 Live List ]       │
-└─────────────────────────────┘
-```
-
-#### B. Implicit Login Flow
-**No separate login button is required on the home page**; login is automatically completed when a function button is clicked:
-* Click "Host Broadcasting" → Login using `anchor001` → Jump to host page.
-* Click "Audience Viewing" → Login using `user001` → Jump to audience page.
-* Click "Live List" → Login using `user001` → Jump to list page.
-
----
-
-## 🎯 Implementation Details
-
-### 1. Host Broadcasting (`host_streaming`)
-* **Core**: `LiveCoreView(viewType: .pushView)`
-* **Flow**: `LiveListStore.shared.createLive()`
-* **Cleanup**: `deinit` or when exiting the page, `endLive()` MUST be called.
-
-### 2. Audience Viewing (`audience_streaming`)
-* **Core**: `LiveCoreView(viewType: .playView)`
-* **Flow**: `LiveListStore.shared.joinLive()`
-* **Cleanup**: `deinit` or when exiting the page, `leaveLive()` MUST be called.
-
-### 3. Live List (`live_list`)
-* **Core**: `LiveListStore.shared.fetchLiveList()` + `UITableView/UICollectionView`
-* **Data**: Subscribe to `liveState.liveList`.
-* **Navigation**: Clicking a list item navigates to the audience page, passing the `liveID`.
-
-### 4. Co-guest & Co-host Interaction Specifications (`co_guest` & `co_host`)
-
-#### A. Audience Co-guesting (Host passively receives)
-* **Host UI**: ❌ **Strictly prohibited** to display a "Co-guest Application" list button in the bottom toolbar or anywhere else.
-* **Interaction Logic**: Upon receiving a co-guest application callback, pop up a dialog (`UIAlertController`) directly in the center of the screen:
-    * **Title**: Co-guest Application
-    * **Content**: Received a co-guest application from audience [Nickname], accept?
-    * **Operations**: [Decline] [Accept]
-
-#### B. Host Co-hosting Panel (Pops up when clicking bottom [Co-host] button)
-* **Presentation**: Use a bottom floating panel (`UIView` animated up); prohibit `UIAlertController`.
-* **UI Layout (Strictly follow illustration)**:
-```
-┌─────────────────────────────────────┐
-│                                     │
-│  Initiate Connection   [🚪 End Co-host]  │  ← Red text
-│                                     │
-│  Connected (2 persons)               │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] Li Ziming [💎20]      PK...   ││  ← Connected users
-│  │ [👤] Filinna  [💎32]      PK...   ││
-│  └─────────────────────────────────┘│
-├─────────────────────────────────────┤
-│  Other Live Users                   │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] Li Ziming [💎20]  [Cancel Inv] ││  ← Gray-black background button
-│  │ [👤] Filinna  [💎32]  [Invite]      ││  ← Blue background button
-│  │ [👤] Tie Zhu   [💗99]  [Invite]      ││
-│  └─────────────────────────────────┘│
-└─────────────────────────────────────┘
-```
-
-#### C. PK Button Interaction Constraints
-* **Pre-check**: When clicking the bottom [PK] button, current connection status must be checked (`CoHostStore.shared.connectedUsers.isEmpty`).
-* **Status Handling**:
-    * **Not connected**: ❌ Prohibit jump, show Toast: `"Please initiate co-hosting first"`.
-    * **Connected**: ✅ Pop up PK invitation panel.
-
----
-
-## 📋 Agent Final Checklist
-
-### 🚨 Must-do Items (None can be omitted)
-- [ ] **🔴 Compilation Verification**: Executed the following command and output contains **BUILD SUCCEEDED** (This item must be explicitly listed in the TODO task)
-  ```bash
-  xcodebuild build -scheme <ProjectName> -workspace <ProjectName>.xcworkspace -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "(error:|warning:.*\.swift|BUILD SUCCEEDED|BUILD FAILED)" | head -30
-  ```
-- [ ] **Credential Injection**: Called `get_usersig` to generate test credentials.
-- [ ] **Dependencies Complete**: Checked `Podfile` and Info.plist permissions.
-
-### Code Quality Check
-- [ ] **API Accuracy**: Imports not modified, APIs not fabricated, `LiveInfo` field names verified.
-- [ ] **Timeout Compliance**: Co-guesting 5-1800s, Co-hosting ≤30s.
-- [ ] **Extra Feature Compliance**: Audio enums correct, beauty range 0-9, barrage layout overlays, and keyboard adaptation.
-- [ ] **Gift Compliance**: Full-screen gift animations implemented on both host and audience sides.
-
----
-
-## 🚨 Security Reminder (Code Comment Template)
-
-```swift
-/**
- * ⚠️ Test Credential Warning
- * - Current userSig is automatically generated by development tools and is valid for 7 days.
- * - ❌ PROHIBITED from generating userSig on the client side in production.
- * - ✅ userSig MUST be generated on a backend service before official launch.
- * - Reference: https://trtc.io/document/35166?product=live&menulabel=uikit&platform=ios
- */
-```