# 开发文档

*Hearo（听见）实时语音 AI 平台 · 从接入到上线的完整参考*

Hearo 是一套可自部署的实时语音 AI 平台：把麦克风音频实时送入云端，做语音识别（ASR）→ 大模型（LLM）→ 语音合成（TTS），并支持随时打断（barge-in）。默认接入链路是 **WSS + 16 kHz 单声道 PCM**，设备也可通过 **MQTT** 接入，另外提供 **WebRTC（实验）** 的浏览器 Opus 路径。它们最终都汇聚到同一个「房间」，AI 智能体作为房间的一个参与者加入对话。

## 整体架构

```text
浏览器 / SDK              IoT / aispea 设备
      │ WSS（默认）/ WebRTC（实验） │ MQTT
      ▼                          ▼
┌───────────┐          ┌──────────────┐
│  gateway  │          │ mqtt-gateway │
│ (边缘/转码)│          │ (broker+适配) │
└─────┬─────┘          └──────┬───────┘
      │      内部媒体          │
      ▼                       ▼
   ┌────────┐   作为参与者加入   ┌─────────────┐
   │  room  │ ◀──────────────── │agent-runtime│
   │ (路由器) │                  │ ASR→LLM→TTS │
   └────────┘                   └─────────────┘
        ▲
        └──── 控制台 console（签发 token / 调度智能体）
```

- **gateway** 是 WSS 与 WebRTC（实验）的边缘（鉴权 + 音频转码，统一成 16k 单声道 PCM）；
- **mqtt-gateway** 是 MQTT 的边缘：内嵌 broker + 原生/aispea 两套协议适配，可水平扩展；
- **room** 是与厂商无关的「媒体/数据路由器」，参与者（人或 AI）在房间里互通音频与控制消息；
- **agent-runtime** 是运行并调度语音智能体的 Go 服务；
- **console** 是控制面：签发 token、配置厂商 key、调度智能体。

> 💡 **先体验，再接入**：想立刻看效果？在 [房间与分组](/docs/rooms) 里新建一个房间，点「网页进入」即可在浏览器内连线、邀请 AI、调 VAD 参数——它本身就是一个实时调试台。

## 选择接入方式

- **WebSocket**：默认且最通用，适合自定义客户端、IoT、服务器中转；推荐使用 WSS + PCM。
- **WebRTC（实验）**：浏览器 Opus 接入路径，适合验证原生回声消除与抖动缓冲；生产接入优先使用 WSS + PCM。
- **MQTT**：低带宽 / IoT 设备；连 mqtt-gateway，CONNECT 带客户端 Token 或设备接入密码。已有 aispea/cyberbase 设备可零改动接入。

## 文档导航

- [快速开始](/docs/quickstart)：5 分钟跑通——建 API Key → 建客户端 → 签 token → 浏览器对话 → 邀请 AI。
- [鉴权与 Token](/docs/auth)：工作空间 API Key + 客户端 Token（两层凭据）。
- [客户端与接入模型](/docs/clients)：统一的「客户端 → 房间」接入模型。
- [房间与分组](/docs/rooms)：房间管理、默认智能体、网页进入、匿名分享链接。
- [WebSocket](/docs/websocket) / [WebRTC（实验）](/docs/webrtc) / [MQTT 接入](/docs/mqtt) / [aispea 设备接入](/docs/aispea-mqtt)：各传输的协议细节。
- [交互模式与 VAD](/docs/modes) · [AI 智能体](/docs/agents) · [实时字幕与翻译](/docs/captions)：能力。
- [REST API](/docs/rest-api) · [SDK 与示例](/docs/sdk)：参考。