Initial commit: hardened DeerFlow factory
Vendored deer-flow upstream (bytedance/deer-flow) plus prompt-injection hardening: - New deerflow.security package: content_delimiter, html_cleaner, sanitizer (8 layers — invisible chars, control chars, symbols, NFC, PUA, tag chars, horizontal whitespace collapse with newline/tab preservation, length cap) - New deerflow.community.searx package: web_search, web_fetch, image_search backed by a private SearX instance, every external string sanitized and wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> delimiters - All native community web providers (ddg_search, tavily, exa, firecrawl, jina_ai, infoquest, image_search) replaced with hard-fail stubs that raise NativeWebToolDisabledError at import time, so a misconfigured tool.use path fails loud rather than silently falling back to unsanitized output - Native client back-doors (jina_client.py, infoquest_client.py) stubbed too - Native-tool tests quarantined under tests/_disabled_native/ (collect_ignore_glob via local conftest.py) - Sanitizer Layer 7 fix: only collapse horizontal whitespace, preserve newlines and tabs so list/table structure survives - Hardened runtime config.yaml references only the searx-backed tools - Factory overlay (backend/) kept in sync with deer-flow tree as a reference / source See HARDENING.md for the full audit trail and verification steps.
This commit is contained in:
289
deer-flow/backend/docs/PATH_EXAMPLES.md
Normal file
289
deer-flow/backend/docs/PATH_EXAMPLES.md
Normal file
@@ -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 deerflow.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<UploadedFile[]>([]);
|
||||
|
||||
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<HTMLInputElement>) {
|
||||
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 (
|
||||
<div>
|
||||
<input type="file" multiple onChange={handleUpload} />
|
||||
|
||||
<ul>
|
||||
{files.map(file => (
|
||||
<li key={file.filename}>
|
||||
<span>{file.filename}</span>
|
||||
<a href={file.artifact_url} target="_blank">预览</a>
|
||||
<a href={`${file.artifact_url}?download=true`}>下载</a>
|
||||
{file.markdown_artifact_url && (
|
||||
<a href={file.markdown_artifact_url} target="_blank">Markdown</a>
|
||||
)}
|
||||
<button onClick={() => handleDelete(file.filename)}>删除</button>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **路径安全性**
|
||||
- 实际路径（`path`）包含线程 ID，确保隔离
|
||||
- API 会验证路径，防止目录遍历攻击
|
||||
- 前端不应直接使用 `path`，而应使用 `artifact_url`
|
||||
|
||||
2. **Agent 使用**
|
||||
- Agent 只能看到和使用 `virtual_path`
|
||||
- 沙箱系统自动映射到实际路径
|
||||
- Agent 不需要知道实际的文件系统结构
|
||||
|
||||
3. **前端集成**
|
||||
- 始终使用 `artifact_url` 访问文件
|
||||
- 不要尝试直接访问文件系统路径
|
||||
- 使用 `?download=true` 参数强制下载
|
||||
|
||||
4. **Markdown 转换**
|
||||
- 转换成功时，会返回额外的 `markdown_*` 字段
|
||||
- 建议优先使用 Markdown 版本（更易处理）
|
||||
- 原始文件始终保留
|
||||
Reference in New Issue
Block a user