Skill/openspec/changes/archive/2026-03-08-create-lyxy-reader-html-skill/design.md at master

Files

lanyuanxiaoyao 6b4fcf2647 创建 lyxy-reader-html skill

- 新增 skill: lyxy-reader-html，用于解析 HTML 文件和 URL 网页内容
- 支持 URL 下载（pyppeteer → selenium → httpx → urllib 优先级回退）
- 支持 HTML 解析（trafilatura → domscribe → MarkItDown → html2text 优先级回退）
- 支持查询功能：全文提取、字数统计、行数统计、标题提取、章节提取、正则搜索
- 新增 spec: html-document-parsing
- 归档 change: create-lyxy-reader-html-skill

2026-03-08 02:02:03 +08:00

4.5 KiB

Raw Permalink Blame History

Context

当前项目已有 lyxy-reader-office skill 用于解析办公文档，其架构设计成熟，包含统一命令行入口、多解析器回退机制、多功能查询等特性。现在需要创建 lyxy-reader-html skill，功能上类似但针对 HTML 内容，同时需支持 URL 下载能力。

约束条件：

与 lyxy-reader-office 保持相同的用户体验（参数、输出格式）
代码完全独立，不复用 lyxy-reader-office 的代码
参考 temp/downloader/download.py 和 temp/parser/parse.py 的现有实现

Goals / Non-Goals

Goals:

创建完整的 lyxy-reader-html skill 目录结构
实现统一的命令行入口 parser.py，支持 URL 和 HTML 文件输入
实现下载器模块，按 pyppeteer → selenium → httpx → urllib 优先级回退
实现解析器模块，按 trafilatura → domscribe → MarkItDown → html2text 优先级回退
实现 HTML 预处理清理和 Markdown 后处理
实现与 lyxy-reader-office 一致的查询功能（全文、字数、行数、标题、章节、搜索）

Non-Goals:

不支持可配置的 HTML 清理选项
不支持 JavaScript 渲染开关（默认启用完整下载链）
不支持正文/全文切换（默认使用解析器的正文提取）

Decisions

1. 目录结构参考 lyxy-reader-office

决策：采用与 lyxy-reader-office 相同的目录结构

lyxy-reader-html/
├── SKILL.md
├── scripts/
│   ├── parser.py       # 统一入口
│   ├── common.py       # 公共函数
│   ├── downloader.py   # URL 下载
│   ├── html_parser.py  # HTML 解析
│   └── README.md
└── references/
    ├── examples.md
    ├── parsers.md
    └── error-handling.md

理由：保持项目一致性，降低用户学习成本

2. 下载器优先级：pyppeteer → selenium → httpx → urllib

决策：直接采用 temp/downloader/download.py 的优先级顺序

pyppeteer（支持 JS 渲染）
selenium（支持 JS 渲染，作为 pyppeteer 的备选）
httpx（轻量级 HTTP 客户端）
urllib（标准库，兜底）

备选方案考虑：

httpx → urllib → pyppeteer → selenium（速度优先）
选择保持原顺序，因为 JS 渲染能力对许多现代网页很重要

3. 解析器优先级：trafilatura → domscribe → MarkItDown → html2text

决策：采用精简后的 4 个解析器，顺序参考 temp/parser/parse.py

trafilatura - 专门用于网页正文提取，质量高
domscribe - 专注内容提取
MarkItDown - 微软官方，格式规范
html2text - 经典库，作为兜底

备选方案考虑：

保留原 6 个解析器（增加 markdownify 和 html-to-markdown）
选择精简为 4 个，减少维护复杂度

4. HTML 预处理清理默认开启且不可配置

决策：解析前固定执行 HTML 清理，移除 script/style/link/svg 标签和 URL 属性

使用 temp/clean_html.py 的清理逻辑
不提供 --no-clean 参数

理由：简化设计，减少用户选择负担

5. Markdown 处理函数独立实现

决策：在 common.py 中独立实现以下函数，不复用 lyxy-reader-office：

remove_markdown_images() - 移除图片标记
normalize_markdown_whitespace() - 规范化空行
extract_titles() - 提取标题
extract_title_content() - 提取章节内容
search_markdown() - 正则搜索

理由：保持 skill 之间完全隔离

6. 命令行参数与 lyxy-reader-office 保持一致

决策：支持以下参数，与 lyxy-reader-office 完全一致：

（无参数）：全文输出
-c / --count：字数统计
-l / --lines：行数统计
-t / --titles：提取标题
-tc <name> / --title-content <name>：提取章节
-s <pattern> / --search <pattern>：正则搜索
-n <num> / --context <num>：搜索上下文行数

不添加 HTML 专用参数

理由：统一用户体验

Risks / Trade-offs

风险	影响	缓解措施
pyppeteer/selenium 依赖重，安装困难	中	提供 httpx/urllib 作为轻量备选
trafilatura 可能提取不到正文	低	后续解析器会继续尝试
不同解析器输出质量差异大	中	用户可通过安装不同依赖来间接选择解析器
URL 下载超时或被反爬	中	多下载器回退增加成功率

Migration Plan

不适用 - 这是新 skill 创建，无迁移需求。

Open Questions

无 - 所有决策已明确。

4.5 KiB Raw Permalink Blame History Unescape Escape