Aska
7e3ec8da93
- Docs/api/rest-api.md: all 15 endpoints with curl examples - Docs/api/websocket.md: WS protocol, message types, reconnect strategy
279 lines
5.1 KiB
Markdown
279 lines
5.1 KiB
Markdown
# 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": "错误描述"}
|
|
```
|