TrendRadar 详细介绍：开源项目架构、功能与实践指南

项目快照：sansan0/TrendRadar，约 62,416 个 Star，24,877 个 Fork；最新推送时间 2026-09-13T06:38:25Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/sansan0/TrendRadar · https://trendradar.sandev.cc

TrendRadar 从代码、运行环境到实践流程的项目封面 — TrendRadar 的项目能力与实践流程示意。

项目速览（TL;DR）

TrendRadar 是一个使用 Python 编写的热点新闻聚合与分析工具，面向“多平台热点、RSS 订阅、关键词筛选、人工智能（AI）处理和消息推送”这一整条信息处理链路。仓库描述将其定位为 AI 驱动的舆情与趋势监测工具，并提供 Docker、本地部署、GitHub Actions、GitHub Pages 和 Cloudflare Pages 等部署相关入口。

根据给定 GitHub 元信息，项目当前默认分支为 master，许可证为 GPL-3.0，GitHub 页面显示 Star 数为 62416、Fork 数为 24877。README 徽章标注的项目版本为 v6.10.0，MCP 相关版本为 v4.1.0；这些版本应以仓库当前内容和官方文档为准。

技术栈：Python，要求 Python 版本为 >=3.12。
数据入口：多平台热点聚合和 RSS 订阅。
筛选与处理：关键词筛选、AI 智能筛选、AI 翻译、AI 分析简报。
输出方式：企业微信、个人微信、飞书、钉钉、Telegram、邮件、ntfy、Bark、Slack 和通用 Webhook 等。
扩展方式：通过 MCP（Model Context Protocol，模型上下文协议）客户端接入自然语言分析、情感洞察和趋势预测等场景。

定位与目标用户

TrendRadar 的主要价值不在于单独抓取某一个网站，而在于把信息采集、关键词命中、AI 处理和通知分发组合成一个可自托管的工作流。对于需要持续关注行业新闻、产品动态、公共议题或指定主题的个人和团队，它可以减少人工重复浏览多个信息源的工作量。

项目描述强调“数据本地/云端自持”，因此部署者可以根据自身环境选择本地运行或云端运行。资料没有说明各数据源的完整清单、采集频率、去重算法、权限模型或数据保留策略，使用前应以最新 README 和官方文档为准。

核心功能

多平台热点聚合

热点聚合的输入是多个平台的公开热点信息，输出是统一处理后的新闻或趋势条目。根据 README 的功能描述，系统会将不同平台的信息汇入同一套筛选和推送流程；但资料没有提供平台适配器名称、请求参数、分页规则、限流策略或完整数据字段，因此不能据此推断具体采集实现。

从工作流角度看，聚合层需要先形成可供后续处理的内容集合，再交给关键词规则或 AI 筛选模块。若某个数据源需要登录、授权或受访问条款约束，使用者必须先确认该数据源允许相应的访问方式，不能把公开可见直接等同于可以任意采集和再分发。

RSS 订阅

RSS（Really Simple Syndication，简易信息聚合）是项目明确支持的数据入口之一，README 将 RSS 订阅源支持标注为 v4.5.0 新增能力。RSS 输入通常包含标题、摘要、链接和发布时间等结构化内容，但本仓库资料没有给出订阅源配置文件格式、刷新周期、失败重试参数或 XML 字段映射。

在功能链路中，RSS 内容会进入与热点信息相同或相近的筛选、翻译、分析和通知流程。项目依赖中包含 feedparser==6.0.12，这能证明 Python 包依赖层使用了 FeedParser，但不能单独证明所有 RSS 业务规则；具体配置应以官方文档为准。

关键词精准筛选

关键词筛选的输入是用户关注的词语或主题，输出是命中后的新闻集合。该机制适合把“所有抓取内容”缩小到“与指定主题相关的内容”，并作为后续 AI 分析和消息推送的前置条件。

资料没有提供关键词配置的字段名、匹配大小写规则、正则表达式支持、排除词优先级和多关键词逻辑。不能据此编写具体配置样例；部署者应查阅官方配置说明，避免把示例字段误当成仓库实际支持的字段。

AI 智能筛选、翻译与分析推送

