# @happyvertical/documents 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/documents/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:01:31.830Z
中文译文更新时间：2026-11-17T12:17:19.435Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/documents
原文对照：https://npmcn.com/package/%40happyvertical/documents/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/documents#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：101 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-06-24T07:29:12.063Z
- 最新版本发布：2026-11-17T00:01:31.600Z
- 近 30 天下载量：7721（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

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

## 安装

```sh
npm install @happyvertical/documents
```

也可以使用：`pnpm add @happyvertical/documents`、`yarn add @happyvertical/documents`、`bun add @happyvertical/documents`

## README

# @ happyvertical/ 文档

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

具有分级结构的文件处理. 支持带有文本提取的 PDF 文档, Word (`.docx`)和PowerPoint(英语:`.pptx`)通过可选Kreuzberg引擎读取的文件,自动文件管理系统检测(WordPress下载管理器,CivilWeb,DocuShare),以及文件缓存. 用途 `@happyvertical/spider` 用于网页分析和 `@happyvertical/pdf` 用于 PDF 文本提取.

## 安装

从 npm 公共登记册安装 :

```bash
npm install @happyvertical/documents
```

匿名安装还需要包的外部 `@happyvertical/ocr`, (中文(简体) ), `@happyvertical/pdf`,以及 `@happyvertical/spider` 需要公开 npm 的依赖性 .

## 快速启动

```typescript
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直接链接:

```typescript
// 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 类型

```typescript
const doc = await fetchDocument('https://example.com/download?id=123', {
  type: 'application/pdf',
});
```

### 缓存控制

```typescript
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 文件读取 [克罗伊斯贝格](https://www.npmjs.com/package/@kreuzberg/node) (单位:千美元)`@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 }`。 。 。 .

```typescript
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 中提取一个人类可读标题.

### 类型

```typescript
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 是什么？

支持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 和提交记录判断。

