| name | trtc-room-builder |
| description | INTERNAL skill — only invoked by trtc-topic during scenario execution. Do NOT trigger directly from user messages. Generates room-type audio/video product UI (conference, live room, voice chat) using templates, component library, or official RoomKit integration. Always route user requests through trtc-onboarding first. |
TRTC Room Builder
从零搭建 room 类音视频产品的前端界面，或把官方 RoomKit 会议能力集成进现有
Vue 3 应用。提供三条路径，根据用户需求自动选择：
- Styled 路径：12 个精美模板 + 设计系统 → 高风格感、视觉精致的界面
- Standard 路径：60 个通用组件 + 5 种场景模板 → 功能完备、标准化的界面
- Official RoomKit 集成模式：官方 RoomKit 组件 + 官方 API → 快速接入现有业务应用，并通过官方扩展点微调界面
本 skill 是自包含的：所有模板、设计系统参考、60 组件的 UIKit 资产与工具脚本都在本目录内（templates/、references/、uikit/），无需外部依赖。
Invocation entry points
本 skill 有两种被使用入口；主入口下支持 official-roomkit 与 full-ui
两种会议 UI 生成/集成模式：
1. 被 ../trtc-topic/SKILL.md 消费（主路径，conference official-roomkit / full-ui 模式）
当用户在 onboarding A2-Q0.5 选择"官方 UI"时，
${CLAUDE_PROJECT_DIR}/.trtc-session.yaml 会写入
ui_mode: official-roomkit。topic 读取本 skill 的"官方 RoomKit 集成模式"
作为生成规范，集成官方组件并使用官方 API 微调界面。
当用户在 A2-Q0.5 选择"AI 生成完整会议 UI"时，session 会写入
ui_mode: full-ui。topic 读取本 skill 的以下资产作为生成规范，并不会
调用本 skill 的"核心决策流程"或 scaffold.py：
references/scenario-mapping.md — onboarding scenario → Standard scene / 模板references/composable-bindings.md — UIKit class → AtomicXCore composable 绑定uikit/assets/themes/meeting-classic/ — 组件 CSS + 图标资产uikit/references/component-catalog.md — 60 组件 HTML 范式
用户看不到本 skill 的参与——topic 拿这些资产作为内部生成规范，输出融合 Vue SFC。
2. 用户直接触发（fallback 入口，非主推路径）
下面的"核心决策流程"保留作为 fallback：当 harness 因为 description 关键词匹配
而自主触发本 skill 时（比如用户恰好说了"搭建会议界面"但未经过 onboarding），
就按"核心决策流程"走。
推荐路径始终是 onboarding A2-Q0.5 → topic——通过那条路径进来的用户要么得到
官方 RoomKit 集成代码，要么得到能跑的 Vue + AtomicXCore 自定义 UI 代码，而不是
孤立的 HTML demo。根 skill 不为本 skill 创建专用触发词；本路径是 harness 行为的
补充，不是主推的用户旅程。
官方 RoomKit 集成模式
当用户要在已有 Vue 3 项目中集成会议/接入多人会议/接入 TUIRoomKit/使用官方
RoomKit，且没有明确要求“完全重做会议 UI / 生成定制全屏会议界面”时，优先走
官方 RoomKit 集成模式，而不是 Styled / Standard 路径。
触发关键词
- 中文：集成会议、接入会议、多人会议 SDK、视频会议 SDK、官方 RoomKit、
TUIRoomKit、含 UI 集成、快速接入、界面微调
- 英文：integrate meeting, add conference, official RoomKit, TUIRoomKit,
Web&H5 Vue3, customize RoomKit UI
实施规则
- 使用官方 Web RoomKit 包；如果要使用界面微调 API，必须确认 lockfile 中实际解析到的
@tencentcloud/roomkit-web-vue3 版本 >=5.4.3。安装
@tencentcloud/roomkit-web-vue3@5 可以作为官方大版本入口，但不能接受解析到
<5.4.3 的既有依赖。并按官方快速接入文档安装相关包：
tuikit-atomicx-vue3、@tencentcloud/uikit-base-component-vue3、
@tencentcloud/universal-api。
- 页面层渲染官方组件：PC 使用
ConferenceMainView，H5 使用
ConferenceMainViewH5（二者从 @tencentcloud/roomkit-web-vue3 导入），
外层包裹 UIKitProvider（从 @tencentcloud/uikit-base-component-vue3 导入），
并根据业务需要设置 theme="light" | "dark"、language="zh-CN" | "en-US"。
- 登录与房间生命周期使用官方
conference API：conference.login()、
conference.setSelfInfo()、conference.createAndJoinRoom()、
conference.joinRoom()、conference.leaveRoom()、conference.endRoom()、
RoomEvent 监听。
- 房间号
roomId 必须来自业务系统或由业务系统保证唯一；在线问诊、1v1 客服等
双方不确定谁先建房的场景，可统一用业务单据号作为 roomId 并调用
conference.createAndJoinRoom()。
- UserSig 生成必须复用
skills/trtc-onboarding/reference/mcp-usersig-generation.md
的规则：优先使用 MCP / 当前本地签名能力生成测试 userSig，正式环境由业务后端
签发；没有签名能力时，前端只保留 SDKAppID / userId / userSig 输入项或占位。
不要生成 src/utils/usersig.ts，不要在前端依赖 SecretKey，不要用 crypto-js、
pako、HmacSHA256 或 tls-sig-api-v2 在浏览器端签名。
- 按钮、工具栏、内置按钮点击前拦截只使用官方界面微调 API：
conference.setWidgetVisible() 隐藏/恢复内置按钮，
conference.registerWidget() 添加自定义业务按钮或侧边面板，
conference.onWill() 拦截内置按钮点击前的操作。
setWidgetVisible()、registerWidget()、onWill() 尽量放在
conference.login() 成功之后、conference.createAndJoinRoom() /
conference.joinRoom() 之前，避免按钮闪烁或拦截器漏掉早期操作。conference.setFeatureConfig() 只用于官方文档定义的特性配置。尤其是
shareLink 必须在 conference.createAndJoinRoom() / conference.joinRoom()
成功后立即设置，确保使用最终确定的 roomId。registerWidget() 和 onWill() 返回的注销函数必须统一收集，并在
RoomEvent.ROOM_LEAVE 和 RoomEvent.ROOM_DISMISS 两个事件里清理，避免多次进出
房间后重复注册。
禁止事项
- 不要为官方 RoomKit 集成模式运行
trtc_prepare_ui.py 或
trtc_verify_ui.py。
- 不要复制
uikit/assets/themes/meeting-classic/ 到客户项目，也不要要求生成的
Vue 组件满足 ui-* class 数量规则。
- 不要手写一套替代 RoomKit 主界面的会议 SFC；官方组件承担会议主界面，业务侧只
负责外层路由、登录、房间号、事件监听和官方 UI 微调 API。
- 不要生成前端 UserSig 签名器，尤其不要生成
src/utils/usersig.ts、不要把
SecretKey 放进 src/config.ts、不要新增 crypto-js / pako / tls-sig-api-v2
这类仅用于浏览器端签名的依赖。
- 不要用 CSS 选择器或 DOM hack 修改 RoomKit 内部按钮显隐、点击前权限和工具栏
扩展；这些需求必须使用
setWidgetVisible()、registerWidget()、onWill()。
- 不要在进房前写死
setFeatureConfig({ shareLink })；分享链接依赖最终 roomId，
应在 createAndJoinRoom() / joinRoom() 成功后设置。
API 签名与代码示例
所有 conference 适配层 API 的完整签名、枚举定义和集成示例已移至
knowledge-base/slices/conference/web/official-roomkit-api.md。
生成 official-roomkit 模式代码前，必须先 Read 该 slice 文件，
使用其中经过源码验证的签名，不得自行推测参数。
参考文档：
医疗在线问诊新项目直拷规则
当用户需求落在医疗在线问诊（例如 1v1-video-consultation、远程问诊、
医生/患者视频问诊、在线诊疗）并且明确是生成全新项目，不要进入 Styled
路径、Standard 路径、theme-copy、手写 Vue SFC 或任何 verifier 流程。
直接把本 skill 内置模板目录完整复制到用户指定的本地项目目录：
skills/trtc/room-builder/templates/scenarios/medical-consultation/
复制时保留模板项目的文件结构、路由、样式、服务适配器、mock 数据和文档。
交付或接入说明中必须提醒客户使用 pnpm install 安装依赖，并使用
pnpm dev 启动本地开发服务；不要推荐 npm install / npm run dev，因为
该医疗模板使用 npm 启动会明显变慢，首屏可能白屏一段时间。
本规则只适用于全新医疗问诊项目；对既有项目做集成/改造时，继续按后续
scenario / official-roomkit / full-ui / UIKit 规则处理。
核心决策流程
用户提出 room 类界面需求
│
▼
是否是已有 Vue 3 项目集成会议 / 官方 RoomKit？
│
┌─────┴──────┐
▼ ▼
YES NO
│ │
▼ ▼
Official 用户是否有明确的风格/视觉诉求？
RoomKit │
集成模式 ┌─────┴──────┐
▼ ▼
YES NO
│ │
▼ ▼
Styled 路径 Standard 路径
(精美模板) (通用组件)
判断标准——何时走 Styled 路径
当用户描述中包含以下任一特征时，走 Styled 路径：
- 提到具体视觉风格：暗色、毛玻璃、渐变、极光、高级感、商务风、清新、扁平
- 提到品牌色/配色方案：紫色调、深色金、森林绿、天蓝系等
- 提到设计参考：像 Zoom/Teams/Google Meet、Dribbble 风格、现代感
- 提到模板/精美/好看/showcase/展示/demo/高颜值
- 明确说"有风格要求"或指定了字体偏好
- 目标用途是展示/演示/客户 demo 而非生产环境
判断标准——何时走 Standard 路径
当用户描述中没有上述风格诉求，且更关注功能完备性时，走 Standard 路径：
- 只描述功能需求：视频会议、语音房、直播、通话等
- 关注功能区域：麦克风控制、成员列表、聊天、设置面板
- 目标是可交互的原型或直接生产使用
- 需要与 TRTC SDK / TUIRoom 对接的标准界面
Styled 路径（精美模板 + 设计系统）
Phase S1：选择模板
读取 references/templates-index.md 匹配用户需求。12 个模板速查：
| # | 文件 | 风格 | 主色 | 适用场景 |
|---|
| 01 | skyblue-dashboard | 友好 SaaS 仪表盘 | #38BDF8 | 产品化视频 + 任务管理 |
| 02 | forest-realestate | 编辑风 / 衬线 / 专业 | #2D6A4F | 房产/法律/咨询 |
| 03 | purple-trackly-ai | 现代创业公司 | #7C5CFC | AI 项目管理 |
| 04 | mindcare-sprint | Sprint 三栏布局 | #2563FF | 迭代计划/站会 |
| 05 | finance-daily | 明亮薄荷绿 | #00C48A | 日会 + 字幕翻译 |
| 06 | evo-ia-aiassistant | AI 助手风 | #00C9A7 | AI 转写/摘要 |
| 07 | green-initiative-grid | 大地色 2×2 等分 | #2D6A4F | 4人站会 |
| 08 | q4-strategy-dark-gold | 暗黑高级金 | #C9A96E | 高管董事会 |
| 09 | aurora-grid-9 | 极光动态 3×3 | #667eea | 9+人 gallery view |
| 10 | glass-design-review | 毛玻璃/粉彩 | #6366f1 | 设计评审 |
| 11 | culture-workshop | 陶土色 Workshop | #E07A5F | 工作坊/团建 |
| 12 | social-design-review | 清爽靛蓝 | #4F6EF7 | 社交/营销评审 |
每个模板另附 -lobby.html 变体（会议前大厅/进入页），用于完整的"入会前 → 会议中"双屏体验。
Phase S2：交付或定制
匹配度 80%+：直接使用模板文件 templates/<NN-name>.html
- 可直接浏览器预览
- 可修改标题、颜色、成员姓名等内容
匹配度不足：用设计系统从零生成
- 读取
references/design-system.md — 颜色/字体/间距 token + 6 条铁律 + 质量检查清单
- 读取
references/layout-recipes.md — 6 种布局骨架 + 决策树
- 读取
references/component-library.md — 复制粘贴 HTML 组件片段
- 按质量清单（14 项 yes/no）验证产出
混合模式：可以从一个模板取视频区，从另一个取聊天面板，拼接组合。
Phase S3：预览
使用 preview_url 打开生成的 HTML 文件让用户实时预览。
全局约束（双路径共用）
以下规则对所有场景、所有路径生效：
最小宽度约束
所有生成的会议界面必须设置 最小宽度 1200px。当浏览器视口窄于 1200px 时，页面内容不压缩、不重排，而是出现横向滚动条。
Standard 路径：已内置在 layout.css 中（通过 --layout-min-width: 1200px token 控制），无需额外操作。
Styled 路径：生成页面时必须包含以下 CSS：
body { min-width: 1200px; }
@media (max-width: 1199px) { html { overflow-x: auto; } }
Standard 路径（通用组件库）
内部组件库资产（uikit/）
Standard 路径依赖本目录下的 uikit/ 子目录（原独立 trtc-room-uikit 技能，已合并到本 skill）：
- 组件目录：
uikit/references/component-catalog.md（60 个组件的 HTML 范式）
- Token 契约：
uikit/references/token-contract.md（~100 个 Design Token + 暗色模式）
- 组件资产：
uikit/assets/themes/meeting-classic/（CSS + 暗色 token + SVG 图标集）
- 风格脚本：
uikit/scripts/generate-theme-overrides.py（L1 token 覆盖生成）
- 图标换色：
uikit/scripts/recolor-icons.py（SVG 图标品牌色替换）
详细说明见 uikit/README.md。
Phase G1：场景判断
读取 references/scene-templates.md 中的决策树：
| 场景 | 关键特征 |
|---|
| meeting | 多人视频/语音 + 屏幕共享 + 成员管理 |
| voice-room | 主持人 + 多人语音连麦 + 无视频 |
| live-stream | 1 主播 + 大量观众 + 连麦互动 |
| one-on-one | 两人视频/语音通话 |
| classroom | 老师讲课 + 学生举手提问 |
如果用户描述模糊，展示以上 5 种选项让用户选择。
Phase G2：搜集需求
确定场景后确认：
- 页面标题
- 需要的功能区域
- 风格偏好（品牌色/圆角/暗色模式）
- 额外需求
Phase G3：准备资产
cp -R {skill_dir}/uikit/assets/themes/meeting-classic {project}/themes/meeting-classic
python3 {skill_dir}/scripts/scaffold.py --scene {type} --title "{title}" --output {project}/
python3 {skill_dir}/uikit/scripts/generate-theme-overrides.py --primary "{color}" --output {project}/themes/overrides.css
python3 {skill_dir}/uikit/scripts/recolor-icons.py --accent "{color}" --dir {project}/themes/meeting-classic/assets
{skill_dir} 表示本 skill 的安装目录。所有脚本都在本 skill 内部，路径相对统一。
Phase G4：填充内容
在骨架的 TODO 位置填入具体组件 HTML。
必读参考：
uikit/references/component-catalog.md — 60 个组件 HTML 范式references/scene-templates.md — 当前场景的推荐组件配置uikit/assets/themes/meeting-classic/index.html — 完整参考实现
填充规则：
- 组件 HTML 结构严格遵循 component-catalog.md
- 图标优先使用
uikit/assets/themes/meeting-classic/assets/ 下内置 SVG
- 状态通过
.is-* class 切换
- CSS 引入顺序：tokens.css → (tokens.dark.css) → layout.css → atoms → molecules → organisms
Phase G5：预览与迭代
使用 preview_url 预览，根据反馈调整。
场景速查
| 场景 | Standard 路径组件 | Styled 路径推荐模板 |
|---|
| 多人视频会议 | topbar, stage, bottombar, side-panel, modal, popover | 01/04/07/09 |
| 高管/正式会议 | 同上 | 08(暗金) |
| AI 增强会议 | topbar, stage, bottombar + AI 面板 | 03/06 |
| 设计评审 | topbar, stage, bottombar, side-panel(chat/files) | 10/12 |
| 工作坊/培训 | topbar, stage, bottombar, side-panel(agenda) | 05/11 |
| 语音房间 | topbar, bottombar, avatar(麦位), chat-message | — (Standard only) |
| 直播连麦 | topbar, stage, bottombar, chat-message, video-badge | — (Standard only) |
| 1v1 通话 | stage, bottombar, video-badge | — (Standard only) |
| 在线课堂 | topbar, stage, bottombar, side-panel | 05 |
资源目录
trtc/room-builder/ ← 自包含 skill 根目录
├── SKILL.md ← 本文件（统一入口 + 决策流程）
├── scripts/
│ └── scaffold.py ← Standard 路径：5 场景骨架生成器
├── references/ ← Styled 路径 + 场景决策参考
│ ├── scene-templates.md ← Standard 路径：场景决策树 + 页面模板
│ ├── templates-index.md ← Styled 路径：12 模板元数据 + 选择指南
│ ├── design-system.md ← Styled 路径：设计系统规范 + 质量清单
│ ├── component-library.md ← Styled 路径：Tailwind 组件代码片段
│ ├── layout-recipes.md ← Styled 路径：6 种布局骨架
│ └── usage-guide.md ← Styled 路径：框架集成指南
├── templates/ ← 12 个精美 HTML 模板 + 12 个 lobby 变体
│ ├── 01-skyblue-dashboard.html
│ ├── 01-skyblue-dashboard-lobby.html
│ ├── ... (共 24 个)
│ └── 12-social-design-review-lobby.html
├── assets/
│ └── gallery.html ← 模板可视化索引页
└── uikit/ ← Standard 路径组件库（内部依赖）
├── README.md ← UIKit 内部说明
├── scripts/
│ ├── generate-theme-overrides.py ← Token 覆盖生成
│ └── recolor-icons.py ← SVG 图标换色
├── references/
│ ├── component-catalog.md ← 60 组件 HTML 范式
│ └── token-contract.md ← ~100 Design Token + 暗色模式
└── assets/
└── themes/meeting-classic/ ← 组件 CSS + 暗色 token + SVG 图标集
