# 简化聊天接口（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)。部署、编译测试与真实火山对话实测是不同验证层次，实测结果以交付记录为准。