TrendRadar 使用教程

📖 项目简介

TrendRadar 是开发者 sansan0 开源的热点聚合与筛选工具，用 Python 编写（语言构成中 Python 占 96.7%），采用 GPL-3.0 协议，在 GitHub 上已累积 6.1 万 Star、2.5 万 Fork，并拿过 GitHub Trending 的 Repository Of The Day 第一名。主程序当前版本 v6.10.0，配套的 MCP 服务版本 v4.1.0。它解决的问题非常具体：热榜太多、噪音太大，你每天刷十几个 App 也未必刷到真正跟自己相关的那几条。

它的工作方式是"抓取 → 筛选 → 推送"三段式。默认监控 11 个平台的热榜，并额外支持 RSS/Atom 订阅源；筛选环节提供两种模式，传统模式用关键词文件精确匹配，新版（v6.5.0 起）可以直接用自然语言写下你的兴趣，由 AI 提取标签再对新闻批量分类打分，只推超过分数阈值的内容，AI 失败时会自动回退到关键词匹配；最后把结果推到手机上。它还会做趋势追踪——记录每条新闻从首次出现到最后出现的时间跨度、排名变化、跨平台表现，新冒出来的热点会用 🆕 标出来，所以你看到的不只是"什么在热"，还有"热点怎么演变"。

它和 AI 编程工具的连接点在 MCP（Model Context Protocol）。项目从 v3.0.0 起提供独立的 MCP 服务，对外暴露十余个工具和四个资源，让你用自然语言直接跟本地的新闻数据对话，而不是自己写脚本查库。对内容创作者来说这一步很关键：选题不再是"我去翻热榜找灵感"，而是"我问一句，它把这几天的数据翻完给我排好序"。作者在三种推送模式的说明里，明确把「当前榜单」这一档标注为给自媒体人 / 内容创作者用的。

📎 相关链接与下载地址（点击展开）

GitHub 项目： github.com/sansan0/TrendRadar
在线可视化配置编辑器： sansan0.github.io/TrendRadar
Docker 镜像： hub.docker.com/r/wantcat/trendradar ／ wantcat/trendradar-mcp
MCP 对话教程：仓库内 README-MCP-FAQ.md
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

📡

11 个平台一次抓完

知乎、抖音、微博、bilibili、百度热搜、今日头条等默认全覆盖，还能自己加平台和 RSS 源

🎯

大白话描述兴趣

不用学关键词语法，直接写"我关注 AI 编程工具"，AI 提标签后按分数阈值过滤

💬

MCP 让 AI 直接查

十余个 MCP 工具，支持检索、趋势分析、跨时段对比、生成简报，自然语言问答

🔒

数据自己拿着

Docker / 本地默认存本地 SQLite，也可接 S3 兼容云存储，不依赖任何第三方服务

🧩 它能做什么、输出什么

项目	说明
数据来源	默认 11 个平台热榜：知乎、抖音、微博、bilibili 热搜、百度热搜、今日头条、贴吧、澎湃新闻、凤凰网、华尔街见闻、财联社热门；可自行增加平台。另支持 RSS / Atom 订阅源（v4.5.0 起），带新鲜度过滤
筛选方式	两种可切换：`keyword` 用 `frequency_words.txt` 精确匹配；`ai` 用 `ai_interests.txt` 写自然语言兴趣，AI 打分后按阈值过滤，失败自动回退
输出	手机推送消息（含 HTML 报告）＋运行后在根目录生成 `index.html` 完整报告页＋可选的 AI 分析简报
推送渠道	企业微信、飞书、钉钉、Telegram、邮件、ntfy、Bark、Slack、通用 Webhook（可对接 Discord / IFTTT 等），支持多账号多群同时推
AI 能力	基于 LiteLLM 统一接口，支持 100+ 提供商（DeepSeek、OpenAI、Gemini、Anthropic、本地 Ollama 等），可配备用模型自动切换；含 AI 筛选、AI 多语言翻译、AI 分析简报三项
MCP 工具	基础查询 `get_latest_news` / `get_news_by_date` / `get_trending_topics`；检索 `search_news` / `find_related_news`；分析 `analyze_topic_trend` / `analyze_data_insights` / `analyze_sentiment` / `aggregate_news` / `compare_periods` / `generate_summary_report`，另有 `check_version`
MCP 资源	4 个：platforms（平台列表）、rss-feeds（订阅源）、available-dates（可查日期）、keywords（关键词）
数据存储	Docker / 本地默认本地 SQLite；GitHub Actions 环境默认远程云存储，兼容 S3 协议（Cloudflare R2、阿里云 OSS、腾讯云 COS 等），不污染仓库

