mcpywrap 0.5.0__tar.gz → 0.5.2__tar.gz

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 更新记录
 
+## 0.5.2
+
+- Addon 的本地/Git 依赖可声明 `consumer_prepare`，使用同一依赖版本的工具处理消费项目素材；build、package 和实际本地新启动自动准备，支持传递范围、来源去重及显式停用，无需消费者重复绑定 hooks。
+- `sync` 可使用本机兼容 Python 创建项目 `.venv`，支持指定已有解释器；不会下载 Python、安装处理器第三方库或执行资源准备。新增 JSON Schema 配置校验、来源诊断及统一日志，失败、超时、取消或身份变化阻止后续组装和新启动。
+- `script list --effective --json` 提供根任务与依赖任务的执行计划、配置示例、环境及就绪状态；原有根脚本和 JSON 查询保持兼容。
+- Windows 统一普通路径与扩展路径的依赖身份，修复传递准备入口定位失败；有限脚本按所属 Job 核对退出，避免过期进程树误判或影响无关进程。
+- Skill 按消费者与框架作者分开提供指引，附带可独立复制的完整模板；现行产品文档与开发、测试、发布流程分开维护。
+
+## 0.5.1
+
+- `screenshot` 支持兼容 Launcher 的 macOS 本地会话，按需读取游戏渲染帧并保存 PNG，无需系统屏幕录制权限。使用实例固定的 `screenshot_protocol=1` 能力，旧运行包明确拒绝。CLI 默认使用原生运行包 0.4.5，全新安装无需额外开启截图。
+- macOS 本地录屏和视频提帧仍不支持；Windows 本机与远程采集沿用原有行为。
+
 ## 0.5.0
 
 - 统一运行部署生命周期：Addon 无论有无依赖都使用稳定装配目录，修复首次添加依赖、移除最后一个依赖后同 UUID 路径变化导致的启动冲突；保留世界，重新运行使用当前代码，`--new` 仅表示新世界。

mcpywrap-0.5.0/docs/development.md → mcpywrap-0.5.2/CONTRIBUTING.md

@@ -6,7 +6,7 @@ python -X utf8 -m unittest discover -s tests -v
 
 自动化测试使用临时目录、模拟安装/发布、Qt 离屏界面和模拟游戏进程，不启动真实游戏。
 
