mcpywrap 0.6.0__tar.gz → 0.6.2__tar.gz

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 更新记录
 
+## 0.6.2
+
+- 日志新增字面过滤与重复消息统计，明确扫描范围；支持结构化日志的 App 宿主另提供端侧和毫秒时间范围筛选。
+- 单会话重启明确交接旧、新 session；缓存信息显示年龄，Android 启动支持分阶段证据、后台尝试历史和独立的确认等待配置。
+
+- 标准 CLI 与同一份 skill 支持配对 Android 本机宿主；工程解析、构建和组装由 App 内核心执行，开发端按阶段完成工具准备，连接失败不回退本地构建。
+- 配对和准备结果支持中断恢复；最近操作保存最后观察到的状态，启动结果未知时可查询关联会话的新证据，不重放副作用。
+- 手机日志支持分源聚合，截图可自动保存到作品 captures 目录；补全库工具在开发端执行，版本目录支持离线缓存和有界联网刷新。
+- 两个发行包继续使用相同版本号，默认完整安装入口保持不变。
+
+## 0.6.1
+
+- 自动化启动默认保留后台窗口，不抢前台应用；提供 `--background` / `--foreground` 显式选择，重启和联调组保留策略。
+- 后台会话截图禁止回退前台，桌面键鼠入口明确拒绝；游戏内统一输入继续可用。
+- macOS 默认运行包升级到 0.4.6，支持后台窗口、全屏偏好隔离和光标保护；修复退出信号打断信号量等待时的错误码转换，避免 Python 锁状态异常。旧实例保留原运行包绑定。
+- 补齐 macOS CI 的后台策略测试，隔离 Windows 部署测试的平台选择，并提供可选的原生 ES2 回退验收。
+
 ## 0.6.0
 
 - 拆分为同版本的 `mcpywrap-core` 与完整 `mcpywrap`；默认 `pip install mcpywrap` / `uv tool install mcpywrap` 继续安装完整桌面依赖。

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/MANIFEST.in

@@ -3,7 +3,7 @@ include setup.py
 include core/mcpywrap_core/_version.py
 recursive-include desktop *.py *.exe *.dll *.cer *.json
 recursive-include scripts *.py *.ps1
-recursive-include native *.cs *.c *.cpp *.h *.cer *.json *.md *.patch
+recursive-include native *.cs *.c *.cpp *.h *.cer *.json *.md *.patch *.py
 recursive-include docs *.md
 recursive-include tests *.py *.md *.json
 recursive-include skills *.md *.yaml *.ps1 *.py *.toml *.json .gitignore

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.6.0
+Version: 0.6.2
 Summary: Complete mcpy desktop tools, powered by the shared mcpywrap-core
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -10,7 +10,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: mcpywrap-core==0.6.0
+Requires-Dist: mcpywrap-core==0.6.2
 Requires-Dist: pip>=23
 Requires-Dist: build>=1.0
 Requires-Dist: watchdog>=2.0.0
@@ -134,9 +134,19 @@ Git 项目使用 `[[tool.mcpywrap.git_dependencies]]` 声明，支持 Addon 与
 
 外部服务器连接、可选 MCS 身份与进服判断见 [网络会话](skills/mcpywrap/references/network-sessions.md)。需要另一台 Windows 执行游戏时，再按 [远程执行端](skills/mcpywrap/references/remote-testing.md) 配置服务。远程连接不部署本地 Mod，也不提供世界实例管理。
 
+## Android 本机宿主
+
+仅在手机上使用外部开发工具时，按[本机 App 接入](skills/mcpywrap/references/application-host.md)完成配对。绑定工作区使用标准命令，由 App 核心执行工程操作；离线时不回退本地构建。普通 Windows/macOS 项目继续使用原本的桌面流程，无需安装手机应用或配置手机权限。
+
 ## AI Agent 使用
 
-安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。
+安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。0.6.2 起也可从已安装的发行包导出完整同版本 Skill：
+
+```bash
+mcpy skill install --directory <Agent技能目录>/mcpywrap
+```
+
+更新已有技能目录加 `--replace`。只维护这份标准 Skill，按任务加载平台参考。
 
 Skill 按当前任务选择参考，不要求 AI 通读产品文档。可直接描述：
 

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/README.md

@@ -109,9 +109,19 @@ Git 项目使用 `[[tool.mcpywrap.git_dependencies]]` 声明，支持 Addon 与
 
 外部服务器连接、可选 MCS 身份与进服判断见 [网络会话](skills/mcpywrap/references/network-sessions.md)。需要另一台 Windows 执行游戏时，再按 [远程执行端](skills/mcpywrap/references/remote-testing.md) 配置服务。远程连接不部署本地 Mod，也不提供世界实例管理。
 
