mcpywrap 0.3.8__tar.gz → 0.3.9__tar.gz

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 更新记录
 
+## 0.3.9
+
+- 截图默认使用 Windows Graphics Capture 捕获游戏客户区；被其他窗口遮挡时仍可读取画面，且不抢占前台。后台捕获不可用时自动回退到原有前台截图，并返回捕获方式和回退原因。
+- 键盘和鼠标操作继续在执行前激活游戏窗口，操作后不恢复此前的前台窗口。新增 x64 捕获辅助程序及完整性校验；已在 Minecraft 3.10 实机验证 DirectX 画面、遮挡、DPI 尺寸和 F3 输入。
+
 ## 0.3.8
 
 - 新增标准 Git 项目依赖：固定提交、导出结构识别、递归子依赖、循环/冲突检测、内容锁定，以及更新、回退和移除；克隆后通过 `mcpy sync` 恢复。

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/MANIFEST.in

@@ -6,9 +6,14 @@ include docs/code-libraries.md docs/git-dependencies.md docs/qumod.md
 recursive-include tests *.py
 recursive-include skills *.md *.yaml *.ps1 *.py
 include scripts/build_mcs_auth_bridge.py
+include scripts/build_all_native.py
+include scripts/build_window_capture.py
+include scripts/check_window_capture.py
 include scripts/check_mcs_auth_bridge.py
 recursive-include native/mcs_auth *.cs *.c *.cer *.json
 recursive-include mcpywrap/mcstudio/bridge_payload *.exe *.dll *.cer *.json
+recursive-include mcpywrap/mcstudio/window_capture *.exe *.json
+recursive-include native/window_capture *.cpp
 prune test
 prune .git
 global-exclude __pycache__ *.py[cod] *.cppconfig *.log

