TrendRadar/README-EN.md

59 KiB

TrendRadar Banner

🚀 Deploy in 30 seconds — Your Smart Trending News Assistant

sansan0%2FTrendRadar | Trendshift

302.AI logo

GitHub Stars GitHub Forks License Version MCP

WeWork Telegram DingTalk Feishu Email ntfy

GitHub Actions GitHub Pages Docker MCP Support

中文 | English

This project is designed to be lightweight and easy to deploy

📑 Quick Navigation

  • Thanks to bug reporters, your feedback makes this project better 😉
  • Thanks to stargazers, your stars and forks are the best support for open source 😍
  • Thanks to followers, your interactions make the content more meaningful 😎
👉 Click to view Acknowledgments (Current 🔥71🔥 supporters)

Data Support

This project uses the API from newsnow to fetch multi-platform data

Promotion Support

Thanks to the following platforms and individuals for recommendations (in chronological order)

Community Support

Thanks to financial supporters. Your generosity has transformed into snacks and drinks beside my keyboard, accompanying every iteration of this project

Supporter Amount (CNY) Date Note
*鬼 1 2025.11.17
*超 10 2025.11.17
R*w 10 2025.11.17 Great agent work!
J*o 1 2025.11.17 Thanks for open source
*晨 8.88 2025.11.16 Nice project
*海 1 2025.11.15
*德 1.99 2025.11.15
*疏 8.8 2025.11.14 Great project
M*e 10 2025.11.14 Open source is not easy
**柯 1 2025.11.14
*云 88 2025.11.13 Good project
*W 6 2025.11.13
*凯 1 2025.11.13
对*. 1 2025.11.13 Thanks for TrendRadar
s*y 1 2025.11.13
**翔 10 2025.11.13 Wish I found it earlier
*韦 9.9 2025.11.13 TrendRadar is awesome
h*p 5 2025.11.12 Support Chinese open source
c*r 6 2025.11.12
a*n 5 2025.11.12
。*c 1 2025.11.12 Thanks for sharing
... ... ... (More 50+ supporters)

This project uses the API from newsnow to fetch multi-platform data

Core Features

  • Zhihu (知乎)
  • Douyin (抖音)
  • Bilibili Hot Search
  • Wallstreetcn (华尔街见闻)
  • Tieba (贴吧)
  • Baidu Hot Search
  • Yicai (财联社)
  • Thepaper (澎湃新闻)
  • Ifeng (凤凰网)
  • Toutiao (今日头条)
  • Weibo (微博)

Default monitoring of 11 mainstream platforms, with support for adding custom platforms.

👉 Click to expand: Custom Monitoring Platforms

The news data comes from newsnow. You can visit the website and click [More] to see if your desired platform is available.

To add platforms, visit the source code, and modify the platforms configuration in config/config.yaml:

platforms:
  - id: "toutiao"
    name: "Toutiao"
  - id: "baidu"
    name: "Baidu Hot"
  - id: "wallstreetcn-hot"
    name: "Wallstreetcn"
  # Add more platforms...

If you're unsure, you can copy from community-shared configurations.

Smart Push Strategies

Three Push Modes:

Mode Target Users Push Timing Display Content Use Case
Daily Summary
daily
📋 Managers/Regular Users Scheduled push (default: hourly) All matched news of the day
+ New news section
Daily reports
Comprehensive trend overview
Current Rankings
current
📰 Content Creators Scheduled push (default: hourly) Current ranking matches
+ New news section
Real-time hot topics
What's trending now
Incremental Monitor
incremental
📈 Traders/Investors Push only when new Newly appeared matching news Avoid duplicate info
High-frequency monitoring

Additional Feature - Push Time Window Control (Optional):

This feature works independently with any push mode:

  • Time Window Limit: Set push time range (e.g., 09:00-18:00 or 20:00-22:00)
  • Push Frequency Control:
    • Multiple pushes within window: Push every execution
    • Once per day: Only push once within window (suitable for daily/current modes)
  • Typical Scenarios:
    • Work hours push: Only receive messages during 09:00-18:00 on weekdays
    • Evening summary: Receive summary at fixed evening time (e.g., 20:00-22:00)
    • Do not disturb: Prevent notifications during non-work hours

Tip: This feature is disabled by default, enable it manually in config/config.yaml with push_window.enabled

Precise Content Filtering

Set personal keywords (e.g., AI, BYD, Education Policy) to receive only relevant trending news, filtering out noise.

  • Supports normal words, required words (+), and filter words (!)
  • Group-based management with independent statistics for different topics

You can also skip filtering and receive all trending news. See v2.0.1 in Changelog

👉 Click to expand: frequency_words.txt Configuration

Configure monitoring keywords in frequency_words.txt with three syntax types and grouping features.

Keywords at the top have higher priority. Adjust keyword order based on your interests.

Syntax Type Symbol Purpose Example Matching Logic
Normal None Basic matching Huawei Match any one
Required + Scope limiting +phone Must include both
Filter ! Noise exclusion !ad Exclude if included

📋 Basic Syntax

1. Normal Keywords - Basic Matching

Huawei
OPPO
Apple

Effect: News containing any one of these words will be captured

2. Required Words +word - Scope Limiting

Huawei
OPPO
+phone

Effect: Must include both normal word and required word to be captured

3. Filter Words !word - Noise Exclusion

Apple
Huawei
!fruit
!price

Effect: News containing filter words will be excluded, even if it contains keywords

🔗 Group Feature - Importance of Empty Lines

Core Rule: Use empty lines to separate different groups, each group is independently counted

Example Configuration:

iPhone
Huawei
OPPO
+launch

A-shares
Shanghai Index
Shenzhen Index
+fluctuation
!prediction

World Cup
Euro Cup
Asian Cup
+match

Group Explanation and Matching Effects:

Group 1 - Phone Launches:

  • Keywords: iPhone, Huawei, OPPO
  • Required: launch
  • Effect: Must include phone brand name and "launch"

