mcpywrap 0.6.2__tar.gz → 0.6.4__tar.gz

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

@@ -1,5 +1,19 @@
 # 更新记录
 
+## 0.6.4
+
+- 游戏依赖新增 `unbundled` 布尔标记，默认 false；设为 true 时 dev/run 照常加载，build/package 排除，支持本地 Addon 与通用 Git Addon/code。
+- 新增依赖图只读预览和仅恢复打包依赖的同步选项，按引用链保留共享节点；Git 锁区分新标记并兼容既有普通依赖，未安装的不打包节点不阻塞发布。
+- Qt 依赖管理提供“不随构建打包”复选框、已有依赖设置修改和发布预览；CLI、JSON 与内置 Skill 使用同一概念，配对 App 的预览保持相同结果结构。
+- dev 与 build 的同目标写入互斥，完整构建清除旧开发产物；阻止不随发布的代码覆盖发布模块，并明确消费者准备的适用边界。
+- macOS 默认运行包升级到 0.4.7：修复兼容层 `uname` 布局越界与 `getlogin`/`sysinfo` 缺失，游戏内置 Tracy 由引擎自行启动并默认仅监听 `127.0.0.1:8086`；终止桩不再覆盖已实现的接口。旧实例保留原运行包绑定。
+
+## 0.6.3
+
+- Windows `run --clients 2` 默认自动加入并校验双方玩家；提供 `--join-mode manual` 保留手动操作，状态、Qt 会话页和 smoke 验收支持自动加入阶段。
+- Windows 本地多项目联机按实际主机端口适配客机，通过 x64 指令结构自动定位 NetherNet 配置，无固定版本地址表；无法唯一识别时拒绝注入并保留诊断。
+- 已验证 3.9.0.350466、3.9.0.401155 和 3.10.0.436581 的自动加入、双项目 Mod 加载与客机重启。修复组监控探针争用导致的连接状态误报，以及重启客机后的会话交接提示。
+
 ## 0.6.2
 
 - 日志新增字面过滤与重复消息统计，明确扫描范围；支持结构化日志的 App 宿主另提供端侧和毫秒时间范围筛选。

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/CONTRIBUTING.md

@@ -8,6 +8,8 @@ python -X utf8 -m unittest discover -s tests -v
 
 自动化测试使用临时目录、模拟安装/发布、Qt 离屏界面和模拟游戏进程，不启动真实游戏。
 
