199 lines
6.6 KiB
Markdown
199 lines
6.6 KiB
Markdown
# 專案架構及開發文檔
|
||
|
||
## 專案概述
|
||
|
||
Wolf Chat 是一個基於 MCP (Modular Capability Provider) 框架的聊天機器人助手，專為與遊戲 "Last War-Survival Game" 整合而設計。該機器人：
|
||
|
||
- 使用螢幕辨識技術監控遊戲聊天視窗
|
||
- 偵測包含 "wolf" 或 "Wolf" 關鍵字的聊天訊息
|
||
- 通過 LLM (語言模型) 生成回應
|
||
- 使用 UI 自動化技術將回應輸入到遊戲聊天介面
|
||
|
||
專案以英文編寫程式碼，但主要輸出和日誌以繁體中文顯示，方便使用者理解。
|
||
|
||
## 系統架構
|
||
|
||
### 核心元件
|
||
|
||
1. **主控模塊 (main.py)**
|
||
- 協調各模塊的工作
|
||
- 初始化 MCP 連接
|
||
- 設置並管理主要事件循環
|
||
- 處理程式生命週期管理和資源清理
|
||
|
||
2. **LLM 交互模塊 (llm_interaction.py)**
|
||
- 與語言模型 API 通信
|
||
- 管理系統提示與角色設定
|
||
- 處理語言模型的工具調用功能
|
||
- 格式化 LLM 回應
|
||
|
||
3. **UI 互動模塊 (ui_interaction.py)**
|
||
- 使用圖像辨識技術監控遊戲聊天視窗
|
||
- 檢測聊天泡泡與關鍵字
|
||
- 複製聊天內容和獲取發送者姓名
|
||
- 將生成的回應輸入到遊戲中
|
||
|
||
4. **MCP 客戶端模塊 (mcp_client.py)**
|
||
- 管理與 MCP 服務器的通信
|
||
- 列出和調用可用工具
|
||
- 處理工具調用的結果和錯誤
|
||
|
||
5. **配置模塊 (config.py)**
|
||
- 集中管理系統參數和設定
|
||
- 整合環境變數
|
||
- 配置 API 密鑰和服務器設定
|
||
|
||
6. **角色定義 (persona.json)**
|
||
- 詳細定義機器人的人格特徵
|
||
- 包含外觀、說話風格、個性特點等資訊
|
||
- 提供給 LLM 以確保角色扮演一致性
|
||
|
||
7. **視窗設定工具 (window-setup-script.py)**
|
||
- 輔助工具，用於設置遊戲視窗的位置和大小
|
||
- 方便開發階段截取 UI 元素樣本
|
||
|
||
### 資料流程
|
||
|
||
```
|
||
[遊戲聊天視窗]
|
||
↑↓
|
||
[UI 互動模塊] <→ [圖像樣本庫]
|
||
↓
|
||
[主控模塊] ← [角色定義]
|
||
↑↓
|
||
[LLM 交互模塊] <→ [語言模型 API]
|
||
↑↓
|
||
[MCP 客戶端] <→ [MCP 服務器]
|
||
```
|
||
|
||
## 技術實現
|
||
|
||
### 核心功能實現
|
||
|
||
#### 聊天監控與觸發機制
|
||
|
||
系統使用基於圖像辨識的方法監控遊戲聊天界面：
|
||
|
||
1. **泡泡檢測**：通過辨識聊天泡泡的角落圖案定位聊天訊息，區分一般用戶與機器人
|
||
2. **關鍵字檢測**：在泡泡區域內搜尋 "wolf" 或 "Wolf" 關鍵字圖像
|
||
3. **內容獲取**：點擊關鍵字位置，使用剪貼板複製聊天內容
|
||
4. **發送者識別**：通過點擊頭像，導航菜單，複製用戶名稱
|
||
5. **防重複處理**：使用位置比較和內容歷史記錄防止重複回應
|
||
|
||
#### LLM 整合
|
||
|
||
系統使用基於 OpenAI API 的介面與語言模型通信：
|
||
|
||
1. **模型選擇**：可配置使用不同的模型，預設為 deepseek/deepseek-chat-v3-0324
|
||
2. **系統提示**：精心設計的提示確保角色扮演和功能操作
|
||
3. **工具調用**：支持模型使用 web_search 等工具獲取資訊
|
||
4. **工具處理循環**：實現了完整的工具調用、結果處理和續發邏輯
|
||
|
||
#### 多服務器連接
|
||
|
||
系統可以同時連接多個 MCP 服務器：
|
||
|
||
1. **並行初始化**：使用 asyncio 並行連接配置的所有服務器
|
||
2. **工具整合**：自動發現並整合各服務器提供的工具
|
||
3. **錯誤處理**：處理連接失敗和工具調用異常
|
||
|
||
### 異步架構
|
||
|
||
系統使用 Python 的 asyncio 作為核心異步框架：
|
||
|
||
1. **主事件循環**：處理 MCP 連接、LLM 請求和 UI 監控
|
||
2. **線程安全通信**：UI 監控在獨立線程中運行，通過線程安全隊列與主循環通信
|
||
3. **資源管理**：使用 AsyncExitStack 管理異步資源的生命週期
|
||
4. **清理機制**：實現了優雅的關閉和清理流程
|
||
|
||
### UI 自動化
|
||
|
||
系統使用多種技術實現 UI 自動化：
|
||
|
||
1. **圖像辨識**：使用 OpenCV 和 pyautogui 進行圖像匹配和識別
|
||
2. **鍵鼠控制**：模擬鼠標點擊和鍵盤操作
|
||
3. **剪貼板操作**：使用 pyperclip 讀寫剪貼板
|
||
4. **狀態式處理**：基於 UI 狀態判斷的互動流程，確保操作穩定性
|
||
|
||
## 配置與部署
|
||
|
||
### 依賴項
|
||
|
||
主要依賴項目包括：
|
||
- openai: 與語言模型通信
|
||
- mcp: MCP 框架核心
|
||
- pyautogui, opencv-python: 圖像辨識與自動化
|
||
- pyperclip: 剪貼板操作
|
||
- pygetwindow: 窗口控制
|
||
- python-dotenv: 環境變數管理
|
||
|
||
### 環境設定
|
||
|
||
1. **API 設定**：通過 .env 文件或環境變數設置 API 密鑰
|
||
2. **MCP 服務器配置**：在 config.py 中配置要連接的 MCP 服務器
|
||
3. **UI 樣本**：需要提供特定遊戲界面元素的截圖模板
|
||
4. **視窗位置**：可使用 window-setup-script.py 調整遊戲視窗位置
|
||
|
||
## 開發建議
|
||
|
||
### 優化方向
|
||
|
||
1. **UI 辨識強化**：
|
||
- 改進泡泡匹配算法，提高可靠性
|
||
- 添加文字 OCR 功能，減少依賴剪貼板
|
||
- 擴展關鍵字檢測能力
|
||
|
||
2. **LLM 優化**：
|
||
- 改進系統提示，使回應更自然
|
||
- 添加更多工具支持
|
||
- 實現對話上下文管理
|
||
|
||
3. **系統穩定性**：
|
||
- 增強錯誤處理和復原機制
|
||
- 添加更多日誌和監控功能
|
||
- 開發自動重啟和診斷功能
|
||
|
||
### 注意事項
|
||
|
||
1. **圖像模板**：確保所有必要的 UI 元素模板都已截圖並放置在 templates 目錄
|
||
2. **API 密鑰**：保護 API 密鑰安全，不要將其提交到版本控制系統
|
||
3. **窗口位置**：UI 自動化對窗口位置和大小敏感，保持一致性
|
||
|
||
## 分析與反思
|
||
|
||
### 架構優勢
|
||
|
||
1. **模塊化設計**：各功能區域職責明確，易於維護和擴展
|
||
2. **基於能力的分離**：MCP 框架提供良好的工具擴展性
|
||
3. **非侵入式整合**：不需要修改遊戲本身，通過 UI 自動化實現整合
|
||
|
||
### 潛在改進
|
||
|
||
1. **更穩健的 UI 互動**：當前的圖像辨識方法可能受游戲界面變化影響
|
||
2. **擴展觸發機制**：增加更多觸發條件，不僅限於關鍵字
|
||
3. **對話記憶**：實現對話歷史記錄，使機器人可以參考之前的互動
|
||
4. **多語言支持**：增強對不同語言的處理能力
|
||
|
||
## 使用指南
|
||
|
||
### 啟動流程
|
||
|
||
1. 確保遊戲已啟動且聊天介面可見
|
||
2. 配置必要的 API 密鑰和服務器連接
|
||
3. 運行 `python main.py` 啟動系統
|
||
4. 系統將自動監控聊天，偵測關鍵字並回應
|
||
|
||
### 日常維護
|
||
|
||
1. 定期檢查 API 密鑰有效性
|
||
2. 確保模板圖像與當前遊戲界面匹配
|
||
3. 監控日誌以檢測可能的問題
|
||
|
||
### 故障排除
|
||
|
||
常見問題及解決方案：
|
||
1. **無法識別泡泡**: 更新模板圖像，調整 CONFIDENCE_THRESHOLD
|
||
2. **複製內容失敗**: 檢查點擊位置和遊戲界面一致性
|
||
3. **LLM 連接問題**: 驗證 API 密鑰和網絡連接
|
||
4. **MCP 服務器連接失敗**: 確認服務器配置正確並且運行中
|