242 lines
8.7 KiB
Markdown
242 lines
8.7 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. **模型選擇**：目前使用 `anthropic/claude-3.7-sonnet` 模型 (改進版)
|
||
2. **系統提示**：精心設計的提示確保角色扮演和功能操作
|
||
3. **工具調用**：支持模型使用 web_search 等工具獲取資訊
|
||
4. **工具處理循環**：實現了完整的工具調用、結果處理和續發邏輯
|
||
5. **結果合成**：添加了從工具調用結果合成回應的機制 (新增功能)
|
||
|
||
#### 多服務器連接
|
||
|
||
系統可以同時連接多個 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 調整遊戲視窗位置
|
||
|
||
## 最近改進（2025-04-17）
|
||
|
||
### 工具調用與結果處理優化
|
||
|
||
針對使用工具時遇到的回應問題，我們進行了以下改進：
|
||
|
||
1. **模型切換**：
|
||
- 已取消
|
||
|
||
2. **系統提示強化**：
|
||
- 重寫系統提示，將角色人格與工具使用指南更緊密結合
|
||
- 添加明確指示，要求 LLM 在工具調用後提供非空回應
|
||
- 添加好與壞的示例，使模型更好地理解如何以角色方式融合工具信息
|
||
|
||
3. **工具結果處理機制**：
|
||
- 實現了工具結果追蹤系統，保存所有工具調用結果
|
||
- 添加了對非空回應的追蹤，確保能在多次循環間保持連續性
|
||
- 開發了合成回應生成器，能從工具結果創建符合角色的回應
|
||
|
||
4. **回應解析改進**：
|
||
- 重寫 `parse_structured_response` 函數，處理更多回應格式
|
||
- 添加回應有效性檢測，確保只有有效回應才發送到遊戲
|
||
- 強化 JSON 解析能力，更好地處理不完整或格式不標準的回應
|
||
|
||
5. **主程序流程優化**：
|
||
- 修改了主流程中的回應處理邏輯，增加回應有效性檢查
|
||
- 改進了工具調用循環處理，確保完整收集結果
|
||
- 添加了更詳細的日誌記錄，方便排查問題
|
||
|
||
這些優化確保了即使在複雜工具調用後，Wolfhart 也能保持角色一致性，並提供合適的回應。無效回應不再發送到遊戲，提高了用戶體驗。
|
||
|
||
## 開發建議
|
||
|
||
### 優化方向
|
||
|
||
1. **UI 辨識強化**：
|
||
- 改進泡泡匹配算法，提高可靠性
|
||
- 添加文字 OCR 功能，減少依賴剪貼板
|
||
- 擴展關鍵字檢測能力
|
||
|
||
2. **LLM 進一步優化**：
|
||
- 繼續微調系統提示，平衡角色扮演與工具使用
|
||
- 研究可能的上下文壓縮技術，處理長對話歷史
|
||
- 為更多查詢類型添加專門的結果處理邏輯
|
||
|
||
3. **系統穩定性**：
|
||
- 擴展錯誤處理和復原機制
|
||
- 添加自動重啟和診斷功能
|
||
- 實現更多遙測和監控功能
|
||
|
||
4. **對話能力增強**：
|
||
- 實現對話歷史記錄
|
||
- 添加主題識別與記憶功能
|
||
- 探索多輪對話中的上下文理解能力
|
||
|
||
### 注意事項
|
||
|
||
1. **圖像模板**：確保所有必要的 UI 元素模板都已截圖並放置在 templates 目錄
|
||
2. **API 密鑰**：保護 API 密鑰安全，不要將其提交到版本控制系統
|
||
3. **窗口位置**：UI 自動化對窗口位置和大小敏感，保持一致性
|
||
4. **LLM 模型選擇**：在更改模型前測試其在工具調用方面的表現
|
||
|
||
## 分析與反思
|
||
|
||
### 架構優勢
|
||
|
||
1. **模塊化設計**：各功能區域職責明確，易於維護和擴展
|
||
2. **基於能力的分離**：MCP 框架提供良好的工具擴展性
|
||
3. **非侵入式整合**：不需要修改遊戲本身，通過 UI 自動化實現整合
|
||
4. **錯誤處理分層**：在多個層次實現錯誤處理，提高系統穩定性
|
||
|
||
### 潛在改進
|
||
|
||
1. **更穩健的 UI 互動**：當前的圖像辨識方法可能受游戲界面變化影響
|
||
2. **擴展觸發機制**：增加更多觸發條件，不僅限於關鍵字
|
||
3. **對話記憶**：實現對話歷史記錄，使機器人可以參考之前的互動
|
||
4. **多語言支持**：增強對不同語言的處理能力
|
||
5. **模型適應性**：開發更通用的提示和處理機制，適應不同的LLM模型
|
||
|
||
## 使用指南
|
||
|
||
### 啟動流程
|
||
|
||
1. 確保遊戲已啟動且聊天介面可見
|
||
2. 配置必要的 API 密鑰和服務器連接
|
||
3. 運行 `python main.py` 啟動系統
|
||
4. 系統將自動監控聊天，偵測關鍵字並回應
|
||
|
||
### 日常維護
|
||
|
||
1. 定期檢查 API 密鑰有效性
|
||
2. 確保模板圖像與當前遊戲界面匹配
|
||
3. 監控日誌以檢測可能的問題
|
||
4. 定期檢查和備份 llm_debug.log 文件
|
||
|
||
### 故障排除
|
||
|
||
常見問題及解決方案：
|
||
1. **無法識別泡泡**: 更新模板圖像，調整 CONFIDENCE_THRESHOLD
|
||
2. **複製內容失敗**: 檢查點擊位置和遊戲界面一致性
|
||
3. **LLM 連接問題**: 驗證 API 密鑰和網絡連接
|
||
4. **MCP 服務器連接失敗**: 確認服務器配置正確並且運行中
|
||
5. **工具調用後無回應**: 檢查 llm_debug.log 文件，查看工具調用結果和解析過程
|