README 将 AI 智能筛选新闻标注为 v6.5.0 新增能力，将 AI 分析推送标注为 v5.0.0 新增能力，并将 AI 多语言推送标注为 v5.2.0 新增能力。其输入可以理解为已采集的热点或 RSS 条目，输出则是筛选结果、翻译文本或分析简报，最终可以交给通知渠道。

依赖文件列出了 litellm==1.82.6 和 json-repair==0.58.6，说明 Python 项目依赖中包含大模型调用抽象和 JSON 修复相关组件。资料没有列出支持的模型供应商、模型名称、提示词模板、令牌消耗、超时设置或返回结构，因此不能在本文中指定某个模型或伪造环境变量。

多渠道智能推送

项目 README 列出了企业微信、个人微信、Telegram、钉钉、飞书、邮件、ntfy、Bark、Slack 和通用 Webhook。通知模块的输入是经过关键词或 AI 处理的内容，输出是发送到指定渠道的消息；不同渠道所需凭据和格式应由对应官方文档以及 TrendRadar 文档共同确定。

资料没有提供任何通知渠道的字段名、默认值、回调地址、签名算法或重试策略。安全部署时不应把令牌、Webhook 地址和邮箱凭据直接写入公开仓库；如果具体渠道要求密钥，应在本地或受控的部署环境中注入，并按照该渠道的授权规则使用。

MCP 客户端与自然语言分析

MCP（Model Context Protocol，模型上下文协议）用于把工具或数据能力暴露给兼容的 AI 客户端。README 宣称项目支持通过 MCP 进行自然语言对话分析、情感洞察和趋势预测，并提供 trendradar-mcp 这一命令行入口；资料没有给出 MCP 服务端口、传输协议、认证方式或客户端配置格式。

pyproject.toml 中的可执行入口为 trendradar-mcp = "mcp_server.server:run_server"，构建目标包含 mcp_server 包。README 徽章显示 MCP 版本为 v4.1.0，而 Python 依赖中包含 fastmcp==2.12.5；两者属于不同层面的版本信息，不能直接视为同一个版本号。

系统架构与关键模块

从公开资料能够确认的架构边界包括 Python 应用包、MCP 服务包、外部数据源、AI 处理组件和通知渠道。下面的处理链是根据 README 功能描述与 pyproject.toml 依赖关系整理出的逻辑架构，不等同于仓库内部的完整类图或调用图。

采集层：接收多平台热点和 RSS 订阅内容。RSS 解析对应 feedparser==6.0.12，HTTP 请求依赖为 requests==2.33.0。
筛选层：使用关键词规则处理关注范围，并提供 AI 智能筛选能力。资料未公布两者的执行优先级和冲突处理规则。
增强层：通过 AI 翻译或 AI 分析生成多语言内容和分析简报。litellm==1.82.6 出现在项目依赖中，但具体模型配置未提供。
分发层：把结果发送到 README 列出的消息渠道，或通过通用 Webhook 对接其他系统。
交互层：由 mcp_server 提供 MCP 相关入口，使兼容客户端可以进行自然语言分析。服务的实际暴露方式需要参考官方文档。

项目构建配置将 trendradar 和 mcp_server 指定为 Wheel 包内容，并使用 Hatchling 作为构建后端。资料没有提供完整目录树，因此不应根据包名进一步推断模块文件名、数据库结构或配置文件位置。

依赖与运行环境

项目声明的运行环境是 Python 3.12 或更高版本，构建后端为 Hatchling。依赖版本在 pyproject.toml 中采用精确版本写法，部署时应优先使用项目声明的依赖集合，避免因手工替换版本而引入未验证的行为差异。

依赖或组件	版本	用途依据	资料状态
requests	2.33.0	项目声明的 Python HTTP 请求依赖	来自 pyproject.toml
PyYAML	6.0.3	项目声明的 YAML 处理依赖	来自 pyproject.toml
feedparser	6.0.12	项目声明的 RSS 解析依赖	来自 pyproject.toml
fastmcp	2.12.5	项目声明的 MCP 相关依赖	来自 pyproject.toml
litellm	1.82.6	项目声明的 AI 模型调用相关依赖	来自 pyproject.toml
websockets	13.1	项目声明的 WebSocket 依赖	来自 pyproject.toml
boto3	1.42.76	项目声明的 AWS SDK 依赖	来自 pyproject.toml
tenacity	8.5.0	项目声明的重试相关依赖	来自 pyproject.toml