-Windows 输入编排与游戏内队列共用 `timeline.py`，单次 key/mouse 与编排共用 `window.InputSender`。改动这些公共层时运行旧输入、编排及玩家队列回归；真实接收窗口和游戏 CLI 的时序验收见 [输入编排开发说明](input-sequence.md#验证)。
+Windows 输入编排与游戏内队列共用 `timeline.py`，单次 key/mouse 与编排共用 `window.InputSender`。改动这些公共层时运行旧输入、编排及玩家队列回归；真实接收窗口和游戏 CLI 的时序验收见 [输入编排开发说明](tests/README.md#输入编排)。
 测试进程使用UTF-8以保持文件读取和直接调用内部函数时的诊断输出一致；独立子进程另外验证真实CLI在GBK和UTF-8管道中的行为，不通过强制用户修改系统编码来掩盖兼容问题。
 CLI 使用调用上下文传递项目目录；底层服务接受明确路径。不要为 GUI 切换全局工作目录。
 
@@ -15,7 +15,7 @@ CLI 使用调用上下文传递项目目录；底层服务接受明确路径。
 
 Addon完整构建先组装再替换；Windows临时锁仅做有限重试。若安装与回滚同时失败，错误会报告保留的`.mcpy-build-*/previous`旧构建及目标目录。检查并解除占用后人工恢复；工具不自动删除或重放这类恢复目录。新产物已安装后的临时目录清理失败只记警告。
 
-Skill 的辅助脚本只使用公开 CLI。游戏交互优先使用 runtime ui/player；game_window 提供绑定会话的截图与桌面输入，Computer Use 仅用于允许占用前台的任务。
+Skill 的辅助脚本只使用公开 CLI。游戏交互使用 Skill 当前推荐的公开入口；game_window 提供绑定会话的截图与桌面输入，Computer Use 仅用于允许占用前台的任务。
 真实游戏验证请使用独立测试项目：
 
 ```powershell
@@ -25,7 +25,7 @@ python skills/mcpywrap/scripts/smoke.py --project D:\mods\test --game --expect-l
 脚本结束后停止自己创建的会话；日志和产物留在项目中。
 需要手动截图验证时直接运行 `run --no-gui --detach --json`，保存会话 ID，操作完后显式 stop。
 网络验证使用 `smoke.py --project <已有目录> --connect <地址> --expect-log <约定标记>`，不打包项目。单人与网络测试都可显式加 `--mcs-auth`；脚本停止自己创建的会话。
-UI/玩家动作及服务端场景准备使用 [可选手动测试入口](../tests/manual/runtime_controls/README.md)。这些脚本不参与默认 unittest/CI，不在正常游戏启动时执行；测试报告写到忽略的 `test/` 或仓库外目录，不提交过程记录。
+UI/玩家动作及服务端场景准备使用 [可选手动测试入口](tests/manual/runtime_controls/README.md)。这些脚本不参与默认 unittest/CI，不在正常游戏启动时执行；测试报告写到忽略的 `test/` 或仓库外目录，不提交过程记录。
 
 录制自动化测试使用模拟任务和真实回环 HTTP，覆盖超过 64 MiB 的分块下载、内存上限、输入并行、清理保护和归档校验。真实 WGC／Media Foundation 验证在已登录未锁屏的 Windows 桌面显式运行：
 
@@ -39,26 +39,40 @@ Remove-Item Env:MCPY_NATIVE_TESTS
 
 `tests/manual_remote_recording.py --project <独立目录> --command <已安装mcpy路径>` 在本机回环启动带令牌的服务和自己的游戏，使用公开远程 CLI 验证录制、输入、游戏退出后的下载／提帧和删除，并清理游戏与服务。连接目标为本机 19132，不要求真实服务器，因此只验证捕获与传输，不声明进服成功；真实跨机器仍需分别在 Windows 和调用端验收。
 
-发布见 [发布流程](releasing.md)。
+发布见 [发布流程](RELEASING.md)。
 
 局域网协议与路由测试使用 `tests/test_remote.py` 的真实回环 HTTP 和模拟游戏，不需要实际登录。
 桌面原生实现集中在 `mcstudio/window.py`，Skill 脚本只组合公开 CLI。鼠标逻辑通过模拟 Win32 测试释放与坐标，实机效果按截图验证。
 Windows CI 保留 3.9/3.12/3.14；macOS CI 验证 Qt 的延迟导入、Qt 离屏组件、本机构建与远程客户端。真实跨机测试需另行准备 Windows 桌面和 macOS 客户端。
 
-游戏内 UI 的协议与有状态适配器测试见 `tests/test_runtime_ui.py`。在独立测试世界运行 `tests/manual_runtime_ui.py --project <目录> --session <会话> --output <新JSON> --require-background` 可通过公开 CLI 验证节点、后台滚动、点击音频页、主音量调整及恢复、旧快照拒绝与重复请求；运行前保持其他应用前台。脚本不停止传入会话，由创建者在结束后 stop。正式 UI 功能与内部引擎接口边界见 [runtime-ui.md](runtime-ui.md)。
+游戏内 UI 的协议与有状态适配器测试见 `tests/test_runtime_ui.py`。在独立测试世界运行 `tests/manual_runtime_ui.py --project <目录> --session <会话> --output <新JSON> --require-background` 可通过公开 CLI 验证节点、后台滚动、点击音频页、主音量调整及恢复、旧快照拒绝与重复请求；运行前保持其他应用前台。脚本不停止传入会话，由创建者在结束后 stop。正式 UI 功能与内部引擎接口边界见 [runtime-ui.md](docs/runtime-ui.md)。
 
-玩家操作与队列的状态机测试见 `tests/test_runtime_player.py`。`tests/manual_runtime_player.py` 使用已准备的独立生存世界验证进食、等待、选槽、朝向、蓄力射箭及重复请求；会消耗食物和箭，并恢复朝向、选槽。准备条件及参数见 [runtime-player.md](runtime-player.md)。
+玩家操作与队列的状态机测试见 `tests/test_runtime_player.py`。`tests/manual_runtime_player.py` 使用已准备的独立生存世界验证进食、等待、选槽、朝向、蓄力射箭及重复请求；会消耗食物和箭，并恢复朝向、选槽。准备条件及参数见 [runtime-player.md](docs/runtime-player.md)。
 
 ## 项目脚本回归
 
-用户契约见 [项目脚本](project-scripts.md)。`project_scripts.py` 负责根项目任务与合作锁；`_script_worker.py` 是通过绝对路径启动的内部有限任务监督进程。低层 builder、Deployment.prepare/refresh 不自动执行 hooks。
+用户契约见 [项目脚本](docs/project-scripts.md)。`project_scripts.py` 负责根项目任务与合作锁；`_script_worker.py` 是通过绝对路径启动的内部有限任务监督进程。低层 builder、Deployment.prepare/refresh 不自动执行 hooks。
 
 `tests/test_project_scripts.py` 使用真实子进程、临时项目及模拟游戏启动，覆盖 JSON 透传、命令位置、串行失败、取消/超时、父进程被杀后的子进程清理和 native/Windows 准备入口。Qt 准备进度与所有权取消在 `test_qt_sessions.py` 中验证。Windows Job Object 路径须由 Windows CI/实机验证，macOS 测试不能替代。
 
+## 消费者准备维护
+
+`consumer_prepare.py` 从 DependencyService 的同一解析结果构建准备计划，`prepare_environment.py` 检查解释器并仅在 sync 创建缺失环境。Git 节点保留原始来源，工具从只读源码快照定位；注册的游戏导出目录不承担工具路径解析。
+
+公共 `before` 执行根任务后运行消费者入口，阶段间检查配置、包身份和工具源码。CLI 构建和 worker 部署复用计划中的 manager；低层 builder 和 Deployment 不触发入口。启动预检保存摘要、任务描述和预算，worker 校验后执行，新增或变化的任务不能绕过预算。
+
+消费者用法维护在 Skill 的 consumer-prepare 参考页，作者协议维护在 consumer-prepare-author 页。完整模板统一位于 Skill 的 assets/consumer-prepare，仓库 examples 仅保留导航。`tests/test_consumer_prepare.py` 将 Skill 单独复制到临时目录，通过其中的模板验证本地/Git 消费和只读查询；另使用真实 Git、虚拟环境和子进程验证协议，不声称游戏验收。实机验证程序显式运行，记录按平台区分。
+
+可选验收程序 `python tests/manual/consumer_prepare_acceptance.py --output <尚不存在的证据目录>` 复制示例并验证 sync、查询、build/package 和输入更新；加 `--game` 才启动当前平台的独立游戏，检查新启动一次、复用零次和重启一次。`--game --clients 2` 检查主机一次、客机补齐零次和整组重启一次。脚本只清理本次独立夹具的会话，保留世界和报告；不会把进程生命周期验证标记成多人玩法或连接成功。Windows/macOS 分别运行，不接入默认 CI。
+
+## 图标资源
+
+使用 `python scripts/build_app_icon.py` 重建 PNG 和 ICNS，需要本机 Xcode 27 / Icon Composer 27 与 PySide6。保留可编辑分层源；运行时直接使用静态资源，不要求用户安装 Xcode。图标的产品与格式约定见 [Qt 界面](docs/qt6-development.md#应用图标)。
+
 ## 文档与 Skill 的维护边界
 
 面向用户和 AI 的命令用法以 `skills/mcpywrap/SKILL.md` 及其 references 为单一维护来源。主文件只保留调用契约、任务路由和影响决策的共通边界；每篇参考围绕一个实际任务，可独立完成该任务，不以源码模块或提交批次划分文章。参数以公开 CLI 帮助和目标能力核对，旧协议留在兼容入口。
 
 修改公开能力时，更新对应的唯一参考页和必要的主文件路由；README 与 docs 中的用户入口指向它，不复制整份操作流程。验证参考链接可在单独复制的 Skill 中使用，示例能经公开 CLI/配置解析，简单任务不必读取安装、调试、录制等无关章节。Skill 测试应验证示例/协议行为，不锁定段落措辞。
 
-`docs/` 只保存长期有效的架构、协议、构建/发布规则及维护说明；可复用的自动化/人工验收程序留在 tests。临时计划、竞品调研、逐轮审计、推进状态、机器路径与当次验收日志放入 Git 忽略的 `.local-notes/` 或 `test/`。这些目录同时被 sdist 排除，发布检查不得把本地工作笔记当必需文件。
+`docs/` 只保存现行产品、架构、接口契约及兼容性说明，不放开发过程文档。维护与发布流程分别放在根目录 CONTRIBUTING.md、RELEASING.md，可复用测试指南与程序留在 tests。临时计划、竞品调研、逐轮审计、推进状态、机器路径与当次验收日志放入 Git 忽略的 `.local-notes/` 或 `test/`。这些目录同时被 sdist 排除，发布检查不得把本地工作笔记当必需文件。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/MANIFEST.in

@@ -1,17 +1,31 @@
 include LICENSE README.md CHANGELOG.md
 recursive-include mcpywrap/ui/assets *.svg *.png *.icns *.json
 include scripts/build_app_icon.py
-include docs/releasing.md
+include CONTRIBUTING.md RELEASING.md
 include docs/runtime-debug.md docs/project-scripts.md
 include docs/runtime-ui.md docs/runtime-player.md
 include docs/input-sequence.md
 include docs/runtime-input.md
-include docs/local-dependencies.md docs/engine-discovery.md docs/development.md
+include docs/local-dependencies.md docs/engine-discovery.md
 include docs/mcs-auth.md
 include docs/code-libraries.md docs/git-dependencies.md docs/qumod.md
 recursive-include tests *.py
+include tests/README.md
 recursive-include tests/manual *.md *.json
+include examples/consumer_prepare/README.md
 recursive-include skills *.md *.yaml *.ps1 *.py
+prune skills/mcpywrap/assets/consumer-prepare
+include skills/mcpywrap/assets/consumer-prepare/framework/pyproject.toml
+include skills/mcpywrap/assets/consumer-prepare/framework/behavior_pack/manifest.json
+include skills/mcpywrap/assets/consumer-prepare/framework/behavior_pack/CatalogRuntime/__init__.py
+include skills/mcpywrap/assets/consumer-prepare/framework/build_tools/*.py
+include skills/mcpywrap/assets/consumer-prepare/framework/build_tools/*.json
+include skills/mcpywrap/assets/consumer-prepare/framework/build_tools/*.toml
+include skills/mcpywrap/assets/consumer-prepare/game/pyproject.toml
+include skills/mcpywrap/assets/consumer-prepare/game/behavior_pack/manifest.json
+include skills/mcpywrap/assets/consumer-prepare/game/resource_pack/manifest.json
+include skills/mcpywrap/assets/consumer-prepare/game/data/items.json
+include skills/mcpywrap/assets/consumer-prepare/game/.gitignore
 include scripts/build_mcs_auth_bridge.py
 include scripts/build_all_native.py
 include scripts/build_window_capture.py

{mcpywrap-0.5.0/mcpywrap.egg-info → mcpywrap-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.5.0
+Version: 0.5.2
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Dist: tomli
 Requires-Dist: tomli-w
 Requires-Dist: setuptools
 Requires-Dist: packaging>=21
+Requires-Dist: jsonschema<5,>=4.18
 Requires-Dist: PySide6-Essentials<7,>=6.6; sys_platform == "win32" or sys_platform == "darwin"
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: rich>=10.0.0
@@ -149,7 +150,7 @@ Skill 按当前任务选择参考，不要求 AI 通读产品文档。可直接
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。
 - [更新记录](https://github.com/EaseCation/mcpywrap/blob/main/CHANGELOG.md)
-- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/docs/development.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/docs/releasing.md)
+- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/CONTRIBUTING.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/RELEASING.md)
 - 欢迎通过 [Issues](https://github.com/EaseCation/mcpywrap/issues) 反馈问题或提交 PR。
 
 [MIT License](LICENSE) © EaseCation

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/README.md

@@ -121,7 +121,7 @@ Skill 按当前任务选择参考，不要求 AI 通读产品文档。可直接
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。
 - [更新记录](https://github.com/EaseCation/mcpywrap/blob/main/CHANGELOG.md)
-- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/docs/development.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/docs/releasing.md)
+- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/CONTRIBUTING.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/RELEASING.md)
 - 欢迎通过 [Issues](https://github.com/EaseCation/mcpywrap/issues) 反馈问题或提交 PR。
 
 [MIT License](LICENSE) © EaseCation

mcpywrap-0.5.0/docs/releasing.md → mcpywrap-0.5.2/RELEASING.md

@@ -33,4 +33,12 @@ Windows CI 先用 MSVC 从 `native/mcs_auth` 编译 x86 登录桥接，再签名
 
 不要覆盖已有 PyPI 版本。发布动作开启 PyPI provenance attestations；各第三方 Action 固定到已核实的提交。GitHub `pypi` environment 与 PyPI publisher 的 environment 必须一致。
 
-用户当前操作统一见 [内置 Skill](../skills/mcpywrap/SKILL.md)。发布验证记录、候选核查和跨仓库推进计划放在被忽略的 `.local-notes/`，不随源码包分发；长期发行规则维护在本页。候选 CI 的未签名桥接不用于验证正式签名登录流程。
+用户当前操作统一见 [内置 Skill](skills/mcpywrap/SKILL.md)。发布验证记录、候选核查和跨仓库推进计划放在被忽略的 `.local-notes/`，不随源码包分发；长期发行规则维护在本页。候选 CI 的未签名桥接不用于验证正式签名登录流程。
+
+## 本机登录桥接开发
+
+源代码位于 `native/mcs_auth`。CI 使用 x86 MSVC 和系统自带的 .NET Framework C# 编译器；本机开发也可使用 x86 TinyCC：
+
+```powershell
+python scripts/build_mcs_auth_bridge.py --cc <x86-tcc.exe> --output <输出目录>
+```

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/code-libraries.md

@@ -3,7 +3,7 @@
 本文描述兼容的叶子代码库声明；新项目推荐 [通用Git项目依赖](git-dependencies.md)，支持读取项目导出和递归子依赖。
 
 QuMod 用户可直接运行 `mcpy add --qumod`，无需手写下方配置；图形界面Git依赖中提供“一键添加 QuMod”快捷按钮。
-克隆项目后执行 `mcpy sync` 恢复。详见 [QuMod 指引与来源调研](qumod.md)。
+克隆项目后执行 `mcpy sync` 恢复。详见 [QuMod 接入](qumod.md)。
 
 代码库由构建工具装入游戏包，独立于 `[project].dependencies`（工具 Python 环境）和 `local_dependencies`（完整 Addon）。不要求上游包含 manifest，不运行上游安装脚本，不自动初始化入口。
 

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/game-backends.md

@@ -19,7 +19,7 @@ WindowsBackend 调用原有 MC Studio 发现、cppconfig 和 Safaia 流程，保
 
 macOS 首次 mcpy run 自动从内置发布源安装原生运行包和官方 APK，进度在 stderr；也可提前执行 mcpy engine install。--catalog / --apk 是高级覆盖选项。交互式 run 显示共用调试小窗，ui 打开完整管理页；--no-gui / --detach / --json / --non-interactive 抑制调试小窗；Windows 保持手动安装 MC Studio。默认资源目录 ~/Library/Application Support/mcpy，可设置 MCPY_ENGINE_HOME、MCPY_RUNTIME_CATALOG。
 
-macOS 支持离线 Addon 世界；无认证服务器连接需 CLI 0.4.3+ 与运行包 0.4.3+ 配套，运行包须声明 network_connect_protocol=1（旧 0.4.0 运行包需要显式升级）。connect 与配置了 server 的 run 共用 cppconfig、会话、日志及退出；网络会话仅支持客户端调试，不装配本地 Mod。macOS 不支持 Map、MCS 登录或 Windows 桌面截图/键鼠/录像；需要这些能力时显式使用 Windows 远程端。最低 macOS 13.0，实际游戏只在 26.6.2 验证。运行包尚为 ad-hoc 签名、公证待完成。
+macOS 支持离线 Addon 世界；无认证服务器连接需 CLI 0.4.3+ 与运行包 0.4.3+ 配套，运行包须声明 network_connect_protocol=1（旧 0.4.0 运行包需要显式升级）。connect 与配置了 server 的 run 共用 cppconfig、会话、日志及退出；网络会话仅支持客户端调试，不装配本地 Mod。游戏截图通过支持 screenshot_protocol=1 的 Launcher 按需读帧；macOS 不支持 Map、MCS 登录、原始桌面键鼠或录像，相关能力边界见[内置 Skill](../skills/mcpywrap/references/macos-local.md)。最低 macOS 13.0；具体能力由所选运行包和当前实例诊断确定。运行包采用 ad-hoc 签名，未提供公证。
 
 图形界面的会话操作集中在 ui/session_controller.py；主界面和小窗仅使用共用 SessionControls/PythonConsole 与 LogView。小窗不再另起 Studio TCP 接收器，详见 [共用日志界面](shared-log-ui.md)。
 
@@ -31,7 +31,7 @@ Windows/macOS 共同基线是 `--local --project <目录> --non-interactive run
 
 基线使用同步 Python；可选队列仍以当前会话能力为准。远程调用遇到不支持的队列/等待条件会在发送代码前拒绝，py-result 和本地会话能力查询不会落到本机会话。没有新增服务端协议。
 
-smoke.py 的 --client-file/--server-file 通过同一 CLI 等待世界/HUD、分别执行一次脚本、收集 JSON/日志，并停止自己创建的游戏。可选 UI/玩家与服务端配套测试见 [手动测试入口](../tests/manual/runtime_controls/README.md)。
+可选 UI/玩家与服务端配套测试见 [手动测试入口](../tests/manual/runtime_controls/README.md)。
 
 两端单人实例共用 cppconfig 的 world_info；存储、启动转换、保存优先级和创建参数见[实例世界设置](instance-world-settings.md)。
 

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/git-dependencies.md

@@ -82,8 +82,4 @@ v2 锁使用相同的大小写敏感路径排序；源码由 Git archive 提取
 
 终端只显示同步进度、结果和必要操作；`mcpy sync --json` 返回结构化结果。`--migrate-windows-lock` 和 JSON 中始终为空的 `git_lock_migrations` 仅保留旧脚本兼容。团队各设备应使用包含此修复的版本，并提交 sync 更新后的锁文件。
 
-## 验证范围
-
-自动化测试使用与任何框架无关的本地Git仓库，覆盖Addon自动识别、代码导出、Git子依赖与仓库内引用、循环/越界、项目隔离、离线恢复、并发下载、更新/回退/移除、内容篡改和深层Windows路径。官方QuMod GitHub与Gitee固定提交的完整源码摘要一致，均通过创建框架、打包和干净克隆sync。
-
-这保证依赖获取与组装契约，不自动保证任意第三方代码兼容游戏。Git子模块、跨仓库可变本地路径、版本范围和上游构建钩子不在本版支持范围。
+测试入口见[测试说明](../tests/README.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/input-sequence.md

@@ -2,7 +2,7 @@
 
 公开入口与参数维护在 [Skill 编排说明](../skills/mcpywrap/references/input-sequence.md)。`input-sequence` 扩展 Windows 桌面输入；原有 `key`、`mouse` 和游戏内 `runtime player sequence` 仍可使用。
 
-## 维护边界
+## 实现边界
 
 - `mcpywrap/timeline.py` 是唯一的时间计划生成器：省略 `at_ms` 时按上一步计划结束和 `delay_ms` 生成，显式时间也进入相同计划。它同时被工具 Python 导入和注入游戏 Python 2，不依赖 Win32 或游戏 SDK。
 - `mcstudio/window.py` 的 `InputSender` 是唯一的 Windows `SendInput` 调用与输入释放实现。旧 key/mouse 和新编排共用它，旧命令的保持时长、修饰键提前量和返回格式不变。
@@ -13,10 +13,4 @@ Windows 使用绝对截止时间、较长空隙的短 sleep 和最后不超过
 
 本机和远程桌面输入共用 Windows 会话内的命名互斥，避免 key/mouse 与时间表交错。远程仍使用原桌面操作锁与协议版本 1，只增加 `input-sequence` 能力和接口；旧客户端不受影响，新客户端遇到旧服务会在发送前报能力不足。文件在调用端读取，不把调用端路径交给远端。
 
-## 验证
-
-`tests/test_input_sequence.py` 覆盖自动/显式时间计划、0 ms 批次、字段和按下释放配对、部分提交、时间戳、失焦、中断、迟到停止与释放。原 `test_game_window_skill.py`、`test_mouse.py` 回归旧入口；`test_remote.py` 通过真实回环 HTTP 验证文件传输、能力协商和失败记录。
-
-交互式 Windows 桌面可设置 `MCPY_NATIVE_TESTS=1`，运行 `tests/test_native_input_sequence.py`：只创建自己的惰性接收窗口，验证 0/1/5/10/20 ms 提交计划和接收顺序。可用 `MCPY_INPUT_TEST_REPORT` 指定尚不存在的 JSON 路径保存提交与接收时刻。测试不以固定精度断言掩盖系统抖动。
-
-真实游戏验收使用 `tests/manual_runtime_input.py --project <独立测试项目> --session <sid> --output <新JSON>`。要求已加载 HUD、快捷栏 8/9 为空并可看向无目标的天空；会占用游戏前台，使用空槽和对空右键，随后恢复原选槽和朝向。它同时验证游戏 Python 2 注入后的自动/显式时间计划；不会停止传入会话，创建者负责结束自己的测试游戏。
+测试入口见[测试说明](../tests/README.md)。

mcpywrap-0.5.2/docs/launcher-client-python.md

@@ -0,0 +1,27 @@
+# macOS Launcher 本地控制协议
+
+日常 Python 调试用法见内置 Skill 的[运行时调试](../skills/mcpywrap/references/runtime-debug.md)，截图用法见[画面采集](../skills/mcpywrap/references/capture.md)。本文维护原生接口与宿主实现的边界，不作为另一套用户操作指南。
+
+## 通道与身份
+
+Launcher 在私有临时目录建立 Unix socket，并在实例 data 目录原子发布 `python-control.json`：protocol=1、pid 和 socket 路径。元数据为 0600，socket 所在目录为 0700；宿主核验归属、权限及会话进程身份，不按窗口标题选目标。Python 与截图共享传输实现，方法独立，截图不执行游戏 Python，也不占 Python 请求队列。
+
+`status` 只读返回原生能力和 Python 就绪状态。`screenshot_protocol=1` 同时记录在运行包 runtime.json 和实际进程 status 中；前者供实例能力查询，后者在截图前确认运行中的实现。查询能力不触发读帧。
+
+## 客户端 Python
+
+`submit/result/cancel/release` 按 request_id 管理请求。相同 ID 与内容幂等，不同内容拒绝；排队请求可取消，已执行的游戏代码不能强行回滚。Python 未就绪时排队，进入世界后保留同一客户端命名空间。外层 worker 继续管理用户可见结果、并发和 Safaia 服务端通道。
+
+JSON UI 定义重载由独立的 `json_ui_reload_protocol=1` 声明。重载后业务界面与回调由 Mod 原有逻辑重新注册；协议不替代资源部署与会话占用检查。
+
+## 单帧截图
+
+`screenshot` 方法接受 `{op, request_id}`；op 为 capture、poll、release，ID 为 32 位小写十六进制。每进程只有一个槽位。capture 幂等，poll 不创建请求，release 只取消/释放匹配 ID，读取已开始时延迟回收其内存。
+
+请求在下一次 GLES swap 前、Launcher 工具层绘制前读取游戏 framebuffer，去掉顶部菜单栏，输出游戏内容区物理像素。原生端保留并恢复 framebuffer/pixel-pack 状态。五秒内没有完成有效读回返回 capture_timeout；不回退系统屏幕采集，不改变前台窗口。
+
+RPC 线程预留有界的匿名内存（最多 16 MiPixels × 4 字节）。渲染线程写入 bottom-up RGBA；完成后 RPC 线程写入私有像素文件并返回 width、height、source_time_ns。磁盘满通过 IO 错误返回，不将文件映射作为 GL 目标，以免渲染线程触发 SIGBUS。该时间来自 Launcher steady_clock，不是 Unix 时间，也不保证与 GPU 呈现时刻相同。
+
+像素路径固定为 socket 目录下的 `screenshot-<request_id>.rgba`，不接受调用方提供的原生输出路径。宿主以 no-follow 打开，检查归属、权限、类型和精确大小，完成方向/颜色转换与 PNG 编码。命令结束总是尝试 release；失联请求最多占用一个槽位，30 秒租约过期后可由下一请求回收，正常进程退出清理。
+
+原生实现只采集单帧，没有编码队列、持续采集服务或录像能力。macOS 的 record/record-frames 保持不支持。运行包必须重新构建才能提供新协议；更新 CLI、Skill 或 runtime install 不会替换旧实例固定的原生包。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/macos-resource-reload.md

@@ -1,6 +1,6 @@
 # macOS 资源热更参考
 
-本页保留原生适配机制与验证记录。用户操作统一见 Skill 的 [运行时调试](../skills/mcpywrap/references/runtime-debug.md) 与 [macOS 平台边界](../skills/mcpywrap/references/macos-local.md)，不要从底层接口名称推断可直接用于业务代码。
+本页维护原生适配机制与兼容性边界。用户操作统一见 Skill 的 [运行时调试](../skills/mcpywrap/references/runtime-debug.md) 与 [macOS 平台边界](../skills/mcpywrap/references/macos-local.md)，不要从底层接口名称推断可直接用于业务代码。
 
 适配器复用 MinecraftGame::handleReloadUIDefinitions，ABI 与受支持 ELF 摘要由原生启动器维护；不能认为任意 Android APK 通用。Windows 的 Ctrl+R 路径不适用于此后端，不能因按键投递成功便宣称 UI 定义已刷新。
 
@@ -12,6 +12,6 @@
 
 通用游戏内 UI/玩家能力可通过 [可选手动测试](../tests/manual/runtime_controls/README.md) 检查；资源热更另需对应 Mod 的效果验证，不能用按钮或脚本回执代替。
 
-3.10.100.299889 也已验证定义重载；新运行包按 ELF 结构识别接口，同一运行包可服务多个 APK 版本，仍需重新注册/创建界面；材质包装接口缺失，Metal Shader 尚未验证，两个入口继续返回 unsupported。切换 APK 版本后需新建实例，不能直接改动旧实例的引擎版本号。
+运行包按 ELF 结构识别接口；同一运行包可支持多个 APK 版本，能力由结构预检决定。定义重载后仍需重新注册/创建界面；Material 和 Metal Shader 入口保持 unsupported。切换 APK 版本需新建实例，不能直接改动旧实例的引擎版本号。
 
 结构规则运行包在安装与启动前执行预检，核心结构无法确认时返回 `unsupported_engine_structure` 和诊断路径，不改变已选版本。JSON UI 定位失败单独返回 unsupported，不影响离线世界启动。新 APK 的版本号不会自动启用尚未验证的 Material/Metal Shader 热更。启动器来源由发行 catalog 管理，默认 APK 来源按网易 pe 发现；结构兼容不等于任意新 APK 的全部能力已获实机验证。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/mcs-auth.md

@@ -32,14 +32,4 @@ mcpy --project D:\mods\demo --non-interactive run --mcs-auth --detach --json
 
 停止使用时，去掉 `--mcs-auth` 即可。若曾安装证书，可打开 `certmgr.msc`，在当前用户的“受信任的根证书颁发机构 → 证书”中找到 `mcpywrap Project Code Signing`，核对上述指纹后移除。不要移除其他证书。已加载的托管桥接程序集会随 MC Studio 退出而卸载。
 
-## 开发与发布
-
-源代码位于 `native/mcs_auth`。CI 使用 x86 MSVC 和系统自带的 .NET Framework C# 编译器；本机开发也可使用 x86 TinyCC：
-
-```powershell
-python scripts/build_mcs_auth_bridge.py --cc <x86-tcc.exe> --output <输出目录>
-```
-
-发布时由 CI 从 GitHub Actions secrets 取得加密 PFX 与密码，在临时 runner 中签署组件并清理私钥。仓库不保存私钥或编译后的组件，只保存源码与公钥校验信息。`scripts/check_mcs_auth_bridge.py` 检查源代码、产物、架构及发布者是否匹配；详见[发布流程](releasing.md)。
-
-`MCPY_MCS_BRIDGE_DIR` 可指定开发组件目录；程序不会为任意外部组件提供证书信任安装。发布包的组件会缓存到用户目录的 `.local/share/mcpywrap/mcs-auth-bridge/<版本摘要>`，避免应用目录重定向造成外部终端找不到文件。
+`MCPY_MCS_BRIDGE_DIR` 可覆盖组件目录；程序不会为任意外部组件提供证书信任安装。发布组件缓存到用户目录的 `.local/share/mcpywrap/mcs-auth-bridge/<版本摘要>`。构建与签名流程见[发布说明](../RELEASING.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/qt6-development.md

@@ -33,7 +33,7 @@ GUI 和 CLI 共用 SessionWatcher：成功组装后防抖，向指定端侧发
 
 Python 模块热更更新模块命名空间；不会自动重建已有对象、替换已注册的回调或撤销之前的副作用。修改事件注册、类结构、新增入口、删除模块或不支持动态加载的资源时，使用“重新部署并重载世界”。该按钮保存退出、重新组装、重开同一世界，不新建或丢弃存档。
 
-资源热更按实际后端能力处理：当前 macOS 开发包支持已知粒子文件更新；local6 起的运行包通过原生入口重载 JSON UI 定义，须重新注册/创建界面及绑定回调，Qt 与 CLI 共用结果和提示。旧运行包的 JSON UI、当前材质和 Shader 返回 unsupported。资源回执为 triggered，仍须检查实际效果。详见 [macOS 资源热更验收](macos-resource-reload.md)。
+资源热更按实际后端能力处理：当前 macOS 开发包支持已知粒子文件更新；支持原生 JSON UI 重载协议的运行包可重载定义，之后须重新注册/创建界面及绑定回调，Qt 与 CLI 共用结果和提示。缺少该协议的运行包、当前材质和 Shader 返回 unsupported。资源回执为 triggered，仍须检查实际效果。详见 [macOS 资源热更](macos-resource-reload.md)。
 
 新原生运行包声明 addon_link_protocol=1，使用 `--link-source-addons`：游戏行为包/资源包目录软链接到实例 assembled 目录，packs 中的标准名称也只是链接。主项目和依赖继续由同一组装器合并，监控直接更新组装目录，无需再复制运行副本。原始项目和依赖不移动、不删除。旧实例仍固定旧运行包，保留复制兼容路径；升级运行包后新建实例才启用新协议。
 
@@ -59,11 +59,11 @@ GUI 入口共用 `ui.application.create_application`：Qt 应用名与菜单显
 
 图标源为 `mcpywrap/ui/assets/mcpy.icon`，是可由 Icon Composer 27 编辑的分层文档：深蓝背景、薄荷绿方块、白色命令提示符。背景满幅不透明，前景 SVG 未预裁切；命令提示符保留不透明，以确保小尺寸对比度。不把 Minecraft 游戏图标用作 mcpy 品牌图标。
 
-设计依据 Apple [App icons HIG](https://developer.apple.com/design/human-interface-guidelines/app-icons)（2026-06-08 更新）和 [Icon Composer 文档](https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer)：
+图标遵循 Apple [App icons HIG](https://developer.apple.com/design/human-interface-guidelines/app-icons) 和 [Icon Composer 文档](https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer)：
 
 - 1024×1024 画布、sRGB；圆角遮罩、高光、边缘反射和层间阴影由 Apple 渲染器生成，不自行用固定半径模拟系统连续圆角。
 - 方块范围 x=248–776、y=224–816，主要内容距离未裁切画布边缘至少 208 px。此数值是本设计的留白选择，HIG 并未规定统一的 macOS 安全区百分比。
 - 分层源背景不预留透明外框。导出给传统 Qt/ICNS 的静态图标时，参考 actool 的 macOS 兼容输出，在 1024 画布内将系统渲染图形放入 824×824 区域，四周留 100 px 透明区，防止 Dock 中图标显得过大。分层源与静态兼容文件的留白不能混用。
 - 图标已用 Icon Composer 27 渲染，并通过 Xcode 27 actool 编译。保留 `.icon` 原始分层素材，PNG 和 ICNS 则用于当前 Qt 应用；静态资源不具备随光照变化的动态 Liquid Glass，也不会自动切换 dark/clear/tinted 外观。将来独立打包 mcpy.app 时可接入编译后的 Assets.car，不能仅给 PNG 加反光就宣称支持全部动态外观。
 
-维护者运行 `python scripts/build_app_icon.py` 重建 PNG 和 ICNS，需要本机 Xcode 27 / Icon Composer 27 与 PySide6；运行时无需 Xcode。ICNS 提供 16、32、128、256、512 点的 1×/2× 图像。wheel 包含静态图标和可编辑分层源。
+ICNS 提供 16、32、128、256、512 点的 1×/2× 图像。wheel 包含静态图标和可编辑分层源，运行时无需 Xcode；图标维护见 [贡献指南](../CONTRIBUTING.md#图标资源)。

mcpywrap-0.5.2/docs/qumod.md

@@ -0,0 +1,7 @@
+# QuMod 接入
+
+添加、恢复、升级和移除 QuMod 的公开用法统一维护在 [Skill 依赖与 QuMod](../skills/mcpywrap/references/project-dependencies.md)。
+
+QuMod 是通用 Git 依赖的预设：来源、推荐提交、目录和模板由 `framework_presets` 维护，标准缓存、解析与组装层不识别框架名称。命令返回实际锁定提交；源码版本字段不表示存在同名官方 Release，已有项目不会随工具升级自动更换依赖版本。
+
+运行库安装到各自 Mod 的脚本目录，系统名和通信通道保持各自作用域。工具不自动合并 Optional、不按业务 import 裁剪代码，也不运行上游 EXE。其他框架使用相同的[Git 依赖契约](git-dependencies.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/runtime-debug.md

@@ -4,4 +4,4 @@
 
 实现定位：`mcstudio/runtime_debug.py` 管理游戏调试请求；`mcstudio/hot_reload.py` 和 `runtime/groups.py` 处理单会话/组更新；`runtime/watch.py` 观察源码事件；实际运行文件写入经 `runtime/deployment.py`。worker 按真实进程身份建立通道和归属，旧 worker 的能力不能由新版 CLI 推定。
 
-Windows 服务端/客户端通道与 macOS 客户端队列实现不同，调用者使用公共能力查询。原生平台资源适配与证据见 [macOS 资源实现说明](macos-resource-reload.md)，通用回归入口见 [开发与验证](development.md)。
+Windows 服务端/客户端通道与 macOS 客户端队列实现不同，调用者使用公共能力查询。原生平台资源适配见 [macOS 资源实现说明](macos-resource-reload.md)，通用回归入口见 [开发与验证](../CONTRIBUTING.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/runtime-input.md

@@ -10,6 +10,6 @@ Agent 的推荐入口是 `runtime input observe → run → status/cancel`；公
 
 Windows适配在会话worker中保留状态与幂等历史，单个调度线程推进操作；远程input端点只传参数。统一游戏控制层预留防止新旧游戏写请求插入设备计划；已持有的系统键或修饰键拒绝接管。未知释放保持busy，支持stop重试，不扩大为多请求共享输入。
 
-原生Mac时钟primitive和配套启动器/结构规则补丁在 `native/runtime_input`。CLI 0.4.6 默认指向运行包 0.4.4，提供 `launcher.steady_clock`；已在 Apple Silicon / macOS 26.6.2 / 开发包 3.9.100.297020 通过 8 项实机用例，3.10.100.299889 通过结构识别检查。旧运行包仍返回 `missing_monotonic_clock`，需显式升级资源并新建实例；原始pointer/text缺能力时保持不支持。
+原生 Mac 单调时钟及启动器结构规则位于 `native/runtime_input`。运行包通过 `launcher.steady_clock` 提供计时能力；缺少该接口时返回 `missing_monotonic_clock`，需升级配套资源并新建实例。原始 pointer/text 缺少能力时保持不支持。
 
-验证采用假时钟检查时序、调用顺序、部分失败、取消、幂等和快照；可选实机脚本覆盖真实客户端与服务端读回。旧入口不改变其修饰键排序、时间原点或输入后端；仅从默认发现入口隐藏，兼容参考保留。
+兼容入口保留原有修饰键排序、时间原点和输入后端，仅从默认发现入口隐藏。测试入口见[测试说明](../tests/README.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/runtime-player.md

@@ -11,7 +11,7 @@
 ## 实现边界
 
 - 公共 ModSDK 用于状态读取、朝向、移动向量锁定、跳跃。内部 `localplayermodule` 用于真实客户端攻击、选槽、使用物品、挖掘和释放，按实际函数是否存在报告能力，不按引擎版本号限制。接口缺失或调用异常会返回引擎版本与兼容性提示。
-- 鼠标负键码不能简单交给内部键盘模拟；实测返回成功却没有放置方块。玩家层改用真实语义入口，并让 key 拒绝鼠标键码。
+- 鼠标负键码不使用内部键盘模拟；键盘调用成功不能证明方块交互已发生。玩家层改用真实语义入口，并让 key 拒绝鼠标键码。
 - 食物/弓开始使用时，原生调用可能返回 False 但 `local_player_is_using_item()` 为 True；封装按真实使用状态继续保持并定时释放。只根据布尔返回值会错误地中断进食或蓄力。
 - `attack / dig / use_item / eat / shoot` 使用 30 秒有效的玩家快照。执行时核对玩家、维度、手持物品、选槽及瞄准目标。准星射线可能返回几十格外的方块，因此还必须与玩家实际 GetPickRange 比较，不能把“射线命中”当成“可交互”。
 - 所有持续输入有上限和自动释放；离开 HUD 时停止。只释放控制层记录的输入，不无条件清空用户或其他 Mod 的全部状态。锁屏、最小化或引擎不执行 tick 时的调度不作保证。
@@ -28,20 +28,14 @@
 
 `completed` 只说明输入流程完成，`effect_verified=false` 保留给上层根据饥饿值、物品数量、位置、目标生命值或服务端日志判断。尤其是挖掘时限耗尽，不等于目标已被破坏。原目标坐标已经变为空气时，`block_removed_observed=true / verification=client_block_readback` 表示客户端读到了方块消失，队列可以继续；不等同于已证明由本次操作造成了服务端变化。
 
-## 验证
+## 按键时间线与动作提交
 
 独立按键重叠使用新增 `runtime player timeline` / `mcpy.player.timeline(plan)`，公开契约见 [后台按键时间线](../skills/mcpywrap/references/runtime-key-timeline.md)。同一时刻严格遵循列表顺序，不采用旧 key 的修饰键排序；默认迟到继续并记录，可显式设置 max_lateness 中止。每个计划独占已有写操作槽位，取消/异常只释放本计划持有的键，失败释放可用 stop 重试。接口通过同一客户端 Python 通道，原 sequence 保持串行。
 
 统一安装源码超过单条 32 KiB 限额时分段暂存，确认各段后才执行安装；暂存不注入部分控制器。查询及业务包不依赖暂存模块，不扩大原传输上限。输入消费阶段、暂停期间释放和人工输入归属均不作额外保证，不把脚本回调计数包装为模拟 tick。
 
-`tests/test_runtime_key_timeline.py` 用假时钟验证边沿顺序、独立释放、迟到策略、幂等、互斥及失败清理。`tests/manual_runtime_key_timeline.py` 是显式可选的 Windows 实机验收，三次重复重叠配方，并检查两种修饰键顺序、取消和菜单释放；保存真实跳跃、持续移动及后台观测证据，不进入默认测试或正常启动。
-
-`tests/test_runtime_player.py` 使用有时序的引擎适配器验证：按键逆序释放、移动/疾跑恢复、目标变化与越距拒绝、食物 False 返回但已开始使用、弓蓄力松开、队列延迟、预检失败、步骤断言、取消、重复请求和调用者修改原计划后的隔离。
-
-实机验收脚本为 `tests/manual_runtime_player.py`。先准备独立生存世界、未满的饥饿值、快捷栏食物/普通弓及箭，再运行 `--project <项目> --session <sid> --food-slot 3 --bow-slot 4 --output <新JSON> --require-background`。脚本通过公开 CLI 提交并验证队列，消耗一份食物和一支箭，恢复原朝向和选槽；不会创建物品、改变游戏模式或停止传入会话。
-
-完整客户端动作与服务端配套夹具见 [可选运行时手动测试](../tests/manual/runtime_controls/README.md)。服务端准备会修改独立测试世界，必须显式开启；服务端读回饥饿、物品、伤害事件和方块变化，不把客户端 completed 作为效果证明。
-
 攻击、放置及物品使用的开始阶段统一交给游戏脚本 tick 执行，避免 JNI 客户端回调发生在引擎交互阶段之外时只出现动画或被拒绝。首次返回 pending 后仍查询原 operation；等待期间取消不会补发动作，开始前重新核对目标、物品、端侧场景和交互距离。completed/accepted 仍只表示动作调用完成，真实伤害、消耗和方块变化需另行观察。
 
 挖掘期间复用客户端 Player.Swing 播放原版挥手，动画请求与挖掘进度共用定时器，结束或取消后不再请求。缺少该 API 的引擎保留挖掘能力并报告 swing_supported=false；动画请求成功不代替方块状态验证。
+
+测试入口见[测试说明](../tests/README.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/docs/runtime-ui.md

@@ -53,10 +53,4 @@ HBUI/HTML 页面暂不提供节点访问：`snapshot` 与节点操作返回 `uns
 
 `snapshot` 的 root 默认为标准原生界面根或 `/main`。其他自定义界面可显式指定真实子树；不支持的结构会返回错误。标准滚动接口需要外层 scrolling_panel，而 Toggle 直接绑定原生节点时使用空相对路径；这些适配由控制层处理。
 
-## 验证
-
-单元与回环 HTTP 测试在 `tests/test_runtime_ui.py`：注入源直接执行、重复安装和升级、远程同名命令路由、过期/变化快照、重复路径、屏外节点、重复请求、按下失败、自动抬起、释放失败、文本参数转义和控件状态语义。
-
-`tests/test_runtime_ui_outline.py` 覆盖语义层级深度、不同卡片/列隔离、重复标签合并、只读字段、跨页上下文、原始签名不变与分组后的实际点击定位。
-
-可选实机检查使用 [运行时手动测试](../tests/manual/runtime_controls/README.md)，覆盖节点、滚动、滑块、过期快照及幂等请求；按当前实例实际能力报告结果，不用历史测试数据证明新引擎兼容。
+测试入口见[测试说明](../tests/README.md)。

mcpywrap-0.5.2/examples/consumer_prepare/README.md

@@ -0,0 +1,5 @@
+# 依赖自带消费者准备示例
+
+示例源码统一维护在 Skill 的 [assets/consumer-prepare](../../skills/mcpywrap/assets/consumer-prepare/)，单独复制或安装 Skill 也可使用。将资产目录复制到工作区后操作，不直接在 Skill 目录构建。
+
+使用方法见[消费者准备](../../skills/mcpywrap/references/consumer-prepare.md)，实现入口见[作者接入](../../skills/mcpywrap/references/consumer-prepare-author.md)。

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/mcpywrap/__init__.py

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

{mcpywrap-0.5.0 → mcpywrap-0.5.2}/mcpywrap/_script_worker.py

@@ -235,7 +235,8 @@ def main():
         save(path, state)
         if job: job.assign(process)
         while process.poll() is None:
-            members(process, known)
+            if not job:
+                members(process, known)
             if cancel.exists() or not alive(parent):
                 state.update(state='cancelled', code='script_cancelled', error='操作已取消或调用进程已退出')
                 break
@@ -244,10 +245,17 @@ def main():
                 break
             time.sleep(.05)
         else:
-            descendants = [r for r in members(process, known) if r['pid'] != process.pid]
+            # Windows 的 Job 是所有权依据。父进程退出后再按 PID 查询树，
+            # 可能观察到复用该 PID 的无关进程；同时给短暂的退出收尾留出时间。
+            descendants = [] if job else [r for r in members(process, known) if r['pid'] != process.pid]
+            remaining = job.active_count() if job else 0
+            settle_deadline = time.monotonic() + .2
+            while remaining and time.monotonic() < settle_deadline:
+                time.sleep(.01)
+                remaining = job.active_count()
             state.update(state='completed' if process.returncode == 0 else 'failed',
                          code=None if process.returncode == 0 else 'script_failed', exit_code=process.returncode)
-            if descendants or (job and job.active_count()):
+            if descendants or remaining:
                 state.update(state='failed', code='script_background_process', error='有限任务不能遗留后台进程')
     except BaseException as exc:
         state.update(state='failed', code='script_start_failed', error=str(exc))