feat: 后端统一消息类型分类 + 更新 API 文档
msg_type 现在由后端在所有消息路径上自动填充,前端无需解析内容猜测类型。
- chat_handler: SendSystemMessage → system_info, parseMultiMessage 返回 proactiveSegment{msgType}
- protocol: MultiMessageItem 增加 MsgType 字段
- useWebSocket: 所有 handler 直接读取 msg_type,移除前端类型推断
- docs/api/gateway-api.md: 文档化 msg_type 分类机制,移除已删除的每日简报章节
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
+17
-62
@@ -25,10 +25,9 @@ WebSocket 通过 query 参数传 token:`/ws/chat?token=<jwt_token>`
|
||||
10. [自动化规则与场景](#10-自动化规则与场景)
|
||||
11. [通知推送](#11-通知推送)
|
||||
12. [提醒管理](#12-提醒管理)
|
||||
13. [每日简报](#13-每日简报)
|
||||
14. [Webhook 第三方接入](#14-webhook-第三方接入)
|
||||
15. [Admin 管理](#15-admin-管理)
|
||||
16. [健康检查](#16-健康检查)
|
||||
13. [Webhook 第三方接入](#13-webhook-第三方接入)
|
||||
14. [Admin 管理](#14-admin-管理)
|
||||
15. [健康检查](#15-健康检查)
|
||||
|
||||
---
|
||||
|
||||
@@ -210,7 +209,7 @@ ws://<gateway>/ws/chat?token=<jwt>&session_id=<optional>&client_id=<optional>&de
|
||||
"text": "string (完整文本)",
|
||||
"content": "string (增量文本/完整内容)",
|
||||
"role": "user|assistant|action|system",
|
||||
"msg_type": "chat|action|thinking|tool_progress|system_info",
|
||||
"msg_type": "chat|action|thinking|tool_progress|system_info (后端始终填充,前端无需自行解析)",
|
||||
"session_id": "string",
|
||||
"error": "string (仅错误时)",
|
||||
"timestamp": 1717000000000,
|
||||
@@ -221,7 +220,7 @@ ws://<gateway>/ws/chat?token=<jwt>&session_id=<optional>&client_id=<optional>&de
|
||||
"tool_progress": { "tool_name": "string", "status": "started|running|completed|failed", "progress": 0.5, "message": "string" },
|
||||
"system_info": { "level": "info|warning|error", "message": "string", "action": "string" },
|
||||
"notification": { "id": "string", "type": "info|warning|success|thinking|reminder", "title": "string", "body": "string", "timestamp": "string", "data": {} },
|
||||
"multi_message": { "messages": [ { "index": 0, "content": "string" } ] },
|
||||
"multi_message": { "messages": [ { "index": 0, "content": "string", "msg_type": "chat|action|system_info" } ] },
|
||||
"review_messages": [ { "type": "action|chat", "content": "string", "delay_ms": 0 } ],
|
||||
"client_info": { "client_id": "string", "device_name": "string", "user_agent": "string" },
|
||||
"full_audio_url": "string",
|
||||
@@ -251,6 +250,15 @@ ws://<gateway>/ws/chat?token=<jwt>&session_id=<optional>&client_id=<optional>&de
|
||||
| `device_update` | IoT 设备状态更新 |
|
||||
| `background_thinking` | 后台思考状态变更 |
|
||||
|
||||
> **消息类型分类 (`msg_type`)**:所有 `response`、`multi_message`、`history_response`、`stream_chunk`、`thinking`、`tool_progress`、`system_info` 类型的服务端消息中,`msg_type` 字段均由后端自动分类填充,前端只需直接读取 `msg_type` 并据此渲染,无需解析消息内容来猜测类型。
|
||||
>
|
||||
> `msg_type` 可选值:
|
||||
> - `chat` — 普通聊天消息
|
||||
> - `action` — 动作/旁白消息(如 `(昔涟轻轻推开窗户)`),前端以斜体灰色样式渲染
|
||||
> - `thinking` — 后台思考过程,前端显示为可折叠详情块
|
||||
> - `tool_progress` — 工具执行进度,前端显示进度条
|
||||
> - `system_info` — 系统通知,前端居中显示为 toast 样式
|
||||
|
||||
---
|
||||
|
||||
### 流式响应流程
|
||||
@@ -837,60 +845,7 @@ delivered = true 表示目标用户有活跃 WebSocket 连接。
|
||||
|
||||
---
|
||||
|
||||
## 13. 每日简报
|
||||
|
||||
### GET /briefings — 按日期获取
|
||||
|
||||
`?user_id=xxx&date=2024-01-01` (date 默认今天)
|
||||
|
||||
```json
|
||||
// 响应 200
|
||||
{
|
||||
"briefing": {
|
||||
"id": "brief_xxx",
|
||||
"user_id": "string",
|
||||
"date": "2024-01-01",
|
||||
"summary": "AI 生成或回退摘要",
|
||||
"summary_source": "ai|fallback",
|
||||
"status": "pending|generated|delivered",
|
||||
"weather": {
|
||||
"location": "string", "temp": 22.5,
|
||||
"condition": "string", "icon": "☀️"
|
||||
},
|
||||
"news": [
|
||||
{ "title": "string", "url": "string", "source": "string", "summary": "string" }
|
||||
],
|
||||
"reminders": [
|
||||
{ "id": "string", "title": "string", "remind_at": "2024-01-01T15:00:00Z" }
|
||||
],
|
||||
"created_at": "...", "generated_at": "...", "delivered_at": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
briefing 为 null 时:`{"briefing":null, "message":"当日简报尚未生成"}`
|
||||
|
||||
### GET /briefings/latest — 最近简报
|
||||
|
||||
`?user_id=xxx&limit=7 (max 30)`
|
||||
|
||||
```json
|
||||
{ "briefings": [ Briefing ], "total": 7 }
|
||||
```
|
||||
|
||||
### POST /briefings/generate — 手动生成
|
||||
|
||||
```json
|
||||
// 请求
|
||||
{ "user_id": "string (必填)" }
|
||||
|
||||
// 响应 200
|
||||
{ "success": true, "briefing": Briefing, "message": "简报已生成并推送" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Webhook 第三方接入
|
||||
## 13. Webhook 第三方接入
|
||||
|
||||
Auth: `X-Webhook-Key` header。
|
||||
|
||||
@@ -930,7 +885,7 @@ Auth: `X-Webhook-Key` header。
|
||||
|
||||
---
|
||||
|
||||
## 15. Admin 管理
|
||||
## 14. Admin 管理
|
||||
|
||||
需要 JWT + admin 权限(`user_id == "admin"`)。非 admin 返回 **403**。
|
||||
|
||||
@@ -1059,7 +1014,7 @@ Auth: `X-Webhook-Key` header。
|
||||
|
||||
---
|
||||
|
||||
## 16. 健康检查
|
||||
## 15. 健康检查
|
||||
|
||||
### GET /health — 健康检查
|
||||
|
||||
|
||||
Reference in New Issue
Block a user