语音边界与话轮
VAD 提供语音起止信号，运行时负责话轮状态与输入收束。
默认媒体路径
WSS + PCM
16 kHz 单声道
设备接入
MQTT
原生协议适配
浏览器实验能力
WebRTC
明确标记实验性
所有参与者，在同一个房间相遇
外部协议在边缘终止。进入房间后，人、设备与 Agent 使用同一份媒体和控制契约。
边缘接入
WSS 设备
浏览器应用
MQTT 终端
AI 参与者
可编程房间PCM 音频与 JSON 控制
统一会话事件花名册、音频、字幕与控制
一次 AI 对话，仍然是一段房间会话
运行时管理话轮，把独立的 ASR、LLM 与 TTS 阶段串成流式响应，并在新语音出现时协同取消进行中的工作。
流式 ASR
将语音转换为阶段性与最终文本。
流式 LLM
读取最终上下文并持续生成回复。
流式 TTS
把回复合成为 Agent 参与者的音频。
字幕与翻译事件
启用后，转写与译文和音频共享同一个房间语境。
协同打断
检测到新的用户语音后，取消尚未完成的模型与合成任务，再开始下一话轮。
从房间列表走到一次真实联调
Room Operations 把当前节点状态、控制面记录与浏览器联调放进一条可重复的排查路径。
工作空间范围
定位工作空间内的房间
从受管记录与当前节点观测中找到目标房间，再进入详情。
一套房间模型，覆盖四类接入
在边缘选择协议，在房间内复用同一条实时媒体主线。
语音设备
使用 WSS 传输 PCM 或 Opus，房间绑定由客户端身份决定。
WSS 为默认路径浏览器与应用
使用 WSS + PCM 接入实时音频与事件。WebRTC 作为浏览器实验路径保留。
客户端 Token 隔离身份MQTT 终端
由 MQTT Gateway 终止原生或 aispea 协议，再桥接到同一个房间媒体入口。
边缘协议适配AI 参与者
Agent 使用工作空间限定的房间身份加入，并遵守与其他参与者相同的媒体与控制契约。
运行时能力取决于部署配置密钥留在服务端，客户端只拿连接身份
控制面把长期凭据与实时连接凭据分开。Gateway 再把客户端解析到工作空间限定的房间。
长期凭据
你的服务端
Workspace API Key 只用于服务端调用 Console API，不发送到浏览器或设备。
短期连接身份
客户端 Token
服务端只把工作空间范围内的客户端身份交给对应终端。
鉴权 + 房间解析
Gateway 解析
Gateway 验证 Token，再向控制面解析客户端绑定的房间。
限定后的房间名
工作空间限定房间
数据面使用 w_<workspaceId>:<room> 形式隔离同名房间。
浏览器不会收到 Workspace API Key、Provider Key 或房间签名密钥。
控制面与实时数据面，各自负责一件事
Console 管理持久配置与身份。独立实时服务终止协议、路由房间媒体并运行 AI 参与者。
Console 控制面
拥有 PostgreSQL 中的工作空间、客户端、房间记录与运行时配置。
身份与配置成员权限、客户端、Provider 配置与 Token 签发。
运营入口房间记录、来源状态与受权限约束的管理动作。
实时数据面
按内部媒体契约连接 Gateway、MQTT Gateway、Room 与 Agent runtime。
Gateway终止 WSS 与实验性 WebRTC，完成鉴权和音频适配。
MQTT Gateway终止 MQTT 并适配设备协议。
Room路由 canonical PCM、花名册与 JSON 控制。
Agent runtime作为参与者入房并执行配置好的 AI 话轮。
从身份到实时音频，路径保持清晰
服务端签发客户端身份，终端连接 Gateway，并进入控制面分配的房间。
创建客户端
在工作空间内建立设备或应用身份。
签发 Token
由服务端使用 Workspace API Key 签发。
连接 Gateway
默认通过 WSS 协商 PCM 音频。
进入房间
接收花名册、媒体与实时控制事件。
WSS 快速接入
// server.ts: keep the Workspace API Key on your server.
const response = await fetch(`${hearoConsole}/api/v1/clients/ephemeral`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HEARO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ room: "support", kind: "web" }),
});
const session = await response.json();
// Return only session.token from your authenticated app endpoint.
// client.ts: the browser receives a client token, never the API Key.
const { token } = await fetch("/api/voice-session", {
method: "POST",
}).then((result) => result.json());
const voice = new WebSocket(
`${gateway}?token=${encodeURIComponent(token)}&encoding=pcm_s16le`
);
voice.binaryType = "arraybuffer";