Telegram News Aggregator

Telegram新闻聚合器

从Telegram群组收集、处理和展示内容的完整系统。

📁 项目结构

telegram-news-aggregator/
├── README.md
├── requirements.txt
├── .env.example
├── config.py
├── src/
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── telegram_agent.py
│   │   └── content_processor.py
│   ├── backend/
│   │   ├── __init__.py
│   │   ├── app.py
│   │   └── database.py
│   └── frontend/
│       ├── index.html
│       ├── styles.css
│       └── script.js
└── data/
    └── posts.db (se genera automáticamente)

🚀 安装

1. 克隆仓库

git clone 
cd telegram-news-aggregator

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

3. 安装依赖项

pip install -r requirements.txt

注\requirements.txt\ 文件包含了核心依赖项以及为实现完整功能（如图像生成、快速解析等）所建议的可选依赖项。如果你在 Windows 上遇到编译错误（特别是与 lxml)，请参阅下面的故障排除部分。

可用的帮助脚本：

• scripts/setup_windows.ps1用于Windows上稳健安装的自动化脚本
• scripts/test_generate_image.py图像生成功能测试脚本

4. 运行系统

选项1：自动化脚本（推荐用于Windows）

.\run_system.ps1

选项2：手动执行

# Activar entorno virtual
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Ejecutar
python run.py

⚙️ 设置

Telegram的MCP服务器

该项目假定你已经配置并运行了服务器 telegram-mcp。 在启动代理之前，请确保其正在运行。

环境变量（.env）

• TELEGRAM_GROUP_NAME要监控的Telegram群组/频道名称
• IMAGE_API_KEY用于生成图像的API密钥（可选）
• IMAGE_API_URL图像生成服务的URL
• CHECK_INTERVAL检查新消息的间隔时间（秒）（默认：300）
• DATABASE_PATHSQLite数据库路径（默认：data/posts.db）
• FLASK_PORTFlask 服务器的端口（默认：5000）

🎯 使用

1. 启动后端（Flask API）

python src/backend/app.py

服务器将在 http://localhost:5000

2. 启动Telegram代理

python src/agent/telegram_agent.py

特工将开始监控Telegram群组，并处理新的URL。

3. 访问前端界面

在你的浏览器中打开：

http://localhost:5000

📡 API 接口端点

POST /api/posts 翻译为中文是：“向 /api/posts 发送 POST 请求”

创建一篇新帖子

{
  "title": "Título del post",
  "summary": "Resumen breve del contenido",
  "source_url": "https://ejemplo.com/articulo",
  "image_url": "https://ejemplo.com/imagen.jpg",
  "release_date": "2025-10-05",
  "provider": "Nombre del Proveedor",
  "type": "Artículo de Blog"
}

获取 /api/posts（资源）

获取所有帖子

{
  "posts": [
    {
      "id": 1,
      "title": "...",
      "summary": "...",
      ...
    }
  ]
}

GET /api/posts/ 的中文翻译可以是：“获取 /api/posts/ 资源”。不过，在实际应用中，这样的翻译可能不太常见，因为“/api/posts/”通常是一个API端点，直接翻译可能无法完全传达其在API上下文中的意义。但为了保持翻译的通用性，上述翻译是一个较为直观的表达。如果需要更具体的上下文解释，可以进一步说明这个API端点的作用，比如“获取文章列表”或“获取所有帖子信息”，具体取决于该API的实际功能

通过ID获取特定帖子

🔧 组件

Telegram代理（telegram_agent.py)

• 连接到Telegram的MCP服务器
• 从上次运行恢复消息
• 在消息中识别URL
• 内容处理外包

内容处理器（content_processor.py)

• 从URL中提取信息（标题、摘要、图片）
• 在没有可用图像时生成图像
• 整理帖子数据

后端 Flask（app.py）

• 用于管理帖子的REST API
• 前端已启用CORS
• 数据验证

数据库（database.py)

• SQLite用于本地存储
• “帖子”表的管理
• CRUD操作

前端

• index.html（通常翻译为“首页文件”或保持原样，因为“index.html”在中文环境中也常直接使用）页面结构
• styles.css（样式表文件）响应式与现代设计
• script.js（通常可直接译为“脚本.js”，在编程或网页开发语境中，它指的是一个JavaScript脚本文件）与API交互，动态渲染

🛠️ 技术

• Python 3.8或更高版本
• Flask（一个轻量级的Web应用框架，常用于Python开发）网络框架
• SQLite数据库
• BeautifulSoup4网络爬虫（或网页抓取）
• 请求：HTTP 客户端
• MCP（模型上下文协议）与Telegram集成

📝 重要笔记

1. 服务器 telegram-mcp 在启动代理之前，它必须已经在运行
2. 数据库在首次启动时自动创建
3. 代理保存最后一次执行的时间戳以避免重复
4. 前端每30秒自动重新加载

🐛 故障排除

错误：“无法连接到MCP服务器”

• 检查 telegram-mcp 是否正在运行
• 检查进程的PID

错误：“未找到Telegram群组”

• 检查.env文件中的名称
• 确保机器人可以访问该群组

错误：“图片API无响应”

• 验证你的API密钥
• 检查服务的URL

Windows：构建wheel时出错（lxml / Microsoft C++ 构建工具）

• 在安装依赖项时，如果你看到类似以下的错误：

  error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools"

这意味着 pip 尝试编译一个依赖项（例如 lxml) 并且没有找到适用于你版本的Python/Windows的预编译轮子（wheel）。

• 建议：运行准备好的脚本 scripts/setup_windows.ps1 从PowerShell（以管理员身份）。脚本将尝试：

1. 更新 pip/setuptools/wheel 1. 安装依赖项时优先使用二进制轮子 1. 使用（某种方法/工具）进行回退 pip 正常 1. 如果失败，请尝试安装 lxml 通过 pipwin （预编译的轮子） 1. 如果一切失败，建议通过安装Visual C++构建工具 winget 或下载安装程序

要运行它：

  # Abre PowerShell como Administrador
  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  .\scripts\setup_windows.ps1

如果你不想运行脚本，请按照上一节中关于安装Visual C++构建工具的说明操作，或者下载预编译的轮子以 lxml。

📄 许可证

MIT 许可证 - 您可以自由使用和修改此项目。

🤝 贡献

欢迎贡献。请先打开一个议题来讨论较大的更改。