Cyrene_v2/Docs/api-reference.md

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

> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.55`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
> **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。
> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**仍未登记的端点 / WS 事件清单见 `DevDocs/audit/00-总览.md` §4④**，属后续「文档补全」批次，本文件暂不补全。
> **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。

---

## 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, X-API-Version`；`Access-Control-Expose-Headers: X-Voice-Provider`（跨域浏览器可读语音降级信号头）；`Max-Age: 600`。`OPTIONS` 预检直接回 `204`。同源/无 Origin 请求放行。**注意：`X-API-Version` 仅作**advisory**惯例头（见 §0.2）——CORS 已放行但它**不参与服务端版本协商**，服务端当前不校验、不据此改变行为。**
- **请求日志**：每个请求由 `logging` 中间件记录一行（method/path/status/duration_ms），并计入可观测性指标。panic 由 `recover` 中间件兜底为 `500 {error:{code:internal,...}}`，不崩溃进程。
- **超时**：WS 连接 ping 周期 54s、pong 等待 60s、写超时 10s；读上限 4096 字节/帧。
- **数据目录 `DATA_DIR`（v0.55）**：默认 `./data`；**新增保留字哨兵 `platform`（大小写不敏感）** → 平台标准数据目录（Windows `%APPDATA%\Cyrene`、macOS `~/Library/Application Support/Cyrene`、Linux `~/.local/share/cyrene`，`internal/platform.DefaultDataDir()`）。显式路径与**显式空值**行为均不变（空值仍走组合根原兜底）。
- **管理面板安全入口 `ADMIN_PATH`（v0.55，env 默认 `admin`）**：面板**前端**挂在 `/<ADMIN_PATH>`（可配成 `xxx/admin`；**非法值回退 `/admin`**，见 `config.ServerConfig.AdminPathPrefix()`）。命中前缀（含深链）→ 返回**注入了 `<base href="/">` 与 `window.__CYRENE_ADMIN_ENTRY__={"prefix":"..."}` 的 `index.html`**（`Cache-Control: no-store`）；**形如面板入口但前缀不符的路径 → `404`**（不回落用户端聊天壳）；前缀恰好命中 dist 真实文件则仍走文件服务器。**REST/WS 路径不随它变化**——`/api/v1/*`、`/api/v1/admin/*`、`/ws/chat`、webhook 一律原样（**API 不藏**，安全靠 JWT + 角色门，design/07 §0.1）；该前缀串**只注入面板入口页**，用户端 bundle 不含它（design/07 §0.2）。
- **额外监听端口的唯一豁免（v0.55 重述）**：`qq-obv11` 渠道的 **OneBot 反连 / HTTP 上报**模式需要独立 `net.Listen` 端口（`listen_addr`），这是 `AGENTS.md` §9 登记的例外（design/13 §0 原文即写「WS server / HTTP server」）；**必须由配置显式给出**，为空则报错、**绝不默认开启**。其余渠道/模式一律不得新开监听端口。

### 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，含 `viewer`，都可连接）。但**连接之后的帧按角色分档**（design/11 §7.2 上行 + §7.1 下行，2026-10-03 落实；**权威描述见 api-client §3 顶部的「两把角色门」，本节不重复维护**）：
  - **上行帧**：非 `owner`/`admin` 连接发来的**任何**上行 JSON 帧一律 **fail-closed 默认拒**，定向回 `{type:"error",data:{code:"forbidden"}}`——**不广播、不驱动模型、不落库**（`internal/services/gateway/ws_route.go` 的 `route` 首条语句即此门）。协议级帧（WS ping/pong/close）不受影响。
  - **握手 `history` 回放**：**仅 `owner`/`admin`** 连接收到（`internal/services/gateway/ws_history.go` 的 `replayHistory` 首行门）。
  - **下行帧**：只有 7 个**不含内容**的状态机信号（`session_busy`/`pending_ack`/`pending_drain`/`session_idle`/`session_interrupted`/`pending_full`/`session_read`）发给所有已认证连接；**其余全部**（正文 / 推理 / 工具 / 持久化与编辑删除的消息 / `graph_update` / `subagent_event` / `task_output` / `mood` / `device_update` / `reminder` …）**仅发 `owner`+`admin`**；未登记的新帧类型默认只发 owner/admin（`internal/services/gateway/ws_frame_scope.go` 的 `frameReachesAll`，fail-closed）。
  - **口径**：`viewer` = **可连接、可读 12 条只读监控 REST、可收 7 个状态机信号帧**；除此以外 WS 上拿不到任何内容、也发不出任何指令。
- **API Key（`X-API-Key`）**：**API key 已接入鉴权（v0.51，见 api-client.md §认证）**——已认证端点同时接受该头，命中签发表即通过且一律 `owner` 级，带该头时只走 key 分支（未知/已吊销/空值回 `401`、不回落 Bearer）；WS 握手仍只认 Bearer。

### 0.2 X-API-Version 头

`Docs/api-client.md` 建议客户端可带 `X-API-Version: 1`。**该头是 advisory 惯例头——服务端不校验、不据此协商版本，带不带行为完全不变**（`CORS Allow-Headers` 已放行它，跨域客户端发送不会预检失败）。若未来要真正版本化（`/api/v1` → 语义化协商），需另行实现服务端校验；在那之前客户端不应依赖它做任何行为分支。

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

- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。
- **REST 语音端点已存在**：`POST /api/v1/audio/transcribe`（STT）、`POST /api/v1/audio/speech`（TTS）、`POST /api/v1/audio/voice-clone`（声音复刻），均 owner-only + 审计，绕开 WS 4KB 帧限。语音也可走 WS `voice_input`（上行）/`voice_output`（下行）。
- 管理端导入知识文档（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 |
| 9 | PATCH | `/api/v1/sessions/{id}` | owner\|admin | 200 | 会话改名(A4) + 置顶(`pinned`, D5) body `{title?,pinned?}`（部分更新，只回显变更字段；见 §3.6a） | M16 |
| 10 | PATCH | `/api/v1/messages/{id}` | owner\|admin | 200 | 编辑单条消息(D3) body `{content}` | M16 |
| 11 | DELETE | `/api/v1/messages/{id}` | owner\|admin | 200 | 删除单条消息(D3) | M16 |
| 12 | GET | `/api/v1/meta/enums` | JWT | 200 | 客户端共享枚举权威表(B4)：`platform`/`mood`/`mode` + `unknown` 回落约定 | M8 |
| 13 | POST | `/api/v1/sessions/{id}/read` | owner\|admin | 200 | 推进已读游标(D4) body `{before?}`（缺省 = 现在）→ `{sessionId,readAt}`（见 §3.6b） | M16 |

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

> **鉴权分档（以 `internal/services/gateway/routes.go` 为准；权威矩阵见 `Docs/api-client.md` §2.0，本表已按其逐条核对）**：管理**读**分两层——**只读监控档 `owner|admin|viewer`**（12 条非敏感 GET：`personas` / `sessions` / `plugins` / `plugins/installed` / `channels` / `iot` / `automations` / `rag` / `observability/{metrics,trace,logs}` / `notifications`，后三条**尚未登记进下表**、见审计 `00-总览.md` §4④）与 **`owner|admin` 档**（含他人数据 / 消息正文 / 凭据面 / 审计流水）；**写一律 `owner`** + 全程审计。下表按注册顺序，标注鉴权与状态。

| # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
|---|------|------|------|:---:|------|:---:|
| 9 | GET | `/api/v1/admin/personas` | owner\|admin\|viewer | 200 | 人格列表 | M8 |
| 10 | GET | `/api/v1/admin/sessions` | owner\|admin\|viewer | 200 | 会话列表 | M16 |
| 11 | GET | `/api/v1/admin/memories` | owner\|admin | 200 | 记忆列表 | M8 |
| 12 | GET | `/api/v1/admin/plugins` | owner\|admin\|viewer | 200 | 插件/能力列表 | M8 |
| 13 | GET | `/api/v1/admin/channels` | owner\|admin\|viewer | 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\|viewer | 200 | IoT 设备列表 | M8 |
| 17 | GET | `/api/v1/admin/llm` | owner\|admin | 200 | LLM 多厂商多模型组（APIKey 不回显） | M8/M15 |
| 18 | GET | `/api/v1/admin/automations` | owner\|admin\|viewer | 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\|viewer | 200 | 知识库文档列表（可带 `?query=` 并入命中） | M10 |
| 22 | POST | `/api/v1/admin/rag/query` | owner\|admin | 200 | 知识库检索 | M10 |
| 23 | POST | `/api/v1/admin/rag/delete` | **owner** | 200/404 | 删除知识文档（项目索引条目 + 级联章节，真实删除；不存在 404） | 后 M12 |
| 24 | GET | `/api/v1/admin/observability/metrics` | owner\|admin\|viewer | 200 | 网关请求指标 | M10 |
| 25 | GET | `/api/v1/admin/observability/trace` | owner\|admin\|viewer | 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** | 200 | **热安装 MCP server 插件**（body `{kind:"mcp",name,config:{transport,endpoint?/command?,args?,apiKey?,env?}}` → 连接+发现+`RegisterTool` 进 registry → 落盘 `plugins.json` → `200 {data:{installed,name,kind,transport,toolCount}}`）；连接/发现失败 `502 plugin_install_failed` 且**不落盘**；非法 `400`；manager 未注入 `501` | 后 M12 |
| 54 | POST | `/api/v1/admin/plugins/uninstall` | **owner** | 200 | 移除插件（MCP → `Unregister`+删 `plugins.json` 配置；普通能力 → `reg.Remove`） | 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）。

---

## 2. 公开端点

### 2.1 GET /api/v1/health
- **鉴权**：无（探针）。
- **响应**：`200` `{"data":{"status":"ok"}}`。
- **备注**：仅存活探针；不含依赖健康状态。示例：

```bash
curl -s http://<host>:8080/api/v1/health
# => {"data":{"status":"ok"}}
```

### 2.2 POST /api/v1/auth/login
- **鉴权**：无（换取 JWT）。
- **请求 Body**（`loginRequest`）：

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `username` | string | 是 | 管理员用户名（对照 `cfg.Auth.AdminUser`） |
| `password` | string | 是 | 管理员密码（对照 `cfg.Auth.AdminPass`） |

```json
{"username":"admin","password":"s3cret"}
```

- **响应**：`200` `{"data":{"token":"<JWT>","expiresAt":<unix秒>,"role":"owner","refreshToken":"<opaque>"}}`（`loginResponse`）。

| 字段 | 类型 | 说明 |
|------|------|------|
| `token` | string | 已签名 JWT（HS256），下文请求头 `Authorization: Bearer <token>` |
| `expiresAt` | int64 | 过期时间，Unix 秒 = `now + 24h`（`tokenTTL=24h`） |
| `role` | string | **恒为 `"owner"`**（代码硬编码 `auth.RoleOwner`） |
| `refreshToken` | string | **不透明 256-bit 随机串**（B2）——服务端**仅存其 SHA-256 哈希**，明文只在响应出现一次；用于 `POST /api/v1/auth/refresh` 静默续期，`AUTH_REFRESH_TTL` 默认 `720h` |

- **错误**：`400` `{"error":{"code":"bad_request","message":"invalid request body"}}`（JSON 解析失败）；`401` `{"error":{"code":"unauthorized","message":"invalid username or password"}}`；`500` `{"error":{"code":"login_failed",...}}`（签名失败）。
- **备注**：登录响应**以代码为准** = `{token, expiresAt, role, refreshToken?}`（**不是** `{token,jwt}`）。`refreshToken` 是 B2 新增的非透明长期凭据（未接线 refresh 存储时**该键省略**，此时形状与 B2 之前一致）；旧 `api-client.md` §1 表内一行写 `{token,jwt}` 为**历史笔误**，以本档为准。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"s3cret"}'
# => {"data":{"token":"eyJ...","expiresAt":1799...,"role":"owner","refreshToken":"...base64url..."}}
```

### 2.3 POST /api/v1/auth/refresh（B2）
- **鉴权**：公开，body 带 `refreshToken`。
- **请求 Body**：`{refreshToken:"<opaque>"}`。
- **响应**：`200` `{"data":{"token":"<新JWT>","expiresAt":<unix秒>,"role":"<owner|admin|viewer>","refreshToken":"<新opaque？>"}}`（`role` 恒返回，取自该 refresh grant 记录的角色）——默认**单次使用旋转**：旧 refresh 立即作废并签发新的；`AUTH_REFRESH_ROTATE_DISABLED=true` 时旧 token 保持有效、不返回新 refresh（`refreshToken` 省略）。
- **错误**：`400 bad_request`（JSON 解析失败 / 空 token）；`401` `{"error":{"code":"invalid_grant",...}}`（未知/已撤销/已过期，统一口径，防枚举）；仅成功才审计。
- **curl**：`curl -s -X POST http://<host>:8080/api/v1/auth/refresh -H 'Content-Type: application/json' -d '{"refreshToken":"<opaque>"}'`

