lanyuanxiaoyao
2b81dd49fe
将所有 HTML Parser 的函数签名从接收 HTML 字符串改为接收文件路径， 与其他 Reader（PDF、DOCX 等）保持一致。 主要变更： - 修改 PARSERS 列表，移除 lambda 表达式，直接传递函数引用 - 在 HtmlReader.parse() 中统一管理临时文件（UTF-8 编码） - 每个 Parser 使用独立的临时文件副本，用完即清理 - 移除 download_and_parse() 方法，逻辑合并到 parse() 中 - 更新相关测试，改为直接传递文件路径 受影响的 Parser： - trafilatura.parse(html_content) -> parse(file_path) - domscribe.parse(html_content) -> parse(file_path) - markitdown.parse(html_content, temp_file_path) -> parse(file_path) - html2text.parse(html_content) -> parse(file_path)
268 lines
8.9 KiB
Markdown
268 lines
8.9 KiB
Markdown
## Purpose
|
||
|
||
HTML/URL 文档解析能力，支持多种解析方法。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: HTML 文档解析
|
||
系统 SHALL 支持解析 HTML 格式文档和 URL 网页，URL 处理逻辑在 HTML reader 内部统一处理。
|
||
|
||
#### Scenario: 按优先级尝试解析器
|
||
- **WHEN** 解析 HTML 内容
|
||
- **THEN** 系统按 trafilatura → domscribe → markitdown → html2text 的顺序尝试
|
||
|
||
#### Scenario: 成功解析
|
||
- **WHEN** 任一解析器成功
|
||
- **THEN** 系统返回解析结果
|
||
|
||
#### Scenario: 所有解析器失败
|
||
- **WHEN** 所有解析器均失败
|
||
- **THEN** 系统返回失败列表并退出非零状态码
|
||
|
||
### Requirement: URL 下载
|
||
系统 SHALL 在 HTML reader 内部处理 URL 下载，而非在 parse_input() 中特殊处理。
|
||
|
||
#### Scenario: HTML reader 支持 URL
|
||
- **WHEN** 调用 HtmlReader.supports(input_path) 且 input_path 为 URL
|
||
- **THEN** 返回 True
|
||
|
||
#### Scenario: HTML reader 解析 URL
|
||
- **WHEN** 调用 HtmlReader.parse(input_path) 且 input_path 为 URL
|
||
- **THEN** 系统在内部处理 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 导入
|
||
|
||
### Requirement: HTML 文件编码检测
|
||
系统 SHALL 在读取本地 HTML 文件时使用编码自动检测。
|
||
|
||
#### Scenario: 读取 HTML 文件使用编码检测
|
||
- **WHEN** 解析本地 HTML 文件
|
||
- **THEN** 系统使用 encoding_detection.read_text_file() 读取文件
|
||
|
||
#### Scenario: 编码检测成功
|
||
- **WHEN** 编码检测成功读取文件
|
||
- **THEN** 系统继续解析 HTML 内容
|
||
|
||
#### Scenario: 编码检测失败
|
||
- **WHEN** 编码检测失败
|
||
- **THEN** 系统返回错误信息包含编码检测失败原因
|
||
|
||
### Requirement: HTML reader 统一处理 URL 和文件
|
||
系统 SHALL 在 HTML reader 的 `parse()` 方法中统一处理 URL 和本地文件，无需单独的 `download_and_parse()` 方法。
|
||
|
||
#### Scenario: parse() 判断输入类型
|
||
- **WHEN** 调用 `HtmlReader.parse(file_path)`
|
||
- **THEN** 系统判断 file_path 是 URL 还是本地文件
|
||
|
||
#### Scenario: URL 下载后解析
|
||
- **WHEN** file_path 为 URL
|
||
- **THEN** 系统下载 HTML 内容
|
||
- **AND** 清理 HTML 内容
|
||
- **AND** 创建临时文件（UTF-8 编码）
|
||
- **AND** 传递临时文件路径给各 parser
|
||
|
||
#### Scenario: 本地文件读取并解析
|
||
- **WHEN** file_path 为本地文件
|
||
- **THEN** 系统使用编码检测读取文件
|
||
- **AND** 清理 HTML 内容
|
||
- **AND** 创建临时文件（UTF-8 编码）或使用原文件路径
|
||
- **AND** 传递文件路径给各 parser
|
||
|
||
### Requirement: 每个 HTML Parser 接收文件路径
|
||
每个 HTML parser SHALL 接收文件路径作为输入，而非 HTML 字符串。
|
||
|
||
#### Scenario: Parser 接收 file_path
|
||
- **WHEN** `HtmlReader.parse()` 调用 parser
|
||
- **THEN** parser 接收 `file_path: str` 参数
|
||
|
||
#### Scenario: Parser 内部读取文件
|
||
- **WHEN** parser 解析 HTML
|
||
- **THEN** parser 内部使用 UTF-8 编码读取文件内容
|
||
|
||
#### Scenario: Parser 独立临时文件
|
||
- **WHEN** 多个 parser 依次尝试
|
||
- **THEN** 每个 parser 使用独立的临时文件副本
|
||
- **AND** 用完后立即清理临时文件
|
||
|
||
### Requirement: HTML reader supports() 支持 URL
|
||
系统 SHALL 在 HTML reader 的 supports() 方法中同时支持 URL 和 HTML 文件扩展名。
|
||
|
||
#### Scenario: supports() 识别 URL
|
||
- **WHEN** 调用 HtmlReader.supports(file_path) 且 file_path 以 http:// 或 https:// 开头
|
||
- **THEN** 返回 True
|
||
|
||
#### Scenario: supports() 识别 HTML 文件
|
||
- **WHEN** 调用 HtmlReader.supports(file_path) 且 file_path 以 .html 或 .htm 结尾
|
||
- **THEN** 返回 True
|
||
|
||
#### Scenario: supports() 不支持其他类型
|
||
- **WHEN** 调用 HtmlReader.supports(file_path) 且 file_path 既非 URL 也非 HTML 文件
|
||
- **THEN** 返回 False
|