# 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>`；管理端另支持 `X-API-Key`。
- **响应统一**: `{"data": ...}` / `{"error": {"code": <string>, "message": <string>}}`；状态码 200/201/204/400/401/403/404/429/500。
- **错误码**：业务错误带 `code` 字符串（如 `unauthorized` / `not_found`），便于客户端分支。

---

## 1. REST 端点（公开）

> 下表为登记表：状态 `✅ 已实现` / `🕐 规划`。实现时补上 URL、方法、请求/响应示例。

| # | 端点 | 方法 | 认证 | 状态 | 说明 |
|---|------|------|------|:---:|------|
| — | `/api/v1/auth/login` | POST | 否 | 🕐 | 用户登录 → 返回 JWT |
| — | `/api/v1/sessions` | GET/POST | JWT | 🕐 | 会话列表/创建 |
| — | `/api/v1/chat` | POST | JWT | 🕐 | 发送 chat 消息（返回流或即时回复） |
| — | `/api/v1/personas` | GET | JWT | 🕐 | 人格列表/当前角色 |

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

> 仅供管理面板与授权客户端；RBAC：`owner`/`admin`/`viewer`；全程审计。

| # | 端点 | 方法 | 状态 | 说明 |
|---|------|------|:---:|------|
| — | `/api/v1/admin/users` | GET/POST | 🕐 | 用户/角色/API key 管理 |
| — | `/api/v1/admin/personas` | GET/POST/PUT/DELETE | 🕐 | 人格 CRUD |
| — | `/api/v1/admin/channels` | GET/POST | 🕐 | 渠道管理（含身份识别测试） |
| — | `/api/v1/admin/memories` | GET/PUT/DELETE | 🕐 | 记忆管理（检索/编辑/删除） |
| — | `/api/v1/admin/plugins` | GET/POST | 🕐 | 插件/能力/MCP |
| — | `/api/v1/admin/llm` | GET/PUT | 🕐 | LLM 模型/路由/降级配置 |
| — | `/api/v1/admin/automations` | GET/POST | 🕐 | 自动化与提醒 |

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

**下行（服务端→客户端）**: `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update`(流程图) / `auth`。
**上行（客户端→服务端）**: `mode_switch` / `chat` / `voice_input` / `subagent_ask`(子代理上下文查询) / `task_output_query`(后台任务输出查询)。

> 完整事件负载 schema 随 M8 实现补充到本文件。

---

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

## 5. 变更记录
- `v0.1`（契约先行）：建骨架 + 端点登记表；gateway 未实现，随 M8 逐条补全并更新本表。