feat(history): 消息搜索/编辑/删除 + 会话置顶(D2/D3/D5)

- history/message_ops.go(新): Search(会话内, q/after互斥, LIKE参数化+%/_转义+大小写不敏感, 严格限定会话doc) / UpdateMessage(返回更新后Message) / DeleteMessage / messageByID / escapeLike
- history/session_pin.go(新): SetPinned; 迁移0009 chat_sessions加pinned INTEGER DEFAULT 0; store.go SessionMeta.Pinned + createSessionsTable加列
- session_preview.go: 查询加s.pinned + ORDER BY pinned DESC,(type=main) DESC,created_at ASC
- gateway history_write.go(新,保持history.go≤500): handlePatchSession(pinned+title) / handlePatchMessage / handleDeleteMessage; server.go加PATCH/DELETE /api/v1/messages/{id} + /sessions/{id}置顶
- history.go: handleListMessages读q分流Search; 契约PATCH title/置顶
- D2会话内搜索(不做跨会话,隔离会话不外泄红线); D3不做重发端点(客户端编辑后再发); D5用pinned bool
- 测试(message_ops/history_messages/migrate_pinned), build/vet/test绿+3平台交叉编译; Docs/api-client v0.30
- 未做: 编辑/删除WS实时广播(message_edited/deleted), 下批

Docs/api-client.md

@@ -26,11 +26,13 @@
 | 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）；带 `Authorization: Bearer <jwt>` 且无 body → 撤**该账号全部** grant（全设备登出，返回 `{revokedCount}`）。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）——**真视觉需配 `LLM_VISION_MODEL`/凭据，无凭据时降级为主模型直接看图或视觉·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,lastMessage?}]}`（主会话 `id="web"` 恒在首位，次级 `web:<uuid>`；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略）；未注入时退化回渠道会话列表 |
+| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,lastMessage?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:<uuid>`；`pinned` 恒返回 bool；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略）；未注入时退化回渠道会话列表 |
 | 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId}}`（`sessionId="web:<uuid>"`）；未注入 HistoryStore 回 `501 not_implemented` |
-| 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` 为**第三方发送者昵称**；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `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` 为**第三方发送者昵称**；**`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:{message}}`（更新后的完整消息 DTO，含 `id/sessionId/role/content/.../createdAt`；**只改 `content`**，role/时间戳/平台保持不变）；消息不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**重发不单独设端点**——客户端用「编辑后的内容再 `POST /chat`」即可（避免重复轮次语义） |
+| 6b | `/api/v1/messages/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除单条消息**（D3）→ `{data:{deleted:<id>}}`；不存在回 `404 not_found`；未注入 HistoryStore 回 `501` |
 | 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）：body `{title}`（trim、≤80 rune，空/超长回 `400`）→ `{data:{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`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / 两者都改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶但不可删；未注入 HistoryStore 回 `501`。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 |
 | 9 | `/api/v1/personas` | GET | JWT | ✅ | `{data:[persona...]}` |
 | 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"`，非空文本省略），客户端据此提示「没识别到声音」） |
 | 11 | `/api/v1/audio/speech` | POST | JWT(owner) | ✅ | **文本→音频**：body `{text,voice?,format?,instruction?}` → `200` 音频字节（`Content-Type: audio/<format>`，非 JSON envelope，走后端 TTS，百炼 `cosyvoice-v3-flash`，复刻音色可带 `instruction` 情绪指令；**静默降级空音频时仍 `500 tts_empty`，并附 `X-Voice-Provider: silent` 响应头**，客户端据此提示「没生成声音」） |
@@ -192,10 +194,13 @@
 3. **带端标识**（可选但推荐）：每条消息/请求可带 `deviceId`（见 §4.3），让她知道你从哪个端来。
 
 ### 4.2 会话与消息用法（聊天）
-- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt}]`。**主会话 `id="web"` 恒在首位**（她与你的主线，最大化继承上下文）；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。
-- **拉取激活会话历史**：`GET /api/v1/sessions/{id}/messages?limit=50&before=<ms>&platform=`。
+- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned}]`。**排序：置顶会话（`pinned=true`）最前，其次主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。
+- **改名 / 置顶**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）或 `{pinned?:bool}`（至少一个字段）→ `{data:{id,title?,pinned?}}`（只回显变更字段）。
+- **拉取激活会话历史**：`GET /api/v1/sessions/{id}/messages?limit=50&before=<ms>&platform=&q=`。
   - **热分页**：`limit` 默认 50（上限 200），`before` = 当前最旧一条的 `createdAt`（毫秒），向上翻页。`platform` 可选（IM 适配器传本平台只拉本渠道；Web/通用客户端不传 = 全量共享主会话）。
+  - **搜索**：`q` 非空 = **会话内**内容搜索（倒序，仍支持 `before`/`limit` 分页）；空 `q` = 普通分页；`q` 与 `after` 互斥。**不跨会话**。
   - 返回**按时间倒序**，需 `reverse()` 成旧→新用于渲染。
+- **编辑 / 删除单条消息**：`PATCH /api/v1/messages/{id}` `{content}`（≤4000 rune）→ `{data:{message}}`；`DELETE /api/v1/messages/{id}` → `{data:{deleted:<id>}}`。不存在回 `404`。**重发**用「编辑后内容再 `POST /chat`」即可（无独立重发端点）。
 - **发消息**：`POST /api/v1/chat` `{text, deviceId?, image?, stream:true}`。`stream:true` 走 WS 流式；非流式返回完整 `reply`（会话正忙时 `202 queued`、排队满 `409 chat_busy`，见 §3.2）。
 - **实时增量**：连接 WS 后，消息落库会广播 `message_persisted`（§3.3）——**用其中的 `id` 去重**，`sessionId` 匹配激活会话才渲染；新开/重连连接首帧即 `history` 回放（主会话最近 50 条）。
 