Matching Examples:

  • "iPhone 15 officially launched with pricing" ← Has "iPhone" + "launch"
  • "Huawei Mate60 series launch livestream" ← Has "Huawei" + "launch"
  • "OPPO Find X7 launch date confirmed" ← Has "OPPO" + "launch"
  • "iPhone sales hit record high" ← Has "iPhone" but missing "launch"

Group 2 - Stock Market:

  • Keywords: A-shares, Shanghai Index, Shenzhen Index
  • Required: fluctuation
  • Filter: prediction
  • Effect: Include stock-related words and "fluctuation", but exclude "prediction"

Matching Examples:

  • "A-shares major fluctuation analysis today" ← Has "A-shares" + "fluctuation"
  • "Shanghai Index fluctuation reasons explained" ← Has "Shanghai Index" + "fluctuation"
  • "Experts predict A-shares fluctuation trends" ← Has "A-shares" + "fluctuation" but contains "prediction"
  • "A-shares trading volume hits new high" ← Has "A-shares" but missing "fluctuation"

Group 3 - Football Events:

  • Keywords: World Cup, Euro Cup, Asian Cup
  • Required: match
  • Effect: Must include cup name and "match"

Matching Examples:

  • "World Cup group stage match results" ← Has "World Cup" + "match"
  • "Euro Cup final match time" ← Has "Euro Cup" + "match"
  • "World Cup tickets on sale" ← Has "World Cup" but missing "match"

🎯 Configuration Tips

1. From Broad to Strict Strategy

# Step 1: Start with broad keywords for testing
Artificial Intelligence
AI
ChatGPT

# Step 2: After finding mismatches, add required words
Artificial Intelligence
AI
ChatGPT
+technology

# Step 3: After finding noise, add filter words
Artificial Intelligence
AI
ChatGPT
+technology
!advertisement
!training

2. Avoid Over-Complexity

Not Recommended: Too many words in one group

Huawei
OPPO
Apple
Samsung
vivo
OnePlus
Meizu
+phone
+launch
+sales
!fake
!repair
!second-hand

Recommended: Split into precise groups

Huawei
OPPO
+new product

Apple
Samsung
+launch

phone
sales
+market

Real-time tracking of news popularity changes helps you understand not just "what's trending" but "how trends evolve."

  • Timeline Tracking: Records complete time span from first to last appearance
  • Popularity Changes: Tracks ranking changes and appearance frequency across time periods
  • New Detection: Real-time identification of emerging topics, marked with 🆕
  • Continuity Analysis: Distinguishes between one-time hot topics and continuously developing news
  • Cross-Platform Comparison: Same news across different platforms, showing media attention differences

Never miss the complete development of important news, from topic emergence to peak discussion

👉 Click to expand: Push Format Explanation

📊 Trending Keywords Stats

🔥 [1/3] AI ChatGPT : 2 items

  1. [Baidu Hot] 🆕 ChatGPT-5 officially launched [1] - 09:15 (1 time)

  2. [Toutiao] AI chip concept stocks surge [3] - [08:30 ~ 10:45] (3 times)

━━━━━━━━━━━━━━━━━━━

📈 [2/3] BYD Tesla : 2 items

  1. [Weibo] 🆕 BYD monthly sales break record [2] - 10:20 (1 time)

  2. [Douyin] Tesla price reduction promotion [4] - [07:45 ~ 09:15] (2 times)

━━━━━━━━━━━━━━━━━━━

📌 [3/3] A-shares Stock Market : 1 item

  1. [Wallstreetcn] A-shares midday review [5] - [11:30 ~ 12:00] (2 times)

🆕 New Trending News (Total 2 items)

Baidu Hot (1 item):

  1. ChatGPT-5 officially launched [1]

Weibo (1 item):

  1. BYD monthly sales break record [2]

Updated: 2025-01-15 12:30:15

Message Format Explanation

Format Element Example Meaning Description
🔥📈📌 🔥 [1/3] AI ChatGPT Popularity Level 🔥 High (≥10) 📈 Medium (5-9) 📌 Normal (<5)
[Number/Total] [1/3] Rank Position Current group rank among all matches
Keyword Group AI ChatGPT Keyword Group Group from config, title must contain words
: N items : 2 items Match Count Total news matching this group
[Platform] [Baidu Hot] Source Platform Platform name of the news
🆕 🆕 ChatGPT-5 officially launched New Mark First appearance in this round
[number] [1] High Rank Rank ≤ threshold, bold red display
[number] [7] Normal Rank Rank > threshold, normal display
- time - 09:15 First Time Time when news was first discovered
[time~time] [08:30 ~ 10:45] Duration Time range from first to last appearance
(N times) (3 times) Frequency Total appearances during monitoring
New Section 🆕 New Trending News New Topic Summary Separately shows newly appeared topics

No longer controlled by platform algorithms, TrendRadar reorganizes all trending searches:

  • Prioritize High-Ranking News (60%): Top-ranked news from each platform appears first
  • Focus on Persistent Topics (30%): Repeatedly appearing news is more important
  • Consider Ranking Quality (10%): Not just frequent, but consistently top-ranked

Merge trending searches from各 platforms and re-sort by your interests. These three ratios can be adjusted for your scenarios.

👉 Click to expand: Trending Weight Adjustment

Current default configuration is balanced.

Two Core Scenarios

Real-Time Trending Type:

weight:
  rank_weight: 0.8    # Mainly focus on ranking
  frequency_weight: 0.1  # Less concern about continuity
  hotness_weight: 0.1

Target Users: Content creators, marketers, users wanting to quickly understand current hot topics

In-Depth Topic Type:

weight:
  rank_weight: 0.4    # Moderate ranking focus
  frequency_weight: 0.5  # Emphasize sustained heat within the day
  hotness_weight: 0.1

Target Users: Investors, researchers, journalists, users needing deep trend analysis

Adjustment Method

  1. Three numbers must sum to 1.0
  2. Increase what's important: Increase rank_weight for rankings, frequency_weight for continuity
  3. Suggest adjusting 0.1-0.2 at a time, observe effects

