hwJinny · Aug 13, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/maa-cli/Cargo.toml b/crates/maa-cli/Cargo.toml
@@ -43,6 +43,11 @@ toml = { workspace = true }
 ureq = { workspace = true, features = ["json", "platform-verifier"] }
 
 [target.'cfg(windows)'.dependencies]
+windows-sys = { workspace = true, features = [
+  "Win32_Foundation",
+  "Win32_System_Threading",
+  "Win32_UI_WindowsAndMessaging",
+] }
 winreg = { workspace = true }
 
 [dev-dependencies]

diff --git a/crates/maa-cli/config_examples/profiles/default.toml b/crates/maa-cli/config_examples/profiles/default.toml
@@ -17,6 +17,18 @@ config = "CompatMac"     # connect config name
 # address = "localhost:1717" # PlayTools address
 # config = "CompatMac"       # connect config name
 
+# 3. Attach to the official Windows PC client (Windows only, no ADB)
+# The title is matched exactly against visible top-level windows. Set a PID or executable path
+# when more than one window has the same title. The control method values below are defaults.
+# [connection]
+# preset = "Win32"
+# window_title = "Arknights"
+# window_process_id = 1234                         # optional disambiguator
+# window_executable = "C:\\Games\\Arknights.exe" # optional canonical path match
+# screencap_method = 2                             # FramePool
+# mouse_method = 32                                # SendMessageWithCursorPos
+# keyboard_method = 2                             # SendMessage
+
 
 # Resource options for MAA Core
 [resource]

diff --git a/crates/maa-cli/docs/en-US/config.md b/crates/maa-cli/docs/en-US/config.md
@@ -356,6 +356,22 @@ There are two special presets: `PlayCover` (macOS) and `Waydroid` (Linux)
    session is already running, starts one if needed, and then connects ADB via `waydroid adb connect`.
    See [Waydroid documentation][waydroid-doc] for details.
 
+- `Win32` attaches MaaCore to the official Windows PC client without ADB. It is only available on Windows.
+
+   `window_title` is required and must exactly match a visible top-level window. `window_process_id` and `window_executable` are optional disambiguators; the executable is compared by canonical path. The default control methods are `screencap_method = 2` (`FramePool`), `mouse_method = 32` (`SendMessageWithCursorPos`), and `keyboard_method = 2` (`SendMessage`).
+
+   `MaaWin32ControlUnit.dll` must be installed beside `MaaCore.dll`. The `PC` platform resources are loaded automatically. maa-cli does not launch the PC client, and it disables `StartUp.start_game_enabled` for this preset, so start the selected client before running a task.
+
+```toml
+[connection]
+preset = "Win32"
+window_title = "Arknights"
+window_process_id = 1234 # optional
+window_executable = "C:\\Games\\Arknights.exe" # optional
+```
+
+Use `maa connection test --profile <name> --screencap --json` to attach and verify a non-empty screenshot without running tasks. On success it exits with code 0 and prints `{"ok":true,"connection":"Win32","screenshot_bytes":...}`.
+
 ### Resource
 
 The `resource` section specifies which resources MaaCore should load:
