---
name: office-text-extract
description: "Extract text from .docx/.pptx/.xlsx/.pdf without pandoc."
version: 2.0.0
author: Hermes Agent
license: Apache-2.0 (docx/pptx/xlsx engine from genspark-ai/genoffice)
metadata:
  hermes:
    tags: [office, docx, pptx, xlsx, pdf, text-extraction, headless, genoffice, pymupdf]
    related_skills: [docx, xlsx, powerpoint, pdf, markdown-to-docx, ocr-and-documents]
---

# Office Text Extraction (headless)

从 `.docx` / `.pptx` / `.xlsx` / `.pdf` 提取纯文本，**无需 pandoc / LibreOffice**。统一入口一个命令覆盖四种格式：

- `.docx` / `.pptx` / `.xlsx` → GenOffice 引擎（github.com/genspark-ai/genoffice，Apache-2.0）的 `file-parse` + `docx-engine`，esbuild 打成单文件 Node CLI
- `.pdf`（文本型）→ pymupdf（Python）
- `.pdf`（扫描件/图片型，需 OCR）→ marker-pdf，见 `ocr-and-documents` 技能

## 何时用

- 需要**读取**已有 Office/PDF 文档内容（本机无 pandoc/LibreOffice 时尤其适用）
- 给 AI 附加 Office/PDF 附件前先转文本
- 快速抽取正文做检索、摘要、diff

## 工具位置

```
scripts/office-extract            # 统一入口（bash，按扩展名分发）★ 主入口
scripts/genoffice-extract.mjs     # docx/pptx/xlsx 引擎（Node，单文件，~1MB）
scripts/extract_pdf.py            # pdf 文本提取（pymupdf）
scripts/build.sh                  # 可复现重建 Node 引擎（从 genoffice 源重新打包）
```

要求：Node 18+（docx/pptx/xlsx）+ `pymupdf`（pdf）。

## 用法

```bash
BIN=scripts/office-extract

# 统一入口，四种格式都行（纯文本到 stdout）
"$BIN" /path/to/file.docx
"$BIN" /path/to/file.pdf

# JSON 模式（{ok,kind,ext,text|error}），便于程序化处理
"$BIN" --json /path/to/file.xlsx
```

也可以直接调底层：`node scripts/genoffice-extract.mjs <docx|pptx|xlsx>`、`python3 scripts/extract_pdf.py <pdf>`。

## 输出格式

- **docx**：标题转 `#`/`##`（按级别），列表项转 `-`，有序列表转 `1. 2. 3.`，表格行转 `cell1 | cell2 | ...`，正文段落原样。接近 Markdown。
- **pptx**：每页一段 `## Slide N`，每段文字一行，按 slide 编号升序。
- **xlsx**：每个工作表一段 `# SheetName`，行内单元格用 ` | ` 连接（空单元格占位对齐），inlineStr/sharedStrings/布尔/数字均正确处理。
- **pdf**：每页文本用 `\n\n` 分隔，中文/多页正常。
- 中文、ASCII 图、多列表格均无损（docx/pdf 实测通过）。

## 坑

1. **PDF 分两类**：
   - 文本型 PDF（有嵌入文本层）→ `extract_pdf.py`（pymupdf），即时返回。
   - 扫描件/图片型 PDF（无文本层）→ pymupdf 提取为空，脚本会提示改用 marker-pdf OCR（`ocr-and-documents` 技能的 `extract_marker.py`）。marker-pdf 需 ~5GB（PyTorch+模型）且首次运行下载模型。
2. **只有提取，没有生成/编辑**：本工具只读文本。生成 docx 用 `docx` 技能（docx-js）、md→docx 用 `markdown-to-docx` 技能；编辑已有 docx 的批注/修订/图表需 `docx-engine` 的 patch 能力（未封装）。
3. **Node 版本**：bundle target 是 node18，老环境可能不兼容。
4. **大文件**：docx 解析会展开整个 OOXML；超大文件（>50MB）内存占用高。

## 重建 Node 引擎（genoffice 上游更新时）

```bash
bash scripts/build.sh
```

`build.sh` 从 genoffice main 分支重新下载 `file-parse` + `docx-engine` 源码、装依赖、esbuild 打包，覆盖 `scripts/genoffice-extract.mjs`。需网络可达 raw.githubusercontent.com（若被墙，先建 SOCKS5 隧道并设 `PROXY=socks5h://127.0.0.1:1080`）。

## 迁移到其他机器 / pipeline-app

- **docx/pptx/xlsx**：`genoffice-extract.mjs` 是纯 Node 单文件工具，**只需 Node 18+**，零依赖。拷过去 `node <path> <file>` 即用。
- **pdf**：需要目标机 `pip install pymupdf`（~25MB，一条命令）。
- **pdf OCR**：需要 `pip install marker-pdf` + ~5GB 磁盘（首次运行下载模型）。

三者迁移成本递增：docx/pptx/xlsx（零依赖）< pdf 文本（pip 装 pymupdf）< pdf OCR（5GB）。

- 若 pipeline-app 服务器有 Node：拷 `genoffice-extract.mjs` 即可在服务器 shell 用。
- 若要 pipeline-app 的 DSPY/前端调用：另写一个薄 Sage 模块，用 `subprocess`/`child_process` 调对应 CLI 取 stdout（后续集成决策，本 skill 不涉及）。