Skill/skills/lyxy-reader-html/scripts/README.md

HTML Parser 使用说明

HTML/URL 解析器，将网页内容或本地 HTML 文件转换为 Markdown 格式。

支持两种输入源：URL（自动下载网页内容）或本地 HTML 文件。下载器按 pyppeteer → selenium → httpx → urllib 优先级依次尝试；解析器按 trafilatura → domscribe → MarkItDown → html2text 优先级依次尝试。

快速开始

# 最简运行（仅 urllib + html2text）
python parser.py https://example.com

# 安装推荐依赖后运行
pip install trafilatura domscribe markitdown html2text httpx beautifulsoup4
python parser.py https://example.com

# 使用 uv 一键运行（自动安装依赖，无需手动 pip install）
uv run --with trafilatura --with domscribe --with markitdown --with html2text --with httpx --with beautifulsoup4 parser.py https://example.com

命令行用法

基本语法

python parser.py <input> [options]

input 可以是：

• 以 http:// 或 https:// 开头的 URL
• 本地 .html 或 .htm 文件路径

不带任何选项时输出完整 Markdown 内容。

参数说明

以下参数互斥，一次只能使用一个：

短选项	长选项	说明
-c	--count	输出解析后文档的总字符数（不含换行符）
-l	--lines	输出解析后文档的总行数
-t	--titles	输出所有标题行（1-6 级，含 # 前缀）
-tc <name>	--title-content <name>	提取指定标题及其下级内容（name 不包含 # 号）
-s <pattern>	--search <pattern>	使用正则表达式搜索文档，返回匹配结果

搜索辅助参数（与 -s 配合使用）：

短选项	长选项	说明
-n <num>	--context <num>	每个匹配结果包含的前后非空行数（默认：2）

退出码

退出码	含义
0	解析成功
1	错误（文件不存在、格式无效、所有下载器失败、所有解析器失败、标题未找到、正则无效或无匹配）

使用示例

URL 输入：

# 输出完整 Markdown
python parser.py https://example.com
python parser.py https://example.com > output.md

HTML 文件输入：

# 输出完整 Markdown
python parser.py page.html
python parser.py page.html > output.md

统计信息（-c / -l）：

输出单个数字，适合管道处理。

$ python parser.py https://example.com -c
8500

$ python parser.py https://example.com -l
215

提取标题（-t）：

每行一个标题，保留 # 前缀和层级。

$ python parser.py https://example.com -t
# 欢迎来到 Example
## 关于我们
## 联系方式

提取标题内容（-tc）：

输出指定标题及其下级内容。如果文档中有多个同名标题，用 --- 分隔。每段输出包含上级标题链。

$ python parser.py https://example.com -tc "关于我们"
# 欢迎来到 Example
## 关于我们
这是关于我们的详细内容...

搜索（-s）：

支持 Python 正则表达式语法。多个匹配结果用 --- 分隔。-n 控制上下文行数。

$ python parser.py https://example.com -s "测试" -n 1
上一行内容
包含**测试**关键词的行
下一行内容
---
另一处上一行
另一处**测试**内容
另一处下一行

批量处理

# Linux/Mac - 批量处理 HTML 文件
for file in *.html; do
    python parser.py "$file" > "${file%.html}.md"
done

# Windows PowerShell - 批量处理 HTML 文件
Get-ChildItem *.html | ForEach-Object {
    python parser.py $_.FullName > ($_.BaseName + ".md")
}

管道使用

# 过滤包含关键词的行
python parser.py https://example.com | grep "重要" > important.md

# 统计标题数量
python parser.py https://example.com -t | wc -l

安装

脚本基于 Python 3.6+ 运行。下载器和解析器按优先级依次尝试，建议安装所有依赖以获得最佳兼容性。也可以只安装部分依赖，脚本会自动选择可用的组件。

完整安装（推荐）

# pip
pip install trafilatura domscribe markitdown html2text httpx pyppeteer selenium beautifulsoup4

# uv（一键运行，无需预安装）
uv run --with trafilatura --with domscribe --with markitdown --with html2text --with httpx --with pyppeteer --with selenium --with beautifulsoup4 parser.py https://example.com

最小安装

仅使用标准库（urllib + html2text）：

pip install html2text beautifulsoup4

