docs: 【严重文档失误】还原被不小心覆盖的 README-MCP-FAQ.md

README-MCP-FAQ.md

@@ -1,154 +1,471 @@
-# TrendRadar × Cherry Studio 部署指南 🍒
+# TrendRadar MCP 工具使用问答
 
-> **适合人群**：零编程基础的用户
+> AI 提问指南 - 如何通过对话使用新闻热点分析工具
-> **客户端**：Cherry Studio（免费开源 GUI 客户端）
+
+## ⚙️ 默认设置说明（重要！）
+
+默认采用以下优化策略，主要是为了节约 AI token 消耗：
+
+| 默认设置       | 说明                                    | 如何调整                              |
+| -------------- | --------------------------------------- | ------------------------------------- |
+| **限制条数**   | 默认返回 50 条新闻                      | 对话中说"返回前 10 条"或"给我 100 条" |
+| **时间范围**   | 默认查询今天的数据                      | 说"查询昨天"、"最近一周"或"1月1日到7日" |
+| **URL 链接**   | 默认不返回链接（节省约 160 tokens/条）  | 说"需要链接"或"包含 URL"              |
+| **关键词列表** | 默认不使用 frequency_words.txt 过滤新闻 | 只有调用"趋势话题"工具时才使用        |
+
+**⚠️ 重要：** AI 模型的选择直接影响工具调用效果，AI 越智能，调用越准确。当你解除上面的限制，比如从今天的查询，放宽到一周的查询，首先你要在本地有一周的数据，其次，token 消耗量可能会倍增（为什么说可能，比如我查询 分析'苹果'最近一周的热度趋势，如果一周中没多少苹果的新闻，那么 token消耗量可能反而很少）
+
+**💡 提示：** 当你说"最近7天"时，AI会自动计算对应的日期范围（如 2025-10-18 至 2025-10-25）并传递给工具。
+
+
+## 💰 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. 确保右上角勾选框打开后显示为 **绿色** ✅
 
 ---
 
-## 📥 第一步：下载 Cherry Studio
+### ✨ 配置完成！
 
-### Windows 用户
+现在你可以开始使用本项目，享受稳定快速的 AI 服务了！
 
