TrendRadar MCP

The fastest hot-topic assistant, deployable in 30 seconds — say goodbye to useless scrolling and only see the news you truly care about

🌐 Official Website · 📖 Official Docs

English | 简体中文

This project aims to be lightweight and easy to deploy

📑 Quick Navigation

💡 Click the links below to jump to the corresponding section. For deployment, we recommend starting with "Quick Start"; for detailed customization, see "Configuration Guide"

• Thanks to everyone who starred the project. Forking is what you desire, starring is what I desire — having both 😍 is the best support for the open-source spirit

Early Supporters Acknowledgments

💡 Special Notes:

1. About the list: The table below records supporters from the project's early stage (Angel Round). Due to the tediousness of manual tracking in the early days, omissions or incomplete records are inevitable. If anyone is missing, it is truly unintentional, and we ask for your understanding.

2. Future Plans: To devote limited energy back to code and feature iteration, this list will no longer be manually maintained from now on.

Whether your name is on the list or not, every bit of your support is the cornerstone of TrendRadar's journey to where it is today. 🙏

Infrastructure Support

Thanks to GitHub for providing free infrastructure, which is the biggest prerequisite for this project's one-click fork convenience.

Data Support

This project uses the API from the newsnow project to fetch multi-platform data. Special thanks to the author for providing this service.

After contacting the author, he indicated there is no need to worry about server load, but this is based on his goodwill and trust. Please:

• Go to the newsnow project and star it to show support

• When deploying with Docker, please control push frequency reasonably and don't overuse the service

Promotion Support

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

• 小众软件 - Open-source software recommendation platform

• LinuxDo 社区 - A gathering place for tech enthusiasts

• 阮一峰周刊 - An influential weekly in the tech community

Viewer Support

Thanks to the friends who provided financial support. Your generosity has been transformed into snacks and drinks beside the keyboard, accompanying every iteration of the project.

About the return of "one-yuan likes": With the release of v5.0.0, the project has entered a new phase. To support the growing API costs and caffeine consumption, the "one-yuan like" channel has been reopened. Every bit of your appreciation will be converted into Tokens and motivation in the code world. 🚀 Go to Support

Related MCP server: TrendRadar

🪄 Sponsor

Enjoy the full-power versions of ByteDance's self-developed Doubao large model and mainstream open-source SOTA models in one place, covering multimodal capabilities such as text, visual understanding (VLM), and image generation. Popular models like Seed-2.1, Seedream 5.0, GLM-5.2, and DeepSeek are all available in one stop — not just for efficient coding, but also for complex long-horizon Agent tasks.

❤️ Like it? Support us

If TrendRadar has captured value for you, why not give it a boost to keep evolving

Any amount is fine — even 1 yuan is encouragement for open source. Feel free to leave a note when supporting (´▽`ʃ♡ƪ)

🤝 Secondary Development and Attribution

If you use or draw inspiration from this project's ideas or core code in your project, you are very welcome to credit the source and include a link to this repository in your README or documentation.

This helps with the project's continued maintenance and community growth. Thank you for your respect and support! ❤️

💬 Communication and Feedback

• GitHub Issues: Best suited for specific technical questions. When asking, please provide complete information (screenshots, error logs, etc.) to help with quick troubleshooting.

• Official Account (WeChat): We recommend discussing in the comment sections of related articles first. If you need to ask via the backend, liking/recommending the article first is the best "door opener" — I can feel that kindness on the backend (´▽`ʃ♡ƪ).

• QQ Group: Follow the official account and reply with "交流群" (Discussion Group) to join. Whether you're an AI beginner or a hardcore developer, whether you need technical help or want to share your tinkering experiences, you're welcome here. The group focuses on mutual help and idea exchange. Please read the group announcement upon joining; when asking questions, describe the issue clearly and attach screenshots. Group members will help when they have time — their hands-on experience is often faster and more comprehensive than mine alone 🤝

Friendly Tip: This project is open-source sharing, not a commercial product. Treating the author as a friend rather than customer support will make communication much smoother!

📝 Changelog

📌 View Latest Updates: Original Repository Changelog :

• Note: It's recommended to check the [Historical Updates] to understand the specific [feature details]

2026/06/19 - v6.10.0

• AI translation batch processing: Large batches of title translations are automatically split into multiple requests to avoid translation failures caused by single-request limits

• Module split refactor: Split context.py and __main__.py; the AI filtering pipeline is now an independent filter_pipeline module for clearer responsibilities and easier maintenance

• Fix Feishu source label display: Fixed the issue where source labels and AI standalone source summaries in Feishu cards were swallowed by CommonMark and not displayed

2026/02/09 - mcp-v4.0.0

• 🔥 AI messages pushed directly to all channels: AI-generated content can now be pushed to 9 channels including Feishu, DingTalk, Telegram, and email with one click. Markdown is automatically adapted to each platform's format, so you don't need to worry about format differences

• New formatting strategy guide: Added the get_channel_format_guide tool that tells AI what formats each channel supports and what limitations exist, resulting in better-formatted generated content

• Smart batch sending: Overlong messages are automatically split according to each channel's byte limits (Feishu 30KB, DingTalk 20KB, etc.), with configuration read from config.yaml

• Fix channel misdetection: ntfy is no longer falsely reported as "configured" due to its default address

• Code reuse optimization: Batch processing functions directly reuse the trendradar core modules instead of reinventing the wheel

2026/06/02 - v6.9.0

• Hotlist domain security validation: Added the expected_domain config option to validate the domain of returned data links. Data is automatically discarded with a warning when it doesn't match, effectively preventing link hijacking or data tampering

• Custom hotlist API address: Supports self-hosting newsnow and configuring api_url to use your own data source

2026/05/23 - v6.8.0

• HTML report comprehensive enhancement: Added report metadata display (generation time, data source, version number), automatic dark mode adaptation, Tab bar interaction improvements, and trend arrow visualization for a much better browser reading experience

• Version check CDN multi-source fallback: The version check endpoint now supports automatic fallback across multiple CDN sources (GitHub → jsDelivr → Cloudflare), ensuring stable update notifications even on domestic networks

• Display region toggles now take effect: HTML reports and emails now correctly respect the display.regions.ai_analysis and display.regions.standalone toggles — regions are not rendered when disabled

• Export button fix: Fixed the issue where the dropdown menu icon disappeared after clicking the export button

• Markdown export fix: Fixed the JS newline escape error in the Markdown export of HTML reports

2026/05/15 - v6.7.0