+Windows 本地自动联机改动需运行 `test_windows_lan.py`、组/会话/调试通道回归，再按 [实机验收入口](tests/README.md) 验证 3.9、3.10 与多个项目。端口定位基于运行映像的 x64 指令结构；不得用固定 RVA、版本字符串或未验证的数值搜索替代唯一候选、进程身份及写前/写后校验。更新 Windows 菜单采集辅助程序后重新构建其 manifest；新的菜单动作必须有当前画面依据和有界的失败路径。
+
 Windows 输入编排与游戏内队列共用 `timeline.py`，单次 key/mouse 与编排共用 `window.InputSender`。改动这些公共层时运行旧输入、编排及玩家队列回归；真实接收窗口和游戏 CLI 的时序验收见 [输入编排开发说明](tests/README.md#输入编排)。
 测试进程使用UTF-8以保持文件读取和直接调用内部函数时的诊断输出一致；独立子进程另外验证真实CLI在GBK和UTF-8管道中的行为，不通过强制用户修改系统编码来掩盖兼容问题。
 CLI 使用调用上下文传递项目目录；底层服务接受明确路径。不要为 GUI 切换全局工作目录。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.6.2
+Version: 0.6.4
 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.2
+Requires-Dist: mcpywrap-core==0.6.4
 Requires-Dist: pip>=23
 Requires-Dist: build>=1.0
 Requires-Dist: watchdog>=2.0.0
@@ -19,6 +19,8 @@ Requires-Dist: setuptools
 Requires-Dist: jsonschema<5,>=4.18
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: rich>=10.0.0
+Requires-Dist: capstone<6,>=5; sys_platform == "win32"
+Requires-Dist: pefile>=2023; sys_platform == "win32"
 Requires-Dist: PySide6-Essentials<7,>=6.6; sys_platform == "win32" or sys_platform == "darwin"
 Dynamic: license-file
 Dynamic: requires-dist

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/RELEASING.md

@@ -9,7 +9,7 @@
 Windows CI 先用 MSVC 从 `native/mcs_auth` 编译 x86 登录桥接，再签名并通过构建产物交给测试和 完整桌面包打包任务；编译后的 EXE/DLL 位于 `desktop/mcpywrap_assets/`，不提交到 Git，也不进入核心 wheel。仓库只保留发布者公钥证书和指纹。
 同一 native job 还会从 `native/window_capture` 编译 x64 后台截图辅助程序，生成 SHA-256 清单；测试和打包阶段校验二进制、源码及 wheel/sdist 内容。辅助程序不可用时运行时回退到前台截图。
 
-该辅助程序同时提供 WGC 连续采集、Media Foundation H.264 MP4 编码及 PNG 提帧；截图仍保持原协议与回退行为，录制要求 WGC，不回退到桌面捕获。源码清单覆盖 cpp 与 video_capture.h，sdist 必须包含二者。系统 H.264 编解码能力通过只读探测报告，不捆绑 FFmpeg。发布前在交互式 Windows 桌面执行 `MCPY_NATIVE_TESTS=1` 的原生验收；普通 CI 跳过需要可见桌面的测试。
+该辅助程序同时提供 WGC 连续采集、Media Foundation H.264 MP4 编码、PNG 提帧和 Windows OCR 菜单识别；截图仍保持原协议与回退行为，录制要求 WGC，不回退到桌面捕获。源码清单覆盖 cpp、video_capture.h 和 ocr.h，sdist 必须全部包含；media_protocol 与 ocr_protocol 分别校验。系统 H.264 编解码能力通过只读探测报告，不捆绑 FFmpeg。发布前在交互式 Windows 桌面执行 `MCPY_NATIVE_TESTS=1` 的原生验收；普通 CI 跳过需要可见桌面的测试。
 
 从源码安装时，在 Windows x64 且已安装 Visual Studio x86/x64 C++ 工具的环境中先运行 `python scripts/build_all_native.py`，再执行 `pip install -e ./core -e .` 或 `pip install ./core .`。脚本一次编译 x86 登录桥接和 x64 截图程序到包目录；可用 `--output-root <目录>` 将结果放入隔离目录。登录桥接源码编译产物没有发布签名，正式登录能力仍应使用带签名的发布包。
 

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/THIRD_PARTY_NOTICES.md

@@ -33,3 +33,13 @@ Upstream licensing and source:
 The separately downloaded native launcher has its own GPL licensing and
 corresponding-source distribution. Changing the Python GUI binding does not
 change that launcher's license or permit redistribution of Minecraft binaries.
+
+## Windows LAN inspection
+
+The Windows desktop package installs Capstone 5 (BSD license) and pefile (MIT
+license) through the package manager for x64 instruction decoding and PE header
+inspection. Their upstream licenses remain in their installed distributions:
+https://github.com/capstone-engine/capstone and https://github.com/erocarrera/pefile.
+No Minecraft executable, memory snapshot, instruction fixture extracted from a
+game, or modified game binary is shipped by this feature. Menu text recognition
+uses Windows.Media.Ocr supplied by Windows.

mcpywrap-0.6.4/core/mcpywrap_core/_version.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.6.2
+Version: 0.6.4
 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.2
+Requires-Dist: mcpywrap-core==0.6.4
 Requires-Dist: pip>=23
 Requires-Dist: build>=1.0
 Requires-Dist: watchdog>=2.0.0
@@ -19,6 +19,8 @@ Requires-Dist: setuptools
 Requires-Dist: jsonschema<5,>=4.18
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: rich>=10.0.0
+Requires-Dist: capstone<6,>=5; sys_platform == "win32"
+Requires-Dist: pefile>=2023; sys_platform == "win32"
 Requires-Dist: PySide6-Essentials<7,>=6.6; sys_platform == "win32" or sys_platform == "darwin"
 Dynamic: license-file
 Dynamic: requires-dist

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

@@ -25,6 +25,7 @@ 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
+docs/dependency-packaging-design.md
 docs/deployment-recovery.md
 docs/engine-discovery.md
 docs/game-backends.md
@@ -44,6 +45,7 @@ docs/runtime-player.md
 docs/runtime-ui.md
 docs/shared-core.md
 docs/shared-log-ui.md
+docs/windows-local-multiplayer.md
 examples/consumer_prepare/README.md
 native/background_window/README.md
 native/background_window/apply.py
@@ -61,8 +63,15 @@ native/runtime_input/README.md
 native/runtime_input/launcher-monotonic.patch
 native/runtime_input/manifest-monotonic.patch
 native/runtime_input/steady_clock.h
+native/tracy_profiler/README.md
+native/tracy_profiler/apply.py
+native/tracy_profiler/client-tracy.patch
+native/tracy_profiler/libc-shim-host-info.patch
+native/tracy_profiler/manifest-tracy.patch
+native/tracy_profiler/probe.py
 native/window_activation/README.md
 native/window_activation/window_activation.cpp
+native/window_capture/ocr.h
 native/window_capture/video_capture.h
 native/window_capture/window_capture.cpp
 scripts/build_all_native.py
@@ -134,6 +143,7 @@ tests/manual_runtime_input_unified.py
 tests/manual_runtime_key_timeline.py
 tests/manual_runtime_player.py
 tests/manual_runtime_ui.py
+tests/manual_windows_local_groups.py
 tests/runtime_support.py
 tests/test_application_icons.py
 tests/test_auth_interaction.py
@@ -205,10 +215,12 @@ tests/test_screenshot.py
 tests/test_session_capabilities.py
 tests/test_shared_logs.py
 tests/test_skill_workflows.py
+tests/test_unbundled_dependencies.py
 tests/test_unified_skill_contract.py
 tests/test_window_activation.py
 tests/test_window_focus.py
 tests/test_window_policy.py
+tests/test_windows_lan.py
 tests/manual/consumer_prepare_acceptance.py
 tests/manual/lifecycle_dependency_audit.py
 tests/manual/runtime_controls/README.md

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

@@ -1,4 +1,4 @@
-mcpywrap-core==0.6.2
+mcpywrap-core==0.6.4
 pip>=23
 build>=1.0
 watchdog>=2.0.0
@@ -8,5 +8,9 @@ jsonschema<5,>=4.18
 psutil>=5.8.0
 rich>=10.0.0
 
+[:sys_platform == "win32"]
+capstone<6,>=5
+pefile>=2023
+
 [:sys_platform == "win32" or sys_platform == "darwin"]
 PySide6-Essentials<7,>=6.6

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

@@ -11,9 +11,9 @@
     "Loader.c": "f2f1f781ce82fc30c62a6ce22bb048d3b023f6ff500e6ec8228da28b4dbf1b4a"
   },
   "files": {
-    "Injector.exe": "05806de2bd8143d690f4136451dd495b892d47036481b5af170576edeacd1d60",
-    "Loader.dll": "7f45d503eb7f06bf535bb564cda2d3b8dc7c38118d4433f514ca57fe94040cce",
-    "McpyMcsAuth.dll": "d7bf8957a2bdcac92bbef80ff0ef5709ffdebfb9ece237a65caf8e244483acce",
+    "Injector.exe": "ae038837e14f65131827b8e1a6aeaabc48a29c5513aa4506c8d0c6fd4613728f",
+    "Loader.dll": "ce459eab2daa5266302ff0f4449fe6124e4c38f86956ea20cdb1a29a58540432",
+    "McpyMcsAuth.dll": "3cb99a76bae9a655b321ef8dc698531dd093dfd7f725021a84d7d905621cbf09",
     "publisher.cer": "e5aa2ac39df40804ed8b08fe8e43c4a2b8923f0d02a360708486b2db5b6303d7"
   }
 }

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/desktop/mcpywrap_assets/window_activation/manifest.json

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