依赖表只说明包管理文件中声明的事实，不代表每个功能在所有部署模式下都会被调用。系统还声明了 json-repair==0.58.6，用于依赖集合中的 JSON 修复能力；具体调用位置和处理边界，官方仓库未在给定资料中提供。

快速开始

资料明确提供了 Python 项目元数据、两个命令行入口以及 Docker、本地部署等方向，但给定 README 片段没有展示完整的安装命令、初始化步骤和运行参数。下面的闭环只使用仓库已声明的构建方式和入口名称，实际配置步骤应以最新官方文档为准。

安装

git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar
python -m pip install .

上述命令使用项目根目录中的 pyproject.toml 进行本地安装，并会读取项目声明的 Python 版本和依赖。资料没有提供虚拟环境命令、锁定文件或离线安装包，因此本文不补写未在仓库资料中出现的环境初始化细节。

运行

trendradar
trendradar-mcp

trendradar 和 trendradar-mcp 是 pyproject.toml 中明确声明的脚本入口。由于资料没有给出命令行参数、默认监听地址、端口或配置文件路径，不能在这里增加 --port、--config 等未经证实的参数；如果直接运行后需要初始化配置，应以终端输出和官方文档为准。

验证

安装阶段可通过命令是否成功返回来验证包构建和依赖解析，运行阶段则应检查命令行输出是否出现启动错误。项目没有在给定资料中提供健康检查 URL、默认端口、测试命令或版本查询参数，因此无法给出一个可核验的 HTTP 检查示例。

如果运行失败，优先核对 Python 是否满足 >=3.12、项目依赖是否完整安装，以及当前工作目录是否为仓库根目录。任何 API 密钥、Webhook 地址或模型凭据都不应直接写入命令历史或公开脚本；本文没有为这些参数虚构名称。

配置说明

给定资料没有包含完整的运行时配置样例，也没有列出 RSS、关键词、通知渠道或模型配置字段。为了区分“项目元数据”和“应用配置”，下表只列出 pyproject.toml 中确实存在的字段；运行时字段的默认值若未在资料中出现，则明确标记为未提供。

字段名	类型	默认值	作用
project.name	字符串	`trendradar`	Python 项目名称
project.version	字符串	`6.10.0`	项目发布版本声明
project.requires-python	版本约束字符串	`>=3.12`	运行所需的 Python 版本约束
project.dependencies	字符串数组	见 pyproject.toml	项目运行依赖及其精确版本
project.scripts.trendradar	入口映射	`trendradar.__main__:main`	注册主程序命令行入口
project.scripts.trendradar-mcp	入口映射	`mcp_server.server:run_server`	注册 MCP 服务命令行入口
tool.hatch.build.targets.wheel.packages	字符串数组	`["trendradar", "mcp_server"]`	指定 Wheel 构建包含的 Python 包

README 中提到“配置详解”，但给定资料没有展开对应内容，因此 RSS 地址、关键词列表、推送开关、AI 服务密钥、MCP 客户端配置和 Docker 环境变量均不能在本文中列出。官方仓库未提供该信息，建议以最新 README 为准。

进阶用法

进阶使用的核心是把筛选条件、AI 处理和通知渠道按业务目的组合，而不是盲目打开所有能力。项目已经提供多渠道推送和 MCP 扩展入口，但每种集成的实际参数、权限范围和失败处理方式都应独立验证。

主题监测：为一个明确主题配置关键词入口，再观察命中内容是否需要增加排除条件。资料未提供具体规则语法，因此不要直接套用未验证的正则或配置键。
多语言阅读：在需要跨语言阅读时启用 AI 翻译，再把翻译结果作为推送内容。模型、语言列表和失败回退策略未在资料中给出。
简报推送：把 AI 分析结果发送到团队已有渠道，适合减少原始链接堆积。应检查推送内容是否包含不应外发的原文、个人信息或内部资料。
MCP 对话分析：在兼容 MCP 的客户端中接入项目提供的能力，用于自然语言查询、情感洞察或趋势分析。连接地址和认证设置未提供，不能从命令入口推导默认端口。
部署方式选择：README 同时列出 Docker、本地部署、GitHub Actions、GitHub Pages 和 Cloudflare Pages 入口。不同方式的职责和限制没有在给定片段中完整说明，应按官方文档选择。

