增加unstructured处理策略

temp/scripts/README.md

@@ -1,103 +1,23 @@
 # Document Parser 使用说明
 
-一个模块化的文档解析器，支持将 DOCX、PPTX、XLSX 和 PDF 文件转换为 Markdown 格式。
+模块化文档解析器，将 DOCX、PPTX、XLSX、PDF 文件转换为 Markdown 格式。
 
-## 概述
+每种文档类型配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。不安装任何第三方库时，DOCX/PPTX/XLSX 仍可通过内置 XML 原生解析工作（PDF 至少需要 pypdf）。
 
-该解析器按优先级尝试多种解析方法，确保最大兼容性：
-
-1. **Docling** (docling.document_converter) - 通用解析方案，优先覆盖 DOCX/PPTX/XLSX/PDF 并内置 OCR 能力
-2. **pypandoc-binary** (DOCX 专用，内置 Pandoc) - 生成结构化 Markdown
-3. **MarkItDown** (微软官方库) - 推荐使用，格式规范
-4. **python-docx / python-pptx / pandas** (成熟的 Python 库) - 输出最详细
-5. **unstructured / pypdf** (成熟的 PDF 库) - PDF 专用
-6. **XML 原生解析** (备选方案) - 无需依赖
-
-脚本会按照上述优先级依次尝试各解析器，前面的失败后自动回退到下一个，因此建议安装该文档类型对应的所有解析器依赖，以获得最佳兼容性。
-
-### 特性
-
-- 支持 DOCX、PPTX、XLSX 和 PDF 格式
-- 自动检测文件类型和有效性
-- 保留文本格式（粗体、斜体、下划线）
-- Docling 作为第一优先解析器，单一依赖即可覆盖全部格式并自动调用 OCR
-- 提取表格并转换为 Markdown 格式
-- 提取列表并保留层级结构
-- 多种输出模式（字数、行数、标题、搜索等）
-- 内容过滤和规范化
-- 模块化设计，易于维护和扩展
-
-## 文件结构
-
-```
-scripts/
-├── common.py         # 公共函数和常量
-├── docx_parser.py    # DOCX 文件解析
-├── pptx_parser.py    # PPTX 文件解析
-├── xlsx_parser.py    # XLSX 文件解析
-├── pdf_parser.py     # PDF 文件解析
-├── parser.py     # 命令行入口
-└── README.md     # 本文档
-```
-
-## 依赖安装
-
-脚本基于标准 Python 环境运行（Python 3.6+），使用 `pip` 安装依赖。
-
-由于每种文档类型有多个解析器按优先级依次尝试，建议安装该类型对应的**所有**解析器依赖，这样当高优先级解析器失败时可以自动回退到下一个。
-
-### DOCX 依赖
-
-解析优先级：Docling → pypandoc-binary → MarkItDown → python-docx → XML 原生
+## 快速开始
 
 ```bash
-pip install docling pypandoc-binary "markitdown[docx]" python-docx
+# 最简运行（XML 原生解析，无需安装依赖）
+python parser.py report.docx
+
+# 安装推荐依赖后运行
+pip install "markitdown[docx]"
+python parser.py report.docx
+
+# 使用 uv 一键运行（自动安装依赖，无需手动 pip install）
+uv run --with "markitdown[docx]" parser.py report.docx
 ```
 
-### PPTX 依赖
-
-解析优先级：Docling → MarkItDown → python-pptx → XML 原生
-
-```bash
-pip install docling "markitdown[pptx]" python-pptx
-```
-
-### XLSX 依赖
-
-解析优先级：Docling → MarkItDown → pandas → XML 原生
-
-```bash
-pip install docling "markitdown[xlsx]" pandas tabulate
-```
-
-### PDF 依赖
-
-解析优先级：Docling → MarkItDown → unstructured → pypdf
-
-```bash
-pip install docling "markitdown[pdf]" unstructured pypdf
-```
-
-### 安装所有依赖
-
-如果需要处理全部文档类型，可以一次性安装所有解析器依赖：
-
-```bash
-pip install docling pypandoc-binary "markitdown[docx,pptx,xlsx,pdf]" python-docx python-pptx pandas tabulate unstructured pypdf
-```
-
-> 注意：MarkItDown 需要按文档类型安装对应的可选依赖，如 `markitdown[docx]`、`markitdown[pptx]`、`markitdown[xlsx]`、`markitdown[pdf]`，直接安装 `markitdown` 不会包含任何格式的解析支持。
-
-### 仅 XML 原生解析（无需安装依赖）
-
-如果不安装任何第三方库，脚本仍可通过内置的 XML 原生解析方式工作（DOCX/PPTX/XLSX），但输出格式和质量相对有限。
-
-### Docling 说明
-
-- Docling 是当前的默认第一优先级解析器，单一依赖即可获得统一输出。
-- 首次运行会自动下载 OCR/视觉模型到缓存目录，需保持网络连通。
-- 脚本会在 Docling 失败时自动回退至其他方案。
-
 ## 命令行用法
 
 ### 基本语法