{mcpywrap-0.3.8/mcpywrap.egg-info → mcpywrap-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.8
+Version: 0.3.9
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -46,6 +46,8 @@ uv tool install mcpywrap
 
 也可以使用 `pip install mcpywrap`。安装完成后，运行 `mcpy --help` 查看命令。
 
+从 Windows 源码检出安装时，先安装 Visual Studio 的 x86/x64 C++ 构建工具，再运行 `python scripts/build_all_native.py` 一次编译全部原生组件，最后执行 `pip install -e .`。正式发布包由 CI 编译并附带原生组件，普通安装无需本机编译。
+
 ## 开始使用
 
 进入你的 Addon 或地图项目目录，按向导初始化：

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/README.md

@@ -19,6 +19,8 @@ uv tool install mcpywrap
 
 也可以使用 `pip install mcpywrap`。安装完成后，运行 `mcpy --help` 查看命令。
 
+从 Windows 源码检出安装时，先安装 Visual Studio 的 x86/x64 C++ 构建工具，再运行 `python scripts/build_all_native.py` 一次编译全部原生组件，最后执行 `pip install -e .`。正式发布包由 CI 编译并附带原生组件，普通安装无需本机编译。
+
 ## 开始使用
 
 进入你的 Addon 或地图项目目录，按向导初始化：

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/docs/releasing.md

@@ -3,6 +3,9 @@
 主分支和 PR 运行 Windows Python 3.9、3.12、3.14 的自动化测试，以及 macOS 的无 Qt 安装、项目构建与远程客户端测试。通过后构建 wheel/sdist、运行严格元数据检查、检查产物内容，并在独立环境安装 wheel 验证 CLI 和模块导入。
 
 Windows CI 先用 MSVC 从 `native/mcs_auth` 编译 x86 登录桥接，再签名并通过构建产物交给测试和 Python 打包任务；编译后的 EXE/DLL 不提交到 Git。仓库只保留发布者公钥证书和指纹。
+同一 native job 还会从 `native/window_capture` 编译 x64 后台截图辅助程序，生成 SHA-256 清单；测试和打包阶段校验二进制、源码及 wheel/sdist 内容。辅助程序不可用时运行时回退到前台截图。
+
+从源码安装时，在 Windows x64 且已安装 Visual Studio x86/x64 C++ 工具的环境中先运行 `python scripts/build_all_native.py`，再执行 `pip install -e .` 或 `pip install .`。脚本一次编译 x86 登录桥接和 x64 截图程序到包目录；可用 `--output-root <目录>` 将结果放入隔离目录。登录桥接源码编译产物没有发布签名，正式登录能力仍应使用带签名的发布包。
 
 仓库 Actions secrets：`MCS_BRIDGE_SIGNING_PFX` 保存 Base64 编码的加密 PFX，`MCS_BRIDGE_SIGNING_PASSWORD` 保存独立的强密码。只有 main／发布标签的签名步骤可读取它们，PR 只构建未签名测试产物。CI 将证书导入临时 runner 的个人证书库，签名后清理，不安装根信任。私钥、PFX 和密码均不进入日志或 artifact。
 

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """mcpywrap - 我的世界中国版 Addon 开发依赖、构建与游戏测试工具。"""
 
-__version__ = '0.3.8'
+__version__ = '0.3.9'

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/commands/package_cmd.py

@@ -52,6 +52,10 @@ def package_cmd(merge):
                     # 新构建器保留源包目录名；分发包仍遵循 PR 的 name_bp/name_rp 约定。
                     for kind, suffix in (('behavior', 'bp'), ('resource', 'rp')):
                         folder = getattr(builder.target_addon, kind + '_pack_dir')
+                        # 网易上传错误码24检查行为包entities目录；纯脚本Addon也保留
+                        # 空目录条目，不创建虚构实体，不修改项目源码或外层包名。
+                        if kind == 'behavior' and folder and Path(folder).is_dir():
+                            (Path(folder) / 'entities').mkdir(exist_ok=True)
                         _zip_dir_keep_empty(zipf, folder, f'{name}_{suffix}')
                 else:
                     _zip_dir_keep_empty(zipf, output, '')

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/mcstudio/bridge_payload/manifest.json

@@ -11,9 +11,9 @@
     "Loader.c": "f2f1f781ce82fc30c62a6ce22bb048d3b023f6ff500e6ec8228da28b4dbf1b4a"
   },
   "files": {
-    "Injector.exe": "077d4d84bfa3d7f9fac2485bc7bc3def415596a94ef2fe0815580446ee4552b6",
-    "Loader.dll": "ea081696b47cb16dfed8b61a95ffbba7d4a66de7bb1769f477cb688099186527",
-    "McpyMcsAuth.dll": "7f0f72b3d38577823e7e280d6378692f9fdfe7f2c0546938aea03312c59431f3",
+    "Injector.exe": "c2419774ecad30ad49e705d584223343bd1b26633879750d583a05c8fd563acf",
+    "Loader.dll": "8a3e2b44747d71ed05bf30bc0d752324c8b9e296653369a7fd9bdf4e0a2effce",
+    "McpyMcsAuth.dll": "c7d8caf91c26aedf00ae3fe4713d040da8c74393e53f17f57e3fe9960bce7a2c",
     "publisher.cer": "e5aa2ac39df40804ed8b08fe8e43c4a2b8923f0d02a360708486b2db5b6303d7"
   }
 }

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/mcstudio/window.py

@@ -1,8 +1,11 @@
 """Windows 游戏会话的键盘输入与客户区截图，仅依赖 Python 标准库。"""
 import ctypes as C
 from ctypes import wintypes as W
+import hashlib
+import json
 import os
 from pathlib import Path
+import subprocess
 import struct
 import time
 import zlib
@@ -169,6 +172,10 @@ class BitmapHeader(C.Structure):
                 ('used', W.DWORD), ('important', W.DWORD)]
 
 
+class BackgroundCaptureUnavailable(ValueError):
+    """The optional background capture path cannot produce a frame."""
+
+
 class GameWindow:
     def __init__(self, game, cancel=None):
         if os.name != 'nt':
@@ -331,30 +338,37 @@ class GameWindow:
                 'sent': True, 'released': True, 'effect_verified': False}
 
     def client_area(self):
+        return self._client_area(require_foreground=True, require_uncovered=True)
+
+    def _client_area(self, *, require_foreground, require_uncovered):
         rect, point = W.RECT(), W.POINT()
         if not self.user.GetClientRect(self.hwnd, C.byref(rect)) or not self.user.ClientToScreen(self.hwnd, C.byref(point)):
             raise ValueError('无法获取游戏客户区')
         width, height = rect.right, rect.bottom
         if not 1 <= width * height <= 32_000_000:
             raise ValueError('游戏窗口尺寸无效或超过 3200 万像素')