@@ -367,7 +383,7 @@ platform_diff_resource = "iOS" # Non-Android resources
 user_resource = true # Whether to load user-defined resources
 ```
 
-When using a non-Simplified Chinese game client, set `global_resource` to load non-Chinese resources. When using an iOS client, set `platform_diff_resource` to `iOS`. Both are optional - leave empty to not load these resources. These are also auto-set based on your `startup` task's `client_type` and when using `PlayTools` connection. To load user-defined resources, set `user_resource` to `true`, which loads resources from `$MAA_CONFIG_DIR/resource`.
+When using a non-Simplified Chinese game client, set `global_resource` to load non-Chinese resources. When using an iOS client, set `platform_diff_resource` to `iOS`. Both are optional - leave empty to not load these resources. These are also auto-set based on your `startup` task's `client_type`, `PlayTools` connections load `iOS`, and `Win32` connections load `PC`. To load user-defined resources, set `user_resource` to `true`, which loads resources from `$MAA_CONFIG_DIR/resource`.
 
 ### Static options
 

diff --git a/crates/maa-cli/docs/ko-KR/config.md b/crates/maa-cli/docs/ko-KR/config.md
@@ -333,6 +333,22 @@ address = "127.0.0.1:7777" # 필요 시 사전 설정된 주소를 재정의할
 
 - `Waydroid`는 Linux에서 `Waydroid`를 통해 Android 앱을 실행하는 데 사용됩니다。이 경우 MaaCore의 장치 연결에 `adb_path`를 지정해야 합니다。maa-cli는 `waydroid status`를 사용하여 세션이 이미 실행 중인지 감지하고, 필요 시 세션을 시작한 다음 `waydroid adb connect`를 통해 ADB 연결을 설정합니다。자세한 내용은 [Waydroid 지원 문서][waydroid-doc]을 참조하세요。
 
+- `Win32`는 ADB 없이 명일방주 공식 Windows PC 클라이언트 창에 MaaCore를 연결하며 Windows에서만 사용할 수 있습니다.
+
+   `window_title`은 필수이며 표시 중인 최상위 창 제목과 정확히 일치해야 합니다. 동일한 제목의 창이 둘 이상이면 `window_process_id` 또는 정규화된 경로로 비교되는 `window_executable`을 지정해야 합니다. 기본 제어 방식은 `screencap_method = 2`(`FramePool`), `mouse_method = 32`(`SendMessageWithCursorPos`), `keyboard_method = 2`(`SendMessage`)입니다.
+
+   `MaaWin32ControlUnit.dll`이 `MaaCore.dll`과 같은 디렉터리에 있어야 하며 `PC` 플랫폼 리소스는 자동으로 로드됩니다. maa-cli는 PC 클라이언트를 직접 실행하지 않고 이 프리셋에서는 `StartUp.start_game_enabled`를 비활성화하므로, 작업 실행 전에 선택한 클라이언트를 시작해야 합니다.
+
+```toml
+[connection]
+preset = "Win32"
+window_title = "Arknights"
+window_process_id = 1234 # 선택 사항
+window_executable = "C:\\Games\\Arknights.exe" # 선택 사항
+```
+
+작업을 실행하지 않고 창 연결과 스크린샷을 검증하려면 `maa connection test --profile <이름> --screencap --json`을 사용하세요. 성공하면 종료 코드 0과 `{"ok":true,"connection":"Win32","screenshot_bytes":...}`를 출력합니다.
+
 ### 리소스 설정
 
 `[resource]` 관련 필드는 MaaCore가 로드하는 리소스를 지정하는 데 사용됩니다:
@@ -344,7 +360,7 @@ platform_diff_resource = "iOS" # 비 안드로이드 버전의 리소스
 user_resource = true # 사용자 정의 리소스를 로드할지 여부
 ```
 
