@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/conference/web/ai-tools.md

@@ -0,0 +1,225 @@
+---
+id: conference/ai-tools
+name: AI 实时转写与字幕
+product: conference
+platform: web
+tags: [ai, asr, transcription, subtitle, translation, realtime]
+platforms: [web]
+related: [conference/room-lifecycle, conference/participant-management]
+---
+
+# AI 实时转写与字幕
+
+## 功能说明
+
+AI 实时转写与字幕负责会议中的实时语音转文字、字幕展示、翻译语言设置和转写消息列表。业务 UI 可以把它做成工具栏入口、侧栏面板或浮层字幕；房主负责启动和更新转写配置，其他成员主要消费字幕和消息结果。
+
+## 核心概念
+
+| 能力 | 说明 |
+|------|------|
+| `useAITranscriberState()` | 启停和更新实时转写配置 |
+| `startRealtimeTranscriber()` | 启动实时转写，传入源语言和翻译目标语言 |
+| `stopRealtimeTranscriber()` | 停止实时转写，离房或角色变化时需要收口 |
+| `updateRealTimeTranscriber()` | 转写运行中更新语言配置 |
+| `RealtimeTranscriberEvent` | 监听转写启动、停止等状态 |
+| `Subtitle` | 字幕展示组件 |
+| `RealtimeMessageList` | 实时转写消息列表组件 |
+| `SubtitleDisplayMode` | 字幕展示模式，当前是 `'bilingual'` / `'translation'` 这类字符串类型 |
+
+## 前置条件
+
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+- 已完成会议 UI 入口设计，例如工具栏按钮、侧栏面板或字幕浮层。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **AI 工具入口应由业务 UI 显式控制** —— 只有在当前会议和用户权限满足条件时才展示入口。
+2. **只让房主启动或更新实时转写** —— 推荐用 `currentRoom.roomOwner.userId === localParticipant.userId` 判断管理权。
+3. **打开字幕或转写面板前先确保 ASR 已启动** —— 面板消费的是实时转写状态，不应空开。
+4. **监听转写停止事件并关闭相关 UI** —— ASR 停止后字幕和实时消息面板应同步收口。
+5. **房间切换时重置语言、字幕模式和启动状态** —— 防止跨房间继承旧配置。
+6. **处理套餐或权限类错误** —— 启动失败时要给出可理解提示，而不是只打印日志。
+
+### ❌ NEVER
+
+1. **不要让每个成员都尝试启动转写** —— 会造成重复请求、权限失败或状态混乱。
+2. **不要在离房后保留字幕浮层** —— 旧房间的实时内容不应残留到下一场会议。
+3. **不要只切 UI 语言而不调用 `updateRealTimeTranscriber()`** —— 运行中的转写配置不会自动变化。
+
+## 代码示例
+
+### 启动、停止和更新实时转写
+
+```ts
+import { ref, watch } from 'vue';
+import {
+  RealtimeTranscriberEvent,
+  useAITranscriberState,
+  useRoomParticipantState,
+  useRoomState,
+} from 'tuikit-atomicx-vue3/room';
+import type { SubtitleDisplayMode } from 'tuikit-atomicx-vue3/room';
+
+const sourceLanguage = ref('auto');
+const targetLanguage = ref('');
+const subtitleDisplayMode = ref<SubtitleDisplayMode>('translation');
+const hasStartedASR = ref(false);
+
+const {
+  startRealtimeTranscriber,
+  stopRealtimeTranscriber,
+  updateRealTimeTranscriber,
+  subscribeEvent,
+} = useAITranscriberState();
+
+const { currentRoom } = useRoomState();
+const { localParticipant } = useRoomParticipantState();
+
+const canManageTranscriber = () =>
+  currentRoom.value?.roomOwner?.userId === localParticipant.value?.userId;
+
+subscribeEvent(RealtimeTranscriberEvent.onRealtimeTranscriberStarted, () => {
+  hasStartedASR.value = true;
+});
+
+subscribeEvent(RealtimeTranscriberEvent.onRealtimeTranscriberStopped, () => {
+  hasStartedASR.value = false;
+});
+
+export async function ensureASRStarted() {
+  if (!canManageTranscriber() || hasStartedASR.value) return;
+
+  await startRealtimeTranscriber({
+    sourceLanguage: sourceLanguage.value || 'auto',
+    translationLanguages: targetLanguage.value ? [targetLanguage.value] : [],
+  });
+  hasStartedASR.value = true;
+}
+
+export async function saveASRSettings(options: {
+  sourceLanguage?: string;
+  targetLanguage?: string;
+  subtitleDisplayMode?: SubtitleDisplayMode;
+}) {
+  const nextSourceLanguage = options.sourceLanguage ?? sourceLanguage.value;
+  const nextTargetLanguage = options.targetLanguage ?? targetLanguage.value;
+
+  sourceLanguage.value = nextSourceLanguage;
+  targetLanguage.value = nextTargetLanguage;
+  subtitleDisplayMode.value = options.subtitleDisplayMode ?? subtitleDisplayMode.value;
+
+  if (canManageTranscriber() && hasStartedASR.value) {
+    await updateRealTimeTranscriber({
+      sourceLanguage: sourceLanguage.value || 'auto',
+      translationLanguages: targetLanguage.value ? [targetLanguage.value] : [],
+    });
+  }
+}
+
+export async function stopASR() {
+  if (!hasStartedASR.value) return;
+  await stopRealtimeTranscriber();
+  hasStartedASR.value = false;
+}
+
+watch(() => currentRoom.value?.roomId, () => {
+  sourceLanguage.value = 'auto';
+  targetLanguage.value = '';
+  hasStartedASR.value = false;
+}, { immediate: true });
+```
+
+### 字幕浮层与实时转写消息列表
+
+```vue
+<template>
+  <Subtitle
+    v-if="isSubtitlesVisible"
+    :target-language="targetLanguage"
+    :display-mode="subtitleDisplayMode"
+  />
+
+  <RealtimeMessageList
+    v-if="isRealtimeMessageListVisible"
+    :target-language="targetLanguage"
+    :display-mode="subtitleDisplayMode"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  RealtimeMessageList,
+  Subtitle,
+} from 'tuikit-atomicx-vue3/room';
+import type { SubtitleDisplayMode } from 'tuikit-atomicx-vue3/room';
+
+const isSubtitlesVisible = ref(false);
+const isRealtimeMessageListVisible = ref(false);
+const targetLanguage = ref('');
+const subtitleDisplayMode = ref<SubtitleDisplayMode>('translation');
+</script>
+```
+
+## 平台特有注意事项
+
+### 1. 管理权以房主为准
+推荐只让房主启动或更新 ASR 配置。如果业务要放开给管理员，需要明确权限规则，并处理多人同时更新配置的冲突。
+
+### 2. 打开 UI 前先启动 ASR
+字幕浮层和转写消息列表只是展示层。点击入口时应先调用 `ensureASRStarted()`，成功后再打开字幕或侧栏。
+
+### 3. 停止后同步关闭 UI
+监听 `RealtimeTranscriberEvent.onRealtimeTranscriberStopped`，转写停止后关闭字幕、实时消息面板和设置弹层，避免残留。
+
+### 4. 套餐错误要显式提示
+启动实时转写可能返回套餐未开通、权限不足或频控类错误。遇到 `ERR_REQUIRE_PAYMENT` 时应提示需要开通对应套餐。
+
+## 代码生成约束
+
+### MUST
+
+1. **通过 `useAITranscriberState()` 启停和更新转写**。  
+   **Verify**: 检查是否存在 `startRealtimeTranscriber()` / `stopRealtimeTranscriber()`。
+2. **打开字幕或转写面板前确保 ASR 已启动**。  
+   **Verify**: 检查入口点击前是否调用 `ensureASRStarted()` 或等价逻辑。
+3. **房间切换或转写停止时清理 UI 状态**。  
+   **Verify**: 检查 `currentRoom.roomId` watch 或 `onRealtimeTranscriberStopped` 监听。
+4. **运行中改语言时调用 `updateRealTimeTranscriber()`**。  
+   **Verify**: 检查保存设置逻辑中是否调用更新接口。
+
+### MUST NOT
+
+1. **不要让每个参会人都启动 ASR**。  
+   **Verify**: 检查是否有房主或业务权限判断。
+2. **不要只渲染 `Subtitle` 而没有转写启动链路**。  
+   **Verify**: 检查字幕入口是否能触发启动。
+
+## 验证矩阵
+
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | AI 转写 API 可解析 | 检查 `useAITranscriberState`、`Subtitle` 导入 | 类型可解析 |
+| 2. 静态规则级 | 启动、更新、停止链路完整 | 搜索 `startRealtimeTranscriber` / `updateRealTimeTranscriber` / `stopRealtimeTranscriber` | 三段链路存在 |
+| 3. 运行时级 | 房主可打开字幕和转写列表 | 房主账号点击 AI 工具 | ASR 启动并展示内容 |
+| 4. 业务行为级 | 切房间或停止后 UI 收口 | 离房或停止 ASR | 字幕和转写面板关闭 |
+
+## 排障指南
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 点击字幕后没有内容 | 字幕浮层打开但无文本 | 检查是否已调用 `startRealtimeTranscriber()` |
+| 非房主启动失败 | 普通成员打开 AI 工具报错 | 只允许房主启动，其他成员消费已有转写结果 |
+| 切换语言不生效 | 设置面板保存后字幕仍旧语言 | 转写已启动时调用 `updateRealTimeTranscriber()` |
+| 离房后字幕残留 | 下一场会议仍显示旧字幕 | 监听 roomId 变化和 stopped 事件，清理 UI 状态 |
+
+## 关联知识
+
+- **[conference/room-lifecycle](room-lifecycle.md)** —— 进退房决定 AI 状态的初始化与清理时机。
+- **[conference/participant-management](participant-management.md)** —— 房主身份和角色变化会影响 AI 管理权。

