fix(gateway)+docs(api): F5 区分「字段缺失/值为空白」+ E4/E5 契约文档治理

- F5：PATCH /sessions/{id} 的 400 文案区分两类——都缺 → at least one of title or pinned is required；
  存在但空白 → title must not be blank（此前空白也回 title is required，误导排查方向）。
  「空串不能清空标题」的既有语义保持不变（用例显式钉住），新增 history_write_test.go 4 段断言
- E4：/auth/logout 的两种真实响应形状（单撤 {revoked} / 全撤 {revoked,revokedCount}）+ 错误码；
  /auth/refresh 补 role；登录响应与一次性接入段补 refreshToken（两份文档一致）
- E5：api-reference §3.2 补 pinned/unreadCount/lastMessage/personaId 与准确排序规则
  （pinned DESC, (type='main') DESC, created_at ASC ⇒ 置顶的次级会话可排在主会话之前）；
  新增 §3.6a PATCH /sessions/{id}（请求体/错误码/部分更新/title 不可清空）与 §3.6b POST /sessions/{id}/read；
  端点表补 read 行
- api-client 删掉「主会话恒在前」的错误断言（两处），PATCH 错误码文案同步
- DevDocs/02-development-constraints.md：上传上限 50MB → **硬 5 MiB**（常量、无配置项）

Docs/api-client.md

@@ -24,17 +24,17 @@
 | # | 端点 | 方法 | 认证 | 状态 | 说明 |
 |---|------|------|------|:---:|------|
 | 1 | `/api/v1/auth/login` | POST | 否 | ✅ | `{username,password}` → `{data:{token,expiresAt,role,refreshToken?}}`（access 24h；**新增 `refreshToken`**——不透明随机串，仅哈希落库，`AUTH_REFRESH_TTL` 默认 720h，用于静默续期；role=owner） |