### 2.4 POST /api/v1/auth/logout（B2）
- **鉴权**：公开，两种方式二选一——body `{refreshToken}` 撤**单个** grant（幂等）；或无 body 但带 `Authorization: Bearer <jwt>` 撤**该账号全部** grant（全设备登出）。
- **响应**（**两种形状，别混**）：
  - body 撤单个：`200` `{"data":{"revoked":<bool>}}`（幂等——未知/已吊销的 token 得 `revoked:false` 而**不是**错误）。
  - Bearer 全撤：`200` `{"data":{"revoked":<bool>,"revokedCount":<n>}}`（`revokedCount` = 本次删除的该账号 refresh 行数，`revoked` = `revokedCount > 0`）。
- **错误**：不存在的 token 为幂等 no-op（仍 `200`）；非法 body `400`；`refreshToken` 与 `Authorization` **都没给**回 `400` `{"error":{"code":"bad_request","message":"refreshToken or Authorization bearer token is required"}}`；Bearer 无效/过期回 `401` `{"error":{"code":"invalid_grant",...}}`；撤销失败回 `500 logout_failed`。

---

## 3. 用户侧端点（已认证）

### 3.1 POST /api/v1/chat
- **鉴权**：`Authorization: Bearer <JWT>`，`Authorize(owner, admin)`（owner 或 admin）。viewer 不能写。
- **请求 Body**（`chatRequest`）：

| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `sessionId` | string | 否 | 目标会话 id；缺省 `"web"`（主会话）。子会话用 `web:<uuid>` |
| `text` | string | 是* | 用户文本。`text` 与 `image` 至少一项非空 |
| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 工具或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn。**语义（v0.53）**：主模型能否收图看生效组的 `multimodal`；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` 只配视觉/OCR **工具**的模型（见 api-client §1 行 3） |
| `deviceId` | string | 否 | 客户端生成的端标识（design/16 §4.5，如 `web:chrome:a1b2c3`），落库到消息，可选 |
| `mode` | string | 否 | 行为模式（design/01 §3、design/16 §5.1，如 `chat`/`code`/…）；随该轮落库供气泡渲染；**IM 恒 `chat`、缺省回落 `chat`**（`chatRequest.Mode`） |
| `stream` | bool | 否 | `true` = 经 WS 触发流式（`publishChatStream` 发 `ws.chat`），**立即返回**；缺省 / `false` = 同步返回完整回复（Go bool 零值即 false，仍**无「必填」约束**） |

```json
{"sessionId":"web","text":"你好","deviceId":"web:chrome:a1b2c3","stream":false}
```

- **响应**：
  - 同步（`stream=false`，会话空闲）`200` `{"data":{"reply":"<助手文本>","steps":<int>,"stopReason":"<string>"}}`（`chatResponse`）。`steps` 为工具循环步数，`stopReason` 为停止原因（如 `stop`/`idle`/`error`）。
  - 同步但会话**正忙**（`SubmitSync` 返回 `Pending`）`202` `{"data":{"queued":true,"queueDepth":<int>}}`（非阻塞 ack，稍后按上下文续接）。
  - 流式（`stream=true`）`200` `{"data":{"stream":true}}` —— 实际文本经 WS 推送（见 §6）。
- **错误**：
  - `400` `{"error":{"code":"bad_request","message":"text or image is required"}}`（空消息）。
  - `409` `{"error":{"code":"chat_busy","message":"会话正忙，待处理消息已满"}}`（pending 队列满，`PendingFull`）。
  - `500` `{"error":{"code":"chat_unavailable",...}}`（`runner` 未注入）/ `{"error":{"code":"chat_failed",...}}`（回合运行出错）。
- **备注**：
  - **会话编排（design/15）**：同会话正忙时新消息**不阻塞**、入 pending（默认上限 5）；满则 `409 chat_busy`。状态经 WS 状态事件通知（§6.4）。
  - 主会话 `web` 绑定**全量访问 env**（`loop.OwnerEnv()`：记忆读写 + 行为不变）。
  - 敏感字段（`image` 可能为 base64）不走日志明文。
  - curl：

```bash
TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"s3cret"}' | jq -r .data.token)
curl -s -X POST http://<host>:8080/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 1' \
  -d '{"sessionId":"web","text":"讲个笑话","stream":false}'
# => {"data":{"reply":"...","steps":2,"stopReason":"stop"}}
```

### 3.2 GET /api/v1/sessions
- **鉴权**：`Authorize()`（任意已认证角色可读元数据）。
- **响应**：注入 `HistoryStore` 时返回**持久化会话**（`historySessionSummary`）；否则回退渠道会话列表（`SessionSummary`，或 `[]`）。

**A) 持久化会话**（`history != nil`，主 + 子）：
```json
{"data":[
  {"id":"web","type":"main","title":"主控台","createdAt":1753...,"pinned":false,"unreadCount":2,
   "lastMessage":{"role":"assistant","content":"好的，我在。","createdAt":1753...},"personaId":"xilian"},
  {"id":"web:<uuid>","type":"sub","title":"临时小事","createdAt":1753...,"pinned":true,"unreadCount":0}
]}
```
- `id`：主会话恒 `"web"`；次级为 `web:<uuid>`。
- `type`：`"main"` | `"sub"`。
- `title`：可选（`omitempty`；首条用户消息到达时自动命名，无标题时缺该键）。
- `createdAt`：int64（Unix 毫秒）。
- `pinned`：bool，**恒返回**（D5 置顶标志；只是排序元数据，客户端无需第二次调用即可排序）。
- `unreadCount`：int，**恒返回**（D4；= 该会话中 `createdAt >` 已读游标的消息条数，`0` = 无未读）。它与 `lastMessage` 由**同一条 SQL** 派生，故查询数不随会话数增长（无 N+1）。
- `lastMessage`：可选（`omitempty`）；最后一条消息的纯展示预览 `{role("user"|"assistant"), content, createdAt}`——`content` 已折叠空白并截断到 **60 rune** 加省略号；**无消息的会话缺该键**。
- `personaId`：可选（`omitempty`，v0.42）；该会话绑定的角色 id（design/22 §2/§4.5）。**缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像。

**排序（以代码为准 = `pinned DESC, (type='main') DESC, created_at ASC`）**：置顶会话最前 → 未置顶的**主会话** → 未置顶的**子会话**（按 `createdAt` 升序）。⚠️ **置顶的次级会话会排在主会话之前**，因此客户端**不要假定「index 0 就是主会话」**；要定位主会话请按 `id == "web"`（或 `type == "main"`）查找。

**B) 渠道会话回退**（`history == nil`）：
```json
{"data":[{"platform":"kook","channelId":"...","sessionId":"...","actorRole":"owner","owner":true,"isGroup":false,"memWritable":true}]}
```
`SessionSummary` 字段：`platform` / `channelId` / `sessionId` / `actorRole`（`owner|admin|viewer|...`）/ `owner`(bool) / `isGroup`(bool) / `memWritable`(bool)。

- **错误**：`500` `{"error":{"code":"sessions_failed",...}}`（列表失败）。
- **备注**：`HistoryStore` 未注入时后端**不报错**，退化为渠道视图（向后兼容）。curl：

```bash
curl -s http://<host>:8080/api/v1/sessions -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 3.3 GET /api/v1/personas
- **鉴权**：`Authorize()`（任意已认证角色）。
- **响应**：`200` `{"data":[<PersonaSummary>...]}`（无 store 时 `[]`）。

`PersonaSummary` 字段（**契约**见 api-client §1 行 9；用户侧 `GET /api/v1/personas` 与管理员侧 `GET /api/v1/admin/personas` 同形，**唯一差别是 admin 侧多一个 `thinking?`**）：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 人格 id（`PersonaID`，回退 `ID`） |
| `name` | string | 显示名（`c.Name`） |
| `character` | string | 角色名（当前恒 = `name`） |
| `isDefault` | bool | 是否默认人格 |
| `mode` | string | 首个行为模式（`modes[0]`，未设置为 `""`；内置默认人格未配置 `modes`，故实际为 `""`） |
| `memoryNamespace` | string | 记忆命名空间。**读侧当前恒为空串 `""`**（`collectPersonas` 不填此字段——**已知实现事实，客户端不要依赖读侧的该字段**）；**人格写响应**（`POST`/`PUT /admin/personas`）才填真实值，未显式配置时为派生默认 `persona.<id>`（`loader.Persona.MemoryNamespace()`） |
| `avatar` | string | 视觉头像 URL（`omitempty`；该人格自己的，缺失则为空） |
| `chatBackground` | object | `omitempty`；`{landscape, portrait}` 双朝向壁纸，仅该人格自己的 |
| `mood` | string | **该角色当前情绪**（design/01 §2；恒返回，无 `omitempty`）。取值见 `GET /meta/enums` 的 `moods`；`""` = 该角色暂无被跟踪的情绪（**不伪造默认值**） |
| `thinking` | object | **仅 `GET /admin/personas` 返回**（`omitempty`，未配置则**无该键**）：`{budgetTokens,effort,showToUser,mode}` 推理/呈现旋钮；用户侧 `GET /personas` **不返回**（详见 api-client「人格 `thinking` 读侧契约」） |

```json
{"data":[{"id":"cyrene","name":"Cyrene","character":"Cyrene","isDefault":true,"mode":"","memoryNamespace":"","mood":"calm","avatar":"/images/Cyrene_Avatar/3rd_Form/Cyrene-3F-Q-Happy-1.png","chatBackground":{"landscape":"/images/Cyrene_ChatBackground/Landscape/3rd_Form/1.png","portrait":"/images/Cyrene_ChatBackground/Vertical/2nd_Form/1.png"}}]}
```
> 上例中 `memoryNamespace:""` 是**读侧的当前真实值**；`mood:"calm"` 来自默认人格 `configs/personas/cyrene.yaml` 的 `emotion.initialState`（其它角色可能为 `""`）。<!-- mood / memoryNamespace 的读写差异与 api-client §1 行 9 一致 -->

- **备注**：视觉资产按角色作用域读取，绝不返回别的角色的；缺失时前端回退中性默认。curl：

