@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/conference/web/room-schedule.md

@@ -0,0 +1,281 @@
+---
+id: conference/room-schedule
+name: 预约会议
+product: conference
+platform: web
+tags: [schedule, calendar, future-room, scheduledRoomList]
+platforms: [web]
+related: [conference/room-lifecycle, conference/room-call]
+api_docs:
+  - title: 预定房间
+    url: https://cloud.tencent.com/document/product/647/126931
+business_decisions:
+  - key: schedule_features
+    tier: blocking
+    multi_select: true
+    baseline: ["list"]   # 始终生成的基础能力，不作为多选项展示（预约会议列表默认提供）
+    question: "预约会议需要支持哪些能力？（预约会议列表默认展示，以下为额外能力，可多选）"
+    options:
+      - { label: "修改或取消已预约的会议", value: "modify" }
+      - { label: "为会议设置访问密码", value: "password" }
+      - { label: "会议状态变更时发送通知（开始提醒、邀请、取消等）", value: "events" }
+---
+
+# 预约会议
+
+## 功能说明
+
+预约会议负责未来时间维度上的会议排期，覆盖预定会议、修改和取消预定、展示预定列表，以及会议临近开始时的提醒和入会入口。它关注的是“未来会议怎么被安排与兑现”，而不是会议真正开始后的房间主链路。
+
+## 核心概念
+
+### 角色与操作
+
+| 角色 | 关键操作 | 说明 |
+|------|----------|------|
+| 会议组织者 | 创建、修改、取消预约会议 | 负责定义未来会议的时间和基础信息 |
+| 被邀请或关注会议的用户 | 查看和进入预约会议 | 在会议临近时感知提醒，并在合适时间进入真实会议 |
+| 日历 / 列表模块 | 承载排期展示 | 提供预约会议列表、筛选、更新和取消入口 |
+| 房间生命周期模块 | 承接真实入会 | 预约会议到点后，真正进入会议仍需回到 `room-lifecycle` |
+
+### 事件流
+
+| 阶段 | 参与方 | 关键动作 |
+|------|--------|----------|
+| 创建预约 | 组织者 | 设置开始时间、结束时间、会议基础配置和预约参会人 |
+| 列表展示 | 客户端 | 拉取并展示未来会议列表，并把预约结果同步给相关参会人入口 |
+| 预约变更 | 组织者 / 系统 | 修改、取消或重排预约会议信息 |
+| 即将开始 | 客户端 / 系统 | 触发“会议即将开始”的提醒与进入入口 |
+| 真实入会 | 用户 | 到点后从预约会议入口进入真实房间主流程 |
+
+### 状态与数据
+
+| 数据 / 状态 | 说明 |
+|-------------|------|
+| 预约会议 ID / 房间 ID | 用于唯一标识一条未来会议记录以及其对应房间 |
+| 开始 / 结束时间 | 定义会议的时间边界 |
+| `scheduleAttendees` / 参会人集合 | 表示本次预约会议计划覆盖的目标参会人 |
+| 预约状态 | 已预约、已修改、已取消、即将开始、已过期等状态 |
+| 预约会议列表与游标 | 用于分页展示和拉取未来会议数据 |
+| 提醒与入会入口状态 | 用于触发“即将开始”提示与进入会议动作 |
+
+### 状态机
+
+```text
+draft
+  → scheduled
+  → updated
+  → starting-soon
+  → joining-room
+  → completed
+
+scheduled
+  → cancelled
+  → expired
+```
+
+## 前置条件
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+
+**前置状态**：
+- 已阅读 `conference/room-schedule`，明确当前能力的产品边界。
+- 已完成 `conference/login-auth`，确保当前页面具备稳定登录态。
+- 已根据业务流程接入会议上下文；需要房间状态时，优先通过 `conference/room-lifecycle` 统一承接。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **把预约信息与真实房间生命周期分开处理** —— 预约会议是未来计划，真正入会要在到点后回到房间主链路。
+2. **让即时会议和预约会议复用同一套房间配置模型** —— 会议名称、密码和默认规则最好保持一致语义。
+3. **显式处理修改、取消和即将开始提醒** —— 预约会议不是只有“创建成功”一个状态。
+4. **在列表与提醒中统一使用同一时间语义** —— 开始时间、结束时间、即将开始阈值要避免前后不一致。
+
+### ❌ NEVER
+
+1. **不要把创建预约会议当成已经创建了正在运行的房间** —— 预约成功不等于用户已经在会议里。
+2. **不要忽略取消和过期状态** —— 预约类能力天然带有时间失效和状态变更特征。
+3. **不要让预约列表、提醒入口和真实入会入口各自维护不同的会议身份** —— 否则很容易出现跳错会或进错房间。
+
+## 代码示例
+### 预约与取消：创建未来会议并分页读取列表
+
+```ts
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { scheduleRoom, getScheduledRoomList, cancelScheduledRoom } = useRoomState();
+const startTime = Math.floor(Date.now() / 1000) + 3600;
+
+await scheduleRoom({
+  roomId: 'schedule_room',
+  options: {
+    roomName: '周会',
+    scheduleStartTime: startTime,
+    scheduleEndTime: startTime + 1800,
+    scheduleAttendees: ['user_a', 'user_b'],
+  },
+});
+
+await getScheduledRoomList({ cursor: '' });
+await cancelScheduledRoom({ roomId: 'schedule_room' });
+```
+
+### 读取预约列表：响应字段与「请求 / 响应」字段名不一致（高频踩坑）
+
+```ts
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { getScheduledRoomList } = useRoomState();
+
+// 返回 { scheduledRoomList: RoomInfo[]; cursor: string }
+const res = await getScheduledRoomList({ cursor: '' });
+
+const rooms = res.scheduledRoomList.map((room) => ({
+  roomId: room.roomId,
+  roomName: room.roomName,
+  // ⚠️ 响应字段是 scheduledStartTime / scheduledEndTime（带 "d"），
+  //    与「创建」请求里的 scheduleStartTime / scheduleEndTime（不带 "d"）拼写不同！
+  //    用错名字会取到 undefined → 时间为 0 → 列表显示空 / 状态恒为「已结束」。
+  startTimeMs: (room.scheduledStartTime ?? 0) * 1000, // 服务端秒级，展示前 *1000 转毫秒
+  endTimeMs: (room.scheduledEndTime ?? 0) * 1000,
+  // ⚠️ 响应里 scheduleAttendees 是 RoomUser[]（对象数组），不是创建请求里的 string[]
+  attendees: (room.scheduleAttendees ?? []).map((u) => u.userId),
+}));
+
+const nextCursor = res.cursor; // 续拉下一页
+```
+
+
+## 调用时序
+```
+完成 login-auth
+   │
+   ▼
+准备预约时间与房间信息
+   │
+   ▼
+scheduleRoom({ roomId, options })
+   │
+   ├─ 成功 → 写入预约列表
+   ├─ 需要查看更多 → getScheduledRoomList({ cursor })
+   └─ 用户取消预约 → cancelScheduledRoom({ roomId })
+   │
+   ▼
+会议临近时结合提醒事件与 room-lifecycle 引导入会
+```
+
+## 平台特有注意事项
+### 1. 时间参数为「秒级」时间戳（注意：SDK 的 .d.ts 注释会误导）
+预约接口（创建与列表响应）的时间单位是**秒级** UNIX 时间戳。
+⚠️ `tuikit-atomicx-vue3` 的 TypeScript 声明（`.d.ts`）把这些字段注释成「毫秒时间戳」、
+示例也写成 `Date.now() + 3600000`，但服务端实际收 / 发的是**秒**。**以秒为准**：
+- 创建：`scheduleStartTime: Math.floor(Date.now() / 1000) + 3600`
+- 读取：响应里的 `scheduledStartTime / scheduledEndTime` 也是秒；前端要和 `Date.now()`（毫秒）
+  比较或交给 `new Date()` 展示时，需先 `* 1000`。
+
+建议应用内部统一用毫秒，只在「调用 / 解析 SDK」这一层做秒↔毫秒转换，避免单位散落各处。
+
+### 2. 「创建请求」与「列表响应」的字段名不一致
+这是最容易静默出错的点：
+| 含义 | 创建请求 `ScheduleRoomOptions` | 列表响应 `RoomInfo` |
+|------|------|------|
+| 开始时间 | `scheduleStartTime` | `scheduledStartTime`（多一个 "d"） |
+| 结束时间 | `scheduleEndTime` | `scheduledEndTime`（多一个 "d"） |
+| 参会人 | `scheduleAttendees: string[]` | `scheduleAttendees: RoomUser[]`（对象数组） |
+
+读取列表时若沿用创建请求的字段名，会取到 `undefined` → 时间为 0 → 列表为空或状态恒为「已结束」。
+
+### 3. `roomId` 更适合由业务后台生成并保证唯一性
+预约会议的 `roomId` 最好由业务后台统一生成或分配，避免未来会议与即时会议在不同入口下发生标识冲突。
+
+### 4. 预约时可同步写入 `scheduleAttendees`
+如果业务希望把会议信息同步到参会人的会议列表或提醒入口，应在预约阶段明确传入受邀参会人集合，而不是依赖后续临时补录。
+
+### 5. 预约列表通常需要分页拉取
+不要默认一次返回所有预约记录；应根据返回的 `cursor` 持续拉取后续列表数据。
+
+### 6. 预约会议最终仍要回到房间生命周期
+无论预约由前端创建还是后端排期系统预生成，临近开会时都应回到 `conference/room-lifecycle` 的真实入会链路。
+
+## 代码生成约束
+
+### 业务决策与代码生成的对应关系
+
+`business_decisions.schedule_features` 的多选结果决定生成代码的范围。`list` 是 **baseline（基础项）**：始终生成、不作为多选项让用户勾选；`modify` / `password` / `events` 是用户多选的额外能力。
+
+| 档位 | 生成的 API 与 UI |
+|---|---|
+| `list`（baseline，始终生成） | `getScheduledRoomList`（含 cursor 分页）+ 预约列表展示 |
+| `modify` | 修改预约时间 / 取消预约的 API + 列表项操作入口 |
+| `password` | 预约创建表单的密码字段 + 入会密码校验 |
+| `events` | 会议开始提醒 / 被邀请 / 被取消等事件订阅与通知 UI |
+
+`list` 因为是 baseline，始终生成；其余三档中未勾选的，对应 API 不导出、不导入、对应 UI 入口不渲染（按 topic G8 规则）。
+
+### 编译必要条件
+- **通用条件**：见 [login-auth 平台 slice](login-auth.md)。
+- **额外导入**：至少需要导入 `useRoomState`。
+- **运行前提**：当前用户具备预约会议权限，且时间参数经过单位校验。
+
+### 生成规则
+#### MUST（生成时必须包含）
+
+1. **在预约创建时显式传入秒级时间戳** — 时间单位错误会直接导致会议时间错位。  
+   **Verify**: 检查是否存在 `Math.floor(Date.now() / 1000)` 或等价转换。
+2. **在预约场景中明确会议标识与参会人集合** — 未来会议记录应能稳定映射到唯一房间和对应参会人入口。  
+   **Verify**: 检查是否提供稳定 `roomId`，并在需要时传入 `scheduleAttendees`。
+3. **支持预约列表分页读取** — 长列表场景不能只写死第一页。  
+   **Verify**: 检查是否存在 `getScheduledRoomList({ cursor })` 调用。
+4. **读取列表必须用响应字段名 `scheduledStartTime` / `scheduledEndTime`（带 "d"）** — 与创建请求的 `scheduleStartTime` / `scheduleEndTime` 拼写不同，用错会取到 0。  
+   **Verify**: 检查列表映射代码读取的是 `scheduledStartTime` / `scheduledEndTime`，且 `scheduleAttendees` 按 `RoomUser[]` 取 `.userId`。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要把毫秒时间戳直接传给预约接口** — 服务端为秒级，传毫秒会让会议时间漂移到错误年份。  
+   **Verify**: 检查创建时是否 `Math.floor(ms / 1000)` 转秒；不要轻信 `.d.ts` 的「毫秒」注释。
+2. **不要把预约成功等价为已经进入会议** — 预约与真实入会是两条不同链路。  
+   **Verify**: 检查是否仍通过 `room-lifecycle` 承接正式开会。
+3. **不要在读取列表时复用创建请求的字段名 / 类型** — `scheduleStartTime`（无 d）、`scheduleAttendees: string[]` 是创建侧的写法，套到响应上会取空。  
+   **Verify**: 检查读取侧未出现 `room.scheduleStartTime` / 把 `scheduleAttendees` 当字符串数组直接用。
+
+### 集成检查点
+- 当前 slice 常与 `conference/room-lifecycle`、业务提醒系统联动。
+- 集成方式通常是新增日程表单、预约列表和提醒入口。
+- 如果业务已有企业日历或排期系统，需要提前约定字段映射与同步策略。
+
+## 验证矩阵
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | 已导入 `useRoomState` | 检查 `import` 语句 | 预约相关 API 可解析 |
+| 2. 静态规则级 | 时间参数、`roomId` 与参会人集合处理正确 | 搜索 `Date.now()`、`roomId`、`scheduleAttendees` | 传参为秒级时间戳，会议标识稳定 |
+| 2.1 字段名级 | 创建用 `scheduleStartTime`、读取用 `scheduledStartTime`（带 "d"）；时间按秒↔毫秒正确转换 | 搜索 `scheduledStartTime` / `scheduledEndTime` 与 `* 1000` / `/ 1000` | 列表能读出真实时间，状态不再恒为「已结束」 |
+| 3. 运行时级 | 可创建、读取和取消预约会议 | 在预约页面走完整流程 | 预约列表与取消结果正确 |
+| 4. 业务行为级 | 临近会议时可顺畅跳转入会 | 从预约记录点击进入会议 | 进入正式入会链路而非停留在预约状态 |
+
+## 排障指南
+
+### 常见问题
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 预约列表不完整或更新不及时 | 新建、修改、取消后列表没有同步变化 | 检查预约列表拉取、分页和本地状态刷新逻辑 |
+| 提醒出现了但无法入会 | 会议即将开始通知已到，但点击后不能进入会议 | 检查提醒入口是否正确衔接到 `room-lifecycle` 的真实入会流程 |
+| 取消后仍能看到旧预约 | 会议已取消，但列表和入口仍保留 | 检查取消后的本地状态清理与列表刷新是否统一收口 |
+
+### 排障流程
+
+```text
+发现 预约会议 相关问题
+├── 第 1 步：确认问题属于未来会议排期，而不是会议已经开始后的房间主链路
+├── 第 2 步：检查预约会议的创建、修改、取消和列表刷新是否共用同一会议身份
+├── 第 3 步：确认 starting-soon 提醒是否正确连接到 join-room 的真实入会动作
+└── 第 4 步：若仍异常，再回查 room-lifecycle / room-call 的衔接是否正确
+```
+
+## 关联知识
+
+- **[conference/room-lifecycle](room-lifecycle.md)** —— 预约会议到点后，真正的入会和退场仍由房间生命周期负责；会议配置（名称、密码、默认规则）也已整合到此 slice。
+- **[conference/room-call](room-call.md)** —— 预约会议场景下的提醒或召回，可能与会中呼叫形成协同。

