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": "错误描述"}
|
||||
```
|
||||
Reference in new issue
Block a user