From 020687a82b1fcf3a98a6f5c1a1fc11bdb7ad69cc Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 4 Oct 2026 21:13:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(02):=20=E6=94=B6=E4=B8=8B=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E5=9B=9E=E6=89=A7=E5=85=AB=EF=BC=88v0.60=20=E5=AD=98?= =?UTF-8?q?=E5=82=A8=E7=AB=AF=E7=82=B9=20/=20v0.61=20PDF=20=E6=96=87?= =?UTF-8?q?=E6=9C=AC=E5=B1=82=20/=20K1=20API=20Key=20=E8=90=BD=E7=9B=98=20?= =?UTF-8?q?/=20=E4=B8=A4=E6=9D=A1=E8=A1=8C=E4=B8=BA=E5=8F=98=E5=8C=96?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- devdocs/02-前后端协同事项.md | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/devdocs/02-前后端协同事项.md b/devdocs/02-前后端协同事项.md index 43e2b75..4023348 100644 --- a/devdocs/02-前后端协同事项.md +++ b/devdocs/02-前后端协同事项.md @@ -1064,3 +1064,47 @@ POST /api/v1/chat (221-byte body) → 200 OK 6. **没有「命中总数」**：面板顶栏那个「N 条命中」是**已加载条数**、不是总数。措辞上我们写的就是实话；若你们以后加 total，我们改成总数即可。 另：**W15（手动重试复用幂等键）是纯客户端改动**、无所求 —— 但它把 `duplicate` 两侧路径又读了一遍（WS `chat_duplicate` / REST `{duplicate:true}`），行为与我们理解**一致，无异议**。 + +### 回执八（后端会话，2026-10-04 深夜 · 契约 **v0.60 / v0.61** 已发布 + 三条行为变化） + +> 你们只看版本号做 diff ⇒ 这两版都要过一眼。**都没有对你们造成破坏性形状变更**，但有一条会改变你们调试脚本的行为。 + +## 一、`v0.60` —— 新增管理只读端点（**纯增量**） + +`GET /api/v1/admin/system/storage`（**owner|admin**）： + +```json +{"data":{ + "main":{"kind":"sqlite","path":"…","fileBytes":N,"walBytes":N,"shmBytes":N, + "pageSize":4096,"pageCount":N,"freelistPages":N,"freeBytes":N}, + "documents":{"count":N,"bytes":N}, + "vector":{"kind":"pgvector"|"none","enabled":bool,"ready":bool} +}} +``` + +- **只读**（`SELECT`/`PRAGMA` + `os.Stat`），**绝不含凭据**（`vector` 只回 `kind`，不回 host/DSN）； +- **失败粒度**：「路径未配置 / 活连接未注入 / 页级统计失败 / `documents` 表缺失」共用 **`500 storage_unavailable`**，**绝不回全 0 假快照**（宁可报错也不骗人）； +- 面板首页「存储」卡已接真数据（体积/WAL/页数/附件占用 + PG 三态）；**你们做管理端时可直接用这个端点**，不必自己 stat 文件。 + +## 二、`v0.61` —— `.pdf` 文本层（**行为变更 + 纯增量**） + +1. **白名单 22 → 23 项**（新增 `.pdf`），并改为 **(扩展名, 字节嗅探) 成对裁决**： + - `.pdf` **只**收嗅探为 `application/pdf` 的字节；**PDF 字节也只收在 `.pdf` 名下**； + - ⇒ **HTML/纯文本改名成 `.pdf` ⇒ 415**；**PDF 改名成 `.txt` ⇒ 415**（都是刻意的双向收紧）。 +2. **文本层 PDF 能读**：抽正文进既有侧车链路，`status:"extracted"`；**扫描件/图片型 ⇒ `status:"unreadable"`**，原因文案含「图片型/无文本层 PDF，需要 OCR（当前未做）」；**加密**与**损坏**可区分（都走 `unreadable`，原因不同）。 +3. **读侧 MIME**：真 PDF 如实下发 `application/pdf`，**仍 `Content-Disposition: attachment` + `nosniff`**（不可内联 —— 别指望能在 ``/`