<div align="center">

**中文** | **[English](README-MCP-FAQ-EN.md)**

</div>

# TrendRadar MCP 工具使用问答

> AI 提问指南 - 如何通过对话使用新闻热点分析工具

## ⚙️ 默认设置说明（重要！）

默认采用以下优化策略，主要是为了节约 AI token 消耗：

| 默认设置       | 说明                                    | 如何调整                              |
| -------------- | --------------------------------------- | ------------------------------------- |
| **限制条数**   | 默认返回 50 条新闻                      | 对话中说"返回前 10 条"或"给我 100 条" |
| **时间范围**   | 默认查询今天的数据                      | 说"查询昨天"、"最近一周"或"1月1日到7日" |
| **URL 链接**   | 默认不返回链接（节省约 160 tokens/条）  | 说"需要链接"或"包含 URL"              |
| **关键词列表** | 默认不使用 frequency_words.txt 过滤新闻 | 只有调用"趋势话题"工具时才使用        |

**⚠️ 重要：** AI 模型的选择直接影响工具调用效果，AI 越智能，调用越准确。当你解除上面的限制，比如从今天的查询，放宽到一周的查询，首先你要在本地有一周的数据，其次，token 消耗量可能会倍增（为什么说可能，比如我查询 分析'苹果'最近一周的热度趋势，如果一周中没多少苹果的新闻，那么 token消耗量可能反而很少）

**💡 提示：** 本项目提供了专门的日期解析工具 `resolve_date_range`，可以准确解析"最近7天"、"本周"等自然语言日期表达式，确保所有 AI 模型获得一致的日期范围。推荐优先使用该工具，详见下方 Q14。


## 💰 AI 模型

