# htmlsense

**Repository Path**: cg33/htmlsense

## Basic Information

- **Project Name**: htmlsense
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# htmlsense

htmlsense 是一个 Go 语言库和命令行工具，用于自动从 HTML 文档中提取元素的 XPath 选择器映射。它利用大语言模型（LLM）的智能分析能力，自动识别 HTML 中的重复结构和有价值的内容元素，并生成对应的 XPath 选择器，大大简化了网页爬虫开发中手动编写选择器的工作。

## 项目背景

在开发网页爬虫程序时，我们经常需要手动识别和编写 XPath 或 CSS 选择器来定位页面元素。这个过程既繁琐又容易出错，特别是当页面结构复杂或经常变化时。htmlsense 通过结合 HTML 结构分析和 LLM 的智能识别能力，实现了选择器的自动生成，让爬虫开发更加高效。

## 功能特性

- ✨ **智能识别**：使用 LLM 自动识别 HTML 中的重复结构和有价值的内容元素
- 🧹 **自动清理**：自动移除 head、style、script 等干扰标签和属性
- 🎯 **范围提取**：支持通过 scopeXPath 指定提取范围，聚焦特定区域
- ✅ **自动校验**：自动校验生成的 XPath 选择器有效性，过滤无效选择器
- 📊 **数据提取**：可选择提取实际数据（表格格式），而不仅仅是选择器
- 🛠️ **命令行工具**：提供完整的命令行工具，方便集成到脚本和自动化流程中
- 📦 **易于集成**：可作为 Go 库使用，轻松集成到现有项目中
- 🔧 **灵活配置**：支持多种 LLM 提供商和模型配置

## 安装

### 前置要求

- Go 1.21 或更高版本
- LLM API 密钥（OpenAI 或其他支持的提供商）

### 从源码安装

```bash
git clone https://github.com/gotoailab/htmlsense.git
cd htmlsense
make install
```

安装后，`htmlsense` 命令将被安装到 `$GOPATH/bin` 目录。

### 使用 Makefile 构建

```bash
# 构建二进制文件到 build/ 目录
make build

# 安装到 GOPATH/bin
make install

# 运行所有测试
make test

# 生成测试覆盖率报告
make test-coverage

# 格式化代码
make fmt

# 运行代码检查
make vet

# 运行所有检查（格式化、检查、测试）
make check

# 构建多平台发布版本
make release

# 查看所有可用命令
make help
```

## 快速开始

### 命令行工具使用

#### 基本用法

```bash
# 从文件提取选择器
htmlsense -html page.html -api-key YOUR_API_KEY

# 从标准输入提取
cat page.html | htmlsense -html - -api-key YOUR_API_KEY

# 指定范围提取（例如只在某个容器内）
htmlsense -html page.html -scope "//div[@class='container']" -api-key YOUR_API_KEY

# 输出为文本格式（默认是 JSON）
htmlsense -html page.html -output text -api-key YOUR_API_KEY

# 提取实际数据（表格格式）
htmlsense -html page.html -extract-data -api-key YOUR_API_KEY

# 提取数据并指定范围
htmlsense -html page.html -extract-data -scope "//div[@class='container']" -api-key YOUR_API_KEY

# 保存中间结果到目录
htmlsense -html page.html -save-intermediate ./output -api-key YOUR_API_KEY

# 提取数据并保存中间结果
htmlsense -html page.html -extract-data -save-intermediate ./output -api-key YOUR_API_KEY

# 使用环境变量设置 API key（推荐）
export HTMLSENSE_API_KEY=YOUR_API_KEY
htmlsense -html page.html

# 指定不同的 LLM 提供商和模型
htmlsense -html page.html -provider openai -model gpt-4 -api-key YOUR_API_KEY
```

#### 命令行参数说明

| 参数 | 说明 | 默认值 | 必需 |
|------|------|--------|------|
| `-html` | HTML 文件路径（使用 `-` 表示从标准输入读取） | - | 是 |
| `-output` | 输出格式：`json` 或 `text` | `json` | 否 |
| `-scope` | 可选的 XPath，用于限制提取范围 | - | 否 |
| `-extract-data` | 提取实际数据而不仅仅是选择器 | `false` | 否 |
| `-save-intermediate` | 保存中间结果的目录（simplified.html, selectors.json, data.json） | - | 否 |
| `-api-key` | LLM API 密钥 | - | 是* |
| `-provider` | LLM 提供商（如 `openai`） | `openai` | 否 |
| `-model` | LLM 模型名称 | `gpt-4` | 否 |
| `-version` | 显示版本信息 | - | 否 |
| `-help` | 显示帮助信息 | - | 否 |

*可以通过 `HTMLSENSE_API_KEY` 环境变量设置，此时不需要 `-api-key` 参数

#### 输出示例

**JSON 格式输出：**
```json
{
  "title": "//h1[@class='article-title']",
  "content": "//div[@class='article-content']//p",
  "author": "//span[@class='author-name']",
  "date": "//time[@class='publish-date']"
}
```

**文本格式输出：**
```
Extracted selector mappings:
  title: //h1[@class='article-title']
  content: //div[@class='article-content']//p
  author: //span[@class='author-name']
  date: //time[@class='publish-date']
```

**数据提取输出（使用 `-extract-data` 参数）：**

