deer-flow/backend/docs/PATH_EXAMPLES.md

# 文件路径使用示例

## 三种路径类型

DeerFlow 的文件上传系统返回三种不同的路径，每种路径用于不同的场景：

### 1. 实际文件系统路径 (path)

```
.deer-flow/users/{user_id}/threads/{thread_id}/user-data/uploads/document.pdf
```

**用途：**
- 文件在服务器文件系统中的实际位置
- 相对于 `backend/` 目录
- 用于直接文件系统访问、备份、调试等

**示例：**
```python
# Python 代码中直接访问
from pathlib import Path
file_path = Path("backend/.deer-flow/users/alice/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/users/alice/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.pdf.md",
  //   markdown_path: ".deer-flow/users/alice/threads/abc123/user-data/.upload-conversions/report.pdf.md",
  //   markdown_virtual_path: "/mnt/user-data/.upload-conversions/report.pdf.md",
  //   markdown_artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/.upload-conversions/report.pdf.md"
  // }

  // 2. 发送消息给 Agent
  await sendMessage(threadId, "请分析刚上传的 PDF 文件");

  // Agent 的当前上传上下文包含主文件：
  // - report.pdf (虚拟路径: /mnt/user-data/uploads/report.pdf)
  // 转换结果必须使用上传响应返回的 markdown_virtual_path，不要推导同目录文件名。

  // 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/users/alice/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` |
| Agent 读取生成 Markdown | `markdown_virtual_path` | `/mnt/user-data/.upload-conversions/file.pdf.md` |
| 前端读取生成 Markdown | `markdown_artifact_url` | `/api/threads/abc123/artifacts/mnt/user-data/.upload-conversions/file.pdf.md` |
| 备份脚本 | `path` | `.deer-flow/users/alice/threads/abc123/user-data/uploads/file.pdf` |
| 日志记录 | `path` | `.deer-flow/users/alice/threads/abc123/user-data/uploads/file.pdf` |

## 代码示例集合

### Python - 后端处理

```python
from deerflow.config.paths import get_paths
from deerflow.uploads.manager import normalize_filename

def process_uploaded_file(user_id: str, thread_id: str, filename: str):
    # 使用与请求所有者相同的用户隔离桶
    base_dir = get_paths().sandbox_uploads_dir(thread_id, user_id=user_id)
    file_path = base_dir / normalize_filename(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_* 字段仅在本次上传响应中返回，
    // 调用方如需保留转换链接，应保存该响应元数据。
  });

  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;
}

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>
            <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_*` 字段
   - 常规生成文件位于 `.upload-conversions/<完整主文件名>.md`；超长名称使用 UTF-8 安全前缀和完整 SHA-256 摘要，因此始终以上传响应中的 `markdown_*` 字段为准
   - AIO 挂载模式以只读挂载暴露 `.upload-conversions`；Local 结构化文件 API 通过只读映射拒绝写入，但 Local 宿主机 bash 不受该映射约束；该目录不会出现在主文件列表中
   - 同名主文件按 `file.pdf`、`file_1.pdf`、`file_2.pdf` 原子发布，不会覆盖
   - 删除主文件会等待该实际文件名的活跃生命周期，然后只删除其精确生成资产，不会删除用户上传的 `uploads/file.md`
   - `.upload-*.part` 是内部暂存名称，不能作为用户上传 basename
   - 建议优先使用 Markdown 版本（更易处理）
   - 原始文件始终保留