Cyrene_v2/Docs/api-reference.md

# Cyrene v2 后端 API 完整参考（api-reference.md）

> **用途**：本文档是 Cyrene v2 **全部后端 API（REST + WebSocket）的唯一详细参考**，供 Web 前端 / 移动端 / 原生客户端 / IM 桥接等**跨平台客户端开发者**使用。所有字段名、取值、鉴权规则、状态码均**以代码为准**（`internal/services/gateway/*.go`）。
> **主文档关系**：`Docs/api-client.md` 为面向使用者的**摘要**；`Docs/api-reference.md` 为**超详细主文档**。
> **维护铁律**：每实现/变更一个端点或 WS 事件必须同步更新本文档；契约变更版本化（REST 走 `/api/v1`，未来破坏性变更升 v2），不得破坏既有客户端。
> **当前版本**：以代码为准（gateway 已在 M0–M16 若干里程碑落地；详见各端点「里程碑」注记）。

---

## 0. 基础约定（全局）

- **Base URL**：`http://<host>:8080`。网关是唯一对外端口（单二进制、单端口 `:8080`、零跨进程 IPC 红线）；生产一般经反向代理 + HTTPS。
- **版本**：REST 全部挂在 `/api/v1/{resource}`；WS 挂 `/ws/chat`；管理端点挂 `/api/v1/admin/*`。
- **响应统一信封**：
  - 成功：`{"data": <payload>}`（HTTP 200 / 201 / 202 / 204）。
  - 失败：`{"error": {"code": <string>, "message": <string>}}`（HTTP 400/401/403/404/409/500/501 等）。
- **错误码**：业务错误带稳定字符串 `code`（如 `unauthorized` / `not_found` / `bad_request` / `chat_busy` / `not_implemented`），便于客户端分支；`message` 面向人读。
- **CORS**：`Access-Control-Allow-Origin` 为配置的 `ALLOWED_ORIGINS` 白名单（`*` 时放开）；`Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`；`Allow-Headers: Authorization, Content-Type`；`Max-Age: 600`。`OPTIONS` 预检直接回 `204`。同源/无 Origin 请求放行。**注意：CORS 只允许 `Authorization, Content-Type` 头——若客户端要额外发送 `X-API-Version`，需自行在网关侧放开或仅作为文档惯例（当前服务端**不校验**该头）。**
- **请求日志**：每个请求由 `logging` 中间件记录一行（method/path/status/duration_ms），并计入可观测性指标。panic 由 `recover` 中间件兜底为 `500 {error:{code:internal,...}}`，不崩溃进程。
- **超时**：WS 连接 ping 周期 54s、pong 等待 60s、写超时 10s；读上限 4096 字节/帧。

### 0.1 鉴权模型（RBAC）

认证基于 **JWT Bearer**（`internal/auth`），角色层级 **owner > admin > viewer**（`owner` 满足 admin/viewer，`admin` 满足 viewer，`viewer` 仅满足 viewer）。

- **获取 token**：`POST /api/v1/auth/login`（见 §2.2）。token 有效期 **24 小时**（`tokenTTL`），签发角色恒为 `owner`。
- **REST 鉴权**：请求头 `Authorization: Bearer <JWT>`。`s.auth.Authorize(...)` 中间件：
  - 缺失/无效/过期 token → `401 {error:{code:"unauthorized",...}}`。
  - 有效 token 但角色不足 → `403 {error:{code:"forbidden",...}}`。
  - `Authorize()`（无参）→ 任意**已认证**角色通过（only read metadata, e.g. GET /sessions、GET /personas）。
  - `Authorize(owner)` → 仅 owner；`Authorize(owner, admin)` → owner 或 admin。
- **WS 鉴权**：`GET /ws/chat` 通过 `?token=<JWT>` 或 `Authorization: Bearer` 取 token（`wsToken`），`Verify` 通过即可升级；**不做角色门槛**（任何有效 token 均可连接），但 `history` 回放与 `proactive` 推送等按角色处理（见 §6）。
- **API Key（`X-API-Key`）**：⚠️ **当前实现未接入**。认证/授权中间件 `Authorize` 只校验 `Authorization: Bearer <JWT>`。`POST /api/v1/admin/users/apikey` 会**签发**一个明文 API key（仅返回一次），`GET /api/v1/admin/users` 会列出其掩码，但**网关的鉴权中间件目前不接受 `X-API-Key` 头**（`auth.APIKey.Verify/Lookup` 仅在单元测试中调用）。本文档按代码如实标注：**所有端点实际鉴权 = Bearer JWT**。若未来把 API key 接入中间件，需同步更新本档。

### 0.2 X-API-Version 头

`Docs/api-client.md` 约定客户端每个请求带 `X-API-Version: 1`。**当前服务端不校验该头**（未在代码中读取），仅作为客户端契约惯例；如需服务端强校验，需另行实现。本文档在 curl 示例中**带上该头**以示惯例。

