feat: Implement PC Logic Adapter and Decision Engine

- Added PcLogicAdapter for handling PC logic input states.
- Introduced RuleBasedDecisionEngine for generating action plans based on observed game states.
- Created StateNormalizer to transform runtime state into ObservedState format.
- Developed TftDataProvider for fetching and caching TFT data from remote sources.
- Implemented services for managing PC logic execution and TFT data retrieval.
- Added tests for RuleBasedDecisionEngine and TftDataProvider to ensure functionality.
- Updated TypeScript configuration for improved module resolution and strict type checking.

Author: rhit-fengr

README.md

@@ -173,6 +173,15 @@ TFT Hextech Helper 是一款基于 Electron + React + TypeScript 开发的云顶
 - **图像识别**: OpenCV.js + Tesseract.js
 - **自动化**: nut-js (鼠标键盘控制)
 
+## 迁移开发辅助（US Android / PC Logic）
+
+为双端迁移新增了以下开发脚本（优先服务安卓模拟器与 PC 纯逻辑阶段）：
+
+- `npm run data:refresh`：拉取官方 TFT 数据（英雄/装备/羁绊/阵容）并刷新本地快照
+- `npm run pc:logic -- <state-json-path>`：对离线局面运行 PC 逻辑引擎，输出动作计划
+- `npm run test:unit`：执行迁移新增核心单元测试（决策引擎 + 数据管线）
+- `npm run typecheck:migration`：仅检查迁移新增模块的 TypeScript 类型
+
 ## 版权说明
 
 本项目采用 **CC BY-NC-ND 4.0** 协议，这意味着：

electron/main.ts

@@ -87,6 +87,8 @@ import {registerOverlayCallbacks} from "../src-backend/utils/OverlayBridge";  //
 // 为了防止在环境检查前加载原生模块导致崩溃，这些模块将在 app.whenReady 中动态导入
 // ============================================================================
 let hexService: any;
+let pcLogicRunner: any;
+let tftDataService: any;
 let tftOperator: any;
 let lineupLoader: any;
 let globalHotkeyManager: any;
@@ -489,6 +491,8 @@ app.whenReady().then(async () => {
         // 1. 加载 HexService (可能依赖 TftOperator)
         const ServicesModule = await import("../src-backend/services");
         hexService = ServicesModule.hexService;
+        pcLogicRunner = ServicesModule.pcLogicRunner;
+        tftDataService = ServicesModule.tftDataService;
 
         // 2. 加载 TftOperator (依赖 nut.js)
         const TftOperatorModule = await import("../src-backend/TftOperator.ts");
@@ -538,6 +542,11 @@ app.whenReady().then(async () => {
     // 加载阵容配置
     const lineupCount = await lineupLoader.loadAllLineups()
     console.log(`📦 [Main] 已加载 ${lineupCount} 个阵容配置`)
+
+    // 预热官方 TFT 数据快照（失败时自动回落到本地快照，不阻塞启动）
+    void tftDataService.refresh(false).catch((error: any) => {
+        console.warn(`⚠️ [Main] TFT 数据预热失败，将使用本地快照: ${error?.message ?? error}`);
+    });
 
     // 注册挂机开关快捷键（从设置中读取）
     const savedHotkey = settingsStore.get('toggleHotkeyAccelerator');
@@ -703,6 +712,16 @@ function registerHandler() {
         }
         return cnToEnMap;
     })
+    ipcMain.handle(IpcChannel.TFT_DATA_REFRESH, async () => {
+        await tftDataService.refresh(true);
+        return tftDataService.getSnapshot();
+    })
+    ipcMain.handle(IpcChannel.TFT_DATA_GET_SNAPSHOT, async () => {
+        return tftDataService.getSnapshot();
+    })
+    ipcMain.handle(IpcChannel.PC_LOGIC_PLAN_ONCE, async (_event, state: any, context?: any) => {
+        return pcLogicRunner.planOnce(state, context);
+    })
 
     // TFT 游戏模式相关
     ipcMain.handle(IpcChannel.TFT_GET_MODE, async () => settingsStore.get('tftMode'))
@@ -871,4 +890,4 @@ function registerHandler() {
             return { error: error.message || '检查更新失败' };
         }
     })
-}
+}

electron/protocol.ts

@@ -35,6 +35,9 @@ export enum IpcChannel {
     LINEUP_DELETE = 'lineup-delete',            // 删除玩家自建阵容
     // 棋子数据相关
     TFT_GET_CHAMPION_CN_TO_EN_MAP = 'tft-get-champion-cn-to-en-map',  // 获取棋子中英文映射表
+    TFT_DATA_REFRESH = 'tft-data-refresh',      // 强制刷新官方 TFT 数据快照
+    TFT_DATA_GET_SNAPSHOT = 'tft-data-get-snapshot', // 读取当前 TFT 数据快照
+    PC_LOGIC_PLAN_ONCE = 'pc-logic-plan-once',  // 运行一次 PC 纯逻辑决策（不执行输入）
     // 游戏模式相关
     TFT_GET_MODE = 'tft-get-mode',              // 获取当前 TFT 模式（匹配/排位）
     TFT_SET_MODE = 'tft-set-mode',              // 设置 TFT 模式
@@ -79,4 +82,4 @@ export enum IpcChannel {
     OVERLAY_SHOW = 'overlay-show',                        // 显示浮窗（传入游戏窗口坐标）
     OVERLAY_CLOSE = 'overlay-close',                      // 关闭浮窗
     OVERLAY_UPDATE_PLAYERS = 'overlay-update-players',    // 更新玩家列表数据（主进程 -> 浮窗渲染进程）
-}
+}