根据本文作者的经验判断，如果信息源数量、关键词数量和通知渠道都较少，本地部署更便于核查数据流；如果需要持续运行，则应在部署前补齐日志、凭据保存和失败重试方案。这个判断不代表项目官方性能结论，资料也没有提供吞吐量、并发数或资源基线。

可观测性与运维

项目资料没有公布日志格式、指标名称、健康检查接口、告警规则、任务调度周期或数据保留策略，因此不能声称项目自带某种监控系统。运维验证应围绕“采集是否成功、筛选是否命中、AI 是否返回、通知是否送达”建立最小检查链路。

记录部署版本，至少区分仓库版本 v6.10.0 与 MCP 徽章标注的 v4.1.0。
检查 RSS 或热点采集是否有新输入，并保存失败源的名称和时间。
单独验证关键词筛选结果，避免把采集失败误判为“没有热点”。
对 AI 翻译和分析设置凭据隔离，记录调用失败，但不要把密钥写入日志。
对每个通知渠道进行测试消息验证，并区分生成成功、发送成功和接收成功。

Docker 的具体镜像标签、容器端口、卷挂载和 Compose 文件在给定资料中未提供；GitHub Actions 和部署到页面服务的完整工作流也未展示。官方仓库未提供该信息，建议以最新 README 为准，不能直接使用未经核验的端口映射或环境变量。

安全与合规边界

TrendRadar 涉及公开信息聚合、内容处理、外部模型调用和消息推送，安全边界主要取决于数据源授权、凭据保护和结果分发范围。本文只讨论授权环境中的使用，不提供面向未授权目标的采集、绕过访问控制或规避检测方法。

数据源授权：使用 RSS 或平台热点前，应遵守数据源服务条款、robots 规则及适用法律；公开可见不等于可以无限制抓取、存储或再分发。
隐私保护：如果订阅内容包含个人信息、内部信息或受限制材料，应在进入 AI 服务和通知渠道前完成分类、最小化和授权审查。
凭据隔离：模型密钥、邮件凭据、Webhook 密钥和消息平台令牌不应提交到公开仓库。资料未提供统一的密钥管理方式，部署者需按自身基础设施制定方案。
AI 输出审查：翻译、摘要、情感分析和趋势预测属于处理结果，不应在没有人工核验时直接作为事实、决策或对外声明。
MCP 边界：MCP 客户端接入前应确认可访问的数据范围、工具权限和网络边界；未提供认证机制时，不应将服务暴露到不受信任的公网。

项目资料没有给出安全审计、漏洞响应、数据删除接口、合规认证或服务等级承诺。部署者需要根据所在地区、组织制度和数据敏感等级自行完成合规评估。

许可证与商用条款

仓库许可证文件是 GNU General Public License（GNU 通用公共许可证）Version 3，简称 GPL-3.0。该许可证文本强调软件自由、源代码获取、修改和再分发权利，同时要求分发覆盖作品时向接收者提供相应自由，并保留许可证及相关版权信息。

复制、修改和分发前，应完整阅读仓库中的 LICENSE 文件。
分发软件或修改版本时，应遵循 GPLv3 的对应义务，并保留必要的版权和许可证信息。
项目不提供无条件的质量保证，LICENSE 中包含相应的无担保条款。
第三方数据源、模型服务和通知平台还可能有独立条款，不能仅凭 GPL-3.0 推断这些服务允许任意使用。

以上是对仓库 LICENSE 的技术性概括，不构成法律意见。具体商用、再分发、聚合作品和模型服务合规问题，以仓库 LICENSE、适用法律及相关第三方条款为准。

局限性与已知限制

公开资料足以说明项目功能方向，但不足以形成完整的生产部署规范。以下限制来自资料缺口或功能边界，不应被解释为代码缺陷结论。

