@tencent-rtc/mcp 1.3.6 → 1.3.7

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

@@ -0,0 +1,353 @@
+
+# Native Live AtomicXCore Code Generation Workflow Instructions (Flutter)
+
+## 🚨 Core Principles (Highest Priority)
+
+**Agent MUST ensure the generated code compiles and runs successfully. Delivering non-buildable code to users is STRICTLY PROHIBITED!**
+
+### ⚠️ Mandatory Build Verification
+
+**After every code generation/modification, a full build verification MUST be executed**:
+
+```bash
+flutter build apk --debug
+# Or on iOS environment
+flutter build ios --debug --no-codesign
+
+```
+
+**Prohibited Actions**:
+
+* ❌ Do NOT assume code is correct by only running `flutter analyze` (cannot detect native dependency issues)
+* ❌ Do NOT ignore `pubspec.yaml` version conflicts
+
+**Build Error Classification and Handling**:
+| Error Type | Example | Resolution |
+|---------|------|---------|
+| Dependency Resolution Failed | `Because xxx depends on yyy...` | Check `pubspec.yaml` version compatibility, run `flutter pub get` |
+| Missing Dependency | `Target of URI doesn't exist` | Add missing library to `dependencies` |
+| Missing Import | `Undefined class 'xxx'` | Add import statement |
+| Missing Asset | `Unable to load asset` | Register asset in `pubspec.yaml` under `assets` node |
+| Missing Permission | Crash on access Camera/Mic | Check `AndroidManifest.xml` and `Info.plist` |
+
+**Verification Flow**:
+
+1. Execute `flutter build apk --debug`.
+2. If failed → Analyze complete error stack → Fix → Rebuild.
+3. Loop until `BUILD SUCCESSFUL`.
+
+**Handling Flow**:
+
+1. **Build Successful** → Deliver code.
+2. **Build Failed** → Analyze error → **Auto-fix** → Rebuild.
+* ✅ **Auto-fixable**: Missing dependencies, Missing imports, Missing permission configurations.
+* ❌ **Not fixable**: SDK internal errors, Flutter environment configuration issues (notify user).
+---
+
+## 📋 Instruction Purpose and Architecture
+
+Provides Agent with a **code generation blueprint** for implementing Native (Flutter) Live AtomicXCore core features.
+
+**Core Architecture**:
+
+* **Container**: `LiveCoreWidget` (View layer)
+* **State**: `Store` (Data-driven)
+* **Events**: `Listener` (Callback handling)
+
+**Feature Dependency Logic (Important)**:
+
+1. **Foundation First**: Must first use this tool (`get_flutter_live_uikit_integration`) to complete basic live streaming (host streaming/viewing/list).
+2. **Interaction Overlay**: If user requirements include "co-guest", "PK", "audience list", must call the interaction tool (`get_flutter_live_uikit_interaction`) **after basic features are completed**.
+3. **Empty Project Handling**: If user requests interaction features in an empty project, Agent **MUST implement basic features first**, then add interaction capabilities.
+
+---
+
+## ⚙️ Automated Workflow Steps
+
+### Step 0: Prerequisites (Automated)
+
+1. **Generate Credentials**: Call `get_usersig` tool to generate test credentials.
+* Anchors: `anchor001`, `anchor002`, `anchor003`
+* Audience: `user001`, `user002`, `user003`
+
+2. **Environment Check**: Check `pubspec.yaml`, auto-add if missing the following dependencies:
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  atomic_x_core: ^3.6.0  # Core library
+  permission_handler: ^11.0.0 # Permission handling
+  svgaplayer_flutter: ^2.0.0 # Gift animation (if needed)
+
+```
+
+3. **Permission Injection**:
+* **Android**: Add Camera/Record Audio permissions in `android/app/src/main/AndroidManifest.xml`.
+* **iOS**: Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` in `ios/Runner/Info.plist`.
+### Step 1: Fetch and Generate
+
+**MUST prioritize and exclusively** use the **real-time documentation content** returned by this tool to generate code.
+
+* **Anchor Only**: Generate `AnchorPage`
+* **Audience Only**: Generate `AudiencePage`
+* **Anchor + Audience**: Generate `MainPage` (entry selection) + `AnchorPage` + `AudiencePage`
+
+### Step 2: Verify and Deliver
+
+Execute `flutter build apk --debug`, deliver after ensuring no errors.
+
+---
+
+## 🚫 Code Generation Constraints (Strictly Follow)
+
+### 1. General Code Constraints
+
+* **NEVER Modify Import**: Uniformly use `import 'package:atomic_x_core/atomicxcore.dart';`.
+* **NEVER Fabricate APIs**: Must strictly follow Store and Model definitions in the documentation.
+* **MUST Consult API Documentation**: When dealing with data model fields (e.g., `LiveInfo`), must check documentation to confirm field names (e.g., confirm it's `liveOwner.userName` not `name`).
+
+### 2. 🧩 Store and Listener Management Constraints (Lifecycle Safety)
+
+**Core Reason**: Dart's Stream and closure listeners, if not properly released, will cause severe memory leaks or null pointer exceptions.
+
+* **Unique Instance Principle**: All Listeners (e.g., `GiftListener`, `CoGuestListener`, `BarrageListener`) **MUST be declared as State member variables**.
+* **NO Anonymous Inner Classes**: Prohibit writing anonymous objects directly in `addListener(Listener(...))`, must instantiate first.
+* **Pairing Principle**: If `addListener` is called in `initState`, then `removeListener` **MUST** be called in `dispose` to prevent memory leaks and listener failures.
+
+### 3. ⏱️ Timeout Limits (Critical Technical Point)
+
+**MUST strictly follow these parameter limits, prioritize using values from documentation examples:**
+
+#### A. Co-Guest (`CoGuestStore`)
+
+* **Rules**:
+* Optional parameter, no timeout check if not provided.
+* If provided, range MUST be between **5 - 1800 seconds**.
+
+* **Correct Example**:
+```dart
+// ✅ Recommended: Follow documentation example (e.g., 30 seconds)
+guestStore.applyForSeat(seatIndex: -1, timeout: 30, extraInfo: null);
+
+```
+#### B. Co-Host/PK (`CoHostStore`)
+
+* **Rules**:
+* **Maximum 30 seconds** (backend hard limit).
+
+* **Correct Example**:
+```dart
+// ✅ Recommended: Use maximum value
+coHostStore.requestHostConnection(..., timeout: 30);
+
+```
+### 3. 🎨 Extended Feature Constraints (Beauty/Audio Effect/UI)
+
+#### A. Audio Effect
+
+* **Voice Changer Enum (`AudioChangerType`)**:
+* ✅ **Allowed**: `AudioChangerType.child`, `AudioChangerType.man` and other standard enums.
+* ❌ **Prohibited**: Using integer indices (e.g., `1`, `2`).
+#### B. Beauty
+
+* **Parameter Range**: **0.0 - 9.0** (Double).
+* **UI Mapping Formula**: `sliderValue * 9.0` (assuming Slider is 0.0-1.0).
+
+#### C. Barrage, Gift & Layout
+
+* **Layer Requirements**: Use `Stack` widget.
+* Bottom layer: `LiveCoreWidget` (full screen).
+* Top layer: Barrage, gift, function buttons (use `Positioned` for positioning).
+
+* **Keyboard Adaptation**:
+* `Scaffold` property `resizeToAvoidBottomInset: false`, prevent keyboard from pushing up video view.
+* Input box at top of `Stack`, use `MediaQuery` to monitor keyboard height or use `Positioned(bottom: 0)` with `SafeArea`.
+##### Barrage Input Box
+
+* **Position**: Fixed at bottom-left of screen, in the same row as function buttons (gift, co-guest, etc.).
+* **Style**: Semi-transparent rounded background + placeholder text "Say something...".
+* **Keyboard Adaptation**:
+* When keyboard pops up, input box **MUST stay in original position**, DO NOT move up with keyboard.
+* **MUST** set `resizeToAvoidBottomInset: false` on `Scaffold`.
+##### Barrage Display Flow
+
+* **Data Source**: Use `ValueListenableBuilder` to listen to `BarrageStore.create(liveId).barrageState.messageList`.
+* **Local Echo**: After successful send, **immediately** call `appendLocalTip` to insert into local barrage list, no need to wait for server callback.
+* **Scroll Behavior**: Auto-scroll to bottom when new message arrives.
+
+##### Full-screen Gift Animation
+
+**⚠️ MUST Implement**: When integrating gift feature, full-screen gift animation is **mandatory**, cannot be omitted.
+
+* **Dependency**: Must include `svgaplayer_flutter`.
+* **Layer**: Full-screen gift animation view must be placed **above** `LiveCoreWidget`.
+* **Dual-side Sync**: After receiving `GiftStore.onReceiveGift` callback, **both anchor and audience** must play the full-screen animation. Prohibit playing only on audience side.
+
+### 🎨 Default UI/UX Design and Interaction Standards (Only effective when user doesn't specify)
+
+**⚠️ Note: The following standards are only applied as defaults when user doesn't provide specific UI design mockups or requirements.**
+
+### 1. Global Visual Style (Global Aesthetics)
+
+* **Immersive Dark**: `Scaffold` background MUST be `Colors.black`, `LiveCoreWidget` MUST **fill the entire screen** (`Positioned.fill`) and be at the bottom layer.
+* **Safe Area**: All floating UI MUST be wrapped in `SafeArea`.
+* **Text Readability**: White text over video (e.g., barrage, ID) MUST have **black shadow** (`Shadow`).
+* **Error Prompts**: Uniformly use `SnackBar` or `FlutterToast`, DO NOT use modal Dialog to interrupt user.
+
+### 2. Common Component Standards
+
+* **Top Capsule (Glass Capsule)**:
+* **Style**: **Semi-transparent black background** + **Fully rounded corners**.
+* **Usage**: Only for top-left display of "anchor avatar + ID + popularity".
+
+* **Common Buttons (Flat Buttons)**:
+* **Style**: **"Text + Rounded rectangle background"**. Flat and minimalist visual style, background color is semi-transparent black or theme color.
+* **Close Button**: Exception, uses circular semi-transparent background icon.
+### 3. Live Room Layout Blueprint
+
+**⚠️ Dynamic Layout Principle: Only render function buttons that user actually integrates. If user didn't request a feature (e.g., PK/beauty), strictly prohibit adding corresponding empty buttons**
+
+#### A. Top Bar
+
+* **Left [Room Info]**: Use **semi-transparent capsule** to wrap [Anchor Avatar | Anchor Nickname].
+* **Right [Control Area]**: Horizontally arrange [Online Audience Count] + [Close Icon (X)].
+
+#### B. Bottom Bar - Dynamic switching based on state
+
+* **Preview Mode**:
+* Content **aligned to right**: [Beauty] [Audio Effect] [Start Live (Main Button)].
+
+* **Anchor Live Mode**:
+* **Left**: [Barrage List (transparent background)] + [Chat Input Box].
+* **Right**: Function array [Beauty] [Audio Effect] [Co-Host] [PK].
+
+* **Audience Mode**:
+* **Left**: [Barrage List] + [Chat Input Box].
+* **Right**: [Gift] [Apply Co-Guest].
+### 4. Home Page Layout and Interaction
+
+#### A. Home Page Reference Layout
+
+```
+┌─────────────────────────────┐
+│       AtomicXCore Live       │
+│                             │
+│  Live Room ID               │
+│  ┌─────────────────────────┐│
+│  │ live_000001             ││  ← Input box (with left Padding, semi-transparent background)
+│  └─────────────────────────┘│
+│                             │
+│  Start Live as Anchor        │
+│  (Click to login as anchor001)│
+│                             │
+│  Watch as Audience           │
+│  (Click to login as user001) │
+│                             │
+│       [ 📋 Live List ]       │
+└─────────────────────────────┘
+
+```
+
+#### B. Implicit Login Flow
+
+**Home page doesn't need a separate login button**, login is automatically completed when clicking function buttons:
+
+* Click "Start Live as Anchor" → Login as `anchor001` → Navigate to anchor page.
+* Click "Watch as Audience" → Login as `user001` → Navigate to audience page.
+* Click "Live List" → Login as `user001` → Navigate to list page.
+
+---
+
+## 🎯 Feature Implementation Details
+
+### 1. Anchor Start Live (`AnchorPage`)
+
+* **Core**: `LiveCoreWidget` + `LiveCoreController`
+* **Flow**: `LiveListStore.createLive()`
+* **Destroy**: MUST call `endLive()` in `dispose`.
+
+### 2. Audience Watch (`AudiencePage`)
+
+* **Core**: `LiveCoreWidget` + `LiveCoreController`
+* **Flow**: `LiveListStore.joinLive()`
+* **Destroy**: MUST call `leaveLive()` in `dispose`.
+
+### 3. Live List (`LiveListPage`)
+
+* **Core**: `LiveListStore.fetchLiveList()` + `GridView`/`ListView`
+* **Data**: Subscribe to `liveState.liveList` (ValueListenable).
+* **Navigation**: Click list item to navigate to audience page, pass `liveID`.
+
+### 4. Co-Guest and Co-Host Interaction Standards (`co_guest` & `co_host`)
+
+#### A. Co-Guest (Anchor passively receives)
+
+* **Anchor UI**: ❌ **STRICTLY PROHIBIT** displaying "Co-Guest Request" list button in bottom toolbar or anywhere.
+* **Interaction Logic**: When receiving audience co-guest application callback (`onApplicationReceived`), directly pop up dialog at screen center (`showDialog`):
+* **Title**: Co-Guest Request
+* **Content**: Received co-guest request from audience [nickname], accept?
+* **Actions**: [Reject] [Accept]
+
+* **Custom View**: Flutter version MUST implement `LiveCoreWidget.videoWidgetBuilder`'s `coGuestWidgetBuilder`, return Foreground (nickname) or Background (avatar) based on `ViewLayer`.
+
+#### B. Co-Host Panel (Pops up when clicking bottom [Co-Host] button)
+
+* **Presentation**: Use bottom sheet panel (`showModalBottomSheet`), prohibit using Dialog.
+* **UI Layout (Strictly follow the diagram)**:
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│  Start Co-Host        [🚪 End Co-Host] │  ← Red text
+│                                     │
+│  Connected (2 people)               │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] John [💎20]          In PK... ││  ← Connected users
+│  │ [👤] Alice [💎32]         In PK... ││
+│  └─────────────────────────────────┘│
+├─────────────────────────────────────┤
+│  Other Co-Host Users                │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] John [💎20]      [Cancel Invite] ││  ← Gray-black background button
+│  │ [👤] Alice [💎32]     [Invite Co-Host] ││  ← Blue background button
+│  │ [👤] Bob   [💗99]     [Invite Co-Host] ││
+│  └─────────────────────────────────┘│
+└─────────────────────────────────────┘
+
+```
+
+#### C. PK Button Interaction Constraints
+
+* **Pre-check**: When clicking bottom [PK] button, MUST check current co-host status (`CoHostStore.connectedUsers.isEmpty()`).
+* **Status Handling**:
+* **Not Connected**: ❌ Prohibit navigation, use Toast to prompt: `"Please start co-host first"`.
+* **Connected**: ✅ Pop up PK invitation panel.
+
+* **Custom View**: Implement `VideoWidgetBuilder.battleWidgetBuilder` to display PK opponent info and scores.
+
+---
+
+## 📋 Agent Final Checklist
+
+* [ ] **Build Verification**: Executed `flutter build apk --debug` with SUCCESS result.
+* [ ] **API Accuracy**: Did not modify Import, did not fabricate APIs, verified `LiveInfo` field names.
+* [ ] **Timeout Compliance**: Co-guest timeout 5-1800s, co-host timeout ≤30s.
+* [ ] **Extension Compliance**: Audio effect enums correct, beauty range 0-9, barrage layout overlays and keyboard adapted.
+* [ ] **Gift Compliance**: Both anchor and audience have implemented full-screen gift animation display.
+* [ ] **Credential Injection**: Test UserSig has been auto-injected.
+* [ ] **Dependency Complete**: Checked and fixed `pubspec.yaml` and platform permission configurations.
+
+---
+
+## 🚨 Security Reminder (Code Comment Template)
+
+```dart
+/**
+ * ⚠️ Test Credential Notice
+ * - Current userSig is auto-generated by development tool, valid for 7 days
+ * - ❌ Production environment MUST NOT generate userSig on client side
+ * - ✅ Must generate on backend service before going live
+ * - Reference: https://trtc.io/document/live-overview?product=live&menulabel=uikit&platform=flutter
+ */
+
+```

package/utils/report-cls-client.js

@@ -6,7 +6,7 @@ function reportCLSClient(reportData) {
     const time = Date.now();
     const data = {
         platform: 'mcp',
-        verison: '1.3.6',
+        verison: '1.3.7',
         sdkappid: `${SDKAppID}`,
         method: method,
         userid: userID,

package/utils/report-es-client.js

@@ -7,7 +7,7 @@ function reportESClient(reportData) {
         report: [
             {
                 platform: 'mcp',
-                version: '1.3.6',
+                version: '1.3.7',
                 sdkappid: `${SDKAppID}`,
                 method: method,
                 userID: `${userID}`,