mcpywrap 0.4.2__tar.gz → 0.4.3__tar.gz

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 更新记录
 
+## 0.4.3
+
+- macOS 新增无认证服务器连接，复用 `mcpy connect` 与项目 `[tool.mcpywrap.server]` 的 `run` 入口、cppconfig、日志、偏好和退出机制，不装配本地 Mod 或创建本地世界实例。
+- 配套 macOS 运行包 0.4.3 使用现有引擎 Python 入口进服，无新增游戏二进制补丁；首次安装自动取得配套运行包，旧包给出明确升级命令，保留已有世界绑定。
+- 网络会话仅开放客户端 Python；在 worker 中拒绝服务端 Python 和本地 Mod 热更。macOS 初次连接超时会提示失败并回收游戏，进入 HUD 后记录连接验证结果。
+- Skill 补充离线服务器条件、旧运行包升级、状态验证及客户端调试边界。已在 macOS 26.6.2 / APK 3.10.100.299889 上通过本机 Nemisys + SynapseAPI + Nukkit 验证 connect、项目 run、Python 与失败清理；不包含 MCS/MPay 登录、外部 HTTP 资源包或新版统一输入的验收。
+
 ## 0.4.2
 
 - 新增统一 `runtime input capabilities/observe/run/status/cancel/stop` 与 `mcpy.input`。键盘组合、独立边沿、玩家与单节点 UI 操作共用 JSON steps、动作注册表、排时和清理；单次 key 快捷命令只生成同一份计划。