-访问官网下载：https://cherry-ai.com/
+在你测试一次询问后，请立刻去 [硅基流动账单](https://cloud.siliconflow.cn/me/bills) 查询这一次的消耗量，心底有个估算。
-或直接下载：[Cherry-Studio-Windows.exe](https://github.com/kangfenmao/cherry-studio/releases/latest)
 
-### Mac 用户
 
-访问官网下载：https://cherry-ai.com/
+## 基础查询
-或直接下载：[Cherry-Studio-Mac.dmg](https://github.com/kangfenmao/cherry-studio/releases/latest)
 
+### Q1: 如何查看最新的新闻？
+
+**你可以这样问：**
+
+- "给我看看最新的新闻"
+- "查询今天的热点新闻"
+- "获取知乎和微博的最新 10 条新闻"
+- "查看最新新闻，需要包含链接"
+
+**调用的工具：** `get_latest_news`
+
+**工具返回行为：**
+
+- MCP 工具会返回所有平台的最新 50 条新闻给 AI
+- 不包含 URL 链接（节省 token）
+
+**AI 展示行为（重要）：**
+
+- ⚠️ **AI 通常会自动总结**，只展示部分新闻（如 TOP 10-20 条）
+- ✅ 如果你想看全部 50 条，需要明确要求："展示所有新闻"或"完整列出所有 50 条"
+- 💡 这是 AI 模型的自然行为，不是工具的限制
+
+**可以调整：**
+
+- 指定平台：如"只看知乎的"
+- 调整数量：如"返回前 20 条"
+- 包含链接：如"需要链接"
+- **要求完整展示**：如"展示全部，不要总结"
 
 ---
 
-## 📦 第二步：获取项目代码
+### Q2: 如何查询特定日期的新闻？
 
-为什么需要获取项目代码？
+**你可以这样问：**
 
-AI 分析功能需要读取项目中的新闻数据才能工作。无论你使用 GitHub Actions 还是 Docker 部署，爬虫生成的新闻数据都保存在项目的 output 目录中。因此，在配置 MCP 服务器之前，需要先获取完整的项目代码（包含数据文件）。
+- "查询昨天的新闻"
+- "看看 3 天前知乎的新闻"
+- "2025-10-10 的新闻有哪些"
+- "上周一的新闻"
+- "给我看看最新新闻"（自动查询今天）
 
-根据你的技术水平，可以选择以下任一方式获取：：
+**调用的工具：** `get_news_by_date`
 
-### 方法一：Git Clone（推荐给技术用户）
+**支持的日期格式：**
 
-如果你熟悉 Git，可以使用以下命令克隆项目：
+- 相对日期：今天、昨天、前天、3 天前
+- 星期：上周一、本周三、last monday
+- 绝对日期：2025-10-10、10 月 10 日
 
-```bash
+**工具返回行为：**
-git clone https://github.com/你的用户名/你的项目名.git
-cd 你的项目名
-```
 
-**优点**：
+- 不指定日期时自动查询今天（节省 token）
+- MCP 工具会返回所有平台的 50 条新闻给 AI
+- 不包含 URL 链接
 
-- 可以随时拉取一个命令就可以更新最新数据到本地了（`git pull`）
+**AI 展示行为（重要）：**
 
-### 方法二：直接下载 ZIP 压缩包（推荐给初学者）
+- ⚠️ **AI 通常会自动总结**，只展示部分新闻（如 TOP 10-20 条）
-
+- ✅ 如果你想看全部，需要明确要求："展示所有新闻，不要总结"
-
-1. **访问 GitHub 项目页面**
-
-   - 项目链接：`https://github.com/你的用户名/你的项目名`
-
-2. **下载压缩包**
-
-   - 点击绿色的 "Code" 按钮
-   - 选择 "Download ZIP"
-   - 或直接访问：`https://github.com/你的用户名/你的项目名/archive/refs/heads/master.zip`
-
-
-**注意事项**：
-
-- 步骤稍微麻烦，后续更新数据需要重复上面步骤，然后覆盖本地数据(output 目录)
 
 ---
 
-## 🚀 第三步：一键部署 MCP 服务器
+### Q3: 如何查看我关注的话题频率统计？
 
-### Windows 用户
+**你可以这样问：**
 
-1. **双击运行**项目文件夹中的 `setup-windows.bat`，如果有问题，就运行 `setup-windows-en.bat`
+- "我关注的词今天出现了多少次"
-2. **等待安装完成**
+- "看看我的关注词列表中哪些词最热门"
-3. **记录显示的配置信息**（命令路径和参数）
+- "统计一下 frequency_words.txt 中的关注词频率"
 
-### Mac 用户
+**调用的工具：** `get_trending_topics`
 
-1. **打开终端**（在启动台搜索"终端"）
+**重要说明：**
-2. **拖拽**项目文件夹中的 `setup-mac.sh` 到终端窗口
+
-3. **按回车键**
+- 本工具**不是**自动提取新闻热点
-4. **记录显示的配置信息**
+- 而是统计你在 `config/frequency_words.txt` 中设置的**个人关注词**
+- 这是一个**可自定义**的列表，你可以根据兴趣添加关注词
 
 ---
 
-## 🔧 第四步：配置 Cherry Studio
+## 搜索检索
 
-### 1. 打开设置
+### Q4: 如何搜索包含特定关键词的新闻？
 
-启动 Cherry Studio，点击右上角 ⚙️ **设置** 按钮
+**你可以这样问：**
 
-### 2. 添加 MCP 服务器
+- "搜索包含'人工智能'的新闻"
+- "查找关于'特斯拉降价'的报道"
+- "搜索马斯克相关的新闻，返回前 20 条"
+- "查找最近7天关于'iPhone 16'的新闻"
+- "查找2025年1月1日到7日'特斯拉'的相关新闻"
+- "查找'iPhone 16 发布'这条新闻的链接"
 
-在设置页面找到：**MCP** → 点击 **添加**
+**调用的工具：** `search_news`
 
-### 3. 填写配置（重要！）
+**工具返回行为：**
 
-根据刚才的安装脚本显示的信息填写
+- 使用关键词模式搜索
+- 默认搜索今天的数据
+- AI会自动将"最近7天"、"上周"等相对时间转换为具体日期范围
+- MCP 工具会返回最多 50 条结果给 AI
+- 不包含 URL 链接
 
-### 4. 保存并启用
+**AI 展示行为（重要）：**
 
-- 点击 **保存** 按钮
+- ⚠️ **AI 通常会自动总结**，只展示部分搜索结果
-- 确保 MCP 服务器列表中的开关是 **开启** 状态 ✅
+- ✅ 如果你想看全部，需要明确要求："展示所有搜索结果"
+
+**可以调整：**
+
+- 指定时间范围：
+  - 相对方式："搜索最近一周的"（AI 自动计算日期）
+  - 绝对日期："搜索2025年1月1日到7日的"
+- 指定平台：如"只搜索知乎"
+- 调整排序：如"按权重排序"
+- 包含链接：如"需要链接"
+
+**示例对话：**
+
+```
+用户：搜索最近7天关于"人工智能突破"的新闻
+AI：（自动计算：date_range={"start": "2025-10-18", "end": "2025-10-25"}）
+
+用户：查找2025年1月的"特斯拉"报道
+AI：（date_range={"start": "2025-01-01", "end": "2025-01-31"}）
+```
 
 ---
 
-## ✅ 第五步：验证是否成功
+### Q5: 如何查找历史相关新闻？
 
-### 1. 测试连接
+**你可以这样问：**
 
-在 Cherry Studio 的对话框中输入：
+- "查找昨天与'人工智能突破'相关的新闻"
+- "搜索上周关于'特斯拉'的历史报道"
+- "找出上个月与'ChatGPT'相关的新闻"
+- "看看'iPhone 发布会'相关的历史新闻"
 
-```
+**调用的工具：** `search_related_news_history`
-帮我爬取最新的新闻
-```
 
-或者尝试其他测试命令：
+**工具返回行为：**
 
-```
+- 搜索昨天的数据
-搜索最近3天关于"人工智能"的新闻
+- 相似度阈值 0.4
-查找2025年1月的"特斯拉"相关报道
+- MCP 工具会返回最多 50 条结果给 AI
-分析"iPhone"的热度趋势
+- 不包含 URL 链接
-```
 
-**提示**：当你说"最近3天"时，AI会自动计算日期范围并搜索。
+**AI 展示行为（重要）：**
-
-### 2. 成功标志
-
-如果配置成功，AI 会：
-
-- ✅ 调用 TrendRadar 工具
-- ✅ 返回真实的新闻数据
-- ✅ 显示平台、标题、排名等信息
 
+- ⚠️ **AI 通常会自动总结**，只展示部分相关新闻
+- ✅ 如果你想看全部，需要明确要求："展示所有相关新闻"
 
 ---
 
-## 🎯 进阶配置
+## 趋势分析
 
-### HTTP 模式（可选）
+### Q6: 如何分析话题的热度趋势？
 
-如果需要远程访问或多客户端共享，可以使用 HTTP 模式：
+**你可以这样问：**
 
-#### Windows
+- "分析'人工智能'最近一周的热度趋势"
+- "看看'特斯拉'话题是昙花一现还是持续热点"
+- "检测今天有哪些突然爆火的话题"
+- "预测接下来可能的热点话题"
+- "分析'比特币'在2024年12月的生命周期"
 
-双击运行 `start-http.bat`
+**调用的工具：** `analyze_topic_trend`
 
-#### Mac
+**工具返回行为：**
 
-```bash
+- 支持多种分析模式：热度趋势、生命周期、异常检测、预测
-./start-http.sh
+- AI会自动将"最近一周"等相对时间转换为具体日期范围
-```
+- 默认分析最近7天数据
+- 按天粒度统计
 
-然后在 Cherry Studio 中配置：
+**AI 展示行为：**
+
+- 通常会展示趋势分析结果和图表
+- AI 可能会总结关键发现
+
+**示例对话：**
 
 ```
-类型: streamableHttp
+用户：分析'人工智能'最近一周的生命周期
-URL: http://localhost:3333/mcp
+AI：（自动计算：date_range={"start": "2025-10-18", "end": "2025-10-25"}）
+
+用户：看看'比特币'在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 通常会总结爬取结果**，只展示部分新闻
+- ✅ 如果你想看全部，需要明确要求："展示所有爬取的新闻"
+
+**可以调整：**
+
+- 指定平台：如"只爬取知乎"
+- 保存数据：说"并保存"或"保存到本地"
+- 包含链接：说"需要链接"
+
+---
+
+## 💡 使用技巧
+
+### 1. 如何让 AI 展示全部数据而不是自动总结？
+
+**背景**: 有时 AI 会自动总结数据，只展示部分内容，即使工具返回了完整的 50 条数据。
+
+**如果 AI 仍然总结，你可以**:
+
+- **方法 1 - 明确要求**: "请展示全部新闻，不要总结"
+- **方法 2 - 指定数量**: "展示所有 50 条新闻"
+- **方法 3 - 质疑行为**: "为什么只展示了 15 条？我要看全部"
+- **方法 4 - 提前说明**: "查询今天的新闻，完整展示所有结果"
+
+**注意**: AI 仍可能根据上下文调整展示方式。
+
+
+### 2. 如何组合使用多个工具？
+
+**示例：深度分析某个话题**
+
+1. 先搜索："搜索'人工智能'相关新闻"
+2. 再分析趋势："分析'人工智能'的热度趋势"
+3. 最后情感分析："分析'人工智能'新闻的情感倾向"
+
+**示例：追踪某个事件**
+
+1. 查看最新："查询今天关于'iPhone'的新闻"
+2. 查找历史："查找上周与'iPhone'相关的历史新闻"
+3. 找相似报道："找出和'iPhone 发布会'相似的新闻"