mcpywrap 0.3.2__tar.gz → 0.3.3__tar.gz

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 更新记录
 
+## 0.3.3
+
+- 新增实验性 `mcpy connect HOST --port PORT`，无需项目配置或登录身份即可尝试连接服务器。
+- `mcpy run` 支持 `[tool.mcpywrap.server]`，可用于纯连接目录或已有 Addon 项目；依赖继续校验，暂不装配网络服 Mod。
+- 网络运行共用前台调度，采集 SDK 与引擎日志；Ctrl+C 结束本次进程并清理临时配置，本地世界流程保持兼容。
+- README 与 Skill 补充精简用法及网络模式限制；126 项回归测试通过，用户已确认本机未认证连接测试通过，其他服务器是否允许连接取决于其认证要求。
+
 ## 0.3.2
 
 - 新增 `package`，构建项目及依赖并生成分发 ZIP，失败保留已有产物。

{mcpywrap-0.3.2/mcpywrap.egg-info → mcpywrap-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.2
+Version: 0.3.3
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -96,7 +96,7 @@ mcpy add --path "../shared-addon"
 | `mcpy run -l` | 查看已有实例 |
 | `mcpy run -d <ID前缀>` | 删除指定实例 |
 
-`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
+本地世界模式下，`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
 
 ### 打包分发
 
@@ -124,6 +124,26 @@ mcpy run --engine-version 3.10.0.420447
 
 已有实例默认保留原引擎版本；显式指定版本可以切换。自定义路径、项目级设置和环境变量的用法见[引擎配置参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/engine-discovery.md)。
 
+### 连接服务器（实验性）
+
+临时连接无需项目配置，地址可以是 IP 或主机名，端口默认 `19132`：
+
+```powershell
+mcpy connect 192.168.31.101 --port 19132
+```
+
+固定目标可写入 `pyproject.toml`，随后在该目录执行 `mcpy run`：
+
+```toml
+[tool.mcpywrap.server]
+host = "192.168.31.101"
+port = 19132
+```
+
+空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。当前使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
+
+网络模式前台输出日志并显示日志文件路径，按 Ctrl+C 结束本次游戏。暂不支持 Map 项目、GUI、`--detach`、`--new` 或本地世界实例 ID。
+
 ## AI Agent 使用
 
 仓库提供标准 [mcpywrap Skill](https://github.com/EaseCation/mcpywrap/tree/main/skills/mcpywrap)，帮助 Agent 安装工具、管理依赖、
@@ -136,7 +156,7 @@ mcpy run --engine-version 3.10.0.420447
 也可以下载仓库 ZIP，将完整的 `skills/mcpywrap` 文件夹复制到对应 Agent 的技能目录。
 无需从源码安装 Python 项目；CLI 和 Skill 分别安装，`pip/uv install` 不会自动注册 Skill。
 Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查是否具备所需命令能力。
-请使用 mcpywrap 0.3.2 或更高版本；需要固定组合时，可从 `v0.3.2` 标签安装对应 Skill。
+请使用 mcpywrap 0.3.3 或更高版本；需要固定组合时，可从 `v0.3.3` 标签安装对应 Skill。
 
 安装后可直接描述任务：
 

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/README.md

@@ -69,7 +69,7 @@ mcpy add --path "../shared-addon"
 | `mcpy run -l` | 查看已有实例 |
 | `mcpy run -d <ID前缀>` | 删除指定实例 |
 
-`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
+本地世界模式下，`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
 
 ### 打包分发
 
@@ -97,6 +97,26 @@ mcpy run --engine-version 3.10.0.420447
 
 已有实例默认保留原引擎版本；显式指定版本可以切换。自定义路径、项目级设置和环境变量的用法见[引擎配置参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/engine-discovery.md)。
 
+### 连接服务器（实验性）
+
+临时连接无需项目配置，地址可以是 IP 或主机名，端口默认 `19132`：
+
+```powershell
+mcpy connect 192.168.31.101 --port 19132
+```
+
+固定目标可写入 `pyproject.toml`，随后在该目录执行 `mcpy run`：
+
+```toml
+[tool.mcpywrap.server]
+host = "192.168.31.101"
+port = 19132
+```
+
+空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。当前使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
+
+网络模式前台输出日志并显示日志文件路径，按 Ctrl+C 结束本次游戏。暂不支持 Map 项目、GUI、`--detach`、`--new` 或本地世界实例 ID。
+
 ## AI Agent 使用
 
 仓库提供标准 [mcpywrap Skill](https://github.com/EaseCation/mcpywrap/tree/main/skills/mcpywrap)，帮助 Agent 安装工具、管理依赖、
@@ -109,7 +129,7 @@ mcpy run --engine-version 3.10.0.420447
 也可以下载仓库 ZIP，将完整的 `skills/mcpywrap` 文件夹复制到对应 Agent 的技能目录。
 无需从源码安装 Python 项目；CLI 和 Skill 分别安装，`pip/uv install` 不会自动注册 Skill。
 Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查是否具备所需命令能力。
-请使用 mcpywrap 0.3.2 或更高版本；需要固定组合时，可从 `v0.3.2` 标签安装对应 Skill。
+请使用 mcpywrap 0.3.3 或更高版本；需要固定组合时，可从 `v0.3.3` 标签安装对应 Skill。
 
 安装后可直接描述任务：
 

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """mcpywrap - 将 Python 3 代码转换为 Python 2 代码的工具"""
 
-__version__ = '0.3.2'
+__version__ = '0.3.3'

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap/cli.py

@@ -5,6 +5,7 @@ from . import __version__
 from .command_context import OperationGroup, configure_context
 
 from .commands.run_cmd import run_cmd
+from .commands.connect_cmd import connect_cmd
 from .commands.init_cmd import init_cmd
 from .commands.add_cmd import add_cmd
 from .commands.remove_cmd import remove_cmd
@@ -50,6 +51,7 @@ cli.add_command(package_cmd, name='package')
 cli.add_command(publish_cmd, name='publish')
 cli.add_command(mod_cmd, name='mod')
 cli.add_command(run_cmd, name='run')
+cli.add_command(connect_cmd, name='connect')
 cli.add_command(edit_cmd, name='edit')
 cli.add_command(ui_cmd, name='ui')
 cli.add_command(doctor_cmd, name='doctor')

mcpywrap-0.3.3/mcpywrap/commands/connect_cmd.py

@@ -0,0 +1,18 @@
+"""无项目、无登录身份的临时网络连接。"""
+import click
+
+from ..command_context import OperationCommand
+from ..mcstudio.discovery import engine_options
+from ..mcstudio.network import ServerTarget, run_network
+
+
+@click.command(cls=OperationCommand)
+@engine_options
+@click.argument('host')
+@click.option('--port', type=click.IntRange(1, 65535), default=19132, show_default=True)
+def connect_cmd(host, port, **engine_overrides):
+    """尝试未认证连接服务器；前台采集日志，Ctrl+C 结束本次游戏。
+
+    不读取项目配置或登录身份，不装配本地 Mod，不保证服务器接受连接。
+    """
+    return run_network(ServerTarget(host, port), engine_overrides=engine_overrides)

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap/commands/run_cmd.py

@@ -142,6 +142,9 @@ def _run_game_with_instance(config_path, level_id, all_packs, wait=True, log_cal
     from ..dependencies import read_project
     project_dir = str(Path(config_path).resolve().parent.parent)
     config = read_project(project_dir)
+    if 'server' in config.get('tool', {}).get('mcpywrap', {}):
+        # GUI/旧会话也不能将网络目标误启动成本地世界。
+        raise ValueError('服务器目标请通过 CLI mcpy run 启动，不能使用本地世界实例')
     project_type = config.get('tool', {}).get('mcpywrap', {}).get('project_type', 'addon')
     project_name = config.get('project', {}).get('name', 'project')
     all_packs = _setup_dependencies(project_name, project_dir)
@@ -337,7 +340,11 @@ def _gen_random_port():
 def run_cmd(new, list, delete, force, clean_all, instance_prefix, no_gui, detach, **engine_overrides):
     """游戏实例运行与管理
     
-    可直接运行 'mcpy run' 启动最新实例，或使用选项管理实例
+    可直接运行 'mcpy run' 启动最新实例，或使用选项管理实例。
+
+    配置 [tool.mcpywrap.server] host/port 时改为未认证网络连接，
+    不装配本地 Mod，不保证服务器接受连接。网络模式前台采集日志，
+    Ctrl+C 结束本次游戏，暂不支持 --detach。
     """
     base_dir = str(current_project())
     if (delete or clean_all) and non_interactive() and not force:
@@ -346,6 +353,21 @@ def run_cmd(new, list, delete, force, clean_all, instance_prefix, no_gui, detach
     if not config_exists():
         require_project()
 
+    # 在存档选择、配置同步和目录创建之前分流；管理选项仍只管理本地存档。
+    if not (list or delete or clean_all):
+        from ..dependencies import read_project
+        from ..mcstudio.network import configured_target, prepare_project, run_network
+        config = read_project(base_dir)
+        target = configured_target(config)
+        if target is not None:
+            if new or instance_prefix:
+                raise click.UsageError('网络模式不支持 --new 或本地世界实例 ID')
+            if detach:
+                raise click.UsageError('网络模式暂不支持 --detach；请在终端会话中前台运行')
+            packs = prepare_project(base_dir, config)
+            return run_network(target, project_dir=base_dir, packs=packs,
+                               engine_overrides=engine_overrides)
+
     # 确保 map 项目的 setuptools 配置同步
     ensure_map_setuptools_sync(interactive=False)
 

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap/commands/ui_cmd.py

@@ -18,6 +18,10 @@ def ui_cmd():
     # 检查项目是否已初始化
     if not config_exists():
         require_project()
+
+    from ..dependencies import read_project
+    if 'server' in read_project(current_project()).get('tool', {}).get('mcpywrap', {}):
+        raise click.UsageError('服务器目标暂不支持 GUI，请使用 mcpy run')
     
     from ..ui.project_ui import show_run_ui
     # 显示图形界面

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap/mcstudio/discovery.py

@@ -96,7 +96,7 @@ def fixed_drives():
             if mask & (1 << i) and kernel.GetDriveTypeW(ctypes.c_wchar_p(f'{chr(65 + i)}:\\')) == 3]
 
 
-def discovery_options(project_dir=None, overrides=None, environ=None, cwd=None):
+def discovery_options(project_dir=None, overrides=None, environ=None, cwd=None, read_project_config=True):
     """逐字段合并 CLI、环境变量、项目配置，并保留各自路径基准。"""
     cwd = Path(cwd or os.getcwd()).resolve()
     project_dir = Path(project_dir or cwd).resolve()
@@ -105,7 +105,7 @@ def discovery_options(project_dir=None, overrides=None, environ=None, cwd=None):
     config_file = project_dir / 'pyproject.toml'
     config = {}
     try:
-        if config_file.exists():
+        if read_project_config and config_file.exists():
             with config_file.open('rb') as stream:
                 document = tomli.load(stream)
             config = document.get('tool', {}).get('mcpywrap', {})
@@ -187,10 +187,10 @@ def _download_from_exe(exe):
     return None
 
 
-def discover_engines(project_dir=None, overrides=None, instance_version=None):
+def discover_engines(project_dir=None, overrides=None, instance_version=None, *, read_project_config=True):
     result = DiscoveryResult()
     try:
-        options = discovery_options(project_dir, overrides)
+        options = discovery_options(project_dir, overrides, read_project_config=read_project_config)
         requested = options.get('engine_version') or instance_version
         if requested:
             try:

mcpywrap-0.3.3/mcpywrap/mcstudio/network.py

@@ -0,0 +1,153 @@
+"""未认证网络连接：目标、项目准备与一次前台运行，不读取 MCS 身份或模板。"""
+import codecs
+import ipaddress
+import json
+import re
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from ..dependencies import DependencyService, addon_directories, read_project
+from .discovery import discover_engines, require_resources
+from .file_logs import FileLogServer
+from .game import open_game
+from .mcs import is_windows
+from .runtime_cppconfig import gen_runtime_config
+
+
+@dataclass(frozen=True)
+class ServerTarget:
+    host: str
+    port: int = 19132
+
+    def __post_init__(self):
+        if not isinstance(self.host, str) or not self.host or self.host != self.host.strip():
+            raise ValueError('server.host 必须是非空 IP 或主机名，不能包含首尾空白')
+        try:
+            ipaddress.ip_address(self.host)
+        except ValueError:
+            try:
+                hostname = self.host.rstrip('.').encode('idna').decode('ascii')
+            except UnicodeError as exc:
+                raise ValueError('server.host 不是有效的主机名') from exc
+            if len(hostname) > 253 or any(
+                not re.fullmatch(r'[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?', label)
+                for label in hostname.split('.')
+            ):
+                raise ValueError('server.host 必须是 IP 或主机名；端口请单独配置')
+        if type(self.port) is not int or not 1 <= self.port <= 65535:
+            raise ValueError('server.port 必须是 1–65535 的整数')
+
+
+def configured_target(config):
+    settings = config.get('tool', {}).get('mcpywrap', {})
+    if 'server' not in settings:
+        return None
+    server = settings['server']
+    if not isinstance(server, dict):
+        raise ValueError('tool.mcpywrap.server 必须是 TOML 表')
+    unknown = server.keys() - {'host', 'port'}
+    if unknown:
+        raise ValueError('未知的 server 配置字段: ' + ', '.join(sorted(unknown)))
+    return ServerTarget(server.get('host'), server.get('port', 19132))
+
+
+def prepare_project(project_dir, config=None):
+    """允许无根 Addon 的连接目录；出现包结构时仍严格校验。"""
+    root = Path(project_dir)
+    config = read_project(root) if config is None else config
+    if config.get('tool', {}).get('mcpywrap', {}).get('project_type', 'addon') != 'addon':
+        raise ValueError('网络运行暂时只支持 Addon 或纯连接目录，不支持 Map 项目')
+    markers = {'level.dat', 'db', 'manifest.json', 'pack_manifest.json'}
+    has_structure = any(p.name in markers or p.name.startswith(
+        ('behavior_pack', 'BehaviorPack', 'resource_pack', 'ResourcePack')) for p in root.iterdir())
+    folders = addon_directories(root) if has_structure else {}
+    manager = DependencyService(root).resolve(config)
+    packs = list(manager.get_all_dependencies().values())
+    if folders:
+        pack = manager.root_node.addon_pack
+        pack.behavior_pack_dir = folders.get('behavior')
+        pack.resource_pack_dir = folders.get('resource')
+        packs.append(pack)
+    return packs
+
+
+def unauthenticated_config(engine, target):
+    """从本地模式的无身份默认值构造实验配置，不复制账号或伪造认证字段。"""
+    config = gen_runtime_config(engine.version, '', '', engine.download_dir, '', [], [])
+    config.update(world_info=None, client_type=1, render_engine=0,
+                  misc={'multiplayer_game_type': 100})
+    config['room_info'].update(ip=target.host, port=target.port)
+    return config
+
+
+def run_network(target, *, project_dir=None, packs=(), engine_overrides=None):
+    """共用调度入口；packs 留待网络装配支持，本版只报告数量，不挂载。"""
+    if not is_windows():
+        raise ValueError('网络游戏启动仅支持 Windows')
+    engine = discover_engines(project_dir, engine_overrides,
+                              read_project_config=project_dir is not None).require_engine()
+    require_resources(engine)
+    config = unauthenticated_config(engine, target)
+    click.echo('未认证网络连接：不使用账号/token，服务器可能拒绝连接。')
+    click.echo(f'本次仅连接服务器，工具未装配本地 Addon（已解析 {len(packs)} 个）。')
+    directory = Path(tempfile.mkdtemp(prefix='mcpy-network-'))
+    config_path, log_path = directory / 'runtime.cppconfig', directory / 'game.log'
+    engine_log = directory / 'engine.log'
+    process, receiver = None, None
+    tails = []
+
+    def relay(final=False):
+        for tail, decoder in tails:
+            click.echo(decoder.decode(tail.read(), final=final), nl=False)
+
+    try:
+        config_path.write_text(json.dumps(config, ensure_ascii=False), encoding='utf-8')
+        receiver = FileLogServer(log_path)
+        receiver.start()
+        engine_log.touch()
+        for path in (log_path, engine_log):
+            tails.append((path.open('rb'), codecs.getincrementaldecoder('utf-8')(errors='replace')))
+        click.echo(f'目标: {target.host}:{target.port}\n日志: {log_path}\n引擎输出: {engine_log}')
+        process = open_game(str(config_path), engine=engine, logging_ip='127.0.0.1',
+                            logging_port=receiver.port, wait=False, use_system_color=False,
+                            output_path=str(engine_log))
+        if not process:
+            raise click.ClickException(f'游戏启动失败；日志目录: {directory}')
+        click.echo(f'游戏进程已创建，PID: {process.pid}（尚未确认连接）；Ctrl+C 结束本次游戏。')
+        while True:
+            relay()
+            try:
+                code = process.wait(timeout=0.2)
+                break
+            except subprocess.TimeoutExpired:
+                continue
+    finally:
+        try:
+            if process and process.poll() is None:
+                process.terminate()
+                try:
+                    process.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait(timeout=5)
+        finally:
+            try:
+                if receiver:
+                    receiver.close()
+                relay(final=True)
+            finally:
+                for tail, _ in tails:
+                    tail.close()
+                config_path.unlink(missing_ok=True)
+    if code:
+        error = click.ClickException(f'游戏退出码 {code}；日志: {log_path}；引擎输出: {engine_log}')
+        error.exit_code = code if 0 < code < 256 else 1
+        raise error
+    return {'application': 'game', 'pid': process.pid, 'state': 'exited', 'exit_code': code,
+            'authenticated': False, 'connection_verified': False, 'addons_assembled': False,
+            'host': target.host, 'port': target.port, 'log_path': str(log_path),
+            'engine_log_path': str(engine_log), 'engine_version': engine.version}

{mcpywrap-0.3.2 → mcpywrap-0.3.3/mcpywrap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.2
+Version: 0.3.3
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -96,7 +96,7 @@ mcpy add --path "../shared-addon"
 | `mcpy run -l` | 查看已有实例 |
 | `mcpy run -d <ID前缀>` | 删除指定实例 |
 
-`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
+本地世界模式下，`mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
 
 ### 打包分发
 
@@ -124,6 +124,26 @@ mcpy run --engine-version 3.10.0.420447
 
 已有实例默认保留原引擎版本；显式指定版本可以切换。自定义路径、项目级设置和环境变量的用法见[引擎配置参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/engine-discovery.md)。
 
+### 连接服务器（实验性）
+
+临时连接无需项目配置，地址可以是 IP 或主机名，端口默认 `19132`：
+
+```powershell
+mcpy connect 192.168.31.101 --port 19132
+```
+
+固定目标可写入 `pyproject.toml`，随后在该目录执行 `mcpy run`：
+
+```toml
+[tool.mcpywrap.server]
+host = "192.168.31.101"
+port = 19132
+```
+
+空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。当前使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
+
+网络模式前台输出日志并显示日志文件路径，按 Ctrl+C 结束本次游戏。暂不支持 Map 项目、GUI、`--detach`、`--new` 或本地世界实例 ID。
+
 ## AI Agent 使用
 
 仓库提供标准 [mcpywrap Skill](https://github.com/EaseCation/mcpywrap/tree/main/skills/mcpywrap)，帮助 Agent 安装工具、管理依赖、
@@ -136,7 +156,7 @@ mcpy run --engine-version 3.10.0.420447
 也可以下载仓库 ZIP，将完整的 `skills/mcpywrap` 文件夹复制到对应 Agent 的技能目录。
 无需从源码安装 Python 项目；CLI 和 Skill 分别安装，`pip/uv install` 不会自动注册 Skill。
 Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查是否具备所需命令能力。
-请使用 mcpywrap 0.3.2 或更高版本；需要固定组合时，可从 `v0.3.2` 标签安装对应 Skill。
+请使用 mcpywrap 0.3.3 或更高版本；需要固定组合时，可从 `v0.3.3` 标签安装对应 Skill。
 
 安装后可直接描述任务：
 

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/mcpywrap.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ mcpywrap/builders/watcher.py
 mcpywrap/commands/__init__.py
 mcpywrap/commands/add_cmd.py
 mcpywrap/commands/build_cmd.py
+mcpywrap/commands/connect_cmd.py
 mcpywrap/commands/default_cmd.py
 mcpywrap/commands/dependency_prompt.py
 mcpywrap/commands/dev_cmd.py
@@ -55,6 +56,7 @@ mcpywrap/mcstudio/file_logs.py
 mcpywrap/mcstudio/game.py
 mcpywrap/mcstudio/log_protocol.py
 mcpywrap/mcstudio/mcs.py
+mcpywrap/mcstudio/network.py
 mcpywrap/mcstudio/processes.py
 mcpywrap/mcstudio/runtime_cppconfig.py
 mcpywrap/mcstudio/session_worker.py
@@ -89,4 +91,5 @@ tests/test_automation.py
 tests/test_engine_discovery.py
 tests/test_game_window_skill.py
 tests/test_local_dependencies.py
+tests/test_network.py
 tests/test_package.py

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/pyproject.toml

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

{mcpywrap-0.3.2 → mcpywrap-0.3.3}/skills/mcpywrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcpywrap
-description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图项目、Python 包与本地依赖，构建分发 ZIP，启动游戏并读取日志；使用会话绑定的脚本截图和发送按键，复杂界面交互交接 Computer Use。
+description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图项目与依赖，构建 ZIP，启动本地世界或尝试未认证服务器连接并读取日志；使用会话绑定的脚本截图和发送按键，复杂界面交互交接 Computer Use。
 ---
 
 # mcpywrap
@@ -9,7 +9,7 @@ description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图项
 
 ## 准备
 
-- 明确用户的项目绝对路径；每条命令使用 `--project`，不依赖当前目录。
+- 项目操作使用绝对路径 `--project`，不依赖当前目录；临时 `connect` 无需项目。
 - 检查 `mcpy --version`、`mcpy --help` 及要调用的子命令帮助。版本号不能代替能力检查。
 - 需要安装时使用 [bootstrap.ps1](scripts/bootstrap.ps1)。脚本使用已有 uv，缺少时返回官方安装入口；默认复用已有可用安装，升级或更换来源使用 `-Upgrade`。
 - 正式版本使用 `-Version`，固定源码使用 `-GitRef <完整提交 SHA>`，开发目录使用 `-EditablePath <绝对路径>`。当前 Skill 对应的 CLI 必须支持 `--project`、`--non-interactive`、`--json` 和会话命令。
@@ -39,7 +39,7 @@ description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图项
 `dev` 持续输出文本日志，不使用 `--json`；修改依赖声明后重启监控。
 `publish --yes` 是真实上传；只有用户请求发布时才调用。
 
-## 游戏验证
+## 本地世界验证
 
 1. `doctor --json` 检查引擎与资源；编辑器缺失不等于无法运行游戏。
 2. `run --no-gui --detach --json` 启动本次会话，只显示游戏本体。
@@ -51,6 +51,23 @@ description: 使用 mcpywrap 管理《我的世界》中国版 Addon/地图项
 可使用 [smoke.py](scripts/smoke.py) 自动检查并打包；`--game` 才运行游戏，
 `--expect-log` 可重复指定加载标记。该脚本会停止自己创建的游戏；不要用于要求保留游戏窗口的任务。
 
+## 网络连接（实验性）
+
+网络能力需 CLI 0.3.3 或更高版本，先检查 `connect --help`。临时连接用 `mcpy connect <IP或主机名> --port 19132`，不读取项目配置。
+固定目标在 `pyproject.toml` 添加以下表，再执行 `mcpy --project <绝对路径> --non-interactive run`：
+
+```toml
+[tool.mcpywrap.server]
+host = "192.168.31.101"
+port = 19132
+```
+
+纯连接目录只需此表，无需 `init`；Addon 项目仍校验依赖，但本版不装配本地 Mod。
+不读取登录身份或 token，不能把进程创建成功当成进服成功。
+在可持续运行的终端会话中执行，读取输出的 PID 和两路日志路径；Ctrl+C 结束本次游戏。
+`--json` 在游戏退出后才返回最终结果；不支持 `--detach`、`--new`、世界实例 ID、Map 或 GUI。
+网络运行不生成本地会话 ID，不使用 `status/logs/stop --session`、`smoke.py --game` 或 `game_window.py` 管理它。
+
 ## 游戏截图与键盘操作
 
 固定截图和键盘输入优先使用 Skill 自带的 [game_window.py](scripts/game_window.py)，仅需 Windows 和 Python 标准库。

mcpywrap-0.3.3/tests/test_network.py

@@ -0,0 +1,228 @@
+"""未认证网络调度：不需要 MCS、认证服务或真实游戏。"""
+import importlib
+import inspect
+import json
+import socket
+import subprocess
+import tempfile
+import time
+import unittest
+import uuid
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from click.testing import CliRunner
+
+from mcpywrap.cli import cli
+from mcpywrap.dependencies import DependencyError
+from mcpywrap.mcstudio import network as n
+from mcpywrap.mcstudio.discovery import Engine, discovery_options
+
+
+class NetworkTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.project = self.root / '中文 项目'
+        self.project.mkdir()
+        options = {'mix_stderr': False} if 'mix_stderr' in inspect.signature(CliRunner).parameters else {}
+        self.runner = CliRunner(**options)
+
+    def config(self, text='[tool.mcpywrap.server]\nhost="127.0.0.1"\n'):
+        (self.project / 'pyproject.toml').write_text(text, encoding='utf-8')
+
+    def call(self, *args):
+        return self.runner.invoke(cli, ['--project', str(self.project), '--non-interactive', *args, '--json'])
+
+    def addon(self, root):
+        pack = root / 'behavior_pack_demo'
+        pack.mkdir(parents=True)
+        (pack / 'manifest.json').write_text(json.dumps({
+            'header': {'uuid': str(uuid.uuid4()), 'name': 'test', 'version': [1, 0, 0]},
+            'modules': [{'uuid': str(uuid.uuid4()), 'type': 'data', 'version': [1, 0, 0]}]}))
+
+    def test_target_validation(self):
+        for host in ('127.0.0.1', '::1', 'example.com', '中文.example'):
+            self.assertEqual(n.ServerTarget(host).port, 19132)
+        for host in ('', None, ' x', 'a:123', 'http://host', 'a/b', 'a\n', '-host'):
+            with self.subTest(host=host), self.assertRaises(ValueError):
+                n.ServerTarget(host)
+        for port in (True, '19132', 0, 65536, 1.5):
+            with self.assertRaises(ValueError):
+                n.ServerTarget('localhost', port)
+        for value in ({}, None, 'host', {'host': 'a', 'prot': 10}):
+            with self.assertRaises(ValueError):
+                n.configured_target({'tool': {'mcpywrap': {'server': value}}})
+        self.assertIsNone(n.configured_target({}))
+
+    def test_empty_project_and_dependency_only_and_root(self):
+        self.config()
+        self.assertEqual(n.prepare_project(self.project), [])
+        dep = self.root / '共享 addon'
+        self.addon(dep)
+        self.config('[tool.mcpywrap]\nlocal_dependencies=["../共享 addon"]\n'
+                    '[tool.mcpywrap.server]\nhost="localhost"\n')
+        packs = n.prepare_project(self.project)
+        self.assertEqual(len(packs), 1)
+        self.assertTrue(Path(packs[0].path).samefile(dep))
+        self.addon(self.project)
+        self.assertEqual(len(n.prepare_project(self.project)), 2)
+        self.assertFalse((dep / 'pyproject.toml').exists())
+
+    def test_bad_structure_is_not_treated_as_empty(self):
+        for marker in ('behavior_pack', 'resource_pack', 'level.dat', 'manifest.json'):
+            path = self.project / marker
+            path.touch()
+            with self.subTest(marker=marker), self.assertRaises(DependencyError):
+                n.prepare_project(self.project)
+            path.unlink()
+        self.config('[tool.mcpywrap]\nlocal_dependencies=["../missing"]\n')
+        with self.assertRaises(DependencyError):
+            n.prepare_project(self.project)
+        self.config('[tool.mcpywrap]\nproject_type="map"\n')
+        with self.assertRaises(ValueError):
+            n.prepare_project(self.project)
+        self.config('[project]\ndependencies=["mcpy-nonexistent-test-package>=9"]\n')
+        with self.assertRaises(DependencyError):
+            n.prepare_project(self.project)
+
+    def test_cli_run_routes_before_local_side_effects(self):
+        self.config()
+        before = (self.project / 'pyproject.toml').read_bytes()
+        with patch.object(n, 'run_network', return_value={'authenticated': False}) as launch:
+            result = self.call('run')
+            self.assertEqual(result.exit_code, 0, result.output)
+            self.assertEqual(launch.call_args.args[0], n.ServerTarget('127.0.0.1'))
+            self.assertEqual(launch.call_args.kwargs['packs'], [])
+            self.assertFalse((self.project / '.runtime').exists())
+        self.assertEqual(before, (self.project / 'pyproject.toml').read_bytes())
+
+    def test_cli_connect_ignores_project_and_requires_host(self):
+        self.config('invalid = [')
+        with patch('mcpywrap.commands.connect_cmd.run_network', return_value={}) as launch:
+            result = self.call('connect', 'localhost', '--port', '20000')
+            self.assertEqual(result.exit_code, 0, result.output)
+            self.assertEqual(launch.call_args.args[0], n.ServerTarget('localhost', 20000))
+            self.assertNotIn('project_dir', launch.call_args.kwargs)
+        self.assertEqual(self.call('connect').exit_code, 2)
+        self.assertEqual(self.call('connect', 'localhost', '--port', '0').exit_code, 2)
+        self.assertFalse((self.project / '.runtime').exists())
+        self.assertEqual(discovery_options(self.project, environ={}, read_project_config=False), {})
+
+    def test_network_options_and_invalid_config_never_start_world(self):
+        run = importlib.import_module('mcpywrap.commands.run_cmd')
+        self.config()
+        with patch.object(run, '_run_game_with_instance') as local, patch.object(n, 'run_network') as launch:
+            for args in (('run', '--new'), ('run', '1234'), ('run', '--detach')):
+                self.assertEqual(self.call(*args).exit_code, 2)
+            self.config('[tool.mcpywrap.server]\nport=123\n')
+            self.assertEqual(self.call('run').exit_code, 1)
+            self.config('broken = [')
+            self.assertEqual(self.call('run').exit_code, 1)
+            local.assert_not_called()
+            launch.assert_not_called()
+        self.assertFalse((self.project / '.runtime').exists())
+
+    def test_gui_and_stale_worker_guard(self):
+        self.config()
+        ui = importlib.import_module('mcpywrap.commands.ui_cmd')
+        with patch.object(ui, 'non_interactive', return_value=False):
+            result = self.runner.invoke(cli, ['--project', str(self.project), 'ui'])
+            self.assertNotEqual(result.exit_code, 0)
+            self.assertIn('mcpy run', result.stderr)
+        run = importlib.import_module('mcpywrap.commands.run_cmd')
+        with self.assertRaisesRegex(ValueError, '服务器目标'):
+            run._run_game_with_instance(str(self.project / '.runtime/old.cppconfig'), 'old', [])
+
+    def test_anonymous_config_does_not_inherit_identity(self):
+        engine = Engine('game', '3.10.0.420447', 'engine', str(self.root), 'test')
+        config = n.unauthenticated_config(engine, n.ServerTarget('localhost'))
+        self.assertIsNone(config['world_info'])
+        self.assertEqual(config['room_info']['token'], '')
+        self.assertEqual(config['misc'], {'multiplayer_game_type': 100})
+        self.assertNotIn('player_info', config)
+        self.assertEqual(config['LocalComponentPathsDict'], {})
+
+    def execute_fake(self, *, exit_code=0, interrupt=False, failed_start=False):
+        directory = self.root / 'run output'
+        directory.mkdir()
+        process = Mock(pid=12345)
+        process.poll.return_value = 0
+        process.wait.return_value = exit_code
+        if interrupt:
+            process.poll.return_value = None
+            process.wait.side_effect = [KeyboardInterrupt(), None]
+        engine = Engine('game', '3.10.0.420447', 'engine', str(self.root), 'test')
+
+        def launch(path, **kwargs):
+            config = json.loads(Path(path).read_text(encoding='utf-8'))
+            self.assertIsNone(config['world_info'])
+            self.assertEqual(kwargs['logging_ip'], '127.0.0.1')
+            Path(kwargs['output_path']).write_text('native engine output\n', encoding='utf-8')
+            with socket.create_connection(('127.0.0.1', kwargs['logging_port']), timeout=2) as client:
+                client.sendall('网络日志\n'.encode('utf-8'))
+            deadline = time.monotonic() + 2
+            while time.monotonic() < deadline and not (directory / 'game.log').read_text(encoding='utf-8'):
+                time.sleep(0.01)
+            return False if failed_start else process
+
+        with patch.object(n, 'is_windows', return_value=True), \
+                patch.object(n, 'discover_engines', return_value=Mock(require_engine=lambda: engine)) as discover, \
+                patch.object(n, 'require_resources'), \
+                patch.object(n.tempfile, 'mkdtemp', return_value=str(directory)), \
+                patch.object(n, 'open_game', side_effect=launch):
+            try:
+                result = n.run_network(n.ServerTarget('localhost'))
+                self.assertFalse(result['connection_verified'])
+                self.assertFalse(result['authenticated'])
+            finally:
+                self.assertFalse((directory / 'runtime.cppconfig').exists())
+                self.assertEqual((directory / 'game.log').read_text(encoding='utf-8'), '网络日志\n')
+                self.assertEqual((directory / 'engine.log').read_text(encoding='utf-8'), 'native engine output\n')
+                self.assertFalse(discover.call_args.kwargs['read_project_config'])
+                if interrupt:
+                    process.terminate.assert_called_once()
+
+    def test_listener_ready_and_cleanup(self):
+        with patch.object(n.click, 'echo') as output:
+            self.execute_fake()
+        self.assertTrue(any('native engine output' in str(c) for c in output.call_args_list))
+        self.assertTrue(any('网络日志' in str(c) for c in output.call_args_list))
+
+    def test_cli_nonzero_exit_and_structured_result(self):
+        import click
+        failure = click.ClickException('game exited 7')
+        failure.exit_code = 7
+        with patch('mcpywrap.commands.connect_cmd.run_network', side_effect=failure):
+            result = self.call('connect', 'localhost')
+        self.assertEqual(result.exit_code, 7)
+        self.assertFalse(json.loads(result.stdout)['ok'])
+
+    def test_interrupt_stops_only_owned_process(self):
+        with self.assertRaises(KeyboardInterrupt):
+            self.execute_fake(interrupt=True)
+
+    def test_nonzero_and_failed_start(self):
+        import click
+        with self.assertRaises(click.ClickException) as raised:
+            self.execute_fake(exit_code=7)
+        self.assertEqual(raised.exception.exit_code, 7)
+
+    def test_failed_start_cleanup(self):
+        import click
+        with self.assertRaises(click.ClickException):
+            self.execute_fake(failed_start=True)
+
+    def test_engine_validation_precedes_writes(self):
+        with patch.object(n, 'is_windows', return_value=True), \
+                patch.object(n, 'discover_engines', side_effect=ValueError('missing engine')), \
+                patch.object(n.tempfile, 'mkdtemp') as create, patch.object(n, 'open_game') as launch:
+            with self.assertRaises(ValueError):
+                n.run_network(n.ServerTarget('localhost'))
+            create.assert_not_called()
+            launch.assert_not_called()
+
+
+if __name__ == '__main__':
+    unittest.main()