Cyrene_v2/Docs/api/rest-api.md

Cyrene v2 — REST API 参考

Base URL: http://localhost:8080/api/v1
认证方式: Bearer Token (JWT)

---

认证

所有认证端点无需 Token。受保护端点需在 Header 中携带 Authorization: Bearer <token>。

POST /auth/register

注册新用户。

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)

{"token": "eyJhbGciOiJIUzI1NiIs..."}

错误

状态码	说明
400	用户名已存在 / 密码太短

---

POST /auth/login

登录获取 Token。

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin12345"}'

成功响应 (200)

{"token": "eyJhbGciOiJIUzI1NiIs..."}

错误

状态码	说明
401	用户名或密码错误

---

GET /health

健康检查（无需认证）。

curl http://localhost:8080/api/v1/health

响应 (200)

{"status":"ok","service":"cyrene-gateway","version":"2.0.0-dev"}

---

会话管理

POST /sessions

创建新会话。

curl -X POST http://localhost:8080/api/v1/sessions \
  -H 'Authorization: Bearer <token>'

响应 (201)

{"session_id": "a1b2c3d4e5f6"}

GET /sessions

获取会话列表。

响应 (200)

{"sessions": []}

DELETE /sessions/:id

删除指定会话。

响应 (204) — 无内容

---

记忆管理

GET /memory

获取当前用户的记忆列表。

curl http://localhost:8080/api/v1/memory \
  -H 'Authorization: Bearer <token>'

响应 (200)

{
  "data": [{
    "id": "uuid",
    "user_id": "admin",
    "content": "喜欢咖啡",
    "summary": "喜欢咖啡",
    "keywords": ["喜欢", "咖啡"],
    "category": "preference",
    "priority": 0.8
  }]
}

POST /memory

创建新记忆。支持自动去重。

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=关键词

搜索记忆（关键词匹配）。

curl "http://localhost:8080/api/v1/memory/search?q=咖啡" \
  -H 'Authorization: Bearer <token>'

响应 (200) — 返回匹配的记忆列表

---

语音服务

POST /voice/stt

语音识别（Speech to Text）。

curl -X POST http://localhost:8080/api/v1/voice/stt \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"audio_data":"base64..."}'

响应 (200)

{"text": "你好世界"}

⚠️ 当前为 stub 实现。生产环境需配置 DashScope API Key。

POST /voice/tts

文字转语音（Text to Speech）。

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)

{"audio_size": 0}

---

管理面板

GET /admin/dashboard

获取系统状态（需 admin 角色）。

curl http://localhost:8080/api/v1/admin/dashboard \
  -H 'Authorization: Bearer <admin_token>'

响应 (200)

{
  "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 协议文档。

---

错误码总览

状态码	含义	常见场景
200	成功	GET/PUT 请求
201	已创建	POST 成功
204	无内容	DELETE 成功
400	请求错误	参数缺失/格式错误
401	未认证	Token 无效或过期
403	无权限	非 admin 访问管理端点
404	未找到	资源不存在
405	方法不允许	用了错误的 HTTP 方法
429	限流	请求频率过高
500	服务器错误	内部异常
503	服务不可用	依赖服务未就绪

错误响应格式

{"error": "错误描述"}