wechat-search

Official account popular article search

1. Introduction

Official account popular viral article search tool, supports searching WeChat official account viral articles by keyword, and intelligently ranks and recommends based on a three-dimensional score of relevance, popularity, and timeliness. Focused on serving official account content creators, new media operators, and self-media teams, helping users quickly discover popular topics, analyze viral patterns, and gain creative inspiration.

2. Features

🔍 Intelligent keyword search — Supports precise keyword search and multi-keyword combined queries (comma-separated), covering official account articles across all categories
📊 Three-dimensional score ranking — Intelligently ranks and recommends based on a weighted total score (out of 15) calculated from relevance (out of 10), popularity (out of 3), and timeliness (out of 2)
⏱️ Flexible time range — Defaults to querying the last 7 days, supports automatic time expansion (1 day→7 days→30 days), data updates daily at 7 AM
🧠 Track keyword recognition and expansion — Automatically recognizes generalized track keywords and recommends 10 sub-directions, helping users precisely target
🔥 Popular recommendations — Automatically displays recent popular recommended articles and hot topics when there are few results
📩 Scheduled subscription push — Supports creating calendar subscription tasks and automatically pushing the latest viral articles at the set time
📄 HTML report generation — Optionally generates an HTML visualization file for easy standalone viewing and sharing
📋 Intelligent number formatting — Reading counts of ten thousand or more are automatically converted (e.g., 10.0w)，and the total score field is bolded for emphasis

3. One-click installation

Authentication

Get API Key

Please go to RedFox Hub to get the API KEY

Configure API Key

Option 1: Using OpenClaw as an example, add REDFOX_API_KEY to ~/.openclaw/openclaw.json:

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

Option 2: Terminal configuration

export REDFOX_API_KEY="ak_xxxx..."

Dependency installation

This Skill uses Python 3.13+ pure standard library (urllib.request, json, os, sys, argparse, datetime), with no need to install any third-party dependencies.

Environment variable configuration

Environment variable	Description	Required	How to obtain
`REDFOX_API_KEY`	RedFox Data API Key	Yes	RedFox Hub

4. Usage guide

Basic usage (complete a query in 3 steps)

Step 1 — Extract keywords: Extract search keywords from the user's description and determine whether they are track keywords or sub-keywords.

Track keyword: A broader category term, such as "workplace" "relationships" "parenting" "beauty" etc.
Non-track keyword: A specific sub-keyword, such as "workplace communication skills" "how to maintain a long-distance relationship" etc.

Step 2 — Call the script：

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

With track keywords:python scripts/fetch_gzh_trends.py --keyword <关键词> --start-date <日期>
Without track keywords (query site-wide popular content):python scripts/fetch_gzh_trends.py --keyword "" --start-date <日期>
Separate multiple keywords with commas:python scripts/fetch_gzh_trends.py --keyword "职场沟通,恋爱技巧,亲子教育" --start-date <日期>

⚠️ Anti-duplicate call rule (mandatory)：

❌ ProhibitedFirst use head/tail/2>/dev/null | head -5 methods such as "trial run" or "preview" of script output
❌ ProhibitedCalling the script multiple times for the same parameter in the same query
✅ Execute the script command only once per query, directly read the complete stdout output
✅ The only scenario where multiple calls are allowed: when data is insufficient, automatically extend the time as specified (last 1 day → last 7 days → last 30 days), using a different --start-date

Step 3 — View results: The script returns structured JSON data; output the results according to the display strategy specified in this guide.

Advanced usage

Track keyword processing flow (execute only when identified as a track keyword)

Step 1: Identify and ask the user (⚠️ execute only when the user explicitly requests it)

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

Step 2: Wait for the user's reply

❌ Prohibited: Calling the script when the user has not replied
❌ Prohibited: Automatically executing the extended search (must wait for the user to explicitly reply "extend")
✅ Correct: Only wait for the user's explicit reply before executing

Step 3: Execute according to the user's explicit reply

User replies "extend" → call the script to search for 10 sub-keywords
User replies "do not extend" or "continue" → call the script to search for the original keyword
User does not reply or replies with other content → identify the corresponding intent

Time range and data query

Time range：

