lanyuanxiaoyao
6b4fcf2647
- 新增 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
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
## 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`
|
||
1. trafilatura - 专门用于网页正文提取，质量高
|
||
2. domscribe - 专注内容提取
|
||
3. MarkItDown - 微软官方，格式规范
|
||
4. 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
|
||
|
||
无 - 所有决策已明确。
|