```bash
curl -s http://<host>:8080/api/v1/personas -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 3.4 GET /api/v1/sessions/{id}/messages
- **鉴权**：`Authorize(owner, admin)`（会话消息/thinking 属主人私密历史，viewer 不可读）。
- **Path**：`{id}` = 会话 id（`web` 或 `web:<uuid>`；IM 隔离会话 `sess-xxx` 亦可用）。
- **Query**：
  | 参数 | 类型 | 必填 | 默认 | 说明 |
  |------|------|:---:|------|------|
  | `limit` | int | 否 | 50 | 页大小，需 `>=1`，钳制上限 200（`maxPageLimit`）；非法回 400 |
  | `before` | int64 | 否 | 0 | 游标：上一页最旧消息的 `createdAt`（Unix 毫秒），向更旧翻页 |
  | `after` | int64 | 否 | 0 | **正向增量**（A5）：返回 `created_at > after`，**升序**；与 `before` **互斥**（同传 400）；负数/非数字回 400 |
  | `q` | string | 否 | - | **会话内搜索**（D2）：`content LIKE` 大小写不敏感，`%`/`_`/`\` 转义为字面量；仍倒序 + before/limit 游标；与 `after` 互斥（同传 400）；空 `q` 走普通分页；**严格限定单会话**（隔离会话不外泄） |
  | `platform` | string | 否 | - | 来源平台过滤（design/16 §4.4）。Web 端不传 = 全量共享主会话；IM 传本平台（如 `telegram`）只拉本渠道消息 |
- **响应**：`200` `{"data":[<historyMessage>...]}`；**`before` 时按时间倒序**（newest first，需 `reverse()` 渲染）；**`after` 时按时间升序**（最旧在前，可直接顺序渲染/追加）。

`historyMessage` 全字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 后端生成的消息 id（客户端据此去重） |
| `sessionId` | string | 会话 id |
| `role` | string | `user` / `assistant` |
| `content` | string | 正文（纯文本/图像消息文本；图像为 `image` 字段） |
| `mode` | string | 该条的模式（`omitempty`，供渲染气泡不用猜） |
| `mood` | string | 情绪标记（`omitempty`） |
| `image` | string | 图像引用（`omitempty`） |
| `thinking` | string | 思维链（`omitempty`；**本端点 owner/admin-only，故可达；公开回放/持久化广播中已剥离**） |
| `platform` | string | 来源平台（`web` / `telegram` / `weixin-ilink` / `qq-obv11`...，`omitempty`） |
| `deviceId` | string | 客户端端标识（`omitempty`，如 `web:chrome:a1b2c3`） |
| `senderName` | string | 第三方发送者昵称（`omitempty`；群聊/陌生人消息带，主人私聊为空） |
| `adapterId` | string | 产生该消息的适配器注册名（`omitempty`，如 `kook:3bef...`；Web 消息为空） |
| `createdAt` | int64 | Unix 毫秒（兼作分页游标） |

```json
{"data":[{"id":"m1","sessionId":"web","role":"assistant","content":"你好","mode":"normal","mood":"calm","platform":"web","deviceId":"web:chrome:a1b2c3","createdAt":1753...}]}
```

- **错误**：`400`（`limit`/`before`/`after` 非法、`before`+`after` 同传、`id` 缺失）；`501` `{"error":{"code":"not_implemented","message":"会话历史服务未配置（未注入 HistoryStore）"}}`；`500` `{"error":{"code":"messages_failed",...}}`。
- **备注**：热分页（design/16 §2.2,§5.1）。`thinking` 只在本 owner/admin 端点可见；WS 回放/广播已剥离。curl：

```bash
curl -s 'http://<host>:8080/api/v1/sessions/web/messages?limit=50&before=1753000000000&platform=web' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 3.5 POST /api/v1/sessions
- **鉴权**：`Authorize(owner, admin)`（写操作，变更持久态）。
- **请求 Body（可选）**：`{"personaId"?}`——**body 可完全省略或为空**。`personaId` 非空时把新会话绑定到该角色（未知角色回 `400 bad_request`）；省略 / 空 = 不绑（`persona_id=''`，继承全局默认角色）。**会话角色只在创建时写入、之后不可变**（design/22 §8-1；`PATCH /sessions/{id}` 一旦收到 `personaId` 键即 `400`）。`ownerID` 从 JWT claims 取作子会话归属。契约见 api-client §1 行 5。
- **响应**：`201` `{"data":{"sessionId":"web:<uuid>"}}`；`personaId` 非空时**回显**该字段（省略时响应形状与旧版一致）。
- **另**：若注入的 `HistoryStore` **不支持角色绑定**且显式传了 `personaId`，回 `501 not_implemented`（不假装写入）。
- **错误**：`501` `{"error":{"code":"not_implemented","message":"会话历史服务未配置（未注入 HistoryStore）"}}`；`500` `{"error":{"code":"session_failed",...}}`。
- **备注**：新建次级会话（`NewSubSession`），独立上下文回溯。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1' -d '{}'
# => {"data":{"sessionId":"web:0123abcd..."}}
```

### 3.6 DELETE /api/v1/sessions/{id}
- **鉴权**：`Authorize(owner, admin)`。
- **Path**：`{id}` = 会话 id。
- **响应**：`200` `{"data":{"deleted":"<id>"}}`。
- **错误**：
  - `403` `{"error":{"code":"forbidden","message":"the main session cannot be deleted"}}`（`history.ErrImmutableMain`，主会话 `web` 不可删）。
  - `400`（id 缺失）；`501`（无 HistoryStore）；`500` `{"error":{"code":"session_failed",...}}`。
- **备注**：删除次级会话及其全部消息。**未知会话 id 也回 `200`（幂等）**——删除只是影响 0 行，不报 `404`（删除目标已不在时「已删除」依然成立）。curl：

```bash
curl -s -X DELETE http://<host>:8080/api/v1/sessions/web:0123abcd... \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
# => {"data":{"deleted":"web:0123abcd..."}}
```

### 3.6a PATCH /api/v1/sessions/{id}
- **鉴权**：`Authorize(owner, admin)`（历史写；viewer → `403`）。
- **Path**：`{id}` = 会话 id。主会话 `web` **可以**改名/置顶，只是不可删。
- **请求 Body**：`{"title"?: string, "pinned"?: bool}`——**两个字段都缺失时回 `400`**（不支持「空 PATCH」）：
  - `title`：会话显示名。服务端 `TrimSpace` 后校验：**空白（`""` / 全空白）→ `400 title must not be blank`**；**超过 80 rune → `400 title is too long (max 80 characters)`**。**`""` 不能清空标题**——「`title` 存在但为空白」与「`title` 缺键」语义不同，后者才是「不改标题」；因此客户端**不提供「恢复自动命名」入口**（要换名只能给非空白标题）。
  - `pinned`：bool，置顶 / 取消置顶（D5）。
  - `personaId`：**不是可设置字段**——请求体里**出现该键（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）即 `400`**，错误消息点名 `personaId`；该检查在会话存在性检查**之前**执行，因此**未知会话 + `personaId` 回 `400`（不是 `404`）**，且与 `title` 同传时整体 `400`、**一个字段都不落库**（design/22 §8-1：会话角色创建时固定、之后不可变；v0.46）。
- **语义**：**部分更新**——只改请求中给出的字段；响应**只回显本次变更的字段**（title-only → `{id,title}`；pin-only → `{id,pinned}`；两者同给 → 三个键都在）。
- **响应**：`200`：
```json
{"data":{"id":"web:<uuid>","title":"新名字"}}
```
- **错误**：
  - `400` `{"error":{"code":"bad_request","message":"at least one of title or pinned is required"}}`（`title` 与 `pinned` 都缺）。
  - `400` `{"error":{"code":"bad_request","message":"title must not be blank"}}`（`title` 存在但 trim 后为空白）/ `"title is too long (max 80 characters)"`；`personaId` 出现即 `400`。
  - `404` `{"error":{"code":"not_found","message":"session \"<id>\" not found"}}`。
  - `501` `not_implemented`（未注入 HistoryStore）；`500` `{"error":{"code":"session_failed",...}}`（改名/置顶失败）。
- **curl**：
```bash
curl -s -X PATCH http://<host>:8080/api/v1/sessions/web:0123abcd... \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"pinned":true}'
# => {"data":{"id":"web:0123abcd...","pinned":true}}
```

### 3.6b POST /api/v1/sessions/{id}/read
- **鉴权**：`Authorize(owner, admin)`（历史写；viewer → `403`）。
- **请求 Body（可选）**：`{"before"?: int64}`——毫秒 Unix 时间戳。**缺省 / 空 body / `{}` = 现在**（「我看到的都算已读」）；给值 = 把游标推进到该时刻。
- **语义**：`createdAt <= readAt` 的消息算已读（`GET /sessions` 的 `unreadCount` 只数 `createdAt > readAt` 的）。**会话级单一游标、单 owner 账号**——读一处 = **该账号所有端已读**（无 per-device 游标）；**只前进不后退**（SQL `read_at = MAX(read_at, before)`），因此乱序/并发/重试请求幂等安全，绝不会把已读退回未读。
- **响应**：`200` `{"data":{"sessionId":"<id>","readAt":<推进后的游标毫秒>}}`。
- **错误**：`before` 为 `0`/负数 → `400 "before must be a positive millisecond timestamp"`；`before` 非数字或 body 非 JSON 对象 → `400 "invalid request body"`（**空对象 `{}` 合法** = 现在）；未知会话（含不在 `chat_sessions` 里的隔离会话 `sess-xxx`）→ `404`；未注入 HistoryStore → `501 not_implemented`；推进失败 → `500 session_failed`。
- **副作用**：成功后向下行广播 `session_read`（见 api-client §3.9），让同账号其它端**免刷新**清红点；**失败路径不广播**。
- **升级回填**：迁移 `0010` 把既有会话游标回填为「该会话现有最新消息时间」，升级当天不误报未读。
- **curl**：
```bash
curl -s -X POST http://<host>:8080/api/v1/sessions/web/read \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"before":1753000000000}'
# => {"data":{"sessionId":"web","readAt":1753000000000}}
```

---

### 3.7 GET /api/v1/meta/enums
- **鉴权**：`Authorize()`（**任意已认证角色**：owner/admin/viewer）——只读、无敏感信息，与 `GET /api/v1/sessions`（§3.2）同级。无 token 回 `401`。
- **用途**：客户端共享枚举权威表（Android 协同 B4，design/07 §6）。`platform`（消息来源平台）/ `mood`（情绪）/ `mode`（行为·呈现模式）此前只在文档里给示例，客户端各自硬编码映射导致来源角标与情绪标签漂移；本端点把三张表做成**机器可读的单一事实来源**，Web / Android / IM bridge 共用。
- **响应**：`200`
  ```json
  {"data":{
    "platforms":[{"id":"web","label":"网页"},{"id":"kook","label":"KOOK"},{"id":"qq-obv11","label":"QQ"},{"id":"weixin-ilink","label":"微信"},{"id":"telegram","label":"Telegram"},{"id":"webhook","label":"Webhook"}],
    "moods":[{"id":"calm","label":"平静"},{"id":"happy","label":"开心"},{"id":"excited","label":"兴奋"},{"id":"sad","label":"低落"},{"id":"angry","label":"生气"}],
    "modes":[{"id":"chat","label":"对话"},{"id":"code","label":"代码"},{"id":"home","label":"家居"},{"id":"work","label":"工作"},{"id":"docs","label":"文档"},{"id":"voice","label":"语音"},{"id":"vision","label":"视觉"},{"id":"agents","label":"智能体"},{"id":"settings","label":"设置"}],
    "unknown":"display-raw"
  }}
  ```
- **字段**：
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `platforms` | `[]{id,label}` | 来源平台：各内置适配器 `Name()`（`kook`/`qq-obv11`/`weixin-ilink`/`telegram`/`webhook`）+ Web 主会话来源 `web`（`history.PlatformWeb`） |
  | `moods` | `[]{id,label}` | 情绪：`internal/persona/emotion` 内置状态。状态机**可扩展**（persona 可经 `AddTransition` 注册更多状态），此表**非封闭集合** |
  | `modes` | `[]{id,label}` | 九模式（design/07 §1）；mode 只驱动呈现，不构成能力边界 |
  | `unknown` | string | 恒 `"display-raw"`：未知值回落约定（机器可读） |
  | `label` | string | **默认中文标签**，客户端可直接显示、也可按 i18n 覆盖；客户端比对应以 `id` 为准（小写、大小写敏感） |
- **错误**：仅 `401`（未认证）。无存储依赖，不会 `501`/`500`。
- **备注**：
  - **未知值回落约定（红线）**：客户端遇不在表中的取值**原样显示原始字符串**——**不丢弃、不报错、不替换占位符**；**服务端新增取值是非破坏性变更**（forward-compatible），旧客户端无需升级，也不得因未知值清空角标或抛错。
  - **单一事实来源在 Go 侧**：`internal/contract/enums`（`Platforms()`/`Moods()`/`Modes()`/`UnknownFallback`），网关只做投影（`internal/services/gateway/meta.go`）。
  - **反漂移**：`internal/contract/enums` 的测试断言三张表与「适配器 `Name()`」「`emotion` 内置状态」「前端 `types.ts` 的 `MODES`」一致；`cmd/cyrene` 另断言表内每个平台都能被渠道工厂构建——漏登记或幽灵条目即 FAIL。
  - Web 侧镜像：`frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 未知值返回原值），顶栏 / 侧栏 / 消息气泡的心情标签已改用。
  - curl：
    ```bash
    curl -s http://<host>:8080/api/v1/meta/enums -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
    # => {"data":{"platforms":[...],"moods":[...],"modes":[...],"unknown":"display-raw"}}
    ```

---

## 4. 管理后台 · 读端点（`owner|admin`）

> 以下端点 `鉴权 = Authorize(owner, admin)`（除特别标注 owner）。所有管理**读**不审计；管理**写**（§5）全程审计（who/what/when/result，见 §4.15）。

### 4.1 GET /api/v1/admin/personas
- 同 `GET /api/v1/personas`（§3.3），返回 `PersonaSummary[]`。`adminListPersonas` 直接复用 `collectPersonas()`。
- `200 {"data":[<PersonaSummary>...]}`。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/personas -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.2 GET /api/v1/admin/sessions
- 同 `GET /api/v1/sessions`（§3.2）：注入 HistoryStore 返回持久化会话（主 + 子）；否则回退渠道会话视图（`collectSessions`）。
- `200 {"data":[...]}`。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/sessions -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.3 GET /api/v1/admin/memories
- **响应**：`200 {"data":[<MemorySummary>...]}`（无 store 时 `[]`）。`MemorySummary` = `{id, scope, text}`。`scope` ∈ `user|persona|project`。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/memories -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.4 GET /api/v1/admin/plugins
- **响应**：`200 {"data":[<PluginSummary>...]}`（`PluginSummary` = `{name, kind, description, allowInGroup, allowInStranger}`）。`kind` 为能力类型，实际取值 = `tool|skill|channel|mcp|iot`（`internal/capability/registry` 的 `KindTool`/`KindSkill`/`KindChannel`/`KindMCP`/`KindIoT`）；`allowInGroup/allowInStranger` 为可达性策略（**落盘 `tool_policies`，重启保留**——迁移 `0012_tool_policy`；`SetPolicy` 先落库后改内存，落盘失败内存保持旧值并返回错误，无行的能力按默认 owner-only）。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/plugins -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.5 GET /api/v1/admin/channels
- **响应**：`200 {"data":[<ChannelSummary>...]}`。

`ChannelSummary` = `{name, connected, accounts?}`。`accounts` 为 `AdminChannelAccount[]`（掩码无 raw token），仅当 `s.channels` 注入且平台有已配账号时出现。
- `name`：平台名（如 `kook`、`telegram`、`weixin-ilink`）。
- `connected`：bool，该平台是否已连接。
- `accounts[]`（`AdminChannelAccount`）字段：`id` / `config`（掩码后的配置 map）/ `allowGroups` / `denyGroups` / `allowUsers` / `denyUsers` / `groupMsgPerMin` / `msgPerMin` / `maxMessages` / `botId?` / `botUsername?` / `botNickname?` / `capabilities?`（如 kook 的 `["friends","user_chats","channels","guilds","message_test"]`）。
  - `botId/botUsername/botNickname` 为**已连接 bot 的真实身份**（如 KOOK Connect 时调 `/api/v3/user/me` 解析），非敏感来自 live adapter。
  - `config` 值已脱敏（token 掩码 `****` + 尾 4）；`bot_token` 等密钥**绝不回显**。

