Gzh Search

---
name: gzh-search-crawler
description: 公众号搜索爬虫 — 通过关键词搜索微信公众号文章，终端表格展示（标题/作者/阅读/点赞/分享/收藏/发布时间/文章链接），自动导出 CSV 并生成交互式 HTML 报告。当用户需要搜索、爬取或浏览公众号文章时使用；也适用于行业热点追踪、竞品内容分析、素材灵感搜集等场景。
---

# 公众号搜索爬虫

输入关键词搜索微信公众号文章，终端表格展示 + CSV 导出 + 交互式 HTML 报告。

> 需先配置 API Key，通过环境变量 REDFOX_API_KEY 或 --api-key 参数传入。
> 爬取范围：**腰部以上公众号**近 30 天内发布的文章。
> 关键词限制：**不超过 10 个字符**，超出会提示精简。

---

## 使用场景

当你需要执行以下任务时，应优先使用本技能：

| 场景             | 示例                                       |
| ---------------- | ------------------------------------------ |
| **行业热点追踪** | 搜 "AI" 了解近期 AI 领域公众号都在讨论什么 |
| **竞品内容分析** | 搜 "大模型" 爬取竞争对手公众号的文章策略   |
| **素材灵感搜集** | 搜 "小红书运营" 获取爆款选题和写作角度     |
| **趋势研究报告** | 搜 "2026 经济" 批量导出 CSV 做数据分析     |
| **寻找优质账号** | 搜 "科技" 发现相关领域的头部公众号         |
| **话题舆情监控** | 搜 "品牌名" 查看公众号对该品牌的讨论风向   |

> 如果你想搜**某个特定公众号的全部历史文章**，应使用 `gzh-subscribe` 技能（公众号文章订阅），它专门针对单账号订阅追踪。

---

## 使用方法

```bash
# 基础搜索
python3 "$SKILL_PATH/assets/search.py" "关键词"

# 指定数量（多页自动翻页）
python3 "$SKILL_PATH/assets/search.py" "AI" --count 50

# 仅导出 CSV
python3 "$SKILL_PATH/assets/search.py" "大模型" --csv-only

# 不自动打开浏览器
python3 "$SKILL_PATH/assets/search.py" "AI" --no-open
```

终端输出按**综合评分**（关键词相关性 + 阅读热度 + 时效新鲜度）降序排列，同分时按阅读量高的优先；结果较少或无结果时自动分层提示。

HTML 报告特性：深色主题 · 实时搜索（300ms 防抖）· 文章卡片点击跳转原文 · 分页加载 · 零结果时引导热门话题。

CSV / HTML 默认保存在 `~/Downloads/QoderGzhSearch/`。

---

## 参数说明

| 参数           | 说明                         | 默认值                       |
| -------------- | ---------------------------- | ---------------------------- |
| `keyword`      | 搜索关键词（必填，位置参数） | —                            |
| `--count`      | 获取文章数量                 | `20`                         |
| `--sort-type`  | 排序方式：`default` / `time` | `default`                    |
| `--output-dir` | 输出目录                     | `~/Downloads/QoderGzhSearch` |
| `--api-key`    | 指定 API Key                 | —                            |
| `--no-open`    | 不自动打开浏览器             | —                            |
| `--csv-only`   | 仅生成 CSV，不生成 HTML      | —                            |
| `--port`       | HTML 本地服务端口            | `8766`                       |

---

## API Key 配置

任选一种方式配置个人 Key：

| 方式             | 命令                                                           |
| ---------------- | -------------------------------------------------------------- |
| 环境变量（推荐） | `export REDFOX_API_KEY=ak_你的密钥`                            |
| 命令行参数       | `--api-key ak_你的密钥`                                        |
| 配置文件         | `echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json` |

注册地址：[redfox.hk](https://redfox.hk/settings/api-keys?source=github)

---

## 功能特点

- **关键词搜索**：实时查询全量微信公众号文章
- **智能评分排序**：三因子（相关性 + 热度 + 时效）综合评分，同分按阅读量降序
- **分层响应降级**：充足时正常浏览 / 较少时引导宽泛搜索 / 无结果时热门兜底
- **终端表格**：标题、作者、阅读、点赞、分享、收藏、发布时间、文章链接
- **CSV 导出**：自动生成 UTF-8 BOM 编码的 CSV
- **HTML 交互报告**：内置搜索框，支持封面图展示，点击卡片跳转原文
- **本地代理服务**：避免浏览器跨域限制

---

## 依赖

```bash
pip3 install requests
```

---

## 常见问题

**Q：搜索范围？**
A：目前覆盖**腰部以上公众号**近 30 天内发布的文章，不保证覆盖所有账号和全部历史。

**Q：我想搜某个特定公众号的所有文章怎么办？**
A：请使用 `gzh-subscribe` 技能（公众号文章订阅），它支持按公众号 ID 订阅追踪单账号的全部文章。

**Q：最多返回多少条？**
A：单次默认 20 条，通过 `--count` 调整，HTML 页面支持分页加载更多。

**Q：数据保存在哪？**
A：`~/Downloads/QoderGzhSearch/`，文件名格式 `公众号搜索_[关键词]_YYYY-MM-DD.csv/html`。

**Q：为什么需要本地服务？**
A：浏览器直接打开 HTML 有跨域限制，内置 HTTP 代理中转 API 请求。

**Q：额度用完怎么办？**
A：前往 [redfox.hk](https://redfox.hk/settings/api-keys?source=github) 注册获取 Token。