本文档面向设备端/客户端开发，说明如何与服务端 ChatBot 进行鉴权、建立 WebSocket 连接、上传语音音频并接收 TTS 音频与转写文本。

1. 术语与前置条件

- device_id：设备唯一标识（服务端已注册）。
- device_secret：设备密钥，仅在注册时返回一次，需安全存储在设备端，不可明文上报。
- nonce：服务端下发的随机挑战串，缓存 60s，仅能使用一次。
- signature/sign：HMAC_SHA256(device_secret, nonce) 的十六进制小写字符串。
- access token：JWT，包含 device_id 等 claim，用于 WS 鉴权。
  
部署建议：

- 生产环境必须使用 HTTPS/WSS。
- 服务端依赖缓存（通常是 Redis）存储 nonce 与用量统计。
  
2. 鉴权流程（必须）

ChatBot WebSocket 连接需要同时提供：

- token：JWT access token
- nonce：一次性挑战串
- sign：对该 nonce 的 HMAC 签名
  
注意：/device/token/ 在签发 token 成功后会删除该次 challenge 的 nonce（防重放）。因此建议按如下顺序做两次 challenge：

1. 获取 token 用的 challenge
2. 获取 WS 连接用的 challenge
  
2.1 获取 access/refresh token（Challenge-Response）

两步 challenge-response（避免明文传输 device_secret）：

1. 请求 nonce（challenge）
  
POST /device/challenge/

请求：
{ "device_id": "LYY-202603-000123" }

响应：
{ "nonce": "..." }

2. 计算签名并换取 token
  
- 在设备端计算 signature = HMAC_SHA256(device_secret, nonce) 并输出 hex（device_secret 不上送）。
  
在设备端计算：

signature = hex(HMAC_SHA256(key=device_secret, msg=nonce))

POST /device/token/

请求：
{ "device_id": "LYY-202603-000123", "signature": "<hex-hmac-sha256>" }

响应：
{ "access": "<access_jwt>", "refresh": "<refresh_jwt>" }

补充：

- nonce 在服务端缓存时间很短（约 60s），且成功使用后会被删除；过期或已使用需要重新获取 nonce。
  
2.2 刷新 access token（SimpleJWT 标准接口）

access token 过期后，使用 refresh token 换取新的 access：

POST /api/token/refresh/

请求：
{ "refresh": "<refresh_token>" }

响应：
{ "access": "<new_access_token>" }

2.3 获取 WS 连接用的 nonce/sign（每次连接前都做一次）

在每次发起 WebSocket 连接之前，再调用一次：

POST /device/challenge/ -> 得到 nonce_ws

在设备端计算：

sign_ws = hex(HMAC_SHA256(key=device_secret, msg=nonce_ws))

随后用 access token + nonce_ws + sign_ws 建立 WS 连接（见下一节）。

3. WebSocket 连接信息

3.1 连接地址

路径（服务端路由固定）：

- GET /ws/chatbot/
  
连接 URL（示例）：

wss://<host>/ws/chatbot/?token=<access>&nonce=<nonce_ws>&sign=<sign_ws>

3.2 语言选项参数（lang）

语言选项通过 Query String 附加在 WebSocket URL 末尾，在建立连接时一次性传入，连接期间不可更改（需重连才能切换语言）。

参数说明

参数
类型
说明
lang
string
指定 ASR 识别语言，不传则服务端默认偏中文识别

支持的语言值

显示名称
URL 参数
说明
默认
（不传 lang）
中英混合，偏中文
中文
lang=zh
中英混合，偏中文
英语
lang=en
中英混合，偏英文
广东话
lang=zh_yue
粤语方言
四川话
lang=zh_sc
四川方言
苏州话
lang=zh_su
苏州方言
日语
lang=ja

西班牙语
lang=es

俄语
lang=ru

韩语
lang=ko

越南语
lang=vi

德语
lang=de

阿拉伯语
lang=ar

印尼语
lang=id

泰语
lang=th

马来语
lang=ms

葡萄牙语
lang=pt

乌兹别克语
lang=uz

波兰语
lang=pl

波斯语
lang=fa


连接 URL 示例

不传语言参数（默认中英混合）：
wss://<host>/ws/chatbot/?token=<access>&nonce=<nonce_ws>&sign=<sign_ws>

指定中文（lang=zh）：
wss://<host>/ws/chatbot/?token=<access>&nonce=<nonce_ws>&sign=<sign_ws>&lang=zh

指定日语（lang=ja）：
wss://<host>/ws/chatbot/?token=<access>&nonce=<nonce_ws>&sign=<sign_ws>&lang=ja

