关键词配置
关键词配置是 TrendRadar 的核心功能之一，它决定了系统从热榜中筛选出哪些你关心的内容进行推送。 通过灵活的语法规则，你可以精确控制信息的匹配、过滤和展示方式。
配置文件位置
关键词配置文件为
config/frequency_words.txt，纯文本格式，每行一个关键词或指令。 支持以 # 开头的注释行，方便标记每个词组的用途。 可使用 [WORD_GROUPS] 标记词组分区的起始位置。1. 语法速查表
下表列出了所有支持的语法类型。如果你是第一次配置，建议先快速浏览，然后跳到下方的详细说明。
| 语法类型 | 标记符号 | 用途 | 示例 | 匹配逻辑 |
|---|---|---|---|---|
| 普通关键词 | 无 | 基础匹配 | 华为 | 标题包含任意一个普通关键词即命中 |
| 必含词 | + | 缩小匹配范围 | +手机 | 必须同时包含所有必含词才命中 |
| 过滤词 | ! | 排除干扰信息 | !广告 | 包含过滤词则立即排除，优先级高于关键词匹配 |
| 数量限制 | @ | 控制推送条数 | @10 | 该词组最多推送指定条数 |
| 全局过滤 | [GLOBAL_FILTER] | 全局排除 | 见下文 | 对所有词组生效，优先级最高 |
| 正则表达式 | /pattern/ | 精确匹配 | /\bai\b/ | 使用正则表达式进行匹配，自动不区分大小写 |
| 显示别名 | => 别名 | 自定义显示名称 | /\bai\b/ => AI 相关 | 推送时显示别名文字，而非原始关键词/正则 |
2. 详细语法说明
2.1 普通关键词
最基本的用法：直接写关键词，每行一个。热榜标题中包含任意一个关键词即命中。
华为
OPPO
苹果匹配示例：
- 命中 「华为发布新款折叠屏手机」 -- 包含「华为」
- 命中 「OPPO Find X8 正式亮相」 -- 包含「OPPO」
- 命中 「苹果将在秋季发布 iPhone」 -- 包含「苹果」
- 未命中 「小米汽车 SU7 销量破万」 -- 不含以上任何关键词
2.2 必含词（+ 前缀）
以
+ 开头的关键词表示「必含词」。匹配规则是：标题必须同时满足两个条件：- 包含至少一个普通关键词
- 包含全部必含词
华为
OPPO
+手机匹配示例：
- 命中 「华为手机最新款发布」 -- 包含「华为」且包含「手机」
- 未命中 「华为发布新款笔记本」 -- 包含「华为」但不含「手机」
- 未命中 「小米手机降价促销」 -- 包含「手机」但不含普通关键词
多个必含词
可以设置多个必含词（如
+手机 和 +发布），此时标题必须同时包含所有必含词才能命中。2.3 过滤词（! 前缀）
以
! 开头的关键词表示「过滤词」。如果标题中包含任意一个过滤词，该条目将被立即排除，无论是否匹配了其他关键词。苹果
华为
!水果
!价格匹配示例：
- 命中 「苹果发布 M4 芯片」 -- 包含「苹果」，不含过滤词
- 排除 「苹果水果价格上涨」 -- 虽然包含「苹果」，但同时包含「水果」和「价格」
- 排除 「华为手机价格汇总」 -- 包含「华为」但同时包含「价格」
2.4 数量限制（@ 前缀）
以
@ 开头的数字表示该词组最多推送的条数。例如 @5 表示即使匹配到 20 条，也只推送前 5 条。特斯拉
马斯克
@5优先级规则：
- 最高 词组内的
@数字设置 - 次之
config.yaml中的max_news_per_keyword全局设置 - 默认 不限制数量
2.5 全局过滤（[GLOBAL_FILTER]）
[GLOBAL_FILTER] 是一个特殊的分组标记，其中的过滤词对所有词组生效，优先级最高。适合过滤广告、营销等在各平台都会出现的低质量内容。[GLOBAL_FILTER]
广告
推广
优惠券
限时特价
点击领取全局过滤使用建议
全局过滤区不需要加
! 前缀，直接写词即可。该区域会影响所有词组的匹配结果，请谨慎添加。建议控制在 5-15 个过滤词，只放入确定无误的低质量内容标记。过多的全局过滤词可能会误伤正常内容。2.6 正则表达式（/pattern/）
用
/ 包裹的内容会被当作正则表达式处理，适合需要精确匹配的场景。系统会自动启用不区分大小写模式。单词边界匹配
更宽泛的边界
与其他语法组合
使用
\b 匹配单词边界，避免误匹配包含目标词的更长单词：/\bai\b/- 命中 「AI 技术突破」 -- ai 作为独立单词
- 命中 「谷歌推出新 AI 模型」 -- ai 前后有空格
- 未命中 「OPPO AirPods 降价」 -- ai 是 Air 的一部分
不会写正则？让 AI 帮你！
你不需要精通正则表达式。只需告诉 AI 助手你想匹配什么内容，让它帮你生成正则即可。例如告诉 AI：「帮我写一个正则，匹配独立的 AI 这个词，但不要匹配 AirPods 里的 AI」。
2.7 显示别名（=> 别名）
使用
=> 可以为关键词（包括正则表达式）设置一个更友好的显示名称。推送消息中将显示别名而非原始关键词。/(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
/\bgpt\b/ => GPT 模型推送效果对比：
- 不设别名时：推送标题前显示
/(?<![a-zA-Z])ai(?![a-zA-Z])/-- 难以阅读 - 设置别名后：推送标题前显示 AI 相关 -- 清晰明了
2.8 组别名（[名称]）
词组的第一行可以写
[自定义名称] 来设置该词组的显示别名。推送时将使用该别名作为词组名称展示，而非自动生成的名称。[华为]
华为
荣耀
+手机
[AI 相关]
/\bai\b/
/\bgpt\b/
+大模型效果：推送结果中，第一个词组显示为 华为，第二个词组显示为 AI 相关，而非默认的关键词拼接名。
3. 词组分组
关键词通过空行分隔成不同的「词组」，每个词组独立运作，拥有自己的关键词、必含词、过滤词和数量限制。
完整配置示例
以下展示了一个包含 3 个词组和全局过滤的完整配置文件：
[GLOBAL_FILTER]
广告
推广
优惠券
iPhone
华为
OPPO
+发布
!二手
@8
A股
上证指数
+涨跌
!预测
!荐股
世界杯
欧洲杯
+赛程4. 进阶配置
除了
frequency_words.txt 中的语法，config.yaml 中还有两个与关键词相关的全局配置项。4.1 排序方式（sort_by_position_first）
按热度排序（默认）
按配置顺序排序
report:
sort_by_position_first: false默认行为。匹配到的内容按照匹配到的热点条数排序， 条数多的词组排在前面。
4.2 全局数量限制（max_news_per_keyword）
在
config.yaml 中设置每个词组的全局推送数量上限：report:
max_news_per_keyword: 10与词组级 @ 的关系：
- 词组中的
@5会覆盖全局设置，该词组最多推送 5 条 - 没有设置
@的词组，使用全局的max_news_per_keyword值 - 设为
0表示不限制数量
4.3 完整配置联动示例
下面展示
config.yaml 和 frequency_words.txt 如何配合工作：config.yaml 关键词相关部分
report:
sort_by_position_first: false # 按热度排序
max_news_per_keyword: 10 # 全局每组最多 10 条frequency_words.txt 关键词配置
[GLOBAL_FILTER]
广告
推广
/(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
/\bgpt\b/ => GPT
+大模型
@5
特斯拉
新能源
比亚迪运行效果：
- 词组 1（AI 相关）：匹配独立的 ai/gpt 关键词，必须包含「大模型」，最多推送 5 条（词组级 @5 覆盖全局 10）
- 词组 2（新能源汽车）：匹配特斯拉/新能源/比亚迪，无必含词，最多推送 10 条（使用全局限制）
- 全局过滤：所有词组的结果中，含「广告」或「推广」的条目都会被排除
5. 配置建议
从宽到严，逐步优化
不要一开始就写大量复杂的规则。建议按以下 3 步逐步调整：
第 1 步 只写普通关键词
华为
苹果
小米先观察推送效果，看看匹配到了哪些内容，是否有太多无关信息。
第 2 步 增加必含词缩小范围
华为
苹果
小米
+手机
+发布发现推送中有太多与手机无关的内容（如「苹果水果」），加入必含词精确匹配。
第 3 步 添加过滤词排除噪音
华为
苹果
小米
+手机
+发布
!二手
!维修
@10发现仍有二手交易、维修教程等不想看的内容，加入过滤词，同时设置数量限制。
避免过度复杂
不要把所有关键词塞进一个词组
每个词组应聚焦于一个主题。不同主题的关键词放到不同词组（用空行分隔），这样每个词组可以有独立的必含词、过滤词和数量限制。
不推荐的写法
推荐的写法
# 所有关键词混在一起，无法精确控制
华为
苹果
A股
上证指数
世界杯
+发布
+涨跌
!广告配置文件支持注释
以
# 开头的行会被当作注释忽略，可以用来标记每个词组的用途，方便后续维护。6. 关键词 vs AI 筛选：如何选择？
TrendRadar 提供两种内容筛选方式，你可以根据自身需求选择：
| 对比项 | 关键词筛选 | AI 智能筛选 |
|---|---|---|
| 适合场景 | 明确知道要关注什么话题 | 兴趣宽泛，难以用关键词精确描述 |
| 成本 | 零成本，不调用任何 API | 每次运行消耗 AI token |
| 灵活度 | 规则固定，需手动维护词库 | 用自然语言描述兴趣，AI 自动理解 |
| 准确度 | 精确匹配，不会误判但可能遗漏 | 语义理解，覆盖面广但可能有误判 |
切换方式：在
config/config.yaml 中修改 filter.method：filter:
method: "keyword" # 可选值: "keyword" | "ai"AI 智能筛选的详细配置请参考 AI 智能筛选 文档页。
7. 调试与验证
检查配置是否正确加载
运行以下命令可检查配置文件是否被正确解析：
uv run python -m trendradar --doctor该命令会检查 config.yaml、frequency_words.txt 等配置文件的加载状态，并报告发现的问题。
正则错误处理
如果
frequency_words.txt 中的正则表达式语法有误，系统会打印 Warning 日志但不会中断运行。 无效的正则会被静默跳过，其余关键词继续正常工作。建议配置后运行一次查看日志，确认没有正则语法错误。推送结果验证
每次推送结果中会显示每个词组匹配到的条目数，例如「AI 相关 (5 条)」「新能源 (3 条)」。 如果某个词组始终匹配为 0 条，说明关键词配置可能需要调整（过于严格或与当前热点不匹配）。