🖥️ 环境要求

环境	建议配置
操作系统	Windows / macOS / Linux 均可；也支持完全不占用本机，直接跑在 GitHub Actions 上
运行环境	本地模式需要 Python，推荐用 `uv` 一并管理 Python 和依赖；走 Docker 则本机无需装 Python
硬件	要求极低，普通 CPU 即可，不需要显卡——它本身只做抓取和文本处理，AI 推理走云端 API 或你自己的 Ollama
低配 / 无服务器方案	① GitHub Actions 定时跑（需定期签到续期）；② Docker 跑在 NAS / 群晖，支持多架构镜像；③ 部署到 GitHub Pages 或 Cloudflare Pages 做在线报告页
关键依赖	本地模式：`uv`；容器模式：Docker + Docker Compose。若要用 AI 筛选 / 翻译 / 分析，还需一个大模型 API Key（填在 `ai.api_key`，三项功能共用一份配置）

🚀 如何使用

💡

最省事的路径：装 uv → 克隆项目 → 跑一次看到 index.html → 再配推送和 AI。先用默认配置跑通、确认能出报告，再去改 config.yaml，比一上来就配一堆渠道要顺得多。想长期无人值守就上 Docker，想接 AI 对话再额外起 MCP 服务。

装运行环境

推荐用 uv，它会自动帮你装好合适的 Python 版本和全部依赖，不用手动折腾虚拟环境。仓库里也提供了 Windows 一键安装脚本 setup-windows.bat。

                        bash
                        # macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
                    

克隆项目

在 GitHub 搜索 TrendRadar，找到作者 sansan0 的仓库后克隆到本地。如果你只想白嫖 GitHub 的定时任务，也可以点仓库页的 Use this template 直接生成自己的仓库。

                        bash
                        git clone 仓库地址 TrendRadar
cd TrendRadar
                    

跑通第一次（最小例子）

两条命令就能出结果。跑完后项目根目录会生成 index.html，用浏览器打开就是完整的热点报告页。

                        bash
                        uv sync                      # 自动安装 Python 和项目依赖
uv run python -m trendradar   # 抓取一次并生成报告
                    

✅

在浏览器里打开这个报告页还有隐藏福利（v6.6.0 起）：按 W 切宽屏、D 切暗色、/ 唤起搜索、? 看全部快捷键，悬停序号可一键复制标题。用邮件客户端看则保持原始窄版布局。

配置筛选和推送

核心就三个文件：config/config.yaml（总配置）、frequency_words.txt（关键词）、ai_interests.txt（自然语言兴趣）。嫌 YAML 麻烦的话，作者还做了网页版可视化配置编辑器，填表单导出即可（地址见文末折叠块）。

                        yaml
                        # config/config.yaml —— 用 AI 筛选的最小配置
filter:
  method: ai            # keyword（默认）| ai

ai_filter:
  min_score: 6          # 只推 6 分以上（1-10）

ai:
  api_key: "你的大模型 API Key"   # 筛选/翻译/分析共用这一份

ai_translation:
  enabled: false        # 需要翻译成外语时再打开
  language: "English"
                    

三种推送模式怎么选（作者给的对应人群）：

模式	适合谁	推送特点
`daily` 当日汇总	企业管理者 / 普通用户	按时推当天所有匹配新闻，会包含之前推过的
`current` 当前榜单	自媒体人 / 内容创作者	推当前榜单的匹配新闻，持续在榜的每次都出现
`incremental` 增量监控	投资者 / 交易员	只推新增内容，零重复

其他常用参数：

