mcpywrap 0.3.4__tar.gz → 0.3.6__tar.gz

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 更新记录
 
+## 0.3.6
+
+- 新增局域网 serve 服务与 --remote/--local 路由；macOS 本机开发、Windows 网络游戏测试共用 CLI 和 Skill。
+- 新增会话截图、键盘、鼠标命令，支持菜单操作与相对视角移动；远端截图保存到调用端。
+- 支持启动去重、所属会话恢复、串行桌面输入与服务退出清理；日志可选择 game/engine/worker。
+- 跨平台 bootstrap.py 共用安装逻辑，PowerShell 入口保留兼容；macOS 安装不依赖 Qt。
+
+## 0.3.5
+
+- 网络连接接入统一游戏会话：`connect/run --detach --json` 返回进程身份与日志，可复用 status/logs/stop、Skill 截图与按键脚本；网络 JSON 启动现在要求 `--detach`。
+- 新增 `doctor --mcs-auth` 只读组件检查；Skill 安装脚本分别报告 CLI 能力与组件是否具备，按任务显式要求可选能力。
+- 冒烟脚本支持 `--mcs-auth` 与 `--connect`，共用日志标记验证和本次会话清理；精简 Skill 入口并补充编辑器、地图合并及网络指引。
+- 修复 Windows PowerShell 5.1 中文脚本读取与 GBK 管道兼容；JSON 无损保留 Unicode，会话 SDK／引擎日志统一解码为 UTF-8 后脱敏。
+
 ## 0.3.4
 
 - 新增显式 `--mcs-auth`：网络连接、单人测试和单人项目 GUI 可按次使用已登录的 MC Studio 身份；默认仍不读取身份，配置文件不能自动启用。

