wechat-search

---
name: wechat-search
description: 公众号搜索工具，支持按关键词搜索爆款文章，展示推荐热门文章，助力内容创作者把握趋势与获取灵感；当用户需要搜索公众号文章、查找爆款内容、获取创作灵感时使用
dependency:
  python:
    - 无第三方依赖（纯标准库：urllib.request, json, os, sys, argparse, datetime）
---

# 公众号热门文章查询

## 1. 简介

公众号热门爆款文章查询工具，支持按关键词搜索微信公众号爆款文章，并基于相关性、热度、时效三维评分智能排序推荐。专注服务于公众号内容创作者、新媒体运营者和自媒体团队，帮助用户快速发现热门选题、分析爆款规律、获取创作灵感。

## 2. 功能特性

- 🔍 **关键词智能搜索** — 支持关键词精确搜索和多关键词组合查询（逗号分隔），覆盖全品类公众号文章
- 📊 **三维评分排序** — 基于相关性（满分10分）、热度（满分3分）、时效（满分2分）加权计算总分（满分15分），智能排序推荐
- ⏱️ **灵活时间范围** — 默认查询最近7天，支持自动拓展时间（1天→7天→30天），数据每日早上7点更新
- 🧠 **赛道词识别与拓展** — 自动识别泛化赛道词并推荐10个细分方向，帮助用户精准定位
- 🔥 **热门推荐文章** — 结果较少时自动展示近期热门推荐文章和热门话题
- 📩 **定时订阅推送** — 支持创建日历订阅任务，到达设定时间自动推送最新爆款文章
- 📄 **HTML 报告生成** — 可选生成 HTML 可视化文件，方便独立查看和分享
- 📋 **数字智能格式化** — 万级以上阅读数自动转换（如 `10.0w`），总分字段加粗突出显示

## 3. 一键安装

### 鉴权

#### 获取 API Key

请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 获取API KEY

#### 配置 API Key

方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中：

```bash
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
```

方案2: 终端配置

```bash
export REDFOX_API_KEY="ak_xxxx..."
```

### 依赖安装

本 Skill 使用 Python 3.13+ 纯标准库（urllib.request、json、os、sys、argparse、datetime），无需安装任何第三方依赖。

### 环境变量配置

