Codex Local
bf1233d5df
ci / verify (push) Canceled after 0s
Add customer and operator login, BLE provisioning, device fleet controls, call memory, memoir generation, and refreshed family and maintenance portals. Include API contracts, migrations, firmware sources, tests, assets, and deployment documentation.
89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# 简化聊天接口（DIRECT-CHAT-1）
|
||
|
||
本文保留旧版 DIRECT-CHAT-1 协议说明。当前实现以 [老人专属智能体与设备聊天接口](elder-agent-flow.md) 为准：每位老人一个智能体，S2S 配置由服务器提交火山，不再发给设备。
|
||
|
||
## 流程
|
||
|
||
1. 设备向后端请求本次聊天参数。
|
||
2. 设备将 params 交给火山 RTC SDK，直接和火山进行语音聊天。
|
||
3. 火山通过每通独立的回调地址给后端发送文字，后端保存，设备不上传文字。
|
||
4. 设备停止 SDK，通知后端本次聊天结束。
|
||
|
||
基础地址：`https://121.41.46.238`。设备接口使用已有设备身份鉴权和 HTTPS，不再增加会话加密/证明包。
|
||
|
||
## 1. 开始聊天
|
||
|
||
`POST /api/v1/device/chat/start`
|
||
|
||
设备生成本次唯一 session_id，重试时不变；boot_id 为本次开机编号。
|
||
|
||
```json
|
||
{"session_id":"<本次会话UUID>","boot_id":"<本次开机UUID>"}
|
||
```
|
||
|
||
成功响应的 data：
|
||
|
||
```json
|
||
{
|
||
"session_id": "<原会话UUID>",
|
||
"bot_id": "<火山智能体ID>",
|
||
"params": {
|
||
"PlatformTaskID": "<原会话UUID>",
|
||
"Config": {
|
||
"S2SConfig": "<后端现有豆包配置对象>",
|
||
"MemoryConfig": {"Enable": false},
|
||
"SubtitleConfig": {"SubtitleMode": 1, "DisableRTSSubtitle": true}
|
||
},
|
||
"AgentConfig": {
|
||
"WelcomeMessage": "你好，今天想聊些什么？",
|
||
"ServerMessageURLForRTS": "<本通专属回调地址>",
|
||
"ServerMessageSignatureForRTS": "<本通回调校验值>"
|
||
}
|
||
},
|
||
"lease_expires_at_ms": 0,
|
||
"expires_at_ms": 0
|
||
}
|
||
```
|
||
|
||
上面 S2SConfig 和时间戳为示意，不是可直接运行的完整配置。params 序列化后传给 SDK；PlatformTaskID 由设备 SDK 适配层用于 GetRTCConfig 的唯一任务编号。
|
||
|
||
记忆：本版读取平台当前已授权的记忆内容，放进 S2SConfig 的会话上下文；不启用火山共享原生记忆库，不给设备数据库密码。不能声称这一版支持火山自动长期记忆同步。
|
||
|
||
内部保活复用 start 接口，每 10 秒自动请求一次同一 session_id，参数保持不变。租约最长 45 秒；解绑、授权撤回、记忆撤销或失联时停止音频。小程序不参与这一步，没有新增 heartbeat 接口。
|
||
|
||
缺少 S2S 配置返回 CHAT_S2S_CONFIG_REQUIRED；无需发布原来的 H01–H12 profile。首次供应商设备注册仍只做一次，单独保存设备级凭据，不是每通聊天步骤。
|
||
|
||
## 2. 火山回传文字
|
||
|
||
`POST /callbacks/v1/volcengine/chat?session_id=<本次会话UUID>`
|
||
|
||
使用火山原生格式：
|
||
|
||
```json
|
||
{"message":"<Base64字幕消息>","signature":"<本通回调校验值>"}
|
||
```
|
||
|
||
后端验证 signature、解码字幕，按 session_id 保存。相同说话人、roundId、sequence 的重复文字只存一次；不能用“设备最新会话”猜测归属。结束后晚到的文字仍写回原会话。
|
||
|
||
收到每句最终文字就保存，不要求火山最后一次性返回整段记录。未知说话人保留 UNKNOWN，不冒充用户记忆。字幕没有完整性结束证明时，不宣称记录百分之百完整。
|
||
|
||
## 3. 结束聊天
|
||
|
||
`POST /api/v1/device/chat/end`
|
||
|
||
```json
|
||
{"session_id":"<本次会话UUID>","reason":"hangup","sdk_stopped":true}
|
||
```
|
||
|
||
reason 可为 hangup、start_failed、disconnected、reboot、timeout。sdk_stopped 只有 SDK 确认停止才为 true。
|
||
|
||
成功响应 data：`{"session_id":"<本次会话UUID>","ended":true}`。
|
||
|
||
失败自动重试；断电保留待结束编号，重新联网后补报。服务端已接受结束的会话不能重新启动。此响应表示平台已登记结束，不冒充火山远端停止证明，不再要求人工对账才能开下一通。
|
||
|
||
## 小程序记录
|
||
|
||
沿用上一版的 `/api/v1/memories/calls/query` 和 `/api/v1/memories/calls/turns`，小程序页面无需另换接口。
|
||
|
||
官方依据：[硬件动态配置](https://www.volcengine.com/docs/6348/1807452)、[实时字幕](https://www.volcengine.com/docs/6348/1337284)。部署、编译测试与真实火山对话实测是不同验证层次，实测结果以交付记录为准。
|