專案鍵盤操作體系說明

本專案支援高度可配置的遊戲鍵盤操作，所有熱鍵均可通過配置自定義，支援多場景（通用、工業、戰鬥）下的快捷鍵對映。本文件詳細介紹鍵盤操作的設計、預設鍵位、擴充套件方式及開發注意事項。

1. 按鍵配置體系概覽

可配置熱鍵統一管理：業務程式碼通過 KeyConfigManager 解析通用、工業和戰鬥鍵位；移動鍵、系統修飾鍵及少數遊戲固定鍵保留底層傳送路徑。
三大類熱鍵：
- 通用（common）：如地圖、互動、背包等
- 整合工業（industry）：如工業規劃、放置傳送帶等
- 戰鬥（combat）：如連攜技等
國際化支援：所有鍵名均有 i18n 支援，便於多語言適配。

2. 預設鍵位表

通用（DEFAULT_COMMON_KEYS）

配置鍵名	預設按鍵	說明
Dodge Key	lshift	閃避
Jump Key	space	跳躍
Interact Key	f	互動
Backpack Key	b	背包
Valuables Key	n	貴重品
Team Key	u	隊伍
Operator Key	c	幹員
Mission Key	j	任務
Track Key	v	追蹤
Map Key	m	地圖
Baker Key	h	帝江號
Mail Key	k	郵件
Handbook Key	f8	手冊
Recruitment Key	f9	招募
Quick Tool Key	r	快捷工具

整合工業（DEFAULT_INDUSTRY_KEYS）

配置鍵名	預設按鍵	說明
Industry Plan Key	t	工業規劃
Place Belt Key	e	放置傳送帶
Place Pipeline Key	q	放置管道
Equipment List Key	z	裝置列表
Overview Mode Key	capslock	全域性檢視
Storage Mode Key	x	倉庫模式
Area Build Key	y	區域建造
Blueprint Key	f1	藍圖
Product Icon Toggle Key	f4	產品圖示切換

戰鬥（DEFAULT_COMBAT_KEYS）

配置鍵名	預設按鍵	說明
Link Skill Key	e	連攜技

3. 按鍵呼叫方式

3.1 業務層介面

press_key(key, **kwargs)：傳送通用按鍵（如地圖、互動等）。
press_industry_key(key, **kwargs)：傳送工業專用熱鍵。
press_combat_key(key, **kwargs)：傳送戰鬥專用熱鍵。
press_esc()：僅過劇情（對話時）觸發 ESC。

前三個介面定義在 RuntimeMixin，簽名為 (key, down_time=0.02, after_sleep=0, interval=-1)，並把解析後的鍵傳給 send_key()。press_esc() 定義在 GameFlowMixin，只允許用於劇情對話跳過。專案當前沒有 press_game_key() 公共方法。

3.2 按鍵對映流程

flowchart TD
    A[业务层调用 press_key / press_industry_key / press_combat_key] --> B[选择 common / industry / combat 默认键表]
    B --> C[KeyConfigManager.resolve_key]
    C --> D{默认按键是否匹配配置项}
    D -->|是| E[读取用户自定义键]
    D -->|否| F[保留原始按键]
    E --> G[调用 send_key 发送实际按键]
    F --> G

業務層呼叫如 press_key('m')。
通過 KeyConfigManager.resolve_key('m', 'common') 在對應預設鍵表中反查配置項名。
若使用者有自定義，則取自定義值，否則用預設值。
最終通過底層 send_key進行物理按鍵模擬。

3.3 未知鍵與異常

resolve_key() 不校驗鍵名：預設表中找不到鍵，或 key_type 不是 common/industry/combat 時，原樣返回傳入的 key。
RuntimeMixin.send_key() 會先啟用遊戲視窗，再委託框架 BaseTask.send_key()；框架會先用 validate_key() 校驗單字元和已知命名鍵，無效鍵會丟擲 HotkeyConfigException，專案層不捕獲該異常。
校驗通過後，EfInteraction._convert_key() 再把常見別名（如 esc、lctrl、pageup）轉換為 pynput 鍵物件；底層傳送異常仍會向呼叫方傳播。
因此新增業務鍵位時應先加入 KeyConfig.py 的對應預設表；不要依賴未知鍵的透傳作為配置機制。

4. 使用者自定義與國際化

使用者可通過配置檔案自定義所有熱鍵。
支援多語言鍵名，語言資源目錄：i18n。

5. 開發注意事項

可配置遊戲熱鍵不得直接使用 send_key，必須通過 press_key、press_industry_key 或 press_combat_key 呼叫（第 6 節列出的例外除外）。
若熱鍵可自定義，則不可用作模板圖片（否則模板匹配會因使用者自定義失效）。
詳細開發規範：DEVELOPMENT.md。