- **聚合逻辑**：`channels.json` 是账号存在性的真源；一个裸平台 + 多账号合并为**一行**；无注册 adapter 但已配账号的平台仍出现（供查看配置）。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/channels -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.6 GET /api/v1/admin/channels/messages
- **鉴权**：`owner|admin`。
- **Query**：`limit`(默认50,上限200) / `before`(游标，Unix 毫秒) / `adapter`(适配器注册名，如 `kook:3bef...`) / `platform`。三粒度（互斥，`adapter` 优先，其次 `platform`，都不传=全量 IM 总览）。
- **响应**：`200 {"data":[<historyMessage>...]}`（newest first）。**本视图不过滤主会话**（因为它带 `adapter_id`）；按 `adapter_id`/`platform` 过滤。`historyMessage` 见 §3.4。
- **错误**：`501`（无 HistoryStore）。
- **备注**：IM 适配器日志页全量数据源 + 轮询兜底；实时增量走 WS `channel_persisted`（§6.3）。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/messages?adapter=kook:3bef...&limit=50' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.7 GET /api/v1/admin/channels/{platform}/messages
- **鉴权**：`owner|admin`。
- **Path**：`{platform}` = IM 平台（如 `telegram`）。
- **Query**：`limit`(默认50,上限200) / `before`(Unix 毫秒)。
- **响应**：`200 {"data":[<historyMessage>...]}`。**排除主会话 `web`**，只返回该平台非主人消息流（隔离 `sess-xxx`）。`senderName` 标发送者昵称；`adapterId` 标来源适配器。
- **错误**：`400`（platform 缺失）；`501`（无 HistoryStore）；`500`。
- curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/telegram/messages?limit=50' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.8 GET /api/v1/admin/iot
- **响应**：`200 {"data":[<iotDeviceSummary>...]}`（`iotDeviceSummary` = `{id, name, type, state, online}`；`state` 为 `map[string]any`）。无 store 时 `[]`。
- **错误**：`500` `{"error":{"code":"iot_failed",...}}`。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/iot -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.9 GET /api/v1/admin/llm
- **响应**：`200 {"data":{"providers":[<AdminLlmProvider>...]}}`（`AdminLlmConfig`）。
- `AdminLlmProvider`：`{id, name, provider, baseUrl, model, multimodal, enabled, fallback?, maxTokens?, reasoning, personaModels?, personaProviders?}`（**v0.53 新增三键**，见 api-client 的「模型配置契约（v0.53）」）；顶层 response 另含 `reasoningKinds` / `personaProviderOptions` 两个取值域数组（面板表单选项的唯一来源）。**`multimodal` = 主模型自己能否收图**（裁决 14.4.1）——它**不**表示「本部署有视觉能力」；视觉/OCR **工具**的模型由 `.env` 的 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 单独配置，与 `multimodal` 无关。`reasoning` 恒下发（`{kind}`，`kind:""` = 未声明形状）。
  - `provider` 协议 ∈ `openai|anthropic`；`name` 为友好标签（OpenAI/Anthropic 或组 id）。
  - `enabled`：index 0 的组为生效组 = `true`。
  - `maxTokens`：该组的 token 预算（`omitempty`，缺省/0 = 未设）；缺省时链末端回退步回落 `LLM_FALLBACK_MAX_TOKENS`（`.env`，默认 8192），再回落适配器默认（anthropic 8192）。
  - `reasoning`（v0.53，恒下发）：`{kind}` —— `kind` ∈ `auto|deepseek|openai|vllm|dashscope`，决定该组用哪种**提供商开关形状**下发推理指令（`""`/`auto` = 按模型名/baseURL 推断，形状有歧义就不下发）；详见 api-client「模型配置契约（v0.53）」。
  - `personaModels` / `personaProviders`（v0.53，`omitempty`）：**角色级模型 / 协议路由表**（`{personaId: modelId}` / `{personaId: "openai"|"anthropic"}`）；未配置 = 该键不出现。
  - `multimodal`：**主模型自己能否收图**（= 面板的「多模态」勾选）；视觉/OCR **工具**的模型是 `.env` 的 `LLM_VISION_MODEL`/`LLM_OCR_MODEL`，与本字段无关（裁决 14.4.1 修语义）。
  - **API key 永不返回**（wire 无 key 字段）。
- 数据源：`models.json` 各组（index 0 = 生效组）；无 `models.json` 时按 `.env` 合成单组。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/llm -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.9.1 GET /api/v1/admin/llm/catalog（v0.53，此前漏记）
- **鉴权**：`owner|admin` 读（**只读**）。**Query**：`?refresh=1` 强制在线刷新；否则复用 24h TTL 内的本地快照。数据源 `https://models.dev/api.json`。
- **响应**：`200 {"data":{"source":"cache"|"models.dev", fetchedAt?, stale?, warning?, providers:[{id,name,api?,doc?,env?,npm?,models:[{id,name,attachment,reasoning,toolCall,contextLimit?,outputLimit?}]}]}}`；**既无本地快照又抓不到** → `503 {"error":{"code":"catalog_unavailable","message"}}`；**有快照但刷新失败** → `200` + `stale:true` + `warning`。带 `Accept-Encoding: gzip` 时响应带 `Content-Encoding: gzip`（**信封形状不变**）。
- **副作用只有一处**：落盘快照 `<DATA_DIR>/llm_catalog.json`（**不含任何凭据**、`data/` 已 gitignore、TTL 24h），**不改 `models.json`**。**审计动作**：`llm.catalog`（`ok`/`stale`/`error`）。完整契约与「不进运行时热路径」的边界见 `api-client.md` §2「模型配置契约（v0.53）」。

### 4.10 GET /api/v1/admin/automations
- **响应**：`200 {"data":[<AdminAutomationRecord>...]}`。
- `AdminAutomationRecord`：`{id, name, kind, cron?, enabled, lastRun?, nextRun?}`。`kind` ∈ `cron|event`；`lastRun/nextRun` 为 RFC3339（未知省略）。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/automations -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.11 GET /api/v1/admin/users
- **响应**：`200 {"data":[<AdminUserRecord>...]}`。
- `AdminUserRecord`：`{id, username, role, createdAt?}`（`createdAt` RFC3339）。无 UserStore 时仅有配置的 admin 账号（`id:"admin"`、`role:"owner"`）；注入 UserStore 后追加 API key 摘要（`username:"apikey"`、`id` 为掩码）。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/users -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.12 GET /api/v1/admin/backthink
- **响应**：`200 {"data":[<AdminBackthinkItem>...]}`（无 store 时 `[]`）。`AdminBackthinkItem`：`{id, trigger, conclusion?, shouldNotify, pushed, at}`（`at` 为 Unix 毫秒）。默认取最近 50 条。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/backthink -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.13 GET /api/v1/admin/rag
- **Query**：`?query=<string>`（可选；带则并入检索命中）。
- **响应**：`200 {"data":{"documents":[<AdminRagDoc>...], "hits"?:[<AdminRagHit>...]}}`（`AdminRagResponse`）。
  - `AdminRagDoc`：`{id, name, desc?, chunks, embedded}`（`embedded` 反映是否配置向量增强）。
  - `AdminRagHit`：`{docId, docName, chapter?, text, score, semantic}`（`semantic` 布尔，语义/向量命中为 true）。
- **错误**：`500`。无 store 时返回空文档列表（不 500）。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/rag?query=部署' -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.14 POST /api/v1/admin/rag/query
- **鉴权**：`owner|admin`。
- **Body**：`{"query":"<string>"}`（必填，非空）。
- **响应**：`200 {"data":{"query":"<string>","hits":[<AdminRagHit>...]}}`。**审计**：`rag.query`（成功 `ok` / 失败 `error`）。
- **错误**：`400`（query 缺失/空）；`501`（未注入 RagStore）；`500`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/rag/query \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"query":"部署要求是什么"}'
```

### 4.15 GET /api/v1/admin/observability/audit
- **Query**：`?limit=N`（默认 50，上限 500）。
- **响应**：`200 {"data":[<AuditRecord>...]}`（newest first）。`AuditRecord` = `{id(int64递增), who, what, when(RFC3339), result}`。`who` 形如 `admin:owner`；`what` 为审计动作（如 `system.backup`）；`result` ∈ `ok|error`。
- 来源：SQLite `audit_logs`（`SQLiteAuditStore`）；未注入时退化为进程内存。
- 示例：`{"data":[{"id":1,"who":"admin:owner","what":"system.backup","when":"2026-09-08T00:00:00Z","result":"ok"}]}`。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/observability/audit?limit=100' -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.16 GET /api/v1/admin/observability/metrics
- **Query**：无（不接收 limit）。
- **副作用（v0.55）**：owner/admin 凭据**读取本端点即建立可观测推送订阅**（`observability_metrics` 帧此后由 WS 推来，面板不再轮询；`observability_push.go`）——该凭据的 WS 连接全断即退订。同理见 §4.17 与 `GET /api/v1/admin/observability/logs`（三者的读取都是订阅握手）。响应形状**一字未变**。
- **响应**：`200 {"data":<AdminMetrics>}`。`AdminMetrics` = `{totalRequests, qps, avgLatencyMs, maxLatencyMs, perMethod{}, perPath{}, statusCounts{}, llmCalls, subagentEvents}`。
  - `qps`：近 1 秒窗口计数；`avgLatencyMs/maxLatencyMs`：均值/最大耗时（毫秒）。
  - `perMethod/perPath/statusCounts`：分布计数。
  - `llmCalls/subagentEvents`：由实际观测的 trace span 按 `kind` 累计（Tracer 未注入为 0）。
  - **Token/成本后端不统计、不返回**（不伪造指标）。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/observability/metrics -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.17 GET /api/v1/admin/observability/trace
- **Query**：`?limit=N`（默认 50，上限 500）。
- **副作用（v0.55）**：读取本端点同样建立推送订阅（`observability_trace` 帧随后推来），详见 §4.16。
- **响应**：`200 {"data":[<AdminTraceSpan>...]}`（newest first）。`AdminTraceSpan` = `{id, parentId?, name, kind, status, startedAt, endedAt?, durationNs, props?, events?}`。`kind` ∈ `llm_call|tool_call|orchestration|state_transition|subagent|memory|guardrail`；`events` 为 `[{time,type,props?}]`；时间 RFC3339。
- **旁路节点的 span 现已真实产生**（裁决 11.4.2 / 11.4.3，2026-10-04）：`memory.recall` / `memory.write` / `guardrail.input` / `guardrail.output` / `orchestration.spawn` 均由真实生产者开出，因此 `kind` 取值集里的 `memory|guardrail|orchestration` 不再只是枚举——trace 列表中会真的出现这三类 span（此前三者无生产者，全仓只有 `llm_call`/`tool_call`/`subagent`/`state_transition`）。它们只带元数据（记忆作用域/条数/字节数、护栏裁决与耗时、被派发的子代理 id 与目标角色 id），**不含记忆正文、不含提示词、不含密钥**；见 `design/19 §1`。
- 来源：环形缓冲（默认 512 条），由 `ObserveSpan`/`TraceSink` 注入。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/observability/trace?limit=100' -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 4.18 GET /api/v1/admin/sessions/{id}/export
- **鉴权**：`owner|admin`（注册为 `adminAuth`）。
- **Path**：`{id}` = 会话 id。
- **响应**：`200 {"data":{"session":<SessionSummary>}}`（`summaryOfSession`：`{platform, channelId, sessionId, actorRole, owner, isGroup, memWritable}`）。
- **错误**：`404`（会话未找到）；`500`。
- **备注**：导出会话身份元数据；完整消息转录由 M10 提供。curl：

```bash
curl -s http://<host>:8080/api/v1/admin/sessions/web:0123.../export -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

---

## 5. 管理后台 · 写端点（`owner`，全程审计）

> 以下端点**鉴权 = `Authorize(owner)`**（仅主人）。每个写操作都会调用 `auditClaims(r, "<action>", "ok"|"error")` 记录 who/what/when/result（落 `audit_logs` + 网关日志）。**敏感值（token/密钥/新 JWT 密钥/DB 路径）不在响应/日志回显**。

### 5.1 POST /api/v1/admin/plugins/policy
- **Body**（`policyRequest`）：`{"name":"<能力名>","allowInGroup":bool,"allowInStranger":bool}`。
- **响应**：`200 {"data":{"name":"<能力名>","allowInGroup":bool,"allowInStranger":bool}}`。
- **错误**：`400`（name 缺失）；`500`（cap service 未配置）；`404`（能力不存在）；`500`。
- **审计**：`policy.set`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/plugins/policy \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"name":"web_search","allowInGroup":true,"allowInStranger":false}'
```

### 5.2 POST /api/v1/admin/personas
- **Body**（`personaUpsertRequest`）：`{"id","name","characterRef?","role","systemPrompt?","personality?","speechStyle?","catchphrase?","background?","values?[]","modes?[]"/"mode?","memoryNamespace?"}`。`id/name/role` 必填；`systemPrompt` 空时派生默认；`characterRef` 空时 = id。
- **响应**：`201 {"data":<PersonaSummary>}`。注册进 persona registry（真实运行效果）+ 持久化到 `configs/personas/<id>.yaml`（重启存活）。
- **错误**：`400`（id/name/role 缺失）；`409` `{"error":{"code":"duplicate","message":"人格已存在，请使用编辑"}}`；`500`（registry 未配置 / 持久化失败 / 注册失败）。
- **审计**：`persona.create`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/personas \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"id":"luna","name":"Luna","role":"女仆","modes":["normal"],"memoryNamespace":"luna"}'
# => {"data":{"id":"luna","name":"Luna","character":"Luna","isDefault":false,"mode":"normal","memoryNamespace":"luna"}}
```

