关键词配置

关键词配置是 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股
上证指数
+涨跌
!预测
!荐股

世界杯
欧洲杯
+赛程

词组 1：手机数码

普通关键词：iPhone、华为、OPPO

必含词：+发布

过滤词：!二手

数量限制：@8（最多 8 条）

匹配示例：

命中「iPhone 17 发布日期确认」 -- 含 iPhone + 发布
命中「华为 Pura 80 正式发布」 -- 含华为 + 发布
未命中「iPhone 15 降价促销」 -- 含 iPhone 但不含「发布」
排除「二手 iPhone 交易指南」 -- 含过滤词「二手」
排除「OPPO 发布推广活动」 -- 全局过滤「推广」生效

词组 2：股市行情

词组 3：体育赛事

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 条，说明关键词配置可能需要调整（过于严格或与当前热点不匹配）。