U.E.P 的心智 - Discord 機器人

專案簡介

U.E.P's Mind 是一個以 Python 與 discord.py 開發的 Discord 社群管理機器人，旨在提供完整的伺服器管理功能、內容審核、以及成員互動體驗。透過模組化的 Cog 架構設計，本機器人整合了垃圾訊息偵測、髒話過濾、訊息管理、動態擴展載入等核心功能，並使用 SQLite 資料庫持久化儲存使用者違規記錄。

本專案採用非同步事件驅動架構，支援 Slash Commands 與傳統指令雙模式，並提供彈性的擴展管理系統，讓管理員能夠即時載入、重載、卸載功能模組，實現高效能且易維護的機器人服務。

專案狀態：本專案目前處於維護狀態，雖然核心功能完整但部分依賴套件可能需要更新，未來將持續優化以符合最新的 Discord API 規範。

核心理念

社群安全：自動偵測並處理垃圾訊息與不當內容
模組化設計：使用 Cog 系統實現功能分離與動態載入
資料持久化：SQLite 資料庫儲存使用者行為記錄
管理彈性：即時擴展管理與指令重載機制

我的職責

作為本專案的唯一開發者，我負責所有系統設計與實作：

機器人核心架構

設計模組化 Cog 系統架構（cogs/）：
- extensions.py：擴展管理系統（載入/重載/卸載）
- message.py：訊息管理功能（批量刪除）
- info.py：資訊查詢功能
- tokens.py：Token 管理
- test.py：測試功能
建立主程式入口點（Entry.py）：
- 非同步 Cog 載入機制
- Slash Commands 同步
- 環境變數管理（.env）

安全與審核系統

垃圾訊息偵測（spam_detection.py）：
- 實作訊息頻率追蹤演算法
- 設定偵測參數（LIMIT=4, DIFF=2500ms, TIME=3000ms）
- 自動刪除垃圾訊息並警告使用者
- 累積違規達 3 次自動靜音（Timeout 60 秒）
髒話過濾系統（foul_prevention.py）：
- 建立禁用詞彙清單
- 自動刪除包含禁用詞彙的訊息
- 違規計數與警告系統

資料庫系統設計

設計 SQLite 資料庫類別（database.py）：
- Key-Value 儲存結構
- 自動建表機制
- 違規計數持久化（foulCount_{user_id}）
- 預設值處理與容錯設計

指令與互動功能

擴展管理指令：
- >load-again：重新載入所有未載入的 Cog
- >reload：重載所有 Cog
- >list：列出所有已載入的擴展
- >unload <number>：卸載指定編號的擴展（支援鎖定保護）
訊息管理指令：
- >clear <amount>：批量刪除訊息（上限 100 則）
- 自動刪除確認訊息（2 秒後）

核心功能

1. 垃圾訊息偵測系統

即時監控：
- 追蹤每位使用者的訊息時間戳
- 計算訊息間隔差異
- 維護使用者訊息映射（users_map）
偵測邏輯：
- 若訊息間隔 > 2500ms，重置計數器
- 若短時間內發送 4 則訊息，判定為垃圾訊息
- 自動刪除該批次的所有訊息
懲罰機制：
- 第 1-3 次違規：發送警告訊息
- 第 4 次違規：自動靜音 60 秒
- 違規記錄永久儲存於資料庫

2. 髒話過濾系統

內容審核：
- 即時檢查訊息內容
- 對照禁用詞彙清單（banned_words）
- 自動刪除違規訊息
違規追蹤：
- 記錄使用者髒話違規次數
- 與垃圾訊息共用違規計數器
- 達到閾值觸發進一步處罰

3. 訊息管理系統

批量刪除功能：
- 支援刪除 1-99 則訊息
- 權限檢查（requires manage_messages）
- 自動清理確認訊息
安全限制：
- 單次刪除上限 100 則（含指令本身）
- 超過限制提示使用者調整數量

4. 動態擴展管理

熱重載機制：
- 無需重啟機器人即可更新功能
- 支援載入新 Cog
- 支援重載現有 Cog
- 支援卸載指定 Cog
擴展保護：
- 鎖定關鍵擴展（如 extensions.py）
- 防止誤卸載核心功能
管理介面：
- 控制台輸出載入狀態
- Discord 頻道回饋操作結果
- 可愛的表情符號回應（如 (/≧▽≦)/、ƪ(˘⌣˘)ʃ）