{mcpywrap-0.4.2/mcpywrap.egg-info → mcpywrap-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.4.2
+Version: 0.4.3
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/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 世界，不支持 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。macOS 不支持 Map、MCS 登录或 Windows 桌面截图/键鼠/录像；需要这些能力时显式使用 Windows 远程端。最低 macOS 13.0，实际游戏只在 26.6.2 验证。运行包尚为 ad-hoc 签名、公证待完成。
 
 图形界面的会话操作集中在 ui/session_controller.py；主界面和小窗仅使用共用 SessionControls/PythonConsole 与 LogView。小窗不再另起 Studio TCP 接收器，详见 [共用日志界面](shared-log-ui.md)。
 

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/__init__.py

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

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/commands/connect_cmd.py

@@ -22,5 +22,14 @@ def connect_cmd(host, port, mcs_auth=False, detach=False, request_id=None, **eng
     if request_id:
         raise click.UsageError('--request-id 仅用于远程启动')
     from ..engines.backend import get_backend
-    return get_backend().connect(ServerTarget(host, port, 'mcs' if mcs_auth else 'none'),
-                                 engine_overrides=engine_overrides, detach=detach)
+    from ..engines.host import EngineError
+    backend = get_backend()
+    target = ServerTarget(host, port, 'mcs' if mcs_auth else 'none')
+    try:
+        return backend.connect(target, engine_overrides=engine_overrides, detach=detach)
+    except EngineError as error:
+        if error.code != 'setup_required' or not backend.managed_install: raise
+        from .engine_cmd import perform_install
+        click.echo('首次运行：自动下载并准备本地游戏环境…', err=True)
+        perform_install()
+        return backend.connect(target, engine_overrides=engine_overrides, detach=detach)

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/engines/install.py

@@ -24,7 +24,7 @@ from .host import EngineError, describe, require_macos
 
 CATALOG_ENV = 'MCPY_RUNTIME_CATALOG'
 DEFAULT_CATALOG = ('https://github.com/EaseCation/mcpelauncher-manifest/releases/download/'
-                   'mcpy-runtime-v0.4.0/catalog.json')
+                   'mcpy-runtime-v0.4.3/catalog.json')
 # Public constant from the official ApkDownload component, verified 2026-10-05.
 # https://mcdev.webapp.163.com/static/js/4.05713153ba17aea6db53.js
 CDN_CONSTANT = 'mEE7Cot48r9j2AvEL2N6jpXEc'

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/engines/macos.py

@@ -65,7 +65,8 @@ def pinned_runtime(item):
     install.verify_game(game, plan['profile'])
     compatibility = install.preflight_runtime(app, game, plan['profile'], meta, plan['runtime_id'])
     return {'runtime': str(app), 'game': str(game), 'profile': plan['profile'], 'runtime_id': plan['runtime_id'],
-            'compat_report': compatibility, 'cppconfig_protocol': meta.get('cppconfig_protocol')}
+            'compat_report': compatibility, 'cppconfig_protocol': meta.get('cppconfig_protocol'),
+            'network_connect_protocol': meta.get('network_connect_protocol')}
 
 
 def run(project, *, new=False, listing=False, delete=None, clean_all=False, force=False,
@@ -85,9 +86,15 @@ def run(project, *, new=False, listing=False, delete=None, clean_all=False, forc
         raise EngineError('MC Studio 身份、EXE 和下载目录参数仅适用于 Windows。', 'unsupported_option',
                           'macOS 当前使用开发者 APK 的离线模式；资源由 mcpy engine 管理。')
     config = read_project(project)
-    if config.get('tool', {}).get('mcpywrap', {}).get('server'):
-        raise EngineError('macOS 本地后端当前只支持离线世界。', 'unsupported_feature',
-                          '连接服务器请配置 --remote <Windows 服务地址>。')
+    if not (listing or delete or clean_all):
+        from ..mcstudio.network import configured_target, prepare_project
+        target = configured_target(config)
+        if target is not None:
+            if new or instance_prefix or world_config is not None:
+                raise click.UsageError('网络模式不支持 --new 或本地世界实例 ID')
+            packs = prepare_project(project, config)
+            from .macos_network import connect
+            return connect(target, project_dir=project, packs=packs, engine_overrides=overrides, detach=detach)
     if config.get('tool', {}).get('mcpywrap', {}).get('project_type', 'addon') != 'addon':
         raise EngineError('macOS 首版支持 Addon 测试，Map 项目尚未接入。', 'unsupported_feature',
                           '地图项目请在 Windows 本机运行。')
@@ -192,6 +199,13 @@ def run(project, *, new=False, listing=False, delete=None, clean_all=False, forc
 
 def launch_session(data):
     plan = data['launch']
+    if data.get('mode') == 'network':
+        from types import SimpleNamespace
+        from ..mcstudio.network import ServerTarget, unauthenticated_config
+        config = unauthenticated_config(
+            SimpleNamespace(version=plan['engine_version'], download_dir=plan['game']),
+            ServerTarget(**data['network']['target']))
+        install.write_json(Path(plan['cppconfig']), config)
     app = Path(plan['runtime'])
     helper = app/'Contents/Resources/launcher/run_netease_dev.py'
     if not helper.is_file():
@@ -228,7 +242,7 @@ class MacOSBackend(GameBackend):
     label = 'macOS · Apple Silicon · Metal'
     capabilities = ('local-worlds', 'macos-local-worlds', 'engine-install', 'macos-engine-install',
                     'status', 'logs', 'stop', 'py', 'runtime', 'runtime-ui', 'runtime-player',
-                    'client-python-requests', 'project-ui', 'reload', 'watch')
+                    'client-python-requests', 'project-ui', 'reload', 'watch', 'network-sessions')
     managed_install = True
     setup_description = ('在 Apple Silicon Mac 上运行本地 Addon 测试。\n'
                          '首次运行会自动下载原生启动器和网易开发者版资源，并在本机完成安装。\n'
@@ -250,6 +264,10 @@ class MacOSBackend(GameBackend):
         options.pop('no_gui', None)
         return run(project, **options)
 
+    def connect(self, target, **options):
+        from .macos_network import connect
+        return connect(target, **options)
+
     def watch_directory(self, project, data):
         return Path(data['config_path']).parent/'assembled'
 
@@ -380,7 +398,9 @@ else:
                 request_id = 'startup-' + str(index)
                 result = channel._rpc('result', {'request_id': request_id})
                 if result.get('request_id') == request_id and result.get('state') in ('failed', 'cancelled'):
-                    raise EngineError('世界启动步骤失败：' + str(result.get('error', result['state'])), 'world_start_failed')
+                    raise EngineError(('服务器连接未完成：' if data.get('mode') == 'network' else '世界启动步骤失败：')
+                                      + str(result.get('error', result['state'])),
+                                      'connection_failed' if data.get('mode') == 'network' else 'world_start_failed')
         except (OSError, ConnectionError):
             pass
         try:
@@ -389,9 +409,13 @@ else:
                 stream.seek(max(0, stream.tell() - 65536))
                 if b'"top_screen":"hud_screen"' in stream.read():
                     data['world_ready'] = True
+                    if data.get('mode') == 'network': data['connection_verified'] = True
                     return True
         except OSError:
             pass
+        if data.get('mode') == 'network' and time.time() - data['created_at'] > 90:
+            raise EngineError('90 秒内未进入服务器；请检查地址、端口、协议版本以及服务器是否允许无认证的中国版客户端。',
+                              'connection_timeout')
         return False
 
     def handoff(self, data):

mcpywrap-0.4.3/mcpywrap/engines/macos_network.py

@@ -0,0 +1,47 @@
+"""Anonymous server launch using the shared cppconfig and session lifecycle."""
+from dataclasses import asdict
+from pathlib import Path
+import uuid
+
+import click
+from . import install
+from .host import EngineError, require_macos
+
+
+def connect(target, *, project_dir=None, packs=(), engine_overrides=None, detach=False):
+    from ..command_context import project_dir as current_project, json_output
+    from ..mcstudio import sessions
+    from ..remote.service import directory_lock
+    from .macos import ensure_runtime, pinned_runtime
+    require_macos()
+    if json_output() and not detach:
+        raise click.UsageError('网络运行 --json 需要 --detach；使用 status/logs/stop 管理返回的会话')
+    overrides = engine_overrides or {}
+    if target.auth != 'none' or overrides.get('game_executable_path') or overrides.get('mcs_download_path'):
+        raise EngineError('macOS 服务器连接仅支持无认证模式；MC Studio 身份和 EXE 参数仅适用于 Windows。',
+                          'unsupported_option')
+    root = Path(project_dir or current_project()).resolve()
+    with directory_lock(install.home()/'install-lock'):
+        state = pinned_runtime({'installation': ensure_runtime()})
+        if state.get('network_connect_protocol') != 1:
+            raise EngineError('此 macOS 运行包尚不支持连接服务器。', 'runtime_incompatible',
+                              '请执行 mcpy engine install --catalog ' + install.DEFAULT_CATALOG + '，再重试；已有世界保留原绑定。')
+        version = state['profile']['apk']['version']
+        requested = overrides.get('engine_version')
+        if requested and requested != version:
+            raise EngineError('当前资源版本为 ' + version, 'engine_version_mismatch',
+                              '请使用匹配的资源，或省略 --engine-version。')
+        session = uuid.uuid4().hex
+        directory = sessions.session_path(root, session)
+        plan = {'runtime': state['runtime'], 'game': state['game'],
+                'data': str(directory/'native/data'), 'cache': str(directory/'native/cache'),
+                'engine_version': version, 'compat_report': state.get('compat_report'),
+                'cppconfig': str(directory/'runtime.cppconfig')}
+        data = sessions.start(root, backend='macos-arm64', session_id=session, launch=plan,
+                              network={'target': asdict(target), 'engine': {'version': version}})
+    result = sessions.handoff(data)
+    if detach:
+        return result
+    click.echo(f'连接 {target.host}:{target.port}（无认证）；不装配本地 Mod。')
+    from .tui import watch_session
+    return watch_session(root, session)

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/engines/tui.py

@@ -19,10 +19,12 @@ def watch_session(project, session):
                 backend = get_backend(data.get('backend', 'windows'))
                 table = Table.grid(padding=(0, 2))
                 table.add_row('平台', backend.label)
-                table.add_row('状态', '世界已就绪' if data.get('world_ready') else '引擎已启动，正在准备世界…')
+                network = data.get('mode') == 'network'
+                table.add_row('状态', ('已进入服务器' if data.get('connection_verified') else '正在连接服务器…')
+                              if network else ('世界已就绪' if data.get('world_ready') else '引擎已启动，正在准备世界…'))
                 table.add_row('会话', session)
                 table.add_row('操作', 'Ctrl+C 保存退出；其他终端可使用 logs / runtime py')
-                live.update(Panel(table, title='mcpy 本地测试'))
+                live.update(Panel(table, title='mcpy 服务器测试' if network else 'mcpy 本地测试'))
                 time.sleep(.25)
     except KeyboardInterrupt:
         console.print('正在保存世界并关闭窗口…')

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/mcstudio/bridge_payload/manifest.json

@@ -11,9 +11,9 @@
     "Loader.c": "f2f1f781ce82fc30c62a6ce22bb048d3b023f6ff500e6ec8228da28b4dbf1b4a"
   },
   "files": {
-    "Injector.exe": "d63c7fcf4061bad6381c14a3f60c7ad78e99e71536dcc82c81fc9e259bea6c53",
-    "Loader.dll": "4e5cdb48778866c66da75b9a560b9513624c1b8cf3b2c6b0e52c5c3145eac91a",
-    "McpyMcsAuth.dll": "30a7a1bf74c7a049e145442baf94870072033d726d83449c7c8a1b9e29438c04",
+    "Injector.exe": "376bbefafdab254e413e6a6d9cb1b880e1e94fd259bae55c8a882e17a383892e",
+    "Loader.dll": "a4f4da0a3d65dfd94802ac2dd30e5edea81d34659df451c961de15e44a87f6ac",
+    "McpyMcsAuth.dll": "c5f105f2e8bd821aa8a0bc1435cc42bac2ca690343a63f8c773eb593971a5ffb",
     "publisher.cer": "e5aa2ac39df40804ed8b08fe8e43c4a2b8923f0d02a360708486b2db5b6303d7"
   }
 }

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/mcstudio/runtime_debug.py

@@ -314,6 +314,8 @@ class _ControlHandler(socketserver.BaseRequestHandler):
             request = json.loads(recv_exact(self.request, size).decode('utf-8'))
             if request.get('token') != self.server.token:
                 raise ValueError('会话控制凭据无效')
+            if self.server.mode == 'network' and (request.get('side', 'client') != 'client' or request.get('action') == 'reload'):
+                raise ValueError('网络会话仅支持客户端调试，不支持服务端 Python 或本地 Mod 热更')
             if request.get('action') == 'execute':
                 options = {'condition': request['condition']} if request.get('condition') is not None else {}
                 if options and not hasattr(self.server.channel, 'submit'):
@@ -357,8 +359,8 @@ class RuntimeControlServer(socketserver.ThreadingTCPServer):
     daemon_threads = True
     allow_reuse_address = True
 
-    def __init__(self, channel, token, project=None, session=None):
-        self.channel, self.token = channel, token
+    def __init__(self, channel, token, project=None, session=None, mode='local'):
+        self.channel, self.token, self.mode = channel, token, mode
         self.input_manager = None
         if project is not None and session is not None:
             from .host_input import HostInputManager

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/mcstudio/session_worker.py

@@ -57,12 +57,12 @@ def run(project, session):
         debug_channel = backend.debug_channel(data, receiver._write)
         debug_channel.start(process.pid)
         token = uuid.uuid4().hex
-        control_server = RuntimeControlServer(debug_channel, token, project, session)
+        control_server = RuntimeControlServer(debug_channel, token, project, session, mode=data.get('mode', 'local'))
         control_server.start()
         sessions.save(directory/'control.json', {'port': control_server.server_address[1],
                                                  'token': token,
                                                  'unified_input_worker': True,
-                                                 'python_reload_sides': ['client', 'server'],
+                                                 'python_reload_sides': [] if data.get('mode') == 'network' else ['client', 'server'],
                                                  'client_python_queue': callable(getattr(debug_channel, 'submit', None))})
         data.update(state='running', game=identity(process.pid))
         sessions.save(path, data)

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/mcstudio/sessions.py

@@ -114,7 +114,7 @@ def handoff(data):
         target = data['network']['target']
         result.update(host=target['host'], port=target['port'], identity_source=target['auth'],
                       identity_provided=data['mcs_auth'], authenticated=False,
-                      connection_verified=False, addons_assembled=False,
+                      connection_verified=data.get('connection_verified', False), addons_assembled=False,
                       engine_version=data['network']['engine']['version'])
     return result
 

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap/mcstudio/window_capture/manifest.json

@@ -1,5 +1,5 @@
 {
-  "executable_sha256": "2a37e9282aac2a242169be0f5ac499aabf443aacff2c7aa92867d9570552089d",
+  "executable_sha256": "81642e2d7c9c5097cd86b139f41f75a6f3ca12cb5b2bddbc0427cb2aee92bb64",
   "source_sha256": "0c0b2a02bfecea68b824a486ac1d88cde6bd9fc8ee8e4c9a6939870bd8e710d1",
   "sources": {
     "video_capture.h": "8daee1b8c1c8273bc8d19d39f0559f82c30d7ff900894bcc2cc197d3881532d7",

{mcpywrap-0.4.2 → mcpywrap-0.4.3/mcpywrap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.4.2
+Version: 0.4.3
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/mcpywrap.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ mcpywrap/engines/backend.py
 mcpywrap/engines/host.py
 mcpywrap/engines/install.py
 mcpywrap/engines/macos.py
+mcpywrap/engines/macos_network.py
 mcpywrap/engines/official.py
 mcpywrap/engines/preferences.py
 mcpywrap/engines/tui.py
@@ -229,6 +230,7 @@ tests/test_launch_encoding.py
 tests/test_launcher_python.py
 tests/test_local_auth_session.py
 tests/test_local_dependencies.py
+tests/test_macos_network.py
 tests/test_manual_runtime_controls.py
 tests/test_mcs_auth.py
 tests/test_mouse.py

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcpywrap"
-version = "0.4.2"
+version = "0.4.3"
 description = "A wrapper for Minecraft China Edition Addons management"
 readme = "README.md"
 authors = [{name = "boybook", email = "boybook@easecation.net"}]

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/skills/mcpywrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcpywrap
-description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图、依赖和 QuMod，并在 Windows 本机/远程或 Apple Silicon macOS 本地离线会话中调试、读取 UI 节点和操控玩家；桌面截图/输入/录制仅 Windows。注入的 mcpy.* 仅限调试，禁止用于业务代码。
+description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图、依赖和 QuMod，并在 Windows 本机/远程或 Apple Silicon macOS 本地世界及无认证联机会话中调试、读取 UI 节点和操控玩家；桌面截图/输入/录制仅 Windows。注入的 mcpy.* 仅限调试，禁止用于业务代码。
 ---
 
 # mcpywrap
@@ -107,9 +107,12 @@ Windows 用户在专用、已登录未锁屏的桌面设置 `MCPY_REMOTE_TOKEN`
 | 目标 | 启动命令 |
 |---|---|
 | Windows/macOS 本地 Addon 世界（先准备资源） | `mcpy --local --project "<项目>" --non-interactive run --no-gui --detach --json` |
+| Windows/macOS 本机临时服务器 | `mcpy --local --project "<会话目录>" --non-interactive connect <游戏服务器地址> --port 19132 --detach --json` |
 | 远程临时服务器 | `mcpy --remote <Windows服务地址> --non-interactive connect <游戏服务器地址> --port 19132 --detach --json` |
 | 远程项目目标 | `mcpy --remote <地址> --project "<调用端项目>" --non-interactive run --detach --json` |
 
+macOS 联机要求 CLI 0.4.3+ 和运行包 0.4.3+（声明 `network_connect_protocol=1`）；仅支持允许无认证中国版客户端的服务器。旧 0.4.0 运行包不具备此能力，更新 Skill 或 CLI 不等于运行包升级。具体检查见 [macOS 本地测试](references/macos-local.md)。
+
 固定游戏目标在项目 `[tool.mcpywrap.server]` 填 `host/port`。连接不装配本地 Mod，网络模式不支持 Map、`--new` 或世界实例 ID。
 远程机器路径只在 Windows serve 参数中配置，客户端仅可覆盖 `--engine-version`；本机 connect 可使用原有引擎覆盖参数。
 `MCPY_REMOTE_TOKEN` 是服务默认要求的访问令牌；可信网络可显式用 `mcpy --local serve --no-token` 关闭认证，此时忽略已有令牌，可访问该端口的设备均可执行游戏客户端 Python。先检查 `serve --help` 是否支持该参数。`--mcs-auth` 才是本次游戏的 MCS 登录身份，二者互不替代。仅用户要求登录身份时添加该选项。

{mcpywrap-0.4.2 → mcpywrap-0.4.3}/skills/mcpywrap/references/macos-local.md

@@ -24,7 +24,7 @@ mcpy --local --project <项目> stop --session <sid> --json
 
 客户端使用 launcher-jni，启动期间可以 --no-wait 提交并用 runtime py-result 按 request_id 查询；--wait-until 是无副作用的客户端 Python 就绪表达式。超时先查原请求，勿重复提交有副作用代码。服务端仍走原有 Safaia，仅进入世界后可用，不给服务端加客户端队列参数。runtime install/ui/player 继续通过公共客户端通道工作；注入的 mcpy.* 仍严格仅用于临时调试。
 
-暂不支持本地 Map、联机服务器、MCS 身份、MCEditor 及 Windows screenshot/key/mouse/input-sequence/record。需要它们时使用显式 Windows --remote，不静默回退或尝试登录。macOS 前台 run 的 Ctrl+C 请求保存退出；一次性测试结束必须 stop 并确认进程退出，关闭自己创建的窗口。
+暂不支持本地 Map、MCS 身份、MCEditor 及 Windows screenshot/key/mouse/input-sequence/record。需要它们时使用显式 Windows --remote，不静默回退或尝试登录。macOS 前台 run 的 Ctrl+C 请求保存退出；一次性测试结束必须 stop 并确认进程退出，关闭自己创建的窗口。
 
 最低版本为 macOS 13.0，游戏实测仅 26.6.2；包目前 ad-hoc 签名，未公证，不宣称已验证最低系统或 Gatekeeper。失败时提供实际错误及日志，不能建议全局关闭系统保护。
 
@@ -44,3 +44,28 @@ Windows 与 macOS 共用 PySide6 界面：人工使用 `mcpy --local --project <
 FPS/VSync、画质、GUI 缩放、音量和输入偏好由 mcpy worker 按用户保存并在新会话导入，位置是引擎资源根目录下的 `preferences/macos`。这些不是 cppconfig 世界设置；不要为每个新实例重新配置。运行中的其他实例不会即时跟随，重开时读取最新值；先正常保存退出以确保游戏完成原生配置写入。
 
 版本发现使用 `mcpy --local engine check-updates --json`：实时查询网易 pe/pe_old，返回真实完整版本和 URL；不得递增版本号或猜测 CDN 路径。该命令只检查，不下载或替换实例。新版本 compatibility=not_checked 需实际 APK 校验与结构兼容检查，不能把“发现版本”当作“可运行”。无需先执行此命令：首次 run 的自动安装已经查询 pe。已有本地版本/实例继续运行；缺失的旧版本若不在官方频道中则不可下载，不猜 CDN 路径。
+
+## 无认证服务器连接
+
+已安装旧运行包时，先正常结束自己的会话，再升级资源并重新 connect：
+
+```sh
+mcpy --local engine install --catalog https://github.com/EaseCation/mcpelauncher-manifest/releases/download/mcpy-runtime-v0.4.3/catalog.json
+```
+
+此命令仍通过网易 pe 发现当前 APK；保留旧资源和原世界绑定。connect 使用当前已选资源，旧单人实例继续使用原运行包。
+
+需要 CLI 0.4.3+ 和原生运行包 0.4.3+（声明 `network_connect_protocol=1`）。首次安装使用配套运行包；旧 0.4.0 运行包需要显式升级，更新 CLI 不会替换已有世界的绑定。`doctor --capabilities` 的 network-sessions 表示后端入口，实际 connect 还会核对运行包；旧包返回 runtime_incompatible，不切换到单人世界。
+
+```sh
+mcpy --local --project <已有会话目录> --non-interactive connect 127.0.0.1 --port 19132 --detach --json
+mcpy --local --project <同一目录> status --session <sid> --json
+mcpy --local --project <同一目录> runtime py --session <sid> --side client --code "print('network client')" --json
+mcpy --local --project <同一目录> stop --session <sid> --json
+```
+
+connect 不读取项目配置；固定目标可以在项目 `[tool.mcpywrap.server]` 中设置 host/port，再使用同一套 `run --no-gui --detach --json`。网络会话不会创建世界实例或装配本地 Mod；不能组合 --new/实例 ID/世界选项。每次连接独立保存数据和日志，共享用户画面及输入偏好。
+
+`running` 仅表示进程已启动。macOS `connection_verified=true` 表示此会话曾观察到进入 HUD，并非持续在线探活，也不表示已通过身份认证；需要当前状态时用客户端 Python/日志验证。90 秒未进入 HUD 会失败并关闭本次游戏。失败后检查 logs --source engine/worker、服务端日志、协议版本及离线配置，不尝试账号登录。
+
+仅支持客户端 Python 与 runtime install；游戏内输入另查当前会话 capabilities（旧 C++ 运行包可能缺少统一输入所需的单调时钟），不因注入成功就断言输入可用。服务端 Python 与本地 Mod 热更禁用，服务端逻辑仍由服务器管理。3.10.100.299889 已用本机 Nemisys + SynapseAPI + Nukkit 验证无认证进服；测试端须关闭 Nemisys xbox-auth 并按 SynapseAPI 的调试开关强制 NetEase 玩家。不能推断公开服务器或其他版本一定接受连接。当前网络策略允许目标 UDP 端口和 DNS，不包含外部 HTTP 资源包下载；需要这种资源分发的服务器尚未验收。

mcpywrap-0.4.3/tests/test_macos_network.py

@@ -0,0 +1,120 @@
+"""macOS network entry points preserve common sessions and reject unsupported modes."""
+import json
+from pathlib import Path
+import tempfile
+import time
+import unittest
+from unittest.mock import Mock, patch
+from click.testing import CliRunner
+
+from mcpywrap.cli import cli
+from mcpywrap.engines.macos import MacOSBackend
+from mcpywrap.engines.host import EngineError
+from mcpywrap.mcstudio import sessions
+from mcpywrap.mcstudio.network import ServerTarget
+
+
+class MacOSNetworkTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name).resolve()
+        self.backend = MacOSBackend()
+        self.state = {'runtime': str(self.root/'runtime'), 'game': str(self.root/'game'),
+                      'profile': {'apk': {'version': '3.10'}}, 'network_connect_protocol': 1}
+        for name, value in [('mcpywrap.engines.backend.get_backend', self.backend),
+                            ('mcpywrap.engines.macos.require_macos', {}),
+                            ('mcpywrap.engines.macos_network.require_macos', {}),
+                            ('mcpywrap.engines.macos.ensure_runtime', self.state),
+                            ('mcpywrap.engines.macos.pinned_runtime', self.state),
+                            ('mcpywrap.engines.install.home', self.root/'resources')]:
+            obj = patch(name, return_value=value); obj.start(); self.addCleanup(obj.stop)
+        obj = patch.object(sessions, 'start', side_effect=self.start)
+        self.start_mock = obj.start(); self.addCleanup(obj.stop)
+
+    def start(self, root, **options):
+        return {'session': options['session_id'], 'project': str(root), 'state': 'running',
+                'game': {'pid': 123}, 'log_path': 'game.log', 'engine_log_path': 'engine.log',
+                'level_id': None, 'mode': 'network', 'mcs_auth': False, **options}
+
+    def call(self, *args):
+        return CliRunner().invoke(cli, ['--local', '--project', str(self.root), '--non-interactive', *args, '--json'])
+
+    def test_connect_does_not_read_project_or_create_world(self):
+        (self.root/'pyproject.toml').write_text('broken = [')
+        result = self.call('connect', 'localhost', '--port', '29132', '--detach')
+        self.assertEqual(result.exit_code, 0, result.output)
+        data = json.loads(result.stdout)
+        self.assertEqual((data['mode'], data['host'], data['port']), ('network', 'localhost', 29132))
+        self.assertFalse(data['connection_verified'])
+        self.assertFalse(data['addons_assembled'])
+        self.assertFalse((self.root/'.runtime/macos/instances').exists())
+        self.assertIn(data['session'], self.start_mock.call_args.kwargs['launch']['data'])
+
+    def test_old_runtime_rejected_before_start(self):
+        self.state.pop('network_connect_protocol')
+        result = self.call('connect', 'localhost', '--detach')
+        self.assertEqual(json.loads(result.stdout)['code'], 'runtime_incompatible')
+        self.start_mock.assert_not_called()
+
+    def test_auth_and_version_rejected(self):
+        for args, code in [(['--mcs-auth'], 'unsupported_option'), (['--engine-version', 'wrong'], 'engine_version_mismatch')]:
+            result = self.call('connect', 'localhost', '--detach', *args)
+            self.assertEqual(json.loads(result.stdout)['code'], code)
+        self.start_mock.assert_not_called()
+
+    def test_json_requires_detach(self):
+        result = self.call('connect', 'localhost')
+        self.assertEqual(result.exit_code, 2)
+        self.start_mock.assert_not_called()
+
+    def test_configured_run_and_world_flags(self):
+        (self.root/'pyproject.toml').write_text('[project]\nname="network-test"\nversion="0.0.0"\n[tool.mcpywrap.server]\nhost="localhost"\nport=29132\n')
+        with patch('mcpywrap.mcstudio.network.prepare_project', return_value=[]):
+            result = self.call('run', '--no-gui', '--detach')
+            self.assertEqual(result.exit_code, 0, result.output)
+            self.assertEqual(json.loads(result.stdout)['mode'], 'network')
+            self.start_mock.reset_mock()
+            result = self.call('run', '--new', '--detach')
+            self.assertEqual(result.exit_code, 2, result.output)
+            self.start_mock.assert_not_called()
+            result = self.call('run', '--list')
+            self.assertEqual(json.loads(result.stdout)['instances'], [])
+
+    def test_connect_installs_missing_resources_once(self):
+        with patch('mcpywrap.engines.macos.ensure_runtime', side_effect=[EngineError('missing', 'setup_required'), self.state]), \
+                patch('mcpywrap.commands.engine_cmd.perform_install') as install:
+            result = self.call('connect', 'localhost', '--detach')
+        self.assertEqual(result.exit_code, 0, result.output)
+        install.assert_called_once()
+
+    def test_ready_requires_hud_and_failure_times_out(self):
+        log = self.root/'engine.log'; log.write_text('connecting')
+        data = {'mode': 'network', 'engine_log_path': str(log), 'created_at': time.time()-91}
+        with self.assertRaises(EngineError) as error:
+            self.backend.refresh(data, Mock())
+        self.assertEqual(error.exception.code, 'connection_timeout')
+        self.assertFalse(data.get('connection_verified'))
+        self.backend._next_probe = 0
+        log.write_text('{"top_screen":"hud_screen"}')
+        self.assertTrue(self.backend.refresh(data, Mock()))
+        self.assertTrue(data['connection_verified'])
+
+    def test_worker_rejects_server_execution_and_reload(self):
+        from mcpywrap.mcstudio.runtime_debug import RuntimeControlServer, recv_exact
+        import socket, struct
+        channel = Mock()
+        server = RuntimeControlServer(channel, 'test', mode='network'); server.start()
+        try:
+            for action, side in [('execute', 'server'), ('reload', 'client')]:
+                with socket.create_connection(server.server_address) as client:
+                    payload = json.dumps({'token':'test','action':action,'side':side,'code':'1+1'}).encode()
+                    client.sendall(struct.pack('!I',len(payload))+payload)
+                    size=struct.unpack('!I',recv_exact(client,4))[0]
+                    result=json.loads(recv_exact(client,size))
+                    self.assertEqual(result['state'],'failed')
+            channel.execute.assert_not_called()
+        finally: server.close()
+
+
+if __name__ == '__main__': unittest.main()