NCSA-DR 每日總結機器人

使用 Gemini AI 生成 Discord 頻道訊息每日總結的機器人。

功能特色

• 🤖 Discord 整合: 支援文字頻道、論壇頻道、舞台頻道等多種頻道類型
• 🧠 AI 摘要: 使用 Google Gemini 進行智慧訊息摘要
• ⏰ 定時處理: 每日 23:59 台灣時間生成總結（支援時區重疊處理）
• 📊 結構化輸出: 包含頻道重點、行動項目和連結的組織化總結
• 🔒 隱私控制: 可配置的頻道和使用者允許/拒絕清單
• 🐳 多種部署: 支援原生 systemd 和 Docker 部署
• 📝 完整日誌: 結構化日誌記錄與輪轉
• 🏥 健康監控: 內建健康檢查端點

快速開始

前置需求

• Python 3.11 或更高版本
• Discord Bot Token
• Google Gemini API Key
• Git

安裝步驟

1. 複製專案:

   git clone <repository-url>
   cd ntnu-csie-sa-daily-recap

2. 建立虛擬環境:

   # 使用 venv（推薦）
   python3 -m venv .venv
   
   # 啟用虛擬環境
   # Linux/macOS:
   source .venv/bin/activate
   # Windows:
   # .venv\Scripts\activate
   
   # 升級 pip
   pip install --upgrade pip wheel

3. 安裝依賴套件:

   # 方法 1: 使用 pyproject.toml（推薦）
   pip install -e .[dev]  # 包含開發工具
   # 或
   pip install -e .       # 僅基本依賴
   
   # 方法 2: 使用 requirements.txt
   pip install -r requirements.txt        # 基本依賴
   pip install -r requirements-dev.txt    # 包含開發工具

4. 設定環境變數:

   cp .env.example .env
   # 編輯 .env 填入您的 Discord 和 Gemini API 憑證

   重要：.env 文件包含敏感資訊，已被 .gitignore 排除，不會被提交到 Git。 nano .env # 或使用您偏好的編輯器

5. 驗證安裝:

   # 檢查配置是否正確
   python -c "from src.utils.config import Config; Config.validate(); print('配置驗證成功！')"

6. 執行機器人:

   python -m src.bot.main

依賴套件說明

核心依賴

• discord.py>=2.3.0 - Discord API 客戶端
• google-generativeai>=0.3.0 - Google Gemini AI 整合
• apscheduler>=3.10.0 - 任務排程
• pydantic>=2.0.0 - 資料驗證
• python-dotenv>=1.0.0 - 環境變數管理
• uvicorn[standard]>=0.23.0 - ASGI 伺服器
• fastapi>=0.100.0 - Web 框架
• aiofiles>=23.0.0 - 異步檔案操作
• structlog>=23.0.0 - 結構化日誌
• tenacity>=8.2.0 - 重試機制
• tiktoken>=0.5.0 - Token 計算

開發依賴

• pytest>=7.4.0 - 測試框架
• pytest-asyncio>=0.21.0 - 異步測試支援
• pytest-mock>=3.11.0 - Mock 支援
• ruff>=0.1.0 - 程式碼檢查
• black>=23.0.0 - 程式碼格式化
• mypy>=1.5.0 - 型別檢查

設定

請參考 .env.example 查看所有可用的設定選項。

必要設定

• DISCORD_BOT_TOKEN: 您的 Discord 機器人令牌
• DISCORD_GUILD_ID: 目標 Discord 伺服器 ID
• DISCORD_SUMMARY_CHANNEL_ID: 發布總結的頻道 ID
• GEMINI_API_KEY: Google Gemini API 金鑰

頻道監控設定

• CHANNEL_ALLOWLIST_IDS: 要監控的頻道 ID 清單（推薦，逗號分隔）
• CHANNEL_ALLOWLIST: 要監控的頻道名稱清單（備用，逗號分隔）
• CHANNEL_DENYLIST_IDS: 排除的頻道 ID 清單（逗號分隔）
• CHANNEL_DENYLIST: 排除的頻道名稱清單（逗號分隔）
• USER_DENYLIST: 排除的使用者名稱清單（逗號分隔）

監控邏輯：

