diff --git a/Docs/api-client.md b/Docs/api-client.md index 43ccaca..a2a7b9e 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -86,7 +86,7 @@ | U5 | POST | `/api/v1/audio/transcribe` | **owner** | 200 / 400 / 500 | STT。body `{audio,format?,deviceId?}` → `{data:{text, provider?}}`。`provider` 只在结果为空/降级时出现（如 `"silent"`）。空 audio → `400`；未接语音 → `500 voice_unavailable`；识别失败 → `500 stt_failed`。**owner-only + 审计**。 | | U6 | POST | `/api/v1/audio/speech` | **owner** | 200 / 400 / 500 | TTS。body `{text,voice?,format?,instruction?}` → **`200` 原始音频字节**（`Content-Type: audio/`，**非 JSON 信封**）。空 text → `400`；未接语音 → `500 voice_unavailable`；失败 → `500 tts_failed`；静默空音频 → `500 tts_empty` 且响应头 `X-Voice-Provider: silent`。**owner-only + 审计**。 | | U7 | POST | `/api/v1/audio/voice-clone` | **owner** | 200 / 400 / 500 | 声音复刻建音色。body `{url,prefix?}` → `{data:{voiceId}}`。参考 URL **绝不进日志/审计**。空 url → `400`；失败 → `500 voice_clone_failed`。 | -| U8 | POST | `/api/v1/upload` | owner/admin | 201 / 400 / 413 / 415 / 500 | **图片上传**，`multipart/form-data` 字段 `file`（光栅图，5 MiB）→ `{data:{url,size,mime,name}}`。`url` 是**绝对同源 URL**，可直接作 `chat.image`。嗅探裁决 png/jpeg/gif/webp/bmp（拒 SVG/HTML）；原始文件名丢弃，用 128-bit 随机名。缺文件/空文件 `400`、超限 `413`、非白名单 `415`。**带审计**。 | +| U8 | POST | `/api/v1/upload` | owner/admin | 201 / 400 / 413 / 415 / 500 | **图片上传**，`multipart/form-data` 字段 `file`（光栅图，**单文件字节 ≤ 5 MiB**，即 `maxUploadBytes = 5 << 20`）→ `{data:{url,size,mime,name}}`。`url` 是**绝对同源 URL**，可直接作 `chat.image`（该路径的 5 MiB 在**上传时**定死，与 `chat.image` 的字符长度判据无关，见 [§4.5](#45-图片--文档--语音链路)）。嗅探裁决 png/jpeg/gif/webp/bmp（拒 SVG/HTML）；原始文件名丢弃，用 128-bit 随机名。缺文件/空文件 `400`、超限 `413 payload_too_large`、非白名单 `415 unsupported_media_type`。**带审计**。 | | U9 | GET | `/api/v1/files/{name}` | **无需**（能力 URL） | 200 / 404 | 上传文件读取。`name` 仅接受「32 位小写 hex + 白名单扩展名」；路径穿越全形态拒绝。**GET 不鉴权**是该 URL 为 128-bit 随机能力地址（``/provider 无法带 token）；任何持有 URL 者可取，勿外泄。 | | U10 | POST | `/api/v1/documents` | owner/admin | 201 / 200 / 400 / 413 / 415 / 500 | **文档上传**，`multipart/form-data` 字段 `file`。首次 `201 {data:{name,url,mime,size,sha256,deduped:false}}`；**同字节同扩展名重复上传 → `200` + 同 `name` + `deduped:true`**（可当成功）。单文件上限 `CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB，`≤0` 用默认）。见 [§4.5](#45-图片--文档--语音链路)。 | | U11 | GET | `/api/v1/documents/{name}` | **owner/admin（必须 Bearer）** | 200 / 404 | 文档读取。与图片读侧**刻意相反**（必须鉴权）。响应 `Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`，**永不内联渲染**。名字非法/穿越/不存在统一 `404 document_not_found`。 | @@ -373,7 +373,7 @@ | 状态 | code（示例） | 场景 | |---|---|---| -| 400 | `bad_request`、`image_too_large`、`too_many_documents` | 请求体/字段非法、图片超限、附件超条数 | +| 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） | @@ -468,10 +468,15 @@ **图片**： -- 两条入口：`POST /api/v1/upload`（multipart，5 MiB）取**绝对同源 URL**；或 `chat.image` 直接内联 base64 `data:` URI / http(s) URL。 -- `chat.image` 内联上限 = **解码后 5 MiB**（同上传口径；base64 字符上限 ≈ `ceil(n/3)*4 + 64`），超限 `400 image_too_large`（文案指路先上传）。上限来自 `CHAT_IMAGE_MAX_BYTES`，**只能收紧、不能放宽**（钳到 vision 解码层硬顶）。 -- **WS `chat` 帧到不了这条判定**：读上限 4096 字节/帧，超限由传输层断连 ⇒ **WS 上发真实图片必须「上传 + URL」**。 -- 视觉 URL 由服务端取回内联为 `data:` URI 再交 provider；类型裁决靠**字节嗅探**（HTML/SVG/判不定 → 明确报错，绝不静默当 PNG）。**主模型能否收图**看生效组的 `multimodal`（见 §5），与 `LLM_VISION_MODEL`/`LLM_OCR_MODEL` 无关。 +- 两条入口：`POST /api/v1/upload`（multipart，**单文件字节 ≤ 5 MiB**）取**绝对同源 URL**；或 `chat.image` 直接内联 base64 `data:` URI / http(s) URL。 +- ⚠️ **按形态写清（v0.66 补充说明，更正旧措辞「解码后 5 MiB」）**：`chat.image` 的**唯一入口判据是 `image` 字符串长度，不是「解码后字节数」** —— `POST /api/v1/chat` 的 `handleChat` 在**解码 / 落库 / 入模型之前**调用 `checkChatImageSize(image, limit)`（`internal/services/gateway/rest.go`），判定就是 `len(image) <= limit`；`limit` = `CHAT_IMAGE_MAX_BYTES`（默认 `5242880`）按 base64 膨胀 4/3 换算出的**字符**上限 = `ceil(n/3)*4 + 64`，默认 **6990572 字符**（那 64 字符是 `data:` 前缀余量）。**超一字符**即 `400 {"error":{"code":"image_too_large"}}`（`message` 带上限与本次长度，文案指路先上传）。 + - **base64 / `data:` URI 形态**：受上述 **6990572 字符**约束，**等价于解码后约 5 MiB**。`data:` 前缀越长，留给载荷的字符越少；**裸 base64**（无前缀）在恰界（正好 6990572 字符）时解码 ≈ `5242929` 字节 = **5 MiB + 49 字节** ⇒ **「解码后 5 MiB」是换算口径**，逐字节的硬判据在代码里**不存在**（视觉解码层的兜底预检 `vision/limits.go` 同样是**按字符串长度**判 `MaxInlineImageChars`）。要与「一张图 5 MiB」严格对齐，客户端按 `ceil(n/3)*4 + 64` 自查即可，不要按解码字节数试探。 + - **http(s) URL 形态**（含 `/api/v1/upload` 返回的 `/api/v1/files/<32hex>.`）：判据与形态无关（任何**短于 6990572 字符**的串都通过），而正常 URL 只有约 60 字符 ⇒ **实践中 `image_too_large` 不会因 URL 形态触发**。URL 形态真正的天花板在**视觉取回层**：`internal/runtime/multimodal/vision/image.go` 的 `maxFetchedBody = maxImageBytes = 50 << 20`（**50 MiB**；其**视觉/OCR 工具路径**下同源 upload 产物优先走本地直读 `readFile`，用同一常量，而**主模型直收路径**仍走一次 HTTP 自取），另有 **30 s** 取回超时。⚠️ 该 50 MiB 是 `io.LimitReader` 的**截断**上限 —— **超出部分被静默丢弃、不返回错误** ⇒ 客户端**不要**把「服务端会拒绝超大 URL 图」当契约，也不要把 50 MiB 当成能用满的额度。 + - **upload 形态**：`POST /api/v1/upload` 自带 **5 MiB** 单文件硬上限（`maxUploadBytes = 5 << 20`；超限 `413 {"error":{"code":"payload_too_large"}}`）⇒ 经 upload 拿到的同源 URL 图，有效上限仍是 **5 MiB**，在**上传那一刻**定死，与本接口的字符串长度判据无关。 +- 上限来源 `CHAT_IMAGE_MAX_BYTES`：`≤0` = 用默认（**不存在「禁用上限」的取值**）；**只能收紧、不能放宽**（钳到 vision 解码层硬顶 `vision.MaxInlineImageBytes` = 5 MiB）。 +- `data:` 前缀与类型嗅探**都不参与**这个体积判据：前缀只通过那 64 字符余量影响能塞多少；类型裁决（**字节嗅探**为唯一裁决权；HTML/SVG/判不定 → 明确报错，绝不静默当 PNG）发生在**视觉层**，属回合内错误，**不是**入口 `400`。 +- **WS `chat` 帧到不了这条判定**：WS 上行（`streamChat`）**没有任何图片体积校验**，读上限 4096 字节/帧由传输层直接断连 ⇒ **WS 上发真实图片必须「上传 + URL」**。 +- 视觉 URL 由服务端取回内联为 `data:` URI 再交 provider。**主模型能否收图**看生效组的 `multimodal`（见 §5），与 `LLM_VISION_MODEL`/`LLM_OCR_MODEL` 无关。 **文档**： @@ -504,6 +509,7 @@ - `sessionId` 省略 → `"web"`。 - `deviceId`：客户端端标识（如 `web:chrome:a1b2c3`），随消息落库。 - `mode`：行为模式（如 `chat`/`code`/`home`/…），随该回合落库；缺省回落 `chat`。 +- `image`：base64 `data:` URI、裸 base64 或 http(s) URL。**上限按形态不同**（判据是**字符串长度**，不是解码后字节），见 [§4.5](#45-图片--文档--语音链路)。 - `stream`：仅 REST 用，见下。 **同步（非 `stream`）响应面**： @@ -516,6 +522,7 @@ | 忙、显式并行且照准 | `202` | `{data:{parallel:true,turnId:"turn-…"}}`（**拿不到同步 reply**；文本经 WS 流式到达） | | 队列满 | `409` | `{error:{code:"chat_busy"}}` | | 空回合（无 text/image/documents） | `400` | `{error:{code:"bad_request"}}` | +| **`image` 字符串超长**（**仅 base64 / `data:` 形态会触发**；URL 形态不会） | `400` | `{error:{code:"image_too_large"}}` —— 在解码/落库/入模型**之前**拒；上限 = `CHAT_IMAGE_MAX_BYTES` 换算出的**字符**上限（默认 **6990572 字符**），见 §4.5 | | 未接 loop | `500` | `{error:{code:"chat_unavailable"}}` | | 回合内部报错 | `500` | `{error:{code:"chat_failed"}}` | @@ -585,7 +592,7 @@ | `PORT` | `8080` | 网关唯一端口（含 REST/WS/admin） | | `HOST` | `0.0.0.0` | 监听地址 | | `ADMIN_PATH` | `admin` | 管理面板**前端路由前缀**（`/`+值）。**不是 REST 契约**：`/api/v1/admin/*` 一律不藏。非法值回退 `/admin`；路径形如面板入口但前缀不符 → `404` | -| `CHAT_IMAGE_MAX_BYTES` | `5242880`（5 MiB） | `chat.image` 解码后字节上限（`≤0` 用默认；**只能收紧**，钳到 vision 硬顶） | +| `CHAT_IMAGE_MAX_BYTES` | `5242880`（5 MiB） | `chat.image` **字符串长度**上限的换算源（**单位是字节**，按 base64 4/3 膨胀换成字符：`ceil(n/3)*4 + 64`，默认 **6990572 字符**；只作用于 **base64 / `data:` 形态**，URL 形态不走这道检查）。`≤0` = 用默认；**只能收紧**，钳到 vision 硬顶（见 §4.5） | | `CHAT_DOCUMENT_MAX_BYTES` | `20971520`（20 MiB） | `POST /documents` 单文件上限（`≤0` 用默认；与图片上限**刻意解耦**） | | `AUTH_REFRESH_TTL` | `720h` | refresh token 有效期（access 固定 24h） | | `AUTH_REFRESH_ROTATE_DISABLED` | `false` | `true` = 关闭 refresh 单次轮换 | @@ -649,6 +656,7 @@ - ⚠️ **本版更正 v0.65 的两处陈述（文档写错，不是代码变更）**： - **`thinking` 口径**：本文档曾写「历史思维链只有 `GET /sessions/{id}/messages`（owner/admin）返回」—— **与实现不符**。`history.Message.Thinking` **全仓没有任何写入者**（`loop.Result` 无该字段、`finalizeAnthropicStream` 直接丢弃思考文本）⇒ 该键在**所有**读取面**恒缺席**；思维链的**唯一出口**是实时 `thinking.*` 帧（owner/admin）。已在 §3.4.4、§4.4 按实测改写。 - **v0.65 §7 的「未实现」清单**：`turn_begin` / `steer_ack.turnId` / `interrupt.turnId` / `chat_messages.turn_id` / 写类工具文件级互斥 —— **现已全部实现并上线**（`c0dc435`、`d64b26d`+`d804c4e`、`354b08a`），§7 已相应改写。 +- ⚠️ **v0.66 补充说明（描述性更正，不动形状/阈值，不升版本号）**：**`chat.image` 的体积判据是「字符串长度」而不是「解码后字节」** —— 旧措辞「内联上限 = 解码后 5 MiB」只对 **base64 / `data:` 形态**成立，且它本身是**换算口径**（`len(image) <= 6990572` 字符，见 §4.5）。**URL 形态不触发 `image_too_large`**（URL 串约 60 字符，必然通过）：其天花板在视觉取回层的 **50 MiB**（`io.LimitReader`，**超出静默截断**、不报错）；**`POST /api/v1/upload` 自身是 5 MiB 字节硬限**（`413 payload_too_large`）。四处已按实现写清（§4.5 图片、§4.6 响应面、§5 环境变量表、U8 行 + 错误码表）。**无端点 / 帧 / 字段形状变更，无默认值变更**。 ### v0.65（上一版）