# 專案架構及開發文檔

## 專案概述

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. **泡泡檢測**：通過辨識聊天泡泡的左上角 (TL) 和右下角 (BR) 角落圖案定位聊天訊息。系統能區分一般用戶泡泡和機器人泡泡。**為了適應玩家可能使用的不同聊天泡泡外觀 (skin)，一般用戶泡泡的偵測機制已被擴充，可以同時尋找多組不同的角落模板 (例如 `corner_tl_type2.png`, `corner_br_type2.png` 等)，提高了對自訂外觀的兼容性。機器人泡泡目前僅偵測預設的角落模板。**
2. **關鍵字檢測**：在泡泡區域內搜尋 "wolf" 或 "Wolf" 關鍵字圖像
3. **內容獲取**：點擊關鍵字位置，使用剪貼板複製聊天內容
4. **發送者識別**：**關鍵步驟** - 系統會根據**偵測到關鍵字的那個特定聊天泡泡**的左上角座標，計算出頭像的點擊位置（目前水平偏移量為 -55 像素）。這確保了點擊的是觸發訊息的發送者頭像，而不是其他位置的頭像。接著通過點擊計算出的頭像位置，導航菜單，最終複製用戶名稱。
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 也能保持角色一致性，並提供合適的回應。無效回應不再發送到遊戲，提高了用戶體驗。

## 最近改進（2025-04-18）

### 支援多種一般聊天泡泡外觀，並修正先前錯誤配置

- **UI 互動模塊 (`ui_interaction.py`)**：
    - **修正**：先前錯誤地將多外觀支援應用於機器人泡泡。現已修正 `find_dialogue_bubbles` 函數，使其能夠載入並搜尋多組**一般用戶**泡泡的角落模板（例如 `corner_tl_type2.png`, `corner_br_type2.png` 等）。
    - 允許任何類型的一般用戶左上角與任何類型的一般用戶右下角進行配對，只要符合幾何條件。
    - 機器人泡泡的偵測恢復為僅使用預設的 `bot_corner_tl.png` 和 `bot_corner_br.png` 模板。
    - 這提高了對使用了自訂聊天泡泡外觀的**一般玩家**訊息的偵測能力。
- **模板文件**：
    - 在 `ui_interaction.py` 中為一般角落定義了新類型模板的路徑（`_type2`, `_type3`）。
    - **注意：** 需要在 `templates` 資料夾中實際添加對應的 `corner_tl_type2.png`, `corner_br_type2.png` 等圖片檔案才能生效。
- **文件更新 (`ClaudeCode.md`)**：
    - 在「技術實現」部分更新了泡泡檢測的說明。
    - 添加了此「最近改進」條目，並修正了先前的描述。

### 頭像點擊偏移量調整

- **UI 互動模塊 (`ui_interaction.py`)**：
    - 將 `AVATAR_OFFSET_X` 常數的值從 `-50` 調整為 `-55`。
    - 這統一了常規關鍵字觸發流程和 `remove_user_position` 功能中計算頭像點擊位置時使用的水平偏移量。
- **文件更新 (`ClaudeCode.md`)**：
    - 在「技術實現」的「發送者識別」部分強調了點擊位置是相對於觸發泡泡計算的，並註明了新的偏移量。
    - 添加了此「最近改進」條目。

## 開發建議

### 優化方向

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 文件，查看工具調用結果和解析過程