### 5.3 PUT /api/v1/admin/personas/{id}
- **Path**：`{id}` = 人格 id。**Body** 同 5.2（不含 id；服务端以 path 覆盖 `req.ID`）。`name`/`role` 必填。
- **响应**：`200 {"data":<PersonaSummary>}`。
- **错误**：`400`（name/role 缺失）；`404`（不存在）；`500`（registry 未配置 / 持久化 / 更新失败）。
- **审计**：`persona.update`。curl：

```bash
curl -s -X PUT http://<host>:8080/api/v1/admin/personas/luna \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"name":"Luna","role":"女仆","modes":["gentle"]}'
```

### 5.4 POST /api/v1/admin/users
- **响应**：`501 {"error":{"code":"not_implemented","message":"新增用户/角色存储为 M10 提供（当前为单 admin + APIKey 现状）"}}`。**审计**：`user.create`（error）。
- **备注**：诚实不伪造（无持久用户表）。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/users \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' -d '{}'
```

### 5.5 POST /api/v1/admin/users/apikey
- **Body**（`apiKeyIssueRequest`）：`{"role":"owner|admin|viewer"}`。
- **响应**：`201 {"data":{"id":"<掩码>","key":"<明文·仅此一次>","role":"<role>"}}`。`key` 为 base64 raw URL 编码的 32 字节随机串，**仅此响应可见一次**；`id` 为掩码（`xxxx....xxxx`），用于后续吊销。
- **错误**：`400`（invalid role/role 缺失）；`500`（user service 未配置 / 生成失败）。
- **审计**：`apikey.issue`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/users/apikey \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"role":"admin"}'
# => {"data":{"id":"abcd****wxyz","key":"LQV...","role":"admin"}}
```

### 5.6 DELETE /api/v1/admin/users/apikey/{id}
- **Path**：`{id}` = 列表返回的掩码 id。
- **响应**：`200 {"data":{"id":"<掩码>","revoked":true}}`。
- **错误**：`404`（掩码未命中）；`500`（user service 未配置）。
- **审计**：`apikey.revoke`。curl：

```bash
curl -s -X DELETE http://<host>:8080/api/v1/admin/users/apikey/abcd****wxyz \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.7 POST /api/v1/admin/iot/{id}/control
- **Path**：`{id}` = 设备 id。**Body**（`iotControlRequest`）：`{"action":"<string>","params":{...}?}`。
- **响应**：`200 {"data":{<iotDeviceSummary>}}`（`{id,name,type,state,online}`）——真实下发到 IoT provider，并发布 `device_update` 事件。
- **错误**：`400`（action 缺失 / 动作不支持 / 参数错）；`404`（设备不存在）；`409`（设备离线）；`500`（IoT 服务未配置 / 控制失败）。
- **审计**：`iot.control`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/iot/d1/control \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"action":"toggle","params":{"brightness":50}}'
```

### 5.8 POST /api/v1/admin/iot/scenarios
- **响应**：`501 {"error":{"code":"not_implemented","message":"IoT 场景未实现：IoT 子系统仅有设备列表/控制/状态（Provider 接口无场景模型与存储）；场景 CRUD 需先新增模型 + 执行器"}}`。**审计**：`iot.scenario`（error）。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/iot/scenarios -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'
```

### 5.9 POST /api/v1/admin/iot/rules
- **响应**：`501 {"error":{"code":"not_implemented","message":"IoT 自动化规则未实现：IoT 子系统无规则模型与存储（通用 automations 服务只跑 cron/事件规则，不含设备状态条件 + 设备动作执行器）"}}`（同 5.8，审计 `iot.rule`）。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/iot/rules -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'
```

### 5.10 POST /api/v1/admin/automations
- **Body**（`automationCreateRequest`）：`{"name","kind":"cron|event","expression"}`（均必填）。
- **响应**：`201 {"data":{"id":"<id>","name":"<name>","kind":"<kind>"}}`——真实注册规则。
- **错误**：`400`（字段缺失 / `invalid_cron` / `invalid_rule`）；`500`（自动化服务未配置 / 添加失败）。
- **审计**：`automation.create`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/automations \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"name":"晨间问候","kind":"cron","expression":"0 8 * * *"}'
```

### 5.11 POST /api/v1/admin/automations/{id}/run
- **Path**：`{id}`。**Body**：无。
- **响应**：`200 {"data":{"id":"<id>","output":"<string>"}}`（手动触发一次）。
- **错误**：`404`；`500`。
- **审计**：`automation.run`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/automations/<id>/run -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.12 DELETE /api/v1/admin/automations/{id}
- **Path**：`{id}`。**响应**：`200 {"data":{"id":"<id>","deleted":true}}`。
- **错误**：`404`；`500`。**审计**：`automation.delete`。curl：

```bash
curl -s -X DELETE http://<host>:8080/api/v1/admin/automations/<id> -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.13 POST /api/v1/admin/llm
- **Body**（`llmProviderRequest`）：`{"id?","name?","provider?","baseUrl","apiKey?","model","multimodal?","fallback?","maxTokens?","reasoning?","personaModels?","personaProviders?"}`。`baseUrl`+`model` 必填；`provider` 空默认 `openai`（仅允许 `openai|anthropic`）；`maxTokens` 缺省/`0` = 未设，负数回 `400`。**v0.53 三键**缺省 = 保留已存值（`reasoning` 整块给出即整块替换；两张 persona 表给出即整表替换）；非法 `reasoning.kind`、非法协议名、anthropic 组声明 openai 系形状 → `400 bad_request`（`Group.Validate` 报错，不落盘）。契约见 api-client「模型配置契约（v0.53）」。
- **响应**：`201 {"data":{"provider":<AdminLlmProvider>,"persisted":true,"path":"<models.json 绝对路径>"}}`。**真实持久化**：读-改-写 `models.json`，保存组**提升为生效组**（index 0），并**热重载**运行中的 LLM stack（无需重启）。
- **错误**：`400`（缺 baseUrl/model / invalid provider）；`500`（LLM 服务未注入 / 写盘失败 / 热重载失败）。**API key 写入文件但永不回显、不落日志**。
- **审计**：`llm.addProvider`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/llm \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"provider":"openai","baseUrl":"https://api.openai.com/v1","apiKey":"sk-...","model":"gpt-4o","multimodal":true}'
```

### 5.14 POST /api/v1/admin/llm/test
- **Body**（`llmTestRequest`）：`{"provider?","baseUrl","model","apiKey?","prompt?"}`。`model`+`baseUrl` 必填；`provider` 空默认 `openai`；`prompt` 空用探针 `"Reply with the single word: OK"`。
- **响应**：`200 {"data":{"ok":true,"provider":"openai","model":"gpt-4o","reply":"<模型回复>","tokens":<int>}}`——**真实模型调用**（超时 30s）。
- **错误**：`400`（缺 model/baseUrl / invalid provider）；`500`（调用失败）。
- **审计**：`llm.test`。**API key 仅本次请求内使用，不落库、不进 wire**。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/llm/test \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"provider":"openai","baseUrl":"https://api.openai.com/v1","model":"gpt-4o","apiKey":"sk-...","prompt":"你好"}'
```

### 5.15 POST /api/v1/admin/channels/open
- **Body**（`channelActionRequest`）：`{"name":"<渠道名>"}`（如 `"kook"` / `"kook:conf0"` / 裸平台名解析到该平台首个账号）。
- **响应**：`200 {"data":{"name":"<name>","connected":true}}`——真实 Connect。
- **错误**：`400`（name 缺失）；`404`（渠道未注册）；`409` `{"error":{"code":"needs_login","message":"该渠道尚未登录：请先用「扫码登录」绑定，再连接"}}`（weixin-iLink 无 token）；`500`（连接失败）。
- **审计**：`channel.open`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/channels/open \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"name":"kook"}'
```

### 5.16 POST /api/v1/admin/channels/close
- **Body**：`{"name":"<渠道名>"}`。**响应**：`200 {"data":{"name":"<name>","connected":false}}`——真实 Disconnect。
- **错误**：`400` / `404` / `500`。**审计**：`channel.close`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/channels/close \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' -d '{"name":"kook"}'
```

### 5.17 POST /api/v1/admin/channels/test
- **Body**（`channelTestRequest`）：`{"platform?","accountId","isGroup"}`（`accountId` 必填）。
- **响应**：`200 {"data":{"role":"owner|member|...","owner":bool,"isGroup":bool,"env":"owner|...|","verdict":"<人读结论>"}}`。**结构性身份识别**：channel 层 actor 元数据 × `configs/users/owner.yaml` 白名单，**绝不靠提示词**。`verdict` 说明：群聊→隔离+记忆只读+仅允许工具；命中白名单→owner（全量访问）；未命中→按陌生人（default deny）。
- **错误**：`400`（accountId 缺失）。**审计**：`channel.identity-test`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/channels/test \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"platform":"weixin-ilink","accountId":"wx_uid_123","isGroup":false}'
# => {"data":{"role":"owner","owner":true,"isGroup":false,"env":"owner","verdict":"匹配主人白名单 → owner（全量访问，记忆可读写）"}}
```

### 5.18 GET /api/v1/admin/channels/{platform}/login-qr
- **鉴权**：`owner`。**Path**：`{platform}` = `weixin-ilink`（其它平台 501）。**Query**：`?accountId=`（可选）。
- **响应**：`200 {"data":{"qrUrl?","qrCode?","status":"confirmed|<状态>"}}`。`qrUrl` 为微信二维码图 URL（前端据此渲染可扫 QR），`qrCode` 为原始扫码标识；已登录时 `status:"confirmed"`。
- **错误**：`501`（非 weixin-ilink）；`404`（账号未找到，提示先保存账号）；`500`（取码失败）。
- **审计**：`channel.weixin.login.qr`。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/weixin-ilink/login-qr?accountId=conf0' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.19 GET /api/v1/admin/channels/{platform}/login-status
- **鉴权**：`owner`。**Path**：`{platform}` = `weixin-ilink`。**Query**：`?accountId=`（可选）。
- **响应**：`200 {"data":{"status":"confirmed|failed|...","botId?","botToken?","err?"}}`。`botToken` 为**掩码（`****`+尾4）**；`status==confirmed` 时后端已把刚取到的 `bot_token/bot_id/owner_id` **写入 channels.json** 并**热加载**该平台（bridge 连上已配置的 adapter，无需重启），且（owner_id 存在时）把扫码者绑定 id 登记进 owner 白名单（`owner.yaml`，热生效）。`status==failed` 时 `err` 带原因。
- **错误**：`501` / `404` / `500`。
- **审计**：`channel.weixin.login.status`（+ `channel.weixin.login.persist`（确认时））。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/weixin-ilink/login-status?accountId=conf0' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
# 确认后 => {"data":{"status":"confirmed","botId":"wxid_xx","botToken":"****abcd"}}
```

### 5.20 GET /api/v1/admin/channels/{platform}/view
- **鉴权**：`owner`。**Path**：`{platform}` = `kook`（其它 501）。**Query**：`?accountId=`（可选）。
- **响应**：`200 {"data":{"platform":"kook","accountId?","friends?","userChats?","guilds?","channels?","members?","errors?"}}`。聚合该账号真实数据（好友/申请/屏蔽、私信会话、服务器 + 首个服务器频道与成员）。`errors` 为 `{子项:原因}` 记录失败子项（不伪造）。token/密钥不打印不落日志。
- **错误**：`501`（非 kook）；`404`（账号未找到）；`500`。
- **审计**：`channel.platform.view`。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/kook/view?accountId=3bef...' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.21 GET /api/v1/admin/channels/{platform}/friends
- **鉴权**：`owner`。**Path**：`kook`。**Query**：`?type=friend|request|block&accountId=`（`type` 空=全部）。
- **响应**：`200 {"data":<KOOK FriendList>}`（含 friends/requests/blocked）。
- **错误**：`501` / `404` / `500`。**审计**：`channel.friends`。curl：