+## Android 本机宿主
+
+仅在手机上使用外部开发工具时，按[本机 App 接入](skills/mcpywrap/references/application-host.md)完成配对。绑定工作区使用标准命令，由 App 核心执行工程操作；离线时不回退本地构建。普通 Windows/macOS 项目继续使用原本的桌面流程，无需安装手机应用或配置手机权限。
+
 ## AI Agent 使用
 
-安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。
+安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。0.6.2 起也可从已安装的发行包导出完整同版本 Skill：
+
+```bash
+mcpy skill install --directory <Agent技能目录>/mcpywrap
+```
+
+更新已有技能目录加 `--replace`。只维护这份标准 Skill，按任务加载平台参考。
 
 Skill 按当前任务选择参考，不要求 AI 通读产品文档。可直接描述：
 

mcpywrap-0.6.2/core/mcpywrap_core/_version.py

@@ -0,0 +1 @@
+__version__ = '0.6.2'

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/desktop/mcpywrap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.6.0
+Version: 0.6.2
 Summary: Complete mcpy desktop tools, powered by the shared mcpywrap-core
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -10,7 +10,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: mcpywrap-core==0.6.0
+Requires-Dist: mcpywrap-core==0.6.2
 Requires-Dist: pip>=23
 Requires-Dist: build>=1.0
 Requires-Dist: watchdog>=2.0.0
@@ -134,9 +134,19 @@ Git 项目使用 `[[tool.mcpywrap.git_dependencies]]` 声明，支持 Addon 与
 
 外部服务器连接、可选 MCS 身份与进服判断见 [网络会话](skills/mcpywrap/references/network-sessions.md)。需要另一台 Windows 执行游戏时，再按 [远程执行端](skills/mcpywrap/references/remote-testing.md) 配置服务。远程连接不部署本地 Mod，也不提供世界实例管理。
 
+## Android 本机宿主
+
+仅在手机上使用外部开发工具时，按[本机 App 接入](skills/mcpywrap/references/application-host.md)完成配对。绑定工作区使用标准命令，由 App 核心执行工程操作；离线时不回退本地构建。普通 Windows/macOS 项目继续使用原本的桌面流程，无需安装手机应用或配置手机权限。
+
 ## AI Agent 使用
 
-安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。
+安装仓库内完整的 [mcpywrap Skill](skills/mcpywrap/SKILL.md)。可让 Agent 安装 `EaseCation/mcpywrap` 的 `skills/mcpywrap` 目录，或将整个文件夹复制到其技能目录。CLI 与 Skill 分别安装，安装 Python 包不会自动注册 Skill。0.6.2 起也可从已安装的发行包导出完整同版本 Skill：
+
+```bash
+mcpy skill install --directory <Agent技能目录>/mcpywrap
+```
+
+更新已有技能目录加 `--replace`。只维护这份标准 Skill，按任务加载平台参考。
 
 Skill 按当前任务选择参考，不要求 AI 通读产品文档。可直接描述：
 

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/desktop/mcpywrap.egg-info/SOURCES.txt

@@ -20,6 +20,8 @@ desktop/mcpywrap_assets/bridge_payload/Loader.dll
 desktop/mcpywrap_assets/bridge_payload/McpyMcsAuth.dll
 desktop/mcpywrap_assets/bridge_payload/manifest.json
 desktop/mcpywrap_assets/bridge_payload/publisher.cer
+desktop/mcpywrap_assets/window_activation/manifest.json
+desktop/mcpywrap_assets/window_activation/mcpy-window-activation.dll
 desktop/mcpywrap_assets/window_capture/manifest.json
 desktop/mcpywrap_assets/window_capture/mcpy-window-capture.exe
 docs/code-libraries.md
@@ -43,6 +45,13 @@ docs/runtime-ui.md
 docs/shared-core.md
 docs/shared-log-ui.md
 examples/consumer_prepare/README.md
+native/background_window/README.md
+native/background_window/apply.py
+native/background_window/client-background.patch
+native/background_window/game-window-background.patch
+native/background_window/libc-shim-background.patch
+native/background_window/manifest-background.patch
+native/background_window/test_window.cpp
 native/mcs_auth/Bridge.cs
 native/mcs_auth/Injector.cs
 native/mcs_auth/Loader.c
@@ -52,15 +61,19 @@ native/runtime_input/README.md
 native/runtime_input/launcher-monotonic.patch
 native/runtime_input/manifest-monotonic.patch
 native/runtime_input/steady_clock.h
+native/window_activation/README.md
+native/window_activation/window_activation.cpp
 native/window_capture/video_capture.h
 native/window_capture/window_capture.cpp
 scripts/build_all_native.py
 scripts/build_app_icon.py
 scripts/build_distributions.py
 scripts/build_mcs_auth_bridge.py
+scripts/build_window_activation.py
 scripts/build_window_capture.py
 scripts/check_mcs_auth_bridge.py
 scripts/check_release.py
+scripts/check_window_activation.py
 scripts/check_window_capture.py
 scripts/pypi_release.py
 scripts/sign_mcs_auth_ci.ps1