package/knowledge-base/slices/conference/web/beauty-effects.md

@@ -0,0 +1,188 @@
+---
+id: conference/beauty-effects
+name: 美颜效果
+product: conference
+platform: web
+tags: [beauty, FreeBeautyPanel, useFreeBeautyState, preview]
+platforms: [web]
+related: [conference/device-control, conference/video-layout, conference/virtual-background]
+api_docs:
+  - title: 基础美颜
+    url: https://cloud.tencent.com/document/product/647/126937
+---
+
+# 美颜效果
+
+## 功能说明
+
+美颜效果负责会议中本地视频的人像基础增强，包括磨皮、美白、红润等参数调节，以及从实时预览到正式保存生效的两阶段体验。它处理的是本地视频前处理效果，不负责摄像头开关、房间主链路或背景替换。
+
+## 核心概念
+
+### 角色与操作
+
+| 角色 | 关键操作 | 说明 |
+|------|----------|------|
+| 当前参会人 | 调节美颜参数 | 根据个人偏好调整磨皮、美白、红润等基础效果 |
+| 美颜面板 | 提供预览与确认 | 承载参数调整、重置与保存入口 |
+| 本地视频处理链 | 应用美颜结果 | 把保存后的参数真正作用到本地视频流 |
+| 相邻能力模块 | 与设备 / 背景 / 布局联动 | 摄像头状态影响预览前提，虚拟背景与美颜共同作用于本地视频 |
+
+### 事件流
+
+| 阶段 | 参与方 | 关键动作 |
+|------|--------|----------|
+| 打开面板 | 当前参会人 | 进入本地美颜设置界面 |
+| 实时预览 | 当前参会人 / 本地视频处理链 | 调整参数并即时预览效果 |
+| 确认保存 | 当前参会人 | 将当前预览值正式保存到视频效果设置中 |
+| 会中生效 | 本地视频流 | 远端开始看到保存后的美颜效果 |
+| 重置或关闭 | 当前参会人 | 清空或恢复默认效果，退出当前设置流程 |
+
+### 状态与数据
+
+| 数据 / 状态 | 说明 |
+|-------------|------|
+| 美颜参数集合 | 磨皮、美白、红润等基础美颜值 |
+| 预览态参数 | 当前面板内临时调整、尚未正式保存的参数 |
+| 已保存参数 | 真正对视频流生效的美颜设置 |
+| 面板开关状态 | 标识当前是否处于美颜设置流程 |
+| 本地视频可用态 | 决定当前是否具备可感知的实时预览前提 |
+
+### 状态机
+
+```text
+off
+  → panel-opened
+  → previewing
+  → saved
+  → active
+  → reset
+  → off
+```
+
+## 前置条件
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+
+**前置状态**：
+- 已阅读 `conference/beauty-effects`，明确当前能力的产品边界。
+- 已完成 `conference/login-auth`，确保当前页面具备稳定登录态。
+- 已根据业务流程接入会议上下文；需要房间状态时，优先通过 `conference/room-lifecycle` 统一承接。
+- 当前能力涉及媒体采集、渲染或浏览器权限时，请在 `HTTPS` 或 `localhost` 安全上下文下调试。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **把实时预览和正式保存拆成两段** —— 让用户先试效果，再决定是否真正作用到会中画面。
+2. **在摄像头已准备好的前提下再强调预览体验** —— 没有本地视频输入时，很难判断美颜调整是否真实生效。
+3. **把美颜参数集中维护** —— 面板、预览区和最终保存动作应围绕同一份参数模型工作。
+4. **和虚拟背景等本地视频特效能力明确编排关系** —— 都属于本地视频前处理，但初始化与兼容性要求不同。
+
+### ❌ NEVER
+
+1. **不要把美颜效果写成摄像头控制能力** —— 摄像头开关属于 `device-control`，美颜只处理视频前处理效果。
+2. **不要在用户拖动滑杆时无条件永久保存** —— 如果产品设计要求确认保存，应保留预览态和提交态分层。
+3. **不要忽略重置和退出流程的状态收口** —— 否则面板关闭后，用户很难理解当前到底应用了哪组参数。
+
+## 代码示例
+### 基础接入：实时预览并显式保存美颜设置
+
+```ts
+import { useFreeBeautyState } from 'tuikit-atomicx-vue3/room';
+
+const { setFreeBeauty, saveBeautySetting } = useFreeBeautyState();
+
+await setFreeBeauty({ beautyLevel: 60, whitenessLevel: 40, ruddinessLevel: 20 });
+await saveBeautySetting();
+```
+
+## 调用时序
+```
+完成 login-auth 并打开本地视频
+   │
+   ▼
+进入美颜设置面板
+   │
+   ▼
+调用 setFreeBeauty(...) 做本地预览
+   │
+   ├─ 用户继续调节 → 重复预览
+   ├─ 用户取消 → 回退未保存的本地预览
+   └─ 用户确认 → saveBeautySetting()
+   │
+   ▼
+远端看到最终保存后的美颜效果
+```
+
+## 平台特有注意事项
+### 1. `setFreeBeauty()` 主要作用于本地预览
+只有在调用 `saveBeautySetting()` 后，当前选择才会作为最终效果稳定生效；不要把两者当成同一步。
+
+### 2. 无摄像头或摄像头关闭时应禁用入口
+美颜直接依赖本地视频流，若摄像头未开启，则继续暴露调节入口会产生无效操作体验。
+
+### 3. 低性能设备要预留降级路径
+美颜会增加本地渲染负担，低性能终端可能出现掉帧、发热或风扇噪声上升，业务层应允许快速关闭。
+
+## 代码生成约束
+### 编译必要条件
+- **通用条件**：见 [login-auth 平台 slice](login-auth.md)。
+- **额外导入**：至少需要从 `tuikit-atomicx-vue3/room` 导入 `useFreeBeautyState`。
+- **运行前提**：本地摄像头可用，且页面已处于安全上下文。
+
+### 生成规则
+#### MUST（生成时必须包含）
+
+1. **使用 `useFreeBeautyState` 承接美颜状态与保存动作** — 这样 UI 预览与最终生效状态才一致。  
+   **Verify**: 检查是否存在 `useFreeBeautyState()`。
+2. **将预览与保存拆成两段链路** — 否则用户每次调节参数都可能直接影响最终效果。  
+   **Verify**: 检查是否同时存在 `setFreeBeauty(` 与 `saveBeautySetting(`。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要在无本地视频的前提下强行启用美颜操作** — 会造成空操作或异常体验。  
+   **Verify**: 检查入口是否与摄像头状态联动。
+2. **不要把滑杆变化直接等价为永久保存** — 会破坏“先预览、再确认”的交互预期。  
+   **Verify**: 检查参数变化处理是否无条件调用 `saveBeautySetting()`。
+
+### 集成检查点
+- 当前 slice 常与 `conference/device-control`、`conference/video-layout` 联动。
+- 通常只需要新增一个设置面板或弹层，不应修改视频渲染底层实现。
+- 若业务还接入了 `conference/virtual-background`，需明确二者在 UI 上的优先级和入口关系。
+
+## 验证矩阵
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | 已导入 `useFreeBeautyState` | 检查 `import` 语句 | 美颜 Hook 可解析 |
+| 2. 静态规则级 | 预览与保存动作分离 | 搜索 `setFreeBeauty` 与 `saveBeautySetting` | 两段链路同时存在 |
+| 3. 运行时级 | 参数调整后可看到本地效果变化 | 开启摄像头并调节美颜参数 | 本地预览立即变化 |
+| 4. 业务行为级 | 用户确认后效果稳定生效 | 调整参数并点击保存 | 最终效果符合保存结果 |
+
+## 排障指南
+
+### 常见问题
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 调整后看不到效果 | 面板参数变化了，但本地或远端画面没有明显变化 | 检查本地视频是否已开启，以及是否完成了保存动作 |
+| 预览有效但重新打开面板丢失 | 刚调整好的效果下一次打开又恢复默认 | 检查预览态和已保存参数是否被分开维护并正确持久化 |
+| 与虚拟背景联动异常 | 开启背景替换后美颜表现不稳定或理解混乱 | 检查本地视频特效链路是否明确区分美颜与背景处理责任 |
+
+### 排障流程
+
+```text
+发现 美颜效果 相关问题
+├── 第 1 步：确认问题属于本地视频前处理效果，而不是摄像头开关或背景替换能力
+├── 第 2 步：检查本地视频是否可用，以及当前调整是否仍停留在预览态
+├── 第 3 步：确认预览参数、已保存参数和重置逻辑是否围绕同一份状态管理
+└── 第 4 步：若仍异常，再回查 device-control / video-layout / virtual-background 的衔接是否正确
+```
+
+## 关联知识
+
+- **[conference/device-control](device-control.md)** —— 摄像头是否可用决定美颜预览链路是否成立。
+- **[conference/video-layout](video-layout.md)** —— 美颜最终作用在本地画面单元上，会影响用户对布局中的自我画面感知。
+- **[conference/virtual-background](virtual-background.md)** —— 与美颜同属本地视频前处理，但有更强的初始化和兼容性约束。