feat(gateway,config,web,docs): backthink 实时帧显示打扰原因 + 图片上限可配 + api-reference 端点表补齐

- 前端：`lib/wsParse.ts` 的 `parseBackthinkItem` 现在也读原始 `PushResult` 的 route/detail/bypassed（兼容
  camelCase），与历史 DTO 路径**同名同义**（空串 → undefined、未报告的 bool 不编成 false）；
  Backthink 页 Notice 改为如实描述。证据＝用后端两条路径的**真实序列化**喂同一个 PushResult 做逐字段比对
- 图片上限可配：`CHAT_IMAGE_MAX_BYTES`（默认 5242880 = 与 /upload 同口径；**未配置/0/负 一律用默认**，
  不存在「禁用上限」）；删掉重复的字符常量，换算只留一份 `chatImageCharsFor`；补 3 条用例
  （默认值==upload 预算、配 1 MiB 真生效且只有合法那条驱动回合、非正值回落默认）
- `Docs/api-reference.md`：§1 端点表按 `routes.go` **补齐**（auth refresh/logout、upload、files、三支 audio、
  /admin/plugins/installed、/admin/llm/catalog、observability/logs、notifications、owner-profile、reminders），
  既有编号一律未动（保交叉引用）；两张 `historyMessage` 字段表补 `personaId`（+ `clientMsgId`）；
  修正 §8.1「主人档案保存仍 501」与实现不符（已真实实现）
- 复核：build/vet 绿 + gateway/config 包测试绿 + 前端 tsc 0 错 + vite build 成功
- 登记：§1 各表的编号跨表重复（不重编号以保交叉引用）；`admin_plugins.go:217` 注释写错鉴权档（未改）；
  §6.4 的 WS 事件帧表仍未补全

Docs/api-reference.md