6. 直接使用底層鍵盤介面的位置

以下是當前直接呼叫 send_key / send_key_down / send_key_up 或 Win32 keybd_event 的專案程式碼。部分呼叫沒有就地註釋，表中按當前行為記錄，不代表所有繞過鍵位對映的呼叫都合理：

檔案	行號/方法	按鍵	原因
`src/core/base_mixin/runtime_mixin.py`	`press_key` / `press_industry_key` / `press_combat_key` 方法體	動態	這三個方法本身就是對 `send_key` 的配置對映封裝
`src/core/base_mixin/runtime_mixin.py`	`click_with_alt` 方法	`alt`	`alt` 為系統修飾鍵，用於 alt+點選操作
`src/interaction/Key.py`	`move_keys` 方法	動態移動鍵	持續按下和釋放移動鍵的底層輔助函式
`src/interaction/Mouse.py`	`active_and_send_mouse_delta` 的視窗啟用回退	Win32 `VK_MENU`	`SetForegroundWindow` 失敗時用 `win32api.keybd_event` 短按 Alt 解除前臺視窗限制
`src/core/base_mixin/game_flow_mixin.py`	`skip_dialog` 方法	`esc`	`esc` 為系統通用退出鍵
`src/tasks/onetime/AutoCombatLogic.py`	普通技能釋放邏輯	動態技能鍵	技能鍵為遊戲固定不可配置鍵，不經過 `KeyConfigManager` 管理
`src/tasks/mixin/battle_mixin.py`	`use_ult` 方法	`1`/`2`/`3`/`4`	終極技鍵位為遊戲固定不可配置鍵，不經過 `KeyConfigManager` 管理
`src/tasks/mixin/liaison_mixin.py`	幹員互動導航回撥 / `click_chat_box` 方法	`alt`	`alt` 為系統修飾鍵，用於 alt+點選幹員聊天框，非遊戲可配置熱鍵
`src/tasks/mixin/liaison_mixin.py`	導航過程中釋放移動鍵	`w`	`w` 為方向移動鍵，不屬於遊戲可配置熱鍵
`src/tasks/mixin/navigation_mixin.py`	`navigate_until_target` 方法	`w` / `s`	`w`/`s` 為方向移動鍵，用於持續移動/後退搜尋，不屬於遊戲可配置熱鍵
`src/tasks/daily/misc/daily_reward_mixin.py`	每日獎勵領取邏輯	`esc`	`esc` 為系統通用退出鍵
`src/tasks/daily/daily_task_runner.py`	任務開始前切奔跑模式	`shift`	`shift` 為奔跑切換鍵，遊戲固定不可配置鍵
`src/tasks/trigger/AutoInteractionTask.py`	`run` 方法	`esc`	`esc` 為系統通用退出鍵，非遊戲可配置熱鍵
`src/tasks/onetime/WarehouseTransferTask.py`	倉庫切換檢測邏輯	`esc`	`esc` 為系統通用退出鍵，非遊戲可配置熱鍵
`src/tasks/onetime/WarehouseTransferTask.py`	`_ctrl_click` 方法	Win32 `VK_CONTROL`	直接用 `win32api.keybd_event` 按下/釋放 Ctrl，以配合點選多選；不經過 `send_key` 或 `KeyConfigManager`
`src/tasks/mixin/zip_line_mixin.py`	`zip_line_list_go` / `ensure_click_on_zip_line` 方法	`e`	滑索推進互動鍵為遊戲固定不可改綁鍵，且短距離滑索需高頻重複輸入避免漏觸發
`src/tasks/onetime/DeliveryTask.py`	取貨/送達導航	`v`	導航迴圈中重置追蹤視野；`v` 同時是可配置的 `Track Key` 預設值，當前直接傳送會繞過使用者改綁，是已知例外而非固定鍵
`src/tasks/onetime/YingTuoTask.py`	豐碑互動	`e`	當前任務直接傳送固定互動鍵；修改該流程時應重新確認是否仍不可改綁

說明：大多數呼叫屬於系統修飾/退出鍵、移動鍵或當前流程認定的固定遊戲鍵。DeliveryTask 直接傳送的 v 是可配置 Track Key 的預設值，因而不會遵循使用者改綁；YingTuoTask 的固定 e 也應在修改流程時重新確認。當前並非每個例外都有程式碼註釋；新增或調整直接底層呼叫時，應新增原因註釋並同步本表。

7. 參考

熱鍵配置器程式碼
按鍵函式封裝
應用配置
開發文件：API.md, DEVELOPMENT.md
國際化資源：../../i18n/

擴充套件新熱鍵時，請在 KeyConfig.py 的預設鍵表中補充，並完善 i18n 資源。