@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/conference/web/network-quality.md

@@ -0,0 +1,190 @@
+---
+id: conference/network-quality
+name: 网络质量
+product: conference
+platform: web
+tags: [network, quality, loss, delay, NetworkQuality]
+platforms: [web]
+related: [conference/device-control, conference/room-lifecycle, conference/video-layout]
+api_docs:
+  - title: 设备及网络
+    url: https://cloud.tencent.com/document/product/647/126923
+---
+
+# 网络质量
+
+## 功能说明
+
+网络质量负责会议中的连接稳定性观测与弱网提示，帮助用户理解当前延迟、丢包、连接波动和恢复情况，并为卡顿、断线、恢复等体验提供统一的状态表达。它关注的是“网络现在怎么样”，而不是“是否立刻离房或重进房”。
+
+## 核心概念
+
+### 角色与操作
+
+| 角色 | 关键操作 | 说明 |
+|------|----------|------|
+| 当前参会人 | 感知弱网状态 | 通过状态栏、角标或详情面板理解当前网络情况 |
+| UI 状态层 | 映射网络等级 | 把原始时延、丢包和质量等级转成用户可理解的提示 |
+| 房间生命周期模块 | 处理断连与重连 | 网络质量是观察信号，真正的离房和重入仍由房间生命周期负责 |
+| 布局与挂件模块 | 消费弱网状态 | 可在画面单元或工具栏中展示弱网标记 |
+
+### 事件流
+
+| 阶段 | 参与方 | 关键动作 |
+|------|--------|----------|
+| 网络采样 | SDK / 客户端 | 周期性获取时延、丢包和质量等级 |
+| 状态映射 | UI 状态层 | 把原始值映射成优、良、差、断连等可读状态 |
+| 体验提示 | UI | 在工具栏、状态栏或成员挂件上展示网络提示 |
+| 连接波动 | 房间生命周期 | 若发生断线、重连或恢复，和房间状态一起解释给用户 |
+| 恢复收口 | UI | 网络恢复后更新提示，避免长期停留在错误状态 |
+
+### 状态与数据
+
+| 数据 / 状态 | 说明 |
+|-------------|------|
+| 网络质量等级 | 用于描述当前连接的大致稳定性 |
+| 时延 | 反映当前链路往返延迟 |
+| 上下行丢包率 | 用于辅助判断是本地发送问题还是接收问题 |
+| 重连相关状态 | 用于解释断线、重连中、恢复等体验阶段 |
+| 弱网提示文案 / 图标 | 面向用户的最终表达层 |
+
+### 状态机
+
+```text
+good
+  → weak
+  → bad
+  → reconnecting
+  → recovered
+  → good
+```
+
+## 前置条件
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+
+**前置状态**：
+- 已阅读 `conference/network-quality`，明确当前能力的产品边界。
+- 已完成 `conference/login-auth`，确保当前页面具备稳定登录态。
+- 已根据业务流程接入会议上下文；需要房间状态时，优先通过 `conference/room-lifecycle` 统一承接。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **把原始网络指标映射成稳定、可读的用户提示** —— 用户不需要直接理解每个指标，但需要知道会议当前是否受影响。
+2. **让网络状态与房间生命周期一起解释** —— 弱网提示和重连状态结合起来，体验上更连贯。
+3. **在全局状态栏和局部挂件中复用同一套网络状态** —— 避免不同区域对同一网络情况给出相互矛盾的反馈。
+4. **在恢复后及时清理弱网提示** —— 网络恢复时要同步收口，避免用户仍以为会议处于异常状态。
+
+### ❌ NEVER
+
+1. **不要把网络质量直接等同于必须离房或重进房** —— 观察信号不应替代真实的生命周期决策。
+2. **不要只显示原始指标而没有语义化表达** —— 这会增加用户理解成本，也不利于产品统一。
+3. **不要混淆本地网络问题与远端成员状态问题** —— 网络提示应明确是谁受影响、影响在哪一侧。
+
+## 代码示例
+### 基础接入：把网络质量映射成可读文案
+
+```ts
+import { computed } from 'vue';
+import { useDeviceState, NetworkQuality } from 'tuikit-atomicx-vue3/room';
+
+const { networkInfo } = useDeviceState();
+
+const networkText = computed(() => {
+  switch (networkInfo.value?.quality) {
+    case NetworkQuality.Excellent: return '优秀';
+    case NetworkQuality.Good: return '良好';
+    case NetworkQuality.Poor: return '一般';
+    default: return '未知';
+  }
+});
+```
+
+## 调用时序
+```
+完成 login-auth 并进入会议
+   │
+   ▼
+读取 useDeviceState().networkInfo
+   │
+   ├─ quality 优秀 / 良好 → 展示常规状态
+   ├─ quality 一般 / 较差 → 展示弱网提示与恢复建议
+   └─ 数据为空 → 等待进房与媒体状态稳定后再展示
+   │
+   ▼
+结合 room-lifecycle 的重连 / 离会状态做统一反馈
+```
+
+## 平台特有注意事项
+### 1. `networkInfo` 通常在进房且媒体链路建立后更稳定
+仅完成登录但未进房时，网络质量数据往往不完整；展示层应允许初始为空或未知状态。
+
+### 2. 弱网提示应与房间生命周期联动
+如果只在顶部展示一个图标，却不联动重连、掉线、离会等状态，用户很难理解当前问题来源。
+
+### 3. 网络状态适合做常驻感知，不适合做高频弹窗
+建议把状态放到顶部工具栏、布局状态栏或参会者信息区，避免高频通知打断会议流程。
+
+## 代码生成约束
+### 编译必要条件
+- **通用条件**：见 [login-auth 平台 slice](login-auth.md)。
+- **额外导入**：至少需要导入 `useDeviceState`；如需映射等级，按需导入 `NetworkQuality`。
+- **运行前提**：页面已进入会议流程，网络状态来源可用。
+
+### 生成规则
+#### MUST（生成时必须包含）
+
+1. **通过 `networkInfo` 作为网络质量单一状态源** — 可避免 UI 与底层状态割裂。  
+   **Verify**: 检查是否存在 `useDeviceState()` 与 `networkInfo` 读取逻辑。
+2. **把质量等级映射为用户可理解的文案或图标** — 直接暴露枚举值不利于会议中快速感知。  
+   **Verify**: 检查是否存在 `computed` / 映射表 / 文案转换逻辑。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要把弱网提示做成与房间状态无关的孤立展示** — 用户无法判断是否需要重试或重连。  
+   **Verify**: 检查是否与 `room-lifecycle` 或页面状态联动。
+2. **不要假设 `networkInfo` 在所有阶段都立即可用** — 初始空值必须可处理。  
+   **Verify**: 检查是否对空值或未知状态做了兜底。
+
+### 集成检查点
+- 当前 slice 常与 `conference/video-layout`、`conference/room-lifecycle` 联动展示。
+- 一般只需要新增状态条、角标或弱网提示组件，侵入性较低。
+- 若业务侧已有独立网络探测能力，需要明确展示优先级，避免两套网络状态互相矛盾。
+
+## 验证矩阵
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | 已导入 `useDeviceState` / `NetworkQuality` | 检查 `import` 语句 | 网络状态相关导入可解析 |
+| 2. 静态规则级 | 网络枚举被映射为可读状态 | 搜索 `networkInfo` 和文案映射逻辑 | 存在从枚举到 UI 的转换 |
+| 3. 运行时级 | 进房后可观测到网络状态变化 | 在会议中查看弱网提示区域 | 可看到网络等级或未知兜底 |
+| 4. 业务行为级 | 弱网时用户能获得清晰反馈 | 模拟网络波动或弱网环境 | 页面出现明确的状态感知与提示 |
+
+## 排障指南
+
+### 常见问题
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 网络状态一直不变 | 明显卡顿，但界面中的网络图标长期不更新 | 检查网络采样结果是否真正驱动了 UI 状态映射 |
+| 网络恢复后仍显示异常 | 已恢复正常，但工具栏仍显示弱网或重连中 | 检查恢复路径是否有及时清理旧提示状态 |
+| 弱网提示与房间状态矛盾 | 页面提示网络正常，但房间却在重连或相反 | 检查网络质量状态与 `room-lifecycle` 的连接状态是否协同解释 |
+
+### 排障流程
+
+```text
+发现 网络质量 相关问题
+├── 第 1 步：确认问题属于网络观测和提示层，而不是设备异常或房间主链路本身
+├── 第 2 步：检查时延、丢包、质量等级是否已稳定映射为统一的 UI 状态
+├── 第 3 步：确认弱网、重连、恢复提示是否与 room-lifecycle 使用同一套连接语义
+└── 第 4 步：若仍异常，再回查 device-control / room-lifecycle / video-layout 的衔接是否正确
+```
+
+## 关联知识
+
+- **[conference/device-control](device-control.md)** —— 网络问题和设备问题常被用户混淆，需要分层排查。
+- **[conference/room-lifecycle](room-lifecycle.md)** —— 断线、重连、恢复等真正的会议主链路状态由这里承接。
+- **[conference/video-layout](video-layout.md)** —— 弱网状态可作为成员单元挂件或状态角标的一部分输入。

