Keyword Configuration
Keyword configuration is one of TrendRadar's core features — it determines which content from the trending lists the system filters out and pushes to you. With flexible syntax rules, you can precisely control how information is matched, filtered, and displayed.
Config file location
The keyword config file is
config/frequency_words.txt, a plain-text file with one keyword or directive per line. Lines starting with # are supported as comments, handy for labeling what each group does. You can use [WORD_GROUPS] to mark where the word-group section begins.1. Syntax cheat sheet
The table below lists every supported syntax type. If this is your first time configuring, skim it quickly, then jump to the detailed explanations below.
| Syntax type | Symbol | Purpose | Example | Matching logic |
|---|---|---|---|---|
| Plain keyword | none | Basic matching | 华为 | Matches if the title contains any one plain keyword |
| Required word | + | Narrow the match | +手机 | Must contain all required words to match |
| Filter word | ! | Exclude noise | !广告 | If a filter word is present, exclude immediately; takes priority over keyword matching |
| Count limit | @ | Limit pushed items | @10 | Push at most the specified number of items for this group |
| Global filter | [GLOBAL_FILTER] | Global exclusion | see below | Applies to all groups; highest priority |
| Regular expression | /pattern/ | Precise matching | /\bai\b/ | Matches using a regular expression; case-insensitive automatically |
| Display alias | => alias | Custom display name | /\bai\b/ => AI 相关 | Shows the alias text in the push instead of the raw keyword / regex |
2. Detailed syntax
2.1 Plain keywords
The most basic usage: write keywords directly, one per line. A trending title matches if it contains any one of the keywords.
华为
OPPO
苹果Matching examples:
- Match "华为发布新款折叠屏手机" -- contains "华为"
- Match "OPPO Find X8 正式亮相" -- contains "OPPO"
- Match "苹果将在秋季发布 iPhone" -- contains "苹果"
- No match "小米汽车 SU7 销量破万" -- contains none of the above keywords
2.2 Required words (+ prefix)
A keyword starting with
+ is a "required word". The matching rule is that the title must satisfy both conditions:- Contain at least one plain keyword
- Contain all required words
华为
OPPO
+手机Matching examples:
- Match "华为手机最新款发布" -- contains "华为" and "手机"
- No match "华为发布新款笔记本" -- contains "华为" but not "手机"
- No match "小米手机降价促销" -- contains "手机" but no plain keyword
Multiple required words
You can set multiple required words (such as
+手机 and +发布); in that case the title must contain all required words to match.2.3 Filter words (! prefix)
A keyword starting with
! is a "filter word". If the title contains any filter word, the item is excluded immediately, regardless of whether it matched other keywords.苹果
华为
!水果
!价格Matching examples:
- Match "苹果发布 M4 芯片" -- contains "苹果", no filter word
- Excluded "苹果水果价格上涨" -- contains "苹果" but also "水果" and "价格"
- Excluded "华为手机价格汇总" -- contains "华为" but also "价格"
2.4 Count limit (@ prefix)
A number starting with
@ is the maximum number of items this group will push. For example, @5 means that even if 20 items match, only the top 5 are pushed.特斯拉
马斯克
@5Priority rules:
- Highest the
@numbersetting inside the group - Next the global
max_news_per_keywordsetting inconfig.yaml - Default no count limit
2.5 Global filter ([GLOBAL_FILTER])
[GLOBAL_FILTER] is a special group marker; the filter words within it apply to all groups with the highest priority. It's ideal for filtering out low-quality content like ads and marketing that appears across all platforms.[GLOBAL_FILTER]
广告
推广
优惠券
限时特价
点击领取Advice on using the global filter
The global filter section does not require the
! prefix — just write the words directly. The global filter affects the matching results of all groups, so add to it carefully. We recommend keeping it to 5-15 filter words and only including markers of content you're certain is low quality. Too many global filter words may wrongly exclude legitimate content.2.6 Regular expressions (/pattern/)
Content wrapped in
/ is treated as a regular expression, suitable for scenarios that need precise matching. The system automatically enables case-insensitive mode.Word boundary matching
Broader boundaries
Combining with other syntax
Use
\b to match word boundaries and avoid wrongly matching longer words that contain the target word:/\bai\b/- Match "AI 技术突破" -- ai as a standalone word
- Match "谷歌推出新 AI 模型" -- ai surrounded by spaces
- No match "OPPO AirPods 降价" -- ai is part of "Air"
Can't write regex? Let AI help!
You don't need to be a regex expert. Just tell an AI assistant what you want to match and let it generate the regex for you. For example, tell the AI: "Write me a regex that matches the standalone word AI but not the AI inside AirPods."
2.7 Display alias (=> alias)
Use
=> to give a keyword (including a regular expression) a friendlier display name. The push message will show the alias instead of the raw keyword./(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
/\bgpt\b/ => GPT 模型Push display comparison:
- Without an alias: the push title is prefixed with
/(?<![a-zA-Z])ai(?![a-zA-Z])/-- hard to read - With an alias: the push title is prefixed with AI 相关 -- clear and readable
2.8 Group alias ([name])
The first line of a word group can be
[custom name] to set a display alias for that group. When pushing, this alias is shown as the group name instead of an auto-generated one.[华为]
华为
荣耀
+手机
[AI 相关]
/\bai\b/
/\bgpt\b/
+大模型Result: in the push results, the first group is shown as 华为 and the second group as AI 相关, rather than a default concatenation of the keywords.
3. Word groups
Keywords are separated into different "groups" by blank lines. Each group operates independently, with its own keywords, required words, filter words, and count limit.
Complete configuration example
The following shows a complete config file with 3 word groups and a global filter:
[GLOBAL_FILTER]
广告
推广
优惠券
iPhone
华为
OPPO
+发布
!二手
@8
A股
上证指数
+涨跌
!预测
!荐股
世界杯
欧洲杯
+赛程4. Advanced configuration
Beyond the syntax in
frequency_words.txt, config.yaml has two more global options related to keywords.4.1 Sort order (sort_by_position_first)
Sort by heat (default)
Sort by config order
report:
sort_by_position_first: falseThe default behavior. Matched content is sorted by the number of matched trending items per group. Groups with more matches are ranked higher.
4.2 Global count limit (max_news_per_keyword)
Set the global per-group cap on the number of pushed items in
config.yaml:report:
max_news_per_keyword: 10Relationship with the group-level @:
- A group's
@5overrides the global setting; that group pushes at most 5 items - A group without
@uses the globalmax_news_per_keywordvalue - Setting it to
0means no count limit
4.3 Complete combined example
The following shows how
config.yaml and frequency_words.txt work together:config.yaml keyword-related part
report:
sort_by_position_first: false # 按热度排序
max_news_per_keyword: 10 # 全局每组最多 10 条frequency_words.txt keyword config
[GLOBAL_FILTER]
广告
推广
/(?<![a-zA-Z])ai(?![a-zA-Z])/ => AI 相关
/\bgpt\b/ => GPT
+大模型
@5
特斯拉
新能源
比亚迪Resulting behavior:
- Group 1 (AI): matches the standalone keywords ai/gpt, must contain "大模型", pushes at most 5 items (the group-level @5 overrides the global 10)
- Group 2 (new-energy vehicles): matches 特斯拉/新能源/比亚迪, no required word, pushes at most 10 items (uses the global limit)
- Global filter: across all groups' results, items containing "广告" or "推广" are excluded
5. Configuration advice
From broad to strict, refine step by step
Don't write a large set of complex rules right away. We recommend adjusting in these 3 steps:
Step 1 Write only plain keywords
华为
苹果
小米First observe the push results to see what content matched and whether there's too much irrelevant information.
Step 2 Add required words to narrow the scope
华为
苹果
小米
+手机
+发布If you find too much content unrelated to phones (such as "苹果水果"), add required words for precise matching.
Step 3 Add filter words to exclude noise
华为
苹果
小米
+手机
+发布
!二手
!维修
@10If you still see unwanted content like second-hand trades or repair tutorials, add filter words and set a count limit too.
Avoid over-complexity
Don't cram all keywords into one group
Each group should focus on a single topic. Put keywords for different topics into different groups (separated by blank lines) so each group can have its own required words, filter words, and count limit.
Not recommended
Recommended
# 所有关键词混在一起，无法精确控制
华为
苹果
A股
上证指数
世界杯
+发布
+涨跌
!广告The config file supports comments
Lines starting with
# are ignored as comments. Use them to label what each group does, making future maintenance easier.6. Keyword vs AI filtering: how to choose?
TrendRadar provides two content filtering methods. Choose the one that fits your needs:
| Comparison | Keyword filtering | AI filtering |
|---|---|---|
| Best for | You know exactly what topics to follow | Your interests are broad and hard to express with keywords |
| Cost | Zero cost, no API calls | Consumes AI tokens on each run |
| Flexibility | Fixed rules, keyword list must be maintained manually | Describe interests in natural language, AI understands automatically |
| Accuracy | Exact matching, no false positives but may miss items | Semantic understanding, broader coverage but may have false positives |
To switch: change
filter.method in config/config.yaml:filter:
method: "keyword" # Options: "keyword" | "ai"For detailed AI filtering configuration, see the AI Smart Filtering docs page.
7. Debugging & verification
Check that your config loads correctly
Run the following command to verify that your config files are parsed correctly:
uv run python -m trendradar --doctorThis command checks the loading status of config.yaml, frequency_words.txt, and other config files, and reports any issues found.
Regex error handling
If a regular expression in
frequency_words.txt has a syntax error, the system prints a Warning log but does not stop running. Invalid regexes are silently skipped, and the remaining keywords continue to work normally. We recommend running once after configuration to check the logs for any regex syntax errors.Verifying push results
Each push result shows the number of matched items per group, such as "AI (5 items)", "New energy (3 items)". If a group consistently matches 0 items, the keyword configuration may need adjustment (too strict or not matching current trends).