5. 資料庫持久化

SQLite 資料庫：
- 自動建立 bot_database.db
- Key-Value 結構儲存
- 自動建表機制
資料管理：
- get(key, default_value)：取得或建立資料
- set(key, value)：設定或更新資料
- 違規計數器自動遞增
- 資料一致性保證

6. 事件驅動架構

Bot Events：
- on_ready：機器人啟動事件
- 自動載入所有 Cog
- 同步 Slash Commands
- 輸出系統狀態資訊
Message Events（透過 main/ 模組）：
- 每則訊息自動檢查垃圾訊息
- 每則訊息自動檢查髒話
- 非同步處理避免阻塞

使用技術

核心框架

Python 3.10+：主要開發語言
discord.py 2.4.0：Discord API 封裝框架
asyncio：非同步 I/O 處理
SQLite：嵌入式資料庫

Discord 相關套件

discord.ext.commands：指令處理框架
discord.Intents：事件訂閱系統
discord.app_commands：Slash Commands 支援

資料處理與工具

python-dotenv：環境變數管理
sqlite3：資料庫操作
datetime / timedelta：時間處理

網路與加密

aiohttp 3.10.10：非同步 HTTP 客戶端
aiohttp-retry 2.9.0：HTTP 重試機制
cryptography 43.0.3：加密功能
pycryptodomex 3.21.0：進階加密

Web 框架（可能用於未來擴展）

Flask 3.0.3：輕量級 Web 框架
Jinja2 3.1.4：模板引擎

其他依賴

protobuf 4.25.5：資料序列化
iso8601 2.1.0：日期時間解析
argon2-cffi 23.1.0：密碼雜湊
pyseto 1.7.9：安全 Token 處理

開發工具

Visual Studio / VS Code：主要 IDE
pip：套件管理
虛擬環境（env/）：依賴隔離

專案狀態

當前版本：維護階段（v1.0-legacy）

開發狀態：核心功能完整，處於維護狀態
主要特性：穩定運行的社群管理機器人

功能完成度

✅ 已完成：
- 完整的垃圾訊息偵測系統
- 髒話過濾機制
- 訊息批量刪除功能
- Cog 動態載入/重載/卸載系統
- SQLite 資料庫持久化
- 違規計數與自動靜音
- Slash Commands 支援
- 環境變數配置
🔄 需要更新：
- 部分依賴套件版本較舊
- discord.py 可能需要升級到最新版本
- 安全性套件更新（cryptography、argon2-cffi）
📋 未來計畫：
- 更新至最新 discord.py 版本
- 擴展更多管理功能
- 加入更多互動指令
- 改善髒話偵測演算法（支援變體詞彙）
- Dashboard Web 介面（Flask 基礎已存在）

開發挑戰與收穫

1. 非同步程式設計

挑戰：如何設計高效能的非同步事件處理系統？

解決方案：

使用 asyncio 與 async/await 語法處理所有 I/O 操作
設計非同步 Cog 載入機制（await bot.load_extension()）
實作非同步計時器（asyncio.create_task(self.remove_user())）
使用 discord.utils.sleep_until() 實現延遲操作

收穫：

深入理解 Python 非同步程式設計
掌握 asyncio 事件循環機制
學習並行處理與任務管理
提升高效能應用開發能力

2. 垃圾訊息偵測演算法

挑戰：如何準確偵測垃圾訊息，同時避免誤判正常對話？

解決方案：

設計滑動時間窗口演算法：
- LIMIT=4：4 則訊息觸發偵測
- DIFF=2500ms：訊息間隔閾值
- TIME=3000ms：使用者資料過期時間
維護使用者訊息映射表（users_map）追蹤歷史訊息
實作自動清理機制（定時器刪除過期資料）
累積違規機制避免單次誤判過重

收穫：

學習演算法設計與參數調校
掌握時間序列資料處理
理解滑動窗口技術應用
提升資料結構設計能力

3. 模組化 Cog 架構

挑戰：如何設計彈性且易維護的機器人擴展系統？

