@lobehub/chat/packages/file-loaders/README.md

Lobe Chat - an open-source, high-performance chatbot framework that supports speech synthesis, multimodal, and extensible Function Call plugin system. Supports one-click free deployment of your private ChatGPT/LLM web application.

# @lobehub/file-loaders

`@lobehub/file-loaders` 是 LobeChat 项目中的一个工具包，专门用于从本地文件路径加载各种类型的文件，并将其内容转换为标准化的 `Document` 对象数组。

它的主要目的是提供一个统一的接口来读取不同的文件格式，提取其核心文本内容，并为后续处理（例如在 LobeChat 中进行文件预览、内容提取或将其作为知识库数据源）做好准备。

## ✨ 功能特性

- **统一接口**: 提供 `loadFile(filePath: string)` 函数作为核心入口点。
- **自动类型检测**: 根据文件扩展名自动选择合适的加载方式。
- **广泛的格式支持**:
  - **纯文本类**: `.txt`, `.csv`, `.md`, `.json`, `.xml`, `.yaml`, `.html` 以及多种代码和配置文件格式。
  - **PDF**: `.pdf` 文件。
  - **Word**: `.docx` 文件。
  - **Excel**: `.xlsx`, `.xls` 文件，每个工作表作为一个 `Page`。
  - **PowerPoint**: `.pptx` 文件，每个幻灯片作为一个 `Page`。
- **标准化输出**: 始终返回 `Promise<Document>`。 `Document` 对象代表一个加载的文件，其内部包含一个 `Page` 数组，代表文件的各个逻辑单元（页、幻灯片、工作表、文本块等）。
- **层级结构**: 采用 `Document` 包含 `Page[]` 的结构，更好地反映文件原始组织方式。
- **丰富的元数据**: 在 `Document` 和 `Page` 层面提供详细的元数据，包括文件信息、内容统计和结构信息。

## 核心数据结构

`loadFile` 函数返回一个 `FileDocument` 对象，包含文件级信息和其所有逻辑页面 / 块 (`DocumentPage`)。

### `FileDocument` Interface

| 字段              | 类型              | 描述                                                           |
| :---------------- | :---------------- | :------------------------------------------------------------- |
| `content`         | `string`          | 文件内容 (聚合后的内容)                                        |
| `createdTime`     | `Date`            | 文件创建时间戳。                                               |
| `fileType`        | `string`          | 文件类型或扩展名。                                             |
| `filename`        | `string`          | 原始文件名。                                                   |
| `metadata`        | `object`          | 文件级别的元数据。                                             |
| `metadata.author` | `string?`         | 文档作者 (如果可用)。                                          |
| `metadata.error`  | `string?`         | 如果整个文件加载失败，记录错误信息。                           |
| `metadata.title`  | `string?`         | 文档标题 (如果可用)。                                          |
| `...`             | `any`             | 其他文件级别的元数据。                                         |
| `modifiedTime`    | `Date`            | 文件最后修改时间戳。                                           |
| `pages`           | `DocumentPage[]?` | 包含文档中所有逻辑页面 / 块的数组 (可选)。                     |
| `source`          | `string`          | 原始文件的完整路径。                                           |
| `totalCharCount`  | `number`          | 整个文档的总字符数 (所有 `DocumentPage` 的 `charCount` 之和)。 |
| `totalLineCount`  | `number`          | 整个文档的总行数 (所有 `DocumentPage` 的 `lineCount` 之和)。   |

### `DocumentPage` Interface

| 字段                       | 类型      | 描述                         |
| :------------------------- | :-------- | :--------------------------- |
| `charCount`                | `number`  | 此页 / 块内容的字符数。      |
| `lineCount`                | `number`  | 此页 / 块内容的行数。        |
| `metadata`                 | `object`  | 与此页 / 块相关的元数据。    |
| `metadata.chunkIndex`      | `number?` | 如果分割成块，当前块的索引。 |
| `metadata.error`           | `string?` | 处理此页 / 块时发生的错误。  |
| `metadata.lineNumberEnd`   | `number?` | 在原始文件中的结束行号。     |
| `metadata.lineNumberStart` | `number?` | 在原始文件中的起始行号。     |
| `metadata.pageNumber`      | `number?` | 页码 (适用于 PDF, DOCX)。    |
| `metadata.sectionTitle`    | `string?` | 相关的章节标题。             |
| `metadata.sheetName`       | `string?` | 工作表名称 (适用于 XLSX)。   |
| `metadata.slideNumber`     | `number?` | 幻灯片编号 (适用于 PPTX)。   |
| `metadata.totalChunks`     | `number?` | 如果分割成块，总块数。       |
| `...`                      | `any`     | 其他特定于页 / 块的元数据。  |
| `pageContent`              | `string`  | 此页 / 块的核心文本内容。    |

如果你对我们的项目感兴趣，欢迎在 [GitHub](https://github.com/lobehub/lobe-chat) 上查看、点赞或贡献代码！