### 0.3 上传 / 媒体（重要确认）

- **无 `/upload` 端点**。图片走 `POST /api/v1/chat` 或 WS `chat` 的 `image` 字段（**base64 data: URI** 或 http(s) URL，入视觉真推理，见 §6 流式与直连）。
- **无 REST 语音端点**。语音**只走 WS**：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64）。见 §6.5。
- 管理端导入知识文档（RAG）也走 JSON body 文本（`POST /api/v1/admin/rag`），非文件上传。

---

## 1. REST 端点总览

> 下表为**全量登记**；下文 §2–§5 每端点给出字段级说明。`鉴权列`：`无` / `JWT`(任意已认证) / `owner|admin` / `owner`。`里程碑` 为代码/设计归属的大致里程碑（M8 网关、M9 前端、M10 补齐写、M16 会话持久化等）。

### 1.1 公开（无鉴权）

| # | 方法 | 路径 | 状态 | 说明 | 里程碑 |
|---|------|------|:---:|------|:---:|
| 1 | GET | `/api/v1/health` | 200 | 存活探针 `{status:"ok"}` | M8 |
| 2 | POST | `/api/v1/auth/login` | 200 | 换取 JWT（恒 owner） | M8 |

### 1.2 用户侧（已认证）

| # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
|---|------|------|------|:---:|------|:---:|
| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/409 | 发消息（同步回复或触发 WS 流式） | M8/M15 |
| 4 | GET | `/api/v1/sessions` | JWT | 200 | 会话列表（持久化会话 or 渠道会话回退） | M16 |
| 5 | GET | `/api/v1/personas` | JWT | 200 | 人格列表 | M8 |
| 6 | GET | `/api/v1/sessions/{id}/messages` | owner\|admin | 200 | 会话消息热分页 | M16 |
| 7 | POST | `/api/v1/sessions` | owner\|admin | 201 | 新建次级会话 | M16 |
| 8 | DELETE | `/api/v1/sessions/{id}` | owner\|admin | 200 | 删除次级会话 | M16 |

### 1.3 管理后台（`/api/v1/admin/*`）

读（`owner|admin`）＋ 写（`owner`，全程审计）。下表按注册顺序，标注鉴权与状态。

| # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
|---|------|------|------|:---:|------|:---:|
| 9 | GET | `/api/v1/admin/personas` | owner\|admin | 200 | 人格列表 | M8 |
| 10 | GET | `/api/v1/admin/sessions` | owner\|admin | 200 | 会话列表 | M16 |
| 11 | GET | `/api/v1/admin/memories` | owner\|admin | 200 | 记忆列表 | M8 |
| 12 | GET | `/api/v1/admin/plugins` | owner\|admin | 200 | 插件/能力列表 | M8 |
| 13 | GET | `/api/v1/admin/channels` | owner\|admin | 200 | 渠道列表 + 已配账号(掩码+bot 身份+capabilities) | M8/M17 |
| 14 | GET | `/api/v1/admin/channels/messages` | owner\|admin | 200 | IM 适配器日志流（全量/平台/适配器三粒度） | M16 |
| 15 | GET | `/api/v1/admin/channels/{platform}/messages` | owner\|admin | 200 | 某平台 IM 适配器日志流 | M16 |
| 16 | GET | `/api/v1/admin/iot` | owner\|admin | 200 | IoT 设备列表 | M8 |
| 17 | GET | `/api/v1/admin/llm` | owner\|admin | 200 | LLM 多厂商多模型组（APIKey 不回显） | M8/M15 |
| 18 | GET | `/api/v1/admin/automations` | owner\|admin | 200 | 自动化/提醒列表 | M8 |
| 19 | GET | `/api/v1/admin/users` | owner\|admin | 200 | 账号/API-key 列表 | M8 |
| 20 | GET | `/api/v1/admin/backthink` | owner\|admin | 200 | 后台思考记录 | M9/M10 |
| 21 | GET | `/api/v1/admin/rag` | owner\|admin | 200 | 知识库文档列表（可带 `?query=` 并入命中） | M10 |
| 22 | POST | `/api/v1/admin/rag/query` | owner\|admin | 200 | 知识库检索 | M10 |
| 23 | POST | `/api/v1/admin/rag/delete` | owner\|admin | 501 | 删除文档（写为 M10，当前 501） | M10 |
| 24 | GET | `/api/v1/admin/observability/metrics` | owner\|admin | 200 | 网关请求指标 | M10 |
| 25 | GET | `/api/v1/admin/observability/trace` | owner\|admin | 200 | 最近 trace span | M10 |
| 26 | GET | `/api/v1/admin/observability/audit` | owner\|admin | 200 | 审计记录 | M10 |
| 27 | POST | `/api/v1/admin/plugins/policy` | **owner** | 200 | 写工具策略（审计） | M8 |
| 28 | GET | `/api/v1/admin/sessions/{id}/export` | owner\|admin | 200 | 导出会话元数据 | M8 |
| 29 | POST | `/api/v1/admin/personas` | **owner** | 201 | 新建人格 | M8 |
| 30 | PUT | `/api/v1/admin/personas/{id}` | **owner** | 200 | 编辑人格 | M8 |
| 31 | POST | `/api/v1/admin/users` | **owner** | 501 | 新建用户（M10） | M10 |
| 32 | POST | `/api/v1/admin/users/apikey` | **owner** | 201 | 签发 API key | M8 |
| 33 | DELETE | `/api/v1/admin/users/apikey/{id}` | **owner** | 200 | 吊销 API key | M8 |
| 34 | POST | `/api/v1/admin/iot/{id}/control` | **owner** | 200 | 设备控制 | M8 |
| 35 | POST | `/api/v1/admin/iot/scenarios` | **owner** | 501 | IoT 场景（M10） | M10 |
| 36 | POST | `/api/v1/admin/iot/rules` | **owner** | 501 | IoT 规则（M10） | M10 |
| 37 | POST | `/api/v1/admin/automations` | **owner** | 201 | 新建自动化/提醒 | M8 |
| 38 | POST | `/api/v1/admin/automations/{id}/run` | **owner** | 200 | 手动触发规则 | M8 |
| 39 | DELETE | `/api/v1/admin/automations/{id}` | **owner** | 200 | 删除规则 | M8 |
| 40 | POST | `/api/v1/admin/llm` | **owner** | 201 | 保存 LLM provider 组（落盘 + 热更新） | M8/M15 |
| 41 | POST | `/api/v1/admin/llm/test` | **owner** | 200 | 真实模型调用测试 | M8/M15 |
| 42 | POST | `/api/v1/admin/channels/open` | **owner** | 200 | 连接渠道 | M8 |
| 43 | POST | `/api/v1/admin/channels/close` | **owner** | 200 | 断开渠道 | M8 |
| 44 | POST | `/api/v1/admin/channels/test` | **owner** | 200 | 结构性身份识别测试 | M8/M16 |
| 45 | GET | `/api/v1/admin/channels/{platform}/login-qr` | **owner** | 200 | 微信 iLink 扫码绑定 QR | M16 |
| 46 | GET | `/api/v1/admin/channels/{platform}/login-status` | **owner** | 200 | 微信 iLink 扫码状态 | M16 |
| 47 | GET | `/api/v1/admin/channels/{platform}/view` | **owner** | 200 | KOOK 账号聚合视图 | M17 |
| 48 | GET | `/api/v1/admin/channels/{platform}/friends` | **owner** | 200 | KOOK 好友/申请/屏蔽 | M17 |
| 49 | POST | `/api/v1/admin/channels/{platform}/friend/handle` | **owner** | 200 | KOOK 处理好友申请 | M17 |
| 50 | POST | `/api/v1/admin/channels/{platform}/message/test` | **owner** | 200 | KOOK 发送测试消息 | M17 |
| 51 | PUT | `/api/v1/admin/channels/{platform}/config` | **owner** | 201 | 保存渠道账号配置（落盘 + 热更新） | M16 |
| 52 | DELETE | `/api/v1/admin/channels/{platform}/config` | **owner** | 200 | 删除渠道账号 | M16 |
| 53 | POST | `/api/v1/admin/plugins/install` | **owner** | 501 | 安装插件（需源码清单） | M10 |
| 54 | POST | `/api/v1/admin/plugins/uninstall` | **owner** | 200 | 移除插件 | M8 |
| 55 | POST | `/api/v1/admin/memories` | **owner** | 201 | 手动添加记忆 | M8 |
| 56 | POST | `/api/v1/admin/memories/search` | **owner** | 200 | 记忆检索 | M8 |
| 57 | POST | `/api/v1/admin/rag` | **owner** | 201 | 导入知识文档 | M10 |
| 58 | POST | `/api/v1/admin/system/revoke-keys` | **owner** | 200 | 吊销全部 API key | M10/M11 |
| 59 | POST | `/api/v1/admin/system/rotate-jwt` | **owner** | 200 | 轮换 JWT 密钥 | M10/M11 |
| 60 | POST | `/api/v1/admin/system/backup` | **owner** | 200 | 备份数据库 | M10/M11 |
| 61 | POST | `/api/v1/admin/system/restore` | **owner** | 200 | 恢复数据库 | M10/M11 |

**另**：外部 webhook 回调（如 `webhook` 渠道的 HMAC 回调）由 composition root 通过 `Deps.Webhooks` 动态挂载，**不走网关鉴权**（handler 自校验签名/授权）；路径由调用方决定，不在上表枚举。

**WS**：`GET /ws/chat`（握手，JWT，见 §6）。