JSON 格式：
```json
[
  {
    "title": "文章标题 1",
    "content": "文章内容 1...",
    "author": "作者名 1",
    "date": "2024-01-01"
  },
  {
    "title": "文章标题 2",
    "content": "文章内容 2...",
    "author": "作者名 2",
    "date": "2024-01-02"
  }
]
```

文本格式：
```
Extracted data:

Row 1:
  title: 文章标题 1
  content: 文章内容 1...
  author: 作者名 1
  date: 2024-01-01

Row 2:
  title: 文章标题 2
  content: 文章内容 2...
  author: 作者名 2
  date: 2024-01-02
```

**中间结果（使用 `-save-intermediate` 参数）：**

使用 `-save-intermediate` 时，会在指定目录保存以下文件：

- `simplified.html`：清理和简化后的 HTML，用于 LLM 分析
- `selectors.json`：包含 LLM 返回的原始选择器和验证后的选择器：
  ```json
  {
    "raw_selectors": {
      "title": "//h1[@class='article-title']",
      "content": "//div[@class='article-content']//p"
    },
    "valid_selectors": {
      "title": "//h1[@class='article-title']",
      "content": "//div[@class='article-content']//p"
    }
  }
  ```
- `data.json`：提取的数据，JSON 格式（仅在使用了 `-extract-data` 时生成）

### 作为 Go 库使用

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/gotoailab/htmlsense"
)

func main() {
    // 配置 htmlsense
    config := htmlsense.Config{
        APIKey:   "your-api-key",
        Provider: "openai",
        Model:    "gpt-4",
    }

    // 创建提取器
    extractor, err := htmlsense.NewExtractor(config)
    if err != nil {
        log.Fatal(err)
    }

    // HTML 内容
    htmlContent := `
    <html>
        <body>
            <div class="container">
                <h1 class="title">文章标题</h1>
                <p class="content">文章内容...</p>
                <span class="author">作者名</span>
            </div>
        </body>
    </html>
    `

    ctx := context.Background()

    // 方式 1: 从整个 HTML 提取
    selectors, err := extractor.ExtractSelectors(ctx, htmlContent)
    if err != nil {
        log.Fatal(err)
    }

    // 方式 2: 从指定范围提取（例如只在 container 内）
    selectors, err := extractor.ExtractSelectors(ctx, htmlContent, "//div[@class='container']")
    if err != nil {
        log.Fatal(err)
    }

    // 使用提取的选择器
    for elementName, xpath := range selectors {
        fmt.Printf("%s: %s\n", elementName, xpath)
    }

    // 方式 3: 提取实际数据（表格格式）
    data, err := extractor.ExtractData(ctx, htmlContent)
    if err != nil {
        log.Fatal(err)
    }

    // data 是 []map[string]string，每个 map 代表一行数据
    for i, row := range data {
        fmt.Printf("第 %d 行:\n", i+1)
        for fieldName, value := range row {
            fmt.Printf("  %s: %s\n", fieldName, value)
        }
    }
}
```

## 工作原理

htmlsense 的工作流程如下：

1. **HTML 清理**：移除不需要的标签（head、style、script 等）和干扰属性（如 img 的 src），简化 HTML 结构，使其更适合 LLM 分析

2. **范围提取**（可选）：如果提供了 `scopeXPath` 参数，先从原始 HTML 中使用 XPath 提取指定范围的 DOM 子树

3. **结构识别**：使用 LLM 分析简化后的 HTML，智能识别：
   - 重复的结构模式（如列表项、卡片、文章等）
   - 有价值的内容元素（标题、正文、作者、日期、价格等）

4. **选择器生成**：为每个识别出的元素生成准确的 XPath 选择器，确保选择器既具体又灵活

5. **选择器校验**：自动校验生成的 XPath 是否有效，确保它们能在 HTML 中匹配到节点，过滤掉无效的选择器

## 使用场景

- **网页爬虫开发**：快速生成页面元素的选择器，无需手动编写
- **数据提取自动化**：批量处理多个页面，自动识别和提取结构化数据
- **页面结构分析**：分析网页结构，理解页面布局和内容组织
- **测试自动化**：为 UI 测试生成元素定位器
- **内容监控**：监控网页结构变化，自动更新选择器

## 项目结构

```
htmlsense/
├── cmd/
│   └── htmlsense/          # 命令行工具
│       └── main.go
├── html/                   # HTML 处理模块
│   ├── cleaner.go          # HTML 清理
│   └── simplifier.go       # HTML 简化
├── selector/               # 选择器提取模块
│   ├── extractor.go        # 选择器提取器
│   └── validator.go        # XPath 校验器
├── example/                # 示例代码
├── build/                  # 构建输出目录
├── Makefile               # 构建脚本
├── go.mod                 # Go 模块定义
└── README.md             # 项目文档
```

## 依赖项

- `github.com/gotoailab/llmhub` - LLM 客户端库
- `github.com/antchfx/htmlquery` - HTML 解析和 XPath 查询
- `golang.org/x/net/html` - HTML 解析

## 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue: [GitHub Issues](https://github.com/gotoailab/htmlsense/issues)
- 邮箱: [项目维护者邮箱]

## 致谢

感谢所有为本项目做出贡献的开发者！