@@ -80,6 +93,7 @@ skills/mcpywrap/assets/consumer-prepare/game/pyproject.toml
 skills/mcpywrap/assets/consumer-prepare/game/behavior_pack/manifest.json
 skills/mcpywrap/assets/consumer-prepare/game/data/items.json
 skills/mcpywrap/assets/consumer-prepare/game/resource_pack/manifest.json
+skills/mcpywrap/references/application-host.md
 skills/mcpywrap/references/capture.md
 skills/mcpywrap/references/consumer-prepare-author.md
 skills/mcpywrap/references/consumer-prepare.md
@@ -109,6 +123,7 @@ skills/mcpywrap/scripts/smoke.py
 tests/README.md
 tests/core_fixture.py
 tests/embedded_upgrade_probe.py
+tests/manual_background_launch.py
 tests/manual_dependency_boundaries.py
 tests/manual_input_window.py
 tests/manual_integration.py
@@ -138,6 +153,7 @@ tests/test_engine_backends.py
 tests/test_engine_compatibility.py
 tests/test_engine_discovery.py
 tests/test_engine_install.py
+tests/test_execution_boundaries.py
 tests/test_game_window_skill.py
 tests/test_git_projects.py
 tests/test_host_input.py
@@ -151,10 +167,14 @@ tests/test_lifecycle_races.py
 tests/test_local_auth_session.py
 tests/test_local_dependencies.py
 tests/test_lock_storage.py
+tests/test_log_query.py
 tests/test_log_stream.py
 tests/test_macos_network.py
 tests/test_manual_runtime_controls.py
 tests/test_mcs_auth.py
+tests/test_mobile_diagnostics.py
+tests/test_mobile_host.py
+tests/test_mobile_pairing.py
 tests/test_modsdk_environment.py
 tests/test_mouse.py
 tests/test_native_input_sequence.py
@@ -171,6 +191,7 @@ tests/test_recordings.py
 tests/test_remote.py
 tests/test_remote_scripts.py
 tests/test_resource_reload.py
+tests/test_restricted_process_identity.py
 tests/test_runtime_debug.py
 tests/test_runtime_deployment.py
 tests/test_runtime_groups.py
@@ -185,7 +206,9 @@ tests/test_session_capabilities.py
 tests/test_shared_logs.py
 tests/test_skill_workflows.py
 tests/test_unified_skill_contract.py
+tests/test_window_activation.py
 tests/test_window_focus.py
+tests/test_window_policy.py
 tests/manual/consumer_prepare_acceptance.py
 tests/manual/lifecycle_dependency_audit.py
 tests/manual/runtime_controls/README.md

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/desktop/mcpywrap.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mcpywrap-core==0.6.0
+mcpywrap-core==0.6.2
 pip>=23
 build>=1.0
 watchdog>=2.0.0

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/desktop/mcpywrap_assets/bridge_payload/manifest.json

@@ -11,9 +11,9 @@
     "Loader.c": "f2f1f781ce82fc30c62a6ce22bb048d3b023f6ff500e6ec8228da28b4dbf1b4a"
   },
   "files": {
-    "Injector.exe": "ba3caeae28560fcf49c89a1e5562d7e9f4d5a9ac66639abca7dda0cc51462706",
-    "Loader.dll": "abc1715947c505ffb7df7e63f62603156180961a2a86320b2b8c580bd4d65ac2",
-    "McpyMcsAuth.dll": "42af0e2376e6f0a8c2e4829793cf3ce73e751cd0e0a6302ed069efb161599151",
+    "Injector.exe": "05806de2bd8143d690f4136451dd495b892d47036481b5af170576edeacd1d60",
+    "Loader.dll": "7f45d503eb7f06bf535bb564cda2d3b8dc7c38118d4433f514ca57fe94040cce",
+    "McpyMcsAuth.dll": "d7bf8957a2bdcac92bbef80ff0ef5709ffdebfb9ece237a65caf8e244483acce",
     "publisher.cer": "e5aa2ac39df40804ed8b08fe8e43c4a2b8923f0d02a360708486b2db5b6303d7"
   }
 }

mcpywrap-0.6.2/desktop/mcpywrap_assets/window_activation/manifest.json

@@ -0,0 +1,6 @@
+{
+  "background_window_protocol": 1,
+  "architecture": "x64",
+  "dll_sha256": "e05ff1d30f809621dd104d87a63f26d7c725864a43c0989d9035ed2647879cb4",
+  "source_sha256": "03c1aab9e8d46c162e11f9448903c4907fbe3b87d1e77d8118b72c3e6b250ec5"
+}

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/desktop/mcpywrap_assets/window_capture/manifest.json