{mcpywrap-0.3.4/mcpywrap.egg-info → mcpywrap-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.4
+Version: 0.3.6
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -20,7 +20,7 @@ Requires-Dist: tomli
 Requires-Dist: tomli-w
 Requires-Dist: setuptools
 Requires-Dist: packaging>=21
-Requires-Dist: PyQt5>=5.15.0
+Requires-Dist: PyQt5>=5.15.0; sys_platform == "win32"
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: rich>=10.0.0
 Dynamic: license-file
@@ -140,9 +140,18 @@ host = "192.168.31.101"
 port = 19132
 ```
 
-空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。当前使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
+空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。默认使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
 
-网络模式前台输出日志并显示日志文件路径，按 Ctrl+C 结束本次游戏。暂不支持 Map 项目、GUI、`--detach`、`--new` 或本地世界实例 ID。
+网络模式默认前台输出日志，Ctrl+C 结束本次游戏。增加 `--detach --json` 可返回会话，与本地游戏共用 `status/logs/stop` 及 Skill 截图、按键脚本：
+
+```powershell
+mcpy --project D:\tests\server --non-interactive connect example.com --detach --json
+mcpy --project D:\tests\server status --session <id> --json
+mcpy --project D:\tests\server stop --session <id> --json
+```
+
+目录须已存在；临时 `connect` 不读取项目配置，只在该目录保存会话。后续操作使用启动返回的 `project` 和 `session`。
+网络模式暂不支持 Map、Qt GUI、`--new` 或本地世界实例 ID；进程启动不等于成功进服。
 
 ### 使用 MC Studio 登录身份（可选）
 
@@ -163,8 +172,8 @@ port = 19132
 
 也可以下载仓库 ZIP，将完整的 `skills/mcpywrap` 文件夹复制到对应 Agent 的技能目录。
 无需从源码安装 Python 项目；CLI 和 Skill 分别安装，`pip/uv install` 不会自动注册 Skill。
-Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查是否具备所需命令能力。
-请使用 mcpywrap 0.3.4 或更高版本；需要固定组合时，可从 `v0.3.4` 标签安装对应 Skill。
+两端使用跨平台 `scripts/bootstrap.py` 安装或复用各自的 CLI，Windows 也可用 `bootstrap.ps1`。脚本分别报告本机与远端能力；Skill、CLI 与 Windows 服务需要分别检查，Git／可编辑安装可能缺少登录组件。
+局域网流程请使用 mcpywrap 0.3.6 或更高版本，可从 `v0.3.6` 标签安装配套 Skill。实际能力仍以脚本检测为准；更新 Skill 不会自动更新两端 CLI。
 
 安装后可直接描述任务：
 
@@ -172,9 +181,24 @@ Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查
 - “启动这个项目，不弹日志界面，检查客户端和服务端的加载日志。”
 - “启动游戏并截图，模拟组合按键移动，检查 F11 输入模式和 F3 调试信息层。”
 
-Agent 通过 CLI 管理项目，Skill 自带游戏截图与键盘输入脚本；复杂游戏交互交给 Computer Use。Qt 管理与模板界面用于人工操作。
+Agent 通过 CLI 管理项目、截图和输入键鼠。远程交互查看下载的图片后继续操作；本机复杂交互可交给 Computer Use。Qt 管理与模板界面用于人工操作。
 常用入口：`mcpy --project <目录> --non-interactive <命令> --json`。
 
+## macOS 与 Windows 局域网联调
+
+Windows 用户在测试桌面运行 `mcpy --local serve`，默认监听 `0.0.0.0:18765`；macOS 使用同一服务地址调用：
+
+```bash
+mcpy --remote http://192.168.1.20:18765 --non-interactive connect 192.168.1.10 --port 19132 --detach --json
+mcpy --remote http://192.168.1.20:18765 screenshot --session <id> --output ./game.png --json
+mcpy --remote http://192.168.1.20:18765 key --session <id> SHIFT+W --hold-ms 1000 --json
+mcpy --remote http://192.168.1.20:18765 stop --session <id> --json
+```
+
+项目依赖与构建仍在 macOS，游戏诊断、网络启动、日志和输入转发到 Windows，截图下载到调用端。
+默认免认证，可用两端 `MCPY_REMOTE_TOKEN` 启用令牌；服务 Ctrl+C 清理所属游戏。需要 Windows 保持登录未锁屏，一次只接受一个活动会话。
+bootstrap 检测不会保存远端地址，独立终端调用请每次显式传 `--remote <地址>`。部署、鼠标与恢复见[远程测试指引](skills/mcpywrap/references/remote-testing.md)。
+
 ## 更多信息
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/README.md

@@ -113,9 +113,18 @@ host = "192.168.31.101"
 port = 19132
 ```
 
-空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。当前使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
+空目录只需上述配置，无需执行 `mcpy init`；已有 Addon 项目也可添加此表。默认使用未认证连接，不读取登录身份或 token，不保证服务器允许进服；项目依赖仍会校验，但暂不装配本地 Mod。
 
-网络模式前台输出日志并显示日志文件路径，按 Ctrl+C 结束本次游戏。暂不支持 Map 项目、GUI、`--detach`、`--new` 或本地世界实例 ID。
+网络模式默认前台输出日志，Ctrl+C 结束本次游戏。增加 `--detach --json` 可返回会话，与本地游戏共用 `status/logs/stop` 及 Skill 截图、按键脚本：
+
+```powershell
+mcpy --project D:\tests\server --non-interactive connect example.com --detach --json
+mcpy --project D:\tests\server status --session <id> --json
+mcpy --project D:\tests\server stop --session <id> --json
+```
+
+目录须已存在；临时 `connect` 不读取项目配置，只在该目录保存会话。后续操作使用启动返回的 `project` 和 `session`。
+网络模式暂不支持 Map、Qt GUI、`--new` 或本地世界实例 ID；进程启动不等于成功进服。
 
 ### 使用 MC Studio 登录身份（可选）
 
@@ -136,8 +145,8 @@ port = 19132
 
 也可以下载仓库 ZIP，将完整的 `skills/mcpywrap` 文件夹复制到对应 Agent 的技能目录。
 无需从源码安装 Python 项目；CLI 和 Skill 分别安装，`pip/uv install` 不会自动注册 Skill。
-Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查是否具备所需命令能力。
-请使用 mcpywrap 0.3.4 或更高版本；需要固定组合时，可从 `v0.3.4` 标签安装对应 Skill。
+两端使用跨平台 `scripts/bootstrap.py` 安装或复用各自的 CLI，Windows 也可用 `bootstrap.ps1`。脚本分别报告本机与远端能力；Skill、CLI 与 Windows 服务需要分别检查，Git／可编辑安装可能缺少登录组件。
+局域网流程请使用 mcpywrap 0.3.6 或更高版本，可从 `v0.3.6` 标签安装配套 Skill。实际能力仍以脚本检测为准；更新 Skill 不会自动更新两端 CLI。
 
 安装后可直接描述任务：
 
@@ -145,9 +154,24 @@ Skill 中的 `scripts/bootstrap.ps1` 可使用已有 uv 安装 CLI，并检查
 - “启动这个项目，不弹日志界面，检查客户端和服务端的加载日志。”
 - “启动游戏并截图，模拟组合按键移动，检查 F11 输入模式和 F3 调试信息层。”
 
-Agent 通过 CLI 管理项目，Skill 自带游戏截图与键盘输入脚本；复杂游戏交互交给 Computer Use。Qt 管理与模板界面用于人工操作。
+Agent 通过 CLI 管理项目、截图和输入键鼠。远程交互查看下载的图片后继续操作；本机复杂交互可交给 Computer Use。Qt 管理与模板界面用于人工操作。
 常用入口：`mcpy --project <目录> --non-interactive <命令> --json`。
 
+## macOS 与 Windows 局域网联调
+
+Windows 用户在测试桌面运行 `mcpy --local serve`，默认监听 `0.0.0.0:18765`；macOS 使用同一服务地址调用：
+
+```bash
+mcpy --remote http://192.168.1.20:18765 --non-interactive connect 192.168.1.10 --port 19132 --detach --json
+mcpy --remote http://192.168.1.20:18765 screenshot --session <id> --output ./game.png --json
+mcpy --remote http://192.168.1.20:18765 key --session <id> SHIFT+W --hold-ms 1000 --json
+mcpy --remote http://192.168.1.20:18765 stop --session <id> --json
+```
+
+项目依赖与构建仍在 macOS，游戏诊断、网络启动、日志和输入转发到 Windows，截图下载到调用端。
+默认免认证，可用两端 `MCPY_REMOTE_TOKEN` 启用令牌；服务 Ctrl+C 清理所属游戏。需要 Windows 保持登录未锁屏，一次只接受一个活动会话。
+bootstrap 检测不会保存远端地址，独立终端调用请每次显式传 `--remote <地址>`。部署、鼠标与恢复见[远程测试指引](skills/mcpywrap/references/remote-testing.md)。
+
 ## 更多信息
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/docs/development.md

@@ -19,6 +19,11 @@ 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`；脚本停止自己创建的会话。
 历史验收记录仅用于追溯，不能代替当前版本测试。
 
 发布见 [发布流程](releasing.md)。
+
+局域网协议与路由测试使用 `tests/test_remote.py` 的真实回环 HTTP 和模拟游戏，不需要实际登录。
+桌面原生实现集中在 `mcstudio/window.py`，Skill 脚本只组合公开 CLI。鼠标逻辑通过模拟 Win32 测试释放与坐标，实机效果按截图验证。
+Windows CI 保留 3.9/3.12/3.14；macOS CI 验证无 Qt 安装、本机构建与远程客户端。真实跨机验收需另行准备 Windows 桌面和 macOS 客户端。

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/docs/engine-discovery.md

@@ -52,4 +52,4 @@ mcpy --project D:\mods\demo stop --session <id> --json
 
 只打开游戏窗口，日志写入返回的文件。`running` 表示进程存活，加载是否成功应查看项目日志或游戏画面。
 Computer Use 只接手游戏画面；Qt 管理、模板及日志页留给人工操作。
-本功能不包含第三方网络服 IP/端口连接。
+以上示例是本地世界会话。网络连接可用 `mcpy connect <地址> --detach --json`，或配置服务器后执行 `run --detach --json`；同样使用返回的项目路径、会话 ID 读取日志、截图、输入和停止。临时 connect 不读取项目引擎配置，使用 CLI 参数或环境变量覆盖。

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/docs/mcs-auth.md

@@ -10,7 +10,9 @@ mcpy ui --mcs-auth
 mcpy --project D:\mods\demo --non-interactive run --mcs-auth --detach --json
 ```
 
-网络模式不支持 `--detach`；GUI 登录支持单人项目，网络目标继续使用 CLI。
+本地与网络均支持 `--detach --json`，共用会话查询、日志和停止。GUI 登录支持单人项目，网络目标使用 CLI。
+
+`mcpy doctor --mcs-auth --json` 可只读检查组件文件，不读取身份、不写缓存、不修改证书。组件具备不表示已登录或系统策略允许启用。
 
 ## 用户会看到什么
 

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/docs/releasing.md

@@ -1,6 +1,6 @@
 # 发布流程
 
-主分支和 PR 运行 Windows Python 3.9、3.12、3.14 的自动化测试。通过后构建 wheel/sdist、运行严格元数据检查、检查产物内容，并在独立环境安装 wheel 验证 CLI 和模块导入。
+主分支和 PR 运行 Windows Python 3.9、3.12、3.14 的自动化测试，以及 macOS 的无 Qt 安装、项目构建与远程客户端测试。通过后构建 wheel/sdist、运行严格元数据检查、检查产物内容，并在独立环境安装 wheel 验证 CLI 和模块导入。
 
 Windows CI 先用 MSVC 从 `native/mcs_auth` 编译 x86 登录桥接，再签名并通过构建产物交给测试和 Python 打包任务；编译后的 EXE/DLL 不提交到 Git。仓库只保留发布者公钥证书和指纹。
 

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/__init__.py

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

mcpywrap-0.3.6/mcpywrap/__main__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""
+mcpywrap 命令行工具的入口点
+"""
+
+from .cli import cli
+
+def main():
+    """主函数，作为 CLI 入口点"""
+    import sys
+    # Keep the caller's text encoding; unsupported symbols must not abort an operation.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, 'reconfigure'):
+            stream.reconfigure(errors='backslashreplace')
+    cli()
+
+if __name__ == "__main__":
+    main()

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/cli.py

@@ -27,11 +27,13 @@ from .commands.session_cmd import status_cmd, logs_cmd, stop_cmd
 @click.option("--project", type=click.Path(file_okay=False), help="项目目录，默认当前目录")
 @click.option("--non-interactive", is_flag=True, help="不读取终端输入")
 @click.option("--json", "json_output", is_flag=True, help="输出 JSON 结果")
+@click.option('--remote', help='Windows 测试服务地址，例如 http://192.168.1.20:18765')
+@click.option('--local', 'local_only', is_flag=True, help='本次强制本机执行')
 @click.version_option(__version__)
 @click.pass_context
-def cli(ctx, project, non_interactive, json_output):
+def cli(ctx, project, non_interactive, json_output, remote, local_only):
     """mcpywrap - 《我的世界》中国版 依赖管理与项目构建工具"""
-    configure_context(project, non_interactive)
+    configure_context(project, non_interactive, remote, local_only)
     # 如果没有提供子命令，则运行 default_cmd
     if ctx.invoked_subcommand is None:
         # 导入并运行默认命令
@@ -60,5 +62,12 @@ cli.add_command(status_cmd)
 cli.add_command(logs_cmd)
 cli.add_command(stop_cmd)
 
+from .commands.desktop_cmd import screenshot_cmd, key_cmd, mouse_cmd
+from .commands.serve_cmd import serve_cmd
+cli.add_command(screenshot_cmd, 'screenshot')
+cli.add_command(key_cmd, 'key')
+cli.add_command(mouse_cmd, 'mouse')
+cli.add_command(serve_cmd, 'serve')
+
 if __name__ == '__main__':
     cli()

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/command_context.py

@@ -17,6 +17,8 @@ class CommandContext:
     project: Path
     non_interactive: bool = False
     json_output: bool = False
+    remote: str = None
+    local: bool = False
 
 
 _context = contextvars.ContextVar('mcpy_context', default=None)
@@ -67,6 +69,10 @@ class OperationCommand(click.Command):
 
     def invoke(self, ctx):
         ctx.params.pop('json_output', None)
+        from .remote.client import routed_command
+        routed, result = routed_command(ctx.info_name, ctx.params)
+        if routed:
+            return result
         return super().invoke(ctx)
 
 
@@ -111,7 +117,8 @@ class OperationGroup(click.Group):
                 data = {'ok': code == 0, 'error': None, 'hint': None}
                 if isinstance(result, dict):
                     data.update(result)
-                click.echo(json.dumps(data, ensure_ascii=False), file=output)
+                # ASCII JSON survives both GBK consoles and UTF-8 subprocess pipes losslessly.
+                click.echo(json.dumps(data, ensure_ascii=True), file=output)
             elif code:
                 click.echo('错误: ' + str((result or {}).get('error') or '操作失败'), err=True)
                 if (result or {}).get('hint'):
@@ -130,9 +137,31 @@ class OperationGroup(click.Group):
         return result
 
 
-def configure_context(project, interactive_disabled):
+def configure_context(project, interactive_disabled, remote=None, local=False):
     current = _context.get()
+    current.remote, current.local = remote, local
     current.project = Path(project or os.getcwd()).expanduser().resolve()
     current.non_interactive = interactive_disabled or not sys.stdin.isatty()
     if not current.project.is_dir():
         raise click.UsageError(f'项目目录不存在: {current.project}')
+
+
+def remote_url():
+    """Resolve only for game operations; local project commands never depend on a remote."""
+    state = _context.get()
+    if state and state.local:
+        return None
+    if state and state.remote is not None:
+        return state.remote
+    if os.environ.get('MCPY_REMOTE'):
+        return os.environ['MCPY_REMOTE']
+    path = project_dir()/'pyproject.toml'
+    if path.is_file():
+        import tomli
+        try:
+            with path.open('rb') as stream:
+                return tomli.load(stream).get('tool', {}).get('mcpywrap', {}).get('remote_url')
+        except tomli.TOMLDecodeError:
+            # connect intentionally ignores unrelated malformed project configuration.
+            return None
+    return None

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/connect_cmd.py

@@ -11,10 +11,15 @@ from ..mcstudio.network import ServerTarget, run_network
 @click.argument('host')
 @click.option('--port', type=click.IntRange(1, 65535), default=19132, show_default=True)
 @click.option('--mcs-auth', is_flag=True, help='本次连接使用已登录的 MC Studio 身份')
-def connect_cmd(host, port, mcs_auth=False, **engine_overrides):
+@click.option('--detach', is_flag=True, help='后台连接并返回游戏会话；JSON 必须指定')
+@click.option('--request-id', help='远程启动的 32 位十六进制请求 ID，用于找回或重试同一请求')
+def connect_cmd(host, port, mcs_auth=False, detach=False, request_id=None, **engine_overrides):
     """尝试连接服务器；前台采集日志，Ctrl+C 结束本次游戏。
 
     默认不读取登录身份；--mcs-auth 要求 MCS 已登录及本机桥接可用。
     不读取项目配置，不装配本地 Mod，不保证服务器接受连接。
     """
-    return run_network(ServerTarget(host, port, 'mcs' if mcs_auth else 'none'), engine_overrides=engine_overrides)
+    if request_id:
+        raise click.UsageError('--request-id 仅用于远程启动')
+    return run_network(ServerTarget(host, port, 'mcs' if mcs_auth else 'none'),
+                       engine_overrides=engine_overrides, detach=detach)

mcpywrap-0.3.6/mcpywrap/commands/desktop_cmd.py

@@ -0,0 +1,67 @@
+"""Session-bound desktop operations; the CLI router can execute these remotely."""
+from pathlib import Path
+import click
+from ..command_context import OperationCommand, project_dir
+
+
+def output_path(value):
+    path = Path(value).expanduser().resolve()
+    if path.suffix.lower() != '.png' or path.exists():
+        raise ValueError('输出必须是尚不存在的 .png 文件')
+    return path
+
+
+def save_image(path, content):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('xb') as stream:
+        stream.write(content)
+
+
+class KeyCommand(OperationCommand):
+    def get_help(self, ctx):
+        from ..mcstudio.window import KEYS, ALIASES
+        self.epilog = '键名: ' + ', '.join(sorted(set(KEYS) | set(ALIASES) | {'NUMPAD_ENTER'}))
+        return super().get_help(ctx)
+
+
+@click.command(cls=OperationCommand)
+@click.option('--session', required=True)
+@click.option('--output', required=True, help='本机 PNG 路径，不覆盖已有文件')
+def screenshot_cmd(session, output):
+    """截图到调用端；远程模式会下载 Windows 游戏客户区 PNG。"""
+    from ..mcstudio.window import operate
+    path = output_path(output)
+    result = operate(project_dir(), session, 'screenshot')
+    save_image(path, result.pop('content'))
+    return {'image': str(path), **result}
+
+
+@click.command(cls=KeyCommand)
+@click.option('--session', required=True)
+@click.argument('keys', nargs=-1, required=True)
+@click.option('--hold-ms', type=click.IntRange(20, 60000), default=80, show_default=True)
+def key_cmd(session, keys, hold_ms):
+    """发送键名、组合键或 VK/SC/E0 扫描码，结束时释放；例如 SHIFT+W。"""
+    from ..mcstudio.window import operate
+    return operate(project_dir(), session, 'key', {'keys': keys, 'hold_ms': hold_ms})
+
+
+@click.command(cls=OperationCommand)
+@click.argument('action', type=click.Choice(['move', 'click', 'double-click', 'scroll', 'drag', 'relative']))
+@click.option('--session', required=True)
+@click.option('--x', type=int)
+@click.option('--y', type=int)
+@click.option('--width', type=click.IntRange(1), help='参考截图客户区宽度')
+@click.option('--height', type=click.IntRange(1), help='参考截图客户区高度')
+@click.option('--to-x', type=int, help='拖拽终点')
+@click.option('--to-y', type=int, help='拖拽终点')
+@click.option('--dx', type=int, default=0, help='相对移动总量')
+@click.option('--dy', type=int, default=0)
+@click.option('--delta', type=int, default=0, help='滚轮量，120 为一格，负值向下')
+@click.option('--button', type=click.Choice(['left', 'right', 'middle']), default='left')
+@click.option('--duration-ms', type=click.IntRange(20, 60000), default=80, show_default=True)
+@click.option('--keys', multiple=True, help='同时按住的修饰键，例如 SHIFT 或 CTRL+ALT')
+def mouse_cmd(session, **parameters):
+    """客户区鼠标操作；relative 用于视角转向，其他动作需 x/y/width/height。"""
+    from ..mcstudio.window import operate
+    return operate(project_dir(), session, 'mouse', parameters)

mcpywrap-0.3.6/mcpywrap/commands/doctor_cmd.py

@@ -0,0 +1,30 @@
+"""不创建项目、不启动程序的本机诊断。"""
+import click
+from ..command_context import OperationCommand, project_dir as current_project
+from ..mcstudio.discovery import engine_options
+
+
+@click.command(cls=OperationCommand)
+@engine_options
+@click.option('--mcs-auth', is_flag=True, help='同时只读检查登录组件；不读取身份或安装证书')
+@click.option('--capabilities', is_flag=True, help='报告本机或远端能力，不启动游戏')
+def doctor_cmd(mcs_auth=False, capabilities=False, **overrides):
+    """诊断游戏发现和运行资源（只读，无需初始化项目）"""
+    from ..mcstudio.diagnostics import diagnose
+    if capabilities:
+        from ..remote.service import capabilities as inspect_capabilities
+        return inspect_capabilities()
+    data = diagnose(current_project(), overrides, mcs_auth)
+    from ..command_context import json_output
+    if not json_output():
+        for candidate in data['candidates']:
+            click.echo(f"候选 [{candidate['source']}] {candidate['version']}: {candidate['executable']}")
+        for issue in data['diagnostics']:
+            click.echo(f'{issue["path"]}: {issue["message"]}')
+        for kind, issues in data['resources'].items():
+            for issue in issues:
+                click.echo(f'资源 [{kind}]: {issue}')
+        if mcs_auth:
+            click.echo('登录组件: ' + ('文件齐全，尚未验证登录和系统策略' if data['mcs_auth']['component_available']
+                                     else data['mcs_auth']['error']))
+    return data

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/edit_cmd.py

@@ -25,6 +25,8 @@ from ..utils.project_setup import find_and_configure_behavior_pack
 @click.option("--detach", is_flag=True, help="启动编辑器后返回进程信息")
 def edit_cmd(detach, **engine_overrides):
     """使用 MC Studio Editor 编辑器进行编辑"""
+    if os.name != 'nt':
+        raise click.ClickException('此界面仅支持 Windows 人工操作，不支持远程 GUI')
     # 检查项目是否已初始化
     if not config_exists():
         require_project()

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/mod_cmd.py

@@ -1,5 +1,6 @@
 """用参数生成 Mod 脚本，GUI 向导仅用于人工交互。"""
 import keyword
+import os
 import click
 from ..command_context import OperationCommand, project_dir, non_interactive, require_project
 from ..minecraft.addons import find_behavior_pack_dir
@@ -20,6 +21,8 @@ def mod_cmd(name, version, script_dir, server_system, client_system, gui):
     if not behavior:
         raise click.ClickException('未找到行为包，请先初始化 Addon')
     if gui or (not name and not non_interactive()):
+        if os.name != 'nt':
+            raise click.ClickException('Qt 模板向导仅支持 Windows，请使用 --name 等参数')
         from ..command_context import json_output
         if non_interactive() or json_output():
             raise click.UsageError('Qt 模板向导仅供人工使用；请提供 --name 等生成参数')

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/run_cmd.py

@@ -126,7 +126,7 @@ def _build_dependency_tree(node, tree_node):
 
 def _run_game_with_instance(config_path, level_id, all_packs, wait=True, log_callback=None,
                             engine_overrides=None, no_gui=False, logging_port=None, output_path=None,
-                            auth_context=None, auth_config_path=None):
+                            auth_context=None, auth_config_path=None, capture_output=False):
     """使用指定的实例运行游戏
     
     Args:
@@ -274,7 +274,7 @@ def _run_game_with_instance(config_path, level_id, all_packs, wait=True, log_cal
     
     with console.status("启动游戏中...", spinner="dots"):
         game_process = open_game(launch_config_path, logging_port=logging_port, wait=False, engine=engine,
-                                 **({'capture_output': True} if auth_context is not None else
+                                 **({'capture_output': True} if auth_context is not None or capture_output else
                                     {'output_path': output_path} if output_path else {}))
 
     if not game_process:
@@ -356,7 +356,7 @@ def run_cmd(new, list, delete, force, clean_all, instance_prefix, no_gui, detach
     配置 [tool.mcpywrap.server] host/port 时改为网络连接；默认未认证，
     可用 --mcs-auth 显式读取 MCS 身份，单人测试同样支持此选项。
     不装配本地 Mod，不保证服务器接受连接。网络模式前台采集日志，
-    Ctrl+C 结束本次游戏，暂不支持 --detach。
+    Ctrl+C 结束本次网络游戏；--detach 返回可查询、操作和停止的会话。
     """
     base_dir = str(current_project())
     if (delete or clean_all) and non_interactive() and not force:
@@ -379,11 +379,9 @@ def run_cmd(new, list, delete, force, clean_all, instance_prefix, no_gui, detach
                 target = replace(target, auth='mcs')
             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)
+                               engine_overrides=engine_overrides, detach=detach)
 
     # 确保 map 项目的 setuptools 配置同步
     ensure_map_setuptools_sync(interactive=False)
@@ -470,10 +468,7 @@ def run_cmd(new, list, delete, force, clean_all, instance_prefix, no_gui, detach
         import time
         data = sessions.start(base_dir, config_path, level_id, engine_overrides,
                               **({'auth_context': auth_context} if auth_context is not None else {}))
-        result = {'application': 'game', 'project': base_dir, 'session': data['session'],
-                  'state': data['state'], **data['game'], 'log_path': data['log_path'],
-                  'engine_log_path': data.get('engine_log_path'),
-                  'window_title_hint': 'Minecraft', 'window_verified': False}
+        result = sessions.handoff(data)
         if detach:
             return result
         click.echo('会话: ' + data['session'] + '；日志: ' + data['log_path'])

mcpywrap-0.3.6/mcpywrap/commands/serve_cmd.py

@@ -0,0 +1,35 @@
+"""Manually hosted LAN endpoint in the logged-in Windows desktop."""
+import os
+from pathlib import Path
+import click
+from ..command_context import OperationCommand, json_output
+from ..mcstudio.discovery import engine_options
+
+
+@click.command(cls=OperationCommand)
+@click.option('--host', default='0.0.0.0', show_default=True)
+@click.option('--port', type=click.IntRange(1, 65535), default=18765, show_default=True)
+@click.option('--data-dir', type=click.Path(file_okay=False), help='服务会话与日志目录')
+@engine_options
+def serve_cmd(host, port, data_dir, **engine_overrides):
+    """在当前 Windows 用户桌面启动局域网测试服务；Ctrl+C 清理所属游戏。"""
+    if json_output():
+        raise click.UsageError('serve 是持续服务，不支持 --json')
+    if os.name != 'nt':
+        raise click.ClickException('serve 只能在 Windows 交互桌面启动；macOS 请配置 --remote')
+    from ..remote.service import GameService, directory_lock
+    from ..remote.http_server import GameHTTPServer
+    root = Path(data_dir).expanduser().resolve() if data_dir else Path.home()/'.local/share/mcpywrap/remote'
+    with directory_lock(root):
+        service = GameService(root, {k: v for k, v in engine_overrides.items() if v is not None})
+        try:
+            with GameHTTPServer((host, port), service, os.environ.get('MCPY_REMOTE_TOKEN')) as server:
+                click.echo(f'测试服务: http://{host}:{port}\n数据目录: {root}\n'
+                           f'访问令牌: {"已启用" if server.token else "未启用"}\n'
+                           '保持桌面登录且未锁屏；Ctrl+C 停止服务及所属游戏。')
+                try:
+                    server.serve_forever(poll_interval=.2)
+                except KeyboardInterrupt:
+                    click.echo('正在取消输入并清理所属会话…')
+        finally:
+            service.close()

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/session_cmd.py

@@ -5,18 +5,26 @@ from ..mcstudio import sessions
 
 
 @click.command(cls=OperationCommand, name='status')
-@click.option('--session', required=True)
-def status_cmd(session):
+@click.option('--session')
+@click.option('--list', 'list_sessions', is_flag=True, help='列举会话，远端可用于找回启动结果')
+def status_cmd(session, list_sessions):
     """查询会话；running 只表示进程存活。"""
+    if bool(session) == list_sessions:
+        raise click.UsageError('指定 --session 或 --list 中的一项')
+    if list_sessions:
+        root = project_dir()/'.runtime/sessions'
+        return {'sessions': [sessions.read(project_dir(), p.parent.name)
+                             for p in sorted(root.glob('*/session.json'))]}
     return sessions.read(project_dir(), session)
 
 
 @click.command(cls=OperationCommand, name='logs')
 @click.option('--session', required=True)
 @click.option('--tail', type=click.IntRange(1, 10000), default=100, show_default=True)
-def logs_cmd(session, tail):
+@click.option('--source', type=click.Choice(['game', 'engine', 'worker']), default='game', show_default=True)
+def logs_cmd(session, tail, source):
     """读取会话日志末尾，不等待新日志。"""
-    text = sessions.logs(project_dir(), session, tail)
+    text = sessions.logs(project_dir(), session, tail, source)
     if json_output():
         return {'session': session, 'text': text}
     click.echo(text, nl=False)

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/commands/ui_cmd.py

@@ -16,6 +16,8 @@ def ui_cmd(mcs_auth=False):
     from ..command_context import json_output
     if non_interactive() or json_output():
         raise click.UsageError("Qt 管理页仅供人工使用；Agent 请调用 run、add、remove 等命令")
+    if os.name != 'nt':
+        raise click.ClickException('此界面仅支持 Windows 人工操作，不支持远程 GUI')
     # 检查项目是否已初始化
     if not config_exists():
         require_project()

{mcpywrap-0.3.4 → mcpywrap-0.3.6}/mcpywrap/mcstudio/bridge_assets.py

@@ -9,6 +9,30 @@ BINARIES = ('Injector.exe', 'Loader.dll', 'McpyMcsAuth.dll')
 PAYLOAD = Path(__file__).with_name('bridge_payload')
 
 
+def inspect_bridge():
+    """只检查组件文件；不复制缓存、不读取身份、不改变证书信任。"""
+    override = os.environ.get('MCPY_MCS_BRIDGE_DIR')
+    bundled = not override and (PAYLOAD/'manifest.json').is_file()
+    directory = (Path(override).expanduser().resolve() if override else PAYLOAD if bundled
+                 else Path.home()/'.local/share/mcpywrap/mcs-auth-bridge')
+    result = {'component_available': False, 'directory': str(directory),
+              'source': 'override' if override else 'package' if bundled else 'development',
+              'integrity_verified': False, 'trust_verified': False, 'login_verified': False,
+              'error': None, 'hint': None}
+    try:
+        if bundled:
+            payload_manifest()
+            result['integrity_verified'] = True
+        missing = [name for name in BINARIES if not (directory/name).is_file()]
+        if missing:
+            raise ValueError('缺少登录组件: ' + ', '.join(missing))
+        result['component_available'] = True
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        result.update(error=str(exc), hint='使用包含桥接组件的正式发布包；Git／可编辑安装需另行构建组件，'
+                      '并通过 MCPY_MCS_BRIDGE_DIR 指定目录。组件存在不表示已登录或系统策略允许启用。')
+    return result
+
+
 def digest(path):
     return hashlib.sha256(path.read_bytes()).hexdigest()