| 环境变量 | 说明 | 是否必填 | 获取方式 |
| -------- | ---- | -------- | -------- |
| `REDFOX_API_KEY` | 红狐数据 API Key | 是 | [红狐hub](https://redfox.hk/settings/api-keys?source=github) |

## 4. 使用指南

### 基础使用（3 步完成查询）

**Step 1 — 提取关键词**：从用户描述中提取搜索关键词，判断是赛道词还是细分词。

- **赛道词**：较大的分类词，如"职场""情感""亲子""美妆"等
- **非赛道词**：具体细分词，如"职场沟通技巧""异地恋怎么维持"等

**Step 2 — 调用脚本**：

```bash
python scripts/fetch_gzh_trends.py --keyword <关键词> --start-date <日期>
```

- 有赛道关键词：`python scripts/fetch_gzh_trends.py --keyword <关键词> --start-date <日期>`
- 无赛道关键词（查询全站热门）：`python scripts/fetch_gzh_trends.py --keyword "" --start-date <日期>`
- 多个关键词用逗号分隔：`python scripts/fetch_gzh_trends.py --keyword "职场沟通,恋爱技巧,亲子教育" --start-date <日期>`

**⚠️ 防重复调用规则（强制）**：

- ❌ **禁止**先用 `head`/`tail`/`2>/dev/null | head -5` 等方式"试运行"或"预览"脚本输出
- ❌ **禁止**在同一次查询中对同一参数多次调用脚本
- ✅ **每次查询只执行一次脚本命令**，直接读取完整的 stdout 输出
- ✅ 唯一允许多次调用的场景：数据不足时按规定的自动拓展时间（近1天→近7天→近30天），每次使用不同的 `--start-date`

**Step 3 — 查看结果**：脚本返回结构化 JSON 数据，按本指南规定的展示策略输出结果。

---

### 高级使用

#### 赛道词处理流程（仅当识别为赛道词时执行）

**第一步：识别并询问用户（⚠️ 仅当用户明确要求时才执行）**

```
我识别到「职场」是较大的分类，已查询近期热门趋势，推荐以下细分方向：
工作、打工人、职场穿搭、职场干货、成长、冷门职业、向上管理、职场焦虑、升职、财务自由
回复「拓展」将同时搜索这10个词，回复「不拓展」将继续搜索「职场」
```

**第二步：等待用户回复**
- ❌ **禁止**：用户未回复时调用脚本
- ❌ **禁止**：自动执行拓展搜索（必须等用户明确回复「拓展」）
- ✅ **正确**：只等待用户明确回复后再执行

**第三步：根据用户明确回复执行**
- 用户回复「拓展」 → 调用脚本搜索10个细分词
- 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词
- 用户未回复或回复其他内容 → 识别对应意图

---

#### 时间范围与数据查询

**时间范围**：

- 数据库只包含昨天至30天前的数据
- **"最近"的默认定义**：最近7天（startDate = 今天 - 7天）
- **日期计算**（将用户表达转换为 startDate）：
  - 今天：直接用昨天日期，startDate = 昨天
  - 最近/近7天：startDate = 今天 - 7天
  - 近N天：startDate = 今天 - N天
  - 示例：用户说"近15天" → startDate = 今天 - 15天

**数据不足时的自动拓展时间**：

- ✅ 当 articles 数量不足时，自动按顺序拓展时间范围：近1天 → 近7天 → 近30天
- ✅ 每次拓展后重新调用脚本查询，直到获取到数据或拓展到30天为止
- ❌ **禁止自动扩展关键词搜索**：搜索结果不足10条时，禁止用拓展词/相关词/同义词再次调用接口搜索
- ❌ **禁止自动尝试相关搜索建议**
- ✅ 拓展时间后仍无数据，直接返回 articles=0 的结果

**超出范围或未更新数据的道歉说明**：

- 用户说"今天/今日"时：回答"非常抱歉，今天的数据暂未更新，已为您展示最近可用的数据"
- 用户要求的时间超出30天时：回答"非常抱歉，当前仅支持最近30天的数据，已为您展示最接近的数据"

**输出文件**：

- JSON数据：输出到标准输出（stdout）
- HTML文件：`{keyword}_趋势数据.html`（可选）

---

#### 前置说明（在展示数据前必须告知用户）

- **数据说明**：爆款文章范围为阅读数5000+以上的文章，每日早上7点更新昨日数据。文章互动数据截止为入库时间，不是实时数据，入库后互动数据可能持续增长。
- **排序说明**（有关键词搜索时）：根据相关性（满分10分）、热度（满分3分）、时效（满分2分）三个维度加权计算，总分共15分
- **排序说明**（全站热门/无关键词时）：按阅读数排序

---

#### 数据展示策略（核心）

**⚠️ 强制输出规则**：

- ✅ 必须严格按照本步骤规定的格式输出
- ❌ 禁止在输出前添加任何分析或解读
- ❌ 禁止自作主张给建议或方案
- ❌ 禁止询问用户的真实目的或需求
- ✅ 直接读取脚本返回的JSON数据，按照对应策略输出即可

**数据字段说明**：

- **articles**：正常文章数据（主要展示内容）
- **latestHotArticles**：推荐热门文章（辅助内容，默认展示10条，表格不含评分字段）
- **hotTopics**：热门话题（接口返回，仅供参考，不在对话中展示）

##### A. articles数量 ≥ 10条

展示内容：

1. **时间范围说明**：必须告知用户查询的时间范围，如"📅 查询时间范围：5月8日 - 5月19日"
2. 正常文章数据（按totalScore降序排序）
3. 拓词推荐（relatedSearches）

**Markdown表格格式**：

⚠️ **表格字段顺序必须严格按以下顺序展示**：
| 文章标题 | 作者 | 阅读数 | 发布时间 | 相关性 | 热度 | 时效 | **总分** |

**注意**：总分字段需要加粗显示（使用`**分数**`格式）

示例：
📅 查询时间范围：5月8日 - 5月19日

| 文章标题                                                                  | 作者       | 阅读数 | 发布时间   | 相关性 | 热度 | 时效 | **总分** |
| ------------------------------------------------------------------------- | ---------- | ------ | ---------- | ------ | ---- | ---- | -------- |
| [职场新人必看：5个让你快速融入团队的技巧](https://mp.weixin.qq.com/s/xxx) | 职场成长社 | 10.0w  | 2026-05-15 | 9.8    | 3.0  | 2.0  | **14.8** |

---

**🔤 拓词推荐**：职场沟通、职场晋升、打工人

##### B. articles数量 < 10条但 > 0

展示内容：

1. **时间范围说明**：必须告知用户查询的时间范围，如"📅 查询时间范围：5月8日 - 5月19日"
2. **提示信息**："💡当前关键词当前时间段仅找到 X 条结果，您可以尝试拓展词或者拓展时间，我们还为您推荐了近期的热门文章"
3. 正常文章数据
4. 推荐热门文章（latestHotArticles，带"推荐热门文章"标题分区，默认展示10条）
5. 推荐热门话题
6. 拓词推荐（relatedSearches）

**Markdown格式示例**：

📅 查询时间范围：5月8日 - 5月19日

> 💡当前关键词当前时间段仅找到 3 条结果，

| 文章标题     | 作者  | 阅读数 | 发布时间   | 相关性 | 热度 | 时效 | **总分** |
| ------------ | ----- | ------ | ---------- | ------ | ---- | ---- | -------- |
| [文章1](url) | 作者1 | 10.0w  | 2026-05-15 | 9.8    | 3.0  | 2.0  | **14.8** |

**您可以尝试拓展词或者拓展时间，我们还为您推荐了近期的热门文章供参考**：

⚠️ 推荐热门文章表格不需要评分字段，格式为：
| 文章标题 | 作者 | 阅读数 | 发布时间 |
|---------|------|--------|----------|
| [热门文章1](url) | 作者A | 8.5w | 2026-05-14 |
| [热门文章2](url) | 作者B | 6.2w | 2026-05-13 |

**📈 推荐热门话题**：

您可以尝试搜索以下热门赛道：
人文、知识、养生、时尚、美食、生活、旅游、搞笑、情感、体育娱乐、美妆、文摘、民生资讯、财富理财、科技数码、创投商业、汽车、房产楼市、职场、教育考试、学术

##### C. articles数量 = 0

**⚠️ 必须严格按照以下格式输出，禁止自作主张给建议或分析**

展示内容：

```
🔍 抱歉，爆款文章收录原则为阅读数5000+以上的文章,该搜索词在查询时间范围（5月8日 - 5月19日）内太小众，未找到与"XXX"直接相关的内容，你可以尝试用更短/宽泛的关键词重试 。

💡 或者您可以尝试搜索以下热门赛道：
人文、知识、养生、时尚、美食、生活、旅游、搞笑、情感、体育娱乐、美妆、文摘、民生资讯、财富理财、科技数码、创投商业、汽车、房产楼市、职场、教育考试、学术

我们为您推荐近期最热门的文章，您也可以关注~
```

在以上内容之后，展示latestHotArticles数据（如果有），热门推荐表格不需要评分字段：

| 文章标题         | 作者  | 阅读数 | 发布时间   |
| ---------------- | ----- | ------ | ---------- |
| [热门文章1](url) | 作者A | 8.5w   | 2026-05-14 |
| [热门文章2](url) | 作者B | 6.2w   | 2026-05-13 |

**输出规则**：

- ✅ 必须直接输出上述格式内容
- ❌ 禁止添加额外的分析或建议
- ❌ 禁止解释为什么搜不到数据
- ❌ 禁止主动提供其他搜索方案
- ❌ 禁止询问用户的真实目的

---

#### 展示逻辑（分页）

**当articles数量 > 10条时**：

1. 初始默认只展示前10条数据
2. 必须提示用户：
   ```
   💡 当前共找到 X 条相关文章，已展示前10条。是否需要查看全部？
   ```
3. 等待用户回复：
   - 用户回复"是"/"查看全部"/"全部" → 展示全部数据
   - 用户回复"否"/"不用"/"不需要" → 不展示更多

**展示全部数据时的格式**：

```
📊 全部结果（共X条）：

| 文章标题 | 作者 | 阅读数 | 发布时间 | 相关性 | 热度 | 时效 | **总分** |
|---------|------|--------|----------|--------|------|------|------|
| ...（全部数据）...
```

---

#### 智能筛选热门内容（可选）

**⚠️ 此步骤为可选，仅在用户明确要求"筛选"、"推荐"时执行**

**筛选原则**：

- **统一排序**：脚本已自动将所有数据按totalScore排序
- **目标数量**：最多10条，如实展示实际数据量

---

#### 订阅服务询问（必须执行）

**当articles数量 > 0时，结果输出完成后必须询问**：

```
📬 订阅服务
1️⃣ 是否需要订阅当前搜索条件文章，订阅后将定时推送给您？
2️⃣ 暂不需要
```

**处理用户回复**：

- 用户选择1️⃣ → 使用 `calendar_create` 工具创建日程，订阅当前搜索条件
- 用户选择2️⃣ → 结束当前对话

**订阅实现步骤**：

1. **告知数据更新时间并询问推送时间**：

   ```
   📅 数据更新时间：每日早上7点更新昨日数据

   请告诉我您希望推送的具体时间~
   ```

2. **用户选择后，调用 `calendar_create` 工具**：
   - **title**：`公众号趋势订阅：{关键词}`
   - **description**：记录当前搜索参数（关键词、时间范围）
   - **start_time**：根据用户选择的时间设置
   - **remind_type**：设置为定期提醒
   - 其他参数使用当前查询参数

3. **订阅成功后提示**：

   ```
   ✅ 订阅创建成功！

   📌 订阅信息：
   - 关键词：{关键词}
   - 时间范围：{当前时间范围}
   - 推送时间：{用户选择的时间}
   - 数据更新：每日早上7点更新昨日数据

   到达设定时间后，将自动为您推送最新的公众号爆款文章。
   ```

**⚠️ 强制规则**：

- ✅ 必须在结果输出完成后立即询问
- ✅ 用户选择订阅时，必须使用 `calendar_create` 工具
- ✅ 参数必须使用当前查询参数（关键词、时间范围等）
- ❌ 禁止跳过此步骤
- ❌ 禁止在展示结果前询问

---

### 常用命令速查表

| 场景 | 命令 |
| ---- | ---- |
| 关键词搜索（默认近7天） | `python scripts/fetch_gzh_trends.py --keyword "关键词" --start-date <日期>` |
| 全站热门 | `python scripts/fetch_gzh_trends.py --keyword "" --start-date <日期>` |
| 多关键词搜索 | `python scripts/fetch_gzh_trends.py --keyword "词1,词2,词3" --start-date <日期>` |
| 指定时间范围 | `python scripts/fetch_gzh_trends.py --keyword "关键词" --start-date 2026-05-08` |
| 生成 HTML 报告 | 脚本自动生成 `{keyword}_趋势数据.html` |
| 订阅创建 | 回复1️⃣后使用 `calendar_create` 工具创建定时任务 |

## 5. 使用场景

### 场景一：公众号创作者寻找选题灵感

- **角色**：公众号内容创作者
- **需求**：想了解近期"职场"领域有哪些爆款文章，寻找下一篇选题灵感
- **使用方式**：输入赛道词「职场」后，系统推荐 10 个细分方向（如"职场穿搭""向上管理"等），回复「拓展」批量搜索
- **预期收益**：通过三维评分排序快速锁定高价值选题方向，了解同赛道爆款文章的内容特征

### 场景二：新媒体运营竞品分析

- **角色**：新媒体运营经理
- **需求**：需要分析竞品公众号近期发布了哪些爆款文章，了解其内容策略
- **使用方式**：搜索竞品公众号名称或相关领域关键词，查看按 totalScore 排序的文章列表
- **预期收益**：系统了解竞品的内容选题、标题套路和发布节奏，为自身运营策略提供数据支撑

### 场景三：自媒体矩阵内容规划

- **角色**：MCN 机构内容总监
- **需求**：需要一次性查看多个领域（职场、情感、亲子）的近期爆款文章，规划矩阵内容排期
- **使用方式**：使用逗号分隔多关键词 `--keyword "职场,情感,亲子"` 进行跨领域查询
- **预期收益**：一个命令覆盖多个领域，高效获取跨品类热门趋势，提升内容规划效率

### 场景四：每日爆文定时推送

- **角色**：自媒体博主
- **需求**：希望每天上午自动收到特定领域的公众号爆款文章列表
- **使用方式**：搜索关键词后选择「1️⃣ 订阅」，设置推送时间，创建日历定时任务
- **预期收益**：无需手动重复搜索，每日定时获取最新爆款文章，持续跟踪赛道动态

## 6. 项目架构

### 目录结构

```
wechat-search/
├── SKILL.md                          # Skill 定义与使用文档（本文件）
├── scripts/
│   └── fetch_gzh_trends.py           # 核心搜索脚本，调用红狐 API 获取公众号爆款文章
└── references/
    └── gzh_trend_data_format.md      # 数据字段格式参考文档
```

### 技术栈

| 组件 | 技术 | 说明 |
| ---- | ---- | ---- |
| 运行环境 | Python 3.13+ | 纯标准库，无第三方依赖 |
| 标准库 | urllib.request, json, os, sys, argparse, datetime | 用于 HTTP 请求、JSON 处理、参数解析、日期计算 |
| 数据接口 | 红狐 API (Redfox) | 通过 REDFOX_API_KEY 鉴权 |
| 输出格式 | JSON (stdout) + HTML (文件) | JSON 通过 stdout 输出供 AI 解析，HTML 为可选可视化文件 |
| 展示格式 | Markdown 表格 | AI 代理将 JSON 渲染为表格展示 |

### 核心模块说明

| 模块 | 路径 | 功能 |
| ---- | ---- | ---- |
| 搜索脚本 | `scripts/fetch_gzh_trends.py` | 调用红狐接口获取公众号爆款文章，支持 --keyword、--start-date、--max-items、--output-format 参数 |
| 数据格式参考 | `references/gzh_trend_data_format.md` | 详细说明接口返回的数据字段格式和含义 |
| SKILL 定义 | `SKILL.md` | 定义 Skill 元数据、工作流程、展示策略、订阅逻辑 |

### 资源索引

- **核心脚本**：`scripts/fetch_gzh_trends.py` — 调用红狐 API 获取公众号爆款文章数据，参数：--keyword（必需）、--start-date（可选）、--max-items（可选）、--output-format（可选）
- **参考文档**：`references/gzh_trend_data_format.md` — 何时读取：需要了解接口数据格式、字段说明时

## 7. 常见问答

### 安装

**Q: 需要安装哪些依赖？**
A: 本工具使用 Python 3.13+ 纯标准库（urllib.request、json、os、sys、argparse、datetime），无需安装任何第三方依赖。确保系统已安装 Python 3.13 或更高版本。

**Q: 如何获取 API Key？**
A: 请访问 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 注册并获取 API Key，按本文"一键安装"章节配置环境变量。

### 使用

**Q: 赛道词和非赛道词有什么区别？**
A: 赛道词是较大分类词（如"职场""情感"），识别后会触发拓展策略；非赛道词是具体细分词（如"职场沟通技巧"），直接搜索无需拓展询问。

**Q: 数据的时间范围是什么？**
A: 数据库仅包含昨天至30天前的数据，默认查询最近7天。数据不足时会自动拓展时间范围（1天→7天→30天）。每日早上7点更新昨日数据。

**Q: 为什么表格中有些字段有评分、有些没有？**
A: 有关键词搜索时按 totalScore（相关性+热度+时效）排序，展示评分字段；全站热门按阅读数排序，无评分字段。推荐热门文章表格也不含评分。

**Q: 如何查看超过 10 条的完整结果？**
A: 当结果超过 10 条时，系统会提示「是否查看全部？」。回复「是」「查看全部」或「全部」即可展示完整数据。

### 故障排除

**Q: 脚本执行返回空结果？**
A: 爆款文章收录原则为阅读数5000+以上。如果关键词太小众或时间范围太短，可能无数据。系统会自动拓展时间范围，若拓展到30天仍无数据则返回空。可尝试更短/更宽泛的关键词。

**Q: 提示"今天的数据暂未更新"？**
A: 数据库每日早上7点更新昨日数据，当天数据尚未入库。系统会自动展示最近可用的数据。

**Q: 脚本报错怎么办？**
A: 常见原因：(1) REDFOX_API_KEY 未配置或已过期；(2) Python 版本 < 3.13；(3) 网络问题。请逐一排查。

### 安全许可

**Q: API Key 如何安全存储？**
A: 推荐使用方案 1（配置到 openclaw.json 的 env 字段中），避免在终端历史中泄露。请勿将 API Key 硬编码在脚本中或上传到公开仓库。

**Q: 数据来源和版权？**
A: 数据来源于红狐 API 收录的公众号公开文章。文章版权归原作者所有，本工具仅供学习和内容创作参考使用。