-        left, top = self.user.GetSystemMetrics(76), self.user.GetSystemMetrics(77)
-        if not (left <= point.x and top <= point.y and point.x + width <= left + self.user.GetSystemMetrics(78)
-                and point.y + height <= top + self.user.GetSystemMetrics(79)):
-            raise ValueError('游戏客户区部分位于屏幕外，无法可靠截图')
-        # 可见截图要求无上层窗口覆盖；宁可拒绝，也不截取其他应用内容。
-        for hwnd in self.windows():
-            if hwnd == self.hwnd:
-                break
-            if self.usable(hwnd) and not self.user.IsIconic(hwnd):
-                other = W.RECT()
-                if self.user.GetWindowRect(hwnd, C.byref(other)) and (
-                    max(other.left, point.x) < min(other.right, point.x + width) and
-                    max(other.top, point.y) < min(other.bottom, point.y + height)):
-                    raise ValueError('游戏客户区被其他窗口覆盖，请移开后重试')
-        self.check_foreground()
+        if require_foreground or require_uncovered:
+            left, top = self.user.GetSystemMetrics(76), self.user.GetSystemMetrics(77)
+            if not (left <= point.x and top <= point.y and point.x + width <= left + self.user.GetSystemMetrics(78)
+                    and point.y + height <= top + self.user.GetSystemMetrics(79)):
+                raise ValueError('游戏客户区部分位于屏幕外，无法可靠截图')
+        if require_uncovered:
+            # 可见截图要求无上层窗口覆盖；宁可拒绝，也不截取其他应用内容。
+            for hwnd in self.windows():
+                if hwnd == self.hwnd:
+                    break
+                if self.usable(hwnd) and not self.user.IsIconic(hwnd):
+                    other = W.RECT()
+                    if self.user.GetWindowRect(hwnd, C.byref(other)) and (
+                        max(other.left, point.x) < min(other.right, point.x + width) and
+                        max(other.top, point.y) < min(other.bottom, point.y + height)):
+                        raise ValueError('游戏客户区被其他窗口覆盖，请移开后重试')
+        if require_foreground:
+            self.check_foreground()
         return width, height, point
 
     def screenshot(self):
+        """Capture the visible client area after making the game foreground."""
         self.foreground()
         width, height, point = self.client_area()
         screen = self.user.GetDC(None)
@@ -393,6 +407,73 @@ class GameWindow:
             if screen:
                 self.user.ReleaseDC(None, screen)
 
