docs(api): add REST API reference and WebSocket protocol docs
- Docs/api/rest-api.md: all 15 endpoints with curl examples - Docs/api/websocket.md: WS protocol, message types, reconnect strategy
This commit is contained in:
Aska committed
1 parent
fbb331ed4b
commit
7e3ec8da93
2 files changed
+424
No files matched your search
@@ -0,0 +1,278 @@
|
||||
# Cyrene v2 — REST API 参考
|
||||
|
||||
> **Base URL**: `http://localhost:8080/api/v1`
|
||||
> **认证方式**: Bearer Token (JWT)
|
||||
|
||||
---
|
||||
|
||||
## 认证
|
||||
|
||||
所有认证端点无需 Token。受保护端点需在 Header 中携带 `Authorization: Bearer <token>`。
|
||||
|
||||
### `POST /auth/register`
|
||||
|
||||
注册新用户。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/auth/register \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username":"myuser","password":"mypassword"}'
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| username | string | ✅ | 用户名，不可重复 |
|
||||
| password | string | ✅ | 密码，最少 6 位 |
|
||||
|
||||
**成功响应** (201)
|
||||
```json
|
||||
{"token": "eyJhbGciOiJIUzI1NiIs..."}
|
||||
```
|
||||
|
||||
**错误**
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 400 | 用户名已存在 / 密码太短 |
|
||||
|
||||
---
|
||||
|
||||
### `POST /auth/login`
|
||||
|
||||
登录获取 Token。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username":"admin","password":"admin12345"}'
|
||||
```
|
||||
|
||||
**成功响应** (200)
|
||||
```json
|
||||
{"token": "eyJhbGciOiJIUzI1NiIs..."}
|
||||
```
|
||||
|
||||
**错误**
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 401 | 用户名或密码错误 |
|
||||
|
||||
---
|
||||
|
||||
### `GET /health`
|
||||
|
||||
健康检查（无需认证）。
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/health
|
||||
```
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{"status":"ok","service":"cyrene-gateway","version":"2.0.0-dev"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 会话管理
|
||||
|
||||
### `POST /sessions`
|
||||
|
||||
创建新会话。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/sessions \
|
||||
-H 'Authorization: Bearer <token>'
|
||||
```
|
||||
|
||||
**响应** (201)
|
||||
```json
|
||||
{"session_id": "a1b2c3d4e5f6"}
|
||||
```
|
||||
|
||||
### `GET /sessions`
|
||||
|
||||
获取会话列表。
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{"sessions": []}
|
||||
```
|
||||
|
||||
### `DELETE /sessions/:id`
|
||||
|
||||
删除指定会话。
|
||||
|
||||
**响应** (204) — 无内容
|
||||
|
||||
---
|
||||
|
||||
## 记忆管理
|
||||
|
||||
### `GET /memory`
|
||||
|
||||
获取当前用户的记忆列表。
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/memory \
|
||||
-H 'Authorization: Bearer <token>'
|
||||
```
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"id": "uuid",
|
||||
"user_id": "admin",
|
||||
"content": "喜欢咖啡",
|
||||
"summary": "喜欢咖啡",
|
||||
"keywords": ["喜欢", "咖啡"],
|
||||
"category": "preference",
|
||||
"priority": 0.8
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /memory`
|
||||
|
||||
创建新记忆。支持自动去重。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/memory \
|
||||
-H 'Authorization: Bearer <token>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"content":"用户喜欢喝咖啡","category":"preference","priority":0.8}'
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| content | string | ✅ | 记忆内容 |
|
||||
| category | string | | 分类：fact/preference/event/plan (默认 fact) |
|
||||
| priority | float | | 优先级 0.0-1.0 (默认 0.5) |
|
||||
|
||||
**响应** (201) — 返回创建的完整记忆对象
|
||||
|
||||
### `GET /memory/:id`
|
||||
|
||||
获取单条记忆。
|
||||
|
||||
**错误** — 404 Not Found
|
||||
|
||||
### `DELETE /memory/:id`
|
||||
|
||||
删除单条记忆。
|
||||
|
||||
**响应** (204) — 无内容
|
||||
|
||||
### `GET /memory/search?q=关键词`
|
||||
|
||||
搜索记忆（关键词匹配）。
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8080/api/v1/memory/search?q=咖啡" \
|
||||
-H 'Authorization: Bearer <token>'
|
||||
```
|
||||
|
||||
**响应** (200) — 返回匹配的记忆列表
|
||||
|
||||
---
|
||||
|
||||
## 语音服务
|
||||
|
||||
### `POST /voice/stt`
|
||||
|
||||
语音识别（Speech to Text）。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/voice/stt \
|
||||
-H 'Authorization: Bearer <token>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"audio_data":"base64..."}'
|
||||
```
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{"text": "你好世界"}
|
||||
```
|
||||
|
||||
> ⚠️ 当前为 stub 实现。生产环境需配置 DashScope API Key。
|
||||
|
||||
### `POST /voice/tts`
|
||||
|
||||
文字转语音（Text to Speech）。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/voice/tts \
|
||||
-H 'Authorization: Bearer <token>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"text":"你好","voice":"zh-CN-XiaoxiaoNeural"}'
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| text | string | — | 要转换的文本 |
|
||||
| voice | string | zh-CN-XiaoxiaoNeural | 语音角色 |
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{"audio_size": 0}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 管理面板
|
||||
|
||||
### `GET /admin/dashboard`
|
||||
|
||||
获取系统状态（需 admin 角色）。
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/admin/dashboard \
|
||||
-H 'Authorization: Bearer <admin_token>'
|
||||
```
|
||||
|
||||
**响应** (200)
|
||||
```json
|
||||
{
|
||||
"dashboard": {
|
||||
"status": "running",
|
||||
"version": "2.0.0-dev",
|
||||
"uptime_sec": 3600,
|
||||
"services": {
|
||||
"memory": true,
|
||||
"voice": true,
|
||||
"ai_core": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket
|
||||
|
||||
### `GET /ws/chat?token=<jwt>`
|
||||
|
||||
升级到 WebSocket 连接。详见 [WebSocket 协议文档](websocket.md)。
|
||||
|
||||
---
|
||||
|
||||
## 错误码总览
|
||||
|
||||
| 状态码 | 含义 | 常见场景 |
|
||||
|--------|------|---------|
|
||||
| 200 | 成功 | GET/PUT 请求 |
|
||||
| 201 | 已创建 | POST 成功 |
|
||||
| 204 | 无内容 | DELETE 成功 |
|
||||
| 400 | 请求错误 | 参数缺失/格式错误 |
|
||||
| 401 | 未认证 | Token 无效或过期 |
|
||||
| 403 | 无权限 | 非 admin 访问管理端点 |
|
||||
| 404 | 未找到 | 资源不存在 |
|
||||
| 405 | 方法不允许 | 用了错误的 HTTP 方法 |
|
||||
| 429 | 限流 | 请求频率过高 |
|
||||
| 500 | 服务器错误 | 内部异常 |
|
||||
| 503 | 服务不可用 | 依赖服务未就绪 |
|
||||
|
||||
**错误响应格式**
|
||||
```json
|
||||
{"error": "错误描述"}
|
||||
```
|
||||
@@ -0,0 +1,146 @@
|
||||
# Cyrene v2 — WebSocket 协议
|
||||
|
||||
> **端点**: `ws://localhost:8080/ws/chat?token=<jwt>`
|
||||
> **协议**: JSON 文本帧
|
||||
|
||||
---
|
||||
|
||||
## 连接
|
||||
|
||||
```
|
||||
ws://localhost:8080/ws/chat?token=eyJhbGciOi...
|
||||
```
|
||||
|
||||
Token 通过 query 参数传递，需先通过 `/api/v1/auth/login` 获取。
|
||||
|
||||
---
|
||||
|
||||
## 客户端 → 服务端
|
||||
|
||||
### 发送消息
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "message",
|
||||
"content": "你好呀",
|
||||
"session_id": "abc123",
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| type | string | 固定 `"message"` |
|
||||
| content | string | 用户输入文本 |
|
||||
| session_id | string | 会话 ID（需先通过 REST 创建） |
|
||||
| timestamp | number | Unix 毫秒时间戳 |
|
||||
|
||||
---
|
||||
|
||||
## 服务端 → 客户端
|
||||
|
||||
### `stream_chunk` — 流式输出
|
||||
|
||||
LLM 逐 token 推送。前端应累积拼接。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "stream_chunk",
|
||||
"content": "你",
|
||||
"session_id": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### `stream_end` — 流式结束
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "stream_end",
|
||||
"session_id": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### `response` — 独立消息
|
||||
|
||||
审查后的 action/chat 分段或系统响应。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "response",
|
||||
"content": "你好呀~ 有什么可以帮你的吗？",
|
||||
"session_id": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
> **action 消息**：当 content 包含 `[Intent: xxxx]` 前缀时，前端应居中斜体渲染。
|
||||
|
||||
### `device_update` — IoT 状态广播
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "device_update",
|
||||
"devices": [
|
||||
{"id": "light-livingroom", "name": "客厅灯", "type": "light", "state": {"power": true}, "online": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `notification` — 推送通知
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "notification",
|
||||
"title": "提醒",
|
||||
"body": "你设置的闹钟时间到了"
|
||||
}
|
||||
```
|
||||
|
||||
### `error` — 错误消息
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": "AI 引擎未配置"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整对话流程
|
||||
|
||||
```
|
||||
1. 浏览器 → POST /api/v1/auth/login → 获得 JWT Token
|
||||
2. 浏览器 → POST /api/v1/sessions → 获得 session_id
|
||||
3. 浏览器 → WS /ws/chat?token=<jwt> → WebSocket 连接建立
|
||||
4. 浏览器 → 发送 {"type":"message","content":"打开客厅灯","session_id":"..."}
|
||||
5. 服务端 → stream_chunk: "好"
|
||||
6. 服务端 → stream_chunk: "的"
|
||||
7. 服务端 → stream_chunk: "~"
|
||||
8. 服务端 → response: "[Intent: iot_control]"
|
||||
9. 服务端 → response: "客厅灯已经打开啦♪"
|
||||
10. 服务端 → stream_end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 重连策略
|
||||
|
||||
前端应实现指数退避自动重连：
|
||||
|
||||
| 重试次数 | 等待时间 |
|
||||
|---------|---------|
|
||||
| 1 | 1s |
|
||||
| 2 | 2s |
|
||||
| 3 | 4s |
|
||||
| 4 | 8s |
|
||||
| 5+ | 30s (上限) |
|
||||
|
||||
重连后需重新发送 `session_id` 绑定消息。
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 单连接单会话：一个 WebSocket 连接对应一个 `session_id`
|
||||
- Token 过期：服务端返回 `{"type":"error","error":"invalid token"}` 后关闭连接，前端应重新登录
|
||||
- 心跳：暂时无 ping/pong 协议，TCP 层保活。
|
||||
Reference in new issue
Block a user