mcpywrap-0.6.4/desktop/mcpywrap_assets/window_capture/manifest.json

@@ -0,0 +1,11 @@
+{
+  "executable_sha256": "e3bc6c8b8c45df6c8e07655dc207921ae6908a4a9d397471d359d1269bf126d4",
+  "source_sha256": "64c9db4f31031fc794e4a41a3287a8382c5ac5599244824b6fd7d44971d68f05",
+  "sources": {
+    "ocr.h": "0b62eed9a41cdeec451283c24b140da4f333a47b59c581e26dd8f0d803e9cfd6",
+    "video_capture.h": "f766d4234e41a554a8eb8ecae93fd818c2fb8877fbd1795f3915dcc8771e7909",
+    "window_capture.cpp": "64c9db4f31031fc794e4a41a3287a8382c5ac5599244824b6fd7d44971d68f05"
+  },
+  "media_protocol": 1,
+  "ocr_protocol": 1
+}

mcpywrap-0.6.4/docs/dependency-packaging-design.md

@@ -0,0 +1,62 @@
+# 依赖的 unbundled 打包标记
+
+状态：已实现。默认 `unbundled = false`。日期：2026-10-30。
+
+## 契约
+
+`unbundled` 是依赖引用上的布尔值。false 表示随 build/package 发布；true 表示 dev/run 照常加载，但 build/package 排除。旧字符串形式的本地依赖、未填标记的 Git 依赖都默认 false。
+
+```toml
+[tool.mcpywrap]
+local_dependencies = ["../shared", { path = "../test-helper", unbundled = true }]
+
+[[tool.mcpywrap.git_dependencies]]
+name = "test-helper"
+git = "https://example.com/team/test-helper.git"
+rev = "0123456789abcdef0123456789abcdef01234567"
+unbundled = true
+```
+
+不引入 main/dev 依赖类别，避免与 dev 命令混淆；也不使用 Java 中通常表示合并依赖的 Shadow/Shade 命名。该标记只控制是否随产物发布，不表示 optional、外部宿主提供、源码替换或独立 Addon 加载。
+
+## 入口与反馈
+
+- `add --path/--git --unbundled` 设置 true；`--bundled` 设置 false。新依赖省略时默认 false；更新已有依赖省略时保留原值。
+- `dev`、本地 `run`、本地双客户端组和 Windows edit 选择运行图，包含根项目的 unbundled 引用。
+- `build`、`package` 选择发布图，组装前排除 unbundled 引用。package 从源码独立组装。
+- `deps --json` 只读预览运行图；`deps --bundled-only --json` 预览发布图。
+- 默认 sync 准备运行图；`sync --bundled-only` 恢复已锁定的发布图，保留未安装节点的锁记录。
+- 网络连接和远程运行保持原有端侧限制，不因这个标记自动向服务器安装依赖。
+
+UI 使用默认不勾选的“不随构建打包（unbundled）”复选框，列表显示是否随构建打包，允许修改已有设置与查看发布引用链。Python 工具包不显示此选项。
+
+add JSON 返回 `unbundled`、`previous_unbundled`、`included_in_release`。有效图包含 `purpose`（runtime/release）、`includes_unbundled`、节点 `unbundled`、`via` 和 `excluded`。节点布尔值由当前根项目的有效引用关系决定。
+
+## 传递与共享节点
+
+只有当前根项目的 unbundled 引用在运行图中启用。进入依赖项目后只跟随普通打包引用，不加载该依赖自己的 unbundled 辅助工具。
+
+```text
+P --false--> A --false--> C
+P --true---> B --false--> C
+                 +--false--> D
+A --true---> A-helper
+B --true---> B-helper
+```
+
+运行图为 A、B、C、D；发布图为 A、C。A-helper、B-helper 不自动启用。B 所需的 D 必须加载，“unbundled 不向消费者传递”不能被解释成 B 的正常子依赖也被排除。
+
+C 即使经不打包路径可达，也因为存在普通打包路径而进入发布。去重不能掩盖这条路径；预览必须解释它为什么仍会发布。相同源码但安装 target 不同，仍可成为不同安装节点。
+
+## 鲁棒性
+
+1. **先选择图。** 发布不读取未选中依赖的内容、校验其本地副本或发现其准备入口。未安装的 unbundled 路径和私有副本不阻塞发布；配置语法和锁拓扑仍需校验。
+2. **严格布尔值。** 拒绝 `"true"`、1、空值、错误字段与旧 scope 语法，不把输入错误当作 false。来源类型与打包标记独立；宿主 Python 包不使用此字段。
+3. **统一用途上下文。** 解析结果携带根项目与 runtime/release 用途，构建器拒绝复用错误项目或错误用途的 manager。准备、组装、部署和监控使用同一有效图。
+4. **Git 注册保留语义。** 同步时过滤上游自身 unbundled 引用；源码和安装节点身份不包含根引用上的标记。含新语义的锁用 v3，普通旧项目仍为 v2。
+5. **一份锁，按图恢复。** 运行图与发布图共享锁；部分恢复不删除、伪造或要求安装未选中的 unbundled 节点。build/package/run 不隐式联网、不更新版本。
+6. **防止残留和竞争。** build 完整替换输出，清理 dev 留下的不发布内容；dev 与 build 不能同时写同一目标。watcher 的增量和完整重建都保持运行图。package 独立组装。
+7. **保护正式模块。** unbundled 独占内容不能覆盖随发布的 Python 模块，已有代码 target 冲突规则继续生效；标记不改变现有资源合并和包身份规则。
+8. **限制有副作用的准备。** unbundled 独占依赖暂不支持 consumer_prepare；否则生成到主源码包的文件会绕过图筛选进入发布。未来支持需先提供输出归属、隔离和安全清理。根 hooks 的副作用仍需单独验收。
+9. **固定会话选择。** 热更沿用会话运行图，修改依赖或打包标记仍按生命周期重启。去掉依赖不会清除其写入世界的实体、方块和业务数据。
+10. **检查最终产物。** Python 动态导入无法全部静态验证。正式代码不能依赖被排除的模块，运行组装成功不代表 ZIP 已独立验收。

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

