zik/Wolf-Chat-for-Lastwar

Fork 0

z060142 d5d7b87727 first commit

2025-04-17 01:28:22 +08:00

6.6 KiB

Raw Blame History

專案架構及開發文檔

專案概述

Wolf Chat 是一個基於 MCP (Modular Capability Provider) 框架的聊天機器人助手，專為與遊戲 "Last War-Survival Game" 整合而設計。該機器人：

使用螢幕辨識技術監控遊戲聊天視窗
偵測包含 "wolf" 或 "Wolf" 關鍵字的聊天訊息
通過 LLM (語言模型) 生成回應
使用 UI 自動化技術將回應輸入到遊戲聊天介面

專案以英文編寫程式碼，但主要輸出和日誌以繁體中文顯示，方便使用者理解。

系統架構

核心元件

主控模塊 (main.py)
- 協調各模塊的工作
- 初始化 MCP 連接
- 設置並管理主要事件循環
- 處理程式生命週期管理和資源清理
LLM 交互模塊 (llm_interaction.py)
- 與語言模型 API 通信
- 管理系統提示與角色設定
- 處理語言模型的工具調用功能
- 格式化 LLM 回應
UI 互動模塊 (ui_interaction.py)
- 使用圖像辨識技術監控遊戲聊天視窗
- 檢測聊天泡泡與關鍵字
- 複製聊天內容和獲取發送者姓名
- 將生成的回應輸入到遊戲中
MCP 客戶端模塊 (mcp_client.py)
- 管理與 MCP 服務器的通信
- 列出和調用可用工具
- 處理工具調用的結果和錯誤
配置模塊 (config.py)
- 集中管理系統參數和設定
- 整合環境變數
- 配置 API 密鑰和服務器設定
角色定義 (persona.json)
- 詳細定義機器人的人格特徵
- 包含外觀、說話風格、個性特點等資訊
- 提供給 LLM 以確保角色扮演一致性
視窗設定工具 (window-setup-script.py)
- 輔助工具，用於設置遊戲視窗的位置和大小
- 方便開發階段截取 UI 元素樣本

資料流程

[遊戲聊天視窗]
     ↑↓
[UI 互動模塊] <→ [圖像樣本庫]
     ↓
[主控模塊] ← [角色定義]
   ↑↓
[LLM 交互模塊] <→ [語言模型 API]
   ↑↓
[MCP 客戶端] <→ [MCP 服務器]

技術實現

核心功能實現

聊天監控與觸發機制

系統使用基於圖像辨識的方法監控遊戲聊天界面：

泡泡檢測：通過辨識聊天泡泡的角落圖案定位聊天訊息，區分一般用戶與機器人
關鍵字檢測：在泡泡區域內搜尋 "wolf" 或 "Wolf" 關鍵字圖像
內容獲取：點擊關鍵字位置，使用剪貼板複製聊天內容
發送者識別：通過點擊頭像，導航菜單，複製用戶名稱
防重複處理：使用位置比較和內容歷史記錄防止重複回應

LLM 整合

系統使用基於 OpenAI API 的介面與語言模型通信：

模型選擇：可配置使用不同的模型，預設為 deepseek/deepseek-chat-v3-0324
系統提示：精心設計的提示確保角色扮演和功能操作
工具調用：支持模型使用 web_search 等工具獲取資訊
工具處理循環：實現了完整的工具調用、結果處理和續發邏輯

多服務器連接

系統可以同時連接多個 MCP 服務器：

並行初始化：使用 asyncio 並行連接配置的所有服務器
工具整合：自動發現並整合各服務器提供的工具
錯誤處理：處理連接失敗和工具調用異常

異步架構

系統使用 Python 的 asyncio 作為核心異步框架：

主事件循環：處理 MCP 連接、LLM 請求和 UI 監控
線程安全通信：UI 監控在獨立線程中運行，通過線程安全隊列與主循環通信
資源管理：使用 AsyncExitStack 管理異步資源的生命週期
清理機制：實現了優雅的關閉和清理流程

UI 自動化

系統使用多種技術實現 UI 自動化：

圖像辨識：使用 OpenCV 和 pyautogui 進行圖像匹配和識別
鍵鼠控制：模擬鼠標點擊和鍵盤操作
剪貼板操作：使用 pyperclip 讀寫剪貼板
狀態式處理：基於 UI 狀態判斷的互動流程，確保操作穩定性

配置與部署

依賴項

主要依賴項目包括：

openai: 與語言模型通信
mcp: MCP 框架核心
pyautogui, opencv-python: 圖像辨識與自動化
pyperclip: 剪貼板操作
pygetwindow: 窗口控制
python-dotenv: 環境變數管理

環境設定

API 設定：通過 .env 文件或環境變數設置 API 密鑰
MCP 服務器配置：在 config.py 中配置要連接的 MCP 服務器
UI 樣本：需要提供特定遊戲界面元素的截圖模板
視窗位置：可使用 window-setup-script.py 調整遊戲視窗位置

開發建議

優化方向

UI 辨識強化：
- 改進泡泡匹配算法，提高可靠性
- 添加文字 OCR 功能，減少依賴剪貼板
- 擴展關鍵字檢測能力
LLM 優化：
- 改進系統提示，使回應更自然
- 添加更多工具支持
- 實現對話上下文管理
系統穩定性：
- 增強錯誤處理和復原機制
- 添加更多日誌和監控功能
- 開發自動重啟和診斷功能

注意事項

圖像模板：確保所有必要的 UI 元素模板都已截圖並放置在 templates 目錄
API 密鑰：保護 API 密鑰安全，不要將其提交到版本控制系統
窗口位置：UI 自動化對窗口位置和大小敏感，保持一致性

分析與反思

架構優勢

模塊化設計：各功能區域職責明確，易於維護和擴展
基於能力的分離：MCP 框架提供良好的工具擴展性
非侵入式整合：不需要修改遊戲本身，通過 UI 自動化實現整合

潛在改進

更穩健的 UI 互動：當前的圖像辨識方法可能受游戲界面變化影響
擴展觸發機制：增加更多觸發條件，不僅限於關鍵字
對話記憶：實現對話歷史記錄，使機器人可以參考之前的互動
多語言支持：增強對不同語言的處理能力

使用指南

啟動流程

確保遊戲已啟動且聊天介面可見
配置必要的 API 密鑰和服務器連接
運行 python main.py 啟動系統
系統將自動監控聊天，偵測關鍵字並回應

日常維護

定期檢查 API 密鑰有效性
確保模板圖像與當前遊戲界面匹配
監控日誌以檢測可能的問題

故障排除

常見問題及解決方案：

無法識別泡泡: 更新模板圖像，調整 CONFIDENCE_THRESHOLD
複製內容失敗: 檢查點擊位置和遊戲界面一致性
LLM 連接問題: 驗證 API 密鑰和網絡連接
MCP 服務器連接失敗: 確認服務器配置正確並且運行中

6.6 KiB Raw Blame History Unescape Escape