+    def _background_helper(self):
+        if os.name != 'nt':
+            raise BackgroundCaptureUnavailable('Windows Graphics Capture 仅支持 Windows')
+        helper = Path(__file__).with_name('window_capture') / 'mcpy-window-capture.exe'
+        if not helper.is_file():
+            raise BackgroundCaptureUnavailable('未安装 Windows Graphics Capture 辅助程序')
+        try:
+            manifest = json.loads(helper.with_name('manifest.json').read_text(encoding='utf-8'))
+            if hashlib.sha256(helper.read_bytes()).hexdigest() != manifest['executable_sha256']:
+                raise BackgroundCaptureUnavailable('Windows Graphics Capture 辅助程序完整性校验失败')
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            raise BackgroundCaptureUnavailable(f'Windows Graphics Capture 辅助程序校验失败: {exc}') from exc
+        return helper
+
+    def screenshot_background(self):
+        """Capture an occluded window without changing the foreground window."""
+        self.validate_process()
+        if self.owner(self.hwnd) != self.game['pid']:
+            raise ValueError('游戏窗口归属已改变')
+        if not self.usable(self.hwnd) or self.user.IsIconic(self.hwnd):
+            raise BackgroundCaptureUnavailable('游戏窗口不可进行后台捕获')
+        width, height, _ = self._client_area(require_foreground=False, require_uncovered=False)
+        helper = self._background_helper()
+        flags = subprocess.CREATE_NO_WINDOW if os.name == 'nt' else 0
+        try:
+            completed = subprocess.run(
+                [str(helper), '--hwnd', str(int(self.hwnd))],
+                stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                timeout=5, creationflags=flags, check=False)
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise BackgroundCaptureUnavailable(f'后台捕获程序不可用: {exc}') from exc
+        if completed.returncode:
+            reason = completed.stderr.decode('utf-8', errors='replace').strip()
+            raise BackgroundCaptureUnavailable(reason or f'后台捕获程序退出码 {completed.returncode}')
+        header, separator, content = completed.stdout.partition(b'\n')
+        fields = header.decode('ascii', errors='replace').split()
+        if len(fields) != 4 or fields[0] != 'MCPYCAP1':
+            raise BackgroundCaptureUnavailable('后台捕获返回格式无效')
+        try:
+            captured_width, captured_height, content_size = map(int, fields[1:])
+        except ValueError as exc:
+            raise BackgroundCaptureUnavailable('后台捕获尺寸无效') from exc
+        if not separator or content_size != len(content) or content[:8] != b'\x89PNG\r\n\x1a\n':
+            raise BackgroundCaptureUnavailable('后台捕获没有返回有效 PNG')
+        if (captured_width, captured_height) != (width, height):
+            raise BackgroundCaptureUnavailable(
+                f'后台捕获尺寸 {captured_width}x{captured_height} 与客户区 {width}x{height} 不一致')
+        self.validate_process()
+        return content, captured_width, captured_height
+
+    def screenshot_with_fallback(self):
+        try:
+            content, width, height = self.screenshot_background()
+            return content, width, height, {
+                'capture': 'background-window', 'capture_fallback': False,
+            }
+        except BackgroundCaptureUnavailable as background_error:
+            try:
+                content, width, height = self.screenshot()
+            except Exception as visible_error:
+                raise ValueError(
+                    f'后台截图不可用: {background_error}; 前台回退失败: {visible_error}') from visible_error
+            return content, width, height, {
+                'capture': 'visible-client-area', 'capture_fallback': True,
+                'capture_fallback_reason': str(background_error),
+            }
+
     def mouse(self, action, *, x=None, y=None, width=None, height=None, to_x=None, to_y=None,
               dx=0, dy=0, delta=0, button='left', duration_ms=80, keys=()):
         if action not in ('move', 'click', 'double-click', 'scroll', 'drag', 'relative'):
@@ -520,8 +601,8 @@ def operate(project, session, action, parameters=None, cancel=None):
     window = GameWindow(session_game(project, session), cancel=cancel)
     try:
         if action == 'screenshot':
-            content, width, height = window.screenshot()
-            result = {'content': content, 'width': width, 'height': height, 'capture': 'visible-client-area'}
+            content, width, height, capture = window.screenshot_with_fallback()
+            result = {'content': content, 'width': width, 'height': height, **capture}
         elif action == 'key':
             result = window.press(parameters['keys'], parameters.get('hold_ms', 80))
         elif action == 'mouse':

mcpywrap-0.3.9/mcpywrap/mcstudio/window_capture/manifest.json

@@ -0,0 +1,4 @@
+{
+  "executable_sha256": "baface6b59f67379eb74fcbfe7803d5a1dfee1ac73ff7dbbb44e38e5c7c11853",
+  "source_sha256": "8f00a92f7a4418bfe59b5d1aea0547f1cb06aac8163b698932cabd1b1f829883"
+}

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/remote/client.py

@@ -1,4 +1,5 @@
 """CLI routing and standard-library transport. Never falls back or retries mutations."""
+import base64
 import json
 import os
 from http.client import HTTPException
@@ -66,8 +67,19 @@ class Client:
                 if not raw.startswith(b'\x89PNG\r\n\x1a\n') or len(raw) < 24:
                     raise RemoteError('远端未返回有效 PNG', 'invalid_response')
                 width, height = struct.unpack('>II', raw[16:24])
-                return {'content': raw, 'width': width, 'height': height,
-                        'service_instance': response.headers.get('X-Mcpy-Service-Instance')}
+                result = {'content': raw, 'width': width, 'height': height,
+                          'service_instance': response.headers.get('X-Mcpy-Service-Instance')}
+                capture = response.headers.get('X-Mcpy-Capture')
+                if capture:
+                    result['capture'] = capture
+                    result['capture_fallback'] = response.headers.get('X-Mcpy-Capture-Fallback') == 'true'
+                    reason = response.headers.get('X-Mcpy-Capture-Fallback-Reason-B64')
+                    if reason:
+                        try:
+                            result['capture_fallback_reason'] = base64.b64decode(reason, validate=True).decode('utf-8')
+                        except (ValueError, UnicodeError):
+                            raise RemoteError('远端截图状态无效', 'invalid_response') from None
+                return result
             try:
                 result = json.loads(raw.decode('utf-8-sig'))
             except (ValueError, UnicodeError):

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap/remote/http_server.py