解決方案：

採用 discord.py 的 Cog 系統分離功能模組
實作動態載入機制掃描 cogs/ 資料夾
設計擴展管理 Cog 提供熱重載功能
實作擴展鎖定機制保護核心模組
使用 setup() 函式統一 Cog 註冊介面

收穫：

掌握插件化架構設計模式
學習動態模組載入技術（__import__、importlib）
理解關注點分離原則
提升大型專案架構能力

4. SQLite 資料庫設計

挑戰：如何設計簡單但有效的資料持久化方案？

解決方案：

採用 Key-Value 結構簡化資料模型
實作自動建表機制（CREATE TABLE IF NOT EXISTS）
設計容錯的 get() 方法，不存在時自動建立預設值
使用 INSERT OR REPLACE 簡化更新邏輯
資料庫連接由 Database 類別統一管理

收穫：

掌握 SQLite 基礎操作
學習資料庫設計模式
理解 ORM 概念（雖然使用原生 SQL）
提升資料持久化設計能力

5. Discord Bot 開發實務

挑戰：如何整合 Discord API 實現完整的機器人功能？

解決方案：

使用 discord.py 框架簡化 API 呼叫
啟用所有 Intents 獲取完整事件存取權
實作 Slash Commands 與傳統指令雙支援
設計權限檢查裝飾器（@commands.has_permissions）
使用表情符號與個性化訊息提升使用者體驗

收穫：

掌握 Discord Bot 開發完整流程
學習 OAuth2 與 Token 管理
理解 Discord Gateway 與 WebSocket 通訊
提升 API 整合與第三方服務對接能力
培養使用者體驗設計思維

專案架構

U.E.P's Mind Reflourished/
├── Entry.py                # 機器人入口點
├── requirements.txt        # 依賴套件列表
├── .env                    # 環境變數（Token、Creator ID）
├── bot_database.db         # SQLite 資料庫
├── cogs/                   # Cog 模組
│   ├── extensions.py       # 擴展管理系統
│   ├── message.py          # 訊息管理功能
│   ├── info.py             # 資訊查詢
│   ├── tokens.py           # Token 管理
│   └── test.py             # 測試功能
├── main/                   # 核心邏輯模組
│   ├── database.py         # 資料庫操作類別
│   ├── spam_detection.py  # 垃圾訊息偵測
│   └── foul_prevention.py # 髒話過濾系統
├── resources/              # 資源檔案（可能包含圖片、音效等）
└── env/                    # 虛擬環境

預期維護工程

套件更新

建議定期更新以下關鍵套件：

discord.py：確保與 Discord API 最新版本相容
cryptography：修補已知安全漏洞
aiohttp：改善網路效能與穩定性
argon2-cffi：提升密碼雜湊安全性

功能擴展方向

進階審核：
- 支援正則表達式髒話偵測
- 圖片內容審核（OCR + AI）
- 網址黑名單過濾
社群互動：
- 歡迎新成員系統
- 角色自助選取
- 等級與經驗值系統
管理工具：
- 成員資料統計
- 伺服器活躍度分析
- 自動化管理規則

程式碼優化

將硬編碼參數移至設定檔（LIMIT、DIFF、TIME）
實作日誌系統取代 print 語句
加強錯誤處理與例外捕捉
撰寫單元測試確保功能穩定性

訪客計數

快速統計

最新更新

本日名言

專案簡介

核心理念

我的職責

機器人核心架構

安全與審核系統

資料庫系統設計

指令與互動功能

核心功能

1. 垃圾訊息偵測系統

2. 髒話過濾系統

3. 訊息管理系統

4. 動態擴展管理

5. 資料庫持久化

6. 事件驅動架構

使用技術

核心框架

Discord 相關套件

資料處理與工具

網路與加密

Web 框架（可能用於未來擴展）

其他依賴

開發工具

專案狀態

當前版本：維護階段（v1.0-legacy）

功能完成度

開發挑戰與收穫

1. 非同步程式設計

2. 垃圾訊息偵測演算法

3. 模組化 Cog 架構

4. SQLite 資料庫設計

5. Discord Bot 開發實務

專案架構

預期維護工程

套件更新

功能擴展方向

程式碼優化