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

# 公众号热门文章查询

## 任务目标

- 本 Skill 用于：查询公众号热门爆款文章，获取创作灵感
- 能力包含：关键词搜索、数据评分排序、智能结果展示
- 触发条件：用户需要查询公众号热门内容、分析爆款规律、寻找选题灵感

## 前置准备

- 依赖说明：Python 3.13+（纯标准库，无第三方依赖）
- 输出文件：JSON数据文件、HTML可视化文件

### 鉴权

#### 获取 API Key

请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=clawhub) 获取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..."
```

## 操作步骤

### 步骤 1：关键词理解与处理

**关键词提取**：

- 用户输入关键词后，先进行理解，识别是否为赛道关键词
- 赛道关键词：较大的分类词，如"职场"、"情感"、"亲子"、"美妆"等
- 非赛道关键词：具体细分词，如"职场沟通技巧"、"异地恋怎么维持"等

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

1. **第一步：识别并询问用户（⚠️ 仅当用户明确要求时才执行）**
   ```
   我识别到「职场」是较大的分类，已查询近期热门趋势，推荐以下细分方向：
   工作、打工人、职场穿搭、职场干货、成长、冷门职业、向上管理、职场焦虑、升职、财务自由
   回复「拓展」将同时搜索这10个词，回复「不拓展」将继续搜索「职场」
   ```
2. **第二步：等待用户回复**
   - ❌ **禁止**：用户未回复时调用脚本
   - ❌ **禁止**：自动执行拓展搜索（必须等用户明确回复「拓展」）
   - ✅ **正确**：只等待用户明确回复后再执行
3. **第三步：根据用户明确回复执行**
   - 用户回复「拓展」 → 调用脚本搜索10个细分词
   - 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词
   - 用户未回复或回复其他内容 → 识别对应意图

### 步骤 2：时间范围与数据查询

**时间范围**：

- 数据库只包含昨天至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天的数据，已为您展示最接近的数据"

**执行命令**：

- 有赛道关键词：`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 输出
- ✅ 唯一允许多次调用的场景：数据不足时按 SKILL.md 规定的自动拓展时间（近1天→近7天→近30天），每次使用不同的 `--start-date`

**输出文件**：

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

---

### 步骤 3：数据展示策略（核心）

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

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

**数据字段说明**：

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

**展示规则**（基于articles数量判断）：

#### 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 |

**输出规则**：

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

---

### 步骤 4：展示逻辑）

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

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

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

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

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

---

### 步骤 5：订阅服务询问（必须执行）

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

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

**处理用户回复**：

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

**订阅实现步骤**：

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

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

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

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

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

   ```
   ✅ 订阅创建成功！

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

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

**⚠️ 强制规则**：

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

---

### 步骤 6：前置说明（必须展示）

**在展示数据前，必须告知用户**：

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

---

### 步骤 7：智能筛选热门内容（可选）

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

**筛选原则**：

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

---

## 使用示例

### 示例1：查询职场热门文章

**场景**：用户说"帮我查一下最近职场相关的爆款文章"

**执行流程**：

1. 识别"职场"为赛道关键词
2. 推荐细分方向，等待用户回复
3. 用户回复"不拓展" → 执行查询
4. 调用脚本：`python scripts/fetch_gzh_trends.py --keyword "职场" --start-date 2026-05-08`
5. 读取JSON数据，提取articles字段
6. 根据articles数量判断展示策略
7. 以Markdown表格形式展示给用户（默认前10条）
8. 如果articles > 10条，提示用户是否查看全部
9. 展示订阅服务询问

**预期产出**：

- JSON数据文件包含完整文章信息
- 对话中展示Markdown表格（默认前10条）
- 如用户选择查看全部，展示全部数据
- 展示订阅服务询问
- HTML卡片文件（可选）

**关键要点**：

- 赛道词需要先询问用户是否拓展
- 时间范围默认近7天
- 数据按总分排序展示
- 结果超过10条时询问是否查看全部
- 结果展示完成后必须询问订阅服务

### 示例2：查询具体细分词

**场景**：用户说"查一下职场沟通技巧的文章"

**执行流程**：

1. 识别"职场沟通技巧"为非赛道关键词
2. 直接查询，无需拓展询问
3. 调用脚本：`python scripts/fetch_gzh_trends.py --keyword "职场沟通技巧" --start-date 2026-05-08`
4. 根据返回数据判断展示策略

**预期产出**：

- 精准匹配的文章列表
- 可能触发"部分结果"策略（<10条）

**关键要点**：

- 非赛道词直接查询
- 结果少时展示推荐热门文章

### 示例3：多关键词查询

**场景**：用户说"帮我查职场、情感、亲子三个领域的爆款"

**执行流程**：

1. 识别多个关键词
2. 调用脚本：`python scripts/fetch_gzh_trends.py --keyword "职场,情感,亲子" --start-date 2026-05-08`
3. 合并三个关键词的查询结果
4. 按总分统一排序展示

**预期产出**：

- 跨分类的文章列表
- 包含各领域热门文章

**关键要点**：

- 多关键词用逗号分隔
- 结果合并去重
- 统一排序展示

---

## 资源索引

- 脚本：见 [scripts/fetch_gzh_trends.py](scripts/fetch_gzh_trends.py)
  - 用途：调用接口获取数据、排序处理、生成HTML
  - 参数：--keyword（必需）、--start-date（可选）、--max-items（可选）、--output-format（可选）
- 参考：见 [references/gzh_trend_data_format.md](references/gzh_trend_data_format.md)
  - 何时读取：需要了解接口数据格式、字段说明时

## 注意事项

- **数据源说明**：数据来源于公众号热门文章接口，包含阅读数、互动数、评分等，每日早上7点更新昨日数据
- **展示策略**：根据articles数量智能判断，确保用户体验
- **评分排序**：关键词搜索时按totalScore（相关性+热度+时效）降序排序，总分共15分；全站热门按阅读数排序
- **前置说明**：展示数据前必须告知用户数据说明和排序说明
- **HTML文件**：卡片样式，适合独立查看和分享