package/knowledge-base/slices/conference/web/official-roomkit-api.md

@@ -0,0 +1,298 @@
+---
+id: conference/official-roomkit-api
+platform: web
+api_docs:
+  - title: 快速接入 Web&H5 (Vue3)
+    url: https://cloud.tencent.com/document/product/647/81962
+  - title: 界面微调 (Web)
+    url: https://cloud.tencent.com/document/product/647/129842
+---
+
+# 官方 RoomKit 适配层 API — Web 实现
+
+> 本 slice 覆盖 `@tencentcloud/roomkit-web-vue3` 导出的 `conference` 对象的完整 API。
+> 当 `ui_mode = official-roomkit` 时，业务侧通过此对象操作会议，
+> 而不是直接调用 composable（composable 层见 `conference/web/room-lifecycle.md` 等）。
+>
+> 以下签名基于 `@tencentcloud/roomkit-web-vue3@5.9.0` 源码验证。
+> 源码参考：`RoomKit/adapter/conference.ts` + `RoomKit/adapter/type.ts`。
+
+## 前置条件
+
+**安装依赖**：
+```bash
+npm install @tencentcloud/roomkit-web-vue3@5 tuikit-atomicx-vue3 \
+  @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
+```
+
+**版本要求**：lockfile 中 `@tencentcloud/roomkit-web-vue3` 解析版本必须 `>=5.4.3`。
+
+**导入来源**：
+```ts
+// 会议组件 + conference API + 事件/枚举
+import {
+  ConferenceMainView,
+  ConferenceMainViewH5,
+  conference,
+  RoomEvent,
+  BuiltinWidget,
+  InterceptorAction,
+} from '@tencentcloud/roomkit-web-vue3'
+
+// UIKitProvider（包裹组件用）
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3'
+```
+
+## 枚举定义
+
+```ts
+enum RoomEvent {
+  ROOM_LEAVE = 'RoomLeave',
+  ROOM_DISMISS = 'RoomDismiss',
+  ROOM_ERROR = 'RoomError',
+  KICKED_OUT = 'KickedOut',
+  KICKED_OFFLINE = 'KickedOffline',
+  USER_SIG_EXPIRED = 'UserSigExpired',
+}
+
+enum BuiltinWidget {
+  MicWidget = 'MicWidget',
+  CameraWidget = 'CameraWidget',
+  ScreenShareWidget = 'ScreenShareWidget',
+  RoomChatWidget = 'RoomChatWidget',
+  MemberWidget = 'MemberWidget',
+  InviteWidget = 'InviteWidget',
+  VirtualBackgroundWidget = 'VirtualBackgroundWidget',
+  BasicBeautyWidget = 'BasicBeautyWidget',
+  AIToolsWidget = 'AIToolsWidget',
+  SettingsWidget = 'SettingsWidget',
+  ThemeWidget = 'ThemeWidget',
+  LayoutWidget = 'LayoutWidget',
+  LocalNetworkInfoWidget = 'LocalNetworkInfoWidget',
+  LanguageWidget = 'LanguageWidget',
+  LoginUserInfoWidget = 'LoginUserInfoWidget',
+  CurrentRoomInfoWidget = 'CurrentRoomInfoWidget',
+  LeaveRoomWidget = 'LeaveRoomWidget',
+  SwitchCameraWidget = 'SwitchCameraWidget',
+  BarrageWidget = 'BarrageWidget',
+  RaiseHandsWidget = 'RaiseHandsWidget',
+  RaiseHandsListWidget = 'RaiseHandsListWidget',
+}
+
+enum InterceptorAction {
+  OpenMicrophone = 'openMicrophone',
+  CloseMicrophone = 'closeMicrophone',
+  OpenCamera = 'openCamera',
+  CloseCamera = 'closeCamera',
+  StartScreenShare = 'startScreenShare',
+  StopScreenShare = 'stopScreenShare',
+}
+```
+
+## API 签名
+
+### 登录与用户信息
+
+```ts
+conference.login({ sdkAppId: number, userId: string, userSig: string }): Promise<void>
+conference.setSelfInfo({ userName: string, avatarUrl: string }): Promise<void>
+conference.logout(): Promise<void>
+```
+
+### 房间生命周期
+
+```ts
+// 创建并加入房间
+conference.createAndJoinRoom({
+  roomId: string,
+  roomType?: RoomType,
+  options?: CreateRoomOptions,
+}): Promise<void>
+
+interface CreateRoomOptions {
+  roomName?: string;
+  password?: string;
+  isAllMicrophoneDisabled?: boolean;
+  isAllCameraDisabled?: boolean;
+  isAllScreenShareDisabled?: boolean;
+  isAllMessageDisabled?: boolean;
+}
+
+// 加入已有房间
+conference.joinRoom({
+  roomId: string,
+  roomType?: RoomType,
+  password?: string,
+}): Promise<void>
+
+// 离开（普通成员）
+conference.leaveRoom(): Promise<void>
+
+// 结束（主持人）
+conference.endRoom(): Promise<void>
+```
+
+### 事件
+
+```ts
+conference.on(eventType: RoomEvent, callback: (data?: any) => void): void
+conference.off(eventType: RoomEvent, callback: (data?: any) => void): void
+```
+
+### 界面微调
+
+```ts
+// 隐藏/显示内置按钮
+conference.setWidgetVisible(config: Partial<Record<BuiltinWidget, boolean>>): void
+
+// 注册自定义按钮（返回注销函数）
+conference.registerWidget(config: WidgetConfig): () => void
+
+// 拦截内置操作（返回注销函数）
+conference.onWill(action: InterceptorAction, handler: InterceptorHandler): () => void
+
+type InterceptorHandler = (
+  action: InterceptorAction,
+  proceed: () => void,
+  abort: () => void,
+) => void | Promise<void>
+```
+
+### 特性配置
+
+```ts
+conference.setFeatureConfig(config: Partial<FeatureConfig>): void
+
+interface FeatureConfig {
+  watermark?: WatermarkConfig;
+  shareLink?: string;              // 纯字符串 URL
+  contactList?: ContactListProvider;
+  virtualBackground?: VirtualBackgroundFeatureConfig;
+  aiTools?: AIToolsConfig;
+  layoutTemplate?: RoomLayoutTemplate;
+  toolbar?: ToolbarConfig;
+}
+```
+
+## 调用时序
+
+```
+1. conference.login()
+2. conference.setSelfInfo()
+3. conference.setWidgetVisible()      ← login 之后、进房之前
+   conference.registerWidget()        ← 同上
+   conference.onWill()                ← 同上
+4. conference.createAndJoinRoom() 或 conference.joinRoom()
+5. conference.setFeatureConfig()      ← 进房成功后（shareLink 依赖最终 roomId）
+   ...会中...
+6. conference.leaveRoom() 或 conference.endRoom()
+7. RoomEvent.ROOM_LEAVE / ROOM_DISMISS 回调 → 清理注销函数
+```
+
+## 完整代码示例
+
+```vue
+<template>
+  <UIKitProvider theme="light" language="zh-CN">
+    <ConferenceMainView v-if="isPC" />
+    <ConferenceMainViewH5 v-else />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import {
+  ConferenceMainView,
+  ConferenceMainViewH5,
+  conference,
+  RoomEvent,
+  BuiltinWidget,
+} from '@tencentcloud/roomkit-web-vue3'
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3'
+
+const route = useRoute()
+const router = useRouter()
+const isPC = ref(window.innerWidth > 768)
+function onResize() { isPC.value = window.innerWidth > 768 }
+
+const cleanupFns: Array<() => void> = []
+
+onMounted(async () => {
+  window.addEventListener('resize', onResize)
+
+  const sdkAppId = Number(route.query.sdkAppId)
+  const userId = route.query.userId as string
+  const userSig = route.query.userSig as string
+  const roomId = route.query.roomId as string
+
+  if (!sdkAppId || !userId || !userSig || !roomId) {
+    router.replace('/')
+    return
+  }
+
+  // 1. 登录
+  await conference.login({ sdkAppId, userId, userSig })
+  await conference.setSelfInfo({ userName: userId, avatarUrl: '' })
+
+  // 2. 界面微调（login 之后、进房之前）
+  conference.setWidgetVisible({
+    [BuiltinWidget.InviteWidget]: false,
+  })
+
+  // 3. 监听离房
+  conference.on(RoomEvent.ROOM_LEAVE, handleLeave)
+  conference.on(RoomEvent.ROOM_DISMISS, handleLeave)
+
+  // 4. 创建并加入
+  await conference.createAndJoinRoom({
+    roomId,
+    options: { roomName: `会议-${roomId}` },
+  })
+
+  // 5. 进房后设置分享链接
+  conference.setFeatureConfig({
+    shareLink: `${window.location.origin}/meeting?roomId=${roomId}`,
+  })
+})
+
+function handleLeave() {
+  conference.off(RoomEvent.ROOM_LEAVE, handleLeave)
+  conference.off(RoomEvent.ROOM_DISMISS, handleLeave)
+  cleanupFns.forEach(fn => fn())
+  router.replace('/')
+}
+
+onUnmounted(() => {
+  window.removeEventListener('resize', onResize)
+  handleLeave()
+})
+</script>
+```
+
+## 代码生成约束
+
+### MUST
+
+1. **使用 UIKitProvider 包裹会议组件** — `ConferenceMainView` / `ConferenceMainViewH5` 必须放在 `UIKitProvider` 内。
+2. **界面微调 API 在 login 之后、进房之前注册** — 避免按钮闪烁或拦截器遗漏。
+3. **registerWidget / onWill 返回的注销函数必须收集并在 ROOM_LEAVE + ROOM_DISMISS 时清理** — 防止重复注册。
+4. **shareLink 在进房成功后设置** — 依赖最终确定的 roomId。
+
+### MUST NOT
+
+1. **不要用不存在的枚举值** — `BuiltinWidget.InviteControl` 不存在，正确是 `BuiltinWidget.InviteWidget`。
+2. **不要给 createAndJoinRoom 传顶层 roomName / isOpenCamera / isSeatEnabled** — `roomName` 在 `options` 内，其余不存在。
+3. **不要给 joinRoom 传 isOpenCamera / isOpenMicrophone** — 只接受 `roomId`、`roomType`、`password`。
+4. **不要把 shareLink 写成对象** — `setFeatureConfig({ shareLink: '...' })` 是纯字符串。
+5. **不要用 CSS/DOM hack 修改 RoomKit 内部 UI** — 必须用 `setWidgetVisible` / `registerWidget` / `onWill`。
+
+## 常见错误速查
+
+| 错误写法 | 正确写法 | 原因 |
+|---------|---------|------|
+| `BuiltinWidget.InviteControl` | `BuiltinWidget.InviteWidget` | 枚举值不存在 |
+| `createAndJoinRoom({ roomId, roomName })` | `createAndJoinRoom({ roomId, options: { roomName } })` | roomName 在 options 内 |
+| `joinRoom({ roomId, isOpenCamera: true })` | `joinRoom({ roomId })` | 无 isOpenCamera 参数 |
+| `setFeatureConfig({ shareLink: { link, title } })` | `setFeatureConfig({ shareLink: 'url' })` | shareLink 是字符串 |
+| `import { UIKitProvider } from '@tencentcloud/roomkit-web-vue3'` | `import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3'` | UIKitProvider 在 peer 包中 |