@@ -2,7 +2,7 @@
 
 > **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.56`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 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④**，属后续「文档补全」批次，本文件暂不补全。
+> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**§1 的 REST 端点表已于 2026-10-04 按 `internal/services/gateway/routes.go` 逐条核对并补登记**（补上此前缺失的 `POST /auth/refresh`、`POST /auth/logout`、`POST /upload`、`GET /files/{name}`、三支 `/audio/*`、`GET /admin/llm/catalog`、`GET /admin/observability/logs`、`GET /admin/notifications`、`GET /admin/plugins/installed`、`GET|PUT /admin/owner-profile`、`POST /admin/automations/reminders`）。**仍未补全的是 WS 事件帧清单**：§6.4 自述「并非全表」，`DevDocs/audit/00-总览.md` §4④ 列出的 `session_read` / `message_edited` / `message_deleted` 等仍未逐行登记。
 > **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。
 
 ---
@@ -45,7 +45,7 @@
 
 ### 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` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56）**：`chat.image` 解码后 **5 MiB**（字符串上限 `ceil(n/3)*4 + 64`），超限 `400 {"error":{"code":"image_too_large",...}}`；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
+- **`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` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56，2026-10-04 起可配）**：`chat.image` 解码后默认 **5 MiB**（与 `POST /api/v1/upload` 同口径；换算成字符串上限 `ceil(n/3)*4 + 64` 字符，已含 data: 前缀余量），超限 `400 {"error":{"code":"image_too_large",...}}`；字节上限由 `.env` 的 **`CHAT_IMAGE_MAX_BYTES`** 配置（默认 `5242880`；**≤0 视为「用默认」**，不存在「禁用上限」的取值），换配置时错误文案里的 MiB 数字会自动跟随；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
 - **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`），非文件上传。
 
@@ -53,7 +53,7 @@
 
 ## 1. REST 端点总览
 
-> 下表为**全量登记**；下文 §2–§5 每端点给出字段级说明。`鉴权列`：`无` / `JWT`(任意已认证) / `owner|admin` / `owner`。`里程碑` 为代码/设计归属的大致里程碑（M8 网关、M9 前端、M10 补齐写、M16 会话持久化等）。
+> 下表为**全量登记**；下文 §2–§5 每端点给出字段级说明。`鉴权列`：`无` / `JWT`(任意已认证) / `owner|admin` / `owner`。`里程碑` 为代码/设计归属的大致里程碑（M8 网关、M9 前端、M10 补齐写、M16 会话持久化等）。**`#` 列是登记序号**：它历史上曾是跨表连续序号，但 §1.3 起就与前后表重复（`§8.1` 等处有 `§1.3 #23` 这类交叉引用，故既有编号一律不动）；**补登记的行取本表内下一个可用号**。
 
 ### 1.1 公开（无鉴权）
 
@@ -61,12 +61,14 @@
 |---|------|------|:---:|------|:---:|
 | 1 | GET | `/api/v1/health` | 200 | 存活探针 `{status:"ok"}` | M8 |
 | 2 | POST | `/api/v1/auth/login` | 200 | 换取 JWT（恒 owner） | M8 |
+| 3 | POST | `/api/v1/auth/refresh` | 200/400/401 | 静默续期(B2)：body `{refreshToken}` → 新 access + 新 refresh（默认**单次使用旋转**；`AUTH_REFRESH_ROTATE_DISABLED=true` 时不旋转、旧 token 保持有效） | M17 |
+| 4 | POST | `/api/v1/auth/logout` | 200/400/401 | 登出(B2)：body `{refreshToken}` 撤**单个** grant（幂等）；带 Bearer 且无 body 撤**该账号全部**（两种响应形状不同，见 §2.4） | M17 |
 
 ### 1.2 用户侧（已认证）
 
 | # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
 |---|------|------|------|:---:|------|:---:|
-| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/400/409/500/503 | 发消息（同步回复或触发 WS 流式）；**v0.56**：`stream:true` 受理成功才回（`202` 续接排队 / `409` 队列满 / `500 chat_unavailable` 未接 loop / `503 chat_dispatch_failed` 兜底派发失败）、`image` 超 5 MiB → `400 image_too_large`、`clientMsgId` 重复 → `200 {duplicate:true}` | M8/M15 |
+| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/400/409/500/503 | 发消息（同步回复或触发 WS 流式）；**v0.56**：`stream:true` 受理成功才回（`202` 续接排队 / `409` 队列满 / `500 chat_unavailable` 未接 loop / `503 chat_dispatch_failed` 兜底派发失败）、`image` 超上限 → `400 image_too_large`（上限 = `CHAT_IMAGE_MAX_BYTES`，默认 5 MiB 与 `/upload` 同口径；≤0 视为用默认）、`clientMsgId` 重复 → `200 {duplicate:true}` | 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 |
@@ -77,10 +79,15 @@
 | 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 |
+| 14 | POST | `/api/v1/upload` | owner\|admin | 201 | multipart 图片上传(B1)：光栅白名单（png/jpeg/gif/webp/bmp）、解码后上限 5 MiB → 同源 URL，可直接作 `chat.image`（见 §7） | M17 |
+| 15 | GET | `/api/v1/files/{name}` | **无** | 200/404 | 已存上传的同源静态读（128-bit 随机名即能力 URL，`<img>`/`chat.image` 带不了 Bearer）；`name` 只接受 32 位小写 hex + 白名单扩展名，路径穿越全形态拒绝 | M17 |
+| 16 | POST | `/api/v1/audio/transcribe` | **owner** | 200 | 语音转写(STT，绕开 WS 4KB 帧限)；静音/空结果时响应带 `provider` | M17 |
+| 17 | POST | `/api/v1/audio/speech` | **owner** | 200 | 语音合成(TTS)；响应头 `X-Voice-Provider` 报告实际提供方（降级可见） | M17 |
+| 18 | POST | `/api/v1/audio/voice-clone` | **owner** | 200 | 声音复刻（百炼 create_voice） | M17 |
 
 ### 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`** + 全程审计。下表按注册顺序，标注鉴权与状态。
+> **鉴权分档（以 `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`，**现已全部登记进下表**）与 **`owner|admin` 档**（含他人数据 / 消息正文 / 凭据面 / 审计流水）；**写一律 `owner`** + 全程审计。下表按注册顺序，标注鉴权与状态。
 
 | # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
 |---|------|------|------|:---:|------|:---:|
@@ -88,11 +95,13 @@
 | 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 |
+| 62 | GET | `/api/v1/admin/plugins/installed` | owner\|admin\|viewer | 200 | 运行时安装的插件清单（脱敏配置 + 每 server 工具数）；鉴权以 `routes.go` 的注册（viewerAuth）为准 | 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 |
+| 65 | GET | `/api/v1/admin/llm/catalog` | owner\|admin | 200/503 | 模型目录候选（`?refresh=1` 强制在线刷新，否则复用 ≤24h 本地快照）→ `{source,fetchedAt?,stale?,warning?,providers[]}`；既无快照又抓不到 → `503 catalog_unavailable`（见 §4.9.1） | 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 |
@@ -101,11 +110,15 @@
 | 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 |
+| 63 | GET | `/api/v1/admin/observability/logs` | owner\|admin\|viewer | 200 | 后端日志尾部（`?level=`/`?limit=`，最新在前）；读取即建立推送订阅（v0.55，见 §4.16） | M10 |
+| 64 | GET | `/api/v1/admin/notifications` | owner\|admin\|viewer | 200 | 统一通知 feed（审计 + 渠道 + 后台思考 + 系统聚合；`?type=`/`?before=`/`?limit=`） | 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 |
+| 66 | GET | `/api/v1/admin/owner-profile` | **owner** | 200 | 主人档案（白名单账号 + 显示名/关系备注/默认角色；档案文件不存在返回空白档案而非 404） | M17 |
+| 67 | PUT | `/api/v1/admin/owner-profile` | **owner** | 200 | 保存主人档案（0600 原子落盘 + 热替换活档案，新白名单立即参与判主；校验失败 400） | M17 |
 | 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 |
@@ -113,6 +126,7 @@
 | 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 |
+| 68 | POST | `/api/v1/admin/automations/reminders` | **owner** | 201 | 新建定时提醒 body `{id?,at(RFC3339),message}` → 真实进 ReminderStore，到点发布 `reminder.trigger`（P0-22） | 后 M12 |
 | 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 |
@@ -140,6 +154,8 @@
 
 **另**：外部 webhook 回调（如 `webhook` 渠道的 HMAC 回调）由 composition root 通过 `Deps.Webhooks` 动态挂载，**不走网关鉴权**（handler 自校验签名/授权）；路径由调用方决定，不在上表枚举。
 
+**补登记说明（2026-10-04）**：上表中 `#62`–`#68` 是本次按 `routes.go` 逐条核对后新增的行（`plugins/installed` / `observability/logs` / `notifications` / `llm/catalog` / `owner-profile` GET+PUT / `automations/reminders`），插在各自的鉴权分档里、**既有编号一律未动**。§1.1 的 `#3`/`#4`（`auth/refresh`、`auth/logout`）与 §1.2 的 `#14`–`#18`（`upload`、`files/{name}`、三支 `audio/*`）同理。**仍未登记的是 WS 事件帧**（见 §6.4 与本文档开头的历史包袱说明）。
+
 **WS**：`GET /ws/chat`（握手，JWT，见 §6）。
 
 ---
@@ -231,7 +247,7 @@ curl -s -X POST http://<host>:8080/api/v1/auth/login \
   - 流式（`stream=true`，**v0.56 行为变更**）：**受理成功后才回** —— 空闲已起回合 `200` `{"data":{"stream":true}}`；正忙已续接排队 `202` `{"data":{"stream":true,"queued":true,"queueDepth":<int>}}`；待处理满 `409` `{"error":{"code":"chat_busy",...}}`；幂等键重复 `200` `{"data":{"duplicate":true,"messageId":<id>,"sessionId":<id>}}`（**不落库、不起回合**）。实际文本经 WS 推送（见 §6）。**修复前**该分支在问编排器之前就回 `200 {"data":{"stream":true}}`，故 `202`/`409` 永不出现；**未接 loop 时由 `200 {stream:true}` 改为 `500 chat_unavailable`**（与同步路径同口径）。
 - **错误**：
   - `400` `{"error":{"code":"bad_request","message":"text or image is required"}}`（空消息）。
-  - `400` `{"error":{"code":"image_too_large",...}}`（**v0.56/G3**：`image` 解码后超 **5 MiB**；base64 字符串上限 `ceil(n/3)*4+64`，与 `POST /api/v1/upload` 同口径，文案指路该端点）。
+  - `400` `{"error":{"code":"image_too_large",...}}`（**v0.56/G3**：`image` 解码后超上限；上限 = `CHAT_IMAGE_MAX_BYTES`（默认 **5 MiB**，`≤0` 用默认），base64 字符串上限 `ceil(n/3)*4+64`，与 `POST /api/v1/upload` 同口径，文案指路该端点）。
   - `409` `{"error":{"code":"chat_busy","message":"会话正忙，待处理消息已满"}}`（pending 队列满，`PendingFull`）。
   - `500` `{"error":{"code":"chat_unavailable",...}}`（`runner` 未注入）/ `{"error":{"code":"chat_failed",...}}`（回合运行出错）。
   - `503` `{"error":{"code":"chat_dispatch_failed",...}}`（**v0.56/G2**：仅**未接编排器**时的总线兜底派发失败——本轮**未提交**，不再是静默 200）。
@@ -347,6 +363,8 @@ curl -s http://<host>:8080/api/v1/personas -H "Authorization: Bearer $TOKEN" -H
 | `deviceId` | string | 客户端端标识（`omitempty`，如 `web:chrome:a1b2c3`） |
 | `senderName` | string | 第三方发送者昵称（`omitempty`；群聊/陌生人消息带，主人私聊为空） |
 | `adapterId` | string | 产生该消息的适配器注册名（`omitempty`，如 `kook:3bef...`；Web 消息为空） |
+| `personaId` | string | **该消息说话时的角色 id**（`omitempty`，**v0.42**，design/22 §7-5）：会话角色在创建时固定，`assistant` 消息 = 生成它的角色、`user` 消息 = 当回合角色；**空 = 全局默认角色**（v0.42 之前的全部历史行）。客户端据此按角色渲染名字/头像 |
+| `clientMsgId` | string | **客户端幂等键**（`omitempty`，**v0.56/G4**）：带 `clientMsgId` 发来的 user 消息回填它；空 = 该消息没有幂等键（老客户端 / IM 镜像 / 历史行）。客户端用它把本地乐观气泡对齐到服务端真相 |
 | `createdAt` | int64 | Unix 毫秒（兼作分页游标） |
 
 ```json
@@ -1182,6 +1200,7 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
 | `deviceId` | string | `omitempty` |
 | `senderName` | string | `omitempty`（第三方昵称，主人私聊为空） |
 | `adapterId` | string | `omitempty`（仅 `channel_persisted` 常见，如 `kook:3bef...`） |
+| `personaId` | string | `omitempty`（**v0.42**：该消息说话时的角色 id——`assistant` 消息 = 生成它的角色、`user` 消息 = 当回合角色；空 = 全局默认角色。与 `GET /sessions/{id}/messages` 同源字段，客户端按角色渲染名字/头像） |
 | `clientMsgId` | string | `omitempty`（**v0.56/G4**：客户端自带的幂等键——由 `chat` 上行带 `clientMsgId` 的 user 消息写入，之后在 `message_persisted` / `channel_persisted` / `history` 回放 / `GET /sessions/{id}/messages` 中原样回填；空 = 无幂等键，即老客户端 / IM 镜像 / 历史行） |
 | `createdAt` | int64 | Unix 毫秒 |
 
@@ -1271,7 +1290,7 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
 | 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** |
+| 501 | `not_implemented` | 后端**确定未实现**（新增用户 / IoT 场景·规则 / 编辑环境变量·重启服务·检查更新 / 完整会话转录导出等）——诚实返回，不伪造成功。**注：插件安装（§5.26）、知识库删除（§1.3 #23）、主人档案保存（`PUT /api/v1/admin/owner-profile`，§1.3 #67）均已实现，不再返回 501** |
 
 ### 8.2 依赖注入与「未配置」行为