@@ -48,6 +48,8 @@ Windows 后台启动使用独立桌面包提供的进程内线程级 CBT 保护
 
 两端单人实例共用 cppconfig 的 world_info；存储、启动转换、保存优先级和创建参数见[实例世界设置](instance-world-settings.md)。
 
+Windows 本地双端的自动加入、运行映像端口定位、菜单控制与就绪契约见 [Windows 本地自动联机](windows-local-multiplayer.md)。该适配仅作用于本地客机，不改变其他平台或外服连接的协议。
+
 版本发现使用 `mcpy --local engine check-updates --json`：实时查询网易 pe/pe_old，返回真实完整版本和 URL；不得递增版本号或猜测 CDN 路径。该命令只检查，不下载或替换实例。新版本 compatibility=not_checked 需实际 APK 校验与结构兼容检查，不能把“发现版本”当作“可运行”。无需先执行此命令：首次 run 的自动安装已经查询 pe。已有本地版本/实例继续运行；缺失的旧版本若不在官方频道中则不可下载，不猜 CDN 路径。
 
 ## macOS 游戏图标

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/docs/git-dependencies.md

@@ -83,3 +83,11 @@ v2 锁使用相同的大小写敏感路径排序；源码由 Git archive 提取
 终端只显示同步进度、结果和必要操作；`mcpy sync --json` 返回结构化结果。`--migrate-windows-lock` 和 JSON 中始终为空的 `git_lock_migrations` 仅保留旧脚本兼容。团队各设备应使用包含此修复的版本，并提交 sync 更新后的锁文件。
 
 测试入口见[测试说明](../tests/README.md)。
