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 逐条补全并更新本表。

3.3 KiB Raw Blame History Unescape Escape