• Markdown export: The report export dropdown menu now includes a Markdown format option, generating structured text with links in one click for easy LLM post-processing and cross-platform sharing (#1121)

• RSS guid deduplication: RSS storage now includes a guid field, and the deduplication priority is changed to guid > url, solving the issue of duplicate entries for the same article due to URL changes

• Empty title protection: Added empty-title fallback logic across the entire pipeline (parser, renderer, translation backfill) to ensure entries without titles display correctly

• Translation quality enhancement: Translation prompts now require preserving numbering order, and empty translation results no longer overwrite original titles

2026/03/28 - v6.6.0

• HTML report browser enhancement: Opening the report in a browser now automatically switches to a widescreen layout. Keyword groups and standalone sections both support quick Tab switching, and the search box filters news titles in real time. Email clients still see the original narrow layout with zero regression

• Dark mode: Toggle dark theme with one click, with automatic preference memory, ideal for nighttime reading

• One-click news copy: Hover over a news item's number to copy its title and link for quick sharing

• Export optimization: Full-page and section screenshots are merged into a dropdown export button, and the layout is automatically restored to a clean state when taking screenshots

• Shortcut system: Supports W for widescreen toggle, D for dark mode, / for search, and ? to view shortcut hints

• Reading progress bar: Real-time reading progress displayed at the top of the page

2026/03/12 - v6.5.0

• AI smart filtering system: No more manual keyword setup! Write your areas of interest in ai_interests.txt in everyday language (e.g., "I want to see news about AI and new energy"), and AI will automatically extract tags and score each news item, pushing only content truly relevant to you. If AI filtering ever fails, it automatically falls back to keyword matching so pushes are never interrupted

• Each time slot supports different filtering methods and interests: Each time period in the Timeline can now independently set its filtering method and news type. For example, use "tech keywords" for quick filtering in the morning, and switch to a "finance AI interest description" for deep filtering at night — different content at different times from the same system

• AI analysis scope independent of pushes: The data scope for AI analysis can differ from push content. For example, pushes can only send new messages (to avoid repeated interruptions), while AI analyzes all news of the day (to see the full trend). Each time slot can also set its own AI analysis mode

• AI filtering saves money smartly: Already-analyzed news doesn't consume tokens repeatedly; after interest description changes, AI automatically judges the magnitude of change — small edits only update affected tags, while large edits trigger full reclassification

• Multi-file configuration with tag isolation: Custom keyword files go in config/custom/keyword/, AI interest files in config/custom/ai/. Tags generated from different files are independent and don't interfere with each other

• AI translation precise control: You can independently control whether hotlists, RSS, and standalone display sections are translated. Regions not enabled for display are automatically skipped to avoid wasting tokens

• Remote storage batch upload: Multiple write operations are batched and committed to the cloud at once, reducing API call count

• Per-group keyword/tag display limit: max_news_per_keyword controls how many news items each group displays at most, preventing a single hot topic from filling the entire push

• Time slot conflict detection: If two time periods overlap, the system automatically reports an error to prompt correction, avoiding unexpected behavior from configuration conflicts

• Fixed several bugs

2026/02/09 - v6.0.0

Breaking Change: Configuration file upgrade (config.yaml 2.0.0). The old push_window and analysis_window configurations are no longer compatible. Please refer to the new config.yaml for migration

• Unified scheduling system: Added timeline.yaml to control "when to collect / push / AI analyze" with a single configuration

• 5 preset templates: always_on (24/7, default), morning_evening (morning/evening summaries), office_hours (work hours), night_owl (night owl), custom (custom); you can also add your own templates under presets: as long as keys don't conflict, then enter your template name in config.yaml

• Flexible time slot configuration: Supports weekday/weekend differentiation, cross-midnight time slots, and per-period once deduplication

• Visual configuration editor:

  • Added a timeline.yaml editing tab alongside config.yaml / frequency_words.txt

  • Preset mode card selection: click to switch, automatically syncing schedule.preset in config.yaml

  • Week view timeline: 7-day × 24-hour horizontal bars with colors distinguishing push/analysis/collection status

  • Interactive controls: toggles, dropdowns, time pickers — right-side edits sync to the left-side YAML in real time

  • Week mapping dropdown: dynamically populated based on the day plan; drag, click, and you're done with scheduling

• AI prompt stability optimization (ai_analysis_prompt.txt v2.0.0):

  • Standalone format specification: line breaks/tags/numbers/prohibited items extracted from JSON values into a separate section

  • Simplified JSON template: field descriptions shortened to one sentence + character limits, reducing AI output format chaos

  • Removed Markdown formatting from the system prompt to stay consistent with the "no Markdown" instruction

  • All JSON fields declared optional; missing fields won't cause errors, improving fault tolerance

• New standalone section AI summary analysis (ai_analysis.include_standalone):

  • New independent toggle: when enabled, AI generates core summaries for each standalone source

  • AI analysis decoupled from push display: AI can independently analyze full hotlist data without enabling standalone section push display

  • Supports hotlist platforms and RSS sources, including ranking/time/trajectory data

  • Trajectory analysis linked with include_rank_timeline: when enabled, uses trajectory data for deep trend analysis; when disabled, makes brief judgments based on rankings

  • New standalone_summaries JSON field (standalone source quick summaries), adapted for rendering across all push channels

2026/01/28 - v5.5.0

Same as the mcp feature, I won't create a separate repository for this little tool either — it's pure frontend, so let's keep it all together

• Added a visual configuration editor for trendradar

2026/02/02 - mcp-v3.2.0

• New read_article tool: Reads the full text of a single article via Jina AI Reader (Markdown format)

• New read_articles_batch tool: Batch reads multiple articles (up to 5, with automatic rate limiting)

• Recommended workflow: search_news(query="keyword", include_url=True) → read_article(url=...) to read the full text

• Documentation update: README-MCP-FAQ.md and README-MCP-FAQ-EN.md add Q19-Q20 on article reading

2026/01/10 - mcp-v3.0.0~v3.1.5

• Breaking Change: All tool return values unified to the {success, summary, data, error} structure

• Async consistency: All 21 tool functions use asyncio.to_thread() to wrap synchronous calls

• MCP Resources: Added 4 resources (platforms, rss-feeds, available-dates, keywords)

• RSS enhancement: get_latest_rss supports multi-day queries (days parameter) with cross-date URL deduplication

• Regex matching fix: get_trending_topics supports /pattern/ regex syntax and display_name

• Cache optimization: Added the make_cache_key() function with parameter sorting + MD5 hashing for consistency

• New check_version tool: Supports checking updates for both TrendRadar and MCP Server simultaneously

2026/01/23 - v5.4.0

• Added independent control for AI analysis mode, with options: follow_report | daily | current | incremental

• Added AI analysis time window control, supporting custom run segments and daily frequency limits

• Added configuration file version management

• Fixed several bugs

2026/01/19 - v5.3.0

Major refactor: AI module migrated to LiteLLM

• Unified AI interface: Uses LiteLLM instead of manual implementation, supporting 100+ AI providers

• Simplified configuration: Removed the provider field, switched to model: "provider/model_name" format

• New features: Automatic retry (num_retries), fallback models (fallback_models)

• Configuration changes:

  • ai.provider → removed (merged into model)

  • ai.base_url → ai.api_base

  • AI_PROVIDER environment variable → removed

  • AI_BASE_URL environment variable → AI_API_BASE

• Model format examples:

  • DeepSeek: deepseek/deepseek-chat

  • OpenAI: openai/gpt-4o

  • Gemini: gemini/gemini-2.5-flash

  • Anthropic: anthropic/claude-3-5-sonnet

2026/01/17 - v5.2.0

Mainly see the config.yaml description

🌐 AI Translation Feature

• Multi-language translation: Supports translating push content into any language

• Batch translation: Smart batch processing to reduce API call count

• Custom prompts: Supports custom translation styles

🔧 Configuration Architecture Optimization

• Independent AI model configuration: Analysis and translation share the same model configuration

• Unified region toggles: Unified management of push region display

• Custom region ordering: Supports customizing the display order of each region

✨ AI Analysis Enhancement

• AI analysis embedded in HTML: Analysis results are directly embedded in HTML reports and used directly by email notifications

• Rich-styled AI section: Gradient blue background card layout with clear separation of analysis dimensions

• Ranking timeline support: AI can obtain the exact ranking of each news item at each crawl timestamp

• Section reorganization (7→4): Consolidated into core hotspot trends, public sentiment and controversies, anomalies and weak signals, and research strategy recommendations

🔧 Multi-model Adaptation

• Generic parameter passthrough: Supports passing arbitrary advanced parameters to the API

• Gemini adaptation: Native parameter support with built-in relaxed safety policies

🐛 Bug Fixes

• Fixed several known issues to improve system stability

2026/01/10 - v5.0.0

Development interlude: A tribute to that model from a certain C company that accompanied me for over two years, only to pop up with "This organization has been disabled" right after I renewed my subscription

✨ Push Content "Five Major Sections" Refactor

This update refactors push messages by region. Push content is now clearly divided into five core sections:

1. 📊 Hotlist News: Aggregated trending topics from across the web, precisely filtered by your keywords.

2. 📰 RSS Subscriptions: Your personalized subscription source content, with keyword grouping support.

3. 🆕 New This Time: Real-time capture of brand-new hotspots since the last run (marked with 🆕).

4. 📋 Standalone Display Section: Full hotlist or RSS source display for specified platforms, completely unaffected by keyword filtering.

5. ✨ AI Analysis Section: AI-driven deep insights including trend overviews, popularity trajectories, and extremely important sentiment analysis.

✨ AI Smart Analysis Push Feature

• AI analysis integration: Uses AI large models for deep analysis of push content, automatically generating hotspot trend overviews, keyword popularity analysis, cross-platform correlations, potential impact assessments, and more

• Sentiment analysis: New deep sentiment recognition that precisely captures positive/negative, controversial, or concerned public sentiment

• Multiple AI provider support: Supports DeepSeek (default, cost-effective), OpenAI, Google Gemini, and any OpenAI-compatible endpoint

• Two push modes: only_analysis (AI analysis only), both (push both)

• Custom prompts: Customize AI analysis role and output format via the config/ai_analysis_prompt.txt file

• Multi-dimensional data analysis: AI can analyze ranking changes, popularity duration, cross-platform performance, trend prediction, and more

📋 Standalone Display Section Feature

• Full hotlist display: Complete hotlists of specified platforms displayed separately, unaffected by keyword filtering

• RSS standalone display: RSS source content can be fully displayed, suitable for subscription sources with less content

• Flexible configuration: Supports configuring platform lists, RSS source lists, and maximum display counts

📊 Push Experience Refactor

• Layout upgrade: Redesigned and unified statistics headers across all channels, strengthened section organization, and clearer message hierarchy at a glance

• Simplified configuration: Optimized configuration logic for notification channels like Feishu for easier onboarding

• Popularity trend arrows: New 🔺(up), 🔻(down), ➖(flat) trend indicators for intuitive popularity changes

• Generic Webhook: Supports custom Webhook URLs and JSON templates, easily adapting to Discord, Matrix, IFTTT, and any other platform

🔧 Configuration Optimization

• Frequency word configuration enhancement: New [group alias] syntax and # comment line support for clearer configuration (thanks to @songge8 for the suggestion)

• Environment variable support: AI analysis-related configurations support environment variable overrides (AI_API_KEY, AI_PROVIDER, etc.)

💡 Detailed configuration tutorial: see Let AI analyze hotspots for me

2026/01/02 - v4.7.0

• Fix RSS HTML display: Fixed rendering issues caused by RSS data format mismatches; now correctly grouped by keyword

• New regex syntax: Keyword configuration supports /pattern/ regex syntax, solving English substring false matches (e.g., ai matching training) 📖 View syntax details

• New display name syntax: Use => note to give complex regexes a memorable name for clearer push messages (e.g., /\bai\b/ => AI-related)

• Can't write regex? README adds a guide for AI-generated regex — tell ChatGPT/Gemini/DeepSeek what you want to match and let AI write it for you

2025/12/30 - mcp-v2.0.0

• Architecture adjustment: Removed TXT support, unified on SQLite database

• RSS queries: Added get_latest_rss, search_rss, get_rss_feeds_status

• Unified search: search_news supports the include_rss parameter to search both hotlists and RSS simultaneously

2026/01/01 - v4.6.0

• Fix RSS HTML display: Merged RSS content into the hotlist HTML page, displayed grouped by source

• New display_mode configuration: Supports keyword (group by keyword) and platform (group by platform) display modes

2025/12/30 - v4.5.0

• RSS subscription source support: Added RSS/Atom crawling with keyword-grouped statistics (consistent with hotlist format)

• Storage structure refactor: Flattened directory structure output/{type}/{date}.db

• Unified sort configuration: sort_by_position_first now affects both hotlists and RSS

• Configuration structure refactor: config.yaml reorganized into 7 logical groups (app, report, notification, storage, platforms, rss, advanced) for clearer configuration paths

2025/12/26 - mcp-v1.2.0

MCP module update - optimized toolset, added aggregation comparison, merged redundant tools:

• New aggregate_news tool - cross-platform news deduplication aggregation

• New compare_periods tool - period comparison analysis (week-over-week/month-over-month)

• Merged find_similar_news + search_related_news_history → find_related_news

• Enhanced get_trending_topics - new auto_extract mode for automatic hotspot extraction

• Fixed several bugs

• Synced README-MCP-FAQ.md documentation in both Chinese and English (Q1-Q18)

2025/12/20 - v4.0.3

• Added URL normalization to solve duplicate pushes caused by dynamic parameters (e.g., band_rank) on platforms like Weibo

• Fixed incremental mode detection logic to correctly identify historical titles

2025/12/17 - v4.0.1

• StorageManager adds push record proxy methods

• S3 client switched to virtual-hosted style for better compatibility (supports Tencent Cloud COS and more services)

2025/12/13 - mcp-v1.1.0

MCP module update:

• Adapted to v4.0.0, while remaining compatible with v3.x data

• New storage sync tools: sync_from_remote, get_storage_status, list_available_dates

2025/12/13 - v4.0.0

🎉 Major update: comprehensive storage and core architecture refactor

• Multiple storage backends: Introduced a new storage module supporting local SQLite and remote cloud storage (S3-compatible protocols, e.g., Cloudflare R2), adapting to GitHub Actions, Docker, and local environments.

• Database structure optimization: Refactored SQLite database table structures for improved data efficiency and query capability.

• Core code modularization: Split main program logic into multiple modules of the trendradar package, significantly improving code maintainability.

• Enhanced features: Implemented date format standardization, data retention policies, timezone configuration support, time display optimization, and fixed remote storage data persistence issues to ensure accurate data merging.

• Cleanup and compatibility: Removed most legacy compatibility code and unified data storage and reading methods.

2025/12/03 - v3.5.0

🎉 Core Feature Enhancements

1. Multi-account push support

   • All push channels (Feishu, DingTalk, WeCom, Telegram, ntfy, Bark, Slack) support multi-account configuration

   • Use semicolons ; to separate multiple accounts, e.g.: FEISHU_WEBHOOK_URL=url1;url2

   • Automatically validates paired configuration count consistency (e.g., Telegram token and chat_id)

2. Push region configuration

   • Customize the display order of each region via display.region_order (v5.2.0 replaces the original reverse_content_order)

   • Control whether each region is displayed via display.regions (hotlist, new hotspots, RSS, standalone display, AI analysis)

3. Global filter keywords

   • New [GLOBAL_FILTER] region marker for globally filtering content you don't want to see

   • Use cases: filtering ads, marketing, low-quality content, etc.

🐳 Docker Dual-Path HTML Generation Optimization

• Issue fix: Resolved the problem where index.html couldn't sync to the host machine in Docker environments

• Dual-path generation: The daily summary HTML is now generated to two locations

  • index.html (project root): for GitHub Pages access

  • output/index.html: mounted via Docker Volume for direct host access

• Compatibility: Ensures Docker, GitHub Actions, and local run environments can all access the web report

🐳 Docker MCP Image Support

• Added a standalone MCP service image wantcat/trendradar-mcp

• Supports Docker deployment of AI analysis features, served via HTTP interface (port 3333)

• Dual-container architecture: news push service and MCP service run independently, can be scaled and restarted separately

• See Docker Deployment - MCP Service

🌐 Web Server Support

• Added built-in web server, supports viewing generated reports via browser

• Control start/stop via manage.py command: docker exec -it trendradar python manage.py start_webserver

• Access address: http://localhost:8080 (port configurable)

• Security features: static file serving, directory restrictions, local access

• Supports both auto-start and manual control modes

📖 Documentation Improvements

• Added How are pushed messages displayed? section: customize push style and content

• Added When will I receive pushes? section: set push time windows

• Added How often does it run? section: set automatic run frequency

• Added Push to multiple groups/devices section: push to multiple recipients simultaneously

• Optimized each configuration section: uniformly added "Configuration Location" notes

• Simplified quick start configuration instructions: three core files at a glance

• Optimized Docker Deployment section: added image notes, recommended git clone deployment, reorganized deployment methods

🔧 Upgrade Notes:

• GitHub Fork Users: Update main.py, config/config.yaml (added multi-account push support, no need to modify existing configuration)

• Multi-account Push: New feature, disabled by default, existing single-account configuration is unaffected

2025/11/26 - mcp-v1.0.3

MCP Module Updates:

• Added date parsing tool resolve_date_range, solving the issue of inconsistent date calculations by AI models

• Supports natural language date expression parsing (this week, last 7 days, last month, etc.)

• Total tools increased from 13 to 14

2025/11/28 - v3.4.1

🔧 Format Optimization

1. Bark Push Enhancement

   • Bark now supports Markdown rendering

   • Enabled native Markdown formatting: bold, links, lists, code blocks, etc.

   • Removed plain text conversion, fully leveraging Bark's native rendering capabilities

2. Slack Format Precision

   • Uses dedicated mrkdwn format for batched content

   • Improved byte size estimation accuracy (avoids message limit overruns)

   • Optimized link format: <url|text> and bold syntax: *text*

3. Performance Improvements

   • Format conversion completed during batching, avoiding double processing

   • Accurate message size estimation, reducing send failure rate

🔧 Upgrade Notes:

• GitHub Fork Users: Update main.py, config.yaml

2025/11/25 - v3.4.0

🎉 New Slack Push Support

1. Team Collaboration Push Channel

   • Supports Slack Incoming Webhooks (globally popular team collaboration tool)

   • Centralized message management, suitable for team sharing of trending news

   • Supports mrkdwn format (bold, links, etc.)

2. Multiple Deployment Methods

   • GitHub Actions: configure SLACK_WEBHOOK_URL Secret

   • Docker: environment variable SLACK_WEBHOOK_URL

   • Local run: config/config.yaml configuration file

📖 Detailed Configuration Tutorial: Quick Start - Slack Push

• Optimized setup-windows.bat and setup-windows-en.bat one-click MCP installation experience

🔧 Upgrade Notes:

• GitHub Fork Users: Update main.py, config/config.yaml, .github/workflows/crawler.yml

2025/11/24 - v3.3.0

🎉 New Bark Push Support

1. iOS-exclusive Push Channel

   • Supports Bark push (based on APNs, iOS platform)

   • Free and open source, simple and efficient, no ad interference

   • Supports both official server and self-hosted server

2. Multiple Deployment Methods

   • GitHub Actions: configure BARK_URL Secret

   • Docker: environment variable BARK_URL

   • Local run: config/config.yaml configuration file

📖 Detailed Configuration Tutorial: Quick Start - Bark Push

🐛 Bug Fixes

• Fixed the issue where ntfy_server_url configuration in config.yaml was not taking effect (#345)

🔧 Upgrade Notes:

• GitHub Fork Users: Update main.py, config/config.yaml, .github/workflows/crawler.yml

2025/11/23 - v3.2.0

🎯 New Advanced Customization Features

1. Keyword Sorting Priority Configuration

   • Supports two sorting strategies: popularity-first vs configuration-order-first

   • Meets different usage scenarios: trend tracking or personalized focus

2. Precise Display Count Control

   • Global configuration: uniformly limit display count for all keywords

   • Individual configuration: use @number syntax to set limits for specific keywords

   • Effectively controls push length, highlighting key content

📖 Detailed Configuration Tutorial: Keyword Configuration - Advanced Configuration

🔧 Upgrade Notes:

• GitHub Fork Users: Update main.py, config/config.yaml

2025/11/18 - mcp-v1.0.2

MCP Module Updates:

• Optimized the case where querying today's news might incorrectly return past dates

2025/11/22 - v3.1.1

• Fixed crash caused by abnormal data: resolved the 'float' object has no attribute 'lower' error some users encountered in GitHub Actions environments

• Added dual protection mechanism: filters invalid titles (None, float, empty strings) during data fetching, and adds type checks at function call sites

• Improved system stability, ensuring normal operation even when data sources return abnormal formats

Upgrade Notes (GitHub Fork Users):

• Must update: main.py

• Recommended to use minor version upgrade method: copy and replace the above files

2025/11/20 - v3.1.0

• New Personal WeChat Push Support: WeCom apps can push to personal WeChat, no need to install the WeCom APP

• Supports two message formats: markdown (WeCom group bot) and text (personal WeChat app)

• Added WEWORK_MSG_TYPE environment variable configuration, supporting GitHub Actions, Docker, docker compose and other deployment methods

• text mode automatically strips Markdown syntax, providing plain text push effect

• See the "Personal WeChat Push" configuration notes in Quick Start

Upgrade Notes (GitHub Fork Users):

• Must update: main.py, config/config.yaml

• Optional update: .github/workflows/crawler.yml (if using GitHub Actions deployment)

• Recommended to use minor version upgrade method: copy and replace the above files

2025/11/12 - v3.0.5

• Fixed email sending SSL/TLS port configuration logic error

• Optimized email service providers (QQ/163/126) to default to port 465 (SSL)

• New Docker environment variable support: core configuration items (enable_crawler, report_mode, push_window, etc.) support override via environment variables, solving the issue where NAS users' configuration file changes had no effect (see 🐳 Docker Deployment section)

2025/10/26 - mcp-v1.0.1

MCP Module Updates:

• Fixed date query parameter passing error

• Unified time parameter format across all tools

2025/10/31 - v3.0.4

• Resolved errors caused by overly long push content in Feishu, implemented batched push

2025/10/23 - v3.0.3

• Expanded ntfy error message display scope

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:

  • Added AI analysis server based on MCP (Model Context Protocol)

  • Supports 17 intelligent analysis tools: basic queries, intelligent retrieval, advanced analysis, RSS queries, 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 statistics, keyword co-occurrence)

  • Sentiment analysis, similar news lookup, intelligent summary generation

  • Historical related news retrieval, multi-mode search

• Update Notes:

  • This is a standalone AI analysis feature, does not affect existing push functionality

  • Optional to use, no need to upgrade existing deployments

2025/10/15 - v2.4.4

• Update Content:

  • Fixed ntfy push encoding issue + 1

  • Fixed push time window judgment issue

• Update Notes:

  • Recommended [Minor Version Upgrade]

2025/10/10 - v2.4.3

Thanks to nidaye996 for discovering the UX issue

• Update Content:

  • Refactored "Silent Push Mode" renamed to "Push Time Window Control", improving feature comprehension

  • Clarified push time window as an optional add-on feature, usable with all three push modes

  • Improved comments and documentation descriptions, making feature positioning clearer

• Update Notes:

  • This is only a refactor, upgrade is optional

2025/10/8 - v2.4.2

• Update Content:

  • Fixed ntfy push encoding issue

  • Fixed missing configuration file issue

  • Optimized ntfy push effect

  • Added GitHub Pages image segmented export feature

• Update Notes:

  • Recommended [Major Version Update]

2025/10/2 - v2.4.0

New ntfy Push Notifications

• 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 required (public server)

  • Open source and free (MIT license)

• Update Notes:

  • Recommended [Major Version Update]

2025/09/26 - v2.3.2

• Fixed the issue where email notification configuration check was omitted (#88)

Fix Notes:

• Resolved the issue where the system still prompted "no webhook configured" even when email notifications were correctly configured

2025/09/22 - v2.3.1

• New Email Push Feature: supports sending trending news reports to email

• Smart SMTP Detection: automatically identifies 10+ email service provider configurations including Gmail, QQ Mail, Outlook, NetEase Mail, etc.

• Beautiful HTML Format: email content uses the same HTML format as the web version, beautifully typeset, mobile-optimized

• Batch Send Support: supports multiple recipients, separated by commas to send to multiple people at once

• Custom SMTP: supports custom SMTP server and port

• Fixed Docker build network connection issue

Usage Notes:

• Applicable scenarios: suitable for users needing email archiving, team sharing, scheduled reports

• Supported email: Gmail, QQ Mail, Outlook/Hotmail, 163/126 Mail, Sina Mail, Sohu Mail, etc.

Update Notes:

• This update contains many changes; if upgrading, [Major Version Upgrade] is recommended

2025/09/17 - v2.2.0

• Added one-click news image saving feature, making it easy to share trending topics you care about

Usage Notes:

• Applicable scenarios: when you have enabled the web version feature (GitHub Pages) following the tutorial

• How to use: open the web link on your phone or computer, click the "Save as Image" button at the top of the page

• Actual effect: the system automatically turns the current news report into a beautiful image, saved to your phone's photo album or computer desktop

• Sharing convenience: you can directly send this image to friends, post it on social media, or share it in work groups, so others can see the important information you discovered

2025/09/13 - v2.1.2

• Resolved news push failures caused by DingTalk's push capacity limits (using batched push)

2025/09/04 - v2.1.1

• Fixed the issue where Docker could not run properly on certain architectures

• Officially released the official Docker image wantcat/trendradar, supporting multiple architectures

• Optimized Docker deployment process, no local build required for quick use

2025/08/30 - v2.1.0

Core Improvements:

• Push Logic Optimization: changed from "push on every execution" to "controllable push within time windows"

• Time Window Control: can set push time ranges, avoiding disturbances outside working hours

• Push Frequency Options: supports single push or multiple pushes within a time period

Update Notes:

• This feature is disabled by default, requires manually enabling 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 be sure to keep your webhooks safe, do not make them public, do not make them public, do not make them public

• If you deployed this project on GitHub via fork, please put webhooks in GitHub Secrets, not in config.yaml

• If you have already exposed webhooks or put them in config.yaml, it is recommended to delete and regenerate them

2025/08/06 - v2.0.3

• Optimized the GitHub Pages web version, making it mobile-friendly

2025/07/28 - v2.0.2

• Refactored code

• Resolved the issue where version numbers were easily forgotten to update

2025/07/27 - v2.0.1

Fixed Issues:

1. Docker shell script execution error caused by CRLF line endings

2. Logic issue where news sent was also empty when frequency_words.txt was empty

• After the fix, when you choose to leave frequency_words.txt empty, all news will be pushed, but subject to message push size limits, please make the following adjustments

  • Option 1: Disable mobile push, only use GitHub Pages deployment (this is the option that provides the most complete information, re-sorting all platform hot topics according to your custom hot search algorithm)

  • Option 2: Reduce push platforms, prioritize WeCom or Telegram, these two pushes have batched push functionality (because batched push affects push experience, and only these two platforms give very limited push capacity, so batched push was implemented out of necessity, but at least it ensures complete information)

  • Option 3: Can be combined with Option 2, choosing current or incremental mode can effectively reduce the content pushed at once

2025/07/17 - v2.0.0

Major Refactor:

• Configuration management refactored: all configuration is now managed through the config/config.yaml file (I still didn't split main.py, for your convenience in copy-upgrading)

• Run mode upgrade: supports three modes - daily (daily summary), current (current rankings), incremental (incremental monitoring)

• Docker support: complete Docker deployment solution, supports containerized operation

Configuration File Notes:

• config/config.yaml - main configuration file (app settings, crawler configuration, notification configuration, platform configuration, etc.)

• config/frequency_words.txt - keyword configuration (monitoring vocabulary settings)

2025/07/09 - v1.4.1

New Feature: Added incremental push (configure FOCUS_NEW_ONLY at the top of main.py). This switch only cares about new topics rather than sustained popularity, and only sends notifications when there is new content.

Fixed Issues: In certain cases, occasional formatting anomalies caused by special symbols in the news itself.

2025/06/23 - v1.3.0

WeCom and Telegram push messages have length limits, so I adopted a message splitting approach. Development documentation can be found at WeCom and Telegram

2025/06/21 - v1.2.1

For versions prior to this version, not only main.py needs to be copied and replaced, but crawler.yml also needs to be copied and replaced https://github.com/sansan0/TrendRadar/blob/master/.github/workflows/crawler.yml

2025/06/19 - v1.2.0

Thanks to claude research for organizing the APIs of various platforms, allowing me to quickly complete platform adaptation (though the code became more redundant~)

1. Supports telegram, WeCom, DingTalk push channels, supports multi-channel configuration and simultaneous push

2025/06/18 - v1.1.0

200 stars⭐ reached, continuing to celebrate for everyone~ Recently, with my "encouragement", quite a few people liked, shared, and recommended me on my official account, and I can see the specific account encouragement data in the backend. Many have become angel-round old fans (I've only been running my official account for a little over a month, though I registered it seven or eight years ago haha, so I got on early but started late). But since you didn't leave comments or private messages, I can't respond to each of you individually to thank you for your support, so I'll thank you all here!

1. Important update: added weights. The news you see now has the hottest and most attention-grabbing items at the top

2. Updated usage documentation, because many features have been added recently, and my previous usage documentation was lazily written (see the ⚙️ frequency_words.txt complete configuration tutorial below)

2025/06/16 - v1.0.0

1. Added a project new version update notification, enabled by default. To turn it off, change "FEISHU_SHOW_VERSION_UPDATE": True to False in main.py

2025/06/13+14

1. Removed compatibility code. For those who forked earlier, directly copying the code will show anomalies on the same day (will return to normal the next day)

2. Added a new news display at the bottom of feishu and html

2025/06/09

100 stars⭐ reached, writing a small feature to celebrate The frequency_words.txt file added a [Required Words] feature, using the + sign

1. Required word syntax is as follows:
   Tang Seng or Zhu Bajie must both appear in the title for the news to be included in the push

+唐僧
+猪八戒

2. Filter words have higher priority:
   If a filter word in the title matches "Tang Seng chanting sutras", then even if the required words contain "Tang Seng", it will not be displayed

+唐僧
!唐僧念经

2025/06/02

1. Web and Feishu messages support direct mobile jump to detailed news

2. Optimized display effect + 1

2025/05/26

1. Feishu message display effect optimization

✨ Core Features

Aggregated Hot Topics Across the Web

• Zhihu

• Douyin

• bilibili Hot Search

• Wallstreetcn

• Tieba

• Baidu Hot Search

• CLS Hot Topics

• The Paper

• ifeng.com

• Toutiao

• Weibo

Monitors 11 mainstream platforms by default, additional platforms can be added

💡 Detailed configuration tutorial at Configuration Details - Platform Configuration

RSS Feed Support (New in v4.5.0)

Supports RSS/Atom feed crawling, grouped and counted by keyword (same format as hot lists):

• Unified Format: RSS and hot lists use the same keyword matching and display format

• Simple Configuration: directly add RSS sources in config.yaml

• Merged Push: hot lists and RSS are merged into a single push message

• Freshness Filter: automatically filters out old articles exceeding a specified number of days, avoiding duplicate pushes. Supports global default days and per-source independent settings

💡 RSS uses the same frequency_words.txt for keyword filtering as hot lists

Visual Configuration Editor

Provides a web-based graphical configuration interface, no need to manually edit YAML files. All configuration items can be modified and exported through forms.

👉 Online Demo: https://sansan0.github.io/TrendRadar/

Smart Push Strategy

Three Push Modes:

💡 Quick Selection Guide:

• Don't want to see duplicate news → use incremental (incremental monitoring)

• Want to see complete ranking trends → use current (current rankings)

• Need daily summary reports → use daily (daily summary)

Detailed comparison and configuration tutorial at Configuration Details - Push Mode Explained

Additional Features (optional):

💡 Detailed configuration tutorials at How are pushed messages displayed? and When will I receive pushes?

Precise Content Filtering

Set personal keywords (e.g., AI, BYD, education policy) to only push relevant hot topics and filter out irrelevant information

💡 Basic Configuration Tutorial: Keyword Configuration - Basic Syntax

💡 Advanced Configuration Tutorial: Keyword Configuration - Advanced Configuration

💡 You can also skip filtering and push all hot topics in full (leave frequency_words.txt empty)

AI Smart News Filtering (New in v6.5.0)

Describe your interests in natural language, and AI automatically classifies news, replacing traditional keyword matching

• Natural Language Interest Description: Write down your focus areas in everyday language in ai_interests.txt — no need to learn keyword syntax

• Two-Stage Intelligent Processing: AI first extracts structured tags from the interest description, then batch-classifies and scores news by tags

• Score Threshold Control: Precisely control push quality via ai_filter.min_score, only pushing highly relevant news

• Automatic Fallback Guarantee: Automatically falls back to keyword matching when AI filtering fails, ensuring pushes are never interrupted

• Smart Tag Updates: When interests change, AI automatically evaluates the magnitude of change and decides between incremental or full re-classification

• Flexible Switching: filter.method supports both keyword (default) and ai modes, and Timeline can override by time period

• Time-Segmented Personalization: Different time periods can use different keyword files or AI interest descriptions. For example, use a "tech lexicon" for quick filtering in the morning, then switch to "finance interests" for deep AI filtering in the evening

# config.yaml 快速启用示例
filter:
  method: ai          # keyword（默认）| ai
ai_filter:
  min_score: 6         # 推送最低分数阈值（1-10）

💡 AI filtering shares the same model configuration as AI analysis/translation — configure ai.api_key only once

Hot Trend Analysis

Track news popularity changes in real time, so you know not just "what's trending" but also "how trends evolve"

• Timeline Tracking: Records the full time span of each news item from first appearance to last appearance

• Popularity Changes: Tracks ranking changes and appearance frequency of news across different time periods

• New Item Detection: Identifies newly emerging hot topics in real time, flagged with 🆕 for immediate alerts

• Persistence Analysis: Distinguishes between one-off hot topics and deep news that continues to develop

• Cross-Platform Comparison: Shows how the same news ranks across different platforms, revealing differences in media attention

💡 For push format details, see Message Style Guide

Personalized Hot Ranking Algorithm

No longer at the mercy of each platform's algorithm — TrendRadar re-organizes trending topics from across the web

💡 The three ratios can be adjusted, see Configuration Details - Hot Ranking Weight Adjustment

Multi-Channel Multi-Account Push

Supports WeCom (+ WeChat push solution), Feishu, DingTalk, Telegram, Email, ntfy, Bark, Slack, Generic Webhook (can connect to Discord, IFTTT, or any platform), delivering messages straight to your phone and inbox

💡 Detailed configuration tutorials see Push to Multiple Groups/Devices

AI Multi-Language Translation (New in v5.2.0)

Translate push content into any language, breaking down language barriers — whether reading domestic hot topics or subscribing to overseas news via RSS, you can easily get content in your native language

• One-Click Translation: Set ai_translation.enabled: true and the target language in config.yaml

• Multi-Language Support: Supports English, Korean, Japanese, French, and any other language

• Smart Batch Processing: Automatically translates in batches, reducing API calls and saving costs

• Custom Style: Customize translation style and terminology via ai_translation_prompt.txt

• Shared Model Configuration: Shares the model settings in the ai config section with the AI analysis feature

# config.yaml 快速启用示例
ai_translation:
  enabled: true
  language: "English"  # 翻译目标语言

💡 The translation feature shares model configuration with the AI analysis feature — configure ai.api_key once to use both features

RSS Source References: Below are some RSS subscription source collections you can pick from

• awesome-tech-rss - Blogs and media in tech, startup, and programming

• awesome-rss-feeds - RSS collection of mainstream news media from around the world

⚠️ Some overseas media content may involve sensitive topics, and AI models may refuse to translate. It's recommended to filter subscription sources based on your actual needs.

HTML Report Browser Enhancements (New in v6.6.0)

Open the pushed HTML report in a browser to automatically unlock enhanced features (email clients are unaffected):

• Wide Screen Mode: Desktop automatically switches to a 1200px wide layout, making full use of screen space

• Quick Tab Switching: Both keyword groups and independent display areas support Tab navigation, no more long-page scrolling

• Dark Mode: Toggle dark theme with one click, preferences remembered automatically

• Live Search: Press / to bring up the search box and instantly filter news headlines

• One-Click Copy: Hover over a news number to copy the title and link

• Keyboard Shortcuts: W wide screen, D dark mode, / search, ? view all shortcuts

💡 All enhancements are built on progressive enhancement — email clients still show the original 600px layout with zero regression

Flexible Storage Architecture (Major Update in v4.0.0)

Multiple Storage Backend Support:

• Remote Cloud Storage: Default for GitHub Actions environments, supports S3-compatible protocols (R2/OSS/COS, etc.), data stored in the cloud without polluting the repository

• Local SQLite Database: Default for Docker/local environments, data fully under your control

• Automatic Backend Selection: Intelligently switches storage method based on the runtime environment

💡 Detailed explanation see Where is data stored?

Multi-Platform Deployment

• GitHub Actions: Scheduled automatic crawling + remote cloud storage (requires periodic check-in to renew)

• Docker Deployment: Supports multi-architecture containerized operation, data stored locally

• Local Run: Run directly on Windows/Mac/Linux

AI Analysis Push (New in v5.0.0)

Uses AI large language models to perform deep analysis on pushed content, automatically generating hot topic insight reports

• Intelligent Analysis: Automatically analyzes hot trends, keyword popularity, cross-platform correlations, and potential impact

• Multiple Providers: Based on the LiteLLM unified interface, supports 100+ AI providers (DeepSeek, OpenAI, Gemini, Anthropic, local Ollama, etc.), with automatic fallback model switching

• Independent Analysis Mode: AI's analysis scope can differ from the push scope — pushes only send new messages (to avoid disturbance), but AI can analyze all of the day's news (to see the full trend)

• Flexible Push: Optionally push only raw content, only AI analysis, or both

• Custom Prompts: Customize analysis angles via config/ai_analysis_prompt.txt

💡 Detailed configuration tutorial see Let AI Analyze Hot Topics for Me

Independent Display Area (New in v5.0.0)

Provides complete hot ranking displays for specified platforms, unaffected by keyword filtering

• Complete Hot Rankings: Full display of specified platforms' hot rankings, ideal for users who want to see the complete ranking

• RSS Independent Display: RSS source content can be fully displayed without keyword restrictions

• AI Deep Analysis: Can independently enable AI trend analysis on the complete hot rankings without showing it in the push

• Flexible Configuration: Supports configuring display platforms, RSS sources, and maximum item count

💡 Detailed configuration tutorial see How is push content displayed? - Independent Display Area

AI Intelligent Analysis (New in v3.0.0)

An AI conversational analysis system based on the MCP (Model Context Protocol) protocol, letting you deeply mine news data using natural language

💡 Usage Tip: The AI feature requires local news data support

• The project includes test data, so you can try the feature immediately

• It's recommended to deploy and run the project yourself for more real-time data

See AI Intelligent Analysis

Web Deployment

After running, an index.html is generated in the root directory — that's your complete news report page.

Deployment Method: Click Use this template to create a repository, which can be deployed to static hosting platforms like Cloudflare Pages or GitHub Pages.

💡 Tip: Enabling GitHub Pages gives you an online access URL — go to repository Settings → Pages to enable it. Preview

⚠️ The original GitHub Actions auto-storage feature has been discontinued (that solution caused excessive load on GitHub servers, affecting platform stability).

☁️ Auto-Deploy to Cloudflare Pages (Optional · Faster Access in China)

GitHub Pages is slow to access from China; Cloudflare Pages offers friendlier access speeds. Once configured, every GitHub Actions run will automatically push the latest index.html to Cloudflare Pages with no manual steps needed.

Prerequisite: You've completed GitHub Actions Deployment and can successfully generate the web report.

① Create a Cloudflare Pages Project

Log in to Cloudflare Dashboard → Workers & Pages → Create → Pages → choose Upload assets (direct upload), enter a project name (e.g. trendradar, remember it), upload any file to complete the initial creation (it will be overwritten automatically by Actions later).

② Get API Token and Account ID

• API Token: Avatar in the top right → My Profile → API Tokens → Create Token → Create Custom Token, select permissions Account → Cloudflare Pages → Edit, copy the Token after creation (shown only once).

• Account ID: Found in the right sidebar of the Workers & Pages page (or in the bottom right of any domain's Overview page).

③ Add 3 Secrets to the GitHub Repository

Go to repository Settings → Secrets and variables → Actions → New repository secret, and add them one by one:

Once configured, the next GitHub Actions run will auto-deploy, and the access URL will be https://<project-name>.pages.dev.

💡 Note: If any of the three Secrets is missing, the Cloudflare deployment will be skipped automatically without affecting other features like news pushes; to bind a custom domain, set it up in the Pages project's Custom domains.

Reduce APP Dependency

Go from "being held hostage by algorithmic recommendations" to "proactively getting the information you want"

Who it's for: Investors, self-media creators, corporate PR, and ordinary users who care about current affairs

Typical scenarios: Stock market investment monitoring, brand reputation tracking, industry trend updates, lifestyle information

🚀 Quick Start

Reminder: It's recommended to check the latest official documentation first to make sure your configuration steps are up to date.

Choose the deployment method that suits you

Ⓐ Option 1: Docker Deployment (Recommended 🔥)

• Features: More stable than GitHub Actions, data stored locally (no cloud storage configuration needed)

• Best for: Users with their own server, NAS, or a computer that runs long-term

• Note: You need to read and understand the basic configuration flow below, then jump to the Docker tutorial for deployment.

Ⓑ Option 2: GitHub Actions Deployment (this section ⬇️)

• Features: Serverless, data stored in remote cloud storage (recommended configuration)

• Best for: Users without a server, leveraging GitHub's free resources

• Note: Cloud storage must be configured for the full experience, and periodic check-ins are required to renew

Ⓒ Option 3: Local Deployment (uv)

• Features: Runs directly on your machine, no Docker needed — great for development/debugging or users without a Docker environment

• Best for: Windows / Mac / Linux users (no need to pre-install Python; uv manages it automatically)

• Steps:

  1. Install uv (skip if already installed; no need to pre-install Python)

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # Windows (PowerShell)
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Clone and run

  git clone https://github.com/sansan0/TrendRadar.git
  cd TrendRadar
  uv sync          # 自动安装 Python 和项目依赖
  uv run python -m trendradar

  💡 Tip:

  • uv automatically manages the Python version, so you don't need to install Python manually

  • Windows users can also double-click setup-windows.bat to install dependencies in one go

  • Mac users can use bash setup-mac.sh

  • Before running, edit config/config.yaml to fill in push channel configuration — refer to the basic configuration flow below

1️⃣ Step 1: Get the Project Code

Click the green [Use this template] button in the top right of this repository page → select "Create a new repository".

⚠️ Reminder:

• Any mention of "Fork" in the documentation below can be understood as "Use this template"

• Using Fork may cause runtime issues, see Issue #606

2️⃣ Step 2: Set Up GitHub Secrets

In your forked repository, go to Settings > Secrets and variables > Actions > New repository secret

📌 Important Notes (please read carefully):

• One Name corresponds to one Secret: For each configuration item, click the "New repository secret" button once and fill in one "Name" and "Secret" pair

• Not seeing the value after saving is normal: For security reasons, when you edit after saving, you can only see the Name, not the Secret value

• Never invent your own names: The Secret Name must strictly use the names listed below (e.g. WEWORK_WEBHOOK_URL, FEISHU_WEBHOOK_URL, etc.) — you cannot modify or create new names, otherwise the system won't recognize them

• You can configure multiple platforms at once: The system will send notifications to all configured platforms

Configuration Example:

As shown in the image above, each row is one configuration item:

• Name: Must use the fixed names listed in the expandable sections below (e.g. WEWORK_WEBHOOK_URL)

• Secret: Fill in the actual content you obtained from the corresponding platform (e.g. Webhook URL, Token, etc.)

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: WEWORK_WEBHOOK_URL (copy and paste this name rather than typing it, to avoid typos)

• Secret: Your WeCom bot Webhook URL

Bot Setup Steps:

Mobile Setup:

1. Open the WeCom App → enter the target internal group chat

2. Click the "…" button in the top right → select "Message Push"

3. Click "Add" → enter "TrendRadar" as the name

4. Copy the Webhook URL, click Save, and configure the copied content into the GitHub Secret above

PC Setup is similar

Since this solution is based on WeCom's plugin mechanism, the push style is plain text (no markdown formatting), but it can push directly to personal WeChat without installing the WeCom App.

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: WEWORK_WEBHOOK_URL (copy and paste this name rather than typing it)

• Secret: Your WeCom app Webhook URL

• Name: WEWORK_MSG_TYPE (copy and paste this name rather than typing it)

• Secret: text

Setup Steps:

1. Complete the WeCom bot Webhook setup above

2. Add the WEWORK_MSG_TYPE Secret with the value text

3. Follow the image below to link your personal WeChat

4. Once configured, you can delete the WeCom App from your phone

Notes:

• Uses the same Webhook URL as the WeCom bot

• The difference is the message format: text is plain text, markdown is rich text (default)

• Plain text format automatically strips all markdown syntax (bold, links, etc.)

Note: The original "Feishu Bot Assistant (BotBuilder)" will be discontinued on June 30, 2026. Please use the group custom bot method below. Existing BotBuilder webhook URLs will stop working and need to be reconfigured.

If AI analysis is enabled, Feishu pushes may occasionally (about 5% probability) experience delays of a few minutes (presumably due to the platform's compliance review of AI-generated content).

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: FEISHU_WEBHOOK_URL (copy and paste this name rather than typing it)

• Secret: Your Feishu custom bot Webhook URL (format: https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxx)

Configuration Steps:

1. Enter the target group, click the More button in the top right of the group, and click Settings.

2. In the Settings panel on the right, click Group Bot.

3. In the Group Bot panel, click Add Bot.

4. In the Add Bot dialog, find and click Custom Bot.

5. Set the custom bot's avatar, name (e.g. "TrendRadar Hot Topic Monitor"), and description, then click Add.

6. Get the custom bot's webhook URL and click Done.

⚠️ Please keep this webhook URL safe — do not publish it on publicly accessible sites like GitHub or blogs, to avoid the URL being leaked and maliciously used to send spam.

7. Configure the copied Webhook URL into FEISHU_WEBHOOK_URL in GitHub Secrets.

💡 After configuration, you can click the bot image next to the group name to enter the custom bot details page and manage its configuration.

📖 Official documentation: Custom Bot Usage Guide

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: DINGTALK_WEBHOOK_URL (copy and paste this name rather than typing it)

• Secret: Your DingTalk bot Webhook URL

Bot Setup Steps:

1. Create the bot (PC only):

   • Open the DingTalk PC client and enter the target group chat

   • Click the group settings icon (⚙️) → scroll down to find "Bot" and click it

   • Select "Add Bot" → "Custom"

2. Configure the bot:

   • Set the bot name

   • Security Settings:

     • Custom Keyword: Set "热点"

3. Complete Setup:

   • Check the terms of service agreement → click "Done"

   • Copy the obtained Webhook URL

   • Configure the URL into DINGTALK_WEBHOOK_URL in GitHub Secrets

Note: The mobile app can only receive messages; it cannot create new bots.

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: TELEGRAM_BOT_TOKEN (copy and paste this name rather than typing it)

• Secret: Your Telegram Bot Token

• Name: TELEGRAM_CHAT_ID (copy and paste this name rather than typing it)

• Secret: Your Telegram Chat ID

Note: Telegram requires two Secrets — click the "New repository secret" button twice to add them separately

Bot Setup Steps:

1. Create the bot:

   • Search for @BotFather in Telegram (mind the capitalization; it has a blue badge checkmark and something like 37849827 monthly users — that's the official one; beware of lookalike accounts)

   • Send the /newbot command to create a new bot

   • Set the bot name (must end with "bot"; duplicate names are common, so you'll need to think hard about unique names)

   • Get the Bot Token (format like: 123456789:AAHfiqksKZ8WmR2zSjiQ7_v4TMAKdiHm9T0)

2. Get the Chat ID:

   Method 1: Via the official API

   • First send a message to your bot

   • Visit: https://api.telegram.org/bot<你的Bot Token>/getUpdates

   • Find the number in "chat":{"id":数字} in the returned JSON

   Method 2: Use a third-party tool

   • Search for @userinfobot and send /start

   • Get your user ID as the Chat ID

3. Configure in GitHub:

   • TELEGRAM_BOT_TOKEN: Fill in the Bot Token from step 1

   • TELEGRAM_CHAT_ID: Fill in the Chat ID from step 2

• Note: To prevent the mass email feature from being abused, the current group send shows all recipients' email addresses to each other.

• If you've never configured email sending like this before, it's not recommended to try

⚠️ Important Configuration Dependency: Email push requires the HTML report file. Make sure storage.formats.html is set to true in config/config.yaml:

storage:
  formats:
    sqlite: true
    txt: false
    html: true   # 必须启用，否则邮件推送会失败

If set to false, email push will error out with: 错误：HTML文件不存在或未提供: None

GitHub Secret Configuration (⚠️ Name must match exactly):

• Name: EMAIL_FROM (copy and paste this name rather than typing it)

• Secret: Sender email address

• Name: EMAIL_PASSWORD (copy and paste this name rather than typing it)

• Secret: Email password or authorization code

• Name: EMAIL_TO (copy and paste this name rather than typing it)

• Secret: Recipient email address (separate multiple recipients with English commas; can also be the same as EMAIL_FROM to send to yourself)

• Name: EMAIL_SMTP_SERVER (optional configuration, copy and paste this name)

• Secret: SMTP server address (can be left empty; the system will auto-detect)

• Name: EMAIL_SMTP_PORT (optional configuration, copy and paste this name)

• Secret: SMTP port (can be left empty; the system will auto-detect)

Note: Email push requires at least 3 required Secrets (EMAIL_FROM, EMAIL_PASSWORD, EMAIL_TO); the last two are optional

Supported Email Providers (SMTP configuration auto-detected):

Auto-detection: When using the above email providers, there is no need to manually configure EMAIL_SMTP_SERVER and EMAIL_SMTP_PORT; the system will detect them automatically.

Feedback:

• If you have successfully tested with another email provider, feel free to open an Issues ticket to let me know, and I will add it to the supported list.

• If any of the above email configurations are incorrect or not working, please also open an Issues ticket to report it and help improve the project.

Special thanks:

• Thanks to @DYZYD for contributing the 189 Mail (189.cn) configuration and completing the self-send/self-receive test (#291).

• Thanks to @longzhenren for contributing the Aliyun Mail (aliyun.com) configuration and completing the test (#344).

• Thanks to @ACANX for contributing the Yandex Mail (yandex.com) configuration and completing the test (#663).

• Thanks to @Sleepy-Tianhao for contributing the iCloud Mail (icloud.com) configuration and completing the test (#728).

Common email provider settings:

QQ Mail:

1. Log in to QQ Mail web version → Settings → Account

2. Enable POP3/SMTP service

3. Generate an authorization code (16-character alphanumeric)

4. Fill in EMAIL_PASSWORD with the authorization code, not your QQ password

Gmail:

1. Enable two-step verification

2. Generate an app-specific password

3. Fill in EMAIL_PASSWORD with the app-specific password

163/126 Mail:

1. Log in to the web version → Settings → POP3/SMTP/IMAP

2. Enable SMTP service

3. Set up a client authorization code

4. Fill in EMAIL_PASSWORD with the authorization code

Advanced configuration: If auto-detection fails, you can manually configure SMTP:

• EMAIL_SMTP_SERVER: e.g., smtp.gmail.com

• EMAIL_SMTP_PORT: e.g., 587 (TLS) or 465 (SSL)

If there are multiple recipients (note: separated by English commas):

• EMAIL_TO="user1@example.com,user2@example.com,user3@example.com"

Two ways to use:

Method 1: Free to use (recommended for beginners) 🆓

Features:

• ✅ No account registration required, ready to use immediately

• ✅ 250 messages per day (enough for 90% of users)

• ✅ The Topic name is the "password" (choose a name that is hard to guess)

• ⚠️ Messages are not encrypted, not suitable for sensitive information, but fine for the non-sensitive information in this project

Quick start:

1. Download the ntfy app:

   • Android: Google Play / F-Droid

   • iOS: App Store

   • Desktop: visit ntfy.sh

2. Subscribe to a topic (choose a name that is hard to guess):

   建议格式：trendradar-{你的名字缩写}-{随机数字}
   
   不能使用中文
   
   ✅ 好例子：trendradar-zs-8492
   ❌ 坏例子：news、alerts（太容易被猜到）

3. Configure GitHub Secrets (⚠️ The Name must match exactly):

   • Name: NTFY_TOPIC (please copy and paste this name, do not type it manually)

   • Secret (value): fill in the topic name you just subscribed to

   • Name: NTFY_SERVER_URL (optional configuration, please copy and paste this name)

   • Secret (value): leave blank (defaults to ntfy.sh)

   • Name: NTFY_TOKEN (optional configuration, please copy and paste this name)

   • Secret (value): leave blank

   Note: ntfy requires at least 1 required Secret (NTFY_TOPIC); the last two are optional configurations.

4. Test:

   curl -d "测试消息" ntfy.sh/你的主题名称

Method 2: Self-hosted (full privacy control) 🔒

Suitable for: users with a server, who pursue complete privacy, and have strong technical skills

Advantages:

• ✅ Fully open source (Apache 2.0 + GPLv2)

• ✅ Full control over your data

• ✅ No restrictions at all

• ✅ Zero cost

One-click deployment with Docker:

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  # 自托管可用简单名称
NTFY_TOKEN: tk_your_token  # 可选：启用访问控制

Subscribe in the app:

• Click "Use another server"

• Enter your server address

• Enter the topic name

• (Optional) Enter login credentials

FAQ:

250 messages per day is enough for most users. With a fetch every 30 minutes, that's about 48 pushes per day, which is more than sufficient.

If you choose a random, sufficiently long name (e.g., trendradar-zs-8492-news), brute-forcing is practically impossible:

• ntfy has strict rate limiting (1 request per second)

• 64 character choices (A-Z, a-z, 0-9, _, -)

• A 10-character random string has 64^10 possibilities (would take years to crack)

Recommended choice:

Related links:

• ntfy official documentation

• Self-hosting tutorial

• GitHub repository

GitHub Secret configuration (⚠️ The Name must match exactly):

• Name: BARK_URL (please copy and paste this name, do not type it manually)

• Secret (value): your Bark push URL

About Bark:

Bark is a free, open-source push tool for iOS, characterized by being simple, fast, and ad-free.

How to use:

Method 1: Use the official server (recommended for beginners) 🆓

1. Download the Bark App:

   • iOS: App Store

2. Get the push URL:

   • Open the Bark App

   • Copy the push URL displayed on the home page (format: https://api.day.app/your_device_key)

   • Configure the URL in GitHub Secrets as BARK_URL

Method 2: Self-hosted server (full privacy control) 🔒

Suitable for: users with a server, who pursue complete privacy, and have strong technical skills

One-click deployment with Docker:

docker run -d \
  --name bark-server \
  -p 8080:8080 \
  finab/bark-server

Configure TrendRadar:

BARK_URL: http://your-server-ip:8080/your_device_key

Notes:

• ✅ Bark uses APNs push, with a maximum of 4KB per message

• ✅ Supports automatic batched push, no need to worry about overly long messages

• ✅ Push format is plain text (Markdown syntax is automatically removed)

• ⚠️ iOS platform only

Related links:

• Bark official website

• Bark GitHub repository

• Bark Server self-hosting tutorial

GitHub Secret configuration (⚠️ The Name must match exactly):

• Name: SLACK_WEBHOOK_URL (please copy and paste this name, do not type it manually)

• Secret (value): your Slack Incoming Webhook URL

About Slack:

Slack is a team collaboration tool. Incoming Webhooks can push messages to Slack channels.

Setup steps:

Step 1: Create a Slack App

1. Visit the Slack API page:

   • Open https://api.slack.com/apps?new_app=1

   • If not logged in, log in to your Slack workspace first

2. Choose the creation method:

   • Click "From scratch"

3. Fill in the App information:

   • App Name: enter an app name (e.g., TrendRadar or 热点新闻监控)

   • Workspace: select your workspace from the dropdown list

   • Click the "Create App" button

Step 2: Enable Incoming Webhooks

1. Navigate to Incoming Webhooks:

   • Find and click "Incoming Webhooks" in the left menu

2. Enable the feature:

   • Find the "Activate Incoming Webhooks" toggle

   • Switch the toggle from OFF to ON

   • The page will automatically refresh to show new configuration options

Step 3: Generate the Webhook URL

1. Add a new Webhook:

   • Scroll to the bottom of the page

   • Click the "Add New Webhook to Workspace" button

2. Select the target channel:

   • An authorization page will pop up

   • Select the channel to receive messages from the dropdown list (e.g., #热点新闻)

   • ⚠️ To select a private channel, you must join that channel first

3. Authorize the app:

   • Click the "Allow" button to complete authorization

   • The system will automatically redirect back to the configuration page

Step 4: Copy and save the Webhook URL

1. View the generated URL:

   • In the "Webhook URLs for Your Workspace" section

   • You will see the newly generated Webhook URL

   • Format: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

2. Copy the URL:

   • Click the "Copy" button to the right of the URL

   • Or manually select and copy the URL

3. Configure in TrendRadar:

   • GitHub Actions: add the URL to GitHub Secrets as SLACK_WEBHOOK_URL

   • Local testing: fill in the URL in the slack_webhook_url field of config/config.yaml

   • Docker deployment: add the URL to the SLACK_WEBHOOK_URL variable in the docker/.env file

Notes:

• ✅ Supports Markdown format (automatically converted to Slack mrkdwn)

• ✅ Supports automatic batched push (4KB per batch)

• ✅ Suitable for team collaboration, centralized message management

• ⚠️ The Webhook URL contains a secret key; never make it public

Message format preview:

*[第 1/2 批次]*

📊 *热点词汇统计*

🔥 *[1/3] AI ChatGPT* : 2 条

  1. [百度热搜] 🆕 ChatGPT-5正式发布 *[1]* - 09时15分 (1次)

  2. [今日头条] AI芯片概念股暴涨 *[3]* - [08时30分 ~ 10时45分] (3次)

Related links:

• Slack Incoming Webhooks official documentation

• Slack API app management

GitHub Secret configuration (⚠️ The Name must match exactly):

• Name: GENERIC_WEBHOOK_URL (please copy and paste this name, do not type it manually)

• Secret (value): your Webhook URL

• Name: GENERIC_WEBHOOK_TEMPLATE (optional configuration, please copy and paste this name)

• Secret (value): JSON template string, supports {title} and {content} placeholders

About the generic Webhook:

The generic Webhook supports any platform that accepts HTTP POST requests, including but not limited to:

• Discord: push to channels via Webhook

• Matrix: push via Webhook bridge

• IFTTT: trigger automation flows

• Self-hosted services: any custom service that supports Webhooks

Configuration examples:

Discord configuration

1. Get the Webhook URL:

   • Go to Discord server settings → Integrations → Webhooks

   • Create a new Webhook and copy the URL

2. Configure the template:

   {"content": "{content}"}

3. GitHub Secret configuration:

   • GENERIC_WEBHOOK_URL: Discord Webhook URL

   • GENERIC_WEBHOOK_TEMPLATE: {"content": "{content}"}

Custom templates

The template supports two placeholders:

• {title} - message title

• {content} - message content

Template examples:

# 默认格式（留空时使用）
{"title": "{title}", "content": "{content}"}

# Discord 格式
{"content": "{content}"}

# 自定义格式
{"text": "{content}", "username": "TrendRadar"}

Notes:

• ✅ Supports Markdown format (consistent with WeCom format)

• ✅ Supports automatic batched push

• ✅ Supports multiple account configuration (separated by ;)

• ⚠️ The template must be valid JSON format

• ⚠️ Different platforms have different message format requirements; please refer to the target platform's documentation

3️⃣ Step 3: Manually test the news push

⚠️ Reminder:

• After completing Steps 1-2, test immediately! After a successful test, adjust the configuration as needed (Step 4)

• Go to your own project, not this project!

How to find your Actions page:

• Method 1: open your forked project's homepage and click the Actions tab at the top

• Method 2: directly visit https://github.com/your-username/TrendRadar/actions

Example comparison:

• ❌ Author's project: https://github.com/sansan0/TrendRadar/actions

• ✅ Your project: https://github.com/your-username/TrendRadar/actions

Test steps:

1. Go to your project's Actions page

2. Find "Get Hot News" (must be exactly this text), click into it, then click the "Run workflow" button on the right to run it

   • If you can't see this text, refer to #109 to resolve it

3. In about 3 minutes, the message will be pushed to the platform you configured

⚠️ Reminder:

• Don't run manual tests too frequently to avoid triggering GitHub Actions limits

• After clicking Run workflow, you need to refresh the browser page to see the new run record

4️⃣ Step 4: Configuration instructions (optional)

The default configuration works out of the box. If you want personalized adjustments, understanding the following files is all you need:

👉 Detailed configuration tutorial: Configuration details

5️⃣ Step 5: Remote cloud storage & check-in configuration

v4.0.0 important change: an "activity detection" mechanism has been introduced; GitHub Actions requires periodic check-ins to keep running.

• Run cycle: valid for 7 days; once the countdown ends, the service will automatically suspend.

• Renewal method: manually trigger the "Check In" workflow on the Actions page to reset the 7-day validity period.

• Operation path: Actions → Check In → Run workflow

• Design philosophy:

  • If you forget to check in for 7 days, perhaps this news isn't a real necessity for you. A timely pause can help you step away from the information feed and give your brain some breathing room.

  • GitHub Actions is a valuable public computing resource. The check-in mechanism is designed to avoid wasted compute cycles and ensure resources are allocated to users who are truly active and in need. Thank you for your understanding and support.

About remote cloud storage configuration (choose based on your deployment method):

• GitHub Actions users:

  • Current state: each Actions run is a fresh environment and does not persist files. If you don't configure cloud storage, the project will run in lightweight mode (no incremental push, no history tracking).

  • Recommendation: configure remote cloud storage for the full experience.

• Docker / local users:

  • Current state: data is saved locally on the hard drive by default.

  • Recommendation: cloud storage is optional and can serve as off-site backup.

⚠️ Prerequisites (important):

According to Cloudflare platform rules, enabling R2 requires binding a payment method.

• Purpose: for identity verification only (Verify Only), no charges will be incurred.

• Payment: supports dual-currency credit cards or China-region PayPal.

• Usage: R2's free tier (10GB storage/month) is more than enough for this project's daily operation; no need to worry about costs.

GitHub Secret configuration (4 items required):

Optional configuration:

💡 More storage configuration options: see Where is the data stored?

Detailed steps (obtaining credentials):

1. Go to the R2 overview:

   • Log in to Cloudflare Dashboard.

   • Find and click R2对象存储 in the left sidebar.

2. Create a bucket:

   • Click 概述

   • Click 创建存储桶 (Create bucket) in the top-right corner.

   • Enter a name (e.g., trendradar-data) and click 创建存储桶.

3. Create an API token:

   • Go back to the 概述 page.

   • Click Account Details in the bottom-right corner, find and click Manage (Manage R2 API Tokens).

   • You will also see S3 API: https://<account-id>.r2.cloudflarestorage.com (this is the S3_ENDPOINT_URL)

   • Click 创建 Account APl 令牌.

   • ⚠️ Key settings:

     • Token name: fill in anything (e.g., github-action-write).

     • Permissions: select 管理员读和写.

     • Specified bucket: for security, it is recommended to select 仅适用于指定存储桶 and select your bucket (e.g., trendradar-data).

   • Click 创建 API 令牌 and immediately copy the displayed Access Key ID and Secret Access Key (they are only shown once!).

6️⃣ Step 6: Enable AI analysis push

This is the core feature of v5.0.0, letting AI summarize and analyze the news for you. We recommend trying it.

Configuration method: Add the following to GitHub Secrets (or .env / config.yaml):

• AI_API_KEY: your API Key (supports DeepSeek, OpenAI, etc.)

• AI_PROVIDER: provider name (e.g., deepseek, openai)

That's it — no complex deployment needed. The next time a push happens, you'll see the intelligent analysis report.

7️⃣ Step 7: 🎉 Deployment successful!

Congratulations! You can now start enjoying the efficient information flow brought by TrendRadar.

💬 Join the Community: Follow the official account「硅基茶水间」to share your usage tips and advanced tricks.

8️⃣ Step 8: Advanced: Choose Your AI Assistant

TrendRadar offers two AI usage modes to meet different needs:

👉 Conclusion: Start with AI Analysis Push for daily needs; if you're a data analyst or need deep digging, try AI Smart Analysis.

⚙️ Configuration Details

📖 Reminder: This chapter provides detailed configuration instructions. It's recommended to complete the basic setup in Quick Start first, then come back to check detailed options as needed.

1. Which platforms do I want to monitor?

Configuration Location: The platforms section of config/config.yaml

The news data for this project comes from newsnow. You can click the website, click [More], and check whether the platform you want is available.

For specific additions, visit the project source code, and modify the platforms configuration in the config/config.yaml file based on the file names there:

platforms:
  enabled: true                       # 是否启用热榜平台抓取
  sources:
    - id: "toutiao"
      name: "今日头条"
    - id: "baidu"
      name: "百度热搜"
    - id: "wallstreetcn-hot"
      name: "华尔街见闻"
    # 添加更多平台...

💡 Shortcut: If you can't read the source code, you can copy the platform configuration summary compiled by others.

⚠️ Note: More platforms isn't always better. It's recommended to choose 10-15 core platforms. Too many platforms can cause information overload and actually reduce the user experience.

2. What content do I care about?

Tell the bot what you want to see in the frequency_words.txt file, and it will keep an eye on it for you. It supports regular words, required words, filter words, and more.

2.1 Basic Syntax

Configuration Location: config/frequency_words.txt

1. Regular Keywords - Basic Matching

华为
OPPO
苹果

Purpose: News headlines containing any one of these words will be captured.

2. Required Words +word - Restrict Scope

华为
OPPO
+手机

Purpose: Must include both the regular word and the required word to be captured.

3. Filter Words !word - Exclude Noise

苹果
华为
!水果
!价格

Purpose: News containing filter words will be directly excluded, even if they contain keywords.

4. Quantity Limit @number - Control Display Count (new in v3.2.0)

特斯拉
马斯克
@5

Purpose: Limit the maximum number of news items displayed for that keyword group.

Configuration Priority: @number > Global config > No limit

5. Global Filter [GLOBAL_FILTER] - Globally Exclude Specified Content (new in v3.5.0)

[GLOBAL_FILTER]
广告
推广
营销
震惊
标题党

[WORD_GROUPS]
科技
AI

华为
鸿蒙
!车

Purpose: Filter news containing specified words in all cases, with the highest priority.

Use Cases:

• Filter low-quality content: shocking, clickbait, leaks, etc.

• Filter marketing content: ads, promotions, sponsorships, etc.

• Filter specific topics: entertainment, gossip (as needed)

Filter Priority: Global filter > In-group filter (!) > Group matching

Section Description:

• [GLOBAL_FILTER]: Global filter section; words included here are filtered in all cases

• [WORD_GROUPS]: Word group section; keeps the existing syntax (!, +, @)

• If no section markers are used, everything is treated as word groups by default (backward compatible)

Matching Examples:

[GLOBAL_FILTER]
广告

[WORD_GROUPS]
科技
AI

• ❌ "广告：最新科技产品发布" ← Contains the global filter word "广告", directly rejected

• ✅ "科技公司发布AI新产品" ← Does not contain global filter words, matches the "科技" group

• ✅ "AI技术突破引发关注" ← Does not contain global filter words, matches "AI" in the "科技" group

Notes:

• Global filter words should be used with caution to avoid over-filtering and missing valuable content

• It's recommended to keep global filter words within 5-15

• For filtering specific groups, prefer using in-group filter words (! prefix)

6. Regular Expressions /pattern/ - Precise Matching Mode (new in v4.7.0)

Regular keywords use substring matching, which is convenient in Chinese contexts but can cause false matches in English. For example, ai will match the ai in training.

Using the regular expression syntax /pattern/ enables precise matching:

/(?<![a-z])ai(?![a-z])/
人工智能

Purpose: Match using regular expressions, supporting all Python regex syntax.

Common Regex Patterns:

Matching Examples:

# 配置
/(?<![a-z])ai(?![a-z])/
人工智能

• ✅ "AI is the future" ← Matches the standalone "AI"

• ✅ "你好ai这里" ← Chinese characters before and after, matches "ai"

• ✅ "人工智能发展迅速" ← Matches "人工智能"

• ❌ "Resistance training is important" ← The "ai" in "training" does not match

• ❌ "The maid cleaned the room" ← The "ai" in "maid" does not match

Combined Usage:

# 正则 + 普通词 + 过滤词
/\bai\b/
人工智能
机器学习
!广告

Notes:

• Regular expressions automatically enable case-insensitive matching (re.IGNORECASE)

• JavaScript-style syntax like /pattern/i is supported (flags are ignored since case-insensitivity is enabled by default)

• Invalid regex syntax is treated as a regular word

• Regex can be used for regular words, required words (+), and filter words (!)

💡 Can't write regex? Let AI generate it for you!

If you're not familiar with regular expressions, you can directly ask ChatGPT / Gemini / DeepSeek to generate one for you. Just tell the AI:

I need a Python regular expression to match the English word "ai" but not the "ai" in "training". Please just give me the regex in /pattern/ format, no extra explanation needed.

The AI will give you something like: /(?<![a-zA-Z])ai(?![a-zA-Z])/

7. Display Name => 备注 - Custom Display Text (new in v4.7.0)

Regular expressions may not look friendly in push messages and HTML pages. Use the => 备注 syntax to set a display name:

/(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
人工智能

Purpose: Push messages and HTML pages display "AI 相关" instead of the complex regex.

Syntax Format:

# 正则 + 显示名称
/pattern/ => 显示名称
/pattern/i => 显示名称    # 支持 flags 写法（flags 被忽略）
/pattern/=>显示名称       # => 两边空格可选

# 普通词 + 显示名称
deepseek => DeepSeek 动态

Matching Examples:

# 配置
/(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
人工智能

Notes:

• The display name only needs to be written on the first word of the group

• If multiple words in a group have display names, the first one is used

• When no display name is set, all words in the group are automatically concatenated

🔗 Word Group Feature - The Important Role of Blank Line Separation

Core Rule: Use blank lines to separate different word groups; each group is counted independently.

Example Configuration:

iPhone
华为
OPPO
+发布

A股
上证
深证
+涨跌
!预测

世界杯
欧洲杯
亚洲杯
+比赛

Group Explanation and Matching Effects:

Group 1 - New Phone Categories:

• Keywords: iPhone、华为、OPPO

• Required word: 发布

• Effect: Must include a phone brand name and also include "发布"

Matching Examples:

• ✅ "iPhone 15正式发布售价公布" ← Has "iPhone"+"发布"

• ✅ "华为Mate60系列发布会直播" ← Has "华为"+"发布"

• ✅ "OPPO Find X7发布时间确定" ← Has "OPPO"+"发布"

• ❌ "iPhone销量创新高" ← Has "iPhone" but lacks "发布"

Group 2 - Stock Market:

• Keywords: A股、上证、深证

• Required word: 涨跌

• Filter word: 预测

• Effect: Focuses on actual stock market movements, excludes prediction content

Matching Examples:

• ✅ "A股今日大幅涨跌分析" ← Has "A股"+"涨跌"

• ✅ "上证指数涨跌幅创新高" ← Has "上证"+"涨跌"

• ❌ "专家预测A股涨跌趋势" ← Has "A股"+"涨跌" but contains "预测"

Group 3 - Football Events:

• Keywords: 世界杯、欧洲杯、亚洲杯

• Required word: 比赛

• Effect: Only focuses on match-related news

📝 Configuration Tips

1. From Broad to Narrow

# 第一步：先用宽泛关键词测试
人工智能
AI
ChatGPT

# 第二步：发现误匹配后，加入必须词限定
人工智能
AI
ChatGPT
+技术

# 第三步：发现干扰内容后，加入过滤词
人工智能
AI
ChatGPT
+技术
!广告
!培训

2. Avoid Over-Complexity

❌ Not Recommended: A group with too many words

华为
OPPO
苹果
三星
vivo
一加
魅族
+手机
+发布
+销量
!假货
!维修
!二手

✅ Recommended: Split into multiple precise groups

华为
OPPO
+新品

苹果
三星
+发布

手机
销量
+市场

2.2 Advanced Configuration (new in v3.2.0)

Keyword Sorting Priority

Configuration Location: config/config.yaml

report:
  sort_by_position_first: false  # 排序优先级配置

Example: Config order A, B, C; hot counts A(3 items), B(10 items), C(5 items)

• false: B(10 items) → C(5 items) → A(3 items)

• true: A(3 items) → B(10 items) → C(5 items)

Global Display Quantity Limit

report:
  max_news_per_keyword: 10  # 每个关键词最多显示10条（0=不限制）

Docker Environment Variables:

SORT_BY_POSITION_FIRST=true
MAX_NEWS_PER_KEYWORD=10

Comprehensive Example:

# config.yaml
report:
  sort_by_position_first: true   # 按配置顺序优先
  max_news_per_keyword: 10       # 全局默认每个关键词最多10条

# frequency_words.txt
特斯拉
马斯克
@20              # 重点关注，显示20条（覆盖全局配置）

华为            # 使用全局配置，显示10条

比亚迪
@5               # 限制5条

Final Effect: Displayed in config order: 特斯拉(20 items) → 华为(10 items) → 比亚迪(5 items)

3. Which push mode should I choose?

Configuration Location: The report.mode section of config/config.yaml

report:
  mode: "daily"  # 可选: "daily" | "incremental" | "current"

Detailed Comparison Table

Example of Actual Push Effects

Assume you monitor the "苹果" keyword, executed once per hour:

Explanation:

• daily: Cumulatively displays all news of the day (A, B, C all retained)

• current: Displays news on the current ranking (ranking changes, News D enters, News A drops off)

• incremental: Only pushes newly appeared news (avoids duplicate interruptions)

Common Questions

💡 Running into this issue? 👉 "The news output after the first execution still appears in the next hour's execution"

• Cause: You may have chosen the daily (daily summary) or current (current ranking) mode

• Solution: Switch to incremental (incremental monitoring) mode, which only pushes new content

⚠️ Important Note for Incremental Mode

Users who chose incremental (incremental monitoring) mode, please note:

📌 Incremental mode only pushes when there is new matching news

If you haven't received pushes for a long time, it may be because:

1. No new hot topics matching your keywords appeared in the current time period

2. The keyword configuration is too strict or too broad

3. The number of monitored platforms is too small

Solutions:

• Option 1: 👉 Optimize keyword configuration - Adjust keyword precision, add or modify monitored words

• Option 2: Switch push mode - Use current or daily mode to receive scheduled pushes

• Option 3: 👉 Add monitoring platforms - Add more news platforms to expand information sources

4. Adjust the Hot Topic Algorithm

Configuration Location: The advanced.weight section of config/config.yaml

advanced:
  weight:
    rank: 0.6           # 排名权重
    frequency: 0.3      # 频次权重
    hotness: 0.1        # 热度权重

The current default configuration is a balanced configuration.

Two Core Scenarios

Real-time Hot Topic Tracking:

advanced:
  weight:
    rank: 0.8           # 主要看排名
    frequency: 0.1      # 不太在乎持续性
    hotness: 0.1

Target Audience: Self-media bloggers, marketers, users who want to quickly understand the hottest topics right now

Deep Topic Tracking:

advanced:
  weight:
    rank: 0.4           # 适度看排名
    frequency: 0.5      # 重视当天内的持续热度
    hotness: 0.1

Target Audience: Investors, researchers, journalists, users who need in-depth trend analysis

How to Adjust

1. The three numbers must add up to 1.0

2. Increase whichever matters more to you: increase rank if you care about ranking, increase frequency if you care about persistence

3. It's recommended to adjust by only 0.1-0.2 at a time, then observe the results

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

5. What do the messages I receive look like?

Push Example

📊 Hot Keyword Statistics

🔥 [1/3] AI ChatGPT : 2 items

1. [百度热搜] 🆕 ChatGPT-5正式发布 [1] - 09:15 (1 time)

2. [今日头条] AI芯片概念股暴涨 [3] - [08:30 ~ 10:45] (3 times)

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

📈 [2/3] 比亚迪 特斯拉 : 2 items

1. [微博] 🆕 比亚迪月销量破纪录 [2] - 10:20 (1 time)

2. [抖音] 特斯拉降价促销 [4] - [07:45 ~ 09:15] (2 times)

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

📌 [3/3] A股 股市 : 1 item

1. [华尔街见闻] A股午盘点评分析 [5] - [11:30 ~ 12:00] (2 times)

🆕 New hot news this round (2 items total)

百度热搜 (1 item):

1. ChatGPT-5正式发布 [1]

微博 (1 item):

1. 比亚迪月销量破纪录 [2]

Update time: 2025-01-15 12:30:15

Message Format Description

6. Docker Deployment

Image Description:

TrendRadar provides two independent Docker images. You can choose to deploy based on your needs:

💡 Suggestion:

• Only need push functionality: deploy only the wantcat/trendradar image

• Need AI analysis functionality: deploy both images

Method 1: Using docker compose (Recommended)

1. Create the project directory and configuration:

   # 克隆项目到本地
   git clone https://github.com/sansan0/TrendRadar.git
   cd TrendRadar

   💡 Note: The key directory structure required for Docker deployment is as follows:

当前目录/
├── config/
│   ├── config.yaml                 # 核心功能配置（必需）
│   ├── frequency_words.txt         # 关键词配置（必需）
│   ├── timeline.yaml               # 时间线配置
│   ├── ai_analysis_prompt.txt      # AI 分析提示词（可选）
│   ├── ai_translation_prompt.txt   # AI 翻译提示词（可选）
│   ├── ai_interests.txt            # AI 兴趣过滤配置（可选）
│   ├── ai_filter/                  # AI 过滤相关提示词
│   │   ├── prompt.txt
│   │   ├── extract_prompt.txt
│   │   └── update_tags_prompt.txt
│   └── custom/                     # 用户自定义配置（可选）
│       ├── ai/                     # 自定义 AI 提示词
│       └── keyword/                # 自定义关键词文件
└── docker/
    ├── .env                        # 敏感信息 + Docker 特有配置
    └── docker-compose.yml          # Docker Compose 编排文件

2. Configuration File Description:

   Configuration Division of Labor Principle (v4.6.0 Optimization):

   File	Purpose	Modification Frequency	Description
   config/config.yaml	Core functional configuration	Low	Global behavior control such as report mode, push settings, storage format, push window, AI analysis toggle, platform enablement
   config/frequency_words.txt	Keyword configuration	High	Set the hot topics you care about, supports advanced syntax like grouping, regex, aliases
   config/timeline.yaml	Timeline configuration	Low	Controls the display and filtering rules of the news timeline
   config/ai_analysis_prompt.txt	AI analysis prompt	Medium	Customize the role definition and output format of AI analysis (v5.0.0+)
   config/ai_translation_prompt.txt	AI translation prompt	Low	Customize the prompt template for AI translation
   config/ai_interests.txt	AI interest filtering	Medium	Define rules for AI to automatically filter news based on interests
   config/ai_filter/	AI filtering prompts	Low	Internal prompts for the AI filtering module (generally no need to modify)
   config/custom/	User custom extensions	As needed	custom/ai/ holds custom AI prompts, custom/keyword/ holds custom keyword files
   docker/.env	Sensitive information + Docker-specific configuration	Low	webhook URLs, API Key, S3 keys, scheduled tasks, etc. Not tracked by git

   💡 Division of Labor Key Points:

   • Functional behavior → Modify config.yaml (e.g., enable/disable a platform, adjust push mode)

   • Content of interest → Modify frequency_words.txt (e.g., add new keywords of interest)

   • AI output style → Modify ai_analysis_prompt.txt or ai_translation_prompt.txt

   • Keys and credentials → Modify docker/.env (API Key, Webhook URL and other sensitive information go here)

   • Personalized extensions → Use the config/custom/ directory to avoid default configurations being overwritten by upgrades

   💡 Configuration changes take effect: After modifying config.yaml, run docker compose up -d to restart the container and the changes take effect

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

   Environment variables in the .env file override the corresponding configuration in config.yaml:

   Environment Variable	Corresponding Configuration	Example Value	Description
   WEBSERVER_PORT	-	8080	Web server port
   FEISHU_WEBHOOK_URL	notification.channels.feishu.webhook_url	https://...	Feishu Webhook (multiple accounts separated by ;)
   AI_ANALYSIS_ENABLED	ai_analysis.enabled	true / false	Whether to enable AI analysis (new in v5.0.0)
   AI_API_KEY	ai.api_key	sk-xxx...	AI API Key (shared by ai_analysis and ai_translation)
   AI_PROVIDER	ai.provider	deepseek / openai / gemini	AI provider
   S3_*	storage.remote.*	-	Remote storage configuration (5 parameters)

   Configuration priority: Environment variables > config.yaml

   How to use:

   • Modify the .env file and fill in the required configuration

   • Or add directly in the "Environment Variables" section of the NAS/Synology Docker management interface

   • Restart the container for changes to take effect: docker compose up -d

3. Start the service:

   Option A: Start all services (push + AI analysis)

   # 拉取最新镜像
   docker compose pull
   
   # 启动所有服务（trendradar + trendradar-mcp）
   docker compose up -d

   Option B: Start only the news push service

   # 只启动 trendradar（定时抓取和推送）
   docker compose pull trendradar
   docker compose up -d trendradar

   Option C: Start only the MCP AI analysis service

   # 只启动 trendradar-mcp（提供 AI 分析接口）
   docker compose pull trendradar-mcp
   docker compose up -d trendradar-mcp

   💡 Tip:

   • Most users only need to start trendradar to get news push functionality

   • Only start trendradar-mcp when you need to use ChatGPT/Gemini for AI conversation analysis

   • The two services are independent of each other and can be flexibly combined as needed

4. Check running status:

   # 查看新闻推送服务日志
   docker logs -f trendradar
   
   # 查看 MCP AI 分析服务日志
   docker logs -f trendradar-mcp
   
   # 查看所有容器状态
   docker ps | grep trendradar
   
   # 停止特定服务
   docker compose stop trendradar      # 停止推送服务
   docker compose stop trendradar-mcp  # 停止 MCP 服务

Method 2: Local Build (Developer Option)

If you need to customize the code or build your own image:

# 克隆项目
git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar

# 修改配置文件
vim config/config.yaml
vim config/frequency_words.txt

# 使用构建版本的 docker compose
cd docker
cp docker-compose-build.yml docker-compose.yml

Build and start the service:

# 选项 A：构建并启动所有服务
docker compose build
docker compose up -d

# 选项 B：仅构建并启动新闻推送服务
docker compose build trendradar
docker compose up -d trendradar

# 选项 C：仅构建并启动 MCP AI 分析服务
docker compose build trendradar-mcp
docker compose up -d trendradar-mcp

💡 Architecture parameter description:

• By default, builds an amd64 architecture image (suitable for most x86_64 servers)

• To build an arm64 architecture (Apple Silicon, Raspberry Pi, etc.), set the environment variable:

  export DOCKER_ARCH=arm64
  docker compose build

Image Updates

# 方式一：手动更新（爬虫 + MCP 镜像）
docker pull wantcat/trendradar:latest
docker pull wantcat/trendradar-mcp:latest
docker compose down
docker compose up -d

# 方式二：使用 docker compose 更新
docker compose pull
docker compose up -d

Available images:

Service Management Commands

# 查看运行状态
docker exec -it trendradar python manage.py status

# 手动执行一次爬虫
docker exec -it trendradar python manage.py run

# 查看实时日志
docker exec -it trendradar python manage.py logs

# 显示当前配置
docker exec -it trendradar python manage.py config

# 显示输出文件
docker exec -it trendradar python manage.py files

# Web 服务器管理（用于浏览器访问生成的报告）
docker exec -it trendradar python manage.py start_webserver   # 启动 Web 服务器
docker exec -it trendradar python manage.py stop_webserver    # 停止 Web 服务器
docker exec -it trendradar python manage.py webserver_status  # 查看 Web 服务器状态

# 查看帮助信息
docker exec -it trendradar python manage.py help

# 重启容器
docker restart trendradar

# 停止容器
docker stop trendradar

# 删除容器（保留数据）
docker rm trendradar

💡 Web server description:

• Automatically starts in cron mode; access the latest report via browser at http://localhost:8080

• Navigate to historical reports via directory browsing (e.g., http://localhost:8080/2025-xx-xx/)

• The port can be configured via the WEBSERVER_PORT parameter in the .env file

• Manual stop: docker exec -it trendradar python manage.py stop_webserver

• Manual start: docker exec -it trendradar python manage.py start_webserver

• Security note: only provides static file access, restricted to the output directory, bound to local access only

Data Persistence

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

📊 Web version report access paths:

The daily summary HTML report generated by TrendRadar is saved to two locations simultaneously:

Local access example:

# 方式 1：通过 Web 服务器访问（推荐，Docker 环境）
# 1. 启动 Web 服务器
docker exec -it trendradar python manage.py start_webserver
# 2. 在浏览器访问
http://localhost:8080                           # 访问最新报告（默认 index.html）
http://localhost:8080/html/2025-xx-xx/          # 访问指定日期的报告

# 方式 2：直接打开文件（本地环境）
open ./output/index.html             # macOS
start ./output/index.html            # Windows
xdg-open ./output/index.html         # Linux

# 方式 3：访问历史归档
open ./output/html/2025-xx-xx/当日汇总.html

Why are there two index.html files?

• output/index.html: Mounted to the host via Docker Volume, can be opened directly locally

• index.html: Pushed to the repository by GitHub Actions, automatically deployed by GitHub Pages

💡 Tip: The two files have identical content; choose either one to access.

Troubleshooting

# 检查容器状态
docker inspect trendradar

# 查看容器日志
docker logs --tail 100 trendradar

# 进入容器调试
docker exec -it trendradar /bin/bash

# 验证配置文件
docker exec -it trendradar ls -la /app/config/

MCP Service Deployment (AI Analysis Functionality)

If you need to use the AI analysis functionality, you can deploy a standalone MCP service container.

Architecture description:

flowchart TB
    subgraph trendradar["trendradar"]
        A1[定时抓取新闻]
        A2[推送通知]
    end
    
    subgraph trendradar-mcp["trendradar-mcp"]
        B1[127.0.0.1:3333]
        B2[AI 分析接口]
    end
    
    subgraph shared["共享卷"]
        C1["config/ (ro)"]
        C2["output/ (ro)"]
    end
    
    trendradar --> shared
    trendradar-mcp --> shared

Quick start:

If you have already completed deployment following Method 1: Using docker compose, just start the MCP service:

cd TrendRadar/docker
docker compose up -d trendradar-mcp

# 查看运行状态
docker ps | grep trendradar-mcp

Start the MCP service standalone (without using docker compose):

# Linux/Mac
docker run -d --name trendradar-mcp \
  -p 127.0.0.1:3333:3333 \
  -v $(pwd)/config:/app/config:ro \
  -v $(pwd)/output:/app/output:ro \
  -e TZ=Asia/Shanghai \
  wantcat/trendradar-mcp:latest

# Windows PowerShell
docker run -d --name trendradar-mcp `
  -p 127.0.0.1:3333:3333 `
  -v ${PWD}/config:/app/config:ro `
  -v ${PWD}/output:/app/output:ro `
  -e TZ=Asia/Shanghai `
  wantcat/trendradar-mcp:latest

⚠️ Note: When running standalone, make sure the config/ and output/ folders exist in the current directory and contain configuration files and news data.

Verify the service:

# 检查 MCP 服务健康状态
curl http://127.0.0.1:3333/mcp

# 查看 MCP 服务日志
docker logs -f trendradar-mcp

Configure in AI clients:

After the MCP service starts, configure it according to the different clients:

Cherry Studio (recommended, GUI configuration):

• Settings → MCP Servers → Add

• Type: streamableHttp

• URL: http://127.0.0.1:3333/mcp

Claude Desktop / Cline (JSON configuration):

{
  "mcpServers": {
    "trendradar": {
      "url": "http://127.0.0.1:3333/mcp",
      "type": "streamableHttp"
    }
  }
}

💡 Tip: The MCP service only listens on the local port (127.0.0.1) for security. For remote access, configure a reverse proxy and authentication yourself.

7. How is the push content displayed?

Configuration location: The report and display sections of config/config.yaml

report:
  mode: "daily"                    # 推送模式
  display_mode: "keyword"          # 显示模式（v4.6.0 新增）
  rank_threshold: 5                # 排名高亮阈值
  sort_by_position_first: false    # 排序优先级
  max_news_per_keyword: 0          # 每个关键词最大显示数量

display:
  region_order:                    # 区域显示顺序（v5.2.0 新增）
    - new_items                    # 新增热点区域
    - hotlist                      # 热榜区域
    - rss                          # RSS 订阅区域
    - standalone                   # 独立展示区
    - ai_analysis                  # AI 分析区域

Common Configuration Item Descriptions

Grouping Method Comparison (display_mode)

Do you want to see "what news exists under this topic" or "what news exists on this platform"?

Region Display Order (region_order)

By adjusting the order of the display.region_order list, you can control the display position of each region in push messages.

Default order: New hot items → Hot list → RSS → Standalone display area → AI analysis

Custom example: Want AI analysis at the very front?

display:
  region_order:
    - ai_analysis                  # 移到第一行
    - new_items
    - hotlist
    - rss
    - standalone

Note: A region is only displayed when both conditions are met:

1. It is in the region_order list

2. The corresponding switch in display.regions is set to true

Region Switches (regions)

Use display.regions to control whether each region is displayed in pushes:

display:
  regions:
    hotlist: true                    # 热榜区域（关键词匹配的热点新闻）
    new_items: false                 # 新增热点区域（含热榜新增 + RSS 新增）
    rss: true                       # RSS 订阅区域（关键词匹配的 RSS 内容）
    standalone: false                # 独立展示区（完整热榜/RSS，不受关键词过滤）
    ai_analysis: true                # AI 分析区域

Sorting Priority (sort_by_position_first)

Suppose you configured keywords: 1. Tesla, 2. BYD. Actual popularity: BYD (10 items), Tesla (3 items).

Standalone Display Area (standalone)

Scenario: For some platforms (like Zhihu Hot List, HackerNews), I want to browse everything, regardless of whether it matches my keywords.

display:
  regions:
    standalone: true                  # 推送中展示独立展示区（关闭不影响 AI 分析）

  standalone:
    platforms: ["zhihu", "weibo"]     # 这些平台的热榜给我完整显示
    rss_feeds: ["hacker-news"]        # 这些RSS源的内容给我完整显示
    max_items: 20                     # 最多显示多少条

💡 Push display and AI analysis are independently controlled: regions.standalone only controls whether the standalone display area appears in pushes. Even if push display is disabled, as long as include_standalone: true is enabled in the AI configuration, AI will still analyze the full data from these platforms. Suitable for users who want AI to do deep analysis but don't want overly long push messages.

8. When will I receive pushes?

Configuration location: The schedule section of config/config.yaml + config/timeline.yaml

Quick Start

Simply choose a preset template in config.yaml; no need to edit timeline.yaml:

schedule:
  enabled: true
  preset: "morning_evening"     # 改这里就行

Available Preset Templates

Fully Custom

If none of the preset templates meet your needs, you can edit the custom section at the bottom of config/timeline.yaml to freely define time segments, daily plans, and weekday mappings. See the comments in the timeline.yaml file for details.

Important Notes

⚠️ Attention users upgrading from older versions:

• v6.0.0 removed the old notification.push_window and ai_analysis.analysis_window configurations

• Please use the new schedule + timeline.yaml scheduling system instead

• The old "push once daily" can be replaced with the morning_evening preset

• The old "push during work hours" can be replaced with the office_hours preset

⚠️ GitHub Actions users note:

• GitHub Actions execution times are unstable and may have a ±15 minute deviation

• It is recommended to leave at least 2 hours of buffer in time ranges

• For precise scheduled pushes, it is recommended to use Docker deployment on a personal server

9. How often does it run?

Configuration location: The schedule section of .github/workflows/crawler.yml

on:
  schedule:
    - cron: "0 * * * *"  # 每小时运行一次

How to modify the run frequency?

GitHub Actions uses a time format called "Cron". You don't need to understand it deeply—just copy the code below and replace it.

Configuration location: The schedule section in the .github/workflows/crawler.yml file

⚠️ Two Important Reminders

1. Time zone difference: GitHub's servers are overseas and use UTC time.

   • Simple math: Your desired Beijing time minus 8 hours = the time you need to enter.

   • Example: If you want it to run at 20:00 Beijing time, enter 12:00 in the settings

2. Don't run too frequently: It is recommended that the interval be no less than 30 minutes.

   • GitHub's free resources are limited; running too often may result in account restrictions.

   • Also, Actions itself has a startup delay of a few minutes, so overly precise control is meaningless.

Step-by-Step Modification Guide

1. In your GitHub repository, find the .github/workflows/crawler.yml file

2. Click the ✏️ (Edit) button in the top right corner

3. Find the cron: "..." line and replace the content inside the quotes with the "code" above

4. Click the green Commit changes button in the top right corner to save

10. Push to multiple groups/devices

⚠️ Security First

Don't write passwords/Tokens directly in config.yaml! If you upload a file containing passwords to GitHub, the whole world can see it.

Correct approach:

• GitHub Actions users: Add them in Settings -> Secrets

• Docker users: Write them in the .env file (this file won't be uploaded)

How to push to multiple places at once?

It's simple—just separate multiple addresses with a semicolon ; in the configuration.

For example: Suppose you have two Feishu groups and want to receive pushes in both:

• Group 1 address: https://.../webhook/aaa

• Group 2 address: https://.../webhook/bbb

Fill in the configuration as: https://.../webhook/aaa;https://.../webhook/bbb

Platforms that support multiple accounts

Common configuration examples (GitHub Secrets / .env)

# 飞书发给 3 个群
FEISHU_WEBHOOK_URL=https://hook1...;https://hook2...;https://hook3...

# 钉钉发给 2 个群
DINGTALK_WEBHOOK_URL=https://oapi...;https://oapi...

# Telegram 发给 2 个人 (注意一一对应)
TELEGRAM_BOT_TOKEN=tokenA;tokenB
TELEGRAM_CHAT_ID=userA;userB

Tip: To prevent abuse, each platform is limited to pushing to 3 accounts by default. If you need more, you can modify the MAX_ACCOUNTS_PER_CHANNEL configuration.

11. Where is the data stored?

Where will the data be stored?

The system will automatically choose the most suitable location for you, so you usually don't need to worry about it:

How to configure cloud storage? (Required for GitHub Actions users)

If you're running with GitHub Actions, you need a "cloud drive" to store data. For example, use Cloudflare R2 (because it has a free tier).

Add these 5 variables in GitHub Secrets:

💡 Detailed tutorial: How to apply for R2? See Quick Start - Remote Storage Configuration

How long is the data kept?

By default, we don't automatically delete your data. But if you think the data takes up too much space, you can set up "automatic cleanup."

Configuration location: config/config.yaml

storage:
  local:
    retention_days: 30    # 本地数据只保留 30 天 (0 表示永久)
  remote:
    retention_days: 30    # 云端数据只保留 30 天

Push time is wrong? (Timezone settings)

If you're overseas, or you notice the push time doesn't match your local time, you can modify the timezone.

Configuration location: config/config.yaml

app:
  timezone: "Asia/Shanghai"  # 默认是中国时间

• For example, if you're in Los Angeles, USA, change it to: America/Los_Angeles

• For example, if you're in London, UK, change it to: Europe/London

12. Let AI analyze hot topics for me

What can AI do for me?

After enabling this feature, AI will act like a professional analyst. When pushing each batch of news, it will:

1. Read automatically: Read all matched hot news

2. Think deeply: Analyze the connections between news items that were originally isolated

3. Write reports: Append a short, insightful "insight report" at the end of the pushed message

Included content: Hot topic trend summaries, public opinion direction analysis, cross-platform correlation analysis, potential impact assessment, etc.

How to enable AI analysis?

The simplest way is through environment variables (GitHub Secrets or .env recommended).

Required configuration items:

Supported AI providers (based on LiteLLM, supports 100+ providers):

💡 New feature: Now based on the unified LiteLLM interface, supporting 100+ AI providers, with simpler configuration and better error handling.

Optional configuration items:

Advanced usage: AI translation

If you follow foreign RSS feeds (e.g., Hacker News), AI can translate the content into Chinese for you before pushing.

Configuration location: config/config.yaml

ai_translation:
  enabled: true          # 开启翻译
  language: "Chinese"    # 翻译成什么语言 (Chinese, English, Japanese...)

Advanced usage: Custom AI "persona"

Do you think the AI sounds too formal? You can modify its prompt to give it a style you like (e.g., "sarcastic commentator," "senior investment advisor").

• File to modify: config/ai_analysis_prompt.txt

• How to modify: Open it with a plain text editor and tell the AI what kind of analysis style you want.

✨ AI Intelligent Analysis

TrendRadar v3.0.0 adds an AI analysis feature based on MCP (Model Context Protocol), allowing you to converse with news data in natural language for in-depth analysis.

⚠️ Read before use

Important note: The AI feature requires local news data

The AI analysis feature does not query real-time network data directly; it analyzes the news data you've already accumulated locally (stored in the output folder).

Usage instructions:

1. The project includes test data: The output directory contains one week of hot-list news data by default, from 2025-12-21 to 2025-12-27, which you can use to quickly try out the AI feature.

2. Query limitations:

   • ✅ You can only query data within the existing date range (December 21-27, 7 days total)

   • ❌ You cannot query real-time news or future dates

3. Getting the latest data:

   • The test data is only for a quick trial. We recommend deploying the project yourself to get real-time data.

   • Deploy and run the project following the Quick Start

   • After waiting at least 1 day for news data to accumulate, you can query the latest hot topics.

1. Quick deployment

Cherry Studio provides a GUI configuration interface, deployable in 5 minutes. The complex parts are installed with one click.

Illustrated deployment tutorial: Now updated on my official account. Reply "mcp" to get it.

Detailed deployment tutorial: README-Cherry-Studio.md

Deployment mode description:

• STDIO mode (recommended): Configure once and no further configuration is needed afterward. The illustrated deployment tutorial only uses this mode as an example.

• HTTP mode (alternative): If you run into issues with STDIO mode, you can use HTTP mode. The configuration for this mode is basically the same as STDIO, but the content you copy and paste is just one line, so it's less error-prone. The only thing to note is that you need to manually start the service before each use. See the HTTP mode instructions at the bottom of README-Cherry-Studio.md for details.

2. Learning how to talk to AI

Detailed conversation tutorial: README-MCP-FAQ.md

💡 Tip: We don't actually recommend asking multiple questions at once. If the AI model you chose can't even handle sequential calls like in the image below, we suggest switching to a different one.

🔌 MCP Clients

The TrendRadar MCP service supports the standard Model Context Protocol (MCP), and can connect to various AI clients that support MCP for intelligent analysis.

Supported clients

Notes:

• Replace /path/to/TrendRadar with your actual project path

• Windows paths use double backslashes: C:\\Users\\YourName\\TrendRadar

• Remember to restart after saving

Method 1: HTTP mode

1. Start the HTTP service:

   # Windows
   start-http.bat
   
   # Mac/Linux
   ./start-http.sh

2. Configure Cursor:

   Project-level configuration (recommended): Create .cursor/mcp.json in the project root:

   {
     "mcpServers": {
       "trendradar": {
         "url": "http://localhost:3333/mcp",
         "description": "TrendRadar 新闻热点聚合分析"
       }
     }
   }

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

3. Usage steps:

   • Restart Cursor after saving the configuration file

   • Check the connected tools in "Available Tools" in the chat interface

   • Start using it: Search for today's "AI"-related news

Method 2: STDIO mode (recommended)

Create .cursor/mcp.json:

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

Cline configuration

Add the following in Cline's MCP settings:

HTTP mode:

{
  "trendradar": {
    "url": "http://localhost:3333/mcp",
    "type": "streamableHttp",
    "autoApprove": [],
    "disabled": false
  }
}

STDIO mode (recommended):

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

Continue configuration

Edit ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uv",
          "args": [
            "--directory",
            "/path/to/TrendRadar",
            "run",
            "python",
            "-m",
            "mcp_server.server"
          ]
        }
      }
    ]
  }
}

Usage example:

分析最近7天"特斯拉"的热度变化趋势
生成今天的热点摘要报告
搜索"比特币"相关新闻并分析情感倾向

MCP Inspector is the official debugging tool for testing MCP connections:

Usage steps

1. Start the TrendRadar HTTP service:

   # Windows
   start-http.bat
   
   # Mac/Linux
   ./start-http.sh

2. Start MCP Inspector:

   npx @modelcontextprotocol/inspector

3. Connect in the browser:

   • Visit: http://localhost:3333/mcp

   • Test the "Ping Server" feature to verify the connection

   • Check whether "List Tools" returns 17 tools:

     • Basic queries: get_latest_news, get_news_by_date, get_trending_topics

     • Smart search: search_news, find_related_news

     • Advanced analysis: analyze_topic_trend, analyze_data_insights, analyze_sentiment, aggregate_news, compare_periods, generate_summary_report

     • RSS queries: get_latest_rss, search_rss, get_rss_feeds_status

     • System management: get_current_config, get_system_status, resolve_date_range

Any client that supports the Model Context Protocol can connect to TrendRadar:

HTTP mode

Service URL: http://localhost:3333/mcp

Basic configuration template:

{
  "name": "trendradar",
  "url": "http://localhost:3333/mcp",
  "type": "http",
  "description": "新闻热点聚合分析"
}

STDIO mode (recommended)

Basic configuration template:

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

Notes:

• Replace /path/to/TrendRadar with your actual project path

• Windows paths use backslash escaping: C:\\Users\\...

• Make sure the project dependencies are installed (run the setup script)

Frequently asked questions

Troubleshooting steps:

1. Confirm port 3333 is not in use:

   # Windows
   netstat -ano | findstr :3333
   
   # Mac/Linux
   lsof -i :3333

2. Check whether the project dependencies are installed:

   # 重新运行安装脚本
   # Windows: setup-windows.bat 或者 setup-windows-en.bat
   # Mac/Linux: ./setup-mac.sh

3. View the detailed error logs:

   uv run python -m mcp_server.server --transport http --port 3333

4. Try a custom port:

   uv run python -m mcp_server.server --transport http --port 33333

Solutions:

1. STDIO mode:

   • Confirm the UV path is correct (run which uv or where uv)

   • Confirm the project path is correct and contains no Chinese characters

   • Check the client's error logs

2. HTTP mode:

   • Confirm the service is running (visit http://localhost:3333/mcp)

   • Check the firewall settings

   • Try using 127.0.0.1 instead of localhost

3. General checks:

   • Restart the client application

   • Check the MCP service logs

   • Use MCP Inspector to test the connection

Possible causes:

1. Data doesn't exist:

   • Confirm the crawler has been run (there's data in the output directory)

   • Check whether the queried date range has data

   • Check the available dates in the output directory

2. Parameter errors:

   • Check the date format: YYYY-MM-DD

   • Confirm the platform ID is correct: zhihu, weibo, etc.

   • Check the parameter descriptions in the tool documentation

3. Configuration issues:

   • Confirm config/config.yaml exists

   • Confirm config/frequency_words.txt exists

   • Check whether the configuration file format is correct

📚 Project-related

4 articles:

• You can leave a comment under this article, which makes it convenient for the project author to answer questions on mobile

• Reaching 1000 stars in 2 months, my GitHub project promotion practical experience

• Notes on running this project from a GitHub fork

• Based on this project, how to write articles for an official account or news content

AI development:

• If you have niche needs, you can absolutely develop on top of my project yourself. Even those with zero programming experience can give it a try.

• All of my open-source projects use, to varying degrees, an AI-assisted software I wrote myself to improve development efficiency. This tool is open source.

• Core feature: Quickly filter project code and feed it to AI. You only need to add your personal requirements.

• Project URL: https://github.com/sansan0/ai-code-context-helper

Other projects

📍 Chairman Mao's Footprint Map - Interactive dynamic display of the complete trajectory from 1893-1976. All comrades are welcome to contribute data.

• https://github.com/sansan0/mao-map

Bilibili comment section data visualization and analysis software

• https://github.com/sansan0/bilibili-comment-analyzer

📄 License

GPL-3.0 License

🔝 Back to top