Core idea: Users pursuing speed and timeliness increase ranking weight, users pursuing depth and stability increase frequency weight.

Multi-Channel Real-Time Push

Supports WeWork (+ WeChat push solution), Feishu, DingTalk, Telegram, Email, ntfy — messages delivered directly to phone and email.

Multi-Platform Support

  • GitHub Pages: Auto-generate beautiful web reports, PC/mobile adapted
  • Docker Deployment: Supports multi-architecture containerized operation
  • Data Persistence: HTML/TXT multi-format history saving

AI Smart Analysis (v3.0.0 New)

AI conversational analysis system based on MCP (Model Context Protocol), enabling deep data mining with natural language.

  • Conversational Query: Ask in natural language, like "Query yesterday's Zhihu trending" or "Analyze recent Bitcoin popularity trends"
  • 13 Analysis Tools: Basic query, smart search, trend analysis, data insights, sentiment analysis, etc.
  • Multi-Client Support: Cherry Studio (GUI config), Claude Desktop, Cursor, Cline, etc.
  • Deep Analysis Capabilities:
    • Topic trend tracking (popularity changes, lifecycle, viral detection, trend prediction)
    • Cross-platform data comparison (activity stats, keyword co-occurrence)
    • Smart summary generation, similar news finding, historical correlation search

No more manual data file browsing—AI assistant helps you understand the stories behind the news in seconds

Zero Technical Barrier Deployment

One-click GitHub Fork to use, no programming required.

30-second deployment: GitHub Pages (web browsing) supports one-click save as image for easy sharing

1-minute deployment: WeWork (mobile notification)

💡 Tip: Want a real-time updated web version? After forking, go to your repo Settings → Pages and enable GitHub Pages. Preview Effect.

Reduce APP Dependencies

Transform from "algorithm recommendation captivity" to "actively getting the information you want"

Target Users: Investors, content creators, PR professionals, news-conscious general users

Typical Scenarios: Stock investment monitoring, brand sentiment tracking, industry trend watching, lifestyle news gathering

Github Pages Effect (Mobile Adapted, Email Push) Feishu Push Effect
Github Pages Effect Feishu Push Effect

📝 Changelog

Upgrade Instructions:

  • Tip: Do NOT update this project via Sync fork. Check Changelog to understand specific [Upgrade Methods] and [Features]
  • Minor Version Update: Upgrading from v2.x to v2.y, replace main.py in your forked repo with the latest version
  • Major Version Upgrade: Upgrading from v1.x to v2.y, recommend deleting existing fork and re-forking to save effort and avoid config conflicts

2025/11/12 - v3.0.5

  • Fixed email sending SSL/TLS port configuration logic error
  • Optimized email service providers (QQ/163/126) to default use port 465 (SSL)
  • Added Docker environment variable support: Core config items (enable_crawler, report_mode, push_window, etc.) support override via environment variables, solving config file modification issues for NAS users (see 🐳 Docker Deployment chapter)

2025/11/18 - mcp-v1.0.2

MCP Module Update:

  • Fix issue where today's news query may return articles from past dates
👉 Click to expand: Historical Updates

2025/10/26 - mcp-v1.0.1

MCP Module Update:

  • Fixed date query parameter passing error
  • Unified time parameter format for all tools

2025/10/31 - v3.0.4

  • Solved Feishu error due to overly long push content, implemented batch pushing

2025/10/23 - v3.0.3

  • Expanded ntfy error message display range

2025/10/21 - v3.0.2

  • Fixed ntfy push encoding issue

2025/10/20 - v3.0.0

Major Update - AI Analysis Feature Launched 🤖

  • Core Features:

    • New MCP (Model Context Protocol) based AI analysis server
    • 13 smart analysis tools: basic query, smart search, advanced analysis, system management
    • Natural language interaction: Query and analyze news data through conversation
    • Multi-client support: Claude Desktop, Cherry Studio, Cursor, Cline, etc.
  • Analysis Capabilities:

    • Topic trend analysis (popularity tracking, lifecycle, viral detection, trend prediction)
    • Data insights (platform comparison, activity stats, keyword co-occurrence)
    • Sentiment analysis, similar news finding, smart summary generation
    • Historical related news search, multi-mode search
  • Update Note:

    • This is an independent AI analysis feature, does not affect existing push functionality
    • Optional use, no need to upgrade existing deployment

2025/10/15 - v2.4.4

  • Updates:

    • Fixed ntfy push encoding issue + 1
    • Fixed push time window judgment issue
  • Upgrade Note:

    • Recommended minor version upgrade

2025/10/10 - v2.4.3

Thanks to nidaye996 for discovering the UX issue

  • Updates:

    • Refactored "Silent Push Mode" naming to "Push Time Window Control", improving feature comprehension
    • Clarified push time window as optional additional feature, can work with three push modes
    • Improved comments and documentation, making feature positioning clearer
  • Upgrade Note:

    • This is just refactoring, upgrade optional

2025/10/8 - v2.4.2

  • Updates:

    • Fixed ntfy push encoding issue
    • Fixed missing config file issue
    • Optimized ntfy push effect
    • Added GitHub Pages image segmented export feature
  • Upgrade Note:

    • Recommend major version update

2025/10/2 - v2.4.0

Added ntfy Push Notification

  • Core Features:

    • Supports ntfy.sh public service and self-hosted servers
  • Use Cases:

    • Suitable for privacy-conscious users (supports self-hosting)
    • Cross-platform push (iOS, Android, Desktop, Web)
    • No account registration needed (public servers)
    • Open-source and free (MIT License)
  • Upgrade Note:

    • Recommend major version update