• 如果設定了允許清單，只監控清單中的頻道
• 如果沒有設定允許清單，監控所有頻道（除了拒絕清單）
• 頻道 ID 優先於頻道名稱

可選設定

• GEMINI_MODEL: 使用的 AI 模型（預設：gemini-2.0-flash-exp，推薦使用最新版本）
• MAX_TOKENS_PER_SUMMARY: 每次摘要的最大 token 數（預設：4000）
• TEMPERATURE: 生成溫度（預設：0.7）
• SUMMARY_TIME: 每日總結時間（預設：23:59）
• TZ: 時區設定（預設：Asia/Taipei）
• STORE_RETENTION_DAYS: 資料保留天數（預設：30）
• HEALTH_CHECK_PORT: 健康檢查埠號（預設：8080）

支援的頻道類型

機器人支援以下 Discord 頻道類型：

• 文字頻道 (TextChannel): 一般文字訊息頻道
• 論壇頻道 (ForumChannel): Discord 論壇頻道，包含帖子和討論串
• 舞台頻道 (StageChannel): 舞台頻道（如果有文字功能）

時間範圍處理

• 時區支援: 使用配置的時區（預設：Asia/Taipei）計算日期範圍
• 重疊處理: 自動擴展 2 小時範圍以處理跨時區訊息
• 精確範圍: 實際擷取時間為目標日期的 00:00-23:59（配置時區）

模型選擇指南

推薦使用 Gemini 2.0 Flash Experimental：

• 最新的 AI 模型，效果更好
• 支援更長的上下文和更準確的摘要
• 內容更簡潔、清楚，去重效果更好
• 預設模型：gemini-2.0-flash-exp

免費版本注意事項：

• 配額限制：每分鐘最多 15 次請求，每天最多 1,500 次請求
• 建議設定 MAX_TOKENS_PER_SUMMARY=4000 以充分利用模型能力
• 當配額不足時，機器人會自動使用簡化摘要

部署

原生 systemd

sudo ./deploy/scripts/install-systemd.sh

Docker + systemd

docker compose up -d
sudo ./deploy/scripts/install-systemd-docker.sh

指令

斜線指令 (Application Commands)

• /ping: 測試機器人回應速度
• /recap action:生成總結 date:today: 生成今日總結
• /recap action:生成總結 date:YYYY-MM-DD: 生成指定日期總結
• /recap action:查看設定: 顯示目前設定

傳統指令 (已過時)

• !ping: 測試機器人回應速度（建議使用 /ping）
• !recap: 顯示過時訊息（建議使用 /recap）

架構

詳細系統設計請參考 docs/ARCHITECTURE.md。

服務管理

安裝、升級和維護程序請參考 docs/SERVICE.md。

開發

# 安裝開發依賴
pip install -e .[dev]

# 執行測試
pytest

# 程式碼格式化
ruff check --fix
black .

# 型別檢查
mypy src/

故障排除

常見問題

1. 虛擬環境問題

# 如果虛擬環境無法建立
python3 -m venv --clear .venv

# 如果 pip 安裝失敗
pip install --upgrade pip setuptools wheel

2. 依賴安裝問題

# 清理快取重新安裝
pip cache purge
pip install --no-cache-dir -r requirements.txt

# 如果遇到編譯錯誤，安裝編譯工具
# Ubuntu/Debian:
sudo apt-get install build-essential python3-dev
# macOS:
xcode-select --install

3. 配置驗證失敗

# 檢查環境變數是否正確設定
python -c "import os; print('DISCORD_BOT_TOKEN:', bool(os.getenv('DISCORD_BOT_TOKEN')))"

# 驗證配置
python -c "from src.utils.config import Config; Config.validate()"

4. Discord 連線問題

• 確認 Bot Token 正確
• 檢查網路連線
• 確認 Bot 有正確的權限
• 檢查防火牆設定

5. Gemini API 問題

• 確認 API Key 正確
• 檢查 API 配額（免費版本限制：每分鐘 15 次請求，每天 1,500 次）
• 確認模型名稱正確（建議使用 gemini-1.5-flash 以節省配額）
• 如果遇到配額限制，機器人會自動使用簡化摘要

日誌查看

# 查看應用程式日誌
tail -f logs/app.log

# 查看系統日誌（systemd 部署）
sudo journalctl -u ncsa-dr -f

授權

MIT License