# HTML Parser 使用说明

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

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

## 快速开始

```bash
# 最简运行（仅 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
```

## 命令行用法

### 基本语法

```bash
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 输入：**

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

**HTML 文件输入：**

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

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

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

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

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

**提取标题（`-t`）：**

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

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

**提取标题内容（`-tc`）：**

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

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

**搜索（`-s`）：**

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

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

### 批量处理

```bash
# 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")
}
```

### 管道使用

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

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

## 安装

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

### 完整安装（推荐）

```bash
# 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）：

```bash
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，包含以下元素：

```markdown
# 一级标题

正文段落

## 二级标题

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

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

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

**粗体** *斜体*
```

### 内容自动处理

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

| 处理 | 说明 |
|------|------|
| HTML 清理 | 移除 script/style/link/svg 标签和 URL 属性 |
| 图片移除 | 删除 `![alt](url)` 语法 |
| 空行规范化 | 连续多个空行合并为一个 |

## 错误处理

### 错误消息

```bash
# 输入不是 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 编码，确保终端支持：

```bash
# 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         # 本文档
```