The database only contains data from yesterday to 30 days ago
Default definition of "recent": last 7 days (startDate = today - 7 days)
Date calculation(convert the user's expression into startDate):
- Today: directly use yesterday's date, startDate = yesterday
- Recent/last 7 days: startDate = today - 7 days
- Last N days: startDate = today - N days
- Example: user says "last 15 days" → startDate = today - 15 days

Automatic time extension when data is insufficient：

✅ When the number of articles is insufficient, automatically extend the time range in order: last 1 day → last 7 days → last 30 days
✅ After each extension, call the script again to query until data is obtained or the extension reaches 30 days
❌ Prohibited from automatically expanding keyword search: When search results are fewer than 10, it is prohibited to call the interface again to search using expanded terms/related terms/synonyms
❌ Prohibited from automatically trying related search suggestions
✅ If there is still no data after extending the time, directly return the result with articles=0

Apology explanation for out-of-range or not-yet-updated data：

When the user says "today": reply "We are very sorry, today's data has not been updated yet. We have shown you the most recently available data."
When the time requested by the user exceeds 30 days: reply "We are very sorry, currently only data from the last 30 days is supported. We have shown you the closest data."

Output files：

JSON data: output to standard output (stdout)
HTML file:{keyword}_趋势数据.html(optional)

Preliminary explanation (must be communicated to the user before displaying data)

Data description：The scope of viral articles is articles with 5,000+ reads; yesterday's data is updated every morning at 7:00. Article interaction data is截至 the time of ingestion, not real-time data; after ingestion, interaction data may continue to grow.
Sorting Description(When there is a keyword search): Weighted calculation based on three dimensions: relevance (out of 10 points), popularity (out of 3 points), and timeliness (out of 2 points), for a total score of 15 points
Sorting Description(Site-wide popular/no keyword): Sort by read count

Data Display Strategy (Core)

⚠️ Mandatory Output Rules：

✅ Must strictly follow the format specified in this step for output
❌ Do not add any analysis or interpretation before the output
❌ Do not arbitrarily provide suggestions or solutions
❌ Do not ask about the user's true purpose or needs
✅ Directly read the JSON data returned by the script and output it according to the corresponding strategy

Data Field Description：

articles：Normal article data (main display content)
latestHotArticles：Recommended popular articles (auxiliary content, displays 10 items by default, table does not include the score field)
hotTopics：Popular topics (returned by the interface, for reference only, not displayed in the conversation)

A. Number of articles ≥ 10

Display content:

Time Range Description：Must inform the user of the query time range, such as "📅 Query time range: May 8 - May 19"
Normal article data (sorted by totalScore in descending order)
Related search recommendations (relatedSearches)

Markdown table format：

Note：The total score field needs to be displayed in bold (using**分数**format)

Example: 📅 Query time range: May 8 - May 19

Article Title	Author	Read Count	Publish Time	Relevance	Popularity	Timeliness	Total Score
Must-read for workplace newcomers: 5 tips to help you quickly integrate into the team	Workplace Growth Community	10.0w	2026-05-15	9.8	3.0	2.0	14.8

🔤 Related Search Recommendations：Workplace communication, workplace promotion, workers

B. Number of articles < 10 but > 0

Display content:

Time Range Description：Must inform the user of the query time range, such as "📅 Query time range: May 8 - May 19"
Prompt message："💡Only X results were found for the current keyword in the current time period. You can try expanding the keywords or extending the time. We also recommend recent popular articles for you."
Normal article data
Recommended popular articles (latestHotArticles, with a "Recommended Popular Articles" title section, displays 10 items by default)
Recommended popular topics
Related search recommendations (relatedSearches)

Markdown format example：

📅 Query time range: May 8 - May 19

💡Only 3 results were found for the current keyword in the current time period,

Article Title	Author	Read count	Publish time	Relevance	Popularity	Timeliness	Total score
Article 1	Author 1	10.0w	2026-05-15	9.8	3.0	2.0	14.8

You can try expanding the keywords or the time range. We have also recommended recent popular articles for your reference.：

⚠️ The recommended popular articles table does not need a score field. The format is:

Article title	Author	Read count	Publish time
Popular article 1	Author A	8.5w	2026-05-14
Popular article 2	Author B	6.2w	2026-05-13

📈 Recommended popular topics：

You can try searching the following popular tracks: Humanities, Knowledge, Wellness, Fashion, Food, Lifestyle, Travel, Comedy, Relationships, Sports & Entertainment, Beauty, Digest, Livelihood News, Wealth & Finance, Tech & Digital, Venture & Business, Automotive, Real Estate, Workplace, Education & Exams, Academia

C. articles count = 0

⚠️ You must strictly follow the format below. Do not add suggestions or analysis on your own.

Display content:

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

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

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

After the above content, display the latestHotArticles data (if any). The popular recommendations table does not need a score field:

Article title	Author	Read count	Publish time
Popular article 1	Author A	8.5w	2026-05-14
Popular article 2	Author B	6.2w	2026-05-13

Output rules：

✅ You must directly output the above format content
❌ Do not add extra analysis or suggestions
❌ Do not explain why no data could be found
❌ Do not proactively provide other search options
❌ Do not ask the user for their true purpose

Display logic (pagination)

When the articles count > 10：

Initially display only the first 10 items by default

You must prompt the user:

💡 当前共找到 X 条相关文章，已展示前10条。是否需要查看全部？

Wait for the user to reply:
- User replies "yes"/"view all"/"all" → display all data
- User replies "no"/"not needed"/"don't need" → do not display more

Format when displaying all data：

📊 全部结果（共X条）：

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

Intelligent filtering of popular content (optional)

⚠️ This step is optional and is performed only when the user explicitly requests "filtering" or "recommendation"

Filtering principles：

Unified sorting: The script has automatically sorted all data by totalScore
Target quantity: At most 10 items, display the actual data volume truthfully

Subscription service inquiry (must be performed)

When the articles count > 0, you must ask after the result output is completed：

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

Handle user reply：

User selects 1️⃣ → use calendar_create tool to create a schedule and subscribe to the current search criteria
User selects 2️⃣ → end the current conversation

Subscription implementation steps：

Inform the data update time and ask for the push time：

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

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

After the user selects, call calendar_create tool：
- title：公众号趋势订阅：{关键词}
- description: Record the current search parameters (keywords, time range)
- start_time: Set according to the time selected by the user
- remind_type: Set as a recurring reminder
- Other parameters use the current query parameters

Prompt after successful subscription：

✅ 订阅创建成功！

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

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

⚠️ Mandatory rules：

✅ Must ask immediately after the result output is completed
✅ When the user chooses to subscribe, must use calendar_create tool
✅ Parameters must use the current query parameters (keywords, time range, etc.)
❌ Skipping this step is prohibited
❌ Asking before displaying the results is prohibited

Common Commands Quick Reference

Scenario	Command
Keyword search (default: last 7 days)	`python scripts/fetch_gzh_trends.py --keyword "关键词" --start-date <日期>`
Site-wide trending	`python scripts/fetch_gzh_trends.py --keyword "" --start-date <日期>`
Multi-keyword search	`python scripts/fetch_gzh_trends.py --keyword "词1,词2,词3" --start-date <日期>`
Specify time range	`python scripts/fetch_gzh_trends.py --keyword "关键词" --start-date 2026-05-08`
Generate HTML report	Script automatically generates `{keyword}_趋势数据.html`
Subscription creation	After replying 1️⃣, use `calendar_create` tool to create a scheduled task

5. Use cases

Scenario 1: Official account creators looking for topic inspiration

Role: Official account content creator
: Wants to learn which viral articles have appeared recently in the "workplace" field, to find inspiration for the next topic: Want to learn about which hit articles there are in the recent "workplace" field, and find inspiration for the next topic
How to use: After entering the track word "workplace", the system recommends 10 sub-directions (such as "workplace outfit""managing up", etc.); reply "expand" for batch search
Expected benefits: Quickly lock onto high-value topic directions through three-dimensional score ranking, and understand the content characteristics of viral articles in the same track

Scenario 2: New media operations competitor analysis

Role: New media operations manager
Need: Needs to analyze which viral articles a competitor official account has recently published, and understand its content strategy
How to use: Search the competitor official account name or related field keywords, and view the article list sorted by totalScore
Expected benefits: Systematically understand the competitor's content topics, title patterns, and publishing rhythm, providing data support for one's own operational strategy

Scenario 3: Self-media matrix content planning

Role: MCN agency content director
Need: Needs to view recent viral articles in multiple fields (workplace, relationships, parenting) at once, and plan the matrix content schedule
How to use: Use comma-separated multiple keywords --keyword "职场,情感,亲子" for cross-domain queries
Expected benefits: One command covers multiple fields, efficiently obtaining cross-category trending topics and improving content planning efficiency

Scenario 4: Daily scheduled viral article push

Role: Self-media blogger
Need: Hopes to automatically receive a list of viral articles from official accounts in a specific field every morning
How to use: After searching keywords, choose "1️⃣ Subscribe", set the push time, and create a calendar scheduled task
Expected benefits: No need to manually repeat searches; automatically obtain the latest hit articles at scheduled times every day, and continuously track trends in the track

6. Project Architecture

Directory Structure

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

Tech Stack

Component	Technology	Description
Runtime Environment	Python 3.13+	Pure standard library, no third-party dependencies
Standard Library	urllib.request, json, os, sys, argparse, datetime	Used for HTTP requests, JSON processing, parameter parsing, and date calculation
Data Interface	Redfox API (Redfox)	Authenticated via REDFOX_API_KEY
Output Format	JSON (stdout) + HTML (file)	JSON is output via stdout for AI parsing; HTML is an optional visualization file
Display Format	Markdown table	The AI agent renders JSON as a table for display

Core Module Description

Module	Path	Function
Search Script	`scripts/fetch_gzh_trends.py`	Calls the Redfox interface to obtain hit articles from official accounts, supporting the --keyword, --start-date, --max-items, and --output-format parameters
Data Format Reference	`references/gzh_trend_data_format.md`	Detailed explanation of the format and meaning of the data fields returned by the interface
SKILL Definition	`SKILL.md`	Defines Skill metadata, workflow, display strategy, and subscription logic

Resource Index

Core Script：scripts/fetch_gzh_trends.py — Calls the Redfox API to obtain hit article data from official accounts; parameters: --keyword (required), --start-date (optional), --max-items (optional), --output-format (optional)
Reference Documentation：references/gzh_trend_data_format.md — When to read: when you need to understand the interface data format and field descriptions

7. Frequently Asked Questions

Installation

Q: Which dependencies need to be installed? A: This tool uses the Python 3.13+ pure standard library (urllib.request, json, os, sys, argparse, datetime), and no third-party dependencies need to be installed. Ensure that Python 3.13 or a higher version is installed on the system.

Q: How do I obtain an API Key? A: Please visit Redfox hub to register and obtain an API Key, and configure the environment variables according to the "One-click Installation" section in this document.

Usage

Q: What is the difference between track words and non-track words? A: Track words are broader category words (such as "workplace" and "emotions"); once identified, they trigger an expansion strategy. Non-track words are specific subdivided words (such as "workplace communication skills"), and can be searched directly without an expansion prompt.

Q: What is the time range of the data? A: The database only contains data from yesterday to 30 days ago, and the default query is for the most recent 7 days. When data is insufficient, the time range is automatically expanded (1 day → 7 days → 30 days). Yesterday's data is updated every day at 7 a.m.

Q: Why do some fields in the table have scores and some not? A: When there is a keyword search, results are sorted by totalScore (relevance + popularity + timeliness), and the score field is displayed; site-wide popular articles are sorted by read count and do not have a score field. The recommended popular articles table also does not include scores.

Q: How can I view the complete results, more than 10 items? A: When the results exceed 10 items, the system will prompt "View all?". Reply "Yes", "View all", or "All" to display the complete data.

Troubleshooting

Q: The script returns empty results? A: The inclusion criteria for viral articles is 5000+ reads. If the keyword is too niche or the time range is too short, there may be no data. The system will automatically expand the time range; if it still has no data after expanding to 30 days, it returns empty. You can try shorter/broader keywords.

Q: Prompted "Today's data has not been updated yet"? A: The database updates yesterday's data every morning at 7 AM; the current day's data has not yet been ingested. The system will automatically display the most recently available data.

Q: What should I do if the script reports an error? A: Common causes: (1) REDFOX_API_KEY is not configured or has expired; (2) Python version < 3.13; (3) network issues. Please check each one by one.

Security License

Q: How should the API Key be stored securely? A: It is recommended to use Option 1 (configure it in the env field of openclaw.json) to avoid leaking it in terminal history. Do not hardcode the API Key in scripts or upload it to public repositories.

Q: Data source and copyright? A: The data comes from public articles from official accounts indexed by the Red Fox API. The copyright of the articles belongs to the original authors. This tool is for learning and content creation reference only.

About this skill

1. Introduction

2. Features

3. One-click installation

Authentication

Get API Key

Configure API Key

Dependency installation

Environment variable configuration

4. Usage guide

Basic usage (complete a query in 3 steps)

Advanced usage

Track keyword processing flow (execute only when identified as a track keyword)

Time range and data query

Preliminary explanation (must be communicated to the user before displaying data)

Data Display Strategy (Core)

A. Number of articles ≥ 10

B. Number of articles < 10 but > 0

C. articles count = 0

Display logic (pagination)

Intelligent filtering of popular content (optional)

Subscription service inquiry (must be performed)

Common Commands Quick Reference

5. Use cases

Scenario 1: Official account creators looking for topic inspiration

Scenario 2: New media operations competitor analysis

Scenario 3: Self-media matrix content planning

Scenario 4: Daily scheduled viral article push

6. Project Architecture

Directory Structure

Tech Stack

Core Module Description

Resource Index

7. Frequently Asked Questions

Installation

Usage

Troubleshooting

Security License