From 86e64f2a956eb93297030c134cffa43b60a1a6d4 Mon Sep 17 00:00:00 2001 From: ChengFa <166748424+indexGin@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:01:45 +0800 Subject: [PATCH] docs(uploads): clarify the document conversion opt-in (#7010) --- backend/README.md | 6 +++++- backend/README_zh.md | 5 ++++- backend/docs/API.md | 9 +++++++-- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/backend/README.md b/backend/README.md index 56e8917eb2..8d5e8bddf6 100644 --- a/backend/README.md +++ b/backend/README.md @@ -158,11 +158,15 @@ to a boundary (SQLite) or causing the search to fail (PostgreSQL). | `GET /api/memory/config` | Memory configuration | | `GET /api/memory/status` | Combined config + data | | `GET /api/threads/{id}/runs/{run_id}/events` | Debug/audit events for one run; filter `event_types=context:memory` for effective memory identity | -| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown, rejects directory paths, auto-renames duplicate filenames in one request) | +| `POST /api/threads/{id}/uploads` | Upload files (optional PDF/PPT/Excel/Word-to-Markdown conversion, rejects directory paths, auto-renames duplicate filenames in one request) | | `GET /api/threads/{id}/uploads/list` | List uploaded files | | `DELETE /api/threads/{id}` | Delete DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail | | `GET /api/threads/{id}/artifacts/{path}` | Serve generated artifacts | +Automatic document conversion is disabled by default. Trusted deployments can +enable it with `uploads.auto_convert_documents: true` in `config.yaml`; see +[file upload configuration](docs/FILE_UPLOAD.md#支持的文档格式). + Cancelling an upload waits for an already-running document conversion worker to finish before removing its temporary source. This prevents cleanup from deleting a file that the converter is still reading; cancellation can therefore take as diff --git a/backend/README_zh.md b/backend/README_zh.md index 5e7d8281b1..7335255eca 100644 --- a/backend/README_zh.md +++ b/backend/README_zh.md @@ -129,11 +129,14 @@ FastAPI 应用程序，为前端集成提供 REST 接口： | `GET /api/memory/config` | 获取记忆配置 | | `GET /api/memory/status` | 获取组合后的配置和数据状态 | | `GET /api/threads/{id}/runs/{run_id}/events` | 获取某次运行的调试或审计事件；可使用 `event_types=context:memory` 筛选实际记忆标识 | -| `POST /api/threads/{id}/uploads` | 上传文件（自动将 PDF、PPT、Excel、Word 转换为 Markdown；拒绝目录路径；自动重命名单次请求中的重复文件名） | +| `POST /api/threads/{id}/uploads` | 上传文件（可选地将 PDF、PPT、Excel、Word 转换为 Markdown；拒绝目录路径；自动重命名单次请求中的重复文件名） | | `GET /api/threads/{id}/uploads/list` | 列出已上传的文件 | | `DELETE /api/threads/{id}` | 删除 LangGraph 线程后，清除由 DeerFlow 管理的本地线程数据；意外错误会记录在服务端，并返回通用的 500 错误信息 | | `GET /api/threads/{id}/artifacts/{path}` | 提供生成产物的访问 | +文档自动转换默认关闭。受信任的部署可以在 `config.yaml` 中设置 +`uploads.auto_convert_documents: true` 来启用，详见[文件上传配置](docs/FILE_UPLOAD.md#支持的文档格式)。 + ### 即时通信渠道 即时通信桥接支持飞书、Slack 和 Telegram。Slack 和 Telegram 仍然使用最终的 `runs.wait()` 响应路径；飞书现在通过 `runs.stream(["messages-tuple", "values"])` 进行流式传输，在渠道管理器内部对同一线程中快速连续到达的请求进行串行化，并针对每条源消息原地更新线程内的同一张卡片。 diff --git a/backend/docs/API.md b/backend/docs/API.md index c4a4be16e8..60be71c3e8 100644 --- a/backend/docs/API.md +++ b/backend/docs/API.md @@ -1216,6 +1216,11 @@ mounted directory must be writable only by trusted operators. Upload one or more files to a thread. +Automatic Office/PDF-to-Markdown conversion is disabled by default. To enable +host-side parsing in a trusted deployment, set +`uploads.auto_convert_documents: true` in `config.yaml`. See +[document conversion configuration](FILE_UPLOAD.md#支持的文档格式). + ```http POST /api/threads/{thread_id}/uploads Content-Type: multipart/form-data @@ -1224,7 +1229,7 @@ Content-Type: multipart/form-data **Request Body:** - `files`: One or more files to upload -**Response:** +**Response** (example with automatic conversion enabled and successful): ```json { "success": true, @@ -1248,7 +1253,7 @@ Content-Type: multipart/form-data **Name collisions:** filenames are claimed unique against the thread's existing uploads and reserved atomically — a same-name upload never replaces the existing file; it lands as `document_1.pdf` (the response's `filename`/`original_filename` reflect the claimed name). Use the artifacts `PUT` endpoint for sanctioned in-place updates. -**Supported Document Formats** (auto-converted to Markdown): +**Supported Document Formats** (converted to Markdown only when automatic conversion is enabled): - PDF (`.pdf`) - PowerPoint (`.ppt`, `.pptx`) - Excel (`.xls`, `.xlsx`)