docs(api): 扩充客户端接入指引 §4——三步登录/会话消息用法/deviceId·platform·senderName规范/错误码/离线缓存，便于跨平台客户端开发

Docs/api-client.md

@@ -127,10 +127,36 @@
 - **注：群聊/陌生人（非主人）消息**只在**该 IM 适配器日志界面**以消息流显示，**不**经 `message_persisted` 进 Web 主会话（design/16 §4.6 §3-4）；该日志流由 `GET /api/v1/admin/channels/{platform}/messages` 拉取。
 - **客户端处理**：仅当 `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` 列表。
+## 4. 客户端接入指引（Web / 移动 / 原生 / IM bridge 通用）
+
+### 4.1 一次性接入流程（三步走）
+1. **拿令牌**：`POST /api/v1/auth/login` `{username,password}` → `{data:{token,expiresAt,role}}`（JWT，默认 24h，`role` ∈ `owner|admin|viewer`）。
+2. **声明版本**：后续每个请求头带上 `X-API-Version: 1` + `Authorization: Bearer <token>`；WS 握手用 `ws://<host>:<port>/ws/chat?token=<token>`（或 `Authorization: Bearer`）。**viewer 只能读会话/人格元数据；读写会话消息、管理写操作需 `owner`/`admin`。**
+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=`。
+  - **热分页**：`limit` 默认 50（上限 200），`before` = 当前最旧一条的 `createdAt`（毫秒），向上翻页。`platform` 可选（IM 适配器传本平台只拉本渠道；Web/通用客户端不传 = 全量共享主会话）。
+  - 返回**按时间倒序**，需 `reverse()` 成旧→新用于渲染。
+- **发消息**：`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 条）。
+
+### 4.3 deviceId 与 platform 规范（design/16 §4.4-4.5）
+- **`platform`**（来源平台）：`web` / 渠道如 `telegram`、`weixin-ilink`、`qq-obv11`。Web 端恒 `web`；IM 渠道消息带各自平台。**同一平台多个端 → 相同 platform、不同 deviceId。**
+- **`deviceId`**（具体端，客户端自己生成）：Web 每个浏览器 `localStorage` 持久化 `web:<browser>:<随机短id>`（如 `web:chrome:a1b2c3`）；IM 按 `<im平台名>:<本地配置唯一id>:<用户平台唯一uid>`；某 APP 可自定可读前缀。发送时带上，服务端落库消息，聊天气泡可标注来源。
+- **`senderName`**（第三方昵称）：只有群聊/陌生人（非主人）消息带，主人私聊恒空（`omitempty`）。**IM 适配器_log**：该平台非主人私聊在 `GET /api/v1/admin/channels/{platform}/messages` 以消息流显示。
+
+### 4.4 常见错误码 / 边界
+- `401` 未认证/令牌失效 → 重新登录。`403` 权限不足（viewer 读管理写/主会话删除）。
+- `404` 端点未实现；`501 not_implemented` 后端明确未提供（如知识库删除、新增用户）。
+- `400` 请求体/参数非法（`limit`/`before` 越界、空 content）。`409 chat_busy` 排队满。
+- **红线**：身份判定永远来自后端 channel 层 actor 元数据 + 白名单，**客户端不要用提示词/文本判身份**；`thinking`（思维链）在公开消息/回放中**已剥离**，客户端不应依赖它。
+
+### 4.5 离线 / 缓存建议（原生端）
+- PWA / 原生端缓存 `sessions`/`personas` 列表 + 最近一屏消息；重连先本地渲染再拉增量。
+- 消息**真源在后端**，本地只做渲染缓存；用 `message_persisted.id` 去重，不要用本地自增 id。
+- 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
 
 ## 5. 变更记录
 - `v0.14`（IM 多会话隔离 + 第三方身份 + 黑白名单，design/16 §4.6）：**`chat_messages` 增 `sender_name` 列**（迁移 0006，默认 `''`）；消息 DTO（REST 消息、WS `history` 回放、WS `message_persisted`）均带 **`senderName`**（第三方发送者昵称，主人私聊为空 `omitempty`）。**第三方身份边界**：IM 群聊/陌生人会话在上下文构建时对第三方消息注入 `[第三方 · <昵称>]` 前缀（**不改源消息正文**，落库保留原文）+ 前置系统提示词"每个 IM 的非管理员账户 = 第三方人员，和主人无关"——身份判定基于 channel 层 actor 元数据 + 白名单（`MemWritable=false` 即群聊/陌生人），**绝不靠 LLM 猜**。**会话隔离**：群聊/陌生人消息**落独立隔离会话**（`sess-xxx`，带 `platform`+`senderName`，**不**并入主会话 `web`、**不**走 `message_persisted` 广播），供 **`GET /api/v1/admin/channels/{platform}/messages`**（owner/admin，management 面板渠道日志区）以消息流显示；**前端主会话**只显示各平台管理员（owner）私聊；群聊/陌生人记忆只读不写主会话（`memory_gating` 已按 `MemWritable` 门控）。**多账号**：`CHANNELS_JSON` 支持同一平台多个接入配置（每个 account 独立 session/账号，见 §2 渠道契约）。**黑白名单**：每平台每账号可配 `allowGroups/denyGroups/allowUsers/denyUsers`，channelbridge **入站即拦截**（黑名单/不在白名单 → 丢弃，`audit` 可查，**不进 LLM**）；白名单按 `platform+account`（群 id / 用户 uid）。