未提供完整数据源清单、抓取频率、去重规则和采集失败处理机制。
未提供关键词配置语法、默认值、匹配优先级和排除规则。
未提供 AI 模型列表、模型默认值、调用预算、提示词模板和数据出境说明。
未提供通知渠道的完整配置项、认证格式、重试策略和送达确认机制。
未提供 MCP 的监听端口、网络传输方式、认证方式和客户端配置样例。
未提供 Benchmark（基准测试）、并发上限、资源消耗、SLA（服务等级协议）或生产规模承诺。

因此，不能依据 Star、Fork 或 README 的功能徽章推断系统吞吐量、稳定性或适用于某个组织规模。部署前应使用与真实数据源和通知渠道相同的测试条件完成验收。

适合谁

以下信号同时指向“需要集中筛选信息并自行控制数据”的场景时，TrendRadar 值得进行本地验证。选择依据是项目公开能力与部署方式，而不是性能承诺。

个人或小团队每天需要关注多个热点平台和 RSS 源，并希望把结果按关键词集中处理。
团队已经使用企业微信、飞书、钉钉、Telegram、邮件或其他 README 列出的渠道，希望接收自动化简报。
组织需要把数据和处理流程放在自有环境中，且能够自行管理 Python、Docker 或云端部署。
已有兼容 MCP 的 AI 工作流，需要在授权数据范围内进行自然语言分析、情感洞察或趋势研判。
能够接受先阅读配置文档、补充凭据和执行小规模验证，而不是把项目视为开箱即用的托管服务。

不适合谁

如果以下条件是硬约束，项目现有资料不足以支持直接上线，或者应优先选择已经满足这些要求的替代方案。这里不指定未在资料中出现的替代产品。

需要明确 SLA、厂商负责运维、全天候支持和可追责服务合同，但当前资料没有提供这些承诺。
要求固定的采集频率、吞吐量、并发上限或数据完整性指标，而仓库未提供对应 Benchmark 和规模数据。
团队只能运行低于 Python 3.12 的环境，项目声明的 requires-python 为 >=3.12。
需要使用未授权、受登录控制或明确禁止自动化访问的数据源，项目能力不能替代数据授权。
组织无法接受 GPLv3 的分发义务，或不能完成 AI 数据处理、通知外发和个人信息保护审查。

常见问题与排查（FAQ / Troubleshooting）

为什么安装时提示 Python 版本不满足？

项目在 pyproject.toml 中声明 requires-python = ">=3.12"。请先核对当前解释器版本；如果低于该约束，不能据本文推断某个旧版本一定兼容。

为什么找不到 `trendradar` 命令？

该命令由项目脚本入口注册，映射到 trendradar.__main__:main。如果安装没有完成或当前使用的 Python 环境与命令搜索路径不一致，命令可能不可用；应检查安装过程和实际环境，而不是自行修改入口名称。

为什么不知道 MCP 应该连接哪个端口？

给定资料只确认 trendradar-mcp 入口和 mcp_server.server:run_server 映射，没有提供默认端口或连接协议。官方仓库未提供该信息，建议以最新 README 和官方 MCP 文档为准，不要猜测端口。

为什么没有收到通知？

应按采集、关键词命中、AI 处理和渠道发送四个阶段分别排查。资料没有统一的日志字段或诊断命令，因此需要结合实际终端输出、渠道后台记录和官方配置说明确认失败环节。

为什么 AI 筛选结果与关键词筛选结果不同？

两者属于不同类型的处理：关键词筛选依赖显式匹配条件，AI 筛选依赖模型对内容的判断。项目资料没有公布提示词、模型和优先级规则，因此不能为差异给出固定解释；生产使用时应保留人工复核和测试样本。

能否直接把项目暴露到公网？

资料没有提供 MCP 或其他服务入口的认证和默认网络配置，不能据此建议公网暴露。应先确认认证、访问控制、日志脱敏和数据边界；在这些条件未明确前，优先限制在受控网络中。

项目地址与资源

以下链接均来自项目资料或 README 中出现的官方站点。版本、配置和部署行为发生变化时，应以仓库和官方文档的最新内容为准。