techno-neighbour/focal-harvest
GitHub: techno-neighbour/focal-harvest
一款轻量级 Python CLI 工具，自动化完成网页搜索、抓取、清洗与 AI 内容整合，支持离线回退和 17+ 平台的持续话题监控。
Stars: 18 | Forks: 0
# 
Focal Harvest
Focal Harvest 是一款轻量级的 Python CLI 工具，包含两个主要用例，并提供零配置的本地统计回退功能以支持离线运行：
* **自动化研究 Pipeline**：查询搜索引擎，抓取并清洗目标页面，使用 Gemini、Claude 或 GPT-4o-mini 将结果整合为结构化报告。
* **OSINT 收集框架**：通过 daemon 调度、Wayback Machine 回退机制以及 Discord/Telegram 提醒分发，监控 Reddit、Hacker News、Stack Overflow、arXiv 等 17+ 平台上的话题。
[](https://github.com/techno-neighbour/focal-harvest)
[](https://github.com/techno-neighbour/focal-harvest/blob/main/LICENSE)
[](https://www.python.org/)
```
Python • AI Agent • Web Research • CLI • Zero-Config Offline Fallback
```
## ⚡ 快速开始（30 秒内上手）
### 安装
请确保已安装 Python 3.12+。运行跨平台安装程序：
```
python install.py
```
*（或者运行 `pip install -r requirements.txt` 进行标准的手动安装）。*
### 最小可用示例（CLI 启动）
启动交互式终端用户界面（TUI）：
```
python main.py
```
### Python API 编程式用法
对于自定义的自动化脚本，您可以在 Python 中以编程方式运行抓取与整合 pipeline：
```
from scraper import search_duckduckgo, scrape_urls_concurrently
from analyzer import synthesize_topics
# 1. 搜索 query
results = search_duckduckgo("Gemini 1.5 Flash vs Pro", max_results=3)
urls = [r["url"] for r in results]
# 2. 在并行线程中并发抓取目标页面
scraped_data = scrape_urls_concurrently(urls)
# 3. 将发现的结果合成为结构化的 Markdown 报告
report = synthesize_topics(
scraped_data,
query="Gemini 1.5 Flash vs Pro",
spec_topic="pricing comparisons"
)
print(report)
```
## 🎯 问题与我们的解决方案
每位开发者、研究人员和技术博主都在重复同样繁琐的手动工作流程：
`搜索查询 ➔ 打开 20 个浏览器标签页 ➔ 忽略 Cookie 弹窗与广告 ➔ 复制粘贴片段 ➔ 使用 LLM 整合 ➔ 保存报告`
**Focal Harvest** 将这整个流程自动化，并封装在一个轻量级的终端 pipeline 中。
### 📊 性能基准测试（典型运行）
| 指标 / 操作 | 手动浏览器扫描 | 笨重的本地 LLM (Ollama/Llama3) | Focal Harvest |
| :--- | :--- | :--- | :--- |
| **安装包大小** | ~150MB (Chrome) | ~4.7GB (Llama3-8B) | **<5.2MB** (零依赖核心) |
| **冷启动时间** | ~1.5s | ~12.5s（模型加载） | **<0.15s** (TUI 瞬时启动) |
| **抓取与清洗速度** | 每页约 45s | 每页约 1.2s（原始 HTML） | **每页 <0.25s**（并行可读性处理） |
| **上下文密度** | 大量冗余（广告/导航栏） | 中等（包含所有 HTML 标签） | **高密度**（排名前 15 的关键句子） |
| **资源占用** | ~1.2GB RAM | ~6.5GB RAM + 专用 GPU | **<85MB RAM**（可在低端硬件上运行） |
## ⚙️ 工作原理
```
graph LR
A["Focus Query"] --> B["Concurrent Scraper (utils.py)"]
B --> C["Readability Engine (scraper.py)"]
C --> D["Synthesis Engine (analyzer.py)"]
D --> E["TUI Reports / Webhooks (notifier.py)"]
style A fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000000
style E fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000000
```
1. **编排搜索**：通过 Tavily 或 DuckDuckGo 解析搜索参数。
2. **并发抓取**：在并行线程中抓取页面，并绕过 Cloudflare 拦截。
3. **HTML 净化**：剔除广告、小组件和 Cookie 遮罩层，仅保留纯净文本。
4. **自适应补充**：丢弃被屏蔽或空白的页面，并自动抓取替代内容，以确保高密度的有效输入。
5. **AI / 本地整合**：使用 Gemini、Claude 或 OpenAI 总结内容，并支持 API 密钥的自动故障转移。如果未提供 API 密钥，则会自动回退到离线的 PositionRank 统计排名器。
6. **即时分发**：在本地保存结构化的 Markdown/JSON 报告，并将提醒推送到 Discord/Telegram。
## 📋 示例输出
以下是研究**“Gemini 1.5 Flash vs Gemini 1.5 Pro”**时生成的结构化 Markdown 报告的真实示例：
## ✨ 功能特性
### 🔍 健壮的 Web 抓取
* **可选的 403 绕过 (`curl_cffi`)**：模拟标准的 Chrome TLS/JA3 签名和客户端提示，以绕过 Akamai 和 Cloudflare 的反机器人拦截。
* **Wayback Machine 回退机制**：自动将受保护的 SPA（Reddit、Stack Overflow、Quora）重定向到 Internet Archive，以绕过登录限制。
* **条件式 User-Agent 路由**：抓取访客页面时自动切换至 `Discordbot/2.0`；在配置了用户 cookie 时切换至桌面版 Chrome UA，以避免被机器人签名拦截。
* **统一的 Cookie 导入**：支持 Netscape `config/cookies.txt` 文件以及通用的域名到 Cookie 的映射，可抓取位于登录墙后的页面。
### 🧹 17+ 内置自定义插件
预配置的解析器模块，专为清洗和提取结构化布局而设计：
* **HN & Reddit**：捕获嵌套的评论线程和递归的树状层级结构。
* **Stack Overflow**：清洗代码块并识别已采纳的回答。
* **arXiv & Google Scholar**：提取学术元数据、摘要以及作者指标。
* **金融 (Yahoo/SEC EDGAR)**：抓取财务流，并将数据表格转换为 Markdown 表格。
* **ReadTheDocs & Dev.to**：剥离侧边导航栏和页眉。
### 🧠 智能整合与 AI 路由
* **多提供商故障转移**：在降级到离线关键字 PositionRanker 之前，自动按顺序级联尝试 API 密钥（Gemini ➡️ OpenAI ➡️ Claude）。
* **实时搜索 Grounding**：集成 Gemini 实时 Google 搜索 grounding 功能，直接在模型中获取带有引用的实时事实。
* **本地优先缓存**：将 MD5 哈希结果保存在 `reports/cache/` 中，对于周期性出现的话题可跳过网络请求。
## 🛠️ 代码库架构与文件结构
### 系统执行工作流
```
sequenceDiagram
participant User
participant CLI as main.py
participant Scraper as scraper.py
participant AI as analyzer.py
participant Notifier as notifier.py
User->>CLI: Selects Option 1 (Single Scrape)
CLI->>Scraper: Search Query & Crawl Targets
Scraper->>Scraper: Run concurrent thread scrapes
Scraper->>CLI: Return clean list of page contents
CLI->>AI: Synthesize contents (AI or Local)
AI->>CLI: Return structured report
CLI->>Notifier: Export Markdown/JSON & Send Webhooks
Notifier->>User: Renders Report in Terminal + sends Alerts
```
### 文件夹布局
```
├── install.py # Platform-independent setup script
├── main.py # Interactive TUI Controller (Version v1.2.0)
├── config_manager.py # Reads and writes config.json
├── scraper.py # DuckDuckGo/Tavily search, crawler, and HTML cleaning
├── analyzer.py # Multi-LLM provider wrappers and PositionRank offline logic
├── notifier.py # Markdown exporter and Discord/Telegram webhook dispatch
├── utils.py # HTTP request wrapper with retries, cookies, and header sanitization
├── std_plugins/ # Built-in plugins (Hacker News, Reddit, Stack Overflow, etc.)
└── tests/ # Isolated unit tests suite
```
## ⚖️ 5 条严格的设计边界（切勿违反）
Focal Harvest 严格遵循以下核心维护准则：
1. **轻量级足迹**：应用程序保持在 5MB 以下，并在几秒钟内完成安装。
2. **仅限 TUI**：完全在控制台中运行——没有本地 React 仪表板或本地 REST 服务器。
3. **低硬件要求**：在低配置的学生笔记本电脑上也能流畅运行。
4. **无本地 AI 下载**：使用远程 API（Gemini/OpenAI/Claude），以避开数 GB 大小的 Ollama/Llama 下载。
5. **无 SQL 数据库**：以纯 JSON 和 Markdown 文件存储报告，确保绝对的文件系统透明度。
## 🛣️ 路线图
* [x] 并行并发爬虫
* [x] 混合可读性文本解析器
* [x] 多 LLM 提供商故障转移
* [x] Discord / Telegram webhook 分发
* [x] 模拟请求头与 WAF 绕过机制
* [x] 统一的 Netscape `cookies.txt` 映射
* [ ] **增量更新**：生成仅包含差异的摘要，或将更新追加到现有报告中。
* [ ] **PDF/CSV 导出器**：将研究扫描结果导出为 PDF 和结构化的 CSV 表格。
## ⚖️ 法律免责声明与合理使用
Focal Harvest 是一款用于个人和研究目的的命令行实用工具。
* **公开数据抓取**：根据美国既定判例法，对公开数据进行程序化抓取受法律保护。请以合理的频率运行爬虫，尊重目标服务器。
* **授权抓取**：请勿将带有 session cookie 的活跃个人账户用于此目的。请务必使用一次性/专用账户，以防止账户被封停。
## 📜 许可证
基于 MIT 许可证分发。详情请参阅 `LICENSE`。
Focal Harvest
Focal Harvest 是一款轻量级的 Python CLI 工具，包含两个主要用例，并提供零配置的本地统计回退功能以支持离线运行：
* **自动化研究 Pipeline**：查询搜索引擎，抓取并清洗目标页面，使用 Gemini、Claude 或 GPT-4o-mini 将结果整合为结构化报告。
* **OSINT 收集框架**：通过 daemon 调度、Wayback Machine 回退机制以及 Discord/Telegram 提醒分发，监控 Reddit、Hacker News、Stack Overflow、arXiv 等 17+ 平台上的话题。
[](https://github.com/techno-neighbour/focal-harvest)
[](https://github.com/techno-neighbour/focal-harvest/blob/main/LICENSE)
[](https://www.python.org/)
```
Python • AI Agent • Web Research • CLI • Zero-Config Offline Fallback
```
## ⚡ 快速开始（30 秒内上手）
### 安装
请确保已安装 Python 3.12+。运行跨平台安装程序：
```
python install.py
```
*（或者运行 `pip install -r requirements.txt` 进行标准的手动安装）。*
### 最小可用示例（CLI 启动）
启动交互式终端用户界面（TUI）：
```
python main.py
```
### Python API 编程式用法
对于自定义的自动化脚本，您可以在 Python 中以编程方式运行抓取与整合 pipeline：
```
from scraper import search_duckduckgo, scrape_urls_concurrently
from analyzer import synthesize_topics
# 1. 搜索 query
results = search_duckduckgo("Gemini 1.5 Flash vs Pro", max_results=3)
urls = [r["url"] for r in results]
# 2. 在并行线程中并发抓取目标页面
scraped_data = scrape_urls_concurrently(urls)
# 3. 将发现的结果合成为结构化的 Markdown 报告
report = synthesize_topics(
scraped_data,
query="Gemini 1.5 Flash vs Pro",
spec_topic="pricing comparisons"
)
print(report)
```
## 🎯 问题与我们的解决方案
每位开发者、研究人员和技术博主都在重复同样繁琐的手动工作流程：
`搜索查询 ➔ 打开 20 个浏览器标签页 ➔ 忽略 Cookie 弹窗与广告 ➔ 复制粘贴片段 ➔ 使用 LLM 整合 ➔ 保存报告`
**Focal Harvest** 将这整个流程自动化，并封装在一个轻量级的终端 pipeline 中。
### 📊 性能基准测试（典型运行）
| 指标 / 操作 | 手动浏览器扫描 | 笨重的本地 LLM (Ollama/Llama3) | Focal Harvest |
| :--- | :--- | :--- | :--- |
| **安装包大小** | ~150MB (Chrome) | ~4.7GB (Llama3-8B) | **<5.2MB** (零依赖核心) |
| **冷启动时间** | ~1.5s | ~12.5s（模型加载） | **<0.15s** (TUI 瞬时启动) |
| **抓取与清洗速度** | 每页约 45s | 每页约 1.2s（原始 HTML） | **每页 <0.25s**（并行可读性处理） |
| **上下文密度** | 大量冗余（广告/导航栏） | 中等（包含所有 HTML 标签） | **高密度**（排名前 15 的关键句子） |
| **资源占用** | ~1.2GB RAM | ~6.5GB RAM + 专用 GPU | **<85MB RAM**（可在低端硬件上运行） |
## ⚙️ 工作原理
```
graph LR
A["Focus Query"] --> B["Concurrent Scraper (utils.py)"]
B --> C["Readability Engine (scraper.py)"]
C --> D["Synthesis Engine (analyzer.py)"]
D --> E["TUI Reports / Webhooks (notifier.py)"]
style A fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000000
style E fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000000
```
1. **编排搜索**：通过 Tavily 或 DuckDuckGo 解析搜索参数。
2. **并发抓取**：在并行线程中抓取页面，并绕过 Cloudflare 拦截。
3. **HTML 净化**：剔除广告、小组件和 Cookie 遮罩层，仅保留纯净文本。
4. **自适应补充**：丢弃被屏蔽或空白的页面，并自动抓取替代内容，以确保高密度的有效输入。
5. **AI / 本地整合**：使用 Gemini、Claude 或 OpenAI 总结内容，并支持 API 密钥的自动故障转移。如果未提供 API 密钥，则会自动回退到离线的 PositionRank 统计排名器。
6. **即时分发**：在本地保存结构化的 Markdown/JSON 报告，并将提醒推送到 Discord/Telegram。
## 📋 示例输出
以下是研究**“Gemini 1.5 Flash vs Gemini 1.5 Pro”**时生成的结构化 Markdown 报告的真实示例：
## ✨ 功能特性
### 🔍 健壮的 Web 抓取
* **可选的 403 绕过 (`curl_cffi`)**：模拟标准的 Chrome TLS/JA3 签名和客户端提示，以绕过 Akamai 和 Cloudflare 的反机器人拦截。
* **Wayback Machine 回退机制**：自动将受保护的 SPA（Reddit、Stack Overflow、Quora）重定向到 Internet Archive，以绕过登录限制。
* **条件式 User-Agent 路由**：抓取访客页面时自动切换至 `Discordbot/2.0`；在配置了用户 cookie 时切换至桌面版 Chrome UA，以避免被机器人签名拦截。
* **统一的 Cookie 导入**：支持 Netscape `config/cookies.txt` 文件以及通用的域名到 Cookie 的映射，可抓取位于登录墙后的页面。
### 🧹 17+ 内置自定义插件
预配置的解析器模块，专为清洗和提取结构化布局而设计：
* **HN & Reddit**：捕获嵌套的评论线程和递归的树状层级结构。
* **Stack Overflow**：清洗代码块并识别已采纳的回答。
* **arXiv & Google Scholar**：提取学术元数据、摘要以及作者指标。
* **金融 (Yahoo/SEC EDGAR)**：抓取财务流，并将数据表格转换为 Markdown 表格。
* **ReadTheDocs & Dev.to**：剥离侧边导航栏和页眉。
### 🧠 智能整合与 AI 路由
* **多提供商故障转移**：在降级到离线关键字 PositionRanker 之前，自动按顺序级联尝试 API 密钥（Gemini ➡️ OpenAI ➡️ Claude）。
* **实时搜索 Grounding**：集成 Gemini 实时 Google 搜索 grounding 功能，直接在模型中获取带有引用的实时事实。
* **本地优先缓存**：将 MD5 哈希结果保存在 `reports/cache/` 中，对于周期性出现的话题可跳过网络请求。
## 🛠️ 代码库架构与文件结构
### 系统执行工作流
```
sequenceDiagram
participant User
participant CLI as main.py
participant Scraper as scraper.py
participant AI as analyzer.py
participant Notifier as notifier.py
User->>CLI: Selects Option 1 (Single Scrape)
CLI->>Scraper: Search Query & Crawl Targets
Scraper->>Scraper: Run concurrent thread scrapes
Scraper->>CLI: Return clean list of page contents
CLI->>AI: Synthesize contents (AI or Local)
AI->>CLI: Return structured report
CLI->>Notifier: Export Markdown/JSON & Send Webhooks
Notifier->>User: Renders Report in Terminal + sends Alerts
```
### 文件夹布局
```
├── install.py # Platform-independent setup script
├── main.py # Interactive TUI Controller (Version v1.2.0)
├── config_manager.py # Reads and writes config.json
├── scraper.py # DuckDuckGo/Tavily search, crawler, and HTML cleaning
├── analyzer.py # Multi-LLM provider wrappers and PositionRank offline logic
├── notifier.py # Markdown exporter and Discord/Telegram webhook dispatch
├── utils.py # HTTP request wrapper with retries, cookies, and header sanitization
├── std_plugins/ # Built-in plugins (Hacker News, Reddit, Stack Overflow, etc.)
└── tests/ # Isolated unit tests suite
```
## ⚖️ 5 条严格的设计边界（切勿违反）
Focal Harvest 严格遵循以下核心维护准则：
1. **轻量级足迹**：应用程序保持在 5MB 以下，并在几秒钟内完成安装。
2. **仅限 TUI**：完全在控制台中运行——没有本地 React 仪表板或本地 REST 服务器。
3. **低硬件要求**：在低配置的学生笔记本电脑上也能流畅运行。
4. **无本地 AI 下载**：使用远程 API（Gemini/OpenAI/Claude），以避开数 GB 大小的 Ollama/Llama 下载。
5. **无 SQL 数据库**：以纯 JSON 和 Markdown 文件存储报告，确保绝对的文件系统透明度。
## 🛣️ 路线图
* [x] 并行并发爬虫
* [x] 混合可读性文本解析器
* [x] 多 LLM 提供商故障转移
* [x] Discord / Telegram webhook 分发
* [x] 模拟请求头与 WAF 绕过机制
* [x] 统一的 Netscape `cookies.txt` 映射
* [ ] **增量更新**：生成仅包含差异的摘要，或将更新追加到现有报告中。
* [ ] **PDF/CSV 导出器**：将研究扫描结果导出为 PDF 和结构化的 CSV 表格。
## ⚖️ 法律免责声明与合理使用
Focal Harvest 是一款用于个人和研究目的的命令行实用工具。
* **公开数据抓取**：根据美国既定判例法，对公开数据进行程序化抓取受法律保护。请以合理的频率运行爬虫，尊重目标服务器。
* **授权抓取**：请勿将带有 session cookie 的活跃个人账户用于此目的。请务必使用一次性/专用账户，以防止账户被封停。
## 📜 许可证
基于 MIT 许可证分发。详情请参阅 `LICENSE`。标签：Petitpotam, Python, 人工智能, 无后门, 用户模式Hook绕过, 网络调试, 自动化, 逆向工具