lyxy-document/openspec/specs/html-reader/spec.md at 7eab1dcef11aff57f574480b5c3469dd667c8cc2

Files

lanyuanxiaoyao 750ef50a8d refactor: 重构解析器架构并添加编码检测和配置管理

简化 parse_input() 为纯调度器，通过遍历 readers 的 supports() 方法识别输入类型，移除 URL 特殊处理和文件检查逻辑。各 reader 的 parse() 方法负责完整验证（文件存在、格式有效性）。

新增功能：
- 添加 chardet 编码自动检测，支持多种中文编码回退机制
- 创建统一配置类管理编码、下载超时、日志等级等配置项
- HTML reader 支持本地文件编码检测和 URL 统一处理

安全性改进：
- 修复 safe_open_zip() 路径遍历漏洞，使用 pathlib 规范化路径
- 添加边界检查，search_markdown() 检查负数参数

其他改进：
- 修复类型注解（argparse.Namespace）
- 日志系统仅输出 ERROR 级别，避免干扰 Markdown 输出
- 更新 BaseReader 接口文档，明确 supports() 和 parse() 职责划分
- 同步 delta specs 到主 specs（document-reading、html-reader、configuration、encoding-detection）

2026-03-08 16:33:40 +08:00

8.1 KiB

Raw Blame History

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 系统调用内部的 download_and_parse() 方法

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 和本地文件。

Scenario: parse() 判断输入类型

WHEN 调用 HtmlReader.parse(file_path)
THEN 系统判断 file_path 是 URL 还是本地文件

Scenario: URL 调用 download_and_parse

WHEN file_path 为 URL
THEN 系统调用 self.download_and_parse(file_path)

Scenario: 本地文件读取并解析

WHEN file_path 为本地文件
THEN 系统使用编码检测读取文件，然后解析 HTML 内容

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

8.1 KiB Raw Blame History Unescape Escape