[RFC] 111 - 统一文件加载与解析模块

[arvinxx]

1. 摘要 (Summary)

本 RFC 提议正式确立 @lobechat/file-loaders 包作为 LobeChat 项目中处理本地文件加载和内容提取的核心模块。该包提供了一个统一的 loadFile 函数，能够根据文件扩展名自动识别并处理多种常见文件格式（文本、PDF、Word、Excel、PowerPoint 等），将文件内容及其元数据转换为标准化的 FileDocument 和 DocumentPage 对象结构，为后续的文件预览、内容分析、知识库构建等功能提供一致的数据源。

2. 动机 (Motivation)

随着 LobeChat 功能的扩展，特别是涉及到用户上传文件进行 RAG（检索增强生成）或内容预览时，需要一种健壮、可扩展的方式来处理各种不同的文件格式。直接在应用层处理这些格式会导致代码重复、依赖管理复杂以及难以维护。

之前在做知识库的时候曾实现过一个基于 langchain 的模块，但是那个模块是直接做了文件读取 -> 分块的全流程。而随着桌面端的读文件，与大家对知识库直接读文件的诉求越发强烈，因此我们有必要单独抽取一个模块来做相应实现。

@lobechat/file-loaders 的目标是：

• 标准化: 提供统一的 API 和数据输出格式，简化上层应用的文件处理逻辑。
• 解耦: 将文件解析的复杂性封装在独立的包中，降低主应用的复杂度。
• 可扩展性: 易于添加对新文件格式的支持，只需实现对应的加载器。
• 类型安全: 利用 TypeScript 提供明确的数据结构和类型定义。

3. 详细设计 (Detailed Design)

3.1 核心概念

• 统一入口: 提供异步函数 loadFile(filePath: string): Promise<FileDocument> 作为所有文件加载操作的唯一入口点。
• 自动类型检测: loadFile 内部根据 filePath 的扩展名，动态选择合适的加载器 (loader) 来处理文件。
• 标准化输出: 所有加载器都返回符合 FileDocument 接口的对象。FileDocument 包含文件级元数据和一个 DocumentPage[] 数组，其中每个 DocumentPage 代表文件的一个逻辑部分（如 PDF 页面、Word 段落、Excel 工作表、PPT 幻灯片或纯文本块）及其内容和元数据。

3.2 架构

@lobechat/file-loaders
├── src/
│   ├── index.ts         # 包入口，导出 loadFile
│   ├── loadFile.ts      # 实现核心的 loadFile 函数，包含文件类型检测和加载器分发逻辑
│   ├── types.ts         # 定义 FileDocument, DocumentPage 等核心类型接口
│   ├── loaders/         # 包含所有特定文件类型的加载器
│   │   ├── index.ts     # 导出所有具体加载器
│   │   ├── text/        # 处理 .txt, .md, .json, .csv, code files 等
│   │   ├── pdf/         # 处理 .pdf (使用 pdfjs-dist)
│   │   ├── docx/        # 处理 .docx (使用 mammoth)
│   │   ├── excel/       # 处理 .xlsx, .xls (使用 xlsx)
│   │   └── pptx/        # 处理 .pptx (使用 officeparser)
│   └── utils/           # 辅助函数
│       ├── isTextReadableFile.ts # 判断文件是否可作为纯文本读取
│       └── parser-utils.ts       # 解析过程中的通用工具函数
├── package.json         # 定义依赖项 (langchain, pdfjs, mammoth, xlsx, officeparser 等)
└── README.md            # 包文档

3.3 数据结构

主要的输出数据结构是 FileDocument 和 DocumentPage，其详细字段已在 README.md 中定义，关键字段包括：

• FileDocument: filename, fileType, source, content (聚合内容), pages (DocumentPage 数组), metadata (文件级元数据如作者、标题、创建/修改时间), totalCharCount, totalLineCount。
• DocumentPage: pageContent (页面/块内容), metadata (页面/块级元数据如页码、工作表名、幻灯片编号、错误信息), charCount, lineCount。