+
+## 不随构建打包：unbundled
+
+通用 Git Addon/code 支持布尔标记 `unbundled`，默认 false。它属于依赖引用，不参与源码或安装节点身份计算。true 时仅随运行图加载；发布图排除该引用，但仍保留其他普通路径需要的共享节点。
+
+含新标记语义的锁使用 v3；旧项目继续使用 v2。默认 sync 恢复完整运行图，部分恢复只安装发布节点并保留其余锁记录；build/package 只校验有效节点。上游项目自身的 unbundled 引用不自动获取。旧 code_libraries 和生成业务入口的框架快捷依赖继续随发布。
+
+CLI、配置和预览用法统一见 [Skill 的 unbundled 指引](../skills/mcpywrap/references/project-dependencies.md#不随构建打包unbundled)。

{mcpywrap-0.6.2 → mcpywrap-0.6.4}/docs/local-dependencies.md

@@ -39,3 +39,11 @@ shared-addon/
 这不代表游戏运行时的资源包优先级。修改依赖声明后重启 `mcpy dev`。
 
 遇到结构错误先核对目录和清单；查看参数使用 `mcpy add --help`。
+
+## 不随构建打包的运行依赖
+
+本地引用可带布尔标记 `unbundled`，默认 false。true 时 dev/run 仍加载，build/package 在组装前排除；普通字符串引用保持旧行为。该依赖正常需要的子依赖随运行加载，上游自身的不打包引用不向消费者传递；被普通发布路径同时引用的共享节点仍随发布。
+
+发布不要求被排除的本地路径存在。更改标记后需重启会话；停止 dev 后 build 完整替换输出，package 独立组装。仅通过 unbundled 引用的依赖暂不支持 consumer_prepare，以防生成文件残留到源码包。
+
+CLI、配置示例和 JSON 判断方法统一见 [Skill 的 unbundled 指引](../skills/mcpywrap/references/project-dependencies.md#不随构建打包unbundled)。

mcpywrap-0.6.4/docs/windows-local-multiplayer.md

@@ -0,0 +1,29 @@
+# Windows 本地自动联机
+
+WindowsBackend 的本地组默认采用自动加入；用法以 [双客户端技能](../skills/mcpywrap/references/dual-clients.md) 为准。macOS、外服 connect 和远程执行协议不复用本适配层。旧组未记录 join_mode 时继续使用手动方式。
+
+## 端口与引擎兼容
+
+NetherNet 的主机监听可以从 7551 回退到临时端口，但默认发现不覆盖所有同机主机。工具在主机就绪后取得其网络身份，并核对所属进程唯一的 IPv6 通配 UDP 监听端口；多个候选会被拒绝，不将 Safaia、OreUI 或配置中的目标端口当作 LAN 监听端口。
+
+需要非默认端口时，`lan_locator` 使用运行映像的 PE x64 展开表确定函数边界，再反汇编匹配 TransportConfiguration 初始化：16 位端口字段、相邻广播周期、协议 magic 和对象传参必须同时成立，且候选必须唯一。不维护引擎版本/RVA 表，不复用另一个二进制的地址，也不将任意匹配到的 7551 字节视作指令。
+
+`lan_memory` 只操作 worker 刚创建的本地客机，核对 PID 创建时间及可执行文件身份。写入时暂停该进程，复核原指令，只更新端口立即数，读回校验并恢复原页属性、恢复线程。失败会结束本次客机；主机保留。磁盘游戏文件始终不改写，进程退出后适配消失。
+
+此识别方式已覆盖 3.9.0.350466、3.9.0.401155 和 3.10.0.436581。相同结构的新构建会自动定位；机器架构、配置结构或代码生成方式超出识别条件时必须失败，不保证任意未来引擎都无需算法更新。定位器的离线测试仅使用人工生成指令，不分发游戏代码、内存快照或修改后的游戏文件。
+
+## 自动加入与就绪
+
+Safaia 的普通脚本执行依赖进入世界后才初始化的游戏系统。自动客机在隔离角色资料中复用一个工具引导世界，待通道就绪后自动保存退出，再完成目标世界选择和资源下载。此阶段的物理 HUD 标记仅供内部通道就绪判断，不能向组发布 world_ready。
+
+菜单由会话所属窗口的后台 WGC 画面提供，Windows OCR 返回当前文字及物理坐标。选择目标采用主机玩家标识，拒绝截断、任意编辑距离或多个候选；只规范化已知像素字形混淆。输入前重新观察布局，限定一次动作并安排引擎内抬起；不移动系统鼠标，不抢前台。未知请求不重放，停滞、不可识别菜单或超时保留诊断并结束自动操作。
+
+只有客机进入目标网络 ID 和目标世界的 HUD，才发布 world_ready；随后原有 GroupMonitor 核对双方不同玩家与主机服务端名单，发布 connection_verified。自动加入期间，公共客机 Python/热更/输入请求被拒绝，组热更仍要求所有成员世界就绪。明确未发送的只读探针争用保留最近一次验证及原时间戳；真正观察到离开或身份不符会清除验证。
+
+worker 是 session.json 的唯一写入者；自动加入线程单独维护 local-join.json 与最近的 local-join-menu.json。状态包含 initializing、leaving_setup、finding_host、joining、joined、failed、cancelled。公共组响应增加 joining 状态，Qt、CLI、smoke 和重启流程共用它。停止会话或主机身份变化会取消自动操作，只清理所属进程。
+
+## 验证与维护
+
+菜单覆盖中文和英文，依赖 Windows 可用的 OCR 语言及持续渲染的游戏窗口；识别失败没有前台输入回退。引导世界每个角色至多一个，并与项目世界、真实账户资料隔离。组资源热更的现有限制不因自动加入而改变。
+
+维护入口为 [测试指南](../tests/README.md) 中的可选四端实机程序。应同时验证两个项目的 Mod 客户端/服务端系统加载、网络与世界隔离、客机重启、另一组保持连接以及停止清理；只观察窗口、进程存活或端口变化不足以确认联机成功。

mcpywrap-0.6.4/native/tracy_profiler/README.md

@@ -0,0 +1,52 @@
+# macOS 运行包内置 Tracy 分析器
+
+运行包 0.4.7 起包含本目录补丁。网易开发者版 `libminecraftpe.so` 内置 Tracy 客户端，按 `TRACY_MANUAL_LIFETIME` 构建。引擎在首次给线程命名时自行调用 `tracy::StartupProfiler()`，没有配置开关，因此运行包只需要提供正确的宿主接口，不需要也不应主动启动。启动器再调用一次 `___tracy_startup_profiler` 会产生第二个独立实例并占用下一个端口。
+
+## 旧运行包的问题
+
+Tracy 工作线程在监听前依次调用 `uname`、`gethostname`、`getlogin`、`sysinfo`。旧运行包中：
+
+- `uname` 直接透传 Darwin 实现，按 5×256 字节布局写入 Bionic 调用方的 390 字节缓冲，造成栈溢出，工作线程卡死。
+- `getlogin`、`sysinfo` 是 DeveloperCompat 终止桩，调用即以 53 结束进程。
+
+结果是 `___tracy_profiler_started` 为 1 但端口从不监听。socket 层本身可用，不需要改动。
+
+## 补丁
+
+- `libc-shim-host-info.patch`：新增独立的 `src/host_info.cpp`（不与 `common.cpp` 共享 Darwin `sys/param.h` 宏环境）。`uname` 按字段截断转换为 Bionic 6×65 布局；新增 `sysinfo`（Darwin 取自 sysctl、Mach 虚拟内存统计与 libproc，Linux 宿主逐字段复制，其他宿主返回 `ENOSYS`）；`getlogin` 使用宿主实现。均经过 errno 转换。
+- `client-tracy.patch`：DeveloperCompat 终止桩改为只填补 libc-shim 缺失的接口，已提供 ABI 转换的实现不再被覆盖；加载游戏库前默认设置 `TRACY_ONLY_LOCALHOST=1`、`TRACY_ONLY_IPV4=1`，已存在的环境变量优先。
+- `manifest-tracy.patch`：`tests/libc_host_info.cpp` 以保护区校验三个接口不越界写入并返回有效值，纳入构建脚本的 CTest。
+- `apply.py`：三份补丁全部预检后才应用，已应用项跳过，失败回滚；不下载、构建或启动游戏。
+
+修复按符号进行，不含游戏版本相关的地址或偏移；新 APK 只要通过标准 libc 导入调用这些接口即可直接受益。
+
+核对基线：manifest `8b624579618a121c345dd4ff05748d426a0141fa`，client `350eb36f499fbb4bc2bcaf413bd7b2fefa1fb782`，libc-shim `8ca149814eba0c42fa0c1f945b76fb526f6f0694`。可与 [后台窗口补丁](../background_window/README.md) 同时应用，两者不修改相同的位置。
+
+## 构建
+
+源码准备与 [后台窗口补丁](../background_window/README.md#在-mac-构建测试包) 相同，额外执行：
+
+```sh
+python3 native/tracy_profiler/apply.py --manifest /path/to/runtime-source
+```
+
+然后用 `tools/build_macos_runtime.py` 构建新的运行包。Xcode SDK 升级后，旧 CMake 构建目录可能仍引用已删除的 SDK 路径，此时使用新的 `--build-dir`。
+
+## 连接与安全
+
+- 默认监听 `127.0.0.1:8086`；端口被占用时顺延到 8087–8105（例如多个本地实例）。
+- 需要从其他设备连接时，显式以 `TRACY_ONLY_LOCALHOST=0 TRACY_ONLY_IPV4=0` 启动；这会对所有网卡开放分析端口并发送 UDP 发现广播，只在可信网络使用。
+- viewer 版本必须与游戏内置 Tracy 的协议一致，协议随游戏版本变化。`probe.py` 是可选手动工具，列出本机端点及其协议号：
+
+```sh
+python3 native/tracy_profiler/probe.py
+```
+
+开发者包 3.9.100.297020 内置 Tracy 0.11.1，协议 69。
+
+## Mac 验收
+
+1. 用新运行包创建独立实例，确认引擎日志中没有 `Unimplemented Android interface`。
+2. `lsof -nP -a -p <pid> -iTCP -sTCP:LISTEN` 只出现 `127.0.0.1:8086`（单实例）。
+3. `probe.py` 返回 `status=welcome` 及协议号；用对应版本的 Tracy viewer 连接 `127.0.0.1` 并看到帧与区段数据。
+4. 以 `TRACY_ONLY_LOCALHOST=0` 启动时监听地址变为通配地址，未设置时不会出现。

mcpywrap-0.6.4/native/tracy_profiler/apply.py

@@ -0,0 +1,41 @@
+"""Apply the Tracy host-interface 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/'libc-shim', patches/'libc-shim-host-info.patch'),
+               (root/'mcpelauncher-client', patches/'client-tracy.patch'),
+               (root, patches/'manifest-tracy.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.4/native/tracy_profiler/client-tracy.patch

@@ -0,0 +1,41 @@
+diff --git a/src/developer_compat.h b/src/developer_compat.h
+index aa4b983..d4a7c2d 100644
+--- a/src/developer_compat.h
++++ b/src/developer_compat.h
+@@ -57,9 +57,10 @@ inline void addLibCBindings(std::unordered_map<std::string, void*>& libC) {
+     // Deliberately terminating diagnostic bindings, not API emulation.
+     // These allow relocation to proceed without silently accepting calls
+     // for which Bionic/Darwin structures or semantics differ.
+-#define UNIMPLEMENTED_ANDROID(name) libC[#name] = (void*)+[]() { \
++    // libc-shim 已提供 ABI 转换的接口优先，终止桩只填补缺口。
++#define UNIMPLEMENTED_ANDROID(name) libC.emplace(#name, (void*)+[]() { \
+         Log::error("DeveloperCompat", "Unimplemented Android interface: " #name); \
+-        std::fflush(nullptr); _Exit(53); };
++        std::fflush(nullptr); _Exit(53); });
+     UNIMPLEMENTED_ANDROID(__libc_current_sigrtmin)
+     UNIMPLEMENTED_ANDROID(__libc_current_sigrtmax)
+     UNIMPLEMENTED_ANDROID(ttyname)
+@@ -68,8 +69,6 @@ inline void addLibCBindings(std::unordered_map<std::string, void*>& libC) {
+     UNIMPLEMENTED_ANDROID(getservbyport)
+     UNIMPLEMENTED_ANDROID(getprotobyname)
+     UNIMPLEMENTED_ANDROID(__get_h_errno)
+-    UNIMPLEMENTED_ANDROID(getlogin)
+-    UNIMPLEMENTED_ANDROID(sysinfo)
+ #undef UNIMPLEMENTED_ANDROID
+     libC["pthread_sigmask"] = (void*)+[](int, const void*, void*) -> int {
+         Log::error("DeveloperCompat", "Unimplemented Android interface: pthread_sigmask");
+diff --git a/src/main.cpp b/src/main.cpp
+index 525cf9d..130cea8 100644
+--- a/src/main.cpp
++++ b/src/main.cpp
+@@ -438,6 +438,10 @@ Hardware	: Qualcomm Technologies, Inc MSM8998
+     for(auto&& redir : shim::rewrite_filesystem_access) {
+         Log::trace("REDIRECT", "%s to %s", redir.first.data(), redir.second.data());
+     }
++    // 游戏内置的 Tracy 会在首次线程命名时自行启动；默认只监听本机 IPv4，
++    // 避免对局域网开放分析端口。显式设置的环境变量优先。
++    setenv("TRACY_ONLY_LOCALHOST", "1", 0);
++    setenv("TRACY_ONLY_IPV4", "1", 0);
+     auto libC = MinecraftUtils::getLibCSymbols();
+     ThreadMover::hookLibC(libC);
+     if(extendedBindings)