参数	作用
`filter.method`	筛选方式，`keyword` 或 `ai`；调度里可按时段分别覆盖
`ai_filter.min_score`	推送分数阈值 1-10，调高更精准、调低更全
`display.display_mode`	`keyword` 按关键词分组 / `platform` 按平台分组
`display.region_order` / `regions`	调整各区域（热榜、新增热点、RSS、独立展示区、AI 分析）的顺序和显隐
调度系统	按周一到周日逐日编排时段，内置 5 种预设：`always_on`、`morning_evening`（默认）、`office_hours`、`night_owl`、`custom`，每个时段能单独设筛选方式和关注方向

⚠️

Docker 用户注意：密钥类配置（API Key、Webhook 地址）建议统一放 docker/.env，个性化改动放 config/custom/ 目录，避免升级时被覆盖。改完执行 docker compose up -d 重启生效。

用 Docker 长期无人值守

想让它每天自己跑，Docker 是最省心的。项目是双容器架构：trendradar 负责抓取推送，trendradar-mcp 负责 AI 分析接口，可以分别启停。

                        bash
                        cd TrendRadar/docker

docker compose pull
docker compose up -d              # 两个服务都起

# 只要推送服务
docker compose up -d trendradar

# 只要 MCP AI 分析服务
docker compose up -d trendradar-mcp

# 查看日志 / 更新镜像
docker compose logs -f trendradar
docker compose pull && docker compose up -d
                    

结合 Codex 使用

这是对创作者最有价值的一步：让 AI 直接查你本地攒下来的热点数据。它的 MCP 服务提供两种接法—— STDIO 模式（作者推荐，由客户端拉起进程，不用先起容器）和 HTTP 模式（先跑起 MCP 容器，客户端连本机 3333 端口的 /mcp 路径，只监听 127.0.0.1）。

Codex CLI 的 MCP 配置写在 ~/.codex/config.toml 的 [mcp_servers] 段里，把官方 STDIO 模式的 command 和 args 平移过来即可：

                        toml
                        # ~/.codex/config.toml
[mcp_servers.trendradar]
command = "uv"
args = ["--directory", "你的/TrendRadar/绝对路径", "run", "python", "-m", "trendradar_mcp"]
                    

⚠️

作者文档里明确列出的客户端是 Claude Desktop、Cursor、Cline、Roo Code、Continue，没有单独写 Codex 的配置样例。由于走的是标准 MCP 协议，理论上任何支持 MCP 的客户端都能接，但首次接入建议先让它调一下 check_version 这个最简单的工具确认连通，再问复杂问题。启动参数以你本地仓库里 MCP 目录的实际模块名为准。

接通之后，选题环节就变成直接对话，比如：

                        prompt
                        这两天有哪些热点适合做 AI 工具类短视频？按热度和持续性排个序
把最近三天"开源"相关的热点跟上周对比一下，看哪些在持续发酵
帮我把今天的科技类热点整理成一份简报
                    

✅

它会调用 search_news、analyze_topic_trend、compare_periods、generate_summary_report 这些工具自己去翻本地数据，你拿到的是排好序的结论，不是一堆待你人工过滤的原始热榜。

🎯 典型应用场景

🎬

内容选题

用「当前榜单」模式盯住持续在榜的话题，再让 AI 按热度和持续性排序，挑还没被做透的方向

📊

趋势复盘

用跨时段对比看某个话题这周和上周的热度变化，判断是一次性话题还是在持续发酵

🔔

关键词盯梢

只关心特定几个词（某产品、某公司、某技术），设好关键词后用增量模式，只在有新消息时提醒

🌍

跨语言资讯

RSS 订阅海外科技媒体 + AI 翻译成中文，早上一条推送把国内外都看完

🏢

团队情报同步

多账号推送到不同的企业微信群或飞书群，运营、产品、技术各看各关心的那一份

📈

行业信息监测

接财联社、华尔街见闻等财经源，用增量模式零重复地跟进特定行业动向

📈 规格与实力

指标	表现
GitHub 热度	6.1 万 Star、2.5 万 Fork、70 个 tag；曾登 GitHub Trending 的 Repository Of The Day 第一名
版本	主程序 v6.10.0，MCP 服务 v4.1.0（迭代非常密，更新日志覆盖多个大版本）
Docker 拉取量	主镜像约 27.2 万次，MCP 镜像约 11.8 万次
代码构成	Python 96.7%、HTML 2%、其他 1.3%；协议 GPL-3.0
默认覆盖平台	11 个热榜 + 任意数量 RSS 源
部署方式	5 种：GitHub Actions、Docker、本地运行、GitHub Pages、Cloudflare Pages
部署耗时	作者给的说法是最快 30 秒完成部署

