@happyvertical/documents

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 7721

支持PDF、Word、PowerPoint、HTML和Markdown的多段文档处理

中文使用文档
文档目录15 节
  1. 安装
  2. 快速启动
  3. 使用量
  4. 文件管理系统检测
  5. 覆盖 MIME 类型
  6. 缓存控制
  7. API 参考
  8. fetchDocument(url, options?)
  9. FetchDocumentOptions
  10. Document (类)
  11. PDFProcessor
  12. DOCXProcessor 财务报告和审定财务报表 PPTXProcessor
  13. getTitleFromUrl(url, defaultTitle?)
  14. 类型
  15. 许可证

@ happyvertical/ 文档

License: MIT

具有分级结构的文件处理. 支持带有文本提取的 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

选项类型默认说明
typestring自动检测覆盖 MIME 类型检测
extractImagesbooleantrue从文档中提取图像( stub- 目前返回) [](中文(简体) )
runOcrbooleantrue 用于 PDF 的在提取的图像上运行 OCR( stub)
cacheDirstringOS 临时目录缓存下载文件目录
cachebooleantrue启用/ 禁用蜘蛛获取缓存
cacheExpirynumber300000缓存过期( 毫秒 )
scraper'basic' | 'tree' | 'crawlee''basic'内容提取的Scraper策略. crawlee 是一个被折旧的别名,用于 spider: 'crawlee' 和基本的刮刮.
spider'simple' | 'dom' | 'crawlee' | 'crawl4ai''dom'用于取取网页的蜘蛛适配器
headersRecord<string, string>—— 说自定义用于蜘蛛请求的 HTTP 信头
timeoutnumber30000请求超时( 毫秒)
maxDurationnumber—— 说最大刮取时间以毫秒计
maxInteractionsnumber—— 说高级刮发器的最大相互作用

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

许可证

麻省理工学院

版本与发布记录

@happyvertical/documents 共发布 131 个版本,首次发布于 2026/06/24;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/documents 的常见问题

@happyvertical/documents 是什么?

支持PDF、Word、PowerPoint、HTML和Markdown的多段文档处理

如何安装 @happyvertical/documents?

在项目目录运行 npm install @happyvertical/documents,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-documents-context,可以用 npx have-documents-context 直接运行。

@happyvertical/documents 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/documents 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/documents 可以商用吗?

@happyvertical/documents 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/documents 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/documents 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,721 次,日均约 257 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/documents 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。