```bash
curl -s 'http://<host>:8080/api/v1/admin/channels/kook/friends?type=request&accountId=3bef...' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.22 POST /api/v1/admin/channels/{platform}/friend/handle
- **鉴权**：`owner`。**Path**：`kook`。**Query**：`?accountId=`。**Body**（`kookFriendHandleRequest`）：`{"id":<int64>,"accept":bool}`（id 必填）。
- **响应**：`200 {"data":{"handled":true,"id":<int64>,"accept":bool}}`。
- **错误**：`400`（id 缺失）；`501` / `404` / `500`。**审计**：`channel.friend.handle`。curl：

```bash
curl -s -X POST 'http://<host>:8080/api/v1/admin/channels/kook/friend/handle?accountId=3bef...' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"id":12345,"accept":true}'
```

### 5.23 POST /api/v1/admin/channels/{platform}/message/test
- **鉴权**：`owner`。**Path**：`kook`。**Query**：`?accountId=`。**Body**（`kookMessageTestRequest`）：`{"targetId":"<频道id>","content":"<文本>"}`（均必填）。
- **响应**：`200 {"data":{<KOOK TestMessageResult>}}`（如 `{msg_id,msg_timestamp}`）——真实向目标发一条 kmarkdown 测试消息。
- **错误**：`400`（字段缺失）；`501` / `404` / `500`。**审计**：`channel.message.test`。curl：

```bash
curl -s -X POST 'http://<host>:8080/api/v1/admin/channels/kook/message/test?accountId=3bef...' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"targetId":"123456","content":"ping"}'
```

### 5.24 PUT /api/v1/admin/channels/{platform}/config
- **鉴权**：`owner`。**Path**：`{platform}`。**Body**（`channelConfigRequest`）：
  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `id` | string | 账号 id（可选；空则由服务端生成） |
  | `token` | string | 快捷 token，并入 `config["bot_token"]`（若 config 未显式给） |
  | `baseURL` | string | → `config["base_url"]` |
  | `remoteURL` | string | → `config["remote_url"]` |
  | `listenAddr` | string | → `config["listen_addr"]` |
  | `mode` | string | → `config["mode"]` |
  | `accessToken` | string | → `config["access_token"]` |
  | `selfID` | string | → `config["self_id"]` |
  | `config` | object | 平台专属键值（如 `bot_token`/`base_url`/`remote_url`/`endpointPath`/`receive_mode`/`webhook_verify_token`/`transport`/`api_base_url`/`report_path`...） |
  | `allowGroups`/`denyGroups` | string[] | 黑白名单（群） |
  | `allowUsers`/`denyUsers` | string[] | 黑白名单（用户） |
  | `groupMsgPerMin` | int | 群消息限流 |
  | `msgPerMin` | int | 用户消息限流 |
  | `maxMessages` | int | 单账号最大消息数 |
  > 空配置时：`weixin-ilink` 豁免（先建账号再扫码），其它平台 `400`。
  > **`config` 是补丁（v0.54，与 `personaId` 同构）**：只含本次请求显式给出的键——键省略（`config` 里没有该键 / `config` 整体缺席或 `null`）= **保留已存值**、给非空值 = 覆盖、显式 `null`/`""` = **清除**（`0`/`false` 不算空）；顶层便捷字段（`token`/`baseURL`/…）是普通 string，只在**非空**时并入 ⇒ 清除 `bot_token` 须走 `config` 的显式 `null`/`""`。`allowGroups`/`denyGroups`/`allowUsers`/`denyUsers` 与三个限流键仍是**整值替换**（省略 = 清空）。
  > **`qq-obv11` 的 `config` 新增三键（v0.55，OneBot v11 四端，裁决 1.4 / 12.4.1）**：`transport`（`ws`|`http`，默认 `ws`，未知值回落 `ws`）、`api_base_url`（OneBot HTTP API 基址，**必须显式给出、不从 `remote_url` 推导**）、`report_path`（http+server 收上报的路径，默认 `/`）。`mode` 决定哪一半必需：`server` 必需 `listen_addr`（**独立监听端口，`AGENTS.md` §9 登记的唯一豁免，为空则 `Connect` 报错、绝不开端口**）、`client` 必需 `api_base_url`；另一半给齐字段就一并启用（单个适配器即可「收上报 + 回消息」）。env 兜底 `CHANNEL_QQ_OBV11_{TRANSPORT,API_BASE_URL,REPORT_PATH}`。四端完整语义见 `api-client.md` §2 的「OneBot v11 四端契约（v0.55）」。
- **响应**：`201 {"data":{"persisted":true,"path":"<channels.json 路径>","platform":"<platform>","accountId":"<accountId>"}}`。**真实持久化 + 热更新**（读 channels.json→**按 id 打补丁**（`PatchChannel`）→落盘→`Reload(platform)` 热替换 adapter，无需重启；**v0.54 起 `config` 为 patch 三态**（与 `personaId` 同构）：键省略=保留该账号已存值 / 给出非空值=覆盖该键 / 显式 `null`或`""`=清除该键，详见 `api-client.md` §2）。token 写入文件但**不回显**（GET 列表掩码）。
- **错误**：`400`（platform 缺失 / 空配置）；`500`（渠道配置服务未注入 / 写盘失败 / 热重载失败）。
- **审计**：`channel.save`。curl：

```bash
curl -s -X PUT http://<host>:8080/api/v1/admin/channels/kook/config \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"id":"conf0","token":"<bot_token>","allowUsers":["user_i_like"],"groupMsgPerMin":20}'
```

### 5.25 DELETE /api/v1/admin/channels/{platform}/config
- **鉴权**：`owner`。**Path**：`{platform}`。**Query**：`?id=<accountId>`（必填）。
- **响应**：`200 {"data":{"persisted":true,"path":"<channels.json>","platform":"","accountId":"<id>"}}`。删除账号 → 落盘 → `Reload(platform)` 热更新（对应 adapter 优雅关停）。
- **错误**：`400`（platform/id 缺失）；`500`（未注入 / 写盘 / 重载失败）。
- **审计**：`channel.delete`。curl：

```bash
curl -s -X DELETE 'http://<host>:8080/api/v1/admin/channels/kook/config?id=conf0' \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
```

### 5.26 POST /api/v1/admin/plugins/install
- **Body**（`pluginInstallRequest`）：`{"kind":"mcp","name":"<名>","config":{"transport":"stdio|http|sse","endpoint"?|"command"?, "args"?, "apiKey"?, "env"?}}`。`name` 必填；`kind` 缺省 `"mcp"`，**仅 `mcp` 可装**（其它回 `400`）。`endpoint` 的别名是 `url`。
- **响应**：`200 {"data":{"installed":true,"name":"<名>","kind":"mcp","transport":"<t>","toolCount":<n>}}`——**真实安装**：connect + 发现工具 + 热注册进 capability registry（下一轮模型请求即注入，无需重启）→ 落盘 `plugins.json`（gitignore、0600）→ 持有 live server 供后续刷新/卸载。**同名重复安装 = 刷新**（先卸旧再装新，失败回滚旧）。
- **错误**：`400`（缺 `name` / `kind` 非 `mcp` / transport 非法 / `stdio` 缺 `command` / `http|sse` 缺 `endpoint`）；**`502 plugin_install_failed`**（连接/发现/注册失败，且**不落盘**，绝不装一半）；`501 not_implemented`（未注入 plugin manager）。
- **审计**：`plugin.install`。**契约见 api-client §2 的 `POST /admin/plugins/install` 条（本节为索引，不重复维护契约）**。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/plugins/install \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"mcp","name":"fs","config":{"transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}}'
```

### 5.27 POST /api/v1/admin/plugins/uninstall
- **Body**（`pluginActionRequest`）：`{"name":"<能力名>"}`（必填）。
- **响应**：已装 MCP → `200 {"data":{"name":"<name>","uninstalled":true,"kind":"mcp"}}`（`Unregister` 移除其工具 + close + 删 `plugins.json` 条目）；**非 MCP / 普通能力** → `200 {"data":{"name":"<name>","uninstalled":true}}`（走 `registry.Remove`）。
- **错误**：`400`（name 缺失）；`404`（不存在）；`500`。
- **审计**：`plugin.uninstall`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/plugins/uninstall \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' -d '{"name":"web_search"}'
```

### 5.28 POST /api/v1/admin/memories
- **Body**（`memoryAddRequest`）：`{"personaId?","content","scope?"}`。`content` 必填；`personaId` 缺省 `"cyrene"`；`scope` ∈ `user|persona|project`（缺省 `persona`；无效非空回 400）。
- **响应**：`201 {"data":{"id":"<id>","scope":"<scope>","text":"<内容>"}}`——真实写入 memory store。
- **错误**：`400`（content 缺失 / scope 非法）；`501`（memory store 未配置 / 未注入 `memory.Store`）；`500`。
- **审计**：`memory.add`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/memories \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"personaId":"cyrene","content":"主人喜欢喝美式咖啡","scope":"user"}'
```

### 5.29 POST /api/v1/admin/memories/search
- **Body**（`memorySearchRequest`）：`{"query","personaId?","topK?"}`。`query` 必填；`personaId` **省略时回落到库里注册的默认角色**（`defaultPersonaID()`，不再写死 `"cyrene"`），**既未传又无默认角色 → `400 bad_request`**（诚实报错，不拿不可能命中的 id 去查）；`topK` ≤0 取 10。
- **响应**：`200 {"data":{"query":"<query>","personaId":"<personaId>","semantic":false,"hits":[{"id","scope","text","score"}]}}`。真实检索（keyword × 衰减）。**`semantic` 当前仍恒为 `false`，但原因已变**：向量索引**已由组合根注入**（`cmd/cyrene/wire.go` 的 `memory.WithVectorIndex`），真实原因是**索引内当前无向量**（生产路径无向索引写入向量，仅测试有 `Index.Add`），故语义打分返回空；这是诚实反映，不是伪造。
- **错误**：`400`（query 缺失）；`500`（memory store 未配置 / 检索失败）。
- **审计**：`memory.search`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/memories/search \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"query":"咖啡","personaId":"cyrene","topK":5}'
```

### 5.30 POST /api/v1/admin/rag
- **Body**（`ragIndexRequest`）：`{"name","desc?","content"}`。`name`+`content` 必填。
- **响应**：`201 {"data":{"name":"<name>"}}`——真实导入：分块并落项目索引，立即可被关键词/行上下文检索。
- **错误**：`400`（name/content 缺失）；`501`（未注入 RagStore）；`500`。
- **审计**：`rag.index`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/rag \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"name":"部署说明","desc":"v2 部署要求","content":"单二进制...\n单端口 8080..."}'
```

### 5.31 POST /api/v1/admin/system/revoke-keys
- **Body**：无。
- **响应**：`200 {"data":{"revoked":<int>}}`——清空 API key 表，先前签发的所有 key 立即失效。
- **错误**：`500`（user service 未配置，`users_unavailable`）。
- **审计**：`system.revoke_keys`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/system/revoke-keys \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1' -d '{}'
```

### 5.32 POST /api/v1/admin/system/rotate-jwt
- **Body**（`rotateJWTRequest`）：`{"newSecret":"<≥32 位>"}`（必填）。
- **响应**：`200 {"data":{"rotated":true,"refreshTokensRevoked":<int>,"note":"现有 token 与 refresh token 已全部失效，需重新登录"}}`（`refreshTokensRevoked` = 一并删除的 refresh token 行数）。
- **错误**：`400`（newSecret 缺失 / 长度 <32，`"新密钥长度不足 32 位"`）；`500`（认证服务未配置 / 轮换失败）。
- **审计**：`system.rotate_jwt`。**新密钥永不回显、不落日志**。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/system/rotate-jwt \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"newSecret":"a-32-char-long-random-secret-12345678"}'
```

### 5.33 POST /api/v1/admin/system/backup
- **Body**：无。
- **响应**：`200 {"data":{"path":"<dataDir>/backup-<ts>.db","size":<字节数>}}`。经 SQLite `VACUUM INTO`（含已提交 WAL）快照到数据目录。
- **错误**：`500`（DB 路径未配置 `backup_unavailable` / 备份失败）。
- **审计**：`system.backup`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/system/backup \
  -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1' -d '{}'
```

### 5.34 POST /api/v1/admin/system/restore
- **Body**（`restoreRequest`）：`{"path":"<dataDir 内的备份文件>"}`（必填）。
- **响应**：`200 {"data":{"restored":true,"backup":"<恢复前自动快照路径>","note":"已安排恢复，需重启服务后生效"}}`。**流程**：校验 path 在 dataDir 内（`filepath.Rel` 防路径穿越，`..` 逃逸回 400）→ 文件存在校验 → **先自动备份当前 DB** → 复制替换 DB 文件 → 返回（替换后需重启服务生效，因运行进程持有 DB 句柄）。
- **错误**：`400`（path 缺失 / 逃逸数据目录）；`404`（备份文件不存在）；`500`（DB 路径未配置 / 恢复前备份失败 / 替换失败）。
- **审计**：`system.restore`。curl：

```bash
curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
  -d '{"path":"/abs/path/data/backup-20260908T000000.000000000Z.db"}'
