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

Docs/api/websocket.md

@@ -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 层保活。