Quirox Telegram Bot Backend

Quirox Telegram 机器人后端

本项目为 Quirox Telegram 机器人提供后端服务，包含一个 AI Agent，可与 Google Sheets、Gmail（目前已注释）以及通过 DuckDuckGo 进行网页搜索等多种工具交互。项目使用 Model Context Protocol (MCP) 管理 AI 模型（Google Gemini）与可用工具之间的通信。后端通过 FastAPI Web 服务器对外提供服务。

演示

功能

• AI Agent： 使用 Google Gemini（Flash 模型）进行推理和任务执行。
• 工具集成：
  • Google Sheets： 创建电子表格、读取/写入数据、管理工作表（列出、复制、重命名）和共享。使用 helpers/ghseet.py（通过 GoogleSheetsService）。
  • 网页搜索： 使用 DuckDuckGo 搜索网页（helpers/search_tools.py）。
  • 网页内容获取： 获取并解析 URL 中的文本内容（helpers/search_tools.py）。
  • （实验性/已禁用）Gmail： helpers/gmail_tools.py 中包含发送、读取和管理邮件的函数，但这些函数在 mcp_server.py 中似乎已被注释。
• MCP 框架：
  • mcp_server.py：运行 MCP 服务，向 AI 模型提供工具（Sheets、Search、Fetch）。
  • mcp_client.py：与 MCP 服务通信，向 Gemini 模型发送用户查询，处理工具调用并管理对话流程。
• FastAPI 接口：
  • main.py：启动 FastAPI Web 服务器，提供 /chat 端点，通过 HTTP 请求与 AI Agent 交互。

项目结构

├── README.md # 此文件 ├── .env # 环境变量（API 密钥、路径）- 必须创建 ├── .gitignore # Git 忽略规则 ├── requirements.txt # Python 依赖项 ├── main.py # FastAPI 应用程序入口 ├── mcp_client.py # 与 Gemini 和 MCP Server 交互的 MCP 客户端逻辑 ├── mcp_server.py # 提供工具的 MCP 服务 ├── helpers/ # 辅助模块和工具目录 │ ├── config.py # 加载 Gemini API 密钥 │ ├── gsheet_tools.py # （可能较旧）Google Sheets 的 MCP 工具定义 │ ├── ghseet.py # 独立的 GoogleSheetsService 类 │ ├── gmail_tools.py # Gmail 服务类和 MCP 工具定义（目前未使用） │ ├── search_tools.py # DuckDuckGo 搜索和网页内容获取器类 │ └── init.py ├── telegram_bot/ # （空/占位符？）Telegram 机器人专用代码目录 └── bot/ # （空/占位符？）另一个可能的机器人目录

## Setup

### 1. Prerequisites

*   Python 3.8+
*   Access to Google Cloud Platform for Sheets/Drive API and potentially Gmail API.
*   Google Gemini API Key.

### 2. Clone the Repository

```bash
git clone <your-repository-url>
cd <repository-directory>

3. 安装依赖项

pip install -r requirements.txt

4. 环境变量

在根目录中创建 .env 文件，可复制 .env.example（如果该文件存在），也可从头创建。添加以下变量：

# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key

# Google Cloud Credentials (Choose ONE method: Service Account or OAuth)

# Method 1: Service Account (Recommended for servers)
# Path to your service account JSON key file
SERVICE_ACCOUNT_PATH=path/to/your/service_account.json
# Optional: Google Drive Folder ID to work within
DRIVE_FOLDER_ID=your_google_drive_folder_id

# Method 2: OAuth 2.0 (Requires user interaction for the first run)
# Path to your OAuth client secrets file (credentials.json)
CREDENTIALS_PATH=path/to/your/credentials.json
# Path where the OAuth token will be stored after authorization
TOKEN_PATH=token.json # Keep default unless you have a reason to change

# Method 3: Base64 Encoded Service Account Config (Alternative)
# CREDENTIALS_CONFIG=your_base64_encoded_service_account_json_string

重要：

• 确保已在 Google Cloud 项目中启用 Google Sheets API 和 Google Drive API。
• 如果使用 OAuth（CREDENTIALS_PATH），首次运行 mcp_server.py（或使用 GoogleSheetsService/GmailService 的代码）时，会打开浏览器窗口供你授权应用程序。生成的 token.json 将被保存。
• 如果使用服务账号（SERVICE_ACCOUNT_PATH），请确保该服务账号邮箱在目标 Google Sheets 或 Drive 文件夹上拥有适当权限（例如编辑者）。

5. Google Cloud 身份验证设置

• 服务账号：
  1. 前往 Google Cloud Console -> IAM & Admin -> Service Accounts。
  2. 创建服务账号，或使用现有账号。
  3. 为服务账号创建密钥（JSON 格式）并下载。
  4. 在 .env 中将 SERVICE_ACCOUNT_PATH 设置为下载的 JSON 文件路径。
  5. 与服务账号的电子邮件地址共享指定的 Google Drive 文件夹或 Sheets。
• OAuth 2.0：
  1. 前往 Google Cloud Console -> APIs & Services -> Credentials。
  2. 创建类型为 "Desktop app" 的 "OAuth 2.0 Client ID"。
  3. 下载客户端密钥 JSON 文件。
  4. 将其重命名为 credentials.json（或更新 .env 中的 CREDENTIALS_PATH）。

使用方法

该应用由两个需要同时运行的主要部分组成：MCP 服务和 FastAPI 前端（使用 MCP 客户端）。

1. 运行 MCP 服务

此服务向 AI 提供工具（Sheets、Search）。

python mcp_server.py

请保持此终端窗口打开。

2. 运行 FastAPI 应用

这会启动用于监听聊天请求的 Web 服务。

python main.py
# or using uvicorn directly for more options:
# uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. 通过 API 交互

现在可以向 /chat 端点发送 POST 请求：

使用 curl 的示例：

curl -X POST "http://localhost:8000/chat" \
     -H "Content-Type: application/json" \
     -d '{"message": "Create an excel sheet named '\''Test Sheet'\'' and add the headers Name, Age, City in the first row."}'

响应将包含 AI 生成的最终答案；在此之前，AI 可能会通过 MCP 服务调用工具。

主要模块（helpers/）

• config.py：从环境中读取 GEMINI_API_KEY。
• search_tools.py：包含用于网页搜索的 DuckDuckGoSearcher，以及用于从 URL 获取内容的 WebContentFetcher。包含速率限制。
• ghseet.py：实现 GoogleSheetsService，以基于类的接口提供 Google Sheets 和 Drive API 操作（创建、读取、更新、批量更新、添加行/列、列出工作表、共享等）。在内部处理身份验证。
• gmail_tools.py：实现用于 Gmail 操作的 GmailService（结构与 GoogleSheetsService 类似）。包含用于电子邮件任务的 MCP 工具定义，但目前似乎已在 mcp_server.py 中禁用。
• gsheet_tools.py：包含较早的、基于函数的 Google Sheets MCP 工具定义，可能已被 ghseet.py 取代。

依赖项

主要依赖项包括：

• fastapi、uvicorn：用于 Web 服务。
• mcp：Model Context Protocol 库。
• google-api-python-client、google-auth-oauthlib、google-auth：Google API 库。
• google-generativeai：Google Gemini 客户端库。
• python-dotenv：用于加载环境变量。
• httpx、beautifulsoup4：用于网页搜索和内容获取。
• rich：用于格式化控制台输出。

完整列表请参阅 requirements.txt。