-| 1a | `/api/v1/auth/refresh` | POST | refreshToken | ✅ | **静默续期**（B2）：body `{refreshToken}` → `{data:{token,expiresAt,refreshToken?}}`（新 access + 新 refresh，**默认单次使用旋转**——旧 refresh 立即作废，并发重放 fail-closed `401 invalid_grant`）。`AUTH_REFRESH_ROTATE_DISABLED=true` 关闭轮换时旧 token 保持有效、不返回新 refresh。过期/已撤销/乱串统一 `401 {error:{code:"invalid_grant"}}`；成功才审计 |
-| 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）；带 `Authorization: Bearer <jwt>` 且无 body → 撤**该账号全部** grant（全设备登出，返回 `{revokedCount}`）。refresh 相关操作成功才审计 |
+| 1a | `/api/v1/auth/refresh` | POST | refreshToken | ✅ | **静默续期**（B2）：body `{refreshToken}` → `{data:{token,expiresAt,role,refreshToken?}}`（新 access + 新 refresh；**`role` 恒返回** = 该 refresh grant 记录的角色 `owner|admin|viewer`），**默认单次使用旋转**——旧 refresh 立即作废，并发重放 fail-closed `401 invalid_grant`）。`AUTH_REFRESH_ROTATE_DISABLED=true` 关闭轮换时旧 token 保持有效、不返回新 refresh。过期/已撤销/乱串统一 `401 {error:{code:"invalid_grant"}}`；成功才审计 |
+| 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）→ `{data:{revoked:<bool>}}`；带 `Authorization: Bearer <jwt>` 且无 body → 撤**该账号全部** grant（全设备登出）→ `{data:{revoked:<bool>,revokedCount:<n>}}`。**两种响应形状不同**——单撤**没有** `revokedCount`；两者都不给回 `400 bad_request`。refresh 相关操作成功才审计 |
 | 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
 | 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06 §0；**v0.53 语义修正**）——**主模型能不能收图看生效组的 `multimodal`**（`models.json` 组键，面板可保存、热更新）；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**，**与主模型能否收图无关**（裁决 14.4.1）；主模型不收图时由视觉·OCR 工具的**文本描述**替代（图像不占上下文，只有工具结果占）；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `<p>` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` |
-| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:<uuid>`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 |
+| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：以代码为准 = `pinned DESC, (type='main') DESC, created_at ASC`**——`pinned=true` 最前，其次是未置顶的主会话，最后是未置顶子会话（按 `createdAt` 升序）；⚠️ **置顶的次级会话会排在主会话之前**，客户端定位主会话请按 `id=="web"` / `type=="main"`，**不要假定 index 0 就是主会话**；次级 `web:<uuid>`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 |
 | 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:<uuid>"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色（design/22 §2：渠道级只作"新会话的初始角色提供者"；**会话角色只在创建时写入、之后不可变**，见 §1 行 8 / design/22 §8-1）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） |
 | 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：逐条记录"谁说的"——会话角色在创建时固定，§8-1；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` |
 | 6a | `/api/v1/messages/{id}` | PATCH | JWT(owner/admin) | ✅ | **编辑单条消息**（D3）：body `{content}`（非空、≤4000 rune，空/纯空白/超长回 `400`）→ **`{data:<消息DTO>}`**（`data` **直接就是**更新后的完整消息 DTO，含 `id/sessionId/role/content/.../createdAt`，**无 `message` 包一层**；**只改 `content`**，role/时间戳/平台保持不变）；消息不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_edited`**（§3.8，账号其它端免刷新同步）。**重发不单独设端点**——客户端用「编辑后的内容再 `POST /chat`」即可（避免重复轮次语义） |
 | 6b | `/api/v1/messages/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除单条消息**（D3）→ `{data:{deleted:<id>}}`；不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_deleted`**（§3.8，账号其它端按 `id` 移除） |
 | 7 | `/api/v1/sessions/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除次级会话及其消息** → `{data:{deleted:<id>}}`；主会话不可删回 `403 forbidden`；未注入 HistoryStore 回 `501` |
-| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶）：body `{title?,pinned?}`（**至少一个字段**，都缺回 `400`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）；**`personaId` 出现即 `400`**（v0.46，design/22 §8-1：**会话角色在创建时确定、之后不可变，要换角色请新开会话**）——**不是静默忽略、也不是 200 空操作**：**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request`，错误消息点名 `personaId`，且该检查**先于**会话存在性检查（**未知会话 + `personaId` 也回 `400`**，不是 `404`；连 `title` 同传也整体 `400`、不改任何字段）。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / 两项同改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶但不可删；未注入 HistoryStore 回 `501`。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 |
+| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶）：body `{title?,pinned?}`（**至少一个字段**；都缺回 `400 {"code":"bad_request","message":"at least one of title or pinned is required"}`——说明「缺字段」）。`title` trim、≤80 rune：**存在但为空/仅空白回 `400 "title must not be blank"`**（**不是** `title is required`——字段在、只是值非法）、超长回 `400 "title is too long (max 80 characters)"`；**空串不能清空标题**（不回落自动命名，故客户端不提供「恢复自动命名」入口）；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）；**`personaId` 出现即 `400`**（v0.46，design/22 §8-1：**会话角色在创建时确定、之后不可变，要换角色请新开会话**）——**不是静默忽略、也不是 200 空操作**：**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request`，错误消息点名 `personaId`，且该检查**先于**会话存在性检查（**未知会话 + `personaId` 也回 `400`**，不是 `404`；连 `title` 同传也整体 `400`、不改任何字段）。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / 两项同改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶但不可删；未注入 HistoryStore 回 `501`。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 |
 | 8a | `/api/v1/sessions/{id}/read` | POST | JWT(owner/admin) | ✅ | **推进已读游标**（D4 / Android 协同 B3）：body `{before?}`——`before` 为**可选**的毫秒 Unix 时间戳，**缺省（或空 body）= 现在**，即「我看到的都算已读」。→ `200 {data:{sessionId,readAt}}`（`readAt` 为推进后的游标毫秒）。**判定**：`createdAt <= readAt` 的消息算已读（列表 `unreadCount` 只数 `createdAt > readAt` 的）；**语义**：**会话级单一游标、单 owner 账号**——读一处 = **该账号所有端已读**（不做 per-device 游标，与「同一账号所有浏览器都属于同一 owner」一致）；**只前进不后退**（SQL `read_at = MAX(read_at, before)`），所以乱序/并发/重试请求幂等安全、绝不会把已读变回未读。`before` 为 `0`/负数/非数字、或 body 不是 JSON 对象 → `400`；未知会话（含隔离 `sess-xxx`，不在 `chat_sessions`）→ `404`；未注入 HistoryStore → `501 not_implemented`。**成功后广播下行 `session_read`**（§3.9）让同账号其它端清红点；**失败路径不广播**。**升级回填**：迁移 `0010` 把既有会话游标回填为「该会话现有最新消息时间」，升级当天不误报未读 |
 | 9 | `/api/v1/personas` | GET | JWT | ✅ | **角色目录**（任意已认证角色可读）→ `{data:[PersonaSummary...]}`，每项 `{id,name,character,isDefault,mode,memoryNamespace,avatar?,chatBackground?,mood}`。**`mood`（v0.43）** = 该角色**当前情绪状态**（角色级，取值见 `GET /meta/enums` 的 `moods`；`""` = 该角色暂无被跟踪的情绪，**不伪造默认值**）。**语义：情绪跟随角色，与会话无关**——同一角色的所有会话看到同一 `mood`；客户端登录/加载角色目录时用它**播种心情徽标**，避免刷新后短暂空白（随后以 WS `mood` 帧为准）。**不含 admin 专属的 `thinking` 旋钮**（用户侧不暴露模型调用参数）。 |
 | 10 | `/api/v1/audio/transcribe` | POST | JWT(owner) | ✅ | **语音→文本**：body `{audio:"<base64>",format?,deviceId?}` → `{data:{text, provider?}}`（走后端 STT，百炼 `qwen-audio-3.0-asr-flash`；**当结果为空文本/silent 降级时响应体带 `provider`**（如 `"silent"`，非空文本省略），客户端据此提示「没识别到声音」） |
@@ -449,12 +449,12 @@
 ## 4. 客户端接入指引（Web / 移动 / 原生 / IM bridge 通用）
 
 ### 4.1 一次性接入流程（三步走）
-1. **拿令牌**：`POST /api/v1/auth/login` `{username,password}` → `{data:{token,expiresAt,role}}`（JWT，默认 24h，`role` ∈ `owner|admin|viewer`）。
+1. **拿令牌**：`POST /api/v1/auth/login` `{username,password}` → `{data:{token,expiresAt,role,refreshToken}}`（JWT，默认 24h，`role` ∈ `owner|admin|viewer`；`refreshToken` 为 B2 不透明长期凭据，用于静默续期，未接线 refresh 存储时**省略该键**）。
 2. **声明版本（可选/advisory）**：可带 `X-API-Version: 1` + `Authorization: Bearer <token>`；WS 握手用 `ws://<host>:<port>/ws/chat?token=<token>`（或 `Authorization: Bearer`）。**`X-API-Version` 是**advisory**惯例头——服务端当前不校验、不据此协商版本，带不带行为不变**；`viewer` 只能读会话/人格元数据；读写会话消息、管理写操作需 `owner`/`admin`（**WS 上 `viewer` 也只收 7 个状态机信号帧：既收不到 `history` 回放，也发不出任何上行指令**，见 §3 顶部两把角色门，v0.48 + v0.49）。
 3. **带端标识**（可选但推荐）：每条消息/请求可带 `deviceId`（见 §4.3），让她知道你从哪个端来。
 
 ### 4.2 会话与消息用法（聊天）
-- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]`。**排序：置顶会话（`pinned=true`）最前，其次主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。**`personaId`（v0.42）=该会话绑定的角色**；空/缺省 = **继承全局默认角色**，客户端渲染激活会话的名字/头像用它（后端唯一真源是 `chat_sessions.persona_id`，localStorage 之类只作缓存）。
+- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]`。**排序：置顶会话（`pinned=true`）最前，其次是未置顶的主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；⚠️ **置顶的次级会话可以排在主会话之前**，别把列表第一项当主会话（按 `id=="web"` / `type=="main"` 定位）；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。**`personaId`（v0.42）=该会话绑定的角色**；空/缺省 = **继承全局默认角色**，客户端渲染激活会话的名字/头像用它（后端唯一真源是 `chat_sessions.persona_id`，localStorage 之类只作缓存）。
 - **新建时选角（v0.42，v0.46 收口）**：`POST /api/v1/sessions` body `{personaId?}` 在**新建时**就绑角色（省略/空 = 跟随全局默认角色）。**会话角色在创建时确定、之后不可变**（design/22 §8-1）：**没有"会话内换角色"这回事**——`PATCH /api/v1/sessions/{id}` 一旦收到 `personaId` 键就回 `400`（见 §1 行 8），**要换角色请新开会话**。**记忆按角色隔离**：不同角色的会话各记各的，同一角色的多个会话互相可见（design/22 §3 口径 1）；群聊/陌生人会话仍**只读**、且强制默认角色。
 - **角色解析优先级（v0.44，design/22 §2 裁决规则 + §7-3/§7-4）**：一个回合到底以哪个角色答话，**自上而下**取第一个命中的：
   1. **请求级覆盖** —— 仍**未实现**（design/22 §2 裁决规则 1，留待后续批次）；
