12 KiB
12 KiB
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。
- 缺失/无效/过期 token →
- 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或 WSchat的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）。