Index cn
基於 nextcord 框架開發的全功能 Discord 機器人，提供 AI 智能對話、內容處理和實用工具功能。支援多語言介面與整合式網路搜尋功能。🚀⚡🔥
歡迎提供建議和貢獻!
✨ 主要功能
🤖 AI 智能互動
- 文字生成：支援多種 AI 模型（OpenAI GPT-4o — 預設、GPT-5-mini、GPT-5-nano、Claude-3.5-Haiku）與整合式網路搜尋，預設串流模式（約每 10 個字更新一次）
- 使用者記憶：以使用者為單位記錄對話記憶；
/clear_memory會清除你的使用者記憶 - 圖像處理：視覺模型支援，自動圖像格式轉換
- 圖像生成：透過 Responses API 的工具整合，支援漸進式串流渲染，生成的圖片會以 Discord 附件 + Embed 的方式美化呈現，並顯示部分進度
- 智慧網路存取：LLM 可於需要時自動搜尋網路，提供最新資訊
📊 內容處理
- 訊息摘要：智能頻道對話摘要，支援用戶篩選（5、10、20、50 則訊息）
- 影片下載：多平台支援（YouTube、TikTok、Instagram、X、Facebook），提供品質選項
- Bilibili 相容性改善：加入正確 Referer 標頭、更安全的格式回退、與更穩健的錯誤處理
- 網站專屬標頭：Referer 僅在 Bilibili 套用，以避免影響 Facebook 連結
- 楓之谷資料庫：查詢怪物和物品詳細掉落資訊
- 競標系統：完整的拍賣平台與競標功能，支援多貨幣類型（楓幣/雪花/台幣）
- 抽獎系統：多平台抽獎功能，支援 Discord「按鈕報名」或 YouTube 聊天室整合（完全不使用表情反應），可設定每次抽出人數並支援重新建立。已中獎者在同一活動期間會被自動排除，直到你使用「重新建立」開新活動。已統一採用
discord命名，不再使用舊的reaction名稱。參與者名單統一以單一欄位顯示。- 實作說明：報名/取消按鈕以
nextcord.ui.Button的子類別形式實現（JoinLotteryButton、CancelJoinLotteryButton），UI 僅處理互動；中獎與重複檢查集中在核心新增/移除函式中以保持邏輯簡潔。
- 實作說明：報名/取消按鈕以
- 圖像生成：已整合至
/oai指令（使用 image_generation 工具）。獨立的/graph仍為未來擴充的預留指令。
🌍 多語言支援
- 繁體中文
- 簡體中文
- 日本語
- English
🔧 技術特色
- 主要機器人實現：核心機器人類別
DiscordBot在src/discordbot/cli.py中實現，繼承nextcord.ext.commands.Bot並包含完整的初始化、Cog 載入和事件處理 - 模組化 Cog 架構設計
- 非同步處理配合 nextcord
- Pydantic 基礎配置管理
- 完整錯誤處理與日誌記錄
- Docker 支援與開發容器
🎯 核心指令
| 指令 | 功能說明 | 特色功能 |
|---|---|---|
/oai |
生成 AI 文字回應 | 多模型支援（預設 GPT-4o、另含 GPT-5 mini/nano、Claude 3.5 Haiku）、預設串流模式（約每 10 個字更新）、圖像輸入、自動網路搜尋與漸進式圖像生成（Responses API 工具）、使用者記憶 |
/clear_memory |
清除對話記憶 | 重置你的使用者記憶，讓下次對話從頭開始 |
| /sum | 互動式訊息摘要 | 用戶篩選、5/10/20/50 則訊息選項 |
| /download_video | 多平台影片下載器 | 最佳/高/中/低品質；若超過 25MB 自動降為低畫質 |
| /maple_monster | 搜尋楓之谷怪物掉落 | 詳細怪物資訊 |
| /maple_item | 搜尋楓之谷物品來源 | 掉落來源追蹤 |
| /maple_stats | 楓之谷資料庫統計 | 資料概覽和熱門物品 |
| /auction_create | 創建物品拍賣 | 互動表單、貨幣類型選擇 |
| /auction_list | 瀏覽進行中拍賣 | 即時更新、下拉選單 |
| /auction_info | 查看拍賣詳情 | 當前競標、競標歷史 |
| /auction_my | 查看個人拍賣 | 我的拍賣與領先競標 |
| /lottery | 抽獎主指令 | 下拉選擇方式；按鈕：🎉 報名、🚫 取消（Discord 模式）、✅ 開始（主持人）、📊 狀態（僅自己可見）、🔄 重新建立、🔁 更新參與者（YouTube/僅主持人）；建立訊息會自動更新統一的參與者名單；可設定每次抽出人數；同一活動已中獎者不再可加入（除非重新建立） |
| /graph | 生成圖像（預留） | 框架已準備實現 |
| /ping | 機器人效能測試 | 延遲測量 |
🚀 快速開始
系統需求
- Python 3.10 或更高版本
- Discord 機器人 Token
- OpenAI API 金鑰
安裝步驟
-
克隆專案
-
使用 uv 安裝依賴
-
設定環境變數
-
啟動機器人
Docker 部署
# 使用 Docker Compose
docker-compose up -d
# 或手動建立
docker build -t discordbot .
docker run -d discordbot
注意：Docker 映像已安裝 ffmpeg，以便 yt-dlp 可合併視訊/音訊串流。
可選：更新楓之谷資料庫
# 安裝 Playwright Chromium（首次）
uv run playwright install chromium
# 抓取最新怪物/物品資料到 ./data/monsters.json
uv run update
⚙️ 配置設定
必要環境變數
# Discord 設定
DISCORD_BOT_TOKEN=你的_discord_機器人_token
DISCORD_TEST_SERVER_ID=你的_測試_伺服器_id # 可選
# OpenAI 設定
OPENAI_API_KEY=你的_openai_api_金鑰
OPENAI_BASE_URL=https://api.openai.com/v1
# Azure OpenAI（如果使用 Azure）
AZURE_OPENAI_API_KEY=你的_azure_金鑰
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
可選環境變數
# 如果使用 Azure OpenAI
OPENAI_API_VERSION=2025-04-01-preview
# 訊息記錄（SQLite）
SQLITE_FILE_PATH=sqlite:///data/messages.db
# 其他服務（如有使用）
POSTGRES_URL=postgresql://postgres:postgres@postgres:5432/postgres
REDIS_URL=redis://redis:6379/0
# YouTube Data API 金鑰（YouTube 抽獎模式需要）
YOUTUBE_DATA_API_KEY=你的_youtube_data_api_金鑰
YouTube 抽獎模式設定（可選）
- 在
./data/client_secret.json放置 Google OAuth 憑證（桌面應用）。 - 設定
YOUTUBE_DATA_API_KEY。 - 第一次使用 YouTube 模式時會在 8080 端口開啟瀏覽器進行授權，完成後憑證會儲存至
./data/token.pickle。
📁 專案結構
src/discordbot/
├── cli.py # 主要機器人入口點
├── cogs/ # 指令模組
│ ├── gen_reply.py # AI 文字生成 (/oai)
│ ├── summary.py # 訊息摘要 (/sum)
│ ├── video.py # 影片下載 (/download_video)
│ ├── maplestory.py # 楓之谷資料庫查詢
│ ├── auction.py # 競標系統
│ ├── lottery.py # 多平台抽獎系統
│ ├── gen_image.py # 圖像生成（預留）
│ └── template.py # 系統工具與延遲測試
├── sdk/ # 核心業務邏輯
│ ├── llm.py # LLM 整合（OpenAI/Azure）
│ ├── log_message.py # 訊息記錄（寫入 SQLite）
│ └── yt_chat.py # YouTube 聊天輔助
├── typings/ # 配置模型
│ ├── config.py # Discord 設定
│ └── database.py # DB 設定（SQLite/Postgres/Redis）
└── utils/ # 工具函數
└── downloader.py # yt-dlp 包裝
data/
├── monsters.json # 楓之谷怪物與掉落資料庫
├── auctions.db # 競標系統 SQLite 資料庫
└── downloads/ # 影片下載儲存
🔍 核心功能深度解析
多模態 AI 支援
- 即時串流：文字回應採用即時串流，每 10 個字更新一次，提供即時回饋
- 漸進式圖片渲染：圖片生成顯示部分進度更新，提供流暢的視覺體驗
- 文字和圖像輸入處理
- 自動圖像轉 base64 格式
- 透過 Responses API 工具生成圖像；輸出以 Discord 檔案附件與嵌入 (Embed) 呈現，提供優雅的預覽效果
- 模型特定限制處理
- 自動網路搜尋回應功能
影片下載引擎
- 支援 10+ 個平台
- 品質選擇（4K 到純音訊）
- Discord 檔案大小限制驗證
- 進度追蹤和錯誤處理
- 使用 Tenacity 的重試機制：重試 5 次，每次間隔 1 秒（寫死設定）
Bilibili 使用注意
- Referer 僅在 Bilibili 套用；其他站（如 Facebook）使用最小標頭。
- 請確保
yt-dlp為最新版本。 - 需要安裝
ffmpeg以合併分離的視訊/音訊串流（多數 B 站影片為分離流）。 - 下載器會附帶
Referer: https://www.bilibili.com並使用像bestvideo*+bestaudio/best的安全格式回退。 - 若仍出現「Requested format is not available」，可嘗試選擇較低畫質（中/低）。部分影片僅提供特定 DASH 配置或受區域/年齡限制。
- 對於需登入/年齡/區域限制的影片，可能需要提供 cookies 給 yt-dlp（目前未預設接線）。
Facebook 使用注意
- 我們不會對 Facebook 強制加入 Referer；為避免與抽取器衝突，僅使用最小必要標頭。
- 請維持
yt-dlp為最新，並確認已安裝ffmpeg。 - 若下載失敗，嘗試較低畫質；對於私密/登入/區域限制的連結，可能需要提供 cookies 給 yt-dlp。
楓之谷資料庫
- 完整的怪物和物品資料庫（192+ 個怪物）
- 支援模糊搜尋的互動式查詢
- 多語言支援（繁體中文、簡體中文、日文、英文）
- 詳細的怪物屬性和掉落資訊
- 物品來源追蹤與視覺化顯示
- 快取搜尋結果以優化效能
競標系統
- 完整拍賣平台：
- 創建物品拍賣，可自訂持續時間、競標增額和貨幣類型選擇（楓幣/雪花/台幣）
- 多貨幣支援，預設為「楓幣」，另提供「雪花」和「台幣」選項
- 即時競標與互動介面（💰 出價、📊 查看記錄、🔄 刷新）
- 個人拍賣管理與競標追蹤，包含貨幣類型顯示
- 防止自我競標和重複出價的安全機制
- SQLite 資料庫儲存，具備 ACID 合規性和向後相容性
抽獎系統
- 報名模式：Discord 按鈕報名或 YouTube 聊天室關鍵字報名
- 控制按鈕：🎉 報名、🚫 取消、✅ 開始（僅主持人）、📊 狀態（僅本人可見）、🔄 重新建立、🔁 更新參與者（YouTube/僅主持人）
- 即時狀態：按 📊 取得僅自己可見的活動狀態
- 自動更新訊息：建立訊息會自動更新參與者名單（使用者報名/取消時即時反映，統一於單一欄位）
- 訊息綁定：按鈕互動會綁定建立訊息，機器人可藉此辨識對應的抽獎（完全不使用表情反應）
- YouTube 模式名單抓取：在 YouTube 模式下，主持人可隨時按下 🔁 更新參與者 以依設定關鍵字從聊天室抓取參與者；同時在按下 ✅ 開始 之前也會再次抓取一次
- 中獎者排除：在同一活動中，一旦被抽中，將不會再被加入該活動的參與名單（避免連續抽到同一人）。如需讓所有人再次有資格，請使用 🔄 重新建立。
- Discord 模式按鈕：🎉 報名 與 🚫 取消 僅在 Discord 模式顯示
- 每次抽出人數：建立表單可設定每次抽出的人數
- 重新建立（🔄）：建立新的抽獎並沿用設定，並自動帶回所有參與者（含先前中獎者）
- 安全機制：僅主持人控制、加密安全的隨機選擇、參與者驗證
- 單一平台：每次抽獎只選擇一種報名方式
- 記憶體儲存：輕量級 in-memory 結構，重啟後重置
🛠️ 開發指南
本地開發
# 安裝開發依賴
uv sync --dev
# 執行測試
uv sync --group test
uv run pytest -q
# 程式碼品質檢查
uv run ruff check
uv run ruff format
# 建立文檔
uv run mkdocs serve
🧪 測試說明
- 測試框架：
pytest（含xdist平行化、pytest-asyncio非同步測試、覆蓋率設定在pyproject.toml）。 - 測試路徑：所有測試位於
tests/，涵蓋各個 cog 與核心工具。 - 新增的 Cog 單元測試包含：
TemplateCogs：訊息反應與/ping延遲 EmbedMessageFetcher（摘要）：_format_messages()與do_summarize()（模擬 LLM）ReplyGeneratorCogs：_get_attachment_list()與/clear_memoryImageGeneratorCogs：/graph（預留流程）VideoCogs：/download_video樂觀流程（模擬下載器）
執行完整測試並產生報表：
貢獻指南
- Fork 此專案
- 建立功能分支（
git checkout -b feature/新功能） - 提交變更（
git commit -m '新增某項功能'） - 推送到分支（
git push origin feature/新功能） - 建立 Pull Request
程式碼規範
- 遵循 PEP 8 命名慣例
- 使用 Pydantic 模型進行資料驗證
- 所有函數需要型別提示
- 使用 Google 風格的 docstring
- 最大行長度 99 字元
📚 API 參考
主要 SDK 模組
src/sdk/llm.py
# AI 文字生成（範例代碼已更新為新架構）
# 現在透過 Discord 的 /oai 指令使用
# AI 回應與自動網路搜尋
# 現在整合在 /oai 指令中，LLM 會自動判斷是否需要搜尋網路
# 網路搜尋功能已整合至 AI 回應中
# 無需單獨呼叫，LLM 會自動處理
🚀 部署
生產環境部署
-
環境準備
-
Docker 部署
-
監控設定
- 使用 Logfire 進行日誌監控
- 設定健康檢查端點
- 配置錯誤通知
🔧 疑難排解
常見問題
Q: 機器人無法回應指令 A: 檢查機器人權限，確保已啟用「應用程式指令」範圍
Q: OpenAI API 錯誤 A: 驗證 API 金鑰和額度，檢查模型可用性
Q: 影片下載失敗 A: 確認 yt-dlp 版本為最新，檢查平台支援狀況
Q: 資料庫連接錯誤 A: 檢查檔案路徑權限，確保目錄存在
日誌分析
📈 效能優化
建議配置
- 記憶體：最少 512MB，建議 1GB
- 儲存空間：最少 2GB（用於影片下載和資料儲存）
- 網路：穩定的網際網路連接
- CPU：多核心處理器，支援大量並發請求
優化技巧
- 使用 Redis 快取頻繁查詢
- 定期清理舊的下載檔案
- 配置適當的 API 請求限制
- 使用連接池優化資料庫連接
🔒 隱私與資料
本 Discord 機器人遵守 Discord 服務條款與開發者政策。
資料收集與使用
- 本地訊息記錄：預設情況下，機器人在所在頻道的訊息會記錄到本機 SQLite（
./data/messages.db），包含作者、內容、時間戳與附件/貼圖連結。資料僅存在你的伺服器，不會外傳。 - 不與第三方分享：除了為完成請求所需的受信任 API（例如 OpenAI）之外，不會與第三方分享資料。
- 如何停用：伺服器擁有者可在
src/discordbot/cli.py移除記錄呼叫，或依需求調整src/discordbot/sdk/log_message.py。
機器人權限與意圖
本機器人僅為功能需求申請以下權限：
- 訊息內容意圖：用於斜線指令情境、少量關鍵字處理與上述本地記錄（可調整）
- 斜線指令：用於互動式指令處理
- 檔案附件：用於處理 AI 視覺功能中的圖像和下載用戶請求的內容
- 嵌入連結：用於格式化豐富回應和搜尋結果
資料安全
- 所有 API 通訊使用加密的 HTTPS 連接
- 不會將資料發送至任何外部服務。若啟用本地訊息記錄，訊息僅儲存在你的磁碟（SQLite：
./data/messages.db），不會外傳。你可以在src/discordbot/cli.py移除記錄呼叫或調整src/discordbot/sdk/log_message.py以停用。 - 不進行基於用戶內容的長期分析。
聯絡與合規
如果您對隱私有疑慮或對資料處理有疑問：
- 透過 GitHub Issues 回報問題
- 透過專案儲存庫聯絡開發團隊
本機器人採用隱私設計原則和最小化資料處理，以確保用戶隱私保護。
📄 授權條款
本專案採用 MIT 授權條款。詳細資訊請參閱 LICENSE 檔案。
👥 貢獻者
使用 contrib.rocks 製作
📞 聯絡方式
- 📧 Email: [專案維護者郵箱]
- 💬 Discord: [Discord 伺服器連結]
- 🐛 Issue: GitHub Issues
- 💡 討論: GitHub Discussions