@@ -1,5 +1,5 @@
 {
-  "executable_sha256": "1d2721067ad63c12787b5d3a5ff7461decb72f1a250496bafc65e4fad5802e64",
+  "executable_sha256": "74a0ecfbcb266a0e6689ac8c981058cbd59382e9adf7a92aae832836e10e1b3b",
   "source_sha256": "0c0b2a02bfecea68b824a486ac1d88cde6bd9fc8ee8e4c9a6939870bd8e710d1",
   "sources": {
     "video_capture.h": "f766d4234e41a554a8eb8ecae93fd818c2fb8877fbd1795f3915dcc8771e7909",

{mcpywrap-0.6.0 → mcpywrap-0.6.2}/docs/game-backends.md

@@ -36,7 +36,9 @@ Windows 联调成员的生命周期记录、角色归属及占用锁仍位于项
 首次迁移在角色占用锁内复制旧 AppData 到临时目录，完成归属标记后原子改名，原副本保留。后续启动复用新位置；目标缺失、归属不符或遗留未完成迁移时停止，不回退到旧身份。旧资料的长路径用宿主扩展路径形式复制，传给游戏的仍是标准短路径。需要项目所在磁盘根目录允许创建 `mcpy-profiles`；不支持 UNC 或被替换为目录链接的位置，不自动提权。用户搬迁项目时需保留组记录及其指向的 profile，不能只把外部目录当缓存删除。
 
 
-Windows/macOS 共同基线是 `--local --project <目录> --non-interactive run --no-gui --detach --json`，后续统一 status/logs/runtime py/runtime reload/stop。控制端不打开 Qt、小窗或 TUI，游戏本身仍需要显示服务及原生窗口。完整操作顺序维护在 [技能的公共流程](../skills/mcpywrap/references/local-development.md)。
+Windows/macOS 共同基线是 `--local --project <目录> --non-interactive run --no-gui --detach --json`，后续统一 status/logs/runtime py/runtime reload/stop。非交互、JSON、no-gui 或 detach 默认请求后台窗口，`--background / --foreground` 可覆盖；普通交互式 run 和 Qt 默认保留前台聚焦。策略写入会话并随双客户端、重启和部署重试传递，复用已有会话不改变其策略。
+
+Windows 后台启动使用独立桌面包提供的进程内线程级 CBT 保护及非激活启动参数；保护范围与构建见 [窗口保护](../native/window_activation/README.md)。macOS 通过运行包 helper 的 `--background` 传到 GLFW，要求 `background_window_protocol=1`，旧包在创建实例/进程前拒绝；配套源码见 [原生补丁](../native/background_window/README.md)。后台会话强制后台截图并拒绝会激活窗口的桌面键鼠输入。游戏仍需显示服务及原生窗口，完整用法维护在 [技能公共流程](../skills/mcpywrap/references/local-development.md)。
 
 `runtime capabilities --session <id> --json` 返回 schema_version=1：control 描述控制端要求，python 提供执行端侧与 worker 队列声明，reload 按同一后端限制返回 available/unsupported/unavailable。查询不执行游戏代码、不返回控制凭据，available 只说明允许调用。旧 worker 缺少队列声明时返回 null，不能推断支持。Windows 已知 Shader 限制也由 WindowsBackend 提供，实际重载与查询没有两份规则。
 

mcpywrap-0.6.2/native/background_window/README.md

@@ -0,0 +1,65 @@
+# macOS 后台窗口运行包
+
+CLI 的后台窗口接口需要运行包 `background_window_protocol=1`。旧包返回 `background_window_unavailable`；允许占用前台时可显式 `--foreground`。这些补丁针对源码构建，不修改已签名应用或旧实例绑定。
+
+## 补丁与基线
+
+- `game-window-background.patch`：在初次创建及 ES2 回退的 hints 重置后关闭 `GLFW_FOCUSED` / `GLFW_FOCUS_ON_SHOW`，后台时禁止全屏和光标锁定、隐藏、重定位。
+- `client-background.patch`：跳过后台会话的全屏偏好和请求，保留用户偏好。
+- `manifest-background.patch`：helper 接受 `--background`，显式传入 `MCPY_GAME_BACKGROUND=1/0`，普通运行不继承遗留环境开关；构建检查补丁后声明协议。
+- `libc-shim-background.patch`：信号打断 Mach 信号量等待时转换为 `-1/EINTR`，避免退出信号破坏 Python 锁处理；manifest 补丁包含原生回归测试。
+- `apply.py`：四份补丁全部预检后才应用，已应用项可跳过；不下载、构建或启动游戏。
+
+核对基线：manifest `8b624579618a121c345dd4ff05748d426a0141fa`，client `350eb36f499fbb4bc2bcaf413bd7b2fefa1fb782`，game-window `d073c2aace1521ae32d239ca4fc26b97e4b4a27e`，libc-shim `8ca149814eba0c42fa0c1f945b76fb526f6f0694`。
+
+## 在 Mac 构建测试包
+
+在 Apple Silicon Mac 按 manifest 的说明准备 Xcode Command Line Tools、Python、CMake、Ninja 等依赖。可使用已有初始化的开发 checkout；首次准备使用核对基线：
+
+```sh
+git clone https://github.com/EaseCation/mcpelauncher-manifest.git /path/to/runtime-source
+git -C /path/to/runtime-source checkout 8b624579618a121c345dd4ff05748d426a0141fa
+git -C /path/to/runtime-source submodule update --init --recursive
+python3 native/background_window/apply.py --manifest /path/to/runtime-source
+```
+
+选择尚不存在的应用和发行输出目录；APK 应与构建使用的 profile 匹配：
+
+```sh
+python3 /path/to/runtime-source/tools/build_macos_runtime.py \
+  --output /path/to/background-build/McpyRuntime.app \
+  --work-dir /path/to/background-build/portable \
+  --build-dir /path/to/background-build/client
+python3 /path/to/runtime-source/tools/package_macos_release.py \
+  --runtime /path/to/background-build/McpyRuntime.app \
+  --version 0.6.0-background.1 --output /path/to/background-release
+mcpy --local --non-interactive engine install \
+  --catalog /path/to/background-release/catalog.json --apk /path/to/developer.apk --json
+```
+
+mcpywrap 开发 checkout 同时安装 `./core` 与完整包：在开发虚拟环境执行 `python -m pip install -e ./core -e .`。安装新运行包后使用独立项目 `run --new`，旧实例不会自动换包。
+
+## Mac 验收
+
+1. 保持其他应用前台，执行标准 AI 命令 `mcpy --local --project <独立项目> --non-interactive run --new --no-gui --detach --json`。应返回 `background=true`；到 HUD 期间不切应用、不切 Space、不锁定光标。
+2. `status` 确认 `world_ready`，`screenshot --session <sid> --output <新PNG> --json` 应获得新帧。后台会话禁止截图回退前台。
+3. `runtime install` 后用统一输入的默认 `game` 后端验证游戏内动作和效果，覆盖遮挡、菜单及取消释放。`restart --session <sid> --json` 应产生新 session 并保留后台策略。
+4. 停止自己的会话，再从交互终端执行普通 `mcpy run`，确认正常聚焦；显式 `run --foreground --no-gui --detach --json` 应返回 `background=false`。
+5. 覆盖之前已开启全屏的偏好、光标锁定请求及 ES3→ES2 回退；后台退出后原有全屏偏好保持。
+
+此模式保留可见窗口和 GPU 渲染，不承诺隐藏、最小化或锁屏后继续产生帧。公开启动用法见 [本地会话](../../skills/mcpywrap/references/local-development.md)。
+
+### 可选原生回退测试
+
+`test_window.cpp` 只用于交互式 Mac 桌面验收，不接入默认测试或游戏启动。它编译实际的 `window_glfw.cpp`，仅让第一次窗口创建返回失败，然后使用真实 GLFW/ANGLE 创建 ES2 窗口，断言回退后不聚焦、光标锁定请求被抑制、全屏请求被抑制。保持其他应用前台，并同时观察应用激活和 Space 事件；窗口属性断言本身不能证明没有短暂抢焦点。
+
+在已完成上述构建的终端中设置 `source` 为 manifest 目录、`build` 为该次 CMake 构建目录、`runtime` 为新应用路径：
+
+```sh
+c++ -std=c++17 -I "$source/game-window/src" -I "$source/game-window/include" \
+  -I "$build/_deps/glfw3_ext-src/include" native/background_window/test_window.cpp \
+  "$build/game-window/libgamewindow.a" "$build/_deps/glfw3_ext-build/src/libglfw3.a" \
+  -framework Cocoa -framework OpenGL -framework IOKit -framework QuartzCore \
+  -o /tmp/mcpy-background-window-test
+DYLD_LIBRARY_PATH="$runtime/Contents/Frameworks" /tmp/mcpy-background-window-test
+```

mcpywrap-0.6.2/native/background_window/apply.py

@@ -0,0 +1,41 @@
+"""Apply background-window and safe-stop patches to an initialized runtime source tree."""
+import argparse
+from pathlib import Path
+import subprocess
+
+
+def apply(manifest):
+    root = Path(manifest).resolve(strict=True)
+    patches = Path(__file__).resolve().parent
+    targets = [(root/'game-window', patches/'game-window-background.patch'),
+               (root/'mcpelauncher-client', patches/'client-background.patch'),
+               (root/'libc-shim', patches/'libc-shim-background.patch'),
+               (root, patches/'manifest-background.patch')]
+    pending = []
+    for repo, patch in targets:
+        if not (repo/'.git').exists():
+            raise RuntimeError('Initialize the Git checkout/submodule first: ' + str(repo))
+        command = ['git', '-C', str(repo), 'apply']
+        if subprocess.run(command + ['--reverse', '--check', str(patch)], capture_output=True).returncode == 0:
+            continue
+        result = subprocess.run(command + ['--check', str(patch)], capture_output=True, text=True)
+        if result.returncode:
+            raise RuntimeError('Patch preflight failed: ' + str(patch) + '\n' + result.stderr)
+        pending.append((command, patch))
+    applied = []
+    try:
+        for command, patch in pending:
+            subprocess.run(command + [str(patch)], check=True)
+            applied.append((command, patch))
+    except BaseException:
+        for command, patch in reversed(applied):
+            subprocess.run(command + ['--reverse', str(patch)], check=True)
+        raise
+    return len(applied)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--manifest', required=True, type=Path)
+    args = parser.parse_args()
+    print('Applied', apply(args.manifest), 'patches; build a new runtime before testing.')

mcpywrap-0.6.2/native/background_window/client-background.patch

@@ -0,0 +1,35 @@
+diff --git a/src/window_callbacks.cpp b/src/window_callbacks.cpp
+index 6721d73..c60015c 100644
+--- a/src/window_callbacks.cpp
++++ b/src/window_callbacks.cpp
+@@ -11,6 +11,13 @@
+ #include <string>
+ #include "settings.h"
+ #include "util.h"
++
++namespace {
++bool backgroundWindow() {
++    const char* value = std::getenv("MCPY_GAME_BACKGROUND");
++    return value && std::string(value) == "1";
++}
++}
+ #ifdef USE_IMGUI
+ #include "imgui_ui.h"
+ #endif
+@@ -18,7 +25,7 @@
+ WindowCallbacks::WindowCallbacks(GameWindow& window, JniSupport& jniSupport, FakeInputQueue& inputQueue) : window(window), jniSupport(jniSupport), inputQueue(inputQueue) {
+     useDirectMouseInput = Mouse::feed;
+     useDirectKeyboardInput = (Keyboard::_states && (Keyboard::_inputs || Keyboard::_inputsLegacy) && Keyboard::_gameControllerId);
+-    if(Settings::fullscreen) {
++    if(Settings::fullscreen && !backgroundWindow()) {
+         window.setFullscreen(true);
+     }
+     useRawInput = ReadEnvFlag("MCPELAUNCHER_CLIENT_RAW_INPUT");
+@@ -89,6 +96,7 @@ void WindowCallbacks::onClose() {
+ }
+
+ void WindowCallbacks::setFullscreen(bool isFs) {
++    if (backgroundWindow()) return;
+     if(Settings::fullscreen != isFs) {
+         window.setFullscreen(isFs);
+         Settings::fullscreen = isFs;

mcpywrap-0.6.2/native/background_window/game-window-background.patch

@@ -0,0 +1,58 @@
+diff --git a/src/window_glfw.cpp b/src/window_glfw.cpp
+index 7e0a85b..ca8e524 100644
+--- a/src/window_glfw.cpp
++++ b/src/window_glfw.cpp
+@@ -8,12 +8,27 @@
+ #include <sstream>
+
+ #include <math.h>
++#include <cstdlib>
++#include <cstring>
++
++namespace {
++bool backgroundWindow() {
++    const char* value = std::getenv("MCPY_GAME_BACKGROUND");
++    return value && std::strcmp(value, "1") == 0;
++}
++void backgroundWindowHints() {
++    if (!backgroundWindow()) return;
++    glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
++    glfwWindowHint(GLFW_FOCUS_ON_SHOW, GLFW_FALSE);
++}
++}
+
+ GLFWGameWindow::GLFWGameWindow(const std::string& title, int width, int height, GraphicsApi api) : GameWindow(title, width, height, api), width(width), height(height), windowedWidth(width), windowedHeight(height) {
+ #ifdef GAMEWINDOW_X11_LOCK
+     std::lock_guard<std::recursive_mutex> lock(x11_sync);
+ #endif
+     glfwDefaultWindowHints();
++    backgroundWindowHints();
+     if(api == GraphicsApi::OPENGL_ES2) {
+         glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);
+         glfwWindowHint(GLFW_CONTEXT_CREATION_API, GLFW_EGL_CONTEXT_API);
+@@ -29,6 +44,7 @@ GLFWGameWindow::GLFWGameWindow(const std::string& title, int width, int height,
+     if(window == nullptr && api == GraphicsApi::OPENGL_ES2) {
+         // Failed to get es3 request es2
+         glfwDefaultWindowHints();
++        backgroundWindowHints();
+         glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);
+         glfwWindowHint(GLFW_CONTEXT_CREATION_API, GLFW_EGL_CONTEXT_API);
+         glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 2);
+@@ -172,6 +188,8 @@ bool GLFWGameWindow::getCursorDisabled() {
+ }
+
+ void GLFWGameWindow::setCursorDisabled(bool disabled) {
++    // A background test must never grab, hide or recenter the user's cursor.
++    if (backgroundWindow()) disabled = false;
+ #ifdef GAMEWINDOW_X11_LOCK
+     std::lock_guard<std::recursive_mutex> lock(x11_sync);
+ #endif
+@@ -199,7 +217,7 @@ void GLFWGameWindow::setFullscreen(bool fullscreen) {
+ #ifdef GAMEWINDOW_X11_LOCK
+     std::lock_guard<std::recursive_mutex> lock(x11_sync);
+ #endif
+-    requestFullscreen = fullscreen;
++    requestFullscreen = fullscreen && !backgroundWindow();
+ }
+
+ void GLFWGameWindow::setClipboardText(std::string const& text) {

mcpywrap-0.6.2/native/background_window/libc-shim-background.patch

@@ -0,0 +1,25 @@
+diff --git a/src/semaphore.cpp b/src/semaphore.cpp
+index 1388f93..4adad85 100644
+--- a/src/semaphore.cpp
++++ b/src/semaphore.cpp
+@@ -56,7 +56,12 @@ int shim::sem_destroy(host_sem_t *sem) {
+ }
+ 
+ int shim::sem_wait(host_sem_t *sem) {
+-    return semaphore_wait(*sem);
++    auto result = semaphore_wait(*sem);
++    if(result == KERN_SUCCESS) return 0;
++    // POSIX 调用方不能接收 Mach 错误码，否则会误用未持有的锁。
++    errno = result == KERN_ABORTED ? EINTR : EINVAL;
++    bionic::update_errno();
++    return -1;
+ }
+ 
+ int shim::sem_trywait(host_sem_t *sem) {
+@@ -113,4 +118,4 @@ void shim::add_sem_shimmed_symbols(std::vector<shim::shimmed_symbol> &list) {
+         {"sem_timedwait", &detail::arg_rewrite_helper<int (::sem_t *, const struct timespec *)>::rewrite<sem_timedwait>},
+         {"sem_post", &detail::arg_rewrite_helper<int (::sem_t *)>::rewrite<sem_post>},
+     });
+-}
+
++}

mcpywrap-0.6.2/native/background_window/manifest-background.patch

@@ -0,0 +1,112 @@
+diff --git a/tests/libc_compat_smoke.cpp b/tests/libc_compat_smoke.cpp
+index 2ea481f..83cc704 100644
+--- a/tests/libc_compat_smoke.cpp
++++ b/tests/libc_compat_smoke.cpp
+@@ -12,6 +12,11 @@
+ #include <sys/socket.h>
+ #include <sys/mman.h>
+ #include <unistd.h>
++#include <atomic>
++#include <chrono>
++#include <csignal>
++#include <thread>
++#include <pthread.h>
+
+ int main() {
+     std::unordered_map<std::string, void*> symbols;
+@@ -38,6 +43,29 @@ int main() {
+     assert(post(sem) == 0);
+     assert(wait(sem) == 0);
+     assert(wait(sem) == -1 && *error() == 11);
++#ifdef __APPLE__
++    // 信号打断 Mach 等待时，Android 调用方必须收到 -1/EINTR。
++    struct sigaction action{}, previous{};
++    action.sa_handler = +[](int) {};
++    sigemptyset(&action.sa_mask);
++    assert(sigaction(SIGUSR1, &action, &previous) == 0);
++    auto blockingWait = reinterpret_cast<int(*)(void*)>(symbols.at("sem_wait"));
++    auto waitingThread = pthread_self();
++    std::atomic<bool> finished{false};
++    std::thread interrupter([&] {
++        for(int i = 0; i < 100 && !finished; ++i) {
++            std::this_thread::sleep_for(std::chrono::milliseconds(10));
++            pthread_kill(waitingThread, SIGUSR1);
++        }
++        if(!finished) post(sem);
++    });
++    int interrupted = blockingWait(sem);
++    int interruptedError = *error();
++    finished = true;
++    interrupter.join();
++    assert(sigaction(SIGUSR1, &previous, nullptr) == 0);
++    assert(interrupted == -1 && interruptedError == 4);
++#endif
+     assert(destroy(sem) == 0);
+     auto androidFcntl = reinterpret_cast<int(*)(int, int, void*)>(symbols.at("fcntl"));
+     int sockets[2];
+diff --git a/tools/build_macos_runtime.py b/tools/build_macos_runtime.py
+index 9b25aba..2c80ab2 100644
+--- a/tools/build_macos_runtime.py
++++ b/tools/build_macos_runtime.py
+@@ -127,6 +127,10 @@ def main():
+             run(['make', '-j' + str(args.jobs)], cwd=source, env=env, stdout=log, stderr=subprocess.STDOUT)
+             run(['make', 'install_sw'], cwd=source, env=env, stdout=log, stderr=subprocess.STDOUT)
+         stamp.write_text(json.dumps(recipe, indent=2) + '\n')
++    # Advertise this protocol only when every native implementation is present.
++    for source in ('game-window/src/window_glfw.cpp', 'mcpelauncher-client/src/window_callbacks.cpp'):
++        if 'MCPY_GAME_BACKGROUND' not in (ROOT / source).read_text():
++            raise RuntimeError('Missing background-window source patch: ' + source)
+     build = args.build_dir.resolve() if args.build_dir else work / 'client'
+     config = ['cmake', '-S', ROOT, '-B', build, '-G', 'Ninja', '-DCMAKE_BUILD_TYPE=RelWithDebInfo',
+         '-DCMAKE_POLICY_VERSION_MINIMUM=3.5',
+@@ -198,7 +202,7 @@ def main():
+         'LSMinimumSystemVersion': args.minimum_macos, 'NSHighResolutionCapable': True}))
+     metadata = {'schema': 1, 'platform': 'darwin-arm64', 'minimum_macos': args.minimum_macos,
+         'client_python_protocol': 1, 'json_ui_reload_protocol': 1, 'input_monotonic_clock_protocol': 1,
+-        'screenshot_protocol': 1,
++        'screenshot_protocol': 1, 'background_window_protocol': 1,
+         'launch_protocol': 1, 'addon_link_protocol': 1, 'cppconfig_protocol': 1, 'network_connect_protocol': 1,
+         'game_compatibility': {'elf_rules_schema': 1, 'package_name': 'com.netease.mctest', 'abi': 'arm64-v8a',
+                                'rules_sha256': digest(ROOT/'tools/developer_binary_rules.json')}, 'game_profile': json.loads(args.profile.read_text()),
+diff --git a/tools/run_netease_dev.py b/tools/run_netease_dev.py
+index 85c9d2a..46beff2 100644
+--- a/tools/run_netease_dev.py
++++ b/tools/run_netease_dev.py
+@@ -219,9 +219,9 @@ def prepare(args):
+     return game, data, cache, client, angle, commands
+
+
+-def launch_command(game, data, cache, client, angle, commands, session=None, debug_loopback=False, angle_backend=None, server_target=None):
++def launch_command(game, data, cache, client, angle, commands, session=None, debug_loopback=False, angle_backend=None, server_target=None, background=False):
+     policy = network_policy(*server_target) if server_target else (DEBUG_POLICY if debug_loopback else POLICY)
+-    command = ([] if session else ['/usr/bin/sandbox-exec', '-p', policy]) + ['/usr/bin/env', 'DYLD_LIBRARY_PATH='+str(angle)]
++    command = ([] if session else ['/usr/bin/sandbox-exec', '-p', policy]) + ['/usr/bin/env', 'MCPY_GAME_BACKGROUND=' + ('1' if background else '0'), 'DYLD_LIBRARY_PATH='+str(angle)]
+     if angle_backend:
+         command += ['ANGLE_DEFAULT_PLATFORM='+angle_backend]
+     command += [str(client), '--netease-dev', '--force-opengles', '--game-dir', str(game),
+@@ -259,6 +259,7 @@ def main():
+     parser.add_argument('--prepare-only', action='store_true')
+     parser.add_argument('--run-seconds', type=int, help='Bounded smoke run; stops after this time, not a save/quit test')
+     parser.add_argument('--log', type=Path)
++    parser.add_argument('--background', action='store_true', help='Show the game without activating it or grabbing the cursor')
+     parser.add_argument('--exec-client', action='store_true', help=argparse.SUPPRESS)
+     args = parser.parse_args()
+     args.client = args.client or args.runtime/'Contents/MacOS/mcpelauncher-client'
+@@ -297,7 +298,7 @@ def main():
+         parser.error(str(error))
+     log = args.log.resolve()
+     log.parent.mkdir(parents=True, exist_ok=True)
+-    command = launch_command(game, data, cache, client, angle, commands, args.session_file.resolve() if args.online else None, args.debug_loopback, args.angle_backend, getattr(args, 'server_target', None))
++    command = launch_command(game, data, cache, client, angle, commands, args.session_file.resolve() if args.online else None, args.debug_loopback, args.angle_backend, getattr(args, 'server_target', None), background=args.background)
+     command += ['--netease-compat', str(args.compat_report)]
+     (log.parent/'commands.json').write_text(json.dumps(commands, ensure_ascii=False, indent=2)+'\n')
+     if args.make_app:
+@@ -328,7 +329,7 @@ def main():
+         script = mac/'Launch'
+         wrapper = [sys.executable, str(Path(__file__).resolve()), '--game-dir', str(game), '--data-dir', str(data),
+                    '--cache-dir', str(cache), '--client', str(mac/'mcpelauncher-client'), '--angle-dir', str(app/'Contents/Frameworks'),
+-                   '--world-id', args.world_id, '--world-name', args.world_name, '--log', str(log), '--exec-client']
++                   '--world-id', args.world_id, '--world-name', args.world_name, '--log', str(log), '--exec-client'] + (['--background'] if args.background else [])
+         if args.cppconfig:
+             wrapper += ['--cppconfig', str(args.cppconfig.resolve())]
+         if args.compat_report: