---
# System prepended metadata

title: KAFU Discord Bot

---

# KAFU Bot — Stable 3.0 Version

一個集結 **Discord Slash Commands 、YouTube Music Playback 、TTS 語音合成 、RVC 翻唱 、Ollama RAG 智能回應** 的多功能 Discord 機器人。

此版本是穩定可長期運行的第三代版本，採用模組化設計，可根據伺服器需求擴充音樂播放、語音轉換、聊天 AI、伺服器管理等功能。

---

##  功能總覽

###  語音與音樂播放

* `/join`：讓機器人加入語音頻道。
* `/play <網址或關鍵字>`：播放 YouTube 音樂或搜尋播放。
* `/pause`、`/resume`、`/skip`、`/stop`：控制播放進度。
* `/leave`：離開語音頻道。
* **支援 yt-dlp 音源快取 + ffmpeg 解碼**，可穩定播放。

###  語音合成（TTS）與翻唱（RVC）

* `/speak <文字>`：使用 Microsoft Edge TTS 將文字轉為語音播放。
* `/sing <YouTube 連結>`：使用 **uRVC song-cover** 將歌曲自動翻唱成指定角色音色（如 KAFU）。
* 參數可設定音質、RVC 模型、音量比例等。

###  智能對話 / RAG 模式（選用）

* `/think on|off|status`：啟用 / 關閉 Ollama 本地語言模型整合。
* 可透過 Ollama 與自訂 prompts.json 實現智慧問答。

###  娛樂功能

* `/roll`：擲骰子。
* `/choose`：隨機選擇項目。
* `/meme`：隨機迷因。
* `/coin`：擲硬幣。
* `/lottery`：簡易抽獎系統。

###  伺服器輔助

* `/membercount_set_message`：設定固定訊息顯示伺服器成員數。
* `/membercount_set_channel`：設定語音頻道名稱顯示成員數。
* `/membercount_refresh`：手動更新成員數。
* `/report`：回報或檢舉訊息，集中送往管理伺服器頻道。
* `/userinfo`、`/avatar`、`/ping`：常用管理工具。

---

##  系統需求

* **Python**：3.10 ~ 3.12
* **FFmpeg**：系統安裝或由 `imageio-ffmpeg` 提供。
* **libopus**：Windows 需 `libopus-0.dll`。
* **torch**：選用（用於 RVC 功能）。
* **Ollama**：選用（用於 /think）。

---

##  安裝教學

```bash
# 建立虛擬環境
python -m venv .venv

# 啟動虛擬環境
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # macOS / Linux

# 更新 pip 並安裝需求套件
pip install --upgrade pip
pip install -r requirements.txt
```

---

##  路徑與設定

###  Opus（Windows）

```python
OPUS_DIR = r"C:\Users\User\Desktop\program\python\.venv310\Scripts"
OPUS_DLL = os.path.join(OPUS_DIR, "libopus-0.dll")
```

###  uRVC 翻唱（/sing）

```python
URVC_EXE = r"C:\Users\User\Desktop\program\python\ultimate_rvc\.venv312\Scripts\urvc.exe"
URVC_ENV_SCRIPTS = r"C:\Users\User\Desktop\program\python\ultimate_rvc\.venv312\Scripts"
KAFU_MODEL_SRC = Path(r"C:\Users\User\Desktop\program\python\ultimate_rvc\models\rvc\kafu").resolve()
```

> 請確認資料夾中只有一個 `.pth` 模型檔。

###  RVC WebUI（/speak RVC 模式）

```python
RVC_REPO_DIR = Path(r"C:/Users/User/Desktop/tools/RVC/RVC-WebUI")
RVC_MODEL_NAME = "kafu.pth"
RVC_INDEX = Path(r"C:/Users/User/Desktop/tools/RVC/models/added_IVF868_Flat_nprobe_1_v2.index")
```


###  Discord 設定


##  啟動方式

```bash
python "KAFU_bot - stable-3.0ver.py"
```

啟動後機器人將：

1. 自動同步斜線指令。
2. 顯示輪播狀態。
3. 檢查 RVC / Ollama 狀態（若已啟用）。

---

##  常用指令一覽

| 類別            | 指令                                                                     | 說明                 |
| ------------- | ---------------------------------------------------------------------- | ------------------ |
|  音樂         | /join /play /pause /resume /skip /stop /leave                          | 控制音樂播放與語音頻道        |
|  TTS / RVC | /speak /sing                                                           | 文字轉語音 / YouTube 翻唱 |
|  智能         | /think on/off/status                                                   | 開啟或關閉 RAG 模式       |
|  娛樂         | /roll /choose /meme /coin /lottery                                     | 娛樂與抽獎功能            |
|  工具         | /userinfo /avatar /ping /report                                        | 管理與實用指令            |
|  成員統計       | /membercount_set_message /membercount_set_channel /membercount_refresh | 即時顯示伺服器人數          |

---

##  需求套件（requirements.txt）

```txt
discord.py>=2.3.2
PyNaCl>=1.5.0
aiohttp>=3.9.0
requests>=2.31.0
yt-dlp>=2024.0.0
imageio-ffmpeg>=0.4.9
edge-tts>=6.1.12
torch  # 可改為 CPU 版或指定 CUDA 版本
typing_extensions>=4.8.0
```

---

##  RVC / uRVC 說明

* `/sing` 採用 `uRVC song-cover run-pipeline` 完整流程。
* 可搭配 cookies.txt 解決 yt-dlp 403 問題。
* 若報錯 `Requested format is not available` 或 `No video formats found`，程式會自動退階嘗試可行格式。

---

##  疑難排解

| 問題                   | 原因與解法                                                               |
| -------------------- | ------------------------------------------------------------------- |
| **Opus 載入錯誤**        | 確認 `libopus-0.dll` 路徑是否正確。                                          |
| **yt-dlp 403 或無法下載** | 新增 cookies.txt 並重新啟動。                                               |
| **RVC 失敗**           | 檢查 urvc.exe 與模型目錄，確保僅存在一個 .pth。                                     |
| **torch 無法安裝**       | 前往 [PyTorch 官方網站](https://pytorch.org/get-started/locally/) 選擇對應版本。 |

---

##  授權條款

© 2025 jiefoung. All Rights Reserved.
本程式及其所有附屬內容（包含原始碼、模型、資源）僅供個人或授權使用，
禁止任何形式之未經授權修改、散佈、重製或商業使用。

