From 6c003d73f3e2b4c1338fa9093e29b2d94cd6b347 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Sun, 8 Mar 2026 13:52:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20delta=20specs=20?= =?UTF-8?q?=E5=88=B0=E4=B8=BB=20specs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从归档的 unify-document-readers change 同步 delta specs 到主 specs 目录。 新增 specs： - document-reading - 统一文档读取核心能力 - docx-reader - DOCX 文档解析能力 - xlsx-reader - XLSX 文档解析能力 - pptx-reader - PPTX 文档解析能力 - pdf-reader - PDF 文档解析能力（含 OCR） - html-reader - HTML/URL 文档解析能力 --- openspec/specs/document-reading/spec.md | 141 +++++++++++++++++ openspec/specs/docx-reader/spec.md | 113 ++++++++++++++ openspec/specs/html-reader/spec.md | 192 ++++++++++++++++++++++++ openspec/specs/pdf-reader/spec.md | 120 +++++++++++++++ openspec/specs/pptx-reader/spec.md | 98 ++++++++++++ openspec/specs/xlsx-reader/spec.md | 98 ++++++++++++ 6 files changed, 762 insertions(+) create mode 100644 openspec/specs/document-reading/spec.md create mode 100644 openspec/specs/docx-reader/spec.md create mode 100644 openspec/specs/html-reader/spec.md create mode 100644 openspec/specs/pdf-reader/spec.md create mode 100644 openspec/specs/pptx-reader/spec.md create mode 100644 openspec/specs/xlsx-reader/spec.md diff --git a/openspec/specs/document-reading/spec.md b/openspec/specs/document-reading/spec.md new file mode 100644 index 0000000..468f370 --- /dev/null +++ b/openspec/specs/document-reading/spec.md @@ -0,0 +1,141 @@ +## Purpose + +统一文档读取核心能力，包含 CLI 入口、解析调度、Markdown 后处理。 + +## Requirements + +### Requirement: 统一 CLI 入口 +系统 SHALL 提供 lyxy_document_reader.py 作为统一的命令行入口，支持处理所有文档类型。 + +#### Scenario: 调用 CLI 帮助信息 +- **WHEN** 用户执行 `uv run python lyxy_document_reader.py --help` +- **THEN** 系统显示完整的命令行参数帮助信息 + +#### Scenario: CLI 接受输入路径 +- **WHEN** 用户执行 `uv run python lyxy_document_reader.py ` +- **THEN** 系统识别输入类型并解析文档 + +### Requirement: 输入类型自动识别 +系统 SHALL 自动识别输入类型，包括 URL 和本地文件。 + +#### Scenario: 识别 HTTP URL +- **WHEN** 输入以 `http://` 或 `https://` 开头 +- **THEN** 系统识别为 URL，使用 html-reader 处理 + +#### Scenario: 识别 DOCX 文件 +- **WHEN** 输入文件扩展名为 .docx 或 .doc，或文件内容为 OOXML Word 格式 +- **THEN** 系统识别为 DOCX，使用 docx-reader 处理 + +#### Scenario: 识别 XLSX 文件 +- **WHEN** 输入文件扩展名为 .xlsx、.xls 或 .xlsm，或文件内容为 OOXML Excel 格式 +- **THEN** 系统识别为 XLSX，使用 xlsx-reader 处理 + +#### Scenario: 识别 PPTX 文件 +- **WHEN** 输入文件扩展名为 .pptx 或 .ppt，或文件内容为 OOXML PowerPoint 格式 +- **THEN** 系统识别为 PPTX，使用 pptx-reader 处理 + +#### Scenario: 识别 PDF 文件 +- **WHEN** 输入文件扩展名为 .pdf，或文件头为 %PDF +- **THEN** 系统识别为 PDF，使用 pdf-reader 处理 + +#### Scenario: 识别 HTML 文件 +- **WHEN** 输入文件扩展名为 .html、.htm 或 .xhtml +- **THEN** 系统识别为 HTML，使用 html-reader 处理 + +### Requirement: 输出完整 Markdown +系统 SHALL 能够输出解析后的完整 Markdown 内容。 + +#### Scenario: 无查询参数时输出完整内容 +- **WHEN** 用户不使用任何查询参数（-c/-l/-t/-tc/-s） +- **THEN** 系统输出完整的 Markdown 文档内容 + +### Requirement: 字数统计 +系统 SHALL 支持统计解析后文档的总字数。 + +#### Scenario: 使用 -c 参数统计字数 +- **WHEN** 用户使用 `-c` 或 `--count` 参数 +- **THEN** 系统输出解析后文档的总字数（不含换行符） + +### Requirement: 行数统计 +系统 SHALL 支持统计解析后文档的总行数。 + +#### Scenario: 使用 -l 参数统计行数 +- **WHEN** 用户使用 `-l` 或 `--lines` 参数 +- **THEN** 系统输出解析后文档的总行数 + +### Requirement: 标题提取 +系统 SHALL 支持提取文档中的所有标题行。 + +#### Scenario: 使用 -t 参数提取标题 +- **WHEN** 用户使用 `-t` 或 `--titles` 参数 +- **THEN** 系统输出解析后文档的所有 1-6 级标题行 + +### Requirement: 指定标题内容提取 +系统 SHALL 支持提取指定标题及其下级内容。 + +#### Scenario: 使用 -tc 参数提取标题内容 +- **WHEN** 用户使用 `-tc ` 或 `--title-content ` 参数 +- **THEN** 系统输出所有匹配标题名称的标题及其下级内容，包含上级标题上下文，多个匹配用 --- 分隔 + +#### Scenario: 标题未找到时提示错误 +- **WHEN** 指定的标题名称未找到 +- **THEN** 系统输出错误信息并退出非零状态码 + +### Requirement: 正则搜索 +系统 SHALL 支持使用正则表达式搜索文档内容。 + +#### Scenario: 使用 -s 参数搜索 +- **WHEN** 用户使用 `-s ` 或 `--search ` 参数 +- **THEN** 系统输出所有匹配结果及其上下文，多个匹配用 --- 分隔 + +#### Scenario: 使用 -n 参数指定上下文行数 +- **WHEN** 用户同时使用 `-s ` 和 `-n ` 或 `--context ` 参数 +- **THEN** 系统输出匹配结果及其前后指定行数的上下文（不含空行） + +#### Scenario: 无效正则表达式提示错误 +- **WHEN** 提供的正则表达式无效 +- **THEN** 系统输出错误信息并退出非零状态码 + +#### Scenario: 无匹配结果提示错误 +- **WHEN** 未找到任何匹配 +- **THEN** 系统输出错误信息并退出非零状态码 + +### Requirement: Markdown 图片移除 +系统 SHALL 自动移除解析结果中的 Markdown 图片标记。 + +#### Scenario: 移除图片标记 +- **WHEN** 解析结果包含 `![alt](url)` 格式的图片标记 +- **THEN** 系统移除这些图片标记 + +### Requirement: Markdown 空白规范化 +系统 SHALL 规范化解析结果中的空白字符，保留单行空行。 + +#### Scenario: 规范化连续空行 +- **WHEN** 解析结果包含连续 3 个或更多换行符 +- **THEN** 系统将其替换为 2 个换行符（保留单行空行） + +### Requirement: 使用 logging 模块 +系统 SHALL 使用 Python logging 模块进行日志输出，而非简单 print。 + +#### Scenario: 日志输出 +- **WHEN** 系统运行时 +- **THEN** 所有日志信息通过 logging 模块输出 + +### Requirement: 自定义异常 +系统 SHALL 使用自定义异常类处理错误，提供清晰的错误信息和位置上下文。 + +#### Scenario: 抛出 FileDetectionError +- **WHEN** 文件类型检测失败 +- **THEN** 系统抛出 FileDetectionError 异常 + +#### Scenario: 抛出 ReaderNotFoundError +- **WHEN** 未找到适配的阅读器 +- **THEN** 系统抛出 ReaderNotFoundError 异常 + +#### Scenario: 抛出 ParseError +- **WHEN** 文档解析失败 +- **THEN** 系统抛出 ParseError 异常 + +#### Scenario: 抛出 DownloadError +- **WHEN** URL 下载失败 +- **THEN** 系统抛出 DownloadError 异常 diff --git a/openspec/specs/docx-reader/spec.md b/openspec/specs/docx-reader/spec.md new file mode 100644 index 0000000..65141f2 --- /dev/null +++ b/openspec/specs/docx-reader/spec.md @@ -0,0 +1,113 @@ +## Purpose + +DOCX 文档解析能力，支持多种解析方法。 + +## Requirements + +### Requirement: DOCX 文档解析 +系统 SHALL 支持解析 DOCX 格式文档，按优先级尝试多个解析器。 + +#### Scenario: 按优先级尝试解析器 +- **WHEN** 解析 DOCX 文档 +- **THEN** 系统按 docling → unstructured → markitdown → pypandoc-binary → python-docx → XML原生解析的顺序尝试 + +#### Scenario: 成功解析 +- **WHEN** 任一解析器成功 +- **THEN** 系统返回解析结果 + +#### Scenario: 所有解析器失败 +- **WHEN** 所有解析器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: docling 解析器 +系统 SHALL 支持使用 docling 库解析 DOCX。 + +#### Scenario: docling 解析成功 +- **WHEN** docling 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: docling 库未安装 +- **WHEN** docling 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: unstructured 解析器 +系统 SHALL 支持使用 unstructured 库解析 DOCX。 + +#### Scenario: unstructured 解析成功 +- **WHEN** unstructured 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: unstructured 库未安装 +- **WHEN** unstructured 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: markitdown 解析器 +系统 SHALL 支持使用 markitdown 库解析 DOCX。 + +#### Scenario: markitdown 解析成功 +- **WHEN** markitdown 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: markitdown 库未安装 +- **WHEN** markitdown 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: pypandoc-binary 解析器 +系统 SHALL 支持使用 pypandoc-binary 库解析 DOCX。 + +#### Scenario: pypandoc 解析成功 +- **WHEN** pypandoc-binary 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: pypandoc-binary 库未安装 +- **WHEN** pypandoc-binary 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: python-docx 解析器 +系统 SHALL 支持使用 python-docx 库解析 DOCX。 + +#### Scenario: python-docx 解析成功 +- **WHEN** python-docx 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容，保留标题层级、列表、表格、粗体、斜体等格式 + +#### Scenario: python-docx 库未安装 +- **WHEN** python-docx 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: XML 原生解析器 +系统 SHALL 支持使用 XML 原生解析 DOCX。 + +#### Scenario: XML 原生解析成功 +- **WHEN** 文档有效 +- **THEN** 系统返回 Markdown 内容，保留标题层级、列表、表格等格式 + +#### Scenario: XML 原生解析失败 +- **WHEN** XML 原生解析失败 +- **THEN** 系统返回失败信息 + +### Requirement: 每个解析器独立文件 +系统 SHALL 将每个解析器实现为独立的单文件模块。 + +#### Scenario: docling 解析器在独立文件 +- **WHEN** 使用 docling 解析器 +- **THEN** 从 readers/docx/docling.py 导入 + +#### Scenario: unstructured 解析器在独立文件 +- **WHEN** 使用 unstructured 解析器 +- **THEN** 从 readers/docx/unstructured.py 导入 + +#### Scenario: markitdown 解析器在独立文件 +- **WHEN** 使用 markitdown 解析器 +- **THEN** 从 readers/docx/markitdown.py 导入 + +#### Scenario: pypandoc 解析器在独立文件 +- **WHEN** 使用 pypandoc 解析器 +- **THEN** 从 readers/docx/pypandoc.py 导入 + +#### Scenario: python-docx 解析器在独立文件 +- **WHEN** 使用 python-docx 解析器 +- **THEN** 从 readers/docx/python_docx.py 导入 + +#### Scenario: XML 原生解析器在独立文件 +- **WHEN** 使用 XML 原生解析器 +- **THEN** 从 readers/docx/native_xml.py 导入 diff --git a/openspec/specs/html-reader/spec.md b/openspec/specs/html-reader/spec.md new file mode 100644 index 0000000..b02477b --- /dev/null +++ b/openspec/specs/html-reader/spec.md @@ -0,0 +1,192 @@ +## Purpose + +HTML/URL 文档解析能力，支持多种解析方法。 + +## Requirements + +### Requirement: HTML 文档解析 +系统 SHALL 支持解析 HTML 格式文档和 URL 网页，按优先级尝试多个解析器。 + +#### Scenario: 按优先级尝试解析器 +- **WHEN** 解析 HTML 内容 +- **THEN** 系统按 trafilatura → domscribe → markitdown → html2text 的顺序尝试 + +#### Scenario: 成功解析 +- **WHEN** 任一解析器成功 +- **THEN** 系统返回解析结果 + +#### Scenario: 所有解析器失败 +- **WHEN** 所有解析器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: URL 下载 +系统 SHALL 支持从 URL 下载网页内容，按优先级尝试多个下载器。 + +#### Scenario: 按优先级尝试下载器 +- **WHEN** 输入为 URL +- **THEN** 系统按 pyppeteer → selenium → httpx → urllib 的顺序尝试下载 + +#### Scenario: 成功下载 +- **WHEN** 任一下载器成功 +- **THEN** 系统返回 HTML 内容 + +#### Scenario: 所有下载器失败 +- **WHEN** 所有下载器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: HTML 内容清理 +系统 SHALL 在解析前清理 HTML 内容，移除不需要的标签和属性。 + +#### Scenario: 移除 script 标签 +- **WHEN** HTML 内容包含 script 标签 +- **THEN** 系统移除所有 script 标签 + +#### Scenario: 移除 style 标签 +- **WHEN** HTML 内容包含 style 标签 +- **THEN** 系统移除所有 style 标签 + +#### Scenario: 移除 svg 标签 +- **WHEN** HTML 内容包含 svg 标签 +- **THEN** 系统移除所有 svg 标签 + +#### Scenario: 移除 link 标签 +- **WHEN** HTML 内容包含 link 标签 +- **THEN** 系统移除所有 link 标签 + +#### Scenario: 移除 URL 属性 +- **WHEN** HTML 标签包含 href、src、srcset、action 属性 +- **THEN** 系统移除这些属性 + +#### Scenario: 移除 style 属性 +- **WHEN** HTML 标签包含 style 属性 +- **THEN** 系统移除所有 style 属性 + +#### Scenario: 移除 data-href 属性 +- **WHEN** HTML 标签包含 data-href 属性 +- **THEN** 系统移除这些属性 + +#### Scenario: 清理 title 属性中的 URL +- **WHEN** HTML 标签的 title 属性包含 URL +- **THEN** 系统移除 URL + +#### Scenario: 清理包含 URL 的 class 属性 +- **WHEN** HTML 标签的 class 属性包含 URL 样式 +- **THEN** 系统移除这些 class + +### Requirement: pyppeteer 下载器 +系统 SHALL 支持使用 pyppeteer 下载 URL（支持 JS 渲染）。 + +#### Scenario: pyppeteer 下载成功 +- **WHEN** pyppeteer 库可用且 URL 可访问 +- **THEN** 系统返回渲染后的 HTML 内容 + +#### Scenario: pyppeteer 库未安装 +- **WHEN** pyppeteer 库未安装 +- **THEN** 系统尝试下一个下载器 + +### Requirement: selenium 下载器 +系统 SHALL 支持使用 selenium 下载 URL（支持 JS 渲染）。 + +#### Scenario: selenium 下载成功 +- **WHEN** selenium 库可用、LYXY_CHROMIUM_DRIVER 和 LYXY_CHROMIUM_BINARY 环境变量配置正确且 URL 可访问 +- **THEN** 系统返回渲染后的 HTML 内容 + +#### Scenario: selenium 依赖未满足 +- **WHEN** selenium 库未安装或环境变量未配置 +- **THEN** 系统尝试下一个下载器 + +### Requirement: httpx 下载器 +系统 SHALL 支持使用 httpx 下载 URL（轻量级 HTTP 客户端）。 + +#### Scenario: httpx 下载成功 +- **WHEN** httpx 库可用且 URL 可访问 +- **THEN** 系统返回 HTML 内容 + +#### Scenario: httpx 库未安装 +- **WHEN** httpx 库未安装 +- **THEN** 系统尝试下一个下载器 + +### Requirement: urllib 下载器 +系统 SHALL 支持使用 urllib 下载 URL（标准库，兜底方案）。 + +#### Scenario: urllib 下载成功 +- **WHEN** URL 可访问 +- **THEN** 系统返回 HTML 内容 + +#### Scenario: urllib 下载失败 +- **WHEN** urllib 下载失败 +- **THEN** 系统返回失败信息 + +### Requirement: trafilatura 解析器 +系统 SHALL 支持使用 trafilatura 解析 HTML。 + +#### Scenario: trafilatura 解析成功 +- **WHEN** trafilatura 库可用且 HTML 有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: trafilatura 库未安装 +- **WHEN** trafilatura 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: domscribe 解析器 +系统 SHALL 支持使用 domscribe 解析 HTML。 + +#### Scenario: domscribe 解析成功 +- **WHEN** domscribe 库可用且 HTML 有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: domscribe 库未安装 +- **WHEN** domscribe 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: markitdown 解析器 +系统 SHALL 支持使用 markitdown 解析 HTML。 + +#### Scenario: markitdown 解析成功 +- **WHEN** markitdown 库可用且 HTML 有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: markitdown 库未安装 +- **WHEN** markitdown 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: html2text 解析器 +系统 SHALL 支持使用 html2text 解析 HTML（兜底方案）。 + +#### Scenario: html2text 解析成功 +- **WHEN** html2text 库可用且 HTML 有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: html2text 库未安装 +- **WHEN** html2text 库未安装 +- **THEN** 系统返回失败信息 + +### Requirement: 下载器在 html 目录下 +系统 SHALL 将下载器和清理器放在 html 目录下，不拆分。 + +#### Scenario: downloader.py 在 html 目录 +- **WHEN** 使用 URL 下载功能 +- **THEN** 从 readers/html/downloader.py 导入 + +#### Scenario: cleaner.py 在 html 目录 +- **WHEN** 使用 HTML 清理功能 +- **THEN** 从 readers/html/cleaner.py 导入 + +### Requirement: 每个 HTML 解析器独立文件 +系统 SHALL 将每个 HTML 解析器实现为独立的单文件模块。 + +#### Scenario: trafilatura 解析器在独立文件 +- **WHEN** 使用 trafilatura 解析器 +- **THEN** 从 readers/html/trafilatura.py 导入 + +#### Scenario: domscribe 解析器在独立文件 +- **WHEN** 使用 domscribe 解析器 +- **THEN** 从 readers/html/domscribe.py 导入 + +#### Scenario: markitdown 解析器在独立文件 +- **WHEN** 使用 markitdown 解析器 +- **THEN** 从 readers/html/markitdown.py 导入 + +#### Scenario: html2text 解析器在独立文件 +- **WHEN** 使用 html2text 解析器 +- **THEN** 从 readers/html/html2text.py 导入 diff --git a/openspec/specs/pdf-reader/spec.md b/openspec/specs/pdf-reader/spec.md new file mode 100644 index 0000000..3c78a2f --- /dev/null +++ b/openspec/specs/pdf-reader/spec.md @@ -0,0 +1,120 @@ +## Purpose + +PDF 文档解析能力（含 OCR），支持多种解析方法。 + +## Requirements + +### Requirement: PDF 文档解析 +系统 SHALL 支持解析 PDF 格式文档，按优先级尝试多个解析器，OCR 优先。 + +#### Scenario: 按优先级尝试解析器 +- **WHEN** 解析 PDF 文档 +- **THEN** 系统按 docling OCR → unstructured OCR → docling → unstructured → markitdown → pypdf 的顺序尝试 + +#### Scenario: 成功解析 +- **WHEN** 任一解析器成功 +- **THEN** 系统返回解析结果 + +#### Scenario: 所有解析器失败 +- **WHEN** 所有解析器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: 无 --high-res 参数 +系统 SHALL NOT 提供 --high-res 参数来控制是否使用 OCR，OCR 解析器直接加入解析器链。 + +#### Scenario: 不接受 --high-res 参数 +- **WHEN** 用户使用 --high-res 参数 +- **THEN** 系统提示该参数不存在 + +### Requirement: docling OCR 解析器 +系统 SHALL 支持使用 docling 库的 OCR 模式解析 PDF。 + +#### Scenario: docling OCR 解析成功 +- **WHEN** docling 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: docling 库未安装 +- **WHEN** docling 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: unstructured OCR 解析器 +系统 SHALL 支持使用 unstructured 库的 hi_res 策略+PaddleOCR 解析 PDF。 + +#### Scenario: unstructured OCR 解析成功 +- **WHEN** unstructured 和 unstructured-paddleocr 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: unstructured OCR 依赖未安装 +- **WHEN** unstructured 或 unstructured-paddleocr 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: docling 解析器（非 OCR） +系统 SHALL 支持使用 docling 库的非 OCR 模式解析 PDF。 + +#### Scenario: docling 解析成功 +- **WHEN** docling 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: docling 库未安装 +- **WHEN** docling 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: unstructured 解析器（非 OCR） +系统 SHALL 支持使用 unstructured 库的 fast 策略解析 PDF。 + +#### Scenario: unstructured 解析成功 +- **WHEN** unstructured 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: unstructured 库未安装 +- **WHEN** unstructured 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: markitdown 解析器 +系统 SHALL 支持使用 markitdown 库解析 PDF。 + +#### Scenario: markitdown 解析成功 +- **WHEN** markitdown 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: markitdown 库未安装 +- **WHEN** markitdown 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: pypdf 解析器 +系统 SHALL 支持使用 pypdf 库解析 PDF。 + +#### Scenario: pypdf 解析成功 +- **WHEN** pypdf 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: pypdf 库未安装 +- **WHEN** pypdf 库未安装 +- **THEN** 系统返回失败信息 + +### Requirement: 每个解析器独立文件 +系统 SHALL 将每个解析器实现为独立的单文件模块。 + +#### Scenario: docling OCR 解析器在独立文件 +- **WHEN** 使用 docling OCR 解析器 +- **THEN** 从 readers/pdf/docling_ocr.py 导入 + +#### Scenario: unstructured OCR 解析器在独立文件 +- **WHEN** 使用 unstructured OCR 解析器 +- **THEN** 从 readers/pdf/unstructured_ocr.py 导入 + +#### Scenario: docling 解析器在独立文件 +- **WHEN** 使用 docling 解析器 +- **THEN** 从 readers/pdf/docling.py 导入 + +#### Scenario: unstructured 解析器在独立文件 +- **WHEN** 使用 unstructured 解析器 +- **THEN** 从 readers/pdf/unstructured.py 导入 + +#### Scenario: markitdown 解析器在独立文件 +- **WHEN** 使用 markitdown 解析器 +- **THEN** 从 readers/pdf/markitdown.py 导入 + +#### Scenario: pypdf 解析器在独立文件 +- **WHEN** 使用 pypdf 解析器 +- **THEN** 从 readers/pdf/pypdf.py 导入 diff --git a/openspec/specs/pptx-reader/spec.md b/openspec/specs/pptx-reader/spec.md new file mode 100644 index 0000000..fc77255 --- /dev/null +++ b/openspec/specs/pptx-reader/spec.md @@ -0,0 +1,98 @@ +## Purpose + +PPTX 文档解析能力，支持多种解析方法。 + +## Requirements + +### Requirement: PPTX 文档解析 +系统 SHALL 支持解析 PPTX 格式文档，按优先级尝试多个解析器。 + +#### Scenario: 按优先级尝试解析器 +- **WHEN** 解析 PPTX 文档 +- **THEN** 系统按 docling → unstructured → markitdown → python-pptx → XML原生解析的顺序尝试 + +#### Scenario: 成功解析 +- **WHEN** 任一解析器成功 +- **THEN** 系统返回解析结果 + +#### Scenario: 所有解析器失败 +- **WHEN** 所有解析器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: docling 解析器 +系统 SHALL 支持使用 docling 库解析 PPTX。 + +#### Scenario: docling 解析成功 +- **WHEN** docling 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: docling 库未安装 +- **WHEN** docling 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: unstructured 解析器 +系统 SHALL 支持使用 unstructured 库解析 PPTX。 + +#### Scenario: unstructured 解析成功 +- **WHEN** unstructured 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: unstructured 库未安装 +- **WHEN** unstructured 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: markitdown 解析器 +系统 SHALL 支持使用 markitdown 库解析 PPTX。 + +#### Scenario: markitdown 解析成功 +- **WHEN** markitdown 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: markitdown 库未安装 +- **WHEN** markitdown 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: python-pptx 解析器 +系统 SHALL 支持使用 python-pptx 库解析 PPTX。 + +#### Scenario: python-pptx 解析成功 +- **WHEN** python-pptx 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容，每页用二级标题分隔，保留列表、表格、粗体、斜体等格式 + +#### Scenario: python-pptx 库未安装 +- **WHEN** python-pptx 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: XML 原生解析器 +系统 SHALL 支持使用 XML 原生解析 PPTX。 + +#### Scenario: XML 原生解析成功 +- **WHEN** 文档有效 +- **THEN** 系统返回 Markdown 内容，每页用二级标题分隔，保留列表、表格、粗体、斜体等格式 + +#### Scenario: XML 原生解析失败 +- **WHEN** XML 原生解析失败 +- **THEN** 系统返回失败信息 + +### Requirement: 每个解析器独立文件 +系统 SHALL 将每个解析器实现为独立的单文件模块。 + +#### Scenario: docling 解析器在独立文件 +- **WHEN** 使用 docling 解析器 +- **THEN** 从 readers/pptx/docling.py 导入 + +#### Scenario: unstructured 解析器在独立文件 +- **WHEN** 使用 unstructured 解析器 +- **THEN** 从 readers/pptx/unstructured.py 导入 + +#### Scenario: markitdown 解析器在独立文件 +- **WHEN** 使用 markitdown 解析器 +- **THEN** 从 readers/pptx/markitdown.py 导入 + +#### Scenario: python-pptx 解析器在独立文件 +- **WHEN** 使用 python-pptx 解析器 +- **THEN** 从 readers/pptx/python_pptx.py 导入 + +#### Scenario: XML 原生解析器在独立文件 +- **WHEN** 使用 XML 原生解析器 +- **THEN** 从 readers/pptx/native_xml.py 导入 diff --git a/openspec/specs/xlsx-reader/spec.md b/openspec/specs/xlsx-reader/spec.md new file mode 100644 index 0000000..6286922 --- /dev/null +++ b/openspec/specs/xlsx-reader/spec.md @@ -0,0 +1,98 @@ +## Purpose + +XLSX 文档解析能力，支持多种解析方法。 + +## Requirements + +### Requirement: XLSX 文档解析 +系统 SHALL 支持解析 XLSX 格式文档，按优先级尝试多个解析器。 + +#### Scenario: 按优先级尝试解析器 +- **WHEN** 解析 XLSX 文档 +- **THEN** 系统按 docling → unstructured → markitdown → pandas → XML原生解析的顺序尝试 + +#### Scenario: 成功解析 +- **WHEN** 任一解析器成功 +- **THEN** 系统返回解析结果 + +#### Scenario: 所有解析器失败 +- **WHEN** 所有解析器均失败 +- **THEN** 系统返回失败列表并退出非零状态码 + +### Requirement: docling 解析器 +系统 SHALL 支持使用 docling 库解析 XLSX。 + +#### Scenario: docling 解析成功 +- **WHEN** docling 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: docling 库未安装 +- **WHEN** docling 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: unstructured 解析器 +系统 SHALL 支持使用 unstructured 库解析 XLSX。 + +#### Scenario: unstructured 解析成功 +- **WHEN** unstructured 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: unstructured 库未安装 +- **WHEN** unstructured 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: markitdown 解析器 +系统 SHALL 支持使用 markitdown 库解析 XLSX。 + +#### Scenario: markitdown 解析成功 +- **WHEN** markitdown 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容 + +#### Scenario: markitdown 库未安装 +- **WHEN** markitdown 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: pandas 解析器 +系统 SHALL 支持使用 pandas 库解析 XLSX。 + +#### Scenario: pandas 解析成功 +- **WHEN** pandas 和 tabulate 库可用且文档有效 +- **THEN** 系统返回 Markdown 内容，每个工作表用二级标题分隔，数据以表格形式展示 + +#### Scenario: pandas 库未安装 +- **WHEN** pandas 或 tabulate 库未安装 +- **THEN** 系统尝试下一个解析器 + +### Requirement: XML 原生解析器 +系统 SHALL 支持使用 XML 原生解析 XLSX。 + +#### Scenario: XML 原生解析成功 +- **WHEN** 文档有效 +- **THEN** 系统返回 Markdown 内容，每个工作表用二级标题分隔，数据以表格形式展示，过滤全空列 + +#### Scenario: XML 原生解析失败 +- **WHEN** XML 原生解析失败 +- **THEN** 系统返回失败信息 + +### Requirement: 每个解析器独立文件 +系统 SHALL 将每个解析器实现为独立的单文件模块。 + +#### Scenario: docling 解析器在独立文件 +- **WHEN** 使用 docling 解析器 +- **THEN** 从 readers/xlsx/docling.py 导入 + +#### Scenario: unstructured 解析器在独立文件 +- **WHEN** 使用 unstructured 解析器 +- **THEN** 从 readers/xlsx/unstructured.py 导入 + +#### Scenario: markitdown 解析器在独立文件 +- **WHEN** 使用 markitdown 解析器 +- **THEN** 从 readers/xlsx/markitdown.py 导入 + +#### Scenario: pandas 解析器在独立文件 +- **WHEN** 使用 pandas 解析器 +- **THEN** 从 readers/xlsx/pandas.py 导入 + +#### Scenario: XML 原生解析器在独立文件 +- **WHEN** 使用 XML 原生解析器 +- **THEN** 从 readers/xlsx/native_xml.py 导入