-비 중국어 게임 클라이언트를 사용할 때, MaaCore는 기본적으로 간체 중국어 리소스를 로드하기 때문에 `global_resource` 필드를 지정하여 비중문 버전의 리소스를 로드해야 합니다. iOS 버전의 게임 클라이언트를 사용할 때는 `platform_diff_resource` 필드를 지정하여 iOS 버전의 리소스를 로드해야 합니다. 이 두 필드는 선택 사항이며, 리소스를 로드할 필요가 없는 경우 두 필드를 비워둘 수 있습니다. 또한, `startup` 작업에서 `client_type` 필드를 지정한 경우 `global_resource`는 해당 클라이언트의 리소스로 설정되며, `PlayTools` 연결을 사용하는 경우 `platform_diff_resource`는 iOS로 설정됩니다. 마지막으로 사용자 정의 리소스를 로드하려는 경우 `user_resource` 필드를 `true`로 설정해야 합니다.
+비 중국어 게임 클라이언트를 사용할 때, MaaCore는 기본적으로 간체 중국어 리소스를 로드하기 때문에 `global_resource` 필드를 지정하여 비중문 버전의 리소스를 로드해야 합니다. iOS 버전의 게임 클라이언트를 사용할 때는 `platform_diff_resource` 필드를 지정하여 iOS 버전의 리소스를 로드해야 합니다. 이 두 필드는 선택 사항이며, 리소스를 로드할 필요가 없는 경우 두 필드를 비워둘 수 있습니다. 또한, `startup` 작업에서 `client_type` 필드를 지정한 경우 `global_resource`는 해당 클라이언트의 리소스로 설정되며, `PlayTools` 연결은 `iOS`, `Win32` 연결은 `PC` 플랫폼 리소스를 자동으로 설정합니다. 마지막으로 사용자 정의 리소스를 로드하려는 경우 `user_resource` 필드를 `true`로 설정해야 합니다.
 
 ### 정적 옵션
 

diff --git a/crates/maa-cli/docs/zh-CN/config.md b/crates/maa-cli/docs/zh-CN/config.md
@@ -337,6 +337,22 @@ address = "127.0.0.1:7777" # 如果你需要的话，你可以覆盖预设的地
 - `Waydroid`用于在 Linux 上连接直接通过 `Waydroid` 原生运行的游戏客户端。这种情况下仍需要指定 `adb_path` 供 MaaCore 连接设备使用。maa-cli 会自动管理会话：通过 `waydroid status` 检测会话是否已在运行，必要时启动会话，然后通过 `waydroid adb connect` 建立 ADB 连接。
   具体使用参见 [Waydroid 支持文档][waydroid-doc].
 
+- `Win32` 不通过 ADB，而是让 MaaCore 附加到明日方舟官方 Windows PC 客户端窗口；该预设仅支持 Windows。
+
+  `window_title` 为必填项，且必须与可见顶层窗口的标题完全一致。如果多个窗口标题相同，可使用 `window_process_id` 或按规范化路径匹配的 `window_executable` 来消除歧义。默认控制方式为 `screencap_method = 2`（`FramePool`）、`mouse_method = 32`（`SendMessageWithCursorPos`）和 `keyboard_method = 2`（`SendMessage`）。
+
+  `MaaWin32ControlUnit.dll` 必须与 `MaaCore.dll` 位于同一目录，`PC` 平台资源会自动加载。maa-cli 不负责启动 PC 客户端，并会在该预设下禁用 `StartUp.start_game_enabled`，因此运行任务前需要先启动所选客户端。
+
+```toml
+[connection]
+preset = "Win32"
+window_title = "Arknights"
+window_process_id = 1234 # 可选
+window_executable = "C:\\Games\\Arknights.exe" # 可选
+```
+
+可使用 `maa connection test --profile <名称> --screencap --json` 在不运行任务的情况下附加窗口并验证截图非空。成功时退出码为 0，并输出 `{"ok":true,"connection":"Win32","screenshot_bytes":...}`。
+
 ### 资源配置
 
 `[resource]` 相关字段用于指定 MaaCore 加载的资源：
