feat: IM式跨端实时同步——message_persisted 广播 + 前端按id去重追加

- history.Store 新增 AppendFull（返回含 id/createdAt 的完整消息），Append 签名不变
- session_orchestrator 加可空 OnPersisted；persistUserMessages/persistAssistantReply 落库后回调广播
- server.go newOrchestrator 接 OnPersisted → hub.broadcast message_persisted（thinking 剥除）
- 前端 ws.ts 加 message_persisted case（仅 activeSessionId 匹配才处理）；appendOrUpdateMessage 升级为 id 精确upsert+内容/时间归一
- 实测：双 WS，A stream 发消息，B 免刷新收到 user+assistant 各1条（count=2 PASS）
- 红线: 身份仍靠 actor 元数据，不靠提示词；用户/助手消息、本端/异端统一路径

Docs/api-client.md

@@ -87,7 +87,7 @@
 ## 3. WebSocket `/ws/chat`（实时）
 
 - **握手**: `ws://<host>:8080/ws/chat?token=<JWT>` 或 `Authorization: Bearer`；未认证在握手前回 `401` JSON。
-- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?, sessionId?}`（`turnId`/`seq` 为流式关联字段，见 §3.1；`sessionId` 为**会话持久化（design/16）新增**，能确定会话的事件带上，供客户端按激活会话过滤）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end` / `tool_execution.update`（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update`。**会话编排状态（design/15，均为广播，`data.sessionId` 区分会话）**：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（见 §3.2）。语音回复走 `voice_output`（定向回请求连接，非广播）。
+- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?, sessionId?}`（`turnId`/`seq` 为流式关联字段，见 §3.1；`sessionId` 为**会话持久化（design/16）新增**，能确定会话的事件带上，供客户端按激活会话过滤）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end` / `tool_execution.update`（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update` / **`message_persisted`**（会话持久化增量，见 §3.3）。**会话编排状态（design/15，均为广播，`data.sessionId` 区分会话）**：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（见 §3.2）。语音回复走 `voice_output`（定向回请求连接，非广播）。
 
   > **`history` 回放事件（design/16，新增）**：WS 握手升级成功后、该连接下一帧即收到 `{type:"history", sessionId:"web", data:{messages:[{id,sessionId,role,content,mode?,mood?,image?,createdAt}]}}`——回放主会话最新 50 条（`thinking` 已剥离，不泄给非 owner；默认主会话，次级会话由客户端按激活会话走 `GET /sessions/{id}/messages` 拉取）。客户端据此在重连/新开连接后补全上下文。
 
@@ -116,12 +116,18 @@
 - **`pending_full`**：单会话 pending 达上限（默认 5）拒绝入队（`{sessionId, mode, max}`）——防无限积压（design/15 §4）。
 - **上下文续接**：忙完重开时新回合**带上一轮上下文**（`{mode, queueDepth}` 之外的续接由服务端完成），非清空重来（design/15 §2.2）。
 
+### 3.3 消息持久化增量事件（`message_persisted`，design/16）
+- **触发**：每一条 user / assistant 消息**落库后**由编排层广播（`persistUserMessages` 在提交时写用户消息、`persistAssistantReply` 在回合落定时写助手消息）。
+- **载荷**：`{type:"message_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, mood?, image?, createdAt}}}`——`role` ∈ `user|assistant`；`id` 为**后端生成的消息 id**（客户端据此去重）；`thinking` 已剥离（design/16 §6）。
+- **客户端处理**：仅当 `data.message.sessionId === activeSessionId`（激活会话）时处理；按 `id` upsert——本端已预建的**同 role 乐观气泡**（本地 `uid` 无后端 `id`）被**归一**（`uid` → 后端 `id`），异端无本地气泡则直接追加，两者最终收敛为**同一条 `id` 相同的消息**，「A 发消息、A 与 B 都无需刷新且各出现一次」。
+
 ## 4. 客户端接入指引
 - **认证**: 先 `POST /api/v1/auth/login` 取 JWT → WS 握手（`?token=`）注入。
 - **版本**: 客户端请求头声明 `X-API-Version: 1`。
 - **离线**: PWA / 原生端建议缓存 `sessions`/`personas` 列表。
 
 ## 5. 变更记录
+- `v0.11`（跨端实时同步，design/16 §4.2）：WS 下行新增 **`message_persisted`** 事件——每条 user/assistant 消息落库后广播 `{type, sessionId, data:{message:{id,sessionId,role,content,mode?,mood?,image?,createdAt}}}`（`id` 为后端生成，`thinking` 已剥离）。客户端按 `sessionId === activeSessionId` 过滤 + 按 `id` upsert（含本端乐观气泡 `uid`→后端 `id` 归一）去重，实现「A 发消息、A 与 B 都无需刷新且各出现一次」。后端 `history.Store` 新增 `AppendFull` 供编排层取含 `id` 的落库消息。
 - `v0.10`（会话消息持久化 — WS 契约，design/16，后端-2）：WS 下行帧新增可选 `sessionId` 字段（能确定会话的事件带上）；新增 **`history` 回放事件**——WS 握手成功即回放主会话最新 50 条（`{type:"history", sessionId:"web", data:{messages:[...]}}`，`thinking` 已剥离）。`stream_end`/`stream_chunk`/会话编排状态帧（`session_busy` 等）在能确定 session 时带 `sessionId`；`message.delta` 等结构化流帧因 `model.StreamEvent` 无 session 上下文不带（即"若知道就带上"边界）。
 - `v0.9`（会话消息持久化 + 主/次级会话，design/16，后端-1）：新增 `POST /api/v1/sessions`（新建次级会话）、`GET /api/v1/sessions/{id}/messages?limit=&before=`（游标热分页拉历史，时间倒序）、`DELETE /api/v1/sessions/{id}`（删次级会话及其消息）；`GET /api/v1/sessions` 在注入 `HistoryStore` 后改返回持久化会话元数据数组（主 + 次级，`type` 区分），未注入时保持原渠道会话列表向后兼容。读消息/写会话为 owner/admin（用户侧私有历史，thinking 不达 viewer）；会话元数据列表保持任意认证角色可读。
 - `v0.8`（管理面板写操作 CRUD）：补齐管理面板**写端点**（见 §2「管理面板写操作契约」，均 owner-only + 审计）——`POST/PUT /admin/personas`（真实注册 + 持久化 `configs/personas/<id>.yaml`）、`POST /admin/users/apikey` + `DELETE /admin/users/apikey/{id}`（真实签发/撤销）、`POST /admin/iot/{id}/control`（真实设备控制）、`POST /admin/automations` + `/run` + `DELETE`（真实注册/触发/移除规则）、`POST /admin/llm`（临时记录）+ `/admin/llm/test`（真实模型调用）、`POST /admin/channels/{open,close,test}`（真实连接/断开 + 结构性身份识别）、`POST /admin/plugins/uninstall`（真实 registry 移除）、`POST /admin/memories/search`（真实检索）、`GET /admin/sessions/{id}/export`。无存储的写（新增用户 / IoT 场景·规则 / 插件安装）如实返回 `501 not_implemented`。