@@ -463,7 +463,7 @@
   4. **全局默认角色** `owner.yaml:defaultPersona` —— 兜底（`''` 始终 = 当前默认角色）。
   **群聊 / 陌生人隔离会话强制默认角色**（§7-4，更保守）：这两类会话**跳过** 2/3 两条渠道与主会话绑定，一律用默认角色，避免把第三方会话挪进某个角色的记忆域；记忆仍是**只读**。**Web 主会话与 IM 主人私聊共享同一角色**（§7-3）：主会话绑 Y 时，同一主会话里 IM 镜像进来的主人私聊回合也以 Y 答话。
 - **模型上下文里的「谁说的」（v0.44，design/22 §7-5）**：一回合的上下文由该会话**最近 20 条**持久化消息（`chat_messages`，含 `persona_id`）+ 本回合新消息组成（此前只带新消息本身，模型看不到会话前文）；**每条 assistant 历史消息按其说话角色标注**，模型收到形如 `[发言归属] 以下发言来自「昔涟」（xilian），不是你说的。` 的独立 system 标注，以及一条声明当前角色的 `[会话角色] …` 段。**正文永不被改写**：标注只走 system 消息，用户正文与 assistant 正文一字不改（design/11 §10：不给用户正文冒充系统指令的机会）。**对客户端透明**（无新字段、无新端点）。
-- **改名 / 置顶**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）和/或 `{pinned?:bool}`（至少一个字段）→ `{data:{id,title?,pinned?}}`（只回显变更字段）。**body 里出现 `personaId` 键一律 `400`**（会话角色不可变，v0.46 / design/22 §8-1）。
+- **改名 / 置顶**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune，空白标题回 `400 "title must not be blank"`——**空串不能清空标题**/恢复自动命名）和/或 `{pinned?:bool}`（至少一个字段；都缺回 `400`）→ `{data:{id,title?,pinned?}}`（只回显变更字段）。**body 里出现 `personaId` 键一律 `400`**（会话角色不可变，v0.46 / design/22 §8-1）。
 - **未读 / 已读游标（D4）**：列表项的 **`unreadCount`** 直接用于会话列表红点（恒返回整数，0 = 无未读）。客户端进入会话、或滚到底看到最新消息后调用 **`POST /api/v1/sessions/{id}/read`**：body `{"before":<毫秒>}`（如「本次已渲染的最新一条的 `createdAt`」），或**省略 body** = 标记到**现在**。后端**只前进**地推进该会话**唯一**游标（单 owner 账号：读一处 = 所有端已读），并广播 `session_read`（§3.9）——同账号其它端**免刷新**清红点。列表 → 读 → 再看列表即可自洽（漏收广播的端下次拉列表自然收敛）。
 - **拉取激活会话历史**：`GET /api/v1/sessions/{id}/messages?limit=50&before=<ms>&platform=&q=`。
   - **热分页**：`limit` 默认 50（上限 200），`before` = 当前最旧一条的 `createdAt`（毫秒），向上翻页。`platform` 可选（IM 适配器传本平台只拉本渠道；Web/通用客户端不传 = 全量共享主会话）。