feat(win32): 添加后台托管按键守护，支持后台长按移动

docs/en_us/2.2-IntegratedInterfaceOverview.md

@@ -359,6 +359,9 @@ Set controller options. Will be split into specific options in bindings.
 - ScreenshotResizeMethod  
     Set screenshot resize interpolation method (0=INTER_NEAREST, 1=INTER_LINEAR, 2=INTER_CUBIC, 3=INTER_AREA, 4=INTER_LANCZOS4), default is INTER_AREA(3)
 
+- BackgroundManagedKeys  
+    Declare Win32 background managed key domain. After setting, matching `MaaControllerPostClickKey`, `MaaControllerPostKeyDown`, `MaaControllerPostKeyUp` and pipeline `ClickKey`, `LongPressKey`, `KeyDown`, `KeyUp` operations automatically route through the background guardian path. Only supported by Win32 controllers; other controllers will fail.
+
 ### MaaControllerPostConnection
 
 Asynchronously connect device. This is an asynchronous operation that immediately returns an operation id. You can query the status via `MaaControllerStatus` and `MaaControllerWait`.

docs/en_us/2.4-ControlMethods.md

@@ -99,6 +99,7 @@ Different programs on Win32 handle input differently, so there is no universal m
 > - The `WithCursorPos` methods briefly move the cursor to the target position, then restore it after sending the message, hence "Brief" cursor seizure, but it does not block user operations.
 > - The `WithWindowPos` methods briefly move the window so the target position aligns with the current cursor position, then restore the window position after sending the message. The cursor is not moved, so there is no mouse seizure, but the window may briefly flicker.
 > - Win32 also provides a **Mouse Lock Follow** mode: enable with `MaaControllerSetOption(ctrl, MaaCtrlOption_MouseLockFollow, &enabled, sizeof(bool))` (set `enabled` to `true` to enable, `false` to disable). Designed for TPS/FPS games that lock the mouse to the window in the background. When enabled, the window continuously follows the mouse cursor, and RawInput counter-moves prevent the game from sensing hardware mouse movement. Use `MaaControllerPostRelativeMove` to inject intentional camera rotation while this mode is active. **Note:** On Win32, `MaaControllerPostRelativeMove` requires mouse-lock-follow mode to be active; calling it without this mode will fail. Only supported with MessageInput-based input methods (SendMessage / PostMessage variants).
+> - Win32 also provides a **Background Managed Keys** guardian: declare the managed key domain through `MaaControllerSetOption(ctrl, MaaCtrlOption_BackgroundManagedKeys, keycodes, sizeof(int32_t) * count)` with an array of virtual key codes to manage. After setting, matching key operations automatically route through the background guardian path and continuously correct key state while the controller is idle.
 
 ### Win32 Screencap
 

docs/zh_cn/2.2-集成接口一览.md

@@ -359,6 +359,9 @@
 - ScreenshotResizeMethod  
     设置截图缩放插值方法（0=INTER_NEAREST, 1=INTER_LINEAR, 2=INTER_CUBIC, 3=INTER_AREA, 4=INTER_LANCZOS4），默认为 INTER_AREA(3)
 
+- BackgroundManagedKeys  
+    声明 Win32 后台受管键域。声明成功后，现有 `MaaControllerPostClickKey`、`MaaControllerPostKeyDown`、`MaaControllerPostKeyUp` 以及 pipeline 中的 `ClickKey`、`LongPressKey`、`KeyDown`、`KeyUp` 会对命中的键自动走后台守护路径。该选项仅支持 Win32 控制器；其他控制器设置会失败。
+
 ### MaaControllerPostConnection
 
 异步连接设备。这是一个异步操作，会立即返回一个操作 id，可通过 `MaaControllerStatus` 和 `MaaControllerWait` 查询状态。

docs/zh_cn/2.4-控制方式说明.md

@@ -99,6 +99,7 @@ Win32 下不同程序处理输入的方法不同，不存在一个通用方式
 > - `WithCursorPos` 系列方式会短暂移动光标到目标位置，发送完消息后会将光标移回原位置，因此会“短暂”抢占鼠标，但不会阻止用户操作。
 > - `WithWindowPos` 系列方式会短暂移动窗口，使目标位置与当前光标位置重合，发送完消息后会将窗口移回原位置。不会移动光标，因此不抢占鼠标，但窗口会短暂闪烁。
 > - Win32 还提供了**鼠标锁定跟随模式**（Mouse Lock Follow）：通过 `MaaControllerSetOption(ctrl, MaaCtrlOption_MouseLockFollow, &enabled, sizeof(bool))` 开启（`enabled` 为 `true` 开启，`false` 关闭），适用于 TPS/FPS 等在后台将鼠标锁定到窗口内的游戏。开启后窗口会始终跟随鼠标移动，同时通过 RawInput 对冲阻止游戏感知硬件鼠标位移。配合 `MaaControllerPostRelativeMove` 可在此模式下注入视角旋转。**注意：** Win32 平台的 `MaaControllerPostRelativeMove` 需要先开启鼠标锁定跟随模式，否则调用将失败。仅支持 MessageInput 系列输入方式（SendMessage / PostMessage 及其变体）。
+> - Win32 还提供了**后台受管键守护**（Background Managed Keys）：通过 `MaaControllerSetOption(ctrl, MaaCtrlOption_BackgroundManagedKeys, keycodes, sizeof(int32_t) * count)` 声明需要接管的虚拟键码数组。声明成功后，命中的按键操作自动走后台守护路径，并在控制器空闲时持续修正按键状态。
 
 ### Win32 Screencap
 