各组件说明

下载器：

下载器	优点	缺点	依赖
pyppeteer	支持 JS 渲染，现代网页兼容性好	依赖重，需下载 Chromium	pyppeteer
selenium	支持 JS 渲染，成熟稳定	需配置 Chromium driver 和 binary	selenium
httpx	轻量快速，现代 HTTP 客户端	不支持 JS 渲染	httpx
urllib	Python 标准库，无需安装	不支持 JS 渲染	（无）

解析器：

解析器	优点	缺点	依赖
trafilatura	专门用于网页正文提取，质量高	可能无法提取某些页面	trafilatura
domscribe	专注内容提取	相对较新	domscribe
MarkItDown	微软官方，格式规范	输出较简洁	markitdown
html2text	经典库，兼容性好	作为兜底方案	html2text

其他依赖：

• beautifulsoup4 - HTML 清理必需

JS 渲染配置

pyppeteer 和 selenium 支持 JS 渲染，但需要额外配置：

pyppeteer：

• 首次运行会自动下载 Chromium
• 或设置 LYXY_CHROMIUM_BINARY 环境变量指定 Chromium 路径

selenium：

• 必须设置两个环境变量：
  • LYXY_CHROMIUM_DRIVER - ChromeDriver 路径
  • LYXY_CHROMIUM_BINARY - Chromium/Chrome 路径

输出格式

Markdown 文档结构

无选项时输出完整 Markdown，包含以下元素：

# 一级标题

正文段落

## 二级标题

- 无序列表项
- 无序列表项

1. 有序列表项
2. 有序列表项

| 列1 | 列2 | 列3 |
|------|------|------|
| 数据1 | 数据2 | 数据3 |

**粗体** *斜体*

内容自动处理

输出前会自动进行以下处理：

处理	说明
HTML 清理	移除 script/style/link/svg 标签和 URL 属性
图片移除	删除  语法
空行规范化	连续多个空行合并为一个

错误处理

错误消息

# 输入不是 URL 也不是 HTML 文件
$ python parser.py invalid.txt
错误: 不是有效的 HTML 文件: invalid.txt

# 文件不存在
$ python parser.py missing.html
错误: 文件不存在: missing.html

# 所有下载器失败（URL 示例）
$ python parser.py https://example.com
所有下载方法均失败:
- pyppeteer: pyppeteer 库未安装
- selenium: selenium 库未安装
- httpx: httpx 库未安装
- urllib: HTTP 404

# 所有解析器失败
$ python parser.py page.html
所有解析方法均失败:
- trafilatura: trafilatura 库未安装
- domscribe: domscribe 库未安装
- MarkItDown: MarkItDown 库未安装
- html2text: html2text 库未安装

# 标题未找到
$ python parser.py https://example.com -tc "不存在的标题"
错误: 未找到标题 '不存在的标题'

# 无效正则或无匹配
$ python parser.py https://example.com -s "[invalid"
错误: 正则表达式无效或未找到匹配: '[invalid'

解析器回退机制

脚本按优先级依次尝试各下载器和解析器。每个组件失败后记录原因（库未安装 / 下载失败 / 解析失败 / 文档为空），然后自动尝试下一个。全部失败时输出汇总信息并以退出码 1 退出。

常见问题

为什么有些内容没有提取到？

不同解析器输出详细度不同。建议安装所有解析器依赖，脚本会自动选择优先级最高的可用解析器。

如何只使用特定下载器/解析器？

当前版本不支持指定，总是按优先级自动选择。可以通过只安装目标组件的依赖来间接控制——未安装的组件会被跳过。

URL 下载慢或被反爬？

pyppeteer 和 selenium 支持 JS 渲染但较慢。如果目标网页不需要 JS 渲染，可以只安装 httpx 或 urllib，让脚本回退到这些轻量下载器。

中文显示乱码？

脚本输出 UTF-8 编码，确保终端支持：

# Linux/Mac
export LANG=en_US.UTF-8

# Windows PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

文件结构

scripts/
├── common.py         # 公共函数（HTML 清理、Markdown 处理）
├── downloader.py     # URL 下载模块
├── html_parser.py    # HTML 解析模块
├── parser.py         # 命令行入口
└── README.md         # 本文档