下面我以 **[硅基流动](https://cloud.siliconflow.cn)** 平台作为例子，里面有很多大模型可选择。在开发和测试本项目的过程中，我使用本平台进行了许多的功能测试和验证。

### 📊 注册方式对比

| 注册方式 | 无邀请链接直接注册 | 含有邀请链接注册  |
|:-------:|:-------:|:-----------------:|
| 注册链接 | [siliconflow.cn](https://cloud.siliconflow.cn) | [邀请链接](https://cloud.siliconflow.cn/i/fqnyVaIU) |
| 免费额度 | 0 tokens | **2000万 tokens** (≈14元) |
| 额外福利 | ❌ | ✅ 邀请者也获得2000万tokens |

> 💡 **提示**：上面的赠送额度，应该可以询问 **200次以上**


### 🚀 快速开始

#### 1️⃣ 注册并获取 API 密钥

1. 使用上方链接完成注册
2. 访问 [API 密钥管理页面](https://cloud.siliconflow.cn/me/account/ak)
3. 点击「新建 API 密钥」
4. 复制生成的密钥（请妥善保管）

#### 2️⃣ 在 Cherry Studio 中配置

1. 打开 **Cherry Studio**
2. 进入「模型服务」设置
3. 找到「硅基流动」
4. 将复制的密钥粘贴到 **[API密钥]** 输入框
5. 确保右上角勾选框打开后显示为 **绿色** ✅

---

### ✨ 配置完成！

现在你可以开始使用本项目，享受稳定快速的 AI 服务了！

在你测试一次询问后，请立刻去 [硅基流动账单](https://cloud.siliconflow.cn/me/bills) 查询这一次的消耗量，心底有个估算。


## 基础查询

### Q1: 如何查看最新的新闻？

**你可以这样问：**

- "给我看看最新的新闻"
- "查询今天的热点新闻"
- "获取知乎和微博的最新 10 条新闻"
- "查看最新新闻，需要包含链接"

**调用的工具：** `get_latest_news`

**工具返回行为：**

- MCP 工具会返回所有平台的最新 50 条新闻给 AI
- 不包含 URL 链接（节省 token）

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会自动总结**，只展示部分新闻（如 TOP 10-20 条）
- ✅ 如果你想看全部 50 条，需要明确要求："展示所有新闻"或"完整列出所有 50 条"
- 💡 这是 AI 模型的自然行为，不是工具的限制

**可以调整：**

- 指定平台：如"只看知乎的"
- 调整数量：如"返回前 20 条"
- 包含链接：如"需要链接"
- **要求完整展示**：如"展示全部，不要总结"

---

### Q2: 如何查询特定日期的新闻？

**你可以这样问：**

- "查询昨天的新闻"
- "看看 3 天前知乎的新闻"
- "2025-10-10 的新闻有哪些"
- "上周一的新闻"
- "给我看看最新新闻"（自动查询今天）

**调用的工具：** `get_news_by_date`

**支持的日期格式：**

- 相对日期：今天、昨天、前天、3 天前
- 星期：上周一、本周三、last monday
- 绝对日期：2025-10-10、10 月 10 日

**工具返回行为：**

- 不指定日期时自动查询今天（节省 token）
- MCP 工具会返回所有平台的 50 条新闻给 AI
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会自动总结**，只展示部分新闻（如 TOP 10-20 条）
- ✅ 如果你想看全部，需要明确要求："展示所有新闻，不要总结"

---

### Q3: 如何查看我关注的话题频率统计？

**你可以这样问：**

- "我关注的词今天出现了多少次"
- "看看我的关注词列表中哪些词最热门"
- "统计一下 frequency_words.txt 中的关注词频率"

**调用的工具：** `get_trending_topics`

**重要说明：**

- 本工具**不是**自动提取新闻热点
- 而是统计你在 `config/frequency_words.txt` 中设置的**个人关注词**
- 这是一个**可自定义**的列表，你可以根据兴趣添加关注词

---

## 搜索检索

### Q4: 如何搜索包含特定关键词的新闻？

**你可以这样问：**

- "搜索包含'人工智能'的新闻"
- "查找关于'特斯拉降价'的报道"
- "搜索马斯克相关的新闻，返回前 20 条"
- "查找最近7天关于'iPhone 16'的新闻"
- "查找2025年1月1日到7日'特斯拉'的相关新闻"
- "查找'iPhone 16 发布'这条新闻的链接"

**调用的工具：** `search_news`

**工具返回行为：**

- 使用关键词模式搜索
- 默认搜索今天的数据
- AI会自动将"最近7天"、"上周"等相对时间转换为具体日期范围
- MCP 工具会返回最多 50 条结果给 AI
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会自动总结**，只展示部分搜索结果
- ✅ 如果你想看全部，需要明确要求："展示所有搜索结果"

**可以调整：**

- 指定时间范围：
  - 相对方式："搜索最近一周的"（AI 自动计算日期）
  - 绝对日期："搜索2025年1月1日到7日的"
- 指定平台：如"只搜索知乎"
- 调整排序：如"按权重排序"
- 包含链接：如"需要链接"

**推荐使用流程：**

```
用户：搜索最近7天关于"人工智能突破"的新闻
推荐步骤：
1. 先调用 resolve_date_range("最近7天") 获取精确日期范围
2. 再调用 search_news 并传入日期范围

用户：查找2025年1月的"特斯拉"报道
AI：（date_range={"start": "2025-01-01", "end": "2025-01-31"}）
```

---

### Q5: 如何查找历史相关新闻？

**你可以这样问：**

- "查找昨天与'人工智能突破'相关的新闻"
- "搜索上周关于'特斯拉'的历史报道"
- "找出上个月与'ChatGPT'相关的新闻"
- "看看'iPhone 发布会'相关的历史新闻"

**调用的工具：** `search_related_news_history`

**工具返回行为：**

- 搜索昨天的数据
- 相似度阈值 0.4
- MCP 工具会返回最多 50 条结果给 AI
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会自动总结**，只展示部分相关新闻
- ✅ 如果你想看全部，需要明确要求："展示所有相关新闻"

---

## 趋势分析

### Q6: 如何分析话题的热度趋势？

**你可以这样问：**

- "分析'人工智能'最近一周的热度趋势"
- "看看'特斯拉'话题是昙花一现还是持续热点"
- "检测今天有哪些突然爆火的话题"
- "预测接下来可能的热点话题"
- "分析'比特币'在2024年12月的生命周期"

**调用的工具：** `analyze_topic_trend`

**工具返回行为：**

- 支持多种分析模式：热度趋势、生命周期、异常检测、预测
- AI会自动将"最近一周"等相对时间转换为具体日期范围
- 默认分析最近7天数据
- 按天粒度统计

**AI 展示行为：**

- 通常会展示趋势分析结果和图表
- AI 可能会总结关键发现

**推荐使用流程：**

```
用户：分析'人工智能'最近一周的生命周期
推荐步骤：
1. 先调用 resolve_date_range("最近一周") 获取精确日期范围
2. 再调用 analyze_topic_trend 并传入日期范围

用户：看看'比特币'在2024年12月是昙花一现还是持续热点
AI：（date_range={"start": "2024-12-01", "end": "2024-12-31"}）
```

---

## 数据洞察

### Q7: 如何对比不同平台对话题的关注度？

**你可以这样问：**

- "对比各个平台对'人工智能'话题的关注度"
- "看看哪个平台更新最频繁"
- "分析一下哪些关键词经常一起出现"

**调用的工具：** `analyze_data_insights`

**三种洞察模式：**

| 模式           | 功能             | 示例问法                   |
| -------------- | ---------------- | -------------------------- |
| **平台对比**   | 对比各平台关注度 | "对比各平台对'AI'的关注度" |
| **活跃度统计** | 统计平台发布频率 | "看看哪个平台更新最频繁"   |
| **关键词共现** | 分析关键词关联   | "哪些关键词经常一起出现"   |

**工具返回行为：**

- 平台对比模式
- 分析今天的数据
- 关键词共现最小频次 3 次

**AI 展示行为：**

- 通常会展示分析结果和统计数据
- AI 可能会总结洞察发现

---

## 情感分析

### Q8: 如何分析新闻的情感倾向？

**你可以这样问：**

- "分析一下今天新闻的情感倾向"
- "看看'特斯拉'相关新闻是正面还是负面的"
- "分析各平台对'人工智能'的情感态度"
- "看看'比特币'一周内的情感倾向，选择前 20 条最重要的"

**调用的工具：** `analyze_sentiment`

**工具返回行为：**

- 分析今天的数据
- MCP 工具会返回最多 50 条新闻给 AI
- 按权重排序（优先展示重要新闻）
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ 本工具返回 **AI 提示词**，不是直接的情感分析结果
- AI 会根据提示词生成情感分析报告
- 通常会展示情感分布、关键发现和代表性新闻

**可以调整：**

- 指定话题：如"关于'特斯拉'"
- 指定时间：如"最近一周"
- 调整数量：如"返回前 20 条"

---

### Q9: 如何查找相似的新闻报道？

**你可以这样问：**

- "找出和'特斯拉降价'相似的新闻"
- "查找关于 iPhone 发布的类似报道"
- "看看有没有和这条新闻相似的报道"
- "找相似新闻，需要链接"

**调用的工具：** `find_similar_news`

**工具返回行为：**

- 相似度阈值 0.6
- MCP 工具会返回最多 50 条结果给 AI
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会自动总结**，只展示部分相似新闻
- ✅ 如果你想看全部，需要明确要求："展示所有相似新闻"

---

### Q10: 如何生成每日或每周的热点摘要？

**你可以这样问：**

- "生成今天的新闻摘要报告"
- "给我一份本周的热点总结"
- "生成过去 7 天的新闻分析报告"

**调用的工具：** `generate_summary_report`

**报告类型：**

- 每日摘要：总结当天的热点新闻
- 每周摘要：总结一周的热点趋势

---

## 系统管理

### Q11: 如何查看系统配置？

**你可以这样问：**

- "查看当前系统配置"
- "显示配置文件内容"
- "有哪些可用的平台？"
- "当前的权重配置是什么？"

**调用的工具：** `get_current_config`

**可以查询：**

- 可用平台列表
- 爬虫配置（请求间隔、超时设置）
- 权重配置（排名权重、频次权重）
- 通知配置（钉钉、微信）

---

### Q12: 如何检查系统运行状态？

**你可以这样问：**

- "检查系统状态"
- "系统运行正常吗？"
- "最后一次爬取是什么时候？"
- "有多少天的历史数据？"

**调用的工具：** `get_system_status`

**返回信息：**

- 系统版本和状态
- 最后爬取时间
- 历史数据天数
- 健康检查结果

---

### Q13: 如何手动触发爬取任务？

**你可以这样问：**

- "请你爬取当前的今日头条的新闻"（临时查询）
- "帮我抓取一下知乎和微博的最新新闻并保存"（持久化）
- "触发一次爬取并保存数据"（持久化）
- "获取 36 氪 的实时数据但不保存"（临时查询）

**调用的工具：** `trigger_crawl`

**两种模式：**

| 模式           | 用途                 | 示例                 |
| -------------- | -------------------- | -------------------- |
| **临时爬取**   | 只返回数据不保存     | "爬取今日头条的新闻" |
| **持久化爬取** | 保存到 output 文件夹 | "抓取并保存知乎新闻" |

**工具返回行为：**

- 临时爬取模式（不保存）
- 爬取所有平台
- 不包含 URL 链接

**AI 展示行为（重要）：**

- ⚠️ **AI 通常会总结爬取结果**，只展示部分新闻
- ✅ 如果你想看全部，需要明确要求："展示所有爬取的新闻"

**可以调整：**

- 指定平台：如"只爬取知乎"
- 保存数据：说"并保存"或"保存到本地"
- 包含链接：说"需要链接"

---

## 存储同步

### Q14: 如何从远程存储同步数据到本地？

**你可以这样问：**

- "从远程同步最近 7 天的数据"
- "拉取远程存储的数据到本地"
- "同步最近 30 天的新闻数据"

**调用的工具：** `sync_from_remote`

**使用场景：**

- 爬虫部署在云端（如 GitHub Actions），数据存储到远程（如 Cloudflare R2）
- MCP Server 部署在本地，需要从远程拉取数据进行分析

**返回信息：**

- synced_files: 成功同步的文件数量
- synced_dates: 成功同步的日期列表
- skipped_dates: 跳过的日期（本地已存在）
- failed_dates: 失败的日期及错误信息

**前提条件：**

需要在 `config/config.yaml` 中配置远程存储或设置环境变量：
- `S3_ENDPOINT_URL`: 服务端点
- `S3_BUCKET_NAME`: 存储桶名称
- `S3_ACCESS_KEY_ID`: 访问密钥 ID
- `S3_SECRET_ACCESS_KEY`: 访问密钥

---

### Q15: 如何查看存储状态？

**你可以这样问：**

- "查看当前存储状态"
- "存储配置是什么"
- "本地有多少数据"
- "远程存储配置了吗"

**调用的工具：** `get_storage_status`

**返回信息：**

| 类别 | 信息 |
|------|------|
| **本地存储** | 数据目录、总大小、日期数量、日期范围 |
| **远程存储** | 是否配置、端点地址、存储桶名称、日期数量 |
| **拉取配置** | 是否启用自动拉取、拉取天数 |

---

### Q16: 如何查看可用的数据日期？

**你可以这样问：**

- "本地有哪些日期的数据"
- "远程存储有哪些日期"
- "对比本地和远程的数据日期"
- "哪些日期只在远程有"

**调用的工具：** `list_available_dates`

**三种查询模式：**

| 模式 | 说明 | 示例问法 |
|------|------|---------|
| **local** | 仅查看本地 | "本地有哪些日期" |
| **remote** | 仅查看远程 | "远程有哪些日期" |
| **both** | 对比两者（默认） | "对比本地和远程的数据" |

**返回信息（both 模式）：**

- only_local: 仅本地存在的日期
- only_remote: 仅远程存在的日期（可用于决定同步哪些日期）
- both: 两边都存在的日期

---

### Q17: 如何解析自然语言日期表达式？（推荐优先使用）

**你可以这样问：**

- "解析'本周'是哪几天"
- "最近7天对应的日期范围是什么"
- "上月的日期范围"
- "帮我把'最近30天'转换为具体日期"

**调用的工具：** `resolve_date_range`

**为什么需要这个工具？**

用户经常使用"本周"、"最近7天"等自然语言表达日期，但不同的 AI 模型自行计算日期时会产生不一致的结果。此工具使用服务器端的精确时间计算，确保所有 AI 模型获得一致的日期范围。

**支持的日期表达式：**

| 类型 | 中文表达 | 英文表达 |
|------|---------|---------|
| 单日 | 今天、昨天 | today, yesterday |
| 周 | 本周、上周 | this week, last week |
| 月 | 本月、上月 | this month, last month |
| 最近N天 | 最近7天、最近30天 | last 7 days, last 30 days |
| 动态 | 最近N天（任意数字） | last N days |

**返回格式：**

```json
{
  "success": true,
  "expression": "本周",
  "date_range": {
    "start": "2025-11-18",
    "end": "2025-11-26"
  },
  "current_date": "2025-11-26",
  "description": "本周（周一到周日，11-18 至 11-26）"
}
```

**推荐使用流程：**

```
用户：分析 AI 本周的情感倾向
推荐步骤：
1. AI 先调用 resolve_date_range("本周") → 获取 {"start": "2025-11-18", "end": "2025-11-26"}
2. AI 调用 analyze_sentiment(topic="AI", date_range=上一步返回的date_range)

用户：看看最近7天的特斯拉新闻
推荐步骤：
1. AI 调用 resolve_date_range("最近7天") → 获取精确日期范围
2. AI 调用 search_news(query="特斯拉", date_range=上一步返回的date_range)
```

**使用优势：**

- ✅ **一致性**：所有 AI 模型获得相同的日期范围
- ✅ **准确性**：基于服务器端 Python `datetime.now()` 计算
- ✅ **标准化**：返回标准 `YYYY-MM-DD` 格式
- ✅ **灵活性**：支持中英文、动态天数（最近N天）

---

## 💡 使用技巧

### 1. 如何让 AI 展示全部数据而不是自动总结？

**背景**: 有时 AI 会自动总结数据，只展示部分内容，即使工具返回了完整的 50 条数据。

**如果 AI 仍然总结，你可以**:

- **方法 1 - 明确要求**: "请展示全部新闻，不要总结"
- **方法 2 - 指定数量**: "展示所有 50 条新闻"
- **方法 3 - 质疑行为**: "为什么只展示了 15 条？我要看全部"
- **方法 4 - 提前说明**: "查询今天的新闻，完整展示所有结果"

**注意**: AI 仍可能根据上下文调整展示方式。


### 2. 如何组合使用多个工具？

**示例：深度分析某个话题**

1. 先搜索："搜索'人工智能'相关新闻"
2. 再分析趋势："分析'人工智能'的热度趋势"
3. 最后情感分析："分析'人工智能'新闻的情感倾向"

**示例：追踪某个事件**

1. 查看最新："查询今天关于'iPhone'的新闻"
2. 查找历史："查找上周与'iPhone'相关的历史新闻"
3. 找相似报道："找出和'iPhone 发布会'相似的新闻"