diff --git a/Docs/api-client.md b/Docs/api-client.md index a2a7b9e..8b08754 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -1,11 +1,12 @@ # Cyrene v2 客户端 API 契约 -> **契约版本：`v0.66`**（上一版 `v0.65`；该基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 +> **契约版本：`v0.67`**（上一版 `v0.66`，其条目见 §6；`v0.65` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。 > **读者**：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等**跨平台客户端开发者**。 > **唯一真源 = 当前代码**（`internal/services/gateway/*` 等）。本文档由代码逐条核对得出；与代码不符时**以代码为准**，并回改本文档。 > **旧的超详细版已归档、只读**：`Docs/archive/api-client.v0.65.md`（412 KB，含 v0.28→v0.65 全部历史条目）与 `Docs/archive/api-reference.v0.65.md`（170 KB，后端全量字段级文档）。归档的原因是**结构性臃肿 + 历史条目并列 + 长期漂移**；本文档**不复制**那段历史，需要考古时去归档。 > **维护铁律**：每实现/变更一个 REST 端点、WS 事件、admin API **立即改本文档**；契约变更必须版本化，不破坏既有客户端。 > **准确性 > 详尽度**：宁少写也别写错；**写不了确证的写「未确证」**，见 [§7](#7-在飞切片与未实现未确证)。 +> ⚠️ **v0.67 是「契约先行」登记版**：本版新增的三批 —— **语音消息**（播放端点 + 消息 DTO `voice`）、**非消息事件查询面**、**账号在线状态** —— **当前尚未实现**，形状**取自设计文档**（`design/24 §10.11`、`design/26 §4.5` / `§2.6`）**而非代码核对**；已在 §7.2 逐条如实标注。**本文档其余内容仍以代码为真源**。 --- @@ -38,6 +39,7 @@ - 成功：`{"data": <载荷>}`（个别端点直接回二进制，见 §4.5 语音）。 - 失败：`{"error":{"code":"<机器可读码>","message":"<人读文案>"}}`。 - 状态码全集（代码实际使用）：`200 201 202 400 401 403 404 409 413 415 429 500 501 503`。 + - ⚠️ v0.67 登记的 `GET /api/v1/media/{name}`（**尚未实现**，见 §7.2）会引入 **`206` / `304`**，以及一条**非信封**的 **`416`**（`Range` 错误由 Go 标准库直写 `text/plain` + `Content-Range: bytes */`，**不套** `{"error":…}`）。这三者**不在**上面那份「代码实际使用」集合内，实现后才加入；客户端**不要**拿 `error.code` 去解析 `416`。 - **客户端按 `error.code` 分支，不要按 `message` 文本**（文案会随修改变动）。 ### 0.4 三档标注惯例 @@ -56,6 +58,7 @@ |---|---| | `HistoryStore` | `GET /sessions` 回退到渠道会话视图；`POST /sessions`、`GET /sessions/{id}/messages`、`PATCH/DELETE /sessions/{id}`、`POST /sessions/{id}/read`、`PATCH/DELETE /messages/{id}` → `501 not_implemented` | | 语音服务 | `POST /audio/*` → `500 voice_unavailable`；WS `voice_input` → `error` 帧 `{"message":"voice unavailable"}` | +| 渠道事件存储（`internal/runtime/events`） | `GET /admin/channels/events` 与 `.../events/counters` → `500 channel_events_unavailable`（**v0.67 登记，尚未实现**；绝不回全 0 假汇总，见 §2.4(a)） | | LLM usage 出口 | `GET /admin/llm/usage` → `500 usage_unavailable`（绝不回全 0 假汇总） | | 活跃 SQLite 连接 | `GET /admin/system/storage` → `500 storage_unavailable` | | 可观测日志缓冲 | `GET /admin/observability/logs` → `501`（组合根注入前） | @@ -97,8 +100,9 @@ | U16 | POST | `/api/v1/sessions/{id}/read` | owner/admin | 200 / 400 / 404 / 500 / 501 | 推进已读游标。body `{before?}`（毫秒；缺省=现在）→ `{data:{sessionId,readAt}}`。游标**会话级单所有者、只进不退**（读一处 = 该账号所有端已读）。成功广播 `session_read` 帧；失败不广播。 | | U17 | PATCH | `/api/v1/messages/{id}` | owner/admin | 200 / 400 / 404 / 500 / 501 | 编辑单条消息。body `{content}`（非空、≤4000 rune）→ **`{data:<消息 DTO>}`**（`data` 直接就是完整消息，**不再包一层 `message`**）。只改 `content`。成功广播 `message_edited`。 | | U18 | DELETE | `/api/v1/messages/{id}` | owner/admin | 200 / 404 / 500 / 501 | 删除单条消息 → `{data:{deleted:}}`。成功广播 `message_deleted`。 | +| U19 | GET | `/api/v1/media/{name}` | **owner/admin（必须 Bearer）** | 200 / 206 / 304 / 401 / 403 / 404 / 416 | **语音副本播放 / 取字节**（**v0.67 登记，尚未实现**，见 §7.2）。`Content-Type: audio/*`；`Content-Disposition: inline; filename=""`；`X-Content-Type-Options: nosniff`；`Accept-Ranges: bytes`；支持 `Range` 与 `HEAD`；名字非法 / 穿越 / 不存在统一 `404 media_not_found`。⚠️ **`416` 不是 JSON 信封**（标准库直写）。详见 §4.5 语音。 | -> **`GET /api/v1/files/{name}` 无鉴权**（能力 URL）；其余全部用户端点至少要求已认证。 +> **`GET /api/v1/files/{name}` 无鉴权**（能力 URL）；**`GET /api/v1/media/{name}` 与 `GET /api/v1/documents/{name}` 必须 Bearer owner/admin**（与图片读侧「128-bit 名即凭据」的取向**刻意相反**）；其余全部用户端点至少要求已认证。 --- @@ -130,7 +134,7 @@ | A2 | GET | `/api/v1/admin/sessions` | 会话清单 | | A3 | GET | `/api/v1/admin/plugins` | 能力/插件清单 | | A4 | GET | `/api/v1/admin/plugins/installed` | 已安装插件清单 | -| A5 | GET | `/api/v1/admin/channels` | 渠道清单。`accounts[]` 各元素**可能**带可选 `connected:bool`（v0.66）：**该账号自己的**适配器是否已连接；**键缺席 = 状态未知**（该账号没有活适配器），**不等于**「未连接」—— 面板据此决定是否给「断开」按钮。**不含任何凭据** | +| A5 | GET | `/api/v1/admin/channels` | 渠道清单。`accounts[]` 各元素**可能**带可选 `connected:bool`（v0.66）：**该账号自己的**适配器是否已连接；**键缺席 = 状态未知**（该账号没有活适配器），**不等于**「未连接」—— 面板据此决定是否给「断开」按钮。**v0.67 登记（尚未实现）**：各元素另**可能**带可选 `accountOnline:bool`（**账号在平台上是否在线**，与 `connected` 是**两件事**；**键缺席 = 状态未知 ≠ 离线**）—— 见 §2.4(b)。**不含任何凭据** | | A6 | GET | `/api/v1/admin/iot` | IoT 设备清单 | | A7 | GET | `/api/v1/admin/automations` | 自动化与提醒清单 | | A8 | GET | `/api/v1/admin/rag` | 知识库文档清单（名字/描述 + 切分/嵌入状态）；`?query=` 搜索亦只读 | @@ -214,6 +218,33 @@ > - `id` 与 `empty=1` 同时给出 ⇒ `400 bad_request`；**两者都缺 ⇒ `400 bad_request`**（绝不把「id 缺失」默认解释成删无 id 条目 —— 那是一次没有字面证据的批量删除）。`?empty=` / `?empty=0` / `?empty=false` 一律是「否」。 > - 响应：`{data:{persisted, path, platform, accountId, empty, removed}}`（`empty`/`removed` 是 v0.66 新增）；`removed` = 实际删除的条目数。删空后平台键整个消失（与按 id 删除的收尾口径一致）。 +### 2.4 v0.67 登记、**尚未实现**的管理面（渠道事件查询 + 账号在线状态） + +> ⚠️ **本节全部内容尚未进 `routes.go`**（截至契约 v0.67 冻结）：形状取自设计文档（`design/26 §4.5`、`§2.6`），**不是**代码核对所得。**§2.0 的计数（12 + 11 + 40 = 63）不含本节端点**；实现落地后再回填 §2.1/§2.2 并更新计数。客户端**不要**现在就按本节编程到「已可用」——以 §7.2 的状态为准。 + +#### (a) 渠道事件（非消息事件）只读查询 + +| # | 方法 | 路径 | 要点 | +|---|---|---|---| +| D1 | GET | `/api/v1/admin/channels/events` | 非消息事件列表（**倒序**）。query：`platform` / `tier` / `category` / `channelId` / `since` / `until` / `limit` / `offset`。响应 `{data:{events:[…], total}}`。`since` / `until` 按 **UTC ISO-8601 定宽字符串**做**字典序**比较（与 `GET /admin/llm/usage` 同口径）；**跨度上限 90 天**（超 → `400`）；`platform` 未知 → `400`。**不含正文、不含任何媒体 URL、不含任何凭据 / `flag`** | +| D2 | GET | `/api/v1/admin/channels/events/counters` | 逐类计数汇总（**近似值**）。query：`platform`。响应 `{data:{counters:[{platform,accountId,tier,category,platformType,count,firstSeenAt,lastSeenAt}]}}`，并带 **`approx:true`** 如实标注「计数为聚合近似值」（计数是**内存聚合 + 周期 flush**，非逐条实时）。⚠️ `approx` 的**嵌套层级**设计未明说，见 §7.4 | + +- **RBAC 档位未定**：设计原文写「owner/admin；`viewer` 只读亦可，按既有 RBAC 惯例」—— 两种解释都成立，本契约**不替它二选一**（见 §7.4-12）。落地前**不要**假设 viewer 能读。 +- **数据源两张表**（`design/26 §4.1`，表名**复数**）：`channel_events`（`tier` 为 `t2`/`t3` 的事件与**所有** `unknown` 逐条留存，**参与保留期 GC**）与 `channel_event_counters`（`t1` 与**所有**帧的计数，按 `(platform, account_id, platform_type)` upsert，**不参与 GC**）。 +- `tier` 取值域：`t1`（只计数）/ `t2` / `t3`（逐条留存；T3 是「谁对谁做了什么」的定向交互记录）。`category` 取值域（**归一化类别**，设计原文给出 `heartbeat` / `lifecycle` / `join` / `leave` / `recall` / `ban` / `admin` / `friend_request` / `group_request` / `poke` / `reaction` / `button` / `vote` / `item` / `link` / `unknown`，并在末位带 `…` ⇒ **非穷举**，客户端**未知取值原样展示、不报错**）。 +- `events[]` 元素 = 一条 `channel_events` 行的投影。设计只给到**落库列**：`id` / `platform` / `account_id` / `tier` / `category` / `platform_type` / `channel_id` / `channel_type` / `group_id` / `actor_id` / `actor_role`（`owner`/`member`/`system`/`unknown`，结构化解析所得）/ `target_id` / `self_related` / `message_id` / `summary` / `created_at` / `updated_at`。`actor_id`/`target_id` 是 **id 不是昵称**；`summary` 是**固定文案**（如「群成员加入」，**不含任何平台原文**）。⚠️ **元素的 JSON 键名设计未逐字给出**，见 §7.4-9 —— 客户端**现在不要硬编码**。 +- **未接线存储时**：两个端点都回 **`500 channel_events_unavailable`**（对齐 `usage_unavailable` / `storage_unavailable` 的诚实边界口径，**绝不回全 0 假汇总**）。 +- 三个新 env 键（`design/26 §4.4`，已登记进 §5）：`CHANNEL_EVENT_RETENTION`（默认 `720h`）、`CHANNEL_EVENT_GC_INTERVAL`（默认 `1h`）、`CHANNEL_EVENT_COUNTER_FLUSH`（默认 `30s`）。 +- ⚠️ **微信渠道不提供非消息事件**：查询面 / 面板对该渠道**如实显示空 + 说明文字**，绝不伪造、绝不用别的渠道事件顶替。 + +#### (b) `GET /api/v1/admin/channels` 的账号项：`accountOnline` + +- `accounts[]` 元素**可能**带可选 `accountOnline:bool`（**v0.67 登记、尚未实现**）：该账号**在平台侧是否在线**。 +- **与 `connected` 是两件事**（这是本案的全部理由）：`connected` = **本项目的适配器是否连着**（WS 会话连通）；`accountOnline` = **账号本身在平台上是否在线**。OneBot 实现（NapCat 等）的进程与正向 WS 可以一直连着，而背后的 QQ 账号已经掉线 —— 此时 `connected:true` 而 `accountOnline:false`，消息**既收不到也发不出**。 +- **三态**（`known` 口径）：`accountOnline:true` = **确知在线**；`accountOnline:false` = **确知离线**；**键缺席 = 状态未知**（尚未探到：探活未接线 / 刚启动 / 一直失败 / 该平台没有独立账号状态面）。**绝不可把「未知」画成「离线」**，也不可画成「在线」—— 那正是 2026-10-05 事故里「面板仍显示已连接、日志一片空白」的同一类坑。 +- 状态源：`AccountStatus()`（`plugins/channels/qq_obv11/probe.go`），其 `known` 区分「确知离线」与「尚未探到」；本字段的**缺席**即承载 `known=false`。当前**只有 `qq-obv11`** 有这条独立状态面：周期约 **60s** 主动探活 OneBot `get_status`（读 `{online, good}`），与上游可配的 `meta_event` 心跳**并列**（心跳优先、探活兜底），**只在状态变化时**记一条带 `source` 的日志。 +- ⚠️ **字段名（`accountOnline`）是本契约所拟**：设计只规定「独立状态面 + `AccountStatus()` + `known`」，**未给管理面字段名**（见 §7.4-13）。实现若改名，须回改本行与 §6 的 v0.67 条目。 + --- ## 3. WebSocket `/ws/chat` @@ -235,7 +266,7 @@ {"type":"history","sessionId":"web","data":{"messages":[ ... ]}} ``` -- 内容 = 主会话最近 **50** 条（`wsReplayLimit`），`thinking` 恒缺席（见 §3.4.4 口径更正）；每条**可能**带可选 `turnId`（v0.66，空则键省略）。 +- 内容 = 主会话最近 **50** 条（`wsReplayLimit`），`thinking` 恒缺席（见 §3.4.4 口径更正）；每条**可能**带可选 `turnId`（v0.66，空则键省略）与可选 `voice`（**v0.67 登记、尚未实现**；形状见 §4.4）。 - **viewer 连接完成握手时完全不做回放**（其只读窗口是 REST 监控面）。 - 回放是尽力而为：存储未接或读出错静默跳过。 @@ -329,6 +360,7 @@ > **思维链的唯一出口是实时帧**：§3.4.2 的 `thinking.start` / `thinking.delta` / `thinking.end`（owner/admin 档）。客户端**不要**为「从历史里读回思维链」写任何代码。 > ⚠️ 本行**更正**本文档 v0.65 及更早的写法（旧版称「历史思维链只有 `GET /sessions/{id}/messages`（owner/admin）返回」）—— **那是文档写错了**，与实现不符。见 §7.3。 > 另注：管理面板人格清单里的 `thinking` 是**人格旋钮**（`GET /admin/personas` 的 `thinking` 块），与消息 DTO 的 `thinking` 不是同一个字段。 +> **`voice` 覆盖同一批读取面（v0.67 登记，尚未实现）**：消息 DTO 新增的可选 `voice` 对象一次覆盖 `message_persisted` / `channel_persisted` / `message_edited` 与握手 `history` 回放（形状与语义见 §4.4）。**WS 协议本身零变化**：无新帧、无新上行字段；`voice` 只是既有 DTO 的新可选键。 #### 3.4.5 子代理 / 任务 / 系统帧（owner+admin） @@ -376,16 +408,18 @@ | 400 | `bad_request`、`image_too_large`、`too_many_documents` | 请求体/字段非法、图片超限（`image` **字符串长度**，**仅 base64 / `data:` 形态会触发**，见 §4.5）、附件超条数 | | 401 | `unauthorized`、`invalid_grant` | 无/坏凭据；refresh token 非法 | | 403 | `forbidden` | 角色不足；主会话不可删 | -| 404 | `not_found`、`session_not_found`、`document_not_found`、`account_not_found` | 资源缺失；消息列表的会话不存在；文档缺失（含名字非法/穿越）；渠道账号 id 不存在（C19/C20） | +| 404 | `not_found`、`session_not_found`、`document_not_found`、`account_not_found`、`media_not_found`（**v0.67 登记、尚未实现**） | 资源缺失；消息列表的会话不存在；文档缺失（含名字非法/穿越）；渠道账号 id 不存在（C19/C20）；**语音副本缺失**（含名字非法/穿越，三者同一响应，见 §4.5） | | 409 | `chat_busy`、`account_not_registered` | 待处理队列满；渠道账号已配置但没有已注册适配器（C19/C20，v0.66） | | 413 | `payload_too_large`、`document_too_large` | 上传/文档超限 | | 415 | `unsupported_media_type` | 图片/文档类型拒绝 | | 429 | `rate_limited` | 限流（框架级） | -| 500 | `internal`、`chat_unavailable`、`chat_failed`、`voice_unavailable`、`stt_failed`、`tts_failed`、`tts_empty`、`voice_clone_failed`、`usage_unavailable`、`storage_unavailable`、`refresh_unavailable`、`sessions_failed`、`messages_failed`、`session_failed`、`message_failed`、`document_upload_failed`、`login_failed` | 内部错误或依赖未接线（**绝不伪装成功**） | +| 500 | `internal`、`chat_unavailable`、`chat_failed`、`voice_unavailable`、`stt_failed`、`tts_failed`、`tts_empty`、`voice_clone_failed`、`usage_unavailable`、`storage_unavailable`、`channel_events_unavailable`（**v0.67 登记、尚未实现**）、`refresh_unavailable`、`sessions_failed`、`messages_failed`、`session_failed`、`message_failed`、`document_upload_failed`、`login_failed` | 内部错误或依赖未接线（**绝不伪装成功**） | | 501 | `not_implemented` | HistoryStore 等未注入 | | 503 | `timeout`、`chat_dispatch_failed`、`catalog_unavailable` | 派发/上游不可用 | > **未确证**：`conflict`(409) 的通用码存在（框架级 `ErrConflict`），但除了 `chat_busy` 之外，本文档未逐一确证还有哪些端点会带它。 +> **⚠️ `416` 不是错误信封（v0.67 登记，尚未实现）**：`GET /api/v1/media/{name}` 的 `Range` 语法非法或范围不可满足时，**由 Go 标准库直写** `416`（`text/plain` + `Content-Range: bytes */`），**不套** `{"error":{…}}` ⇒ 客户端**不要**拿 `error.code` 去解析它（见 §4.5）。这是字节流端点的既有事实（`/audio/speech` 的 `200`、`/documents/{name}` 的 `200` 同样不是 JSON 信封），**不是**本版新引入的怪癖。 +> **`400` 的渠道事件用法（v0.67 登记，尚未实现）**：`GET /admin/channels/events` 对 `platform` 未知、`since`/`until` 跨度 > 90 天都回 `400`（**具体 `code` 名设计未给出**，见 §7.4-11）。 ### 4.2 分页与游标 @@ -432,11 +466,20 @@ "personaId": "...", // 空 = 全局默认角色 "clientMsgId": "...", // 空则省略 "turnId": "turn-…", // v0.66；空则省略（老消息/未接管路径） + "voice": { // v0.67 登记（尚未实现）；非语音消息键缺席；🎤 判据 = 本键存在 + "source": "asr", // "asr"（服务端识别，含云端）| "platform"（渠道平台自带转写） + "status": "transcribed", // "transcribed" | "empty" | "failed"（闭集三态） + "name": "a1b2c3….ogg", // 音频副本存储名；无副本 ⇒ 键省略 + "mime": "audio/ogg", + "size": 12345, + "durationMs": 3200, // 可选：渠道如实给出时才有（绝不估算） + "url": "/api/v1/media/a1b2c3….ogg" // 与 name 同生共死（服务端相对路径） + }, "createdAt": 1700000000000 } ``` -字段省略规则：`mode`/`mood`/`image`/`thinking`/`platform`/`deviceId`/`senderName`/`adapterId`/`personaId`/`clientMsgId`/`turnId` 均为 `omitempty`（空时键缺席）。 +字段省略规则：`mode`/`mood`/`image`/`thinking`/`platform`/`deviceId`/`senderName`/`adapterId`/`personaId`/`clientMsgId`/`turnId`/`voice` 均为 `omitempty`（空时键缺席；`voice` 是**指针**，非语音消息整键缺席，**不是** `{}` 也不是 `null`）。 **`turnId` 语义（v0.66，可选）**： @@ -445,6 +488,19 @@ - 退化为空（**键省略**）的三类情形：① 加入该列（迁移 `0018`）之前的历史行；② 未经编排器的写入路径（**IM 渠道桥等**，其行 `turn_id` 留空是预期行为）；③ 忙时入队 / 被转向吃进的消息 —— 它们**落库那一刻**还没有自己的路，那一帧 `message_persisted` 因此**不带** `turnId`，客户端从随后的 `turn_begin`（帧壳 `turnId` + `data.messageIds`）得知归属；行本身由**实际处理它的那一路**随后补写（先到先得）。 - 列口径：`chat_messages.turn_id TEXT NOT NULL DEFAULT ''`（**不用 NULL**，于是「旧行」与「没写」是同一个值）。 +**`voice` 语义（v0.67 登记，尚未实现）**： + +- 形状：`{source,status,name?,mime?,size?,durationMs?,url?}`，`omitempty`（**非语音消息键缺席**，与引入语音前逐字相同）。 +- **🎤 判据 = `voice` 键存在**（这条消息来自一条语音消息）。客户端**绝不**从 `content` 正文里认媒体类型：QQ 语音正文里那个 `[语音]` 占位标记自 v0.67 起**不再下发**（见 §6 的 v0.67 行为变更），正文里也可能出现用户自己打出的 `[语音]` 字样。**只认 `voice` 键**。 +- `source` ∈ `"asr"`（服务端语音识别所得，含云端）/ `"platform"`（渠道平台自带转写，微信 iLink 的 `voice_item.text`）。 +- `status` ∈ `"transcribed"`（正文即转写文本）/ `"empty"`（转写成功但没识别出文字）/ `"failed"`（没拿到转写文本 —— 正文是那行中文诚实提示）。**客户端按 `status` 分支，绝不按正文文案分支**（§0.3 的同一纪律）。设计还**刻意不下发** `failed` 的机器可读细分（未配置 / 鉴权 / 欠费 / 限流 / 超时 / 格式不支持 / 无字节 ⇒ 分类只进服务端日志，正文给的是人读的原因方向）。 +- `name` / `mime` / `size` / `url` **四者同生共死**：有音频副本时全在，**无副本时全缺席**（**不会**出现 `url` 指着一个不存在的 `name` 这种形状）。 +- `durationMs` **只有渠道如实给出时才有**；读不出来就**省略键，绝不估算**（当前未确证各渠道是否都给得出，见 design/24 §10.12-8）。 +- `url` 是**服务端相对路径** `/api/v1/media/`（唯一派生字段，由服务端一处拼出）⇒ **客户端绝不自己拼路径**。 +- 落库形状 = DTO 形状**减去** `url`（列 `chat_messages.voice TEXT NOT NULL DEFAULT ''`，JSON **单对象**；**用空串不用 NULL**，与 `turn_id` 同一口径）。音频原件**复用文档那一套存储 / 元数据表 / 引用计数 / GC**（同一 `/uploads/documents` 目录），但**不进文档的抽取 / 注入链路**：不被抽取、不进 `documents` DTO 数组、不占注入预算、不出现在附件清单行里。 +- **一条消息只落一份音频副本**（= 被转写的那一条语音）；同一条消息里的第 2..N 条语音既不转写也不落盘，DTO 里也没有它们（**刻意的边界**，不是遗漏）。 +- ⚠️ **微信（`weixin-ilink`）语音没有音频副本、不可回放**：按既有裁决「平台自带转写就不白下载那份音频」⇒ `source:"platform"` 且**无 `name`/`mime`/`size`/`url`**，只保留 🎤 标记。 + **`documents` 数组语义（核心）**： - 形状：`{name,mime,size,chars,truncated,status,reason?}`，**≤5 条/回合**，顺序 = 客户端发送顺序。 @@ -497,6 +553,34 @@ - WS 语音回合（`voice_input`）：**与文本回合走同一条路**（进编排器 → 落库 → 流式 → 跨端同步 → 忙碌/排队语义一致）。转写文本落库为用户消息、助手回复落库；`deviceId`/`clientMsgId` 与 `chat` 帧同形。 - `voice_output` 在**该回合结算时**才定向回发起连接（可能晚于若干状态帧，甚至由续跑回合或被 steer 注入的那一回合产生）。空正文 / TTS 失败/降级都走 `provider` 降级信号（`silent` 等），**不把 `stopReason` 当语音内容**；连接断开不补投，客户端带回同一 `clientMsgId` 可安全重试。 +**入站语音的音频副本与播放端点（v0.67 登记，尚未实现）**： + +- **音频副本何时产生**：渠道适配器入站拿到语音字节后，转写在**流水线最前端**归一（见上），而**落盘在闸门之后** —— 被会话解析 / 黑白名单 / 最小打扰拦下的语音**盘上不留任何文件**（与 IM 附件同一纪律）。落盘 = 内容寻址（`sha256(bytes)[:32] + ext`，同字节同扩展名天然去重），产出该消息的 `voice` 引用（DTO 见 §4.4）。 +- **播放端点 `GET /api/v1/media/{name}`**（**owner/admin，必须 Bearer**，与 `GET /api/v1/documents/{name}` 同一套门）： + +| 项 | 口径 | +|---|---| +| 名字形态 | 32 位小写十六进制主名 + **音频白名单**扩展名（**10 项**：`.wav` `.mp3` `.aac` `.ogg` `.oga` `.opus` `.m4a` `.webm` `.flac` `.amr`）；`..` 等路径穿越全形态拒绝 | +| `Content-Type` | 按**存储名的扩展名**映射，**恒为 `audio/*`**（`.wav→audio/wav`、`.mp3→audio/mpeg`、`.aac→audio/aac`、`.ogg`/`.oga`/`.opus→audio/ogg`、`.m4a→audio/mp4`、`.webm→audio/webm`、`.flac→audio/flac`、`.amr→audio/amr`）。**不查库、不重新嗅探**（扩展名与字节在**保存时**已成对裁决） | +| `Content-Disposition` | `inline; filename=""` —— 与文档读侧的 `attachment` **刻意相反**（音频要被播放器消费；因下发类型恒 `audio/*` + `nosniff`，内联不构成文档侧那类 XSS 面） | +| 其他响应头 | `X-Content-Type-Options: nosniff`；`Accept-Ranges: bytes`；`Cache-Control: private, max-age=86400, immutable`；**不设 `ETag`**（不自造语义，条件请求走 `Last-Modified`） | +| 状态码 | `200` 全量 / `206 Partial Content`（`Range: bytes=0-`、`bytes=N-M`、`bytes=-N`，**由 Go 标准库 `http.ServeContent` 处理 —— 客户端不要自研 range 解析**）/ `304 Not Modified`（条件请求）/ `404 media_not_found`（**名字形态非法 / 路径穿越 / 文件不存在三者同一响应**，不泄露「存在与否」以外的信息）/ `401` / `403`（中间件） | +| `HEAD` | 支持（`GET` 模式同时匹配 `HEAD`）⇒ 客户端可先探长度再决定要不要整段拉 | +| ⚠️ `416` | **不是 JSON 信封**：`Range` 语法非法或范围不可满足 ⇒ 标准库直写 `text/plain` + `Content-Range: bytes */`，**不套** `{"error":{…}}`。唯一例外：**空文件** + 范围不可满足 ⇒ 忽略 `Range` 回 `200`（标准库的特别处理） | +| 日志 | 404 **不记**错误日志（可预期的输入问题）；不记任何字节内容 | + +- **三条读侧路的边界（别混）**： + +| 端点 | 鉴权 | Disposition | 名字形态 | 语义 | +|---|---|---|---|---| +| `GET /api/v1/files/{name}` | **无**（能力 URL） | `inline`（按图 MIME） | 128-bit 随机名 + 图片扩展名 | 图片，给 `` / provider 直接吃 | +| `GET /api/v1/documents/{name}` | **Bearer owner/admin** | `attachment` | 32 hex + **文档白名单**（23 项） | 文档，**永不内联渲染** | +| `GET /api/v1/media/{name}`（v0.67 登记） | **Bearer owner/admin** | `inline; filename=…` | 32 hex + **音频白名单**（10 项） | 语音副本，供播放器消费 | + +- ⚠️ **音频 URL 不能直接贴进 `