2025/09/26 - v2.3.2

  • Fixed email notification config check being missed (#88)

Fix Description:

  • Solved the issue where system still prompted "No webhook configured" even with correct email notification setup

2025/09/22 - v2.3.1

  • Added email push feature, supports sending trending news reports to email
  • Smart SMTP Recognition: Auto-detects Gmail, QQ Mail, Outlook, NetEase Mail and 10+ email service providers
  • Beautiful HTML Format: Email content uses same HTML format as web version, well-formatted, mobile-adapted
  • Batch Sending Support: Supports multiple recipients, separated by commas
  • Custom SMTP: Can customize SMTP server and port
  • Fixed Docker build network connection issue

Usage Notes:

  • Use cases: Suitable for users needing email archiving, team sharing, scheduled reports
  • Supported emails: Gmail, QQ Mail, Outlook/Hotmail, 163/126 Mail, Sina Mail, Sohu Mail, etc.

Upgrade Note:

  • This update has many changes, if upgrading, recommend major version upgrade

2025/09/17 - v2.2.0

  • Added one-click save news as image feature, easily share trending topics you care about

Usage Notes:

  • Use case: After enabling web version feature (GitHub Pages)
  • How to use: Open webpage on phone or PC, click "Save as Image" button at top
  • Actual effect: System auto-creates beautiful image of current news report, saves to phone album or desktop
  • Sharing convenience: Directly send this image to friends, Moments, or work groups, letting others see your discovered important info

2025/09/13 - v2.1.2

  • Solved DingTalk push capacity limit causing news push failure (using batch push)

2025/09/04 - v2.1.1

  • Fixed Docker unable to run properly on certain architectures
  • Officially released official Docker image wantcat/trendradar, supports multi-architecture
  • Optimized Docker deployment process, can use quickly without local build

2025/08/30 - v2.1.0

Core Improvements:

  • Push Logic Optimization: Changed from "push every execution" to "controllable push within time window"
  • Time Window Control: Can set push time range, avoid non-work hour disturbance
  • Push Frequency Options: Supports single push or multiple pushes within time window

Upgrade Note:

  • This feature is disabled by default, need to manually enable push time window control in config.yaml
  • Upgrade requires updating both main.py and config.yaml files

2025/08/27 - v2.0.4

  • This version is not a bug fix, but an important reminder
  • Please keep webhooks properly, do not make public, do not make public, do not make public
  • If you deployed this project on GitHub via fork, please put webhooks in GitHub Secret, not config.yaml
  • If you already exposed webhooks or put them in config.yaml, suggest deleting and regenerating

2025/08/06 - v2.0.3

  • Optimized GitHub Pages web version effect, convenient for mobile use

2025/07/28 - v2.0.2

  • Refactored code
  • Solved version number easily being missed for modification

2025/07/27 - v2.0.1

Fixed Issues:

  1. Docker shell script line ending as CRLF causing execution exception issue
  2. frequency_words.txt being empty causing news sending also empty logic issue
  • After fix, when you choose frequency_words.txt empty, will push all news, but limited by message push size, please adjust as follows
    • Option 1: Turn off mobile push, only choose GitHub Pages deployment (this is the way to get most complete info, will re-sort all platform trending by your custom trending algorithm)
    • Option 2: Reduce push platforms, prioritize WeWork or Telegram, these two pushes I made batch push feature (because batch push affects push experience, and only these two platforms give very little push capacity, so had to make batch push feature, but at least can ensure complete info)
    • Option 3: Can combine with Option 2, mode choose current or incremental can effectively reduce one-time push content

2025/07/17 - v2.0.0

Major Refactoring:

  • Config management refactoring: All configs now managed through config/config.yaml file (main.py I still didn't split, convenient for you to copy and upgrade)
  • Run mode upgrade: Supports three modes - daily (daily summary), current (current rankings), incremental (incremental monitoring)
  • Docker support: Complete Docker deployment solution, supports containerized operation

Config File Description:

  • config/config.yaml - Main config file (application settings, crawler config, notification config, platform config, etc.)
  • config/frequency_words.txt - Keyword config (monitoring vocabulary settings)

2025/07/09 - v1.4.1

New Feature: Added incremental push (configure FOCUS_NEW_ONLY at top of main.py), this switch only cares about new topics not sustained heat, only sends notification when new content appears.

Fixed Issue: Under certain circumstances, some news containing special symbols caused occasional formatting exceptions.

2025/06/23 - v1.3.0

WeWork and Telegram push messages have length limits, I adopted splitting messages for pushing. Development docs see WeWork and Telegram

2025/06/21 - v1.2.1

Before this version, not only main.py needs copy replacement, crawler.yml also needs you to copy replacement https://github.com/sansan0/TrendRadar/blob/master/.github/workflows/crawler.yml

2025/06/19 - v1.2.0

Thanks to Claude Research for organizing various platform APIs, helping me quickly complete platform adaptation (although code is more redundant~

  1. Supports Telegram, WeWork, DingTalk push channels, supports multi-channel config and simultaneous push

2025/06/18 - v1.1.0

200 stars reached, continue celebrating with everyone~

  1. Important update, added weight, news you see now is hottest most concerned appearing at top
  2. Updated documentation usage, because recently updated many features, and previous usage docs I was lazy wrote simple (see ⚙️ frequency_words.txt complete configuration tutorial below)

2025/06/16 - v1.0.0

  1. Added project new version update reminder, default on, if want to turn off, can change "FEISHU_SHOW_VERSION_UPDATE": True to False in main.py

2025/06/13+14

  1. Removed compatibility code, students who forked before, directly copying code will show exception on same day (will recover normal next day)
  2. Feishu and html bottom added new news display

2025/06/09

100 stars reached, writing small feature to celebrate

frequency_words.txt file added required word feature, using + sign

  1. Required word syntax as follows: Tang Monk or Pig must both appear in title, will be included in push news
+Tang Monk
+Pig
  1. Filter word priority higher: If title filter word matches Tang Monk reciting sutras, then even if required word has Tang Monk, also not display
+Tang Monk
!Tang Monk reciting sutras

2025/06/02

  1. Webpage and Feishu messages support phone directly jumping to detailed news
  2. Optimized display effect + 1

2025/05/26

  1. Feishu message display effect optimized

🚀 Quick Start

After configuration, news data updates after one hour. To accelerate, refer to [Step 4] to manually test configuration

  1. Fork this project to your GitHub account

    • Click the "Fork" button at the top right of this page
  2. Setup GitHub Secrets (Choose your needed platforms):

    In your forked repo, go to Settings > Secrets and variables > Actions > New repository secret, then configure one or more notification platforms as needed:

    You can configure multiple platforms simultaneously, system will send notifications to all configured platforms.

    Effect similar to the image below, one name corresponds to one secret. After saving, you won't see the secret value when re-editing, which is normal.

    GitHub Secrets
    👉 Click to expand: WeWork Bot (Simplest and fastest configuration)

    GitHub Secret Configuration:

    • Name: WEWORK_WEBHOOK_URL
    • Value: Your WeWork bot Webhook address

    Bot Setup Steps:

    Mobile Setup:

    1. Open WeWork App → Enter target internal group chat
    2. Click "…" button at top right → Select "Message Push"
    3. Click "Add" → Name input "TrendRadar"
    4. Copy Webhook address, click save, paste the copied content into GitHub Secret above

    PC Setup Process Similar

    👉 Click to expand: Feishu Bot (Most user-friendly message display)

    GitHub Secret Configuration:

    Two methods available, Method 1 is simpler, Method 2 is more complex (but stable push)

    Method 1 discovered and suggested by ziventian, thanks to them. Default is personal push, group push can be configured via #97

    Method 1:

    For some users, additional operations needed to avoid "System Error". Need to search for the bot on mobile and enable Feishu bot application (suggestion from community, can refer)

    1. Open in PC browser https://botbuilder.feishu.cn/home/my-command

    2. Click "New Bot Command"

    3. Click "Select Trigger", scroll down, click "Webhook Trigger"

    4. Now you'll see "Webhook Address", copy this link to local notepad temporarily, continue with next steps

    5. In "Parameters" put the following content, then click "Done"

    {
      "message_type": "text",
      "content": {
        "total_titles": "{{Content}}",
        "timestamp": "{{Content}}",
        "report_type": "{{Content}}",
        "text": "{{Content}}"
      }
    }
    
    1. Click "Select Action" > "Send via Official Bot"

    2. Message title fill "TrendRadar Trending Monitor"

    3. Most critical part, click + button, select "Webhook Trigger", then arrange as shown in image

    Feishu Bot Config Example

    1. After configuration, put Webhook address from step 4 into GitHub Secrets FEISHU_WEBHOOK_URL

    Method 2: (See Chinese version for detailed steps)

    👉 Click to expand: DingTalk Bot

    GitHub Secret Configuration:

    • Name: DINGTALK_WEBHOOK_URL
    • Value: Your DingTalk bot Webhook address

    Bot Setup Steps:

    1. Create Bot (PC Only):

      • Open DingTalk PC client, enter target group chat
      • Click group settings icon (⚙️) → Scroll down to find "Bot" and click
      • Select "Add Bot" → "Custom"
    2. Configure Bot:

      • Set bot name
      • Security Settings:
        • Custom Keywords: Set "Trending" or "热点"
    3. Complete Setup:

      • Check service terms agreement → Click "Done"
      • Copy the obtained Webhook URL
      • Put URL into GitHub Secrets DINGTALK_WEBHOOK_URL

    Note: Mobile can only receive messages, cannot create new bots.

    👉 Click to expand: Telegram Bot

    GitHub Secret Configuration:

    • Name: TELEGRAM_BOT_TOKEN - Your Telegram Bot Token
    • Name: TELEGRAM_CHAT_ID - Your Telegram Chat ID

    Bot Setup Steps:

    1. Create Bot:

      • Search @BotFather in Telegram (note case, has blue verification checkmark, shows ~37849827 monthly users, this is official, beware of fake accounts)
      • Send /newbot command to create new bot
      • Set bot name (must end with "bot", easily runs into duplicate names, so think creatively)
      • Get Bot Token (format like: 123456789:AAHfiqksKZ8WmR2zSjiQ7_v4TMAKdiHm9T0)
    2. Get Chat ID:

      Method 1: Via Official API

      • First send a message to your bot
      • Visit: https://api.telegram.org/bot<Your Bot Token>/getUpdates
      • Find the number in "chat":{"id":number} in returned JSON

      Method 2: Using Third-Party Tool

      • Search @userinfobot and send /start
      • Get your user ID as Chat ID
    3. Configure to GitHub:

      • TELEGRAM_BOT_TOKEN: Fill in Bot Token from step 1
      • TELEGRAM_CHAT_ID: Fill in Chat ID from step 2
    👉 Click to expand: Email Push (Supports all mainstream email providers)
    • Note: To prevent email bulk sending abuse, current bulk sending allows all recipients to see each other's email addresses.
    • If you haven't configured email sending before, not recommended to try

    GitHub Secret Configuration:

    • Name: EMAIL_FROM - Sender email address
    • Name: EMAIL_PASSWORD - Email password or authorization code
    • Name: EMAIL_TO - Recipient email address (multiple separated by comma) or can be same as EMAIL_FROM, send to yourself
    • Name: EMAIL_SMTP_SERVER - SMTP server address (optional, auto-detect if empty)
    • Name: EMAIL_SMTP_PORT - SMTP port (optional, auto-detect if empty)

    Supported Email Providers (Auto-detect SMTP config):

    Provider Domain SMTP Server Port Encryption
    Gmail gmail.com smtp.gmail.com 587 TLS
    QQ Mail qq.com smtp.qq.com 465 SSL
    Outlook outlook.com smtp-mail.outlook.com 587 TLS
    Hotmail hotmail.com smtp-mail.outlook.com 587 TLS
    Live live.com smtp-mail.outlook.com 587 TLS
    163 Mail 163.com smtp.163.com 465 SSL
    126 Mail 126.com smtp.126.com 465 SSL
    Sina Mail sina.com smtp.sina.com 465 SSL
    Sohu Mail sohu.com smtp.sohu.com 465 SSL

    Auto-detect: When using above emails, no need to manually configure EMAIL_SMTP_SERVER and EMAIL_SMTP_PORT, system auto-detects.

    Common Email Settings:

    QQ Mail:

    1. Login QQ Mail web version → Settings → Account
    2. Enable POP3/SMTP service
    3. Generate authorization code (16-letter code)
    4. EMAIL_PASSWORD fill authorization code, not QQ password

    Gmail:

    1. Enable two-step verification
    2. Generate app-specific password
    3. EMAIL_PASSWORD fill app-specific password

    163/126 Mail:

    1. Login web version → Settings → POP3/SMTP/IMAP
    2. Enable SMTP service
    3. Set client authorization code
    4. EMAIL_PASSWORD fill authorization code

    Advanced Configuration: If auto-detect fails, manually configure SMTP:

    • EMAIL_SMTP_SERVER: Like smtp.gmail.com
    • EMAIL_SMTP_PORT: Like 587 (TLS) or 465 (SSL)

    Multiple Recipients (note: English comma separator):

    • EMAIL_TO="user1@example.com,user2@example.com,user3@example.com"
    👉 Click to expand: ntfy Push (Open-source, free, self-hostable)

    Two Usage Methods:

    Features:

    • No account registration, use immediately
    • 250 messages/day (enough for 90% users)
    • Topic name is "password" (need to choose hard-to-guess name)
    • ⚠️ Messages unencrypted, not for sensitive info, but suitable for our non-sensitive project info

    Quick Start:

    1. Download ntfy App:

    2. Subscribe to Topic (choose a hard-to-guess name):

      Suggested format: trendradar-{your initials}-{random numbers}
      
      Cannot use Chinese
      
      ✅ Good example: trendradar-zs-8492
      ❌ Bad example: news, alerts (too easy to guess)
      
    3. Configure GitHub Secret:

      • NTFY_TOPIC: Fill in your subscribed topic name
      • NTFY_SERVER_URL: Leave empty (default uses ntfy.sh)
      • NTFY_TOKEN: Leave empty
    4. Test:

      curl -d "Test message" ntfy.sh/your-topic-name
      

    Method 2: Self-Hosting (Complete Privacy Control) 🔒

    Target Users: Have server, pursue complete privacy, strong technical ability

    Advantages:

    • Completely open-source (Apache 2.0 + GPLv2)
    • Complete data self-control
    • No restrictions
    • Zero cost

    Docker One-Click Deploy:

    docker run -d \
      --name ntfy \
      -p 80:80 \
      -v /var/cache/ntfy:/var/cache/ntfy \
      binwiederhier/ntfy \
      serve --cache-file /var/cache/ntfy/cache.db
    

    Configure TrendRadar:

    NTFY_SERVER_URL: https://ntfy.yourdomain.com
    NTFY_TOPIC: trendradar-alerts  # Self-hosting can use simple name
    NTFY_TOKEN: tk_your_token  # Optional: Enable access control
    

    Subscribe in App:

    • Click "Use another server"
    • Enter your server address
    • Enter topic name
    • (Optional) Enter login credentials

    FAQ:

    Q1: Is the free version enough?

    250 messages/day is enough for most users. With 30-minute crawl intervals, about 48 pushes/day, completely sufficient.

    Q2: Is the Topic name really secure?

    If you choose a random, sufficiently long name (like trendradar-zs-8492-news), brute force is nearly impossible:

    • ntfy has strict rate limiting (1 request/second)
    • 64 character choices (A-Z, a-z, 0-9, _, -)
    • 10 random characters have 64^10 possibilities (would take years to crack)

    Recommended Choice:

    User Type Recommended Reason
    Regular Users Method 1 (Free) Simple, fast, enough
    Technical Users Method 2 (Self-Host) Complete control, unlimited
    High-Frequency Users Method 3 (Paid) Check official website

    Related Links:

    💡 Beginner Quick Start Tip:

    For first deployment, suggest completing GitHub Secrets configuration first (choose one push platform), then jump to [Step 4] to test push success.

    Don't modify config/config.yaml and frequency_words.txt temporarily, adjust these configs after push test succeeds as needed.

  3. Configuration Notes::

    Note: Suggest only adjusting explicitly documented config items, other options mainly for author's development testing

  4. Manual Test News Push:

    Using my project as example, you should test in your forked project

    1. Enter Actions: https://github.com/sansan0/TrendRadar/actions
    2. Find "Hot News Crawler" and click in. If you don't see this text, refer to #109 to solve
    3. Click "Run workflow" button to run, wait about 1 minute for data to arrive on your phone

🐳 Docker Deployment

Method 1: Quick Experience (One-Line Command)

Linux/macOS System:

# Create config directory and download config files
mkdir -p config output
wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/config/config.yaml -P config/
wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/config/frequency_words.txt -P config/

Or Manual Creation:

  1. Create config folder in current directory
  2. Download config files:

Final directory structure should be:

current directory/
└── config/
    ├── config.yaml
    └── frequency_words.txt
docker run -d --name trend-radar \
  -v ./config:/app/config:ro \
  -v ./output:/app/output \
  -e FEISHU_WEBHOOK_URL="your feishu webhook" \
  -e DINGTALK_WEBHOOK_URL="your dingtalk webhook" \
  -e WEWORK_WEBHOOK_URL="your wework webhook" \
  -e TELEGRAM_BOT_TOKEN="your telegram_bot_token" \
  -e TELEGRAM_CHAT_ID="your telegram_chat_id" \
  -e EMAIL_FROM="your sender email" \
  -e EMAIL_PASSWORD="your email password or auth code" \
  -e EMAIL_TO="recipient email" \
  -e CRON_SCHEDULE="*/30 * * * *" \
  -e RUN_MODE="cron" \
  -e IMMEDIATE_RUN="true" \
  wantcat/trendradar:latest
  1. Create Project Directory and Config:
    # Create directory structure
    mkdir -p trendradar/{config,docker}
    cd trendradar
    
    # Download config file templates
    wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/config/config.yaml -P config/
    wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/config/frequency_words.txt -P config/
    
    # Download docker-compose config
    wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/docker/.env
    wget https://raw.githubusercontent.com/sansan0/TrendRadar/master/docker/docker-compose.yml
    

Final directory structure should be:

current directory/
├── config/
│   ├── config.yaml
│   └── frequency_words.txt
└── docker/
    ├── .env
    └── docker-compose.yml
  1. Config File Description:

    • config/config.yaml - Application main config (report mode, push settings, etc.)
    • config/frequency_words.txt - Keyword config (set your interested trending keywords)
    • .env - Environment variable config (webhook URLs and scheduled tasks)

    ⚙️ Environment Variable Override Mechanism (v3.0.5+)

    If you encounter config.yaml modifications not taking effect in NAS or other Docker environments, you can directly override configs via environment variables:

    Environment Variable Corresponding Config Example Value Description
    ENABLE_CRAWLER crawler.enable_crawler true / false Enable crawler
    ENABLE_NOTIFICATION notification.enable_notification true / false Enable notification
    REPORT_MODE report.mode daily / incremental / current Report mode
    PUSH_WINDOW_ENABLED notification.push_window.enabled true / false Push time window switch
    PUSH_WINDOW_START notification.push_window.time_range.start 08:00 Push start time
    PUSH_WINDOW_END notification.push_window.time_range.end 22:00 Push end time
    FEISHU_WEBHOOK_URL notification.webhooks.feishu_url https://... Feishu Webhook

    Config Priority: Environment Variables > config.yaml

    Usage Method:

    • Modify .env file, uncomment and fill in needed configs
    • Or add directly in NAS/Synology Docker management interface's "Environment Variables"
    • Restart container to take effect: docker-compose restart
  2. Start Service:

    # Pull latest image and start
    docker-compose pull
    docker-compose up -d
    
  3. Check Running Status:

    # View logs
    docker logs -f trend-radar
    
    # View container status
    docker ps | grep trend-radar
    

Method 3: Local Build (Developer Option)

If you need custom code modifications or build your own image:

# Clone project
git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar

# Modify config files
vim config/config.yaml
vim config/frequency_words.txt

# Use build version docker-compose
cd docker
cp docker-compose-build.yml docker-compose.yml

# Build and start
docker-compose build
docker-compose up -d

Image Update

# Method 1: Manual update
docker pull wantcat/trendradar:latest
docker-compose down
docker-compose up -d

# Method 2: Using docker-compose update
docker-compose pull
docker-compose up -d

Service Management Commands

# View running status
docker exec -it trend-radar python manage.py status

# Manually execute crawler once
docker exec -it trend-radar python manage.py run

# View real-time logs
docker exec -it trend-radar python manage.py logs

# Display current config
docker exec -it trend-radar python manage.py config

# Display output files
docker exec -it trend-radar python manage.py files

# View help info
docker exec -it trend-radar python manage.py help

# Restart container
docker restart trend-radar

# Stop container
docker stop trend-radar

# Remove container (keep data)
docker rm trend-radar

Data Persistence

Generated reports and data are saved in ./output directory by default. Data persists even if container is restarted or removed.

Troubleshooting

# Check container status
docker inspect trend-radar

# View container logs
docker logs --tail 100 trend-radar

# Enter container for debugging
docker exec -it trend-radar /bin/bash

# Verify config files
docker exec -it trend-radar ls -la /app/config/

🤖 AI Analysis Deployment

TrendRadar v3.0.0 added MCP (Model Context Protocol) based AI analysis feature, allowing natural language conversations with news data for deep analysis. Best prerequisite for using AI features is running this project for at least one day (accumulate news data).

1. Quick Deployment

Cherry Studio provides GUI config interface, 5-minute quick deployment, complex parts are one-click install.

Illustrated Deployment Tutorial: Now updated to my WeChat Official Account (see FAQ & Support), reply "mcp" to get

Detailed Deployment Tutorial: README-Cherry-Studio.md

2. Learning to Talk with AI

Detailed Conversation Tutorial: README-MCP-FAQ.md

Question Effect:

Actually not recommended to ask multiple questions at once. If your chosen AI model cannot even sequentially call as shown below, suggest switching models.

MCP usage effect

🔌 MCP Clients

TrendRadar MCP service supports standard Model Context Protocol (MCP), can connect to various AI clients supporting MCP for smart analysis.

Supported Clients

Note:

  • Replace /path/to/TrendRadar with your actual project path
  • Windows paths use double backslashes: C:\\Users\\YourName\\TrendRadar
  • Remember to restart after saving
👉 Click to expand: Claude Desktop

Config File Method

Edit Claude Desktop's MCP config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Config Content:

{
  "mcpServers": {
    "trendradar": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/TrendRadar",
        "run",
        "python",
        "-m",
        "mcp_server.server"
      ],
      "env": {},
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
👉 Click to expand: Cursor

Method 1: HTTP Mode

  1. Start HTTP Service:

    # Windows
    start-http.bat
    
    # Mac/Linux
    ./start-http.sh
    
  2. Configure Cursor:

    Project Level Config (Recommended): Create .cursor/mcp.json in project root:

    {
      "mcpServers": {
        "trendradar": {
          "url": "http://localhost:3333/mcp",
          "description": "TrendRadar News Trending Aggregation Analysis"
        }
      }
    }
    

    Global Config: Create ~/.cursor/mcp.json in user directory (same content)

  3. Usage Steps:

    • Restart Cursor after saving config
    • Check connected tools in chat interface "Available Tools"
    • Start using: Search today's "AI" related news

Create .cursor/mcp.json:

{
  "mcpServers": {
    "trendradar": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/TrendRadar",
        "run",
        "python",
        "-m",
        "mcp_server.server"
      ]
    }
  }
}

(Additional client configs including VSCode/Cline/Continue, Claude Code CLI, MCP Inspector, and others available in Chinese version)

FAQ & Support

If you want to support this project, you can search Tencent Charity on WeChat and donate to Education Support Programs as you wish~

We're anxious about information overload, while they struggle in information deserts without even learning opportunities, so they need support more than me.

👉 Click to expand: Author's Note

Thanks for all support! Due to sponsor support, the one-yuan donation QR code has been removed.

Previous one-yuan supporters are listed in the Acknowledgments section at the top.

This project's development and maintenance require significant time, effort, and costs (including AI model fees). With sponsorship support, I can maintain it more confidently.

Currently, major AI model prices are relatively affordable. If you don't have a suitable model yet, clicking 302.AI below also supports the developer:

302ai logo

Usage Process:

  1. After registration and top-up, enter Management Dashboard at top right
  2. Click API Keys on the left
  3. Find default API KEY at page bottom, click eye icon to view, then copy (Note: don't click the copy button on the far right)
  4. Cherry Studio has integrated 302.AI, just fill in API key to use (currently must fill key first to see complete model list)

If you already have a suitable model, welcome to register and try~

  • GitHub Issues: Suitable for targeted answers. Please provide complete info when asking (screenshots, error logs, system environment, etc.)
  • WeChat Official Account: Suitable for quick consultation. Suggest priority to communicate in public comment area of related articles. If private message, please use polite language 😉
WeChat Official Account

🪄 Sponsors

302.AI is a pay-as-you-go enterprise-level AI resource platform Providing the latest and most comprehensive AI models and APIs on the market, plus various ready-to-use online AI applications.

302ai banner

Common Questions

👉 Click to expand: Q1: HTTP Service Cannot Start?

Check Steps:

  1. Confirm port 3333 is not occupied:

    # Windows
    netstat -ano | findstr :3333
    
    # Mac/Linux
    lsof -i :3333
    
  2. Check if project dependencies installed:

    # Re-run install script
    # Windows: setup-windows.bat or setup-windows-en.bat
    # Mac/Linux: ./setup-mac.sh
    
  3. View detailed error logs:

    uv run python -m mcp_server.server --transport http --port 3333
    
  4. Try custom port:

    uv run python -m mcp_server.server --transport http --port 33333
    
👉 Click to expand: Q2: Client Cannot Connect to MCP Service?

Solutions:

  1. STDIO Mode:

    • Confirm UV path correct (run which uv or where uv)
    • Confirm project path correct and no Chinese characters
    • Check client error logs
  2. HTTP Mode:

    • Confirm service started (visit http://localhost:3333/mcp)
    • Check firewall settings
    • Try using 127.0.0.1 instead of localhost
  3. General Checks:

    • Restart client application
    • Check MCP service logs
    • Use MCP Inspector to test connection
👉 Click to expand: Q3: Tool Call Failed or Returns Error?

Possible Reasons:

  1. Data Does Not Exist:

    • Confirm crawler has run (have output directory data)
    • Check query date range has data
    • Check available dates in output directory
  2. Parameter Error:

    • Check date format: YYYY-MM-DD
    • Confirm correct platform ID: zhihu, weibo, etc.
    • See parameter descriptions in tool docs
  3. Config Issues:

    • Confirm config/config.yaml exists
    • Confirm config/frequency_words.txt exists
    • Check config file format is correct

Project Articles

Related Articles (Chinese):

AI Development:

  • If you have niche requirements, you can develop based on my project yourself, even with zero programming experience
  • All my open-source projects use my own AI-assisted software to improve development efficiency, this tool is now open-source
  • Core Function: Quickly filter project code to feed AI, you just need to add personal requirements
  • Project Address: https://github.com/sansan0/ai-code-context-helper

📍 Chairman Mao's Footprint Map - Interactive dynamic display of complete trajectory 1893-1976. Welcome comrades to contribute data

Bilibili Comment Data Visualization Analysis Software

👉 Click to expand: WeChat Push Notification Solution

Since this solution is based on WeWork's plugin mechanism and has very different push styles, I temporarily don't plan to include related implementation in the current project

  • Fork this user's project: https://github.com/jayzqj/TrendRadar
  • Complete WeWork push setup above
  • Follow the image below to operate
  • After configuration, you can delete WeWork app from your phone

Project Workflow Diagram

flowchart TD
    A[👤 User Start] --> B{🚀 Choose Deployment}

    B -->|Cloud Deployment| C1[🍴 Fork to GitHub]
    B -->|Local Deployment| C2[🐳 Docker Deploy]

    C1 --> D[⚙️ Configure Notification<br/>Multiple channels supported]
    C2 --> D

    D --> E[Choose method:<br/>📱WeWork 💬Feishu 🔔DingTalk<br/>📟Telegram 📧Email]

    E --> F[🔑 Fill notification params<br/>GitHub Secrets or Env Vars]

    F --> G[📝 Configure keywords<br/>config/frequency_words.txt<br/>Normal/Required+/Filter!]

    G --> H[🎯 Choose mode<br/>config/config.yaml]

    H --> H1[📋 daily - Daily summary<br/>Scheduled push all matches]
    H --> H2[📰 current - Current rankings<br/>Scheduled push latest]
    H --> H3[📈 incremental - Incremental<br/>Push only new content]

    H1 --> I[Optional: Push time window<br/>⏰ Limit push time range]
    H2 --> I
    H3 --> I

    I --> J[✅ Config Complete]

    J --> K[🤖 Auto Run]

    K --> L[🕷️ Crawl 11+ platforms]
    L --> M[🔍 Keyword filtering]
    M --> N[⚖️ Weight sorting<br/>Rank 60% + Freq 30% + Hot 10%]
    N --> O[📊 Generate reports<br/>HTML + Push messages]
    O --> P[📱 Multi-channel push]

    P --> Q[🎉 Receive precise push<br/>Say goodbye to info overload]

    style A fill:#e3f2fd
    style B fill:#f3e5f5
    style D fill:#fff3e0
    style F fill:#fff9c4
    style G fill:#e8f5e9
    style H fill:#e0f2f1
    style I fill:#fce4ec
    style O fill:#e1bee7
    style Q fill:#c8e6c9

Star History Chart

📄 License

GPL-3.0 License