@@ -106,363 +26,92 @@ pip install docling pypandoc-binary "markitdown[docx,pptx,xlsx,pdf]" python-docx
 python parser.py <file_path> [options]
 ```
 
-### 必需参数
+`file_path` 为 DOCX、PPTX、XLSX 或 PDF 文件路径（相对或绝对路径）。不带任何选项时输出完整 Markdown 内容。
 
-- `file_path`: DOCX、PPTX、XLSX 或 PDF 文件的路径（相对或绝对路径）
+### 参数说明
 
-### 可选参数（互斥组，一次只能使用一个）
+以下参数互斥，一次只能使用一个：
 
-| 参数 | 短选项 | 长选项 | 说明 |
-|------|---------|---------|------|
-| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
-| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
-| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行（1-6级） |
-| `-tc <name>` | `--title-content <name>` | 提取指定标题及其下级内容（不包含#号） |
-| `-s <pattern>` | `--search <pattern>` | 使用正则表达式搜索文档，返回所有匹配结果（用---分隔） |
+| 短选项 | 长选项 | 说明 |
+|--------|--------|------|
+| `-c` | `--count` | 输出解析后文档的总字符数（不含换行符） |
+| `-l` | `--lines` | 输出解析后文档的总行数 |
+| `-t` | `--titles` | 输出所有标题行（1-6 级，含 `#` 前缀） |
+| `-tc <name>` | `--title-content <name>` | 提取指定标题及其下级内容（`name` 不包含 `#` 号） |
+| `-s <pattern>` | `--search <pattern>` | 使用正则表达式搜索文档，返回匹配结果 |
 
-### 搜索上下文参数
+搜索辅助参数（与 `-s` 配合使用）：
 
-- `-n <num>` / `--context <num>`: 与 `-s` 配合使用，指定每个检索结果包含的前后行数（默认：2）
+| 短选项 | 长选项 | 说明 |
+|--------|--------|------|
+| `-n <num>` | `--context <num>` | 每个匹配结果包含的前后非空行数（默认：2） |
 
-## 使用示例
+### 退出码
 
-### 1. 输出完整 Markdown 内容
+| 退出码 | 含义 |
+|--------|------|
+| `0` | 解析成功 |
+| `1` | 错误（文件不存在、格式无效、所有解析器失败、标题未找到、正则无效或无匹配） |
+
+### 使用示例
+
+**输出完整 Markdown：**
 
 ```bash
-# 解析 DOCX
-python parser.py report.docx
-
-# 解析 PDF
-python parser.py report.pdf
-
-# 解析 PPTX
-python parser.py presentation.pptx
-
-# 解析 XLSX
-python parser.py data.xlsx
-
-# 输出到文件
-python parser.py report.docx > output.md
+python parser.py report.docx              # 输出到终端
+python parser.py report.docx > output.md   # 重定向到文件
 ```
 
-### 2. 统计文档信息
+**统计信息（`-c` / `-l`）：**
+
+输出单个数字，适合管道处理。
 
 ```bash
-# 统计字数
-python parser.py report.docx -c
-python parser.py report.pdf -c
+$ python parser.py report.docx -c
+8500
 
-# 统计行数
-python parser.py report.docx -l
-python parser.py report.pdf -l
+$ python parser.py report.docx -l
+215
 ```
 
-### 3. 提取标题
+**提取标题（`-t`）：**
+
+每行一个标题，保留 `#` 前缀和层级。PDF 通常不包含语义化标题层级。
 
 ```bash
-# 提取所有标题
-python parser.py report.docx -t
-python parser.py report.pdf -t
-
-# 输出示例（DOCX）：
+$ python parser.py report.docx -t
 # 第一章 概述
 ## 1.1 背景
 ## 1.2 目标
 # 第二章 实现
-
-# 输出示例（PDF - 注意：PDF 通常不包含明确的标题层级）：
-[内容提取成功，但 PDF 可能缺乏清晰的标题结构]
 ```
 
-### 4. 提取特定标题内容
+**提取标题内容（`-tc`）：**
+
+输出指定标题及其下级内容。如果文档中有多个同名标题，用 `---` 分隔。每段输出包含上级标题链。
 
 ```bash
-# 提取特定章节
-python parser.py report.docx -tc "第一章"
-python parser.py report.pdf -tc "第一章"
-
-# 输出该标题及其所有子内容
+$ python parser.py report.docx -tc "1.1 背景"
+# 第一章 概述
+## 1.1 背景
+这是背景的详细内容...
 ```
 
-### 5. 搜索文档内容
+**搜索（`-s`）：**
+
+支持 Python 正则表达式语法。多个匹配结果用 `---` 分隔。`-n` 控制上下文行数。
 
 ```bash
-# 搜索关键词
-python parser.py report.docx -s "测试"
-python parser.py report.pdf -s "测试"
-
-# 使用正则表达式
-python parser.py report.docx -s "章节\s+\d+"
-python parser.py report.pdf -s "章节\s+\d+"
-
-# 带上下文搜索（前后各2行）
-python parser.py report.docx -s "重要内容" -n 2
-python parser.py report.pdf -s "重要内容" -n 2
-
-# 输出示例：
----
-这是重要内容的前两行
-**重要内容**
-这是重要内容后两行
+$ python parser.py report.docx -s "测试" -n 1
+上一行内容
+包含**测试**关键词的行
+下一行内容
 ---
+另一处上一行
+另一处**测试**内容
+另一处下一行
 ```
 
-## 使用 uv 运行
-
-如果使用 [uv](https://github.com/astral-sh/uv) 作为 Python 环境管理工具，可以通过 `uv run --with` 自动安装依赖并运行脚本，无需手动 `pip install`。
-
-### 基本用法
-
-```bash
-# 无依赖运行（仅 XML 原生解析）
-uv run parser.py file.docx
-
-# 指定依赖运行
-uv run --with docling parser.py file.docx
-```
-
-### 按文档类型运行（安装所有解析器依赖）
-
-```bash
-# DOCX - 安装所有 DOCX 解析器
-uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py report.docx
-
-# PPTX - 安装所有 PPTX 解析器
-uv run --with docling --with "markitdown[pptx]" --with python-pptx parser.py presentation.pptx
-
-# XLSX - 安装所有 XLSX 解析器
-uv run --with docling --with "markitdown[xlsx]" --with pandas --with tabulate parser.py data.xlsx
-
-# PDF - 安装所有 PDF 解析器
-uv run --with docling --with "markitdown[pdf]" --with unstructured --with pypdf parser.py report.pdf
-```
-
-### 安装所有依赖运行
-
-```bash
-uv run --with docling --with pypandoc-binary --with "markitdown[docx,pptx,xlsx,pdf]" --with python-docx --with python-pptx --with pandas --with tabulate --with unstructured --with pypdf parser.py file.pdf
-```
-
-### 批量处理
-
-```bash
-# Linux/Mac
-for file in *.docx; do
-    uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py "$file" > "${file%.docx}.md"
-done
-
-# Windows PowerShell
-Get-ChildItem *.docx | ForEach-Object {
-    uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py $_.FullName > ($_.BaseName + ".md")
-}
-```
-
-## 解析器对比
-
-### DOCX 解析器
-
-DOCX 文件会按以下优先级依次尝试解析：
-
-1. Docling
-2. pypandoc-binary
-3. MarkItDown
-4. python-docx
-5. XML 原生
-
-| 解析器 | 优点 | 缺点 | 适用场景 |
-|---------|------|--------|---------|
-| **Docling** | • 单一依赖覆盖所有 Office/PDF 格式<br>• 自动带 OCR，复杂文档召回率高<br>• 输出 Markdown 结构稳定 | • 首次运行需下载较大的模型<br>• 运行时内存占用相对更高 | • 需要"一键完成"解析<br>• 需要 OCR/多模态支持 |
-| **pypandoc-binary** | • 自带 Pandoc，可直接使用<br>• 输出 Markdown 结构整洁<br>• 错误信息清晰易排查 | • 仅适用于 DOCX<br>• 依赖包体积较大 | • 需要标准化 Markdown 输出<br>• Docling 不可用时的首选 |
-| **MarkItDown** | • 格式规范<br>• 微软官方支持<br>• 兼容性好 | • 需要安装<br>• 输出较简洁 | • 需要标准格式输出<br>• 自动化文档处理 |
-| **python-docx** | • 输出最详细<br>• 保留完整结构<br>• 支持复杂样式 | • 需要安装<br>• 可能包含多余空行 | • 需要精确控制输出<br>• 分析文档结构 |
-| **XML 原生** | • 无需依赖<br>• 运行速度快<br>• 输出原始内容 | • 格式可能不统一<br>• 样式处理有限 | • 依赖不可用时<br>• 快速提取内容 |
-
-### PPTX 解析器
-
-PPTX 文件会按以下优先级依次尝试解析：Docling → MarkItDown → python-pptx → XML 原生。
-
-| 解析器 | 优点 | 缺点 | 适用场景 |
-|---------|------|--------|---------|
-| **Docling** | • 解析幻灯片文本、表格与图片 OCR<br>• 自动生成统一 Markdown，包含分页分隔符 | • 需要下载模型<br>• 细节控制少 | • 需要一次性转换全部幻灯片<br>• 有图片或扫描件的 PPTX |
-| **MarkItDown** | • 格式规范<br>• 自动添加 Slide 分隔<br>• 输出简洁 | • 需要安装<br>• 详细度较低 | • 快速预览幻灯片<br>• 提取主要内容 |
-| **python-pptx** | • 输出最详细<br>• 保留完整结构<br>• 支持层级列表 | • 需要安装<br>• 依赖私有 API | • 需要完整内容<br>• 分析演示结构 |
-| **XML 原生** | • 无需依赖<br>• 结构化输出<br>• 运行速度快 | • 格式可能不统一<br>• 幻灯片分组简单 | • 依赖不可用时<br>• 结构化提取 |
-
-### XLSX 解析器
-
-XLSX 文件会按以下优先级依次尝试解析：Docling → MarkItDown → pandas → XML 原生。
-
-| 解析器 | 优点 | 缺点 | 适用场景 |
-|---------|------|--------|---------|
-| **Docling** | • 单次遍历导出全部工作表为 Markdown<br>• 自动处理合并单元格/图像 OCR | • 需要下载模型<br>• 对极大体积表可能较慢 | • 快速完成全表转 Markdown<br>• 含扫描图片的表格 |
-| **MarkItDown** | • 格式规范<br>• 支持多工作表<br>• 输出简洁 | • 需要安装<br>• 详细度较低 | • 快速预览表格<br>• 提取主要内容 |
-| **pandas** | • 功能强大<br>• 支持复杂表格<br>• 数据处理灵活 | • 需要安装<br>• 依赖较多 | • 数据分析<br>• 复杂表格处理 |
-| **XML 原生** | • 无需依赖<br>• 运行速度快<br>• 支持所有单元格类型 | • 格式可能不统一<br>• 无数据处理能力 | • 依赖不可用时<br>• 快速提取内容 |
-
-### PDF 解析器
-
-PDF 文件会按以下优先级依次尝试解析：Docling → MarkItDown → unstructured → pypdf。
-
-| 解析器 | 优点 | 缺点 | 适用场景 |
-|---------|------|--------|---------|
-| **Docling** | • 内置 RapidOCR，可处理扫描版 PDF<br>• 输出结构化 Markdown，包含表格/图片占位 | • 模型下载体积大<br>• OCR 耗时较长 | • 需要 OCR、表格/图片识别<br>• 多语言 PDF |
-| **MarkItDown** | • 格式规范<br>• 微软官方支持<br>• 兼容性好 | • 需要安装 `markitdown[pdf]`<br>• 输出较简洁 | • 需要标准格式输出<br>• 自动化文档处理 |
-| **unstructured** | • 功能强大<br>• 支持表格提取<br>• 文本组织性好 | • 需要安装<br>• 可能包含页码标记 | • 需要完整内容<br>• 分析文档结构 |
-| **pypdf** | • 轻量级<br>• 速度快<br>• 安装简单 | • 需要安装<br>• 功能相对简单 | • 快速提取内容<br>• 简单文本提取 |
-
-## 输出格式
-
-### Markdown 输出结构
-
-```markdown
-# 标题 1 (一级)
-
-正文段落
-
-## 标题 2 (二级)
-
-- 列表项 1
-- 列表项 2
-
-1. 有序列表项 1
-2. 有序列表项 2
-
-| 列1 | 列2 | 列3 |
-|------|------|------|
-| 数据1 | 数据2 | 数据3 |
-
-**粗体文本** *斜体文本* <u>下划线文本</u>
-```
-
-### PPTX 特有格式
-
-```markdown
-## Slide 1
-
-幻灯片 1 的内容
-
-## Slide 2
-
-表格内容
-
-幻灯片 2 的内容
-
----
-```
-
-### XLSX 特有格式
-
-```markdown
-# Excel数据转换结果
-
-来源: /path/to/file.xlsx
-
-## Sheet1
-
-| 列1 | 列2 | 列3 |
-|------|------|------|
-| 数据1 | 数据2 | 数据3 |
-```
-
-### PDF 特有格式
-
-```markdown
-[PDF 文件的纯文本内容，按段落提取]
-
-中电信粤亿迅〔2023〕3号
-
-关于印发关于印发关于印发关于印发《《《《广东亿迅科技有限公司员工
-
-[注：PDF 通常不包含明确的标题层级结构，内容以文本流形式呈现]
-```
-
-### 标题格式
-
-- 标题使用 Markdown 井号语法：`#` 到 `######`（1-6级）
-- 标题名称不包含井号
-- 段落通过空行分隔
-
-### 表格格式
-
-```markdown
-| 列1 | 列2 | 列3 |
-|------|------|------|
-| 数据1 | 数据2 | 数据3 |
-```
-
-### 列表格式
-
-- 无序列表：使用 `-` 前缀
-- 有序列表：使用 `1.` 前缀
-- 支持多层缩进（使用空格）
-
-## 内容处理
-
-### 自动处理
-
-1. **图片移除**：自动删除 Markdown 图片语法
-2. **空行规范化**：合并连续空行为单个空行
-3. **样式标签过滤**：移除 HTML span 标签
-4. **RGB 颜色过滤**：移除颜色代码行
-
-### 过滤规则（filter_markdown_content）
-
-- 保留：文本、表格、列表、基本格式
-- 移除：
-  - HTML 注释 (`<!-- ... -->`)
-  - Markdown 图片 (`![alt](url)`)
-  - HTML 图片标签 (`<img>`, `</img>`)
-  - 媒体链接 (`[text](file.ext)`)
-  - RGB 颜色代码 (`R:255 G:255 B:255`)
-- 标准化：多余空格合并为单个空格
-
-## 错误处理
-
-### 文件验证
-
-```bash
-# 文件不存在
-错误: 文件不存在: missing.docx
-
-# 无效格式
-错误: 不是有效的 DOCX、PPTX、XLSX 或 PDF 格式: invalid.txt
-```
-
-### 解析器回退
-
-脚本按优先级尝试解析器，如果失败则自动尝试下一个：
-
-```
-所有解析方法均失败:
-- Docling: 库未安装
-- pypandoc-binary: 库未安装
-- MarkItDown: 库未安装
-- python-docx: 解析失败: ...
-- XML 原生解析: document.xml 不存在或无法访问
-```
-
-**PDF 回退示例**:
-
-```
-所有解析方法均失败:
-- Docling: 库未安装
-- MarkItDown: MarkItDown 解析失败: ...
-- unstructured: unstructured 库未安装
-- pypdf: pypdf 库未安装
-```
-
-### 搜索错误
-
-```bash
-# 无效正则
-错误: 正则表达式无效或未找到匹配: '[invalid'
-
-# 标题未找到
-错误: 未找到标题 '不存在的标题'
-```
-
-## 高级用法
-
 ### 批量处理
 
 ```bash
@@ -480,40 +129,285 @@ Get-ChildItem *.docx | ForEach-Object {
 ### 管道使用
 
 ```bash
-# 进一步处理 Markdown 输出
+# 过滤包含关键词的行
 python parser.py report.docx | grep "重要" > important.md
 
-# 统计处理
-python parser.py report.docx -l | awk '{print $1}'
+# 统计含表格行数
+python parser.py data.xlsx | grep -c "^|"
 ```
 
+## 安装
+
+脚本基于 Python 3.6+ 运行。每种文档类型有多个解析器按优先级依次尝试，建议安装对应类型的**所有**依赖以获得最佳兼容性。也可以只安装部分依赖，脚本会自动选择可用的解析器。
+
+### DOCX
+
+优先级：Docling → unstructured → pypandoc-binary → MarkItDown → python-docx → XML 原生
+
+```bash
+# pip
+pip install docling "unstructured[docx]" markdownify pypandoc-binary "markitdown[docx]" python-docx
+
+# uv（一键运行，无需预安装）
+uv run --with docling --with "unstructured[docx]" --with markdownify --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py report.docx
+```
+
+### PPTX
+
+优先级：Docling → unstructured → MarkItDown → python-pptx → XML 原生
+
+```bash
+# pip
+pip install docling "unstructured[pptx]" markdownify "markitdown[pptx]" python-pptx
+
+# uv
+uv run --with docling --with "unstructured[pptx]" --with markdownify --with "markitdown[pptx]" --with python-pptx parser.py presentation.pptx
+```
+
+### XLSX
+
+优先级：Docling → unstructured → MarkItDown → pandas → XML 原生
+
+```bash
+# pip
+pip install docling "unstructured[xlsx]" markdownify "markitdown[xlsx]" pandas tabulate
+
+# uv
+uv run --with docling --with "unstructured[xlsx]" --with markdownify --with "markitdown[xlsx]" --with pandas --with tabulate parser.py data.xlsx
+```
+
+### PDF
+
+优先级：Docling → unstructured → MarkItDown → pypdf
+
+```bash
+# pip - 基础文本提取（使用 fast 策略，无需 OCR）
+pip install docling "unstructured[pdf]"" markdownify "markitdown[pdf]" pypdf
+
+# pip - OCR 版面分析（使用 hi_res 策略 + PaddleOCR）
+pip install docling "unstructured[pdf]" unstructured-paddleocr "paddlepaddle==2.6.2" ml-dtypes markdownify "markitdown[pdf]" pypdf
+
+# uv - 基础文本提取
+uv run --with docling --with "unstructured[pdf]" --with markdownify --with "markitdown[pdf]" --with pypdf parser.py report.pdf
+
+# uv - OCR 版面分析
+uv run --with docling --with "unstructured[pdf]" --with unstructured-paddleocr --with "paddlepaddle==2.6.2" --with ml-dtypes --with markdownify --with "markitdown[pdf]" --with pypdf parser.py report.pdf
+```
+
+> PDF 无内置 XML 原生解析，至少需要安装 pypdf。unstructured 的 `hi_res` 策略需要额外安装 `unstructured-paddleocr`、`paddlepaddle==2.6.2`、`ml-dtypes`，不可用时自动回退 `fast` 策略。PaddlePaddle 必须锁定 2.x 版本，3.x 在 Windows 上有 OneDNN 兼容问题。
+>
+
+### 安装所有依赖
+
+```bash
+# pip - 基础文本提取（不包含 PDF OCR）
+pip install docling "unstructured[docx,pptx,xlsx,pdf]" markdownify pypandoc-binary "markitdown[docx,pptx,xlsx]" python-docx python-pptx pandas tabulate pypdf
+
+# pip - 完整版（包含 PDF OCR）
+pip install docling "unstructured[docx,pptx,xlsx,pdf]" markdownify unstructured-paddleocr "paddlepaddle==2.6.2" ml-dtypes pypandoc-binary "markitdown[docx,pptx,xlsx,pdf]" python-docx python-pptx pandas tabulate pypdf
+
+# uv - 基础文本提取
+uv run --with docling --with "unstructured[docx,pptx,xlsx,pdf]" --with markdownify --with pypandoc-binary --with "markitdown[docx,pptx,xlsx]" --with python-docx --with python-pptx --with pandas --with tabulate --with pypdf parser.py file.docx
+
+# uv - 完整版（包含 PDF OCR）
+uv run --with docling --with "unstructured[docx,pptx,xlsx,pdf]" --with markdownify --with unstructured-paddleocr --with "paddlepaddle==2.6.2" --with ml-dtypes --with pypandoc-binary --with "markitdown[docx,pptx,xlsx,pdf]" --with python-docx --with python-pptx --with pandas --with tabulate --with pypdf parser.py file.docx
+```
+
+### 依赖说明
+
+**MarkItDown**：需要按文档类型安装可选依赖，直接 `pip install markitdown` 不包含任何格式支持。
+
+```bash
+pip install "markitdown[docx]"        # DOCX
+pip install "markitdown[pptx]"        # PPTX
+pip install "markitdown[xlsx]"        # XLSX
+pip install "markitdown[pdf]"         # PDF
+pip install "markitdown[docx,pptx,xlsx,pdf]"  # 全部
+```
+
+**Docling**：首次运行会自动下载 OCR/视觉模型到缓存目录，需保持网络连通。
+
+**unstructured**：需同时安装 `markdownify`。支持按文档类型安装特定 extras 以减少依赖量：
+
+- `unstructured[docx]` - DOCX 处理（仅需 `python-docx`）
+- `unstructured[pptx]` - PPTX 处理（仅需 `python-pptx`）
+- `unstructured[xlsx]` - XLSX 处理（需 `openpyxl`、`xlrd`、`pandas` 等）
+- `unstructured` - 基础包（用于 PDF fast 策略）
+- `unstructured[all-docs]` - 所有文档类型（包含大量不必要的 OCR/视觉依赖）
+
+**PaddleOCR**：不能用 `paddleocr` 代替 `unstructured-paddleocr`，unstructured 查找的模块名是 `unstructured_paddleocr`。
+
+## 输出格式
+
+### Markdown 文档结构
+
+无选项时输出完整 Markdown，包含以下元素：
+
+```markdown
+# 一级标题
+
+正文段落
+
+## 二级标题
+
+- 无序列表项
+- 无序列表项
+
+1. 有序列表项
+2. 有序列表项
+
+| 列1 | 列2 | 列3 |
+|------|------|------|
+| 数据1 | 数据2 | 数据3 |
+
+**粗体** *斜体* <u>下划线</u>
+```
+
+### 各格式特有结构
+
+**PPTX** — 每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔：
+
+```markdown
+## Slide 1
+
+幻灯片 1 的内容
+
+---
+
+## Slide 2
+
+幻灯片 2 的内容
+
+---
+```
+
+**XLSX** — 以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现：
+
+```markdown
+# Excel数据转换结果
+
+## Sheet1
+
+| 列1 | 列2 | 列3 |
+|------|------|------|
+| 数据1 | 数据2 | 数据3 |
+
+## Sheet2
+
+| 列A | 列B |
+|------|------|
+| 值1 | 值2 |
+```
+
+**PDF** — 纯文本流，通常不包含语义化标题层级（PDF 是版面描述格式，标题只是视觉样式）。使用 Docling 或 unstructured hi_res 策略可通过版面分析识别部分标题，但准确度取决于排版质量。
+
+### 内容自动处理
+
+输出前会自动进行以下处理：
+
+| 处理 | 说明 |
+|------|------|
+| 图片移除 | 删除 `![alt](url)` 语法 |
+| 空行规范化 | 连续多个空行合并为一个 |
+| RGB 噪声过滤 | 移除 `R:255 G:128 B:0` 格式的颜色值行 |
+| 页码噪声过滤 | 移除 `— 3 —` 格式的页码行 |
+| 页眉/页脚过滤 | unstructured 解析器自动跳过 Header/Footer 元素 |
+
+## 错误处理
+
+### 错误消息
+
+```bash
+# 文件不存在
+$ python parser.py missing.docx
+错误: 文件不存在: missing.docx
+
+# 格式无效
+$ python parser.py readme.txt
+错误: 不是有效的 DOCX、PPTX、XLSX 或 PDF 格式: readme.txt
+
+# 所有解析器失败（DOCX 示例）
+$ python parser.py report.docx
+所有解析方法均失败:
+- Docling: docling 库未安装
+- unstructured: unstructured 库未安装
+- pypandoc-binary: pypandoc-binary 库未安装
+- MarkItDown: MarkItDown 库未安装
+- python-docx: python-docx 库未安装
+- XML 原生解析: document.xml 不存在或无法访问
+
+# 标题未找到
+$ python parser.py report.docx -tc "不存在的标题"
+错误: 未找到标题 '不存在的标题'
+
+# 无效正则或无匹配
+$ python parser.py report.docx -s "[invalid"
+错误: 正则表达式无效或未找到匹配: '[invalid'
+```
+
+### 解析器回退机制
+
+脚本按优先级依次尝试各解析器。每个解析器失败后记录原因（库未安装 / 解析失败 / 文档为空），然后自动尝试下一个。全部失败时输出汇总信息并以退出码 1 退出。
+
+## 解析器对比
+
+### DOCX
+
+| 解析器 | 优点 | 缺点 | 适用场景 |
+|---------|------|--------|---------|
+| **Docling** | 单一依赖覆盖全格式；自动 OCR；输出结构稳定 | 首次需下载模型；内存占用较高 | 一键解析；需要 OCR |
+| **unstructured** | 元素类型感知；自动过滤噪声；HTML 表格转 Markdown | 需 `unstructured[docx]` / `[pptx]` / `[xlsx]` + `markdownify` | 结构化输出；表格转换 |
+| **pypandoc-binary** | 自带 Pandoc；输出整洁；错误信息清晰 | 仅 DOCX；包体积大 | 标准化 Markdown |
+| **MarkItDown** | 微软官方；格式规范 | 输出简洁 | 标准格式；自动化处理 |
+| **python-docx** | 输出最详细；保留完整结构；支持复杂样式 | 可能含多余空行 | 精确控制输出 |
+| **XML 原生** | 无需依赖；速度快 | 样式处理有限 | 依赖不可用时兜底 |
+
+### PPTX
+
+| 解析器 | 优点 | 缺点 | 适用场景 |
+|---------|------|--------|---------|
+| **Docling** | 文本/表格/图片 OCR；统一 Markdown | 需下载模型 | 一次性转换；含图片的 PPTX |
+| **unstructured** | 元素感知；过滤 RGB 噪声；表格转换 | 需 `unstructured[pptx]` + `markdownify` | 结构化输出 |
+| **MarkItDown** | 自动 Slide 分隔；简洁 | 详细度低 | 快速预览 |
+| **python-pptx** | 输出最详细；支持层级列表 | 依赖私有 API | 完整内容提取 |
+| **XML 原生** | 无需依赖；速度快 | 分组简单 | 依赖不可用时兜底 |
+
+### XLSX
+
+| 解析器 | 优点 | 缺点 | 适用场景 |
+|---------|------|--------|---------|
+| **Docling** | 全表导出；处理合并单元格/图像 OCR | 大表可能慢 | 快速全表转换 |
+| **unstructured** | 元素感知；过滤噪声；表格转换 | 需 `unstructured[xlsx]` + `markdownify` | 结构化输出 |
+| **MarkItDown** | 支持多工作表；简洁 | 详细度低 | 快速预览 |
+| **pandas** | 功能强大；支持复杂表格 | 需 `pandas` + `tabulate` | 数据分析 |
+| **XML 原生** | 无需依赖；支持所有单元格类型 | 无数据处理能力 | 依赖不可用时兜底 |
+
+### PDF
+
+| 解析器 | 优点 | 缺点 | 适用场景 |
+|---------|------|--------|---------|
+| **Docling** | 内置 OCR；结构化 Markdown；表格/图片占位 | 模型体积大；OCR 耗时长 | 扫描版 PDF；多语言 |
+| **unstructured** | hi_res 版面分析 + PaddleOCR；元素感知；自动回退 fast | 需额外 PaddleOCR 依赖 | 版面分析；OCR |
+| **MarkItDown** | 微软官方；格式规范 | 输出简洁 | 标准格式 |
+| **pypdf** | 轻量；速度快；安装简单 | 功能简单 | 快速文本提取 |
+
 ## 常见问题
 
-### Q: 为什么有些内容没有提取到？
+### 为什么有些内容没有提取到？
 
-A: 不同解析器的输出详细度不同：
+不同解析器输出详细度不同。优先级高的解析器不一定输出最详细——Docling 和 unstructured 侧重结构化，python-docx/python-pptx 输出最详细但不做噪声过滤。建议安装对应类型的所有依赖，脚本会自动选择优先级最高的可用解析器。
 
-- `python-docx` / `python-pptx` 输出最详细
-- `MarkItDown` 输出较简洁
-- `XML 原生` 输出原始内容
+### PDF 文件没有标题层级？
 
-建议安装该文档类型对应的所有解析器依赖，脚本会自动按优先级选择最佳可用解析器。
+PDF 是版面描述格式，不包含语义化标题结构。Docling 或 unstructured hi_res 策略可通过版面分析识别部分标题，准确度取决于排版质量。建议用 `-s` 搜索定位内容，或用 `-c` / `-l` 了解文档规模。
 
-### Q: PDF 文件没有标题层级？
+### 表格格式不正确？
 
-A: PDF 是一种版面描述格式，通常不包含语义化的标题层级结构。与 DOCX/PPTX 不同，PDF 中的标题只是视觉上的文本样式，解析器无法准确识别标题层级。建议：
+XML 原生解析器对复杂表格（合并单元格、嵌套表格）支持有限。安装 Docling、unstructured 或对应的专用库可获得更好的表格处理效果。
 
-- 使用搜索功能查找特定内容
-- 使用 `-l` 统计行数了解文档长度
-- 使用 `-c` 统计字数了解文档规模
+### 中文显示乱码？
 
-### Q: 表格格式不正确？
-
-A: 确保原始文档中的表格结构完整。XML 解析器可能无法处理复杂表格。
-
-### Q: 中文显示乱码？
-
-A: 脚本输出使用 UTF-8 编码。确保终端支持 UTF-8：
+脚本输出 UTF-8 编码，确保终端支持：
 
 ```bash
 # Linux/Mac
@@ -523,96 +417,23 @@ export LANG=en_US.UTF-8
 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 ```
 
-### Q: 如何只使用特定解析器？
+### 如何只使用特定解析器？
 
-A: 当前版本自动选择最佳可用解析器。可以通过注释代码中的解析器列表来限制，或安装/卸载特定依赖。
+当前版本不支持指定解析器，总是按优先级自动选择。可以通过只安装目标解析器的依赖来间接控制——未安装的解析器会被跳过。
 
-### Q: MarkItDown 提示依赖未安装？
+### 大文件处理慢？
 
-A: MarkItDown 需要按文档类型安装对应的可选依赖，直接安装 `markitdown` 不会包含任何格式支持：
+Docling 和 unstructured 对大文件较慢（尤其是 OCR）。如果只需要快速提取文本，可以只安装轻量依赖（如 pypdf、python-docx），让脚本回退到这些解析器。DOCX/PPTX/XLSX 不安装任何依赖时使用 XML 原生解析，速度最快。
 
-```bash
-# 错误 - 不包含任何格式支持
-pip install markitdown
+## 文件结构
 
-# 正确 - 按需安装对应格式
-pip install "markitdown[docx]"
-pip install "markitdown[pptx]"
-pip install "markitdown[xlsx]"
-pip install "markitdown[pdf]"
-
-# 或一次性安装所有格式
-pip install "markitdown[docx,pptx,xlsx,pdf]"
 ```
-
-### Q: 大文件处理慢？
-
-A: 大文件建议使用 XML 原生解析（最快），或在脚本外部处理。
-
-## 性能参考
-
-基于测试文件的参考数据：
-
-> Docling 作为统一入口时，整体性能受 OCR/模型下载影响：首次运行略慢，缓存后与 MarkItDown 同量级，但在 PDF 场景中由于 OCR 会稍慢一些。
-
-### DOCX (test.docx)
-
-| 解析器 | 字符数 | 行数 | 相对速度 |
-|---------|--------|------|---------|
-| MarkItDown | ~8,500 | ~123 | 快 |
-| python-docx | ~8,500 | ~123 | 中 |
-| XML 原生 | ~8,500 | ~123 | 快 |
-
-### PPTX (test.pptx)
-
-| 解析器 | 字符数 | 行数 | 相对速度 |
-|---------|--------|------|---------|
-| MarkItDown | ~2,500 | ~257 | 快 |
-| python-pptx | ~2,500 | ~257 | 中 |
-| XML 原生 | ~2,500 | ~257 | 快 |
-
-### XLSX (test.xlsx)
-
-| 解析器 | 字符数 | 行数 | 相对速度 |
-|---------|--------|------|---------|
-| MarkItDown | ~6,000 | ~109 | 快 |
-| pandas | ~6,000 | ~109 | 中 |
-| XML 原生 | ~6,000 | ~109 | 快 |
-
-### PDF (test.pdf)
-
-| 解析器 | 字符数 | 行数 | 相对速度 |
-|---------|--------|------|---------|
-| MarkItDown | ~8,200 | ~1,120 | 快 |
-| unstructured | ~8,400 | ~600 | 中 |
-| pypdf | ~8,400 | ~600 | 快 |
-
-## 代码风格
-
-脚本遵循以下代码风格：
-
-- Python 3.6+ 兼容
-- 遵循 PEP 8 规范
-- 所有公共 API 函数添加类型提示
-- 字符串优先内联使用，不提取为常量，除非被使用超过3次
-- 其他被多次使用的对象根据具体情况可考虑被提取为常量（如正则表达式）
-- 模块级和公共 API 函数保留文档字符串
-- 内部辅助函数不添加文档字符串（函数名足够描述）
-- 变量命名清晰，避免单字母变量名
-
-## 许可证
-
-脚本遵循 PEP 8 规范，Python 3.6+ 兼容。
-
-## 更新日志
-
-### 最新版本
-
-- 新增 Docling 解析路径，统一处理 DOCX/PPTX/XLSX/PDF，并自动具备 OCR 能力
-- DOCX 解析新增 pypandoc-binary 方案并设置为最高优先级
-- 将单体脚本拆分为模块化结构（common.py, docx.py, pptx.py, xlsx.py, parser.py）
-- 添加 XLSX 文件支持
-- 添加 PDF 文件支持（MarkItDown、unstructured、pypdf）
-- 增强错误处理（文件存在性检查、无效格式检测）
-- 完善文档和示例
-- 所有模块通过语法检查和功能测试
+scripts/
+├── common.py         # 公共函数和常量
+├── docx_parser.py    # DOCX 文件解析
+├── pptx_parser.py    # PPTX 文件解析
+├── xlsx_parser.py    # XLSX 文件解析
+├── pdf_parser.py     # PDF 文件解析
+├── parser.py         # 命令行入口
+└── README.md         # 本文档
+```