```

---

## 6. WebSocket 实时协议（`GET /ws/chat`）

> 唯一实时通道。**单二进制、单端口**：同一 `:8080` 上，REST/WS/admin 共用。生产者（loop/IoT/task/automation/reminder/subagent）经进程内 `bus` 发布，hub 订阅 `ws.>` 及桥接模式并规范化成 WS 帧广播给客户端。**上行与下行都有角色门（fail-closed）**：① **上行帧**——只有 `owner`/`admin` 能发，非 owner/admin 连接发来的**任何**上行 JSON 帧被定向拒为 `{type:"error",data:{code:"forbidden"}}`（`ws_route.go` 的 `route` 首条语句，默认拒，不广播/不驱动模型/不落库）；② **握手 `history` 回放**——**仅 `owner`/`admin`**（`ws_history.go` 的 `replayHistory` 首行）；③ **下行帧**——只有 7 个不含内容的状态机信号（含 `session_read`）发给所有已认证连接，其余全部（含 `proactive_message`）**仅 `owner`/`admin`**（`ws_frame_scope.go`）。**权威口径与帧清单见 `Docs/api-client.md` §3 顶部的两把角色门**；本节其余部分只描述帧形状，鉴权以 api-client 为准。

### 6.1 握手与连接

- **URL**：`ws://<host>:8080/ws/chat?token=<JWT>`（或 `Authorization: Bearer <JWT>` 头）。
- **方法**：必须 `GET`（否则握手前回 `400 {"error":{"code":"bad_request","message":"websocket requires GET"}}`）。
- **鉴权**：`s.auth.Verify(wsToken(r))`。`wsToken` 先取 `?token=`，再取 `Authorization: Bearer`。失败 → **握手前**回 `401 {"error":{"code":"unauthorized",...}}`（浏览器/IM 客户端收到干净拒绝）。**连接层不校验角色**（任意有效 JWT——含 `viewer`——都可连）。**但连接之后的帧按角色分档**：上行仅 `owner`/`admin` 可发、`history` 回放仅 `owner`/`admin` 可收、下行除 7 个状态机信号外仅 `owner`/`admin`（见本节开头与 api-client §3 顶部两把角色门）。
- **Origin 校验**：`CheckOrigin` 允许「同一 origin」+「同一 host」+ 白名单；`*` 全放行。同 host 放宽：production 内嵌前端页面 origin 即网关 Host，故 `PORT` 改变无需改 `.env`。**跨源客户端**（外部 IM / 另一 origin）需在 `ALLOWED_ORIGINS` 白名单。
- **升级后流程**：注册连接 → `replayHistory(c, "web")`（首帧推 `history` 回放）→ 启动 `writePump`（唯一写者，含 ping/pong）与 `readPump`（读客户端帧）。
- **心跳/限帧**：读上限 4096 字节/帧；写超时 10s；pong 等待 60s；ping 周期 54s。发送缓冲 32（慢客户端满则丢帧，生产者不阻塞）。
- **`history` 回放（首帧）**：`{type:"history", sessionId:"web", data:{messages:[historyMessage...]}}`——主会话最近 50 条（`wsReplayLimit=50`），**`thinking` 已剥离**；**仅 `owner`/`admin` 连接收到**（`replayHistory` 首行角色门，design/11 §7.2 A；`viewer` 连接建立后不收回放）。回放仅在 `history != nil` 时发生，失败静默跳过。

### 6.2 帧壳（Frame Shell）

- **下行（服务端→客户端）** `wsEvent`：
  | 字段 | 类型 | 必填 | 说明 |
  |------|------|:---:|------|
  | `type` | string | 是 | 事件类型（见 §6.3 表） |
  | `turnId` | string | 否 | 一轮交换的关联 id（流式；`turn-<hex>`）；OnStream 结构化流路径**不带** |
  | `seq` | int | 否 | hub 级单调递增序号，供客户端排序关联流式突发 |
  | `sessionId` | string | 否 | 能确定会话的事件带上，客户端按它把帧路由到该会话的消息桶（v0.54 起非激活会话的帧不再丢弃；只有单槽忙态仍按激活会话判定，见 `api-client.md` §3.1/§3.2/§3.3）；可观测推送三帧（`observability_log`/`observability_trace`/`observability_metrics`，v0.55）**不带**该字段，帧壳只有 `{type,data}` |
  | `data` | any | 否 | 类型化负载（每个事件见 §6.3） |

- **上行（客户端→服务端）** `wsInbound`：
  | 字段 | 类型 | 必填 | 说明 |
  |------|------|:---:|------|
  | `type` | string | 是 | 事件类型（见 §6.3 上行表） |
  | `reqId` | string | 否 | 请求关联 id（当前服务端**不**回填，预留） |
  | `data` | object | 否 | 每类型负载（raw JSON） |

### 6.3 上行事件（客户端 → 服务端）

> 由 `wsConn.route(in)` 按 `in.Type` 分派。未知类型回 `{type:"error", data:{message:"unknown event type"}}`。**角色门（design/11 §7.2，fail-closed）**：`route` 的**第一条语句**就是角色检查——非 `owner`/`admin` 连接发来的**任何**上行帧一律**定向**回 `{type:"error",data:{code:"forbidden"}}`，不广播、不驱动模型、不落库；因此下表**只对 owner/admin 连接生效**（`viewer` 连上也发不出任何一条）。权威帧清单与版本记录见 api-client §3。

| type | 数据负载 | 服务端行为 | 结果 |
|------|----------|-----------|------|
| `mode_switch` | 任意（如 `{"mode":"chat"}`） | 发布 `ws.mode_switch` → hub 规范化广播 | 下行 `mode_switch`（广播） |
| `chat` | `{sessionId?, text, image?, deviceId?, mode?}` | **直达会话编排器的非阻塞 `Submit`（v0.55 起：上行 chat 不再经可丢弃的 bus——会话消息不得被 drop；编排器未注入时回退发布 `ws.chat`）** → `streamChat`（跑 loop 并流式） | 下行 `stream_chunk`/`stream_end` 或 `message.*/thinking.*/tool_call.*`（广播） |
| `interrupt` | `{sessionId}` | 会话编排器中断：取消在跑 turn + 清空 pending | 下行 `session_interrupted` |
| `voice_input` | `{audio?, format?, text?, sessionId?}` | STT→chat→TTS（缺省 sessionId=`web`） | 下行 `voice_output`（**定向回请求连接**） |
| `subagent_ask` | `{id, mode?(""/full/tail/keyword), n, query?}` | 审计子代理上下文（缺省 `mode`=full） | 下行 `subagent_event`（或 `error`） |
| `task_output_query` | `{taskId}` | 查询后台任务输出 | 下行 `task_output`（或 `error`） |

**上行各负载字段**

- **`chat`**（`chatStreamRequest`）：`{sessionId`(缺省`"web"`), `text`, `image?`(base64 data: URI 或 URL), `deviceId?`, `mode?`(行为模式，缺省回落 `chat`)}。text+image 至少一项；`runner` 未注入或两者皆空 → 直接广播 `stream_end{stopReason:"idle"}`。主会话 `web` 绑定全量 env（`loop.OwnerEnv()`）。`chat` 进入时若该会话正忙 → 由编排器入队（见 §6.4），非阻塞。**仅 owner/admin 连接可发**（见本节角色门）。
- **`interrupt`**：`{sessionId}`。命中空闲会话为 no-op。
- **`voice_input`**：`{audio`(base64 或 data: URI), `format`(`wav|mp3|ogg|webm|mpeg`，空由 mime 猜，默认 `wav`), `text`(已转写则跳过 STT), `sessionId?`}。无 `voice` 服务 → `{type:"error",data:{message:"voice unavailable"}}`。
- **`subagent_ask`**：`{id`(必填), `mode`(空/full/tail/keyword), `n`(tail 查询窗长), `query`(keyword 查询词)}。无 auditor → `error`；id 缺失 → `error`。
- **`task_output_query`**：`{taskId}`。无 task store → `error`；运行中任务返回截至目前输出；输出拼接 `stdout + "\n" + stderr`。

### 6.4 下行事件全表

> **角色门（design/11 §7.1，fail-closed）**：下行帧按类型分档，收口在 `internal/services/gateway/ws_frame_scope.go` 的 `frameReachesAll`（**唯一一处判定**，各调用点不自行决定可见性）。**只有 7 个不含内容的状态机信号**发给**所有已认证连接**（含 `viewer`）：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full` / **`session_read`**。**其余全部只发 `owner`+`admin`**：流式内容（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` / `stream_chunk` / `stream_end`）、持久化（`message_persisted` / `message_edited` / `message_deleted` / `channel_persisted`）、系统内部（`graph_update` / `subagent_event` / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`）、私有状态（`mood` / `device_update` / `reminder` / `proactive_message`）、**可观测推送（`observability_log` / `observability_trace` / `observability_metrics`，v0.55）**；**未登记的新帧类型默认只发 owner/admin**。**本表并非全表**：`session_read` / `message_edited` / `message_deleted` 等已实现事件尚未逐行登记于此；**权威清单与逐帧口径见 `Docs/api-client.md` §3**。
>
> **来源标记**：`[direct]` 网关直接 emit；`[relay]` hub 从 bus `ws.>` 规范化（任意 `ws.X` 主题 → 类型 `X`）；`[bridge]` 桥接 producer 主题；`[target]` 仅定向特定连接。

| type | 来源 | 数据（`data`） | 用途 |
|------|------|----------------|------|
| `history` | direct | `{messages:[historyMessage]} ` | 连接首帧回放主会话最近 50 条（thinking 剥离）；**仅 owner/admin 连接收到**（`viewer` 不收） |
| `message.start` | direct | `{index}` | 正文段开始 |
| `message.delta` | direct | `{delta,index}` | 正文 token 增量（累加到当前正文） |
| `message.end` | direct | `{index}` | 正文段结束（不结束整轮，由 `stream_end` 收尾） |
| `thinking.start` | direct | `{index}` | 思维链段开始（前端折叠块） |
| `thinking.delta` | direct | `{delta,index}` | 思维链 token 增量 |
| `thinking.end` | direct | `{index}` | 思维链段结束 |
| `tool_call.start` | direct | `{id,index}` | 工具调用中间态开始 |
| `tool_call.delta` | direct | `{id,index,delta}` | 工具调用参数增量（如 `input_json_delta`） |
| `tool_call.end` | direct | `{id,index}` | 工具调用中间态结束 |
| `tool_execution.update` | direct | `{id,index,delta}` | 工具执行进度/局部输出 |
| `stream_chunk` | direct | `{delta}` | **向后兼容整段文本**（仅非流式回退路径；流式路径不 emit） |
| `stream_end` | direct | `{stopReason, steps?}` / `{stopReason:"idle"}` / `{stopReason:"error", error}` | 一轮结束 |
| `session_busy` | direct(编排) | `{sessionId, mode}` | 会话进入忙碌态（mode∈idle/thinking/executing/subagent） |
| `pending_ack` | direct(编排) | `{sessionId, mode, queueDepth}` | 忙时新消息已入队「收到，稍后回」 |
| `pending_drain` | direct(编排) | `{sessionId, mode, queueDepth}` | 忙完开始消费下一待处理消息 |
| `session_idle` | direct(编排) | `{sessionId, mode}` | 会话回到空闲、队列清空 |
| `session_interrupted` | direct(编排) | `{sessionId, mode, dropped}` | 用户 interrupt，当前任务取消、pending 清空 |
| `pending_full` | direct(编排) | `{sessionId, mode, max}` | 单会话 pending 达上限（默认 5）拒绝入队 |
| `message_persisted` | direct | `{message:historyMessage}`（sessionId 设） | 每条 user/assistant 消息落库后广播（主会话 `web`/`web:<uuid>`），thinking 剥离 |
| `channel_persisted` | direct | `{message:historyMessage}`（sessionId=`sess-xxx`） | 群聊/陌生人（非主人）消息落库后广播，供 IM 适配器日志页 |
| `voice_output` | direct/target | `{audio, format, text, reply}` | 语音合成回复（定向回请求连接） |
| `subagent_event` | direct+relay | 审计结果 或 `{id,name,status,role,mode}` | 子代理上下文查询应答 / 子代理进度 |
| `task_output` | direct+bridge | `{taskId, output, status}` | 后台任务输出查询应答 / task.output 桥接 |
| `capacity_awaken` | direct | `{fromState, toState, tool?}` | 能力状态迁移（design/14 §5，`sessionId` 设） |
| `proactive_message` | direct | `{platform?, channelId?, channelType?, content, contentType?, sender?, timestamp?, messageId?}` | 自主主动推送（仅 owner/admin 连接收到） |
| `device_update` | bridge | producer payload | IoT 设备状态更新（`iot.device_update`） |
| `task_done` | bridge | producer payload | 后台任务完成（`task.done`） |
| `automation_result` | bridge | producer payload | 自动化规则结果（`automation.result`） |
| `reminder` | bridge | producer payload | 提醒触发（`reminder.trigger`） |
| `mode_switch` | direct | 上行原样（任意） | 行为模式切换回显（`ws.mode_switch`） |
| `mood`/`tool_used`/`graph_update`/… | relay | `ws.X` 主题负载（`ws.mood`→`mood`,`ws.tool_used`→`tool_used`,`ws.graph_update`→`graph_update`,…） | 生产者在 bus 上发 `ws.X` 即规范化成类型 `X` 广播 |
| `observability_log` | bridge | `{entries:[{time,level,source,msg}…]}`（最新在前） | **可观测推送（v0.55）**：订阅后新增日志，≤1s 一拍最多一帧、无新条目不发；单帧上限 200 条；**不带 `sessionId`** |
| `observability_trace` | bridge | `{spans:[AdminTraceSpan…]}`（最新在前） | **可观测推送（v0.55）**：订阅后新完成的 span；单帧上限 100 条；**不带 `sessionId`** |
| `observability_metrics` | bridge | `<AdminMetrics>`（扁平，与 REST 同形） | **可观测推送（v0.55）**：与上次发出的不同才发；**不带 `sessionId`** |
| `error` | direct | `{message}` | 非法 JSON / 未知类型 / 语音·子代理·任务错误等 |

> **`auth`**（旧 design/07 列表）：当前**不**由网关直接 emit；若未来有 `ws.auth` 生产者主题，则按 `[relay]` 规则广播。本文档以代码为准。

**`message_persisted` / `channel_persisted` / `history` 的 `historyMessage` 全字段**（含 `thinking` 剥离规则）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 后端生成消息 id（客户端去重键） |
| `sessionId` | string | 会话 id |
| `role` | string | `user` / `assistant` |
| `content` | string | 正文 |
| `mode` | string | `omitempty` |
| `mood` | string | `omitempty` |
| `image` | string | `omitempty` |
| `thinking` | string | **`omitempty`，但在这些实时帧中恒为空**（`BroadcastPersisted`/`replayHistory` 均置空；`/messages` owner/admin 端点才带） |
| `platform` | string | `omitempty`（`web`/`telegram`/`weixin-ilink`/`qq-obv11`...） |
| `deviceId` | string | `omitempty` |
| `senderName` | string | `omitempty`（第三方昵称，主人私聊为空） |
| `adapterId` | string | `omitempty`（仅 `channel_persisted` 常见，如 `kook:3bef...`） |
| `createdAt` | int64 | Unix 毫秒 |

**事件类型分流**（`BroadcastPersisted`）：`sessionId == "web"` 或以 `web:` 前缀 → **`message_persisted`**（Web 聊天实时同步）；其它（隔离 `sess-xxx`）→ **`channel_persisted`**（IM 适配器日志专用）。Web 聊天无 `channel_persisted` handler，天然忽略。

### 6.5 会话编排状态（design/15，`data.sessionId` 区分）

- **语义**：同一会话 `chat` 到达时若「她忙」（跑 loop/工具/子代理/长回复）→ 新消息**不阻塞**、入该会话 pending（上限默认 5）；状态经上述 `session_busy`/`pending_ack`/`pending_drain`/`session_idle`/`session_interrupted`/`pending_full` 推给前端，供「正在做 xx… 有新消息稍后回」轻状态展示。
- **续接**：忙完重开时新回合**带上上一轮上下文**（`tail` 默认 20 条），非清空重来。
- **mode** 取值：`idle` / `thinking` / `executing` / `subagent`。
- REST 同步路径（§3.1）在忙时返回 `202 queued` / 满 `409 chat_busy`，与这些 WS 状态事件一致。

### 6.6 流式关联（`turnId` / `seq`）

- `turnId`：`runTurn` 每次生成 `turn-<hex>`（crypto/rand），用于关联一轮流式突发；`stream_end`/`stream_chunk`（回退路径）带 `turnId`。**OnStream 结构化流路径（`message.*` 等）由 `broadcastStream` 只填 `seq`、不带 `turnId`**（OnStream bus 负载未携带 turn 身份）。
- `seq`：hub 级单调递增 `atomic.Uint64`，保证一次突发有序，即便 loop 多 goroutine 触发。

### 6.7 WS 示例

**握手 + 收 `history` + 发 `chat` 收流式**（伪代码/curl-like）：

```bash
# 1) 拿 token
TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"s3cret"}' | jq -r .data.token)