@@ -206,7 +211,7 @@
 
 ### 4.4 常见错误码 / 边界
 - `401` 未认证/令牌失效 → 重新登录。`403` 权限不足（viewer 读管理写/主会话删除）。
-- `404` 端点未实现；`501 not_implemented` 后端明确未提供（如知识库删除、新增用户）。
+- `404` 资源不存在（消息/会话 id 未找到）或端点未实现；`501 not_implemented` 后端明确未提供（如知识库删除、新增用户）。
 - `400` 请求体/参数非法（`limit`/`before` 越界、空 content）。`409 chat_busy` 排队满。
 - **红线**：身份判定永远来自后端 channel 层 actor 元数据 + 白名单，**客户端不要用提示词/文本判身份**；`thinking`（思维链）在公开消息/回放中**已剥离**，客户端不应依赖它。
 
@@ -216,6 +221,7 @@
 - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
 
 ## 5. 变更记录
+- `v0.30`（**Android 协同批次 ③a：D2 消息搜索 / D3 消息编辑删除 / D5 会话置顶**）：① **D2**：`GET /api/v1/sessions/{id}/messages` 新增可选 **`q`**——**会话内**内容搜索（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 转义为字面量），仍倒序 + `before`/`limit` 游标；`q` 与 `after` 互斥（同传 `400`），空 `q` 走普通分页；**严格限定单会话，不新增跨会话搜索**（避免群聊/陌生人隔离会话外泄，红线）。`HistoryStore` 新增 `Search`。② **D3**：新增 `PATCH /api/v1/messages/{id}`（body `{content}`，非空 ≤4000 rune → `{data:{message}}`，只改 content）与 `DELETE /api/v1/messages/{id}`（→ `{data:{deleted:id}}`）；不存在回 `404 not_found`；`HistoryStore` 新增 `UpdateMessage`/`DeleteMessage` + `ErrMessageNotFound`。**不新增重发端点**（客户端用编辑后的 content 再发）。③ **D5**：`chat_sessions` 新增 `pinned INTEGER NOT NULL DEFAULT 0`（迁移 **0009**，down 可逆）；`GET /sessions` 排序改为 **`pinned DESC` → 主会话优先 → `createdAt ASC`**，会话 DTO 新增恒返回的 **`pinned`** bool；`PATCH /sessions/{id}` 扩展为 body `{title?,pinned?}`（至少一个字段，只回显变更字段，title-only 保持 A4 形状）；`HistoryStore` 新增 `SetPinned`。全部为 owner/admin 写、读消息 owner/admin；未注入 HistoryStore 回 `501`。
 - `v0.29`（**/admin/llm 读-改-写合并**）：`POST /api/v1/admin/llm` 由「全量替换」改为**部分编辑合并**——请求体字段用指针区分「未给」与「显式零值」；`maxTokens` / `apiKey` / `provider` / `baseUrl` / `model` / `fallback` / `multimodal` **省略即保留原值**（不再把省略的 `maxTokens` 重置为 0），新组仍要求 `baseUrl`+`model`、非法 provider / 负 maxTokens 仍 `400`。面板 LLM 页新增每组 `maxTokens` 展示/编辑 + 新增/编辑表单；面板插件页新增「已装插件列表」+「安装 MCP 插件」表单（kind/name/transport/endpoint|command+args/apiKey/env），api.ts 请求体带 `config`（修掉旧 body 400）。`runtimeconfig/models.go` 新增 `Find`。
 - `v0.28`（**MCP 插件热安装/卸载**）：`POST /api/v1/admin/plugins/install`（**由 501 改为真实实现**，owner-only + 审计）body `{kind:"mcp",name,config:{transport,endpoint?|command?,args?,apiKey?,env?}}` → `200 {data:{installed,name,kind,transport,toolCount}}`——真实连接 MCP server、发现并**热注册工具**进 capability registry（下一轮模型请求即注入），配置落盘 `plugins.json`（gitignore、0600）；连接失败回 `502` 且**不落盘**；同名重复 = 刷新。`POST /api/v1/admin/plugins/uninstall` 扩展：MCP 插件走 `Unregister`（移除工具 + close + 删配置），普通能力保持原 `registry.Remove`。新增 `GET /api/v1/admin/plugins/installed`（owner/admin 读）列出已装插件（`apiKey`/敏感 `env` 掩码 + `live`/`toolCount`）。`mcp.MCPConfig` 新增 `APIKey`（http/sse 以 `Authorization: Bearer` 发送）与 `Env`（stdio 子进程环境）；`plugins.json` 于启动时 `Restore` 重新安装。**契约版本 `v0.28`**。
 - `v0.27`（**LLM token 预算可配置化**）：`models.json` 模型组新增可选 **`maxTokens`**（`int`，缺省/`0` = 未设），作为该组主/备链的 token 预算；`GET /api/v1/admin/llm` 的 `AdminLlmProvider` 与 `POST /api/v1/admin/llm` body/回显同步该字段（`omitempty`，未设为 0 时不出现）。`.env` 新增 **`LLM_FALLBACK_MAX_TOKENS`**（`int`，默认 `8192`，`0` = 关闭兜底），只作用于**确有回退模型**时链末端的回退步。**优先级**：显式 `Request.MaxTokens`（审查/判定类小预算）> 生效组 `maxTokens` > `LLM_FALLBACK_MAX_TOKENS`（仅链末端、且组未设时）> 适配器默认（anthropic 8192）。单步链（无 fallback）不套用 env 兜底。`maxTokens` 为负回 `400 bad_request`。**契约版本 `v0.27`**。