# Cyrene v2 客户端 API 文档（用户侧）

> **面向**: Web 前端 / 移动端原生客户端 / IM 桥接等**跨平台客户端开发者**。
> **维护铁律**: 每实现/变更一个 API（REST 端点、WS 事件、admin API）**立即更新本文件**；契约变更必须版本化，不破坏既有客户端。
> **状态**: gateway 已在 M8 落地核心端点；M9 前端按此开发。**`✅` = 已实现**，`🕐` = 规划。

---

## 0. 基础约定
- **Base URL**: `http://<host>:8080`（网关唯一对外端口；生产一般经反代/HTTPS）。
- **版本**: REST 全部挂在 `/api/v1/{resource}`；未来破坏性变更升 v2。
- **认证**: `Authorization: Bearer <JWT>`（RBAC：`owner`/`admin`/`viewer`）；管理端另支持 `X-API-Key`。
- **响应统一**: `{"data": ...}` / `{"error": {"code": <string>, "message": <string>}}`；状态码 200/201/204/400/401/403/404/429/500。
- **错误码**：业务错误带 `code` 字符串（如 `unauthorized` / `not_found`），便于客户端分支。

---

## 1. REST 端点（公开）

| # | 端点 | 方法 | 认证 | 状态 | 说明 |
|---|------|------|------|:---:|------|
| 1 | `/api/v1/auth/login` | POST | 否 | ✅ | `{username,password}` → `{data:{token,jwt}}`（24h，owner） |
| 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式 |
| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}` |
| 5 | `/api/v1/personas` | GET | JWT | ✅ | `{data:[persona...]}` |

## 2. REST 端点（管理，`/api/v1/admin/*`）

> 仅供管理面板与授权客户端；RBAC：`owner`/`admin`/`viewer`（viewer 只读、写 403）；**写操作全程审计**。

| # | 端点 | 方法 | 状态 | 说明 |
|---|------|------|:---:|------|
| 1 | `/api/v1/admin/personas` | GET | ✅ | 人格列表 |
| 2 | `/api/v1/admin/sessions` | GET | ✅ | 会话列表 |
| 3 | `/api/v1/admin/memories` | GET | ✅ | 记忆列表（检索/编辑随 M10 扩展） |
| 4 | `/api/v1/admin/plugins` | GET | ✅ | 插件/能力列表（含 MCP/渠道） |
| 5 | `/api/v1/admin/plugins/policy` | POST | ✅ | 写工具策略（owner-only，审计） |
| 6 | `/api/v1/admin/channels` | GET | ✅ | 渠道列表/健康 |
| 7 | `/api/v1/admin/iot` | GET | ✅ | IoT 设备列表 |
| 8 | `/api/v1/admin/users` | GET/POST | 🕐 | 用户/角色/API key（M10） |
| 9 | `/api/v1/admin/llm` | GET/PUT | 🕐 | LLM 模型/路由/降级（M10） |
| 10 | `/api/v1/admin/automations` | GET/POST | 🕐 | 自动化与提醒（M10） |

> **M10 前端契约补充（管理面板，均🕐未实现，前端按契约封装、后端 404 时显示"待实现"壳，不报错）**：
> `GET /api/v1/admin/users`（用户/角色/API key）· `GET /api/v1/admin/llm` · `GET /api/v1/admin/automations` · `GET /api/v1/admin/backthink` · `GET /api/v1/admin/logs` · `GET /api/v1/admin/trace` · `GET /api/v1/admin/audit` · `GET /api/v1/admin/system`。写操作（策略/档案/密钥/系统设置）经前端审计登记，待后端 M10+ 落地真实持久化与热重载。

## 3. WebSocket `/ws/chat`（实时）

- **握手**: `ws://<host>:8080/ws/chat?token=<JWT>` 或 `Authorization: Bearer`；未认证在握手前回 `401` JSON。
- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:...}`——`stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update`。
- **上行（客户端→服务端）**: `mode_switch` / `chat`（跑 loop 并广播流式） / `voice_input` / `subagent_ask` / `task_output_query`。
- ⚠️ 语音/流式完整 schema 随 M9 前端联调补充；会话级定向（当前对所有连接广播）为后续项。

---

## 4. 客户端接入指引
- **认证**: 先 `POST /api/v1/auth/login` 取 JWT → WS 握手（`?token=`）注入。
- **版本**: 客户端请求头声明 `X-API-Version: 1`。
- **离线**: PWA / 原生端建议缓存 `sessions`/`personas` 列表。

## 5. 变更记录
- `v0.3`（M10）：管理面板 `/admin` 落地——按 §2 契约封装 admin 只读端点（personas/sessions/memories/plugins/channels/iot）+ owner-only `plugins/policy` 写；其余 M10 端点以契约路径封装、后端未实现时前端显式"待实现"壳。
- `v0.2`（M8）：gateway 落地——登录/health/chat/sessions/personas + admin 只读端点 + `plugins/policy` 写 + WS `/ws/chat`（JWT + bus 广播）。
- `v0.1`（契约先行）：骨架 + 端点登记表。