npm package: @howuse/electron-crawler
Description: 基于Electron的爬虫工具包，用于爬取新闻和股票详情
Author: 无名氏
Latest version: 0.5.0

# @howuse/electron-crawler

基于 Electron 的爬虫工具包，用于爬取新闻和股票详情。

## 特性

- 🚀 基于 Electron 构建，支持现代网页渲染
- 📰 专为新闻网站设计的爬虫功能
- 📊 股票详情数据抓取
- ⚙️ 可配置的爬取规则
- 🔄 自动定时任务
- 📦 TypeScript 支持，提供完整的类型定义

## 安装

```bash
npm install @howuse/electron-crawler
```

## 使用方法

### 基本用法

```javascript
import { initCrawler } from '@howuse/electron-crawler'

// 初始化爬虫配置（调用后自动启动定时任务，默认每30分钟执行一次）
initCrawler({
  rules: [
    {
      remark: '示例新闻站点',
      base_url: 'https://example-news-site.com',
      home_range_selector: '.news-list',
      title_selector: 'h1',
      content_selector: '.article-content',
      time_selector: '.publish-time',
      exclude_selectors: ['.ad', '.related-links'],
      enabled: true
    }
  ],
  pushApiUrl: 'https://api.example.com/news/push',
  // 可选：字段映射，'-' 表示忽略该字段
  newsItemFieldMap: {
    url: 'link',               // 重命名链接
    title: 'title',            // 保持不变
    content_html: 'content',   // 重命名 HTML 内容
    content_markdown: '-',     // 不推送 markdown
    published_at: 'publishTime'// 重命名发布时间
  }
})
```

### 从接口拉取规则

```javascript
import { initCrawler } from '@howuse/electron-crawler'

initCrawler({
  // 优先使用内存 rules，其次本地 store，最后从接口获取并写入 store
  rulesApiUrl: 'https://example-news-site.com/rules.json',
  ruleTransformer: (data) => data.rules ?? data, // 若返回 { rules: [...] }，可在此转换
  pushApiUrl: 'https://api.example.com/news/push'
})
```

### 使用推送过滤函数

```javascript
import { initCrawler } from '@howuse/electron-crawler'

initCrawler({
  rules: [/* ... */],
  pushApiUrl: 'https://api.example.com/news/push',
  // 只推送包含特定关键词的新闻
  isPush: (item) => {
    if (item.title.includes('重要') || item.title.includes('紧急')) {
      return true  // 允许推送
    }
    return false  // 不推送
  }
})
```

### 开发模式

```javascript
import { initCrawler } from '@howuse/electron-crawler'

initCrawler({
  rules: [/* ... */],
  pushApiUrl: 'https://api.example.com/news/push',
  devMode: true  // 开发模式：不使用本地缓存，每次都从 API 拉取最新规则
})
```

### 配置选项

| 选项 | 类型 | 描述 |
|------|------|------|
| `rules` | `NewsRule[]` | 直接提供的规则数组 |
| `rulesApiUrl` | `string` | 规则API接口URL |
| `pushApiUrl` | `string` | 结果推送API接口URL（必填以启用推送） |
| `ruleTransformer` | `(data: any) => any` | 规则转换函数 |
| `devMode` | `boolean` | 是否处于开发模式。开发模式：不使用本地缓存，每次都优先使用内存 rules，其次直接从 API 拉取；生产模式：会使用本地缓存（带 5 小时过期时间） |
| `isPush` | `(item: NewsItem) => boolean \| null \| undefined` | 推送前判断函数。返回 `true`、`undefined` 或 `null` 时允许推送，返回 `false` 时不推送。可用于过滤不需要推送的新闻项 |
| `newsItemFieldMap` | `Partial<Record<keyof NewsItem, string \| '-'>>` | 推送字段映射，值为 '-' 表示忽略该字段 |

### NewsRule 结构

| 属性 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `remark` | `string` | 是 | 备注 |
| `base_url` | `string` | 是 | 网站URL |
| `home_range_selector` | `string` | 是 | 首页范围选择器 |
| `title_selector` | `string` | 是 | 标题选择器 |
| `content_selector` | `string` | 是 | 内容选择器 |
| `time_selector` | `string` | 是 | 时间选择器 |
| `exclude_selectors` | `string[]` | 否 | 排除元素选择器数组 |
| `enabled` | `boolean` | 否 | 是否启用，默认为 true |

## API

### `initCrawler(config: CrawlerConfig)`
初始化并启动定时爬虫。会按配置自动拉取规则（内存 > 本地 store > API），并在每次抓取时为每条新闻立即推送到 `pushApiUrl`。

## 注意事项

1. 此包需要在 Electron 环境中运行
2. 请遵守目标网站的 robots.txt 和使用条款
3. 建议设置合理的请求间隔，避免对目标服务器造成压力

## 许可证

MIT