3.4 支持的格式与依赖

根据 loaders 目录结构和 package.json，当前支持：

• 文本类 (.txt, .md, .json, .csv, code, etc.): 使用 Node.js fs 模块，通过 isTextReadableFile 判断。
• PDF (.pdf): pdfjs-dist
• Word (.docx): mammoth
• Excel (.xlsx, .xls): xlsx (可能通过 officeparser 封装)
• PowerPoint (.pptx): officeparser
• XML/HTML: 可作为纯文本处理，或使用 @xmldom/xmldom。

3.5 错误处理

• 文件读取或解析过程中发生的错误会被捕获。
• 文件级别的错误（如文件不存在或无法读取）会导致 loadFile 抛出异常或返回带有 metadata.error 的 FileDocument。
• 页面/块级别的解析错误（如单个 PDF 页面损坏）会记录在对应 DocumentPage 的 metadata.error 字段中，尽量保证加载过程的健壮性。

4. 使用方式 (Usage)

import { loadFile } from '@lobechat/file-loaders';

async function processFile(filePath: string) {
  try {
    const document = await loadFile(filePath);

    console.log(`Loaded document: ${document.filename}`);
    console.log(`Total pages/sections: ${document.pages?.length || 0}`);
    console.log(`Total characters: ${document.totalCharCount}`);
    console.log(`Content: ${document.content}`);


    if (document.pages) {
      document.pages.forEach((page, index) => {
        console.log(`--- Page/Section ${index + 1} ---`);
        console.log(`Content snippet: ${page.pageContent.substring(0, 100)}...`);
        console.log(`Metadata:`, page.metadata);
      });
    }
  } catch (error) {
    console.error(`Error loading file ${filePath}:`, error);
  }
}

// Example usage:
processFile('/path/to/my/document.pdf');
processFile('/path/to/my/spreadsheet.xlsx');
processFile('/path/to/my/notes.md');

5. 备选方案考虑 (Alternatives Considered)

1. 在主应用中分散处理: 每个需要文件处理的地方各自实现逻辑。这会导致代码冗余和不一致。
2. 依赖单一大型库: 寻找一个能处理所有格式的库。但之前查下来是没有这样的流行库的。
3. 使用 Langchain 的 Document Loaders: Langchain 提供了丰富的 Document Loaders。虽然 @lobechat/file-loaders 部分依赖了 @langchain/community (可能用于某些加载器或类型定义)，但创建一个独立的、更贴合 LobeChat 数据结构和需求的封装层，可以提供更好的控制和定制化，并避免强耦合 Langchain 的特定实现。本项目选择了构建一个专用包，以更好地控制依赖、接口和错误处理逻辑，同时借鉴了 Langchain 的 Document 概念。

当前方案通过模块化加载器和统一接口，在灵活性、可维护性和控制力之间取得了较好的平衡。

6. 未来考虑 (Future Considerations)

• 支持更多格式: 如 .epub, .odt, .rtf 等。
• 图片内容提取 (OCR): 为包含扫描内容的 PDF 或图片文件增加 OCR 功能。
• 元数据提取增强: 提取更丰富的文档元数据（如摘要、关键词等）。
• 流式处理: 对于非常大的文件，考虑支持流式读取和处理，以降低内存消耗。
• Web URL 加载: 扩展 loadFile 或创建类似接口以支持从 URL 加载内容。

实现进展

• 🔨 chore: add file-loaders modules #7488

[AutoCONFIG]

期待，改善文本文件的加载和解析对科研学习或者文本型工作很有帮助。
希望能够尽早实现各类文本性文件的内容解析和识别，虽然之前有提过一个建议（[Request] 能否参考豆包网页版的PDF阅读的预选中功能呢？）,但是其只支持pdf，且模型也不能够灵活切换，导致部分场景无法满足要求。所以期待lobechat尽早实现这个功能，特别是如果能够实现各类文本类型，感觉对于文本型工作或者科研学习的实用性会大大提高