# 房间与分组

*房间是工作空间内的命名空间：同一房间内的客户端实时互通；可配默认 AI 智能体、用网页一键进入、生成匿名分享链接*

「房间」是工作空间内唯一、跨工作空间隔离的命名空间（底层限定为 `w_<工作空间>:<房间名>`，你只需用裸名字）。把多个客户端（设备/网页/App）指向**同一个房间**，它们就在一个房间里实时语音互通（群聊/通话）。房间既可以「随手输入名字即用」，也可以在 **房间 / 分组** 页登记成**受管房间**并挂配置。

## 在「房间 / 分组」页管理

| 操作 | 说明 |
|---|---|
| 新建房间 | 名称 + 描述 + 默认智能体 + 交互模式。也可在分配设备时直接输入新名字，自动登记。 |
| 分配设备 | 勾选客户端 → 选已有房间（或输入新名）→ 分配。改房间对在线设备实时生效（秒切）。 |
| 占用 | 每个房间显示「在线 N / 共 M」+ 在线状态点。 |
| 未登记房间 | 设备直接指向、还没登记的房间名会标「未登记」，一键「登记为房间」即可挂配置。 |
| 重命名 / 删除 | 重命名会同时迁移指向它的设备；删除只移除登记，设备绑定保留（回到未登记）。 |

## 房间默认智能体（自动进房）

给房间配置**默认智能体**后，**任何客户端进入该房间就会自动邀请这个智能体**（无论 MQTT / WebSocket / WebRTC（实验）/ 网页进入，因为它在统一的「进房」环节触发）；房间内最后一个客户端离开后，智能体**自动撤走**。

> 💡 **典型用法**：把「前台」房间的默认智能体设为你的客服 Agent —— 任何设备或访客进入前台，客服 AI 自动就位，无需每次手动邀请。

## 网页进入（Web Demo）

每个房间卡片上有 **「网页进入」**：直接在浏览器里以一个临时客户端进入该房间，麦克风对话测试。进入即走统一的「进房」流程，所以房间的默认智能体也会自动出现。适合你（已登录的运营者）快速联调。

## 匿名分享链接（复制链接）

房间卡片上的 **「复制链接」** 生成一条**可重复使用的签名链接**，形如：

```text
https://<你的控制台域名>/join?invite=<签名令牌>
```

把链接发给任何人，**无需登录**即可打开、**填写自己的昵称**后连接说话。每位访客打开链接都会**各自获得一个独立的临时客户端**，进入这个房间。链接用工作空间的隐藏密钥签名、只授权「进入这个房间」，**不包含** API Key 或签名密钥。

| 维度 | 值 | 说明 |
|---|---|---|
| 谁能用 | 匿名访客 | 不需要账号；打开链接即可 |
| 进入哪个房间 | 固定 | 链接里签名绑定，访客改不了 |
| 身份 | 每人独立临时客户端 | 自动创建、带 TTL，会话后回收 |
| 昵称 | 访客自填 | 进入前填写，作为房间内显示名 |

> ⚠️ **务必 HTTPS**：分享链接携带签名令牌，请通过 HTTPS 分发；任何拿到链接的人都能进入该房间，按需控制传播范围。

## 群聊 / 多人通话

把多台设备（或多个网页访客）放进**同一个房间**即群聊：彼此的音频在房间内混合广播。再给房间配个默认智能体，就是「多人 + AI」的房间。设备入库与房间绑定见 [客户端与接入模型](/docs/clients)。

## 临时客户端

网页进入 / 分享链接创建的都是**临时客户端**（`ephemeral`），带过期时间、会话后自动回收。在 **设备** 页可用「全部 / 常驻 / 临时」筛选，并在「类型」列看到「临时」徽章与到期时间，便于和常驻硬件区分。