# 2) 连接（浏览器用 ws = new WebSocket('ws://host:8080/ws/chat?token='+TOKEN)）
# 首帧：{"type":"history","sessionId":"web","data":{"messages":[...]}}

# 3) 上行 chat
# {"type":"chat","data":{"sessionId":"web","text":"你好","deviceId":"web:chrome:a1b2c3"}}
# 下行（流式回退）：{"type":"stream_chunk","turnId":"turn-abc123","seq":1,"sessionId":"web","data":{"delta":"你"}}
# ... {"type":"stream_chunk",...} ...
# {"type":"stream_end","turnId":"turn-abc123","seq":8,"sessionId":"web","data":{"stopReason":"stop","steps":2}}

# 4) 上行 interrupt
# {"type":"interrupt","data":{"sessionId":"web"}}
# 下行：{"type":"session_interrupted","data":{"sessionId":"web","mode":"idle","dropped":2}}

# 5) 上行 voice_input
# {"type":"voice_input","data":{"audio":"<base64>","format":"wav","sessionId":"web"}}
# 下行（定向）：{"type":"voice_output","data":{"audio":"<base64>","format":"wav","text":"你好","reply":"你好呀"}}

# 6) 上行 subagent_ask
# {"type":"subagent_ask","data":{"id":"sub-1","mode":"full"}}
# 下行：{"type":"subagent_event","data":{...审计结果...}}

# 7) 上行 task_output_query
# {"type":"task_output_query","data":{"taskId":"task-1"}}
# 下行：{"type":"task_output","data":{"taskId":"task-1","output":"...","status":"done"}}
```

---

## 7. 上传 / 媒体说明

> ⚠️ **本节曾长期写「无 `/upload` 端点 / 无 REST 语音端点」，与实现恰好相反，已于 2026-10-03 修正**——正确口径见上文 §0.3 与 api-client §1 行 10–14。

- **`POST /api/v1/upload` 存在**（owner/admin + 审计）：multipart `file`（光栅图片，5MB 上限）→ `201 {"data":{"url","size","mime","name"}}`；`url` 为**同源访问地址** `/api/v1/files/<name>`，可直接作 `chat.image`。
- **`GET /api/v1/files/{name}` 存在**（**无需鉴权**——128-bit 随机能力 URL，`<img>`/`chat.image` 无法带 Bearer）：从 `<dataDir>/uploads/` 读该文件；`name` 仅接受「32 位小写 hex + 白名单扩展名」，**路径穿越全形态拒绝**。契约见 api-client §1 行 14。
- **REST 语音端点存在**（均 owner-only + 审计）：`POST /api/v1/audio/{transcribe,speech,voice-clone}`，供原生/移动端绕开 WS 4KB 帧限；语音**也可**走 WS 上行 `voice_input` / 下行 `voice_output`（定向回请求连接）。
- **图片 + 文本并存**：`image` 非空时 turn 变为「带图 + 可选文本」；`text` 空 + `image` 有 → 纯图像 turn。
- **文档导入**：走 `POST /api/v1/admin/rag` 的 JSON `content` 文本，**不是**文件上传。
- **敏感面**：`image`（base64）与 `bot_token`/`apiKey`/`newSecret` 等概不作为日志明文输出；wire 响应对 token/key 做掩码或不返回。

---

## 8. 附录

### 8.1 通用错误码 / 状态码

| 状态码 | code（示例） | 说明 |
|:---:|------|------|
| 200 | - | 成功 |
| 201 | - | 创建成功（personas/子会话/apikey/automations/llm/channels config/memories/rag） |
| 202 | - | 已接受（chat 排队 `queued:true,queueDepth`） |
| 204 | - | CORS 预检 OPTIONS 成功无内容 |
| 400 | `bad_request` / `invalid_cron` / `invalid_rule` / `invalid_role` / `unsupported_action` / `invalid_param` / `invalid_provider` / `invalid_scope` | 请求体/参数非法 |
| 401 | `unauthorized` | 认证缺失/失效/过期（REST Bearer 与 WS） |
| 403 | `forbidden` | 角色不足（viewer 读管理/主会话删除/写操作）；主会话不可删 |
| 404 | `not_found` | 资源不存在 |
| 409 | `chat_busy` / `duplicate` / `device_offline` / `needs_login` | 冲突：队列满 / 人格已存在 / 设备离线 / 渠道未登录 |
| 500 | `internal` / `chat_failed` / `sessions_failed` / … | 服务端错误（含未注入依赖） |
| 501 | `not_implemented` | 后端**确定未实现**（新增用户 / IoT 场景·规则 / 主人档案保存 / 编辑环境变量·重启服务·检查更新 / 完整会话转录导出等）——诚实返回，不伪造成功。**注：插件安装（§5.26）与知识库删除（§1.3 #23）已实现，不再返回 501** |

### 8.2 依赖注入与「未配置」行为

网关依赖（`Deps`）大多为 **nil 容忍**，未注入时端点要么回退、要么**如实报错**，绝不伪造成功：
- `History` 未注入：`GET /sessions` 回退渠道会话视图；`/messages`、`POST /sessions`、`DELETE /sessions/{id}`、`/channels/messages` 回 `501 not_implemented`。
- `RAG` 未注入：`GET /admin/rag` 返回空文档列表；`POST /admin/rag`、`/admin/rag/delete` 回 `501`。
- `Runner(Loop)` 未注入：`/chat` 回 `500 chat_unavailable`；WS `chat` 直接广播 `stream_end{stopReason:"idle"}`。
- `Channels` 未注入：`/admin/channels/config` 回 `500 channels_unavailable`。
- `LLM` 未注入：`/admin/llm` 按 `.env` 合成单组；`POST /admin/llm` 回 `500 llm_unavailable`。
- `Voice` 未注入：WS `voice_input` 回 `error {message:"voice unavailable"}`。
- `Scheduler(auditor)` 未注入：WS `subagent_ask` 回 `error {message:"subagent audit unavailable"}`。
- `Tasks` 未注入：WS `task_output_query` 回 `error {message:"task output unavailable"}`。
- `AuditStore` 未注入：审计退化为进程内存（端点仍返回数据）。
- 管理员**只读**端点若依赖缺失，大多返回 `[]`，不 500。

### 8.3 审计动作清单（`what` 字段，落 `audit_logs`）

`policy.set` / `persona.create` / `persona.update` / `user.create` / `apikey.issue` / `apikey.revoke` / `iot.control` / `iot.scenario` / `iot.rule` / `automation.create` / `automation.run` / `automation.delete` / `llm.addProvider` / `llm.test` / `channel.open` / `channel.close` / `channel.identity-test` / `channel.weixin.login.qr` / `channel.weixin.login.status` / `channel.weixin.login.persist` / `channel.platform.view` / `channel.friends` / `channel.friend.handle` / `channel.message.test` / `channel.save` / `channel.delete` / `plugin.install` / `plugin.uninstall` / `memory.add` / `memory.search` / `rag.index` / `rag.query` / `rag.delete` / `session.export` / `system.revoke_keys` / `system.rotate_jwt` / `system.backup` / `system.restore`。
（`what` 后缀 `_failed/_persist_failed/_reload_failed` 等计入 `error` 分支。）

### 8.4 里程碑与未实现集合（诚实标注）

- **已真实实现**：登录/健康检查/聊天（同步+流式）/会话（列表/新建/删除/消息分页）/人格/管理读（personas/sessions/memories/plugins/channels/iot/llm/users/automations/backthink/rag/observability×4：metrics/trace/audit/logs）/管理写（人格/API key/设备控制/自动化/LLM 保存·测试/渠道连接·断开·身份测试/渠道配置·删除/KOOK 面板/微信扫码/记忆添加·检索/插件安装·卸载/RAG 导入·删除/主人档案读写（`GET`/`PUT /api/v1/admin/owner-profile`，v0.51）/系统设置 4 项）。
- **仍为后置 M10（返回 `501 not_implemented`，不伪造）**：新增用户（无用户表/登录）、IoT 场景与规则（无模型/存储）、编辑环境变量/重启服务/检查更新、完整会话转录导出（当前导出身份元数据）。
- **语义/向量增强**：`memory.search` 的 `semantic` 当前恒为 `false`——**向量索引已由组合根注入**（`cmd/cyrene/wire.go` 的 `memory.WithVectorIndex`），但**索引内当前无向量**（生产无写入），故语义打分返回空，属诚实反映而非伪造；RAG `embedded` 反映部署是否配置向量增强；**配置了增强必须真实走语义/向量路径（红线，非空壳）**。
- **API key 认证**：`X-API-Key` **已接入鉴权**（v0.51，见 §0.1 注与 api-client.md §认证）——命中签发表即通过、一律 `owner` 级（取消 role 分级），带该头时只走 key 分支（坏 key 回 `401`、不回落 Bearer）；签发/吊销/列表同样真实生效。

### 8.5 客户端接入快速索引

1. `POST /api/v1/auth/login` → `{token, expiresAt, role}`（恒 `owner`）。
2. 之后每个 REST 请求带 `Authorization: Bearer <token>`；管理写需 `owner`；管理读需 `owner|admin`；`GET /sessions`、`GET /personas` 任意已认证。
3. 实时：`ws://<host>:8080/ws/chat?token=<token>`；首帧 `history` 回放（**仅 `owner`/`admin` 连接收到**）；上行 `chat`/`interrupt`/`voice_input`/`subagent_ask`/`task_output_query`/`mode_switch`（**仅 `owner`/`admin` 连接可发**，`viewer` 发送一律被定向拒）；下行见 §6.4 与 api-client §3。
4. 身份判定永远来自后端 channel 层 actor 元数据 + 白名单（`configs/users/owner.yaml`），**客户端不要用提示词/文本判身份**；`thinking` 在公开回放/实时帧中已剥离，客户端不应依赖。
5. 发送消息带 `deviceId`（推荐）以便端标识落库；`platform` 用于 IM 渠道过滤。