@@ -1,4 +1,5 @@
 """Versioned, bounded HTTP interface; no file server, arbitrary paths, or shell endpoint."""
+import base64
 import hmac
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 import json
@@ -34,6 +35,12 @@ class Handler(BaseHTTPRequestHandler):
             self.send_header('Content-Type', 'image/png')
             for key in ('width', 'height', 'session', 'service_instance'):
                 self.send_header('X-Mcpy-' + key.replace('_', '-'), str(data[key]))
+            if 'capture' in data:
+                self.send_header('X-Mcpy-Capture', data['capture'])
+                self.send_header('X-Mcpy-Capture-Fallback', 'true' if data.get('capture_fallback') else 'false')
+                if data.get('capture_fallback_reason'):
+                    reason = base64.b64encode(data['capture_fallback_reason'].encode('utf-8')).decode('ascii')
+                    self.send_header('X-Mcpy-Capture-Fallback-Reason-B64', reason)
         else:
             content = json.dumps({'ok': status < 400, 'error': None, 'hint': None, **data},
                                  ensure_ascii=True, allow_nan=False).encode('utf-8')

{mcpywrap-0.3.8 → mcpywrap-0.3.9/mcpywrap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.8
+Version: 0.3.9
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -46,6 +46,8 @@ uv tool install mcpywrap
 
 也可以使用 `pip install mcpywrap`。安装完成后，运行 `mcpy --help` 查看命令。
 
+从 Windows 源码检出安装时，先安装 Visual Studio 的 x86/x64 C++ 构建工具，再运行 `python scripts/build_all_native.py` 一次编译全部原生组件，最后执行 `pip install -e .`。正式发布包由 CI 编译并附带原生组件，普通安装无需本机编译。
+
 ## 开始使用
 
 进入你的 Addon 或地图项目目录，按向导初始化：

{mcpywrap-0.3.8 → mcpywrap-0.3.9}/mcpywrap.egg-info/SOURCES.txt

@@ -90,6 +90,8 @@ mcpywrap/mcstudio/bridge_payload/Loader.dll
 mcpywrap/mcstudio/bridge_payload/McpyMcsAuth.dll
 mcpywrap/mcstudio/bridge_payload/manifest.json
 mcpywrap/mcstudio/bridge_payload/publisher.cer
+mcpywrap/mcstudio/window_capture/manifest.json
+mcpywrap/mcstudio/window_capture/mcpy-window-capture.exe
 mcpywrap/minecraft/__init__.py
 mcpywrap/minecraft/addons.py
 mcpywrap/minecraft/level_dat.py
@@ -113,8 +115,12 @@ native/mcs_auth/Injector.cs
 native/mcs_auth/Loader.c
 native/mcs_auth/publisher.cer
 native/mcs_auth/publisher.json
+native/window_capture/window_capture.cpp
+scripts/build_all_native.py
 scripts/build_mcs_auth_bridge.py
+scripts/build_window_capture.py
 scripts/check_mcs_auth_bridge.py
+scripts/check_window_capture.py
 skills/mcpywrap/SKILL.md
 skills/mcpywrap/agents/openai.yaml
 skills/mcpywrap/references/project-dependencies.md

mcpywrap-0.3.9/native/window_capture/window_capture.cpp

@@ -0,0 +1,282 @@
+#define WIN32_LEAN_AND_MEAN
+#define NOMINMAX
+
+#include <windows.h>
+#include <d3d11.h>
+#include <dxgi1_2.h>
+#include <dwmapi.h>
+#include <fcntl.h>
+#include <objidl.h>
+#include <io.h>
+#include <wincodec.h>
+#include <wrl/client.h>
+
+#include <winrt/base.h>
+#include <winrt/Windows.Graphics.Capture.h>
+#include <winrt/Windows.Graphics.DirectX.Direct3D11.h>
+#include <windows.graphics.capture.interop.h>
+#include <windows.graphics.directx.direct3d11.interop.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cstdint>
+#include <iostream>
+#include <limits>
+#include <string>
+#include <stdexcept>
+#include <vector>
+
+#pragma comment(lib, "d3d11.lib")
+#pragma comment(lib, "dxgi.lib")
+#pragma comment(lib, "dwmapi.lib")
+#pragma comment(lib, "ole32.lib")
+#pragma comment(lib, "windowscodecs.lib")
+#pragma comment(lib, "windowsapp.lib")
+
+using Microsoft::WRL::ComPtr;
+using namespace winrt;
+using namespace winrt::Windows::Graphics::Capture;
+using namespace winrt::Windows::Graphics::DirectX;
+using namespace winrt::Windows::Graphics::DirectX::Direct3D11;
+
+namespace {
+
+constexpr int kUnavailable = 2;
+
+struct Pixels {
+    uint32_t width = 0;
+    uint32_t height = 0;
+    std::vector<uint8_t> bgra;
+};
+
+[[noreturn]] void unavailable(const std::string& message) {
+    throw std::runtime_error(message);
+}
+
+void check_bool(BOOL value, const char* message) {
+    if (!value) {
+        unavailable(message);
+    }
+}
+
+HWND parse_hwnd(int argc, wchar_t** argv) {
+    for (int i = 1; i + 1 < argc; ++i) {
+        if (std::wstring(argv[i]) == L"--hwnd") {
+            try {
+                auto value = std::stoull(argv[i + 1]);
+                if (value == 0 || value > std::numeric_limits<uintptr_t>::max()) {
+                    unavailable("无效的窗口句柄");
+                }
+                return reinterpret_cast<HWND>(static_cast<uintptr_t>(value));
+            } catch (...) {
+                unavailable("无效的窗口句柄");
+            }
+        }
+    }
+    unavailable("缺少 --hwnd 参数");
+}
+
+RECT client_bounds(HWND hwnd) {
+    RECT client{};
+    POINT origin{0, 0};
+    check_bool(GetClientRect(hwnd, &client), "无法获取游戏客户区");
+    check_bool(ClientToScreen(hwnd, &origin), "无法获取游戏客户区坐标");
+    const LONG width = client.right - client.left;
+    const LONG height = client.bottom - client.top;
+    client.left = origin.x;
+    client.top = origin.y;
+    client.right = origin.x + width;
+    client.bottom = origin.y + height;
+    return client;
+}
+
+struct UnmapGuard {
+    ID3D11DeviceContext* context;
+    ID3D11Resource* resource;
+    ~UnmapGuard() { context->Unmap(resource, 0); }
+};
+
+Pixels read_frame(HWND hwnd, const Direct3D11CaptureFrame& frame,
+                  const ComPtr<ID3D11Device>& device,
+                  const ComPtr<ID3D11DeviceContext>& context) {
+    auto surface = frame.Surface();
+    auto access = surface.as<::Windows::Graphics::DirectX::Direct3D11::IDirect3DDxgiInterfaceAccess>();
+    ComPtr<ID3D11Texture2D> source;
+    check_hresult(access->GetInterface(IID_PPV_ARGS(&source)));
+
+    D3D11_TEXTURE2D_DESC source_desc{};
+    source->GetDesc(&source_desc);
+    if (source_desc.Width == 0 || source_desc.Height == 0 || source_desc.Width > 32000 || source_desc.Height > 32000) {
+        unavailable("后台捕获尺寸无效");
+    }
+
+    D3D11_TEXTURE2D_DESC staging_desc = source_desc;
+    staging_desc.Usage = D3D11_USAGE_STAGING;
+    staging_desc.BindFlags = 0;
+    staging_desc.CPUAccessFlags = D3D11_CPU_ACCESS_READ;
+    staging_desc.MiscFlags = 0;
+    ComPtr<ID3D11Texture2D> staging;
+    check_hresult(device->CreateTexture2D(&staging_desc, nullptr, &staging));
+    context->CopyResource(staging.Get(), source.Get());
+
+    D3D11_MAPPED_SUBRESOURCE mapped{};
+    check_hresult(context->Map(staging.Get(), 0, D3D11_MAP_READ, 0, &mapped));
+    UnmapGuard unmap{context.Get(), staging.Get()};
+
+    RECT client = client_bounds(hwnd);
+    RECT window{};
+    check_bool(GetWindowRect(hwnd, &window), "无法获取游戏窗口范围");
+    RECT extended = window;
+    DwmGetWindowAttribute(hwnd, DWMWA_EXTENDED_FRAME_BOUNDS, &extended, sizeof(extended));
+    const LONG crop_width = client.right - client.left;
+    const LONG crop_height = client.bottom - client.top;
+    LONG crop_left = -1;
+    LONG crop_top = -1;
+    for (const RECT& bounds : {window, extended}) {
+        const LONG candidate_left = client.left - bounds.left;
+        const LONG candidate_top = client.top - bounds.top;
+        if (candidate_left >= 0 && candidate_top >= 0 && crop_width > 0 && crop_height > 0 &&
+            candidate_left + crop_width <= static_cast<LONG>(source_desc.Width) &&
+            candidate_top + crop_height <= static_cast<LONG>(source_desc.Height)) {
+            crop_left = candidate_left;
+            crop_top = candidate_top;
+            break;
+        }
+    }
+    if (crop_left < 0 || crop_top < 0) {
+        unavailable("后台捕获窗口范围与客户区不一致");
+    }
+
+    Pixels result;
+    result.width = static_cast<uint32_t>(crop_width);
+    result.height = static_cast<uint32_t>(crop_height);
+    result.bgra.resize(static_cast<size_t>(result.width) * result.height * 4);
+    const auto* base = static_cast<const uint8_t*>(mapped.pData);
+    for (uint32_t row = 0; row < result.height; ++row) {
+        const auto* source_row = base + static_cast<size_t>(crop_top + row) * mapped.RowPitch +
+                                 static_cast<size_t>(crop_left) * 4;
+        auto* target_row = result.bgra.data() + static_cast<size_t>(row) * result.width * 4;
+        std::copy_n(source_row, static_cast<size_t>(result.width) * 4, target_row);
+    }
+    bool has_color = false;
+    for (size_t offset = 0; offset < result.bgra.size(); offset += 4) {
+        if (result.bgra[offset] || result.bgra[offset + 1] || result.bgra[offset + 2]) {
+            has_color = true;
+            break;
+        }
+    }
+    if (!has_color) {
+        unavailable("后台捕获返回全黑画面");
+    }
+    return result;
+}
+
+std::vector<uint8_t> encode_png(const Pixels& pixels) {
+    ComPtr<IWICImagingFactory> factory;
+    check_hresult(CoCreateInstance(CLSID_WICImagingFactory2, nullptr, CLSCTX_INPROC_SERVER,
+                                   IID_PPV_ARGS(&factory)));
+    ComPtr<IStream> stream;
+    check_hresult(CreateStreamOnHGlobal(nullptr, TRUE, &stream));
+    ComPtr<IWICBitmapEncoder> encoder;
+    check_hresult(factory->CreateEncoder(GUID_ContainerFormatPng, nullptr, &encoder));
+    check_hresult(encoder->Initialize(stream.Get(), WICBitmapEncoderNoCache));
+    ComPtr<IWICBitmapFrameEncode> frame;
+    ComPtr<IPropertyBag2> properties;
+    check_hresult(encoder->CreateNewFrame(&frame, &properties));
+    check_hresult(frame->Initialize(properties.Get()));
+    check_hresult(frame->SetSize(pixels.width, pixels.height));
+    WICPixelFormatGUID format = GUID_WICPixelFormat32bppBGRA;
+    check_hresult(frame->SetPixelFormat(&format));
+    check_hresult(frame->WritePixels(pixels.height, pixels.width * 4,
+                                     static_cast<UINT>(pixels.bgra.size()),
+                                     const_cast<BYTE*>(pixels.bgra.data())));
+    check_hresult(frame->Commit());
+    check_hresult(encoder->Commit());
+
+    HGLOBAL handle = nullptr;
+    check_hresult(GetHGlobalFromStream(stream.Get(), &handle));
+    STATSTG status{};
+    check_hresult(stream->Stat(&status, STATFLAG_NONAME));
+    const ULONGLONG stream_size = status.cbSize.QuadPart;
+    if (!stream_size || stream_size > std::numeric_limits<uint32_t>::max()) {
+        unavailable("PNG 输出尺寸无效");
+    }
+    const auto* data = static_cast<const uint8_t*>(GlobalLock(handle));
+    if (!data) {
+        unavailable("无法读取 PNG 输出");
+    }
+    std::vector<uint8_t> output(data, data + static_cast<size_t>(stream_size));
+    GlobalUnlock(handle);
+    return output;
+}
+
+Pixels capture(HWND hwnd) {
+    if (!IsWindow(hwnd) || !IsWindowVisible(hwnd) || IsIconic(hwnd)) {
+        unavailable("游戏窗口不可进行后台捕获");
+    }
+    DWORD cloaked = 0;
+    if (SUCCEEDED(DwmGetWindowAttribute(hwnd, DWMWA_CLOAKED, &cloaked, sizeof(cloaked))) && cloaked) {
+        unavailable("游戏窗口被系统隐藏");
+    }
+
+    ComPtr<ID3D11Device> device;
+    ComPtr<ID3D11DeviceContext> context;
+    D3D_FEATURE_LEVEL feature_level{};
+    const D3D_FEATURE_LEVEL levels[] = {D3D_FEATURE_LEVEL_11_1, D3D_FEATURE_LEVEL_11_0,
+                                        D3D_FEATURE_LEVEL_10_1, D3D_FEATURE_LEVEL_10_0};
+    check_hresult(D3D11CreateDevice(nullptr, D3D_DRIVER_TYPE_HARDWARE, nullptr,
+                                    D3D11_CREATE_DEVICE_BGRA_SUPPORT, levels,
+                                    ARRAYSIZE(levels), D3D11_SDK_VERSION, &device,
+                                    &feature_level, &context));
+    ComPtr<IDXGIDevice> dxgi_device;
+    check_hresult(device.As(&dxgi_device));
+    winrt::com_ptr<::IInspectable> inspectable;
+    check_hresult(CreateDirect3D11DeviceFromDXGIDevice(dxgi_device.Get(), inspectable.put()));
+    auto direct3d_device = inspectable.as<IDirect3DDevice>();
+
+    GraphicsCaptureItem item{nullptr};
+    auto interop = get_activation_factory<GraphicsCaptureItem, IGraphicsCaptureItemInterop>();
+    check_hresult(interop->CreateForWindow(hwnd, guid_of<GraphicsCaptureItem>(),
+                                            reinterpret_cast<void**>(put_abi(item))));
+    auto pool = Direct3D11CaptureFramePool::CreateFreeThreaded(
+        direct3d_device, DirectXPixelFormat::B8G8R8A8UIntNormalized, 1, item.Size());
+    auto session = pool.CreateCaptureSession(item);
+    session.IsCursorCaptureEnabled(false);
+    session.StartCapture();
+
+    Direct3D11CaptureFrame frame{nullptr};
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(3);
+    while (!frame && std::chrono::steady_clock::now() < deadline) {
+        frame = pool.TryGetNextFrame();
+        if (!frame) {
+            Sleep(20);
+        }
+    }
+    if (!frame) {
+        unavailable("后台捕获未返回画面");
+    }
+    return read_frame(hwnd, frame, device, context);
+}
+
+}  // namespace
+
+int wmain(int argc, wchar_t** argv) {
+    try {
+        init_apartment(apartment_type::multi_threaded);
+        SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
+        const HWND hwnd = parse_hwnd(argc, argv);
+        const Pixels pixels = capture(hwnd);
+        const auto png = encode_png(pixels);
+        _setmode(_fileno(stdout), _O_BINARY);
+        std::cout << "MCPYCAP1 " << pixels.width << ' ' << pixels.height << ' ' << png.size() << '\n';
+        std::cout.write(reinterpret_cast<const char*>(png.data()), static_cast<std::streamsize>(png.size()));
+        std::cout.flush();
+        return 0;
+    } catch (const winrt::hresult_error& error) {
+        std::wcerr << error.message().c_str();
+        return kUnavailable;
+    } catch (const std::exception& error) {
+        std::cerr << error.what();
+        return kUnavailable;
+    }
+}