docs(api): 契约 v0.61 —— 登记 .pdf 文本层与成对嗅探裁决（修 B1 落地后的契约漂移）
- 漂移：B1（f82c76d）把白名单 22→23 项、嗅探改为 (扩展名, 嗅探) 成对裁决，而 Docs 仍写「22 项 / 仅放行 text/plain」。本切片只改 Docs 两个文件把口径改准。
- 登记要点：白名单 23 项（22 文本+ .pdf）；成对裁决双向拒（HTML/文本改名 .pdf ⇒ 415；PDF 改名 .txt ⇒ 415）；读侧真 PDF 下发 application/pdf 但仍 attachment+nosniff（不可内联）；文本层抽正文、扫描件诚实拒绝（unreadable，文案含「需要 OCR，当前未做」）、加密/损坏可区分；安全阀 5000 页 / sidecar 8 MiB；ExtractorVersion documents/v3 ⇒ 旧 sidecar 一次性重抽（客户端可观察 chars/truncated 重算）。三档标注：行为变更（.pdf 从 415 变为可上传可读 + 裁决收紧）+ 纯增量（第 23 项）。
- 未发明任何未实现行为：OCR / PDF 写 / Office 明确写「未做」；v0.59 历史条目里的「22」加注「⚠️ 历史值；v0.61 起为 23 项」。
- 主会话复核：grep 22 项 仅剩历史 changelog 一处且已标注；v0.61 在 api-client 12 处、api-reference 13 处；给出「项 → 文档位置 → 代码证据（文件:行）」对照表逐条核对。
- 子代理如实报告的结构隐患（已登记）：api-client 有**两套平行变更记录**（§1.2 末的大块 + §5 列表）易再漂移；api-reference 无自己的版本条目节。
This commit is contained in:
AskaEth committed
1 parent
f82c76df27
commit
c3339a5d07
2 files changed
+35
-32
No files matched your search
+17
-16
@@ -1,6 +1,6 @@
|
||||
# Cyrene v2 后端 API 参考（api-reference.md）
|
||||
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.60`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.61`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。
|
||||
> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**§1 的 REST 端点表已于 2026-10-04 按 `internal/services/gateway/routes.go` 逐条核对并补登记**（补上此前缺失的 `POST /auth/refresh`、`POST /auth/logout`、`POST /upload`、`GET /files/{name}`、三支 `/audio/*`、`GET /admin/llm/catalog`、`GET /admin/observability/logs`、`GET /admin/notifications`、`GET /admin/plugins/installed`、`GET|PUT /admin/owner-profile`、`POST /admin/automations/reminders`）。**仍未补全的是 WS 事件帧清单**：§6.4 自述「并非全表」，`DevDocs/audit/00-总览.md` §4④ 列出的 `session_read` / `message_edited` / `message_deleted` 等仍未逐行登记。
|
||||
> **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。
|
||||
@@ -14,7 +14,7 @@
|
||||
- **响应统一信封**：
|
||||
- 成功：`{"data": <payload>}`（HTTP 200 / 201 / 202 / 204）。
|
||||
- 失败：`{"error": {"code": <string>, "message": <string>}}`（HTTP 400/401/403/404/409/500/501 等）。
|
||||
- **错误码**：业务错误带稳定字符串 `code`（如 `unauthorized` / `not_found` / `bad_request` / `chat_busy` / `not_implemented`，**v0.56** 新增的 `image_too_large`（`chat.image` 超 5 MiB）与 `chat_dispatch_failed`（流式兜底派发失败），**v0.59** 新增的文档四码 `unsupported_media_type`(415) / `document_too_large`(413) / `document_not_found`(404) / `too_many_documents`(400)），便于客户端分支；`message` 面向人读。
|
||||
- **错误码**：业务错误带稳定字符串 `code`（如 `unauthorized` / `not_found` / `bad_request` / `chat_busy` / `not_implemented`，**v0.56** 新增的 `image_too_large`（`chat.image` 超 5 MiB）与 `chat_dispatch_failed`（流式兜底派发失败），**v0.59** 新增的文档四码 `unsupported_media_type`(415) / `document_too_large`(413) / `document_not_found`(404) / `too_many_documents`(400)），便于客户端分支；`message` 面向人读。**v0.61**：文档 **415** 的判定改为「扩展名白名单（**23 项**，含 `.pdf`）∧ 字节嗅探」的**成对裁决**（HTML/纯文本改名成 `.pdf`、或 PDF 改名成 `.txt` 都回 `415`，见 §3.8）。
|
||||
- **CORS**：`Access-Control-Allow-Origin` 为配置的 `ALLOWED_ORIGINS` 白名单（`*` 时放开）；`Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`；`Allow-Headers: Authorization, Content-Type, X-API-Version`；`Access-Control-Expose-Headers: X-Voice-Provider`（跨域浏览器可读语音降级信号头）；`Max-Age: 600`。`OPTIONS` 预检直接回 `204`。同源/无 Origin 请求放行。**注意：`X-API-Version` 仅作**advisory**惯例头（见 §0.2）——CORS 已放行但它**不参与服务端版本协商**，服务端当前不校验、不据此改变行为。**
|
||||
- **请求日志**：每个请求由 `logging` 中间件记录一行（method/path/status/duration_ms），并计入可观测性指标。panic 由 `recover` 中间件兜底为 `500 {error:{code:internal,...}}`，不崩溃进程。
|
||||
- **超时**：WS 连接 ping 周期 54s、pong 等待 60s、写超时 10s；读上限 4096 字节/帧。
|
||||
@@ -46,7 +46,7 @@
|
||||
### 0.3 上传 / 媒体（重要确认）
|
||||
|
||||
- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；**env-only 部署（无有效 `models.json`，走 `.env` 合成组）用 `LLM_MULTIMODAL`（默认 `false`，v0.58）声明这个能力**——它才是该组 `multimodal` 的 env 等价物，且**非 bool 值启动报错**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56，2026-10-04 起可配）**：`chat.image` 解码后默认 **5 MiB**（与 `POST /api/v1/upload` 同口径；换算成字符串上限 `ceil(n/3)*4 + 64` 字符，已含 data: 前缀余量），超限 `400 {"error":{"code":"image_too_large",...}}`；字节上限由 `.env` 的 **`CHAT_IMAGE_MAX_BYTES`** 配置（默认 `5242880`；**≤0 视为「用默认」**，不存在「禁用上限」的取值），换配置时错误文案里的 MiB 数字会自动跟随；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
|
||||
- **文档存储端点已存在（v0.59）**：`POST /api/v1/documents`（owner/admin + 审计 `document.upload`，multipart 字段 `file`，上限 `CHAT_DOCUMENT_MAX_BYTES` 默认 **20 MiB**）与 `GET /api/v1/documents/{name}`（**必须 Bearer owner/admin**，`attachment` + `nosniff`，与图片读侧刻意相反）。**类型裁决 = 字节嗅探（唯一）∧ 扩展名白名单（22 项）**，`mime` 为嗅探基类型（`data.json` → `text/plain`）、`url` 为**相对路径**；同字节同扩展名重复上传回 `200` + 同一 `name` + `deduped:true`。回合引用走 `chat` 的可选 `documents:[{name}]`（**≤5 条、只收服务端存储名**）；历史/实时 DTO 是 **`documents` 数组**（元素 `{name,mime,size,chars,truncated,status}`，无附件时省略该键）。契约见 §3.8 与 api-client §1.2。
|
||||
- **文档存储端点已存在（v0.59；v0.61 纳入 PDF 文本层）**：`POST /api/v1/documents`（owner/admin + 审计 `document.upload`，multipart 字段 `file`，上限 `CHAT_DOCUMENT_MAX_BYTES` 默认 **20 MiB**）与 `GET /api/v1/documents/{name}`（**必须 Bearer owner/admin**，`attachment` + `nosniff`，与图片读侧刻意相反）。**类型裁决 = 字节嗅探（唯一）∧ 扩展名白名单（23 项，含 `.pdf`）**，**v0.61 起为成对裁决**：纯文本类嗅探基类型必须为 `text/plain`、`.pdf` 必须为 `application/pdf`（HTML 改名成 `.pdf`、或 PDF 改名成 `.txt` 均 `415`）；`mime` 为嗅探基类型（`data.json` → `text/plain`，真 PDF → `application/pdf`）、`url` 为**相对路径**；同字节同扩展名重复上传回 `200` + 同一 `name` + `deduped:true`。**PDF 文本层抽正文（`status:"extracted"`）；扫描件/图片型 PDF 无文本层 ⇒ 诚实拒绝 `status:"unreadable"`（需 OCR，当前未做）；加密与损坏可区分；Office 仍诚实拒绝**。回合引用走 `chat` 的可选 `documents:[{name}]`（**≤5 条、只收服务端存储名**）；历史/实时 DTO 是 **`documents` 数组**（元素 `{name,mime,size,chars,truncated,status}`，无附件时省略该键）。契约见 §3.8 与 api-client §1.2。
|
||||
- **REST 语音端点已存在**：`POST /api/v1/audio/transcribe`（STT）、`POST /api/v1/audio/speech`（TTS）、`POST /api/v1/audio/voice-clone`（声音复刻），均 owner-only + 审计，绕开 WS 4KB 帧限。语音也可走 WS `voice_input`（上行）/`voice_output`（下行）；**v0.59 起语音回合进会话编排器**（落库 / 流式 / 跨端 / 忙时排队），`voice_output` 增 `sessionId`/`deviceId?`、`voice_input` 增 `clientMsgId?`，见 §6.3/§6.4 与 api-client §3.15。
|
||||
- 管理端导入知识文档（RAG）走 JSON body 文本（`POST /api/v1/admin/rag`），非文件上传。
|
||||
|
||||
@@ -85,8 +85,8 @@
|
||||
| 16 | POST | `/api/v1/audio/transcribe` | **owner** | 200 | 语音转写(STT，绕开 WS 4KB 帧限)；静音/空结果时响应带 `provider` | M17 |
|
||||
| 17 | POST | `/api/v1/audio/speech` | **owner** | 200 | 语音合成(TTS)；响应头 `X-Voice-Provider` 报告实际提供方（降级可见） | M17 |
|
||||
| 18 | POST | `/api/v1/audio/voice-clone` | **owner** | 200 | 声音复刻（百炼 create_voice） | M17 |
|
||||
| 19 | POST | `/api/v1/documents` | owner\|admin | 201/200/400/413/415 | **文档上传（v0.59）**：multipart 字段 `file`（上限 `CHAT_DOCUMENT_MAX_BYTES`，默认 20 MiB）→ `201 {name,url,mime,size,sha256,deduped:false}`；**同字节同扩展名重复上传 → `200` + 同一 `name` + `deduped:true`**；字节嗅探（唯一裁决）∧ 扩展名白名单（22 项），`mime` 为嗅探基类型、`url` 为**相对路径**；错误码 `400 bad_request`/`413 document_too_large`/`415 unsupported_media_type`（见 §3.8） | M-S（design/24 S1） |
|
||||
| 20 | GET | `/api/v1/documents/{name}` | **owner\|admin** | 200/404 | **文档读取（v0.59）**：**必须带 Bearer**（与图片读侧免鉴权能力 URL 刻意相反）；`name` = 32 位小写 hex + 白名单扩展名，路径穿越全形态拒绝；`Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`；嗅探不出放行类型 → `application/octet-stream`；统一 `404 document_not_found`（见 §3.8） | M-S（design/24 S1） |
|
||||
| 19 | POST | `/api/v1/documents` | owner\|admin | 201/200/400/413/415 | **文档上传（v0.59；v0.61 纳入 PDF）**：multipart 字段 `file`（上限 `CHAT_DOCUMENT_MAX_BYTES`，默认 20 MiB）→ `201 {name,url,mime,size,sha256,deduped:false}`；**同字节同扩展名重复上传 → `200` + 同一 `name` + `deduped:true`**；字节嗅探（唯一裁决）∧ 扩展名白名单（**23 项，含 `.pdf`**），**v0.61 起为成对裁决**（纯文本类 → `text/plain`、`.pdf` → `application/pdf`；HTML 改名成 `.pdf`、PDF 改名成 `.txt` 均 `415`），`mime` 为嗅探基类型、`url` 为**相对路径**；错误码 `400 bad_request`/`413 document_too_large`/`415 unsupported_media_type`（见 §3.8） | M-S（design/24 S1 + §7 S6） |
|
||||
| 20 | GET | `/api/v1/documents/{name}` | **owner\|admin** | 200/404 | **文档读取（v0.59；v0.61 增 PDF MIME）**：**必须带 Bearer**（与图片读侧免鉴权能力 URL 刻意相反）；`name` = 32 位小写 hex + 白名单扩展名，路径穿越全形态拒绝；`Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`；嗅探不出放行类型 → `application/octet-stream`（真 PDF 按成对裁决如实下发 `application/pdf`，仍永不可内联）；统一 `404 document_not_found`（见 §3.8） | M-S（design/24 S1 + §7 S6） |
|
||||
|
||||
### 1.3 管理后台（`/api/v1/admin/*`）
|
||||
|
||||
@@ -490,7 +490,7 @@ curl -s -X POST http://<host>:8080/api/v1/sessions/web/read \
|
||||
# => {"data":{"platforms":[...],"moods":[...],"modes":[...],"unknown":"display-raw"}}
|
||||
```
|
||||
|
||||
### 3.8 POST /api/v1/documents · GET /api/v1/documents/{name}（v0.59，design/24 §3/§6）
|
||||
### 3.8 POST /api/v1/documents · GET /api/v1/documents/{name}（v0.59，v0.61 增 PDF 文本层；design/24 §3/§6 + §7 S6）
|
||||
|
||||
> **一句话**：文档 = 内容寻址存储 + 服务端抽取 + 清单/正文注入。**读侧要 Bearer**（与图片读侧「随机名即能力 URL」刻意相反）；客户端只要这两个端点 + `chat` 的 `documents` 字段。权威口径与边界表见 api-client §1.2。
|
||||
|
||||
@@ -505,13 +505,14 @@ curl -s -X POST http://<host>:8080/api/v1/sessions/web/read \
|
||||
|
||||
首次 `201`（`deduped:false`）；**同字节同扩展名重复上传 → `200` + 同一个 `name` + `deduped:true`**（落盘名 = `sha256(bytes)[:32] + ext`，**内容寻址**，盘上只留一份；元数据行 `ON CONFLICT(name) DO NOTHING` —— 首次的 uploader / 时间戳是权威）。客户端可把 `200` 当成功处理。
|
||||
- **落盘位置**：`<DataDir>/uploads/documents/`（目录 0700、文件 0600）；客户端原始文件名**只用来取扩展名**，永不参与路径。
|
||||
- **类型裁决（唯一裁决权 = 字节嗅探）**：
|
||||
- **扩展名白名单（deny-by-default，22 个）**：`.txt .md .markdown .csv .tsv .json .jsonl .yaml .yml .log .ini .cfg .toml .go .ts .tsx .java .c .h .cpp .rs .sql`；
|
||||
- **字节嗅探**（`http.DetectContentType`）的**基类型必须恰为 `text/plain`**；
|
||||
- 二者是**合取**：`.js` / `.py` 即便嗅探为文本也拒（不在白名单）；改扩展名也换不了类型；
|
||||
- **类型裁决（唯一裁决权 = 字节嗅探；v0.61 起 = 成对裁决）**：
|
||||
- **扩展名白名单（deny-by-default，23 个）**：`.txt .md .markdown .csv .tsv .json .jsonl .yaml .yml .log .ini .cfg .toml .go .ts .tsx .java .c .h .cpp .rs .sql`，**外加 `.pdf`（v0.61 新增，第 23 项）**；
|
||||
- **字节嗅探（`http.DetectContentType`）与扩展名成对判定**（`internal/runtime/documents/store.go` 的 `ContentAllowed`，写侧与读侧同一份）：**纯文本类**嗅探基类型必须恰为 **`text/plain`**；**`.pdf`** 必须恰为 **`application/pdf`**；
|
||||
- 二者是**合取**：`.js` / `.py` 即便嗅探为文本也拒（不在白名单）；改扩展名也换不了类型，且自 v0.61 起**双向**：**HTML/纯文本改名成 `.pdf` ⇒ `415`**（嗅探不是 PDF）、**PDF 改名成 `.txt` ⇒ `415`**（PDF 字节也只收在 `.pdf` 名下）；
|
||||
- **明令拒绝**：`text/html`、`image/svg+xml` 与 XML、`application/zip` 及封装（docx/xlsx）、可执行/脚本（exe/dll/bat/cmd/ps1/js/mjs/sh/py）、判不定者。
|
||||
- 响应里的 **`mime` 是嗅探所得基类型**（去参数），故 `data.json` → `text/plain`（**不是** `application/json`）；**`url` 是相对路径**（读侧要 Bearer，绝对化没有意义）。
|
||||
- **错误**：`400 bad_request`（缺 `file` 部件 / 空文件 / 非 multipart）；`413 document_too_large`（文件或信封超限，文案带生效上限字节数）；`415 unsupported_media_type`（扩展名或嗅探任一不过，文案同时点明两条口径）；`401` / `403`（未认证 / 角色不足）。**审计**：成功 `document.upload`+`ok`、失败 +`error`（成对，不遗漏）。
|
||||
- 响应里的 **`mime` 是嗅探所得基类型**（去参数），故 `data.json` → `text/plain`（**不是** `application/json`）、真 PDF → `application/pdf`；**`url` 是相对路径**（读侧要 Bearer，绝对化没有意义）。
|
||||
- **PDF 文本层（v0.61，切片 B1）**：**文本层 PDF 抽正文**（`Tj`/`TJ`/`'`/`"` 文本算子，页间以换行相接）⇒ DTO `status:"extracted"`；**扫描件/图片型 PDF（无文本层）⇒ 诚实拒绝 `status:"unreadable"`**，原因文案含「这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）」，**绝不假装成功、也绝不返回空正文**（`ErrNoTextLayer`）；**加密**（`ErrPDFEncrypted`）与**损坏/截断**（`ErrPDFDamaged`）是**可区分**的两类失败。安全阀：单份最多 **5000 页**、sidecar 正文 **≤8 MiB**（撞上即 `truncated`）。抽取器版本内部升到 **`documents/v3`** ⇒ **旧 sidecar 一次性重抽**（同一份旧附件的 `chars`/`truncated` 会在某次回合后重算；旧 PDF 若是文本层 PDF 会从 `unreadable` 变为 `extracted`）。**未做**：OCR/扫描件栅格化、PDF 写/生成、`.docx`/`.xlsx` 等 Office（仍诚实拒绝）。
|
||||
- **错误**：`400 bad_request`（缺 `file` 部件 / 空文件 / 非 multipart）；`413 document_too_large`（文件或信封超限，文案带生效上限字节数）；`415 unsupported_media_type`（**扩展名白名单与字节嗅探的成对裁决**任一不过，文案同时点明两条口径）；`401` / `403`（未认证 / 角色不足）。**审计**：成功 `document.upload`+`ok`、失败 +`error`（成对，不遗漏）。
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://<host>:8080/api/v1/documents \
|
||||
@@ -524,7 +525,7 @@ curl -s -X POST http://<host>:8080/api/v1/sessions/web/read \
|
||||
|
||||
- **鉴权**：**必须带 `Authorization: Bearer <JWT>`**（`owner`/`admin`）；无 token → `401`，角色不足 → `403`。这是与 `GET /api/v1/files/{name}` 的**关键差异**——文档摄取在服务端完成，不需要被 `<img>` / provider 直接消费，因此不开「名字即凭据」的免鉴权读侧，也不放开内联服务 HTML/SVG 的口子。
|
||||
- **`name` 形态**：`32 位小写十六进制 + '.' + 白名单扩展名`；**路径穿越全形态拒绝**（`..` / `%2e%2e` / `%2f` 等，含 ServeMux 清理前的守卫）。
|
||||
- **响应头**：`Content-Type` = **读时重新嗅探**的基类型（嗅不出放行类型 → `application/octet-stream`）；`Content-Disposition: attachment; filename="<name>"`；`X-Content-Type-Options: nosniff`；`Cache-Control: private, max-age=86400, immutable`（内容寻址 ⇒ 名字变则内容变）；支持 Range。
|
||||
- **响应头**：`Content-Type` = **读时重新嗅探**的基类型（**同一对裁决**：纯文本类 → `text/plain`、**真 PDF 如实下发 `application/pdf`**、嗅不出放行类型 → `application/octet-stream`）；`Content-Disposition: attachment; filename="<name>"`；`X-Content-Type-Options: nosniff`；`Cache-Control: private, max-age=86400, immutable`（内容寻址 ⇒ 名字变则内容变）；支持 Range。⚠️ **PDF 也永不内联**：`attachment` + `nosniff` 一字未变。
|
||||
- **错误**：`404 document_not_found` —— **名字非法 / 路径逃逸 / 文件不存在三种情况同一响应**（不泄露「是否存在」以外的信息）。
|
||||
|
||||
```bash
|
||||
@@ -1401,7 +1402,7 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
| 404 | `not_found` / `document_not_found`(v0.59) | 资源不存在（文档：名字非法 / 路径穿越 / 文件不存在**同一响应**） |
|
||||
| 409 | `chat_busy` / `duplicate` / `device_offline` / `needs_login` | 冲突：队列满（**REST 响应体与 WS 定向 `error` 帧同码**，v0.59/G5）/ 人格已存在 / 设备离线 / 渠道未登录 |
|
||||
| 413 | `document_too_large`(v0.59) | 文档超 `CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB），文案带生效上限字节数 |
|
||||
| 415 | `unsupported_media_type`(v0.59) | 文档类型不在白名单——**扩展名白名单（22 项）与字节嗅探的合取**任一不过 |
|
||||
| 415 | `unsupported_media_type`(v0.59；判定口径 v0.61) | 文档类型不在白名单——**扩展名白名单（23 项，含 `.pdf`）与字节嗅探的成对裁决**任一不过（HTML/纯文本改名成 `.pdf`、或 PDF 改名成 `.txt` 都走它） |
|
||||
| 500 | `internal` / `chat_failed` / `sessions_failed` / … | 服务端错误（含未注入依赖） |
|
||||
| 501 | `not_implemented` | 后端**确定未实现**（新增用户 / IoT 场景·规则 / 编辑环境变量·重启服务·检查更新 / 完整会话转录导出等）——诚实返回，不伪造成功。**注：插件安装（§5.26）、知识库删除（§1.3 #23）、主人档案保存（`PUT /api/v1/admin/owner-profile`，§1.3 #67）均已实现，不再返回 501** |
|
||||
|
||||
@@ -1426,9 +1427,9 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
|
||||
### 8.4 里程碑与未实现集合（诚实标注）
|
||||
|
||||
- **已真实实现**：登录/健康检查/聊天（同步+流式）/会话（列表/新建/删除/消息分页）/人格/**文档存储与摄取（v0.59：`POST`/`GET /api/v1/documents` + `chat.documents` + `documents` DTO + `document-read` 工具）**/**语音回合进编排（v0.59：落库 / 流式 / 跨端 / 忙时排队，`voice_output` 归属键）**/管理读（personas/sessions/memories/plugins/channels/iot/llm/users/automations/backthink/rag/observability×4：metrics/trace/audit/logs）/管理写（人格/API key/设备控制/自动化/LLM 保存·测试/渠道连接·断开·身份测试/渠道配置·删除/KOOK 面板/微信扫码/记忆添加·检索/插件安装·卸载/RAG 导入·删除/主人档案读写（`GET`/`PUT /api/v1/admin/owner-profile`，v0.51）/系统设置 4 项）。
|
||||
- **已真实实现**：登录/健康检查/聊天（同步+流式）/会话（列表/新建/删除/消息分页）/人格/**文档存储与摄取（v0.59：`POST`/`GET /api/v1/documents` + `chat.documents` + `documents` DTO + `document-read` 工具；**v0.61：PDF 文本层抽取**，白名单 23 项含 `.pdf`、成对裁决、扫描件诚实拒绝）**/**语音回合进编排（v0.59：落库 / 流式 / 跨端 / 忙时排队，`voice_output` 归属键）**/管理读（personas/sessions/memories/plugins/channels/iot/llm/users/automations/backthink/rag/observability×4：metrics/trace/audit/logs）/管理写（人格/API key/设备控制/自动化/LLM 保存·测试/渠道连接·断开·身份测试/渠道配置·删除/KOOK 面板/微信扫码/记忆添加·检索/插件安装·卸载/RAG 导入·删除/主人档案读写（`GET`/`PUT /api/v1/admin/owner-profile`，v0.51）/系统设置 4 项）。
|
||||
- **`thinking` 可达性（v0.59 口径，不改行为）**：消息体 `thinking` 字段在**实时帧**（`message_persisted`/`channel_persisted`/`message_edited`）与**握手回放**中**一律剥离**（有意默认）；**实时思维链**走 `thinking.*` 流帧（owner/admin）；**历史思维链**只有 `GET /sessions/{id}/messages`（owner/admin）返回。
|
||||
- **仍为后置 M10（返回 `501 not_implemented`，不伪造）**：新增用户（无用户表/登录）、IoT 场景与规则（无模型/存储）、编辑环境变量/重启服务/检查更新、完整会话转录导出（当前导出身份元数据）。**文档侧后置**：配额与引用计数/GC（design/24 S7）、PDF/Office 解析（S6，待裁决）、IM 侧 `msg.Media` 摄取（`channelbridge` 只取 `msg.Content`）。**已知缺口**：design/24 §6.2 的 `document_unreadable`(400) 无 REST 落点（只有 `document-read` 工具错误形态）。
|
||||
- **仍为后置 M10（返回 `501 not_implemented`，不伪造）**：新增用户（无用户表/登录）、IoT 场景与规则（无模型/存储）、编辑环境变量/重启服务/检查更新、完整会话转录导出（当前导出身份元数据）。**文档侧后置**：配额与引用计数/GC（design/24 S7）、**Office 解析（`.doc`/`.docx`/`.xls`/`.xlsx`/`.ppt`/`.pptx`/`.odt`/`.ods`/`.odp`/`.rtf`，仍诚实拒绝）**、**扫描件/图片型 PDF 的 OCR**（v0.61 已做文本层 PDF，无文本层者如实报 `unreadable`）、IM 侧 `msg.Media` 摄取（`channelbridge` 只取 `msg.Content`）。**已知缺口**：design/24 §6.2 的 `document_unreadable`(400) 无 REST 落点（只有 `document-read` 工具错误形态；客户端在 DTO 里看到的是 `documents[].status = "unreadable"`）。
|
||||
- **语义/向量增强**：`memory.search` 的 `semantic` 当前恒为 `false`——**向量索引已由组合根注入**（`cmd/cyrene/wire.go` 的 `memory.WithVectorIndex`），但**索引内当前无向量**（生产无写入），故语义打分返回空，属诚实反映而非伪造；RAG `embedded` 反映部署是否配置向量增强；**配置了增强必须真实走语义/向量路径（红线，非空壳）**。
|
||||
- **API key 认证**：`X-API-Key` **已接入鉴权**（v0.51，见 §0.1 注与 api-client.md §认证）——命中签发表即通过、一律 `owner` 级（取消 role 分级），带该头时只走 key 分支（坏 key 回 `401`、不回落 Bearer）；签发/吊销/列表同样真实生效。
|
||||
|
||||
|
||||
Reference in new issue
Block a user