代码示例（Python）

from urllib.parse import urlencode

# 基础参数
params = {
    "token": access_token,
    "nonce": nonce_ws,
    "sign": sign_ws,
}

# lang 示例值：
#   ""       -> 不传 lang（默认，中英混合偏中文）
#   "zh"     -> 中文
#   "en"     -> 英语（中英混合偏英文）
#   "ja"     -> 日语
#   "zh_yue" -> 广东话
lang = "zh"  # 按需修改

if lang:
    params["lang"] = lang

ws_url = f"wss://<host>/ws/chatbot/?{urlencode(params)}"

注意：语言参数在认证（获取 nonce_ws/sign_ws）之后、建立 WebSocket 连接之前拼入 URL。切换语言时需重新走一次认证流程并重建连接。

3.2 关闭码（Close Code）

服务端会在握手后主动关闭（客户端应根据 code 做重试或提示）：

- 4001：未授权（token 无效 / nonce 不存在或过期 / sign 校验失败 / 设备不存在或被禁用）
- 4002：当日使用时长超限（见 6. 用量限制）
  
4. 消息协议（客户端与服务端之间）

该 WS 同时使用两种 frame：

- Binary frame：原始音频字节流
- Text frame：JSON 控制/文本消息
  
4.1 上行（客户端 -> 服务端）

1. 语音输入（binary）
  
- 客户端在“按住说话”期间，持续发送 binary frame。
- binary 内容为原始 PCM 音频字节（服务端声明为 pcm16 输入）。
- 建议：小块发送（例如 20ms 到 100ms 一帧），避免单帧过大造成延迟抖动。
  
2. 松开按键/停止说话（text）
  
当用户结束一轮说话（例如松开按钮）后，发送：
{"action":"stop_speaking"}

服务端会提交输入缓冲并触发一次回答生成。

3. 打断当前回答（text）
  
当用户需要打断正在播报的回答并立即开始新一轮说话时，发送：
{"action":"interrupt"}

服务端会取消当前回答并清空输入缓冲，随后你可以继续发送新的音频 binary frame。

4.2 下行（服务端 -> 客户端）

1. TTS 音频输出（binary）
  
- 服务端会以 binary frame 方式持续下发回答音频 chunk，客户端应边收边播放。
- 服务端当前配置的输出音频格式为 pcm24（24-bit PCM 原始字节流）。
  
2. 文本转写增量（text）
  
服务端会下发 text frame（JSON）表示增量转写：
{"action":"transcript","text":"..."}

说明：

- text 为增量片段（delta），客户端可将其追加到当前显示文本上。
  
5. 推荐的客户端状态机

1. 连接前：确保已有 access token，并获取 nonce_ws/sign_ws。
2. 建立 WS：连接成功后进入 IDLE。
3. IDLE -> RECORDING：用户按住说话，开始周期性发送 PCM16 binary 帧。
4. RECORDING -> WAITING：用户松开按钮，发送 {"action":"stop_speaking"}，停止上行音频。
5. WAITING -> PLAYING：开始接收回答音频 binary 并播放，同时接收转写 text 并显示。
6. PLAYING -> RECORDING：若用户打断，先发送 {"action":"interrupt"}，停止播放，立刻进入录音并发送新音频。
7. 任意状态断线：若 close code 为 4001/4002 按原因处理；否则重新获取 nonce_ws/sign_ws 后重连。
  
6. 用量限制与连接管理

服务端会按“连接持续时间”累计当日使用时长（不是纯说话时长）：

- 当日上限：5 小时（5 * 60 * 60 秒）
- 超限后将拒绝新连接（close code 4002）
  
建议：

- 不用时及时断开 WS，避免空闲连接持续计费。
- 断线重连前重新获取 nonce_ws/sign_ws，不要复用旧 nonce。
  
7. 示例代码（Python，演示握手与 WS 交互骨架）

下面示例只演示流程与消息格式；音频采集与播放请按你的平台实现。

import requests, hmac, hashlib, json, asyncio, websockets

HOST = ""
BASE_HTTP = f"https://{HOST}"
BASE_WS = f"wss://{HOST}"

DEVICE_ID = "LYY-202603-000123"
DEVICE_SECRET = "<device_secret>"

def hmac_hex(secret: str, nonce: str) -> str:
    return hmac.new(secret.encode("utf-8"), nonce.encode("utf-8"), hashlib.sha256).hexdigest()

def get_nonce() -> str:
    r = requests.post(f"{BASE_HTTP}/dev