@@ -348,7 +364,7 @@ platform_diff_resource = "iOS" # 非安卓版本的资源
 user_resource = true # 是否加载用户自定义的资源
 ```
 
-当使用非简体中文游戏客户端时，由于 MaaCore 默认加载的资源是简体中文的，你需要指定 `global_resource` 字段来加载非中文版本的资源。当使用 iOS 版本的游戏客户端时，你需要指定 `platform_diff_resource` 字段来加载 iOS 版本的资源。这两者都是可选的，如果你不需要加载这些资源，你可以将这两个字段设置为空。其次，这两者也会被自动设置，如果你的 `startup` 任务中指定了 `client_type` 字段，那么 `global_resource` 将会被设置为对应客户端的资源，而当你使用 `PlayTools` 连接时，`platform_diff_resource` 将会被设置为 `iOS`。最后，当你想要加载用户自定义的资源时，你需要将 `user_resource` 字段设置为 `true`。
+当使用非简体中文游戏客户端时，由于 MaaCore 默认加载的资源是简体中文的，你需要指定 `global_resource` 字段来加载非中文版本的资源。当使用 iOS 版本的游戏客户端时，你需要指定 `platform_diff_resource` 字段来加载 iOS 版本的资源。这两者都是可选的，如果你不需要加载这些资源，你可以将这两个字段设置为空。其次，这两者也会被自动设置，如果你的 `startup` 任务中指定了 `client_type` 字段，那么 `global_resource` 将会被设置为对应客户端的资源；`PlayTools` 连接会加载 `iOS`，`Win32` 连接会加载 `PC` 平台资源。最后，当你想要加载用户自定义的资源时，你需要将 `user_resource` 字段设置为 `true`。
 
 ### 静态选项
 

diff --git a/crates/maa-cli/schemas/asst.schema.json b/crates/maa-cli/schemas/asst.schema.json
@@ -8,7 +8,7 @@
       "properties": {
         "preset": {
           "type": "string",
-          "enum": ["ADB", "PlayCover", "MuMuPro", "Waydroid"],
+          "enum": ["ADB", "PlayCover", "MuMuPro", "Waydroid", "Win32"],
           "default": "ADB"
         },
         "adb_path": {
@@ -17,8 +17,23 @@
           "default": "adb"
         },
         "address": { "type": "string" },
-        "config": { "type": "string" }
-      }
+        "config": { "type": "string" },
+        "window_title": { "type": "string", "minLength": 1 },
+        "window_process_id": { "type": "integer", "minimum": 1 },
+        "window_executable": { "type": "string", "format": "path" },
+        "screencap_method": { "type": "integer", "minimum": 0, "default": 2 },
+        "mouse_method": { "type": "integer", "minimum": 0, "default": 32 },
+        "keyboard_method": { "type": "integer", "minimum": 0, "default": 2 }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "preset": { "const": "Win32" } },
+            "required": ["preset"]
+          },
+          "then": { "required": ["window_title"] }
+        }
+      ]
     },
     "resource": {
       "type": "object",

diff --git a/crates/maa-cli/src/command.rs b/crates/maa-cli/src/command.rs
@@ -88,6 +88,9 @@ pub(crate) enum Command {
         #[arg(default_value = "all")]
         component: Component,
     },
+    /// Test a configured MaaCore connection without running tasks
+    #[command(subcommand)]
+    Connection(ConnectionCommand),
     /// Run a custom task
     ///
     /// All arguments will be passed to maa-run,
@@ -246,6 +249,12 @@ pub(crate) enum Command {
     },
 }
 
+#[derive(Subcommand)]
+pub(crate) enum ConnectionCommand {
+    /// Connect or attach to the configured client and optionally capture one screenshot
+    Test(run::ConnectionTestArgs),
+}
+
 #[cfg(feature = "cli_installer")]
 #[derive(Subcommand)]
 #[command(name = "self")]
@@ -544,6 +553,28 @@ mod test {
         ));
     }
 
+    #[test]
+    fn connection_test() {
+        assert_matches!(
+            parse_from([
+                "maa",
+                "connection",
+                "test",
+                "--profile",
+                "arkconsole",
+                "--screencap",
+                "--json",
+            ])
+            .command,
+            Command::Connection(ConnectionCommand::Test(run::ConnectionTestArgs {
+                profile: Some(profile),
+                screencap: true,
+                json: true,
+                ..
+            })) if profile == "arkconsole"
+        );
+    }
+
     #[test]
     fn convert() {
         assert_matches!(