diff --git a/backend/docs/FILE_UPLOAD.md b/backend/docs/FILE_UPLOAD.md
new file mode 100644
index 0000000..19a5ff7
--- /dev/null
+++ b/backend/docs/FILE_UPLOAD.md
@@ -0,0 +1,287 @@
+# 文件上传功能
+
+## 概述
+
+DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并自动将 Office 文档和 PDF 转换为 Markdown 格式。
+
+## 功能特性
+
+- ✅ 支持多文件同时上传
+- ✅ 自动转换文档为 Markdown（PDF、PPT、Excel、Word）
+- ✅ 文件存储在线程隔离的目录中
+- ✅ Agent 自动感知已上传的文件
+- ✅ 支持文件列表查询和删除
+
+## API 端点
+
+### 1. 上传文件
+```
+POST /api/threads/{thread_id}/uploads
+```
+
+**请求体：** `multipart/form-data`
+- `files`: 一个或多个文件
+
+**响应：**
+```json
+{
+ "success": true,
+ "files": [
+ {
+ "filename": "document.pdf",
+ "size": 1234567,
+ "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+ "virtual_path": "/mnt/user-data/uploads/document.pdf",
+ "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+ "markdown_file": "document.md",
+ "markdown_path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.md",
+ "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
+ "markdown_artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.md"
+ }
+ ],
+ "message": "Successfully uploaded 1 file(s)"
+}
+```
+
+**路径说明：**
+- `path`: 实际文件系统路径（相对于 `backend/` 目录）
+- `virtual_path`: Agent 在沙箱中使用的虚拟路径
+- `artifact_url`: 前端通过 HTTP 访问文件的 URL
+
+### 2. 列出已上传文件
+```
+GET /api/threads/{thread_id}/uploads/list
+```
+
+**响应：**
+```json
+{
+ "files": [
+ {
+ "filename": "document.pdf",
+ "size": 1234567,
+ "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+ "virtual_path": "/mnt/user-data/uploads/document.pdf",
+ "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+ "extension": ".pdf",
+ "modified": 1705997600.0
+ }
+ ],
+ "count": 1
+}
+```
+
+### 3. 删除文件
+```
+DELETE /api/threads/{thread_id}/uploads/{filename}
+```
+
+**响应：**
+```json
+{
+ "success": true,
+ "message": "Deleted document.pdf"
+}
+```
+
+## 支持的文档格式
+
+以下格式会自动转换为 Markdown：
+- PDF (`.pdf`)
+- PowerPoint (`.ppt`, `.pptx`)
+- Excel (`.xls`, `.xlsx`)
+- Word (`.doc`, `.docx`)
+
+转换后的 Markdown 文件会保存在同一目录下，文件名为原文件名 + `.md` 扩展名。
+
+## Agent 集成
+
+### 自动文件列举
+
+Agent 在每次请求时会自动收到已上传文件的列表，格式如下：
+
+```xml
+
+The following files have been uploaded and are available for use:
+
+- document.pdf (1.2 MB)
+ Path: /mnt/user-data/uploads/document.pdf
+
+- document.md (45.3 KB)
+ Path: /mnt/user-data/uploads/document.md
+
+You can read these files using the `read_file` tool with the paths shown above.
+
+```
+
+### 使用上传的文件
+
+Agent 在沙箱中运行，使用虚拟路径访问文件。Agent 可以直接使用 `read_file` 工具读取上传的文件：
+
+```python
+# 读取原始 PDF（如果支持）
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# 读取转换后的 Markdown（推荐）
+read_file(path="/mnt/user-data/uploads/document.md")
+```
+
+**路径映射关系：**
+- Agent 使用：`/mnt/user-data/uploads/document.pdf`（虚拟路径）
+- 实际存储：`backend/.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf`
+- 前端访问：`/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf`（HTTP URL）
+
+## 测试示例
+
+### 使用 curl 测试
+
+```bash
+# 1. 上传单个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+ -F "files=@/path/to/document.pdf"
+
+# 2. 上传多个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+ -F "files=@/path/to/document.pdf" \
+ -F "files=@/path/to/presentation.pptx" \
+ -F "files=@/path/to/spreadsheet.xlsx"
+
+# 3. 列出已上传文件
+curl http://localhost:2026/api/threads/test-thread/uploads/list
+
+# 4. 删除文件
+curl -X DELETE http://localhost:2026/api/threads/test-thread/uploads/document.pdf
+```
+
+### 使用 Python 测试
+
+```python
+import requests
+
+thread_id = "test-thread"
+base_url = "http://localhost:2026"
+
+# 上传文件
+files = [
+ ("files", open("document.pdf", "rb")),
+ ("files", open("presentation.pptx", "rb")),
+]
+response = requests.post(
+ f"{base_url}/api/threads/{thread_id}/uploads",
+ files=files
+)
+print(response.json())
+
+# 列出文件
+response = requests.get(f"{base_url}/api/threads/{thread_id}/uploads/list")
+print(response.json())
+
+# 删除文件
+response = requests.delete(
+ f"{base_url}/api/threads/{thread_id}/uploads/document.pdf"
+)
+print(response.json())
+```
+
+## 文件存储结构
+
+```
+backend/.deer-flow/threads/
+└── {thread_id}/
+ └── user-data/
+ └── uploads/
+ ├── document.pdf # 原始文件
+ ├── document.md # 转换后的 Markdown
+ ├── presentation.pptx
+ ├── presentation.md
+ └── ...
+```
+
+## 限制
+
+- 最大文件大小：100MB（可在 nginx.conf 中配置 `client_max_body_size`）
+- 文件名安全性：系统会自动验证文件路径，防止目录遍历攻击
+- 线程隔离：每个线程的上传文件相互隔离，无法跨线程访问
+
+## 技术实现
+
+### 组件
+
+1. **Upload Router** (`src/gateway/routers/uploads.py`)
+ - 处理文件上传、列表、删除请求
+ - 使用 markitdown 转换文档
+
+2. **Uploads Middleware** (`src/agents/middlewares/uploads_middleware.py`)
+ - 在每次 Agent 请求前注入文件列表
+ - 自动生成格式化的文件列表消息
+
+3. **Nginx 配置** (`nginx.conf`)
+ - 路由上传请求到 Gateway API
+ - 配置大文件上传支持
+
+### 依赖
+
+- `markitdown>=0.0.1a2` - 文档转换
+- `python-multipart>=0.0.20` - 文件上传处理
+
+## 故障排查
+
+### 文件上传失败
+
+1. 检查文件大小是否超过限制
+2. 检查 Gateway API 是否正常运行
+3. 检查磁盘空间是否充足
+4. 查看 Gateway 日志：`make gateway`
+
+### 文档转换失败
+
+1. 检查 markitdown 是否正确安装：`uv run python -c "import markitdown"`
+2. 查看日志中的具体错误信息
+3. 某些损坏或加密的文档可能无法转换，但原文件仍会保存
+
+### Agent 看不到上传的文件
+
+1. 确认 UploadsMiddleware 已在 agent.py 中注册
+2. 检查 thread_id 是否正确
+3. 确认文件确实已上传到正确的目录
+
+## 开发建议
+
+### 前端集成
+
+```typescript
+// 上传文件示例
+async function uploadFiles(threadId: string, files: File[]) {
+ const formData = new FormData();
+ files.forEach(file => {
+ formData.append('files', file);
+ });
+
+ const response = await fetch(
+ `/api/threads/${threadId}/uploads`,
+ {
+ method: 'POST',
+ body: formData,
+ }
+ );
+
+ return response.json();
+}
+
+// 列出文件
+async function listFiles(threadId: string) {
+ const response = await fetch(
+ `/api/threads/${threadId}/uploads/list`
+ );
+ return response.json();
+}
+```
+
+### 扩展功能建议
+
+1. **文件预览**：添加预览端点，支持在浏览器中直接查看文件
+2. **批量删除**：支持一次删除多个文件
+3. **文件搜索**：支持按文件名或类型搜索
+4. **版本控制**：保留文件的多个版本
+5. **压缩包支持**：自动解压 zip 文件
+6. **图片 OCR**：对上传的图片进行 OCR 识别
diff --git a/backend/docs/PATH_EXAMPLES.md b/backend/docs/PATH_EXAMPLES.md
new file mode 100644
index 0000000..0a3463f
--- /dev/null
+++ b/backend/docs/PATH_EXAMPLES.md
@@ -0,0 +1,289 @@
+# 文件路径使用示例
+
+## 三种路径类型
+
+DeerFlow 的文件上传系统返回三种不同的路径，每种路径用于不同的场景：
+
+### 1. 实际文件系统路径 (path)
+
+```
+.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 文件在服务器文件系统中的实际位置
+- 相对于 `backend/` 目录
+- 用于直接文件系统访问、备份、调试等
+
+**示例：**
+```python
+# Python 代码中直接访问
+from pathlib import Path
+file_path = Path("backend/.deer-flow/threads/abc123/user-data/uploads/document.pdf")
+content = file_path.read_bytes()
+```
+
+### 2. 虚拟路径 (virtual_path)
+
+```
+/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- Agent 在沙箱环境中使用的路径
+- 沙箱系统会自动映射到实际路径
+- Agent 的所有文件操作工具都使用这个路径
+
+**示例：**
+Agent 在对话中使用：
+```python
+# Agent 使用 read_file 工具
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# Agent 使用 bash 工具
+bash(command="cat /mnt/user-data/uploads/document.pdf")
+```
+
+### 3. HTTP 访问 URL (artifact_url)
+
+```
+/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 前端通过 HTTP 访问文件
+- 用于下载、预览文件
+- 可以直接在浏览器中打开
+
+**示例：**
+```typescript
+// 前端 TypeScript/JavaScript 代码
+const threadId = 'abc123';
+const filename = 'document.pdf';
+
+// 下载文件
+const downloadUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}?download=true`;
+window.open(downloadUrl);
+
+// 在新窗口预览
+const viewUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}`;
+window.open(viewUrl, '_blank');
+
+// 使用 fetch API 获取
+const response = await fetch(viewUrl);
+const blob = await response.blob();
+```
+
+## 完整使用流程示例
+
+### 场景：前端上传文件并让 Agent 处理
+
+```typescript
+// 1. 前端上传文件
+async function uploadAndProcess(threadId: string, file: File) {
+ // 上传文件
+ const formData = new FormData();
+ formData.append('files', file);
+
+ const uploadResponse = await fetch(
+ `/api/threads/${threadId}/uploads`,
+ {
+ method: 'POST',
+ body: formData
+ }
+ );
+
+ const uploadData = await uploadResponse.json();
+ const fileInfo = uploadData.files[0];
+
+ console.log('文件信息：', fileInfo);
+ // {
+ // filename: "report.pdf",
+ // path: ".deer-flow/threads/abc123/user-data/uploads/report.pdf",
+ // virtual_path: "/mnt/user-data/uploads/report.pdf",
+ // artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.pdf",
+ // markdown_file: "report.md",
+ // markdown_path: ".deer-flow/threads/abc123/user-data/uploads/report.md",
+ // markdown_virtual_path: "/mnt/user-data/uploads/report.md",
+ // markdown_artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.md"
+ // }
+
+ // 2. 发送消息给 Agent
+ await sendMessage(threadId, "请分析刚上传的 PDF 文件");
+
+ // Agent 会自动看到文件列表，包含：
+ // - report.pdf (虚拟路径: /mnt/user-data/uploads/report.pdf)
+ // - report.md (虚拟路径: /mnt/user-data/uploads/report.md)
+
+ // 3. 前端可以直接访问转换后的 Markdown
+ const mdResponse = await fetch(fileInfo.markdown_artifact_url);
+ const markdownContent = await mdResponse.text();
+ console.log('Markdown 内容：', markdownContent);
+
+ // 4. 或者下载原始 PDF
+ const downloadLink = document.createElement('a');
+ downloadLink.href = fileInfo.artifact_url + '?download=true';
+ downloadLink.download = fileInfo.filename;
+ downloadLink.click();
+}
+```
+
+## 路径转换表
+
+| 场景 | 使用的路径类型 | 示例 |
+|------|---------------|------|
+| 服务器后端代码直接访问 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| Agent 工具调用 | `virtual_path` | `/mnt/user-data/uploads/file.pdf` |
+| 前端下载/预览 | `artifact_url` | `/api/threads/abc123/artifacts/mnt/user-data/uploads/file.pdf` |
+| 备份脚本 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| 日志记录 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+
+## 代码示例集合
+
+### Python - 后端处理
+
+```python
+from pathlib import Path
+from src.agents.middlewares.thread_data_middleware import THREAD_DATA_BASE_DIR
+
+def process_uploaded_file(thread_id: str, filename: str):
+ # 使用实际路径
+ base_dir = Path.cwd() / THREAD_DATA_BASE_DIR / thread_id / "user-data" / "uploads"
+ file_path = base_dir / filename
+
+ # 直接读取
+ with open(file_path, 'rb') as f:
+ content = f.read()
+
+ return content
+```
+
+### JavaScript - 前端访问
+
+```javascript
+// 列出已上传的文件
+async function listUploadedFiles(threadId) {
+ const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+ const data = await response.json();
+
+ // 为每个文件创建下载链接
+ data.files.forEach(file => {
+ console.log(`文件: ${file.filename}`);
+ console.log(`下载: ${file.artifact_url}?download=true`);
+ console.log(`预览: ${file.artifact_url}`);
+
+ // 如果是文档，还有 Markdown 版本
+ if (file.markdown_artifact_url) {
+ console.log(`Markdown: ${file.markdown_artifact_url}`);
+ }
+ });
+
+ return data.files;
+}
+
+// 删除文件
+async function deleteFile(threadId, filename) {
+ const response = await fetch(
+ `/api/threads/${threadId}/uploads/${filename}`,
+ { method: 'DELETE' }
+ );
+ return response.json();
+}
+```
+
+### React 组件示例
+
+```tsx
+import React, { useState, useEffect } from 'react';
+
+interface UploadedFile {
+ filename: string;
+ size: number;
+ path: string;
+ virtual_path: string;
+ artifact_url: string;
+ extension: string;
+ modified: number;
+ markdown_artifact_url?: string;
+}
+
+function FileUploadList({ threadId }: { threadId: string }) {
+ const [files, setFiles] = useState([]);
+
+ useEffect(() => {
+ fetchFiles();
+ }, [threadId]);
+
+ async function fetchFiles() {
+ const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+ const data = await response.json();
+ setFiles(data.files);
+ }
+
+ async function handleUpload(event: React.ChangeEvent) {
+ const fileList = event.target.files;
+ if (!fileList) return;
+
+ const formData = new FormData();
+ Array.from(fileList).forEach(file => {
+ formData.append('files', file);
+ });
+
+ await fetch(`/api/threads/${threadId}/uploads`, {
+ method: 'POST',
+ body: formData
+ });
+
+ fetchFiles(); // 刷新列表
+ }
+
+ async function handleDelete(filename: string) {
+ await fetch(`/api/threads/${threadId}/uploads/${filename}`, {
+ method: 'DELETE'
+ });
+ fetchFiles(); // 刷新列表
+ }
+
+ return (
+
+
+
+
+ {files.map(file => (
+ -
+ {file.filename}
+ 预览
+ 下载
+ {file.markdown_artifact_url && (
+ Markdown
+ )}
+
+
+ ))}
+
+