include/MaaControlUnit/ControlUnitAPI.h

@@ -101,6 +101,7 @@ class Win32ControlUnitAPI
     virtual ~Win32ControlUnitAPI() = default;
 
     virtual bool set_mouse_lock_follow(bool /*enabled*/) { return false; }
+    virtual bool set_background_managed_keys_option(const int32_t* /*keycodes*/, size_t /*count*/) { return false; }
 };
 
 class MacOSControlUnitAPI

include/MaaFramework/MaaDef.h

@@ -234,6 +234,14 @@ enum MaaCtrlOptionEnum
     ///
     /// value: int, eg: 3; val_size: sizeof(int)
     MaaCtrlOption_ScreenshotResizeMethod = 6,
+
+    /// Configure background managed key domain for Win32 controllers.
+    /// Must be set before connection. After setting, matching ClickKey / LongPressKey / KeyDown / KeyUp
+    /// operations automatically route through the background guardian path.
+    /// Only supported by Win32 controllers; other controllers will fail.
+    ///
+    /// value: int32_t array of virtual key codes; val_size: sizeof(int32_t) * count
+    MaaCtrlOption_BackgroundManagedKeys = 7,
 };
 
 typedef MaaOption MaaTaskerOption;

source/MaaAgentClient/Client/AgentClient.cpp

@@ -2460,6 +2460,27 @@ bool AgentClient::handle_controller_set_option(const json::value& j)
         ret = controller->set_option(key, &v, sizeof(v));
         break;
     }
+    case MaaCtrlOption_BackgroundManagedKeys: {
+        if (!req.value.is_array()) {
+            LogError << "BackgroundManagedKeys value must be an array" << VAR(req.value.type_name());
+            ret = false;
+            break;
+        }
+        std::vector<int32_t> keys;
+        for (const auto& item : req.value.as_array()) {
+            if (!item.is_number()) {
+                LogError << "BackgroundManagedKeys array element must be a number" << VAR(item.type_name());
+                ret = false;
+                break;
+            }
+            keys.push_back(static_cast<int32_t>(item.as_integer()));
+        }
+        if (!ret) {
+            break;
+        }
+        ret = controller->set_option(key, keys.data(), sizeof(int32_t) * keys.size());
+        break;
+    }
     default:
         LogError << "unknown key" << VAR(req.key);
         break;

source/MaaAgentServer/RemoteInstance/RemoteController.cpp

@@ -42,6 +42,21 @@ bool RemoteController::set_option(MaaCtrlOption key, MaaOptionValue value, MaaOp
         jvalue = *reinterpret_cast<const bool*>(value);
         break;
 
+    case MaaCtrlOption_BackgroundManagedKeys: {
+        if (val_size != 0 && val_size % sizeof(int32_t) != 0) {
+            LogError << "invalid val_size for int32_t[] option" << VAR(key) << VAR(val_size);
+            return false;
+        }
+        size_t count = val_size / sizeof(int32_t);
+        auto keycodes = reinterpret_cast<const int32_t*>(value);
+        json::array arr;
+        for (size_t i = 0; i < count; ++i) {
+            arr.emplace_back(keycodes[i]);
+        }
+        jvalue = std::move(arr);
+        break;
+    }
+
     default:
         LogError << "unknown key" << VAR(key);
         return false;

source/MaaFramework/Controller/ControllerAgent.cpp

@@ -45,6 +45,8 @@ bool ControllerAgent::set_option(MaaCtrlOption key, MaaOptionValue value, MaaOpt
         return set_mouse_lock_follow_option(value, val_size);
     case MaaCtrlOption_ScreenshotResizeMethod:
         return set_screenshot_resize_method(value, val_size);
+    case MaaCtrlOption_BackgroundManagedKeys:
+        return set_background_managed_keys_option(value, val_size);
 
     default:
         LogError << "Unknown key" << VAR(key) << VAR(value);
@@ -1250,4 +1252,30 @@ bool ControllerAgent::set_screenshot_resize_method(MaaOptionValue value, MaaOpti
     return true;
 }
 
+bool ControllerAgent::set_background_managed_keys_option(MaaOptionValue value, MaaOptionValueSize val_size)
+{
+    LogDebug;
+
+    if (val_size != 0 && val_size % sizeof(int32_t) != 0) {
+        LogError << "invalid value size: " << val_size;
+        return false;
+    }
+
+    if (!control_unit_) {
+        LogError << "control_unit_ is nullptr";
+        return false;
+    }
+
+    auto win32_unit = std::dynamic_pointer_cast<MAA_CTRL_UNIT_NS::Win32ControlUnitAPI>(control_unit_);
+    if (!win32_unit) {
+        LogError << "Background managed keys is only supported for Win32 controllers.";
+        return false;
+    }
+
+    size_t count = val_size / sizeof(int32_t);
+    auto keycodes = reinterpret_cast<const int32_t*>(value);
+
+    return win32_unit->set_background_managed_keys_option(keycodes, count);
+}
+
 MAA_CTRL_NS_END

source/MaaFramework/Controller/ControllerAgent.h

@@ -290,6 +290,7 @@ class ControllerAgent : public MaaController
     bool set_image_use_raw_size(MaaOptionValue value, MaaOptionValueSize val_size);
     bool set_mouse_lock_follow_option(MaaOptionValue value, MaaOptionValueSize val_size);
     bool set_screenshot_resize_method(MaaOptionValue value, MaaOptionValueSize val_size);
+    bool set_background_managed_keys_option(MaaOptionValue value, MaaOptionValueSize val_size);
 
 private:
     bool need_to_stop_ = false;