@ happyvertical/ 文档
具有分级结构的文件处理. 支持带有文本提取的 PDF 文档, Word (.docx)和PowerPoint(英语:.pptx)通过可选Kreuzberg引擎读取的文件,自动文件管理系统检测(WordPress下载管理器,CivilWeb,DocuShare),以及文件缓存. 用途 @happyvertical/spider 用于网页分析和 @happyvertical/pdf 用于 PDF 文本提取.
安装
从 npm 公共登记册安装 :
npm install @happyvertical/documents
匿名安装还需要包的外部 @happyvertical/ocr, (中文(简体) ), @happyvertical/pdf,以及 @happyvertical/spider 需要公开 npm 的依赖性 .
快速启动
import { fetchDocument } from '@happyvertical/documents';
// Process a local PDF
const doc = await fetchDocument('file:///path/to/report.pdf');
for (const part of doc.parts) {
console.log(part.title);
console.log(part.content);
}
// Fetch a remote PDF (auto-detected from URL extension)
const remote = await fetchDocument('https://example.com/report.pdf');
console.log(remote.parts[0].content);
使用量
文件管理系统检测
获取网络 URL时, 软件包使用 @happyvertical/spider 检测文件管理系统并提取PDF直接链接:
// WordPress Download Manager URL — spider detects the PDF link automatically
const doc = await fetchDocument(
'https://example.com/download/meeting-minutes/',
{ scraper: 'basic', spider: 'dom' }
);
覆盖 MIME 类型
const doc = await fetchDocument('https://example.com/download?id=123', {
type: 'application/pdf',
});
缓存控制
const doc = await fetchDocument('https://example.com/report.pdf', {
cacheDir: './my-cache',
cache: true,
cacheExpiry: 600_000, // 10 minutes
});
API 参考
fetchDocument(url, options?)
主工厂功能. 检测文档格式,选择适当的处理器,并返回结构化内容.
- url 密码
string——文档 URL 或文件路径(file://, (中文(简体) ),http://, (中文(简体) ),https://(中文(简体) ) - 选项
FetchDocumentOptions- 见下文 - 回返
Promise<Document> - 掷出 如果检测到的 MIME 类型没有处理器
FetchDocumentOptions
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
type | string | 自动检测 | 覆盖 MIME 类型检测 |
extractImages | boolean | true | 从文档中提取图像( stub- 目前返回) [](中文(简体) ) |
runOcr | boolean | true 用于 PDF 的 | 在提取的图像上运行 OCR( stub) |
cacheDir | string | OS 临时目录 | 缓存下载文件目录 |
cache | boolean | true | 启用/ 禁用蜘蛛获取缓存 |
cacheExpiry | number | 300000 | 缓存过期( 毫秒 ) |
scraper | 'basic' | 'tree' | 'crawlee' | 'basic' | 内容提取的Scraper策略. crawlee 是一个被折旧的别名,用于 spider: 'crawlee' 和基本的刮刮. |
spider | 'simple' | 'dom' | 'crawlee' | 'crawl4ai' | 'dom' | 用于取取网页的蜘蛛适配器 |
headers | Record<string, string> | —— 说 | 自定义用于蜘蛛请求的 HTTP 信头 |
timeout | number | 30000 | 请求超时( 毫秒) |
maxDuration | number | —— 说 | 最大刮取时间以毫秒计 |
maxInteractions | number | —— 说 | 高级刮发器的最大相互作用 |
Document (类)
基础文档处理器. 管理下载、缓存和本地文件路径解析。 由处理器内部使用;也可直接通过 Document.create(url, options)。 。 。 .
PDFProcessor
执行 DocumentProcessor。从 PDF 文件取出文本,验证 PDF 头(检测 HTML 缓存中毒),并处理缓存结果.
DOCXProcessor 财务报告和审定财务报表 PPTXProcessor
通过 Word and PowerPoint 文件读取 克罗伊斯贝格 (单位:千美元)@kreuzberg/node,一个 选项 依赖; 无 LibreOffice). fetchDocument 选他们从 .docx 编号 : .pptx 扩展名或 MIME 类型.
- DOCX 数据库页:1
markdown每个标题部分,按标题级别嵌入(第一个标题之前的文本是标题为文档标题的主要部分)。 嵌入的图像被附在第一部分上. - PPTX 密码页:1
text每个幻灯片,按顺序排列.part.metadata.slide是基于 1 的幻灯片编号,part.title幻灯片文本的第一行,part.notes发言者指出(当幻灯片没有幻灯片时缺席)和part.images幻灯片上的图片( q)image.data持有字节,image.altText说明). - Kreuzberg 未安装数字 :
process()解决parts: []财务报告和审定财务报表document.unsupported = { code: 'dependency-missing', reason, dependency: '@kreuzberg/node' }而不是扔东西。 腐败文件仍然被拒绝 .
对于您已经持有的字节内存使用 extractOffice(source, 'docx' | 'pptx', { extractImages? }),则需要 Buffer, (中文(简体) ), Uint8Array 或文件路径和返回 { status: 'ok', format, title, parts, metadata } 或者说 { status: 'unsupported', code, reason, dependency, format }。 。 。 .
import { extractOffice } from '@happyvertical/documents';
const result = await extractOffice(bytes, 'pptx');
if (result.status === 'unsupported') {
console.warn(result.reason);
} else {
for (const slide of result.parts) console.log(slide.metadata?.slide, slide.content, slide.notes);
}
getTitleFromUrl(url, defaultTitle?)
解析文件名、删除扩展名并解码 URL 编码字符,从 URL 中提取一个人类可读标题.
类型
interface Document {
url: string;
type: string;
parts: DocumentPart[];
metadata?: Record<string, any>;
unsupported?: { code: 'dependency-missing'; reason: string; dependency?: string };
}
interface DocumentPart {
id: string;
title: string;
content: string;
type: 'text' | 'html' | 'markdown';
images?: DocumentImage[];
notes?: string; // speaker notes (PPTX slides)
metadata?: Record<string, any>;
parts?: DocumentPart[];
}
interface DocumentImage {
id: string;
url: string;
localPath?: string;
data?: Uint8Array; // in-memory bytes (Office documents)
altText?: string;
ocrText?: string;
position?: number;
metadata?: { width?: number; height?: number; format?: string };
}
interface DocumentProcessor {
process(url: string, options?: FetchDocumentOptions): Promise<Document>;
supports(type: string): boolean;
}
许可证
麻省理工学院