package/knowledge-base/slices/conference/web/screen-share.md

@@ -0,0 +1,211 @@
+---
+id: conference/screen-share
+name: 屏幕分享
+product: conference
+platform: web
+tags: [screen-share, share, screenAudio, participantWithScreen]
+platforms: [web]
+related: [conference/video-layout, conference/device-control, conference/participant-management]
+api_docs:
+  - title: 屏幕分享
+    url: https://cloud.tencent.com/document/product/647/126925
+---
+
+# 屏幕分享
+
+## 功能说明
+
+屏幕分享负责会议中的共享链路，覆盖开始共享、停止共享、是否携带系统音频、谁正在共享，以及共享状态如何驱动画面编排和权限限制。它关注的是共享媒体能力本身，也要处理“当前为什么不能共享、共享被谁中断、共享受限后如何恢复”这些问题，而不是共享后画面如何排布或谁具备角色治理权限。
+
+## 核心概念
+
+### 角色与操作
+
+| 角色 | 关键操作 | 说明 |
+|------|----------|------|
+| 共享发起人 | 开始 / 停止屏幕共享 | 选择共享窗口、标签页或整个屏幕，并在支持时携带系统音频 |
+| 观看方 | 感知共享状态 | 根据共享者变化切换主画面或观看内容 |
+| 会控模块 | 约束或恢复共享能力 | 可限制成员发起共享，也可通过设备协作帮助成员恢复共享能力 |
+| 浏览器 | 提供原生共享能力 | 控制共享弹窗、系统音频可用性和原生停止事件 |
+| 布局模块 | 消费共享结果 | 根据共享开始、结束或中断结果切换主画面和展示模式 |
+
+### 事件流
+
+| 阶段 | 参与方 | 关键动作 |
+|------|--------|----------|
+| 发起共享 | 共享发起人 / 浏览器 | 用户触发共享，浏览器弹出原生选择窗口 |
+| 共享建立 | 客户端 | 共享成功后记录当前共享状态和共享者信息 |
+| 权限受限或协作恢复 | 会控模块 / 成员 | 当共享被限制时，限制入口、展示原因，并在需要时进入申请或邀请链路 |
+| 共享结束 | 浏览器 / 管理者 / 发起人 | 原生停止、管理员关闭共享或用户主动停止后，客户端同步收口 |
+| 布局回退 | 布局模块 | 根据共享结束结果回退主画面和展示模式 |
+
+### 状态与数据
+
+| 数据 / 状态 | 说明 |
+|-------------|------|
+| 共享状态 | 表示当前是否处于共享中、停止中或空闲态 |
+| `participantWithScreen` | 当前正在共享屏幕的成员信息 |
+| 系统音频选项 | 表示当前共享是否尝试携带系统音频 |
+| 浏览器支持能力 | 决定共享范围和系统音频能力是否可用 |
+| 共享权限状态 | 表示当前成员是否被允许发起共享 |
+| 共享协作状态 | 表示共享是否因会控受限、是否需要申请开启或等待邀请响应 |
+
+### 状态机
+
+```text
+idle
+  → requesting-share
+  → sharing
+  → externally-stopped
+  → idle
+
+requesting-share
+  → restricted
+  → denied
+  → failed
+  → idle
+```
+
+## 前置条件
+**通用依赖**：见 [login-auth 平台 slice](login-auth.md)。
+
+**额外依赖**：
+- 已安装 `tuikit-atomicx-vue3@latest`
+
+**前置状态**：
+- 已阅读 `conference/screen-share`，明确当前能力的产品边界。
+- 已完成 `conference/login-auth`，确保当前页面具备稳定登录态。
+- 已根据业务流程接入会议上下文；需要房间状态时，优先通过 `conference/room-lifecycle` 统一承接。
+- 当前能力涉及媒体采集、渲染或浏览器权限时，请在 `HTTPS` 或 `localhost` 安全上下文下调试。
+
+## 最佳实践
+
+### ✅ ALWAYS
+
+1. **把浏览器原生停止和管理员关闭共享都当作主流程事件处理** —— 用户不一定通过你的按钮结束共享。
+2. **让共享状态与布局编排显式联动** —— 谁在共享、共享何时开始和结束，应该直接驱动画面焦点切换。
+3. **把共享受限原因讲清楚** —— 当共享被会控限制、被管理员关闭或需要申请开启时，应给出明确原因和后续动作入口。
+4. **把共享权限与房间会控统一设计** —— 当共享能力受限时，不仅要限制入口，还要限制真实共享流程，并在需要时进入申请 / 邀请链路。
+5. **针对浏览器差异给出清晰提示** —— 系统音频、共享范围和权限提示在不同环境下会有差异。
+
+### ❌ NEVER
+
+1. **不要把屏幕共享当成普通按钮开关** —— 它受到浏览器原生交互、权限弹窗、会控限制和外部中断事件影响。
+2. **不要忽略共享结束后的布局回退** —— 否则主画面会停留在已经不存在的共享状态。
+3. **不要把共享失败一律归因到浏览器支持性问题** —— 还要排查是否被当前会控限制、被管理员关闭，或是否需要先申请开启共享。
+4. **不要默认系统音频在所有环境都可用** —— 需要根据当前环境能力做提示和降级。
+
+## 代码示例
+### 基础接入：开始共享、监听共享者并在结束时收口
+
+```ts
+import { watch } from 'vue';
+import { useDeviceState, useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+
+const { startScreenShare, stopScreenShare, screenStatus } = useDeviceState();
+const { participantWithScreen } = useRoomParticipantState();
+
+await startScreenShare({ screenAudio: true });
+watch(participantWithScreen, (participant) => {
+  console.log('当前共享者:', participant?.userId);
+});
+await stopScreenShare();
+```
+
+## 调用时序
+```
+完成 login-auth 并进入会议
+   │
+   ▼
+调用 startScreenShare({ screenAudio })
+   │
+   ├─ 浏览器弹出原生共享选择器
+   ├─ 用户确认 → 本地开始共享，participantWithScreen 更新
+   ├─ 用户取消 → 保持未共享状态
+   └─ 浏览器原生停止 → screenStatus / participantWithScreen 变化收口 UI
+   │
+   ▼
+需要结束共享时调用 stopScreenShare()
+```
+
+## 平台特有注意事项
+### 1. 系统音频共享受浏览器差异影响明显
+`screenAudio` 在 Chrome / Edge 上通常体验更完整，Firefox / Safari 的能力与限制差异更大，联调时要分浏览器验证。
+
+### 2. 必须处理浏览器原生“停止分享”
+用户点击浏览器原生停止按钮后，前端不能只依赖业务按钮状态，必须通过共享状态变化主动收口 UI。
+
+### 3. 屏幕分享主要面向桌面浏览器
+移动端 Web 对屏幕共享的支持极其有限，产品设计和文档说明都应以桌面场景为主。
+
+### 4. 本地共享 tile 不展示真实预览时，不要让它停留在纯黑屏
+部分 Web 环境或产品方案里，本地共享流不会展示真实预览，或者业务上本来就不希望在本地重复渲染共享内容。此时推荐改成“您正在共享屏幕”一类的示意态，并按需提供“结束共享”操作。
+
+这里的图标、文案、按钮布局都只是**示例**，不应被理解为固定 UI 规范；真正需要固定的是：用户一眼能知道自己正在共享，且不会看到无语义的黑底。
+
+如需具体承载方式，优先交给 `conference/web/video-layout` 中的 `participantViewUI` 或页面级 overlay 处理。
+
+## 代码生成约束
+### 编译必要条件
+- **通用条件**：见 [login-auth 平台 slice](login-auth.md)。
+- **额外导入**：至少需要导入 `useDeviceState` 与 `useRoomParticipantState`。
+- **运行前提**：浏览器支持屏幕采集，并处于安全上下文。
+
+### 生成规则
+#### MUST（生成时必须包含）
+
+1. **通过 `startScreenShare()` / `stopScreenShare()` 控制共享主链路** — 可保证共享状态与房间状态一致。  
+   **Verify**: 检查是否存在 `startScreenShare(` 与 `stopScreenShare(`。
+2. **根据 `participantWithScreen` 或 `screenStatus` 驱动 UI** — 共享者变化必须能被页面感知。  
+   **Verify**: 检查是否读取 `participantWithScreen` 或 `screenStatus`。
+3. **如果本地共享流不展示真实预览或表现为黑底，必须补共享中的提示态** —— 可以是状态文案、图标、结束共享入口或它们的组合，但不能只有无语义黑屏。  
+   **Verify**: 检查本地共享中的 UI 是否至少向用户表达“正在共享”这一状态。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要假设所有浏览器都等价支持系统音频共享** — 会造成错误的产品承诺。  
+   **Verify**: 检查是否有浏览器差异说明或降级策略。
+2. **不要忽略浏览器原生停止共享后的状态变化** — UI 会残留“仍在共享”的假状态。  
+   **Verify**: 检查是否有基于状态变化的收口逻辑。
+3. **不要把共享中的示意态写死成唯一视觉规范** —— 示例可以参考设计稿，但实现必须允许按业务风格调整。  
+   **Verify**: 检查说明文字是否把示例样式当作唯一合法 UI。
+
+### 集成检查点
+- 当前 slice 常与 `conference/video-layout`、`conference/participant-management` 联动。
+- 集成方式通常是新增共享按钮、共享状态提示和主画面切换逻辑。
+- 如果业务需要限制谁能共享，应在上层与角色治理或会控规则联合判断。
+
+## 验证矩阵
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| 1. 编译级 | 已导入共享相关 Hook | 检查 `import` 语句 | 屏幕共享 API 可解析 |
+| 2. 静态规则级 | 共享开始、停止和状态监听都存在 | 搜索 `startScreenShare` / `stopScreenShare` / `participantWithScreen` | 形成完整共享链路 |
+| 3. 运行时级 | 浏览器确认后可开始共享 | 在桌面浏览器执行共享 | 页面出现共享状态 |
+| 4. 业务行为级 | 原生停止共享后 UI 正确收口 | 点击浏览器原生停止按钮 | 共享按钮与主画面状态恢复正常 |
+
+## 排障指南
+
+### 常见问题
+
+| 问题 | 表现 | 处理建议 |
+|------|------|----------|
+| 点击共享没有成功开始 | 浏览器无弹窗，或弹窗后没有进入共享状态 | 检查浏览器共享权限、当前环境支持能力，以及共享入口是否被会控限制 |
+| 浏览器已停止共享但 UI 仍显示共享中 | 用户通过浏览器原生面板停止后，页面状态未收口 | 检查是否监听并处理了原生停止共享事件 |
+| 共享被中断但原因不清楚 | 共享突然结束，用户不知道是自己停了还是被管理者关闭 | 检查是否对管理员关闭共享和浏览器原生停止做了区分提示 |
+| 共享开始了但主画面没切换 | 共享画面存在，但布局仍停留在普通成员视图 | 检查共享状态是否真正驱动了 `video-layout` 的焦点切换逻辑 |
+
+### 排障流程
+
+```text
+发现 屏幕分享 相关问题
+├── 第 1 步：确认问题属于共享媒体能力，而不是布局编排或角色治理本身
+├── 第 2 步：检查浏览器共享弹窗、权限和系统音频支持是否符合当前环境
+├── 第 3 步：确认当前是否存在禁共享、共享被关闭或申请 / 邀请中的会中限制
+└── 第 4 步：若仍异常，再回查 video-layout / device-control / participant-management 的衔接是否正确
+```
+
+## 关联知识
+
+- **[conference/video-layout](video-layout.md)** —— 屏幕共享会直接驱动主画面切换与布局重编排。
+- **[conference/device-control](device-control.md)** —— 本地媒体控制与共享状态共同构成会中媒体体验。
+- **[conference/participant-management](participant-management.md)** —— 禁共享、共享关闭和申请 / 邀请链路会直接约束当前能力；同时谁能发起共享相关协作也由成员角色边界决定。