🧠

它快和稳的关键在于分工明确：抓取和文本处理全在本地做，不依赖任何大模型，所以普通 CPU 就够、跑起来极轻；只有筛选、翻译、分析这三件"需要理解语义"的事才调 AI，而且走 LiteLLM 统一接口，换模型只改一行配置。 AI 环节还有兜底——筛选失败自动回落到关键词匹配，主模型不可用可切备用模型，所以推送不会因为某个 API 抽风就断掉。

❓ 常见问题

Q: 跟我自己刷热搜有什么区别？

三点区别。一是聚合，11 个平台一次看完，不用来回切 App。二是筛选，只留跟你相关的，不用被平台算法牵着走。三是时间维度，它记录每条新闻从首次出现到最后出现的时间跨度和排名变化，能区分"蹭了一下就没了"和"持续在发酵"，这是你手动刷完全看不出来的。

Q: 支持哪些平台？能自己加吗？

默认 11 个：知乎、抖音、微博、bilibili 热搜、百度热搜、今日头条、贴吧、澎湃新闻、凤凰网、华尔街见闻、财联社热门。可以自行增加额外平台，也可以用 RSS/Atom 补任何有订阅源的站点，RSS 内容和热榜用同一套关键词过滤、合并成一条推送发出。

Q: 关键词筛选和 AI 筛选该用哪个？

关注对象很明确（比如就盯几个产品名）用关键词，精确、免费、不依赖网络。关注的是"某个方向"而不是具体词（比如"AI 编程工具的新动向"）就用 AI 筛选，写大白话即可，代价是要消耗 API 调用。也可以按时段混用：早上用关键词快速过一遍，晚上用 AI 做深度筛选。

Q: 一定要 API Key 吗？不想花钱行不行？

不是必须的。纯抓取 + 关键词筛选 + 推送这条链路完全不需要 AI，零成本。只有 AI 筛选、AI 翻译、AI 分析简报这三项需要，而且共用一份 ai.api_key 配置。想完全本地免费可以接自己的 Ollama。

Q: 硬件要求高吗？需要显卡吗？

不需要显卡，普通 CPU 就行，跑在 NAS、树莓派级别的机器上都没问题——它本身只做网络抓取和文本处理。如果连服务器都不想要，直接用 GitHub Actions 定时跑，本机零占用（注意需要定期签到续期，否则免费额度会被暂停）。

Q: 推送收不到、或者推送时间不对怎么办？

先确认渠道配置里的 Webhook 或 Token 填对了；时间不对基本都是时区问题，容器里设 TZ=Asia/Shanghai。另外注意推送模式的影响：incremental 增量模式只在有新增内容时才推，一段时间没消息是正常的，不是坏了。想每天固定收到就换 daily。

Q: 数据存在哪？会不会把我的仓库搞乱？

Docker 和本地运行默认存本地 SQLite 数据库，完全在你手上。GitHub Actions 环境默认走远程云存储，兼容 S3 协议（Cloudflare R2、阿里云 OSS、腾讯云 COS 都可以），专门就是为了不把抓取数据提交回仓库。它会根据运行环境自动选后端，不用你手动切。

Q: 怎么和 Codex 结合？官方支持吗？

它提供标准 MCP 服务，所以原理上任何支持 MCP 的客户端都能接，Codex CLI 在 ~/.codex/config.toml 的 [mcp_servers] 里配 STDIO 启动命令即可。但要说清楚：作者文档里列的客户端是 Claude Desktop、Cursor、Cline、Roo Code、Continue，没有 Codex 的现成样例，所以第一次接的时候先用 check_version 验证连通再往下走。另外 AI 功能需要本地已有新闻数据，项目自带测试数据可以先体验，但要拿到真实结论得自己跑一段时间攒数据。

Q: 可以商用吗？

协议是 GPL-3.0。自己内部用没问题；如果你要基于它二次开发再对外分发，GPL-3.0 要求衍生作品同样以 GPL-3.0 开源，商业场景请先读一遍协议条款再决定。