mcpywrap 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -1,5 +1,16 @@
 # 更新记录
 
+## 0.3.2
+
+- 新增 `package`，构建项目及依赖并生成分发 ZIP，失败保留已有产物。
+- CLI 共用 `--project`、`--non-interactive`、`--json` 与明确退出码；初始化、Mod 模板和 SDK 安装可通过参数操作。
+- 新增 `sync`；发布命令改用标准 Python 构建及 Twine，预检凭据并只上传本次构建产物。
+- 新增无辅助 GUI 的游戏会话与 `status/logs/stop`，核对进程身份、提前监听日志、分离引擎输出，并兼容中文 SDK 日志。
+- 提供可单独安装的标准 Skill，包含 uv 安装、冒烟验证、游戏截图和键盘输入脚本；支持组合键、扫描码和有界长按，异常时释放按键。
+- 精简操作文档，补充 Skill 安装入口；Computer Use 只接手复杂游戏画面操作，不接手 Qt 管理页。
+- **使用变化**：非交互环境缺少参数立即失败；初始化不再隐式安装项目或 SDK，分别使用 `sync --install`、`modsdk`；`ui` 仅供人工交互。
+- 112 项回归测试通过，并完成本机游戏日志、截图、组合移动和会话停止验证。
+
 ## 0.3.1
 
 - 完善游戏引擎自动发现：优先检查当前用户注册表的两个视图，失败后搜索固定磁盘中的标准下载目录。

{mcpywrap-0.3.1 → mcpywrap-0.3.2}/MANIFEST.in

@@ -2,6 +2,7 @@ include LICENSE README.md CHANGELOG.md
 include docs/releasing.md
 include docs/local-dependencies.md docs/engine-discovery.md docs/development.md
 recursive-include tests *.py
+recursive-include skills *.md *.yaml *.ps1 *.py
 prune test
 prune .git
 global-exclude __pycache__ *.py[cod] *.cppconfig *.log

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap
-Version: 0.3.1
+Version: 0.3.2
 Summary: A wrapper for Minecraft China Edition Addons management
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT
@@ -12,6 +12,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pip>=21
+Requires-Dist: build>=1.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: watchdog>=2.0.0
 Requires-Dist: twine>=3.4.0
@@ -87,6 +88,7 @@ mcpy add --path "../shared-addon"
 | 命令 | 用途 |
 |---|---|
 | `mcpy build` | 将项目和依赖构建到配置的输出目录 |
+| `mcpy package` | 构建项目和依赖，在 `dist` 中生成可分发 ZIP |
 | `mcpy dev` | 监控 Addon 源码与依赖变化，持续更新构建结果 |
 | `mcpy mod` | 通过向导创建 Python Mod 框架 |
 | `mcpy modsdk` | 管理网易 ModSDK |
@@ -96,6 +98,14 @@ mcpy add --path "../shared-addon"
 
 `mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
 
+### 打包分发
+
+在项目根目录执行 `mcpy package`，会先构建项目及 Python 包／本地 Addon 依赖，再生成 `dist/<项目名>-<版本>.zip`。名称和版本读取 `pyproject.toml` 的 `[project]`；不需要配置 `target_dir`。
+
+Addon ZIP 内为 `<项目名>_bp/`、`<项目名>_rp/`（仅包含实际构建出的包）；地图 ZIP 根目录直接包含存档数据、行为包、资源包及世界包配置。地图默认保留独立包，使用 `mcpy package --merge`（或 `-m`）按构建规则合并依赖资源。构建产物中的空目录会保留。
+
+重复打包成功后会替换同名 ZIP；失败时保留已有 ZIP，临时文件自动清理。
+
 ## 游戏启动与排查
 
 通常不需要手动指定游戏路径。mcpywrap 会优先查找 MC Studio 登记的安装，必要时搜索固定磁盘中的标准下载目录，并跳过不完整的引擎版本。
@@ -114,6 +124,29 @@ mcpy run --engine-version 3.10.0.420447
 
 已有实例默认保留原引擎版本；显式指定版本可以切换。自定义路径、项目级设置和环境变量的用法见[引擎配置参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/engine-discovery.md)。
 
+## AI Agent 使用
+
+仓库提供标准 [mcpywrap Skill](https://github.com/EaseCation/mcpywrap/tree/main/skills/mcpywrap)，帮助 Agent 安装工具、管理依赖、
+构建打包、启动游戏和检查日志，并通过自带脚本截图、发送组合键与模拟移动。
+
+**安装 Skill**：可对支持 Skill 安装的 Agent 说：
+
+> 请安装 GitHub 仓库 EaseCation/mcpywrap 中 skills/mcpywrap 目录下的 Skill。
+
+也可以下载仓库 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 为这个 Addon 添加本地依赖，并生成分发 ZIP。”
+- “启动这个项目，不弹日志界面，检查客户端和服务端的加载日志。”
+- “启动游戏并截图，模拟组合按键移动，检查 F11 输入模式和 F3 调试信息层。”
+
+Agent 通过 CLI 管理项目，Skill 自带游戏截图与键盘输入脚本；复杂游戏交互交给 Computer Use。Qt 管理与模板界面用于人工操作。
+常用入口：`mcpy --project <目录> --non-interactive <命令> --json`。
+
 ## 更多信息
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。

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

@@ -61,6 +61,7 @@ mcpy add --path "../shared-addon"
 | 命令 | 用途 |
 |---|---|
 | `mcpy build` | 将项目和依赖构建到配置的输出目录 |
+| `mcpy package` | 构建项目和依赖，在 `dist` 中生成可分发 ZIP |
 | `mcpy dev` | 监控 Addon 源码与依赖变化，持续更新构建结果 |
 | `mcpy mod` | 通过向导创建 Python Mod 框架 |
 | `mcpy modsdk` | 管理网易 ModSDK |
@@ -70,6 +71,14 @@ mcpy add --path "../shared-addon"
 
 `mcpy run` 默认复用最近创建的实例。构建时主项目内容优先于依赖；修改依赖声明后，请重新启动 `mcpy dev`。
 
+### 打包分发
+
+在项目根目录执行 `mcpy package`，会先构建项目及 Python 包／本地 Addon 依赖，再生成 `dist/<项目名>-<版本>.zip`。名称和版本读取 `pyproject.toml` 的 `[project]`；不需要配置 `target_dir`。
+
+Addon ZIP 内为 `<项目名>_bp/`、`<项目名>_rp/`（仅包含实际构建出的包）；地图 ZIP 根目录直接包含存档数据、行为包、资源包及世界包配置。地图默认保留独立包，使用 `mcpy package --merge`（或 `-m`）按构建规则合并依赖资源。构建产物中的空目录会保留。
+
+重复打包成功后会替换同名 ZIP；失败时保留已有 ZIP，临时文件自动清理。
+
 ## 游戏启动与排查
 
 通常不需要手动指定游戏路径。mcpywrap 会优先查找 MC Studio 登记的安装，必要时搜索固定磁盘中的标准下载目录，并跳过不完整的引擎版本。
@@ -88,6 +97,29 @@ mcpy run --engine-version 3.10.0.420447
 
 已有实例默认保留原引擎版本；显式指定版本可以切换。自定义路径、项目级设置和环境变量的用法见[引擎配置参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/engine-discovery.md)。
 
+## AI Agent 使用
+
+仓库提供标准 [mcpywrap Skill](https://github.com/EaseCation/mcpywrap/tree/main/skills/mcpywrap)，帮助 Agent 安装工具、管理依赖、
+构建打包、启动游戏和检查日志，并通过自带脚本截图、发送组合键与模拟移动。
+
+**安装 Skill**：可对支持 Skill 安装的 Agent 说：
+
+> 请安装 GitHub 仓库 EaseCation/mcpywrap 中 skills/mcpywrap 目录下的 Skill。
+
+也可以下载仓库 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 为这个 Addon 添加本地依赖，并生成分发 ZIP。”
+- “启动这个项目，不弹日志界面，检查客户端和服务端的加载日志。”
+- “启动游戏并截图，模拟组合按键移动，检查 F11 输入模式和 F3 调试信息层。”
+
+Agent 通过 CLI 管理项目，Skill 自带游戏截图与键盘输入脚本；复杂游戏交互交给 Computer Use。Qt 管理与模板界面用于人工操作。
+常用入口：`mcpy --project <目录> --non-interactive <命令> --json`。
+
 ## 更多信息
 
 - 运行 `mcpy <命令> --help` 查看该命令的选项。

mcpywrap-0.3.2/docs/development.md

@@ -0,0 +1,24 @@
+# 维护者：开发与验证
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+自动化测试使用临时目录、模拟安装/发布、Qt 离屏界面和模拟游戏进程，不启动真实游戏。
+CLI 使用调用上下文传递项目目录；底层服务接受明确路径。不要为 GUI 切换全局工作目录。
+
+有限命令返回数据或抛出错误，公共 CLI 层负责 JSON、stderr 和退出码。
+新增命令使用相同入口，避免打印错误后返回成功。
+
+Skill 的 bootstrap、smoke 脚本只使用公开 CLI；Skill 的 game_window 脚本负责绑定会话的截图和键盘输入；复杂交互使用环境的 Computer Use。
+真实游戏验证请使用独立测试项目：
+
+```powershell
+python skills/mcpywrap/scripts/smoke.py --project D:\mods\test --game --expect-log "服务端已加载" --expect-log "客户端已加载"
+```
+
+脚本结束后停止自己创建的会话；日志和产物留在项目中。
+需要手动截图验证时直接运行 `run --no-gui --detach --json`，保存会话 ID，操作完后显式 stop。
+历史验收记录仅用于追溯，不能代替当前版本测试。
+
+发布见 [发布流程](releasing.md)。

mcpywrap-0.3.2/docs/engine-discovery.md

@@ -0,0 +1,55 @@
+# 游戏启动与排查
+
+先检查本机环境：
+
+```powershell
+mcpy doctor
+mcpy doctor --json
+```
+
+诊断分别显示游戏、编辑器、Safaia 是否就绪。编辑器缺失不等于无法运行游戏。
+默认优先使用 MC Studio 登记的安装，必要时搜索固定磁盘中的标准下载目录；不完整的版本会被跳过。
+
+## 找不到游戏
+
+确认已通过 MC Studio 下载引擎；自定义位置可指定下载目录或 EXE：
+
+```powershell
+mcpy doctor --mcs-download-path 'D:\MCStudioDownload'
+mcpy run --game-executable 'D:\MCStudioDownload\game\MinecraftPE_Netease\3.10.0.420447\Minecraft.Windows.exe'
+```
+
+选择某个完整版本：
+
+```powershell
+mcpy run --engine-version 3.10.0.420447
+```
+
+已有实例保留原版本；显式指定可切换版本。`3.10` 不是 `3.10.*` 通配符；不存在时明确报错。
+
+## 保存配置
+
+| 项目中的 `[tool.mcpywrap]` 字段 | 本机环境变量 |
+|---|---|
+| `game_executable_path` | `MCPY_GAME_EXECUTABLE` |
+| `mcs_download_path` | `MCPY_MCS_DOWNLOAD_PATH` |
+| `engine_version` | `MCPY_ENGINE_VERSION` |
+
+命令行优先于环境变量，环境变量优先于项目配置。团队通常只提交版本，本机路径放在环境变量。
+项目配置的相对路径以项目为基准；CLI 和环境变量的相对路径以调用目录为基准。
+
+EXE 不在版本目录时，需要另外声明 `engine_version`；这不验证二进制内部版本。
+独立 EXE 仍需要下载目录中的皮肤和游戏用户数据，缺项按 doctor 的实际路径提示补齐。
+同时配置 EXE 与下载目录时不能指向不同的标准安装。
+
+## 不打开辅助界面
+
+```powershell
+mcpy --project D:\mods\demo --non-interactive run --no-gui --detach --json
+mcpy --project D:\mods\demo logs --session <id> --tail 100 --json
+mcpy --project D:\mods\demo stop --session <id> --json
+```
+
+只打开游戏窗口，日志写入返回的文件。`running` 表示进程存活，加载是否成功应查看项目日志或游戏画面。
+Computer Use 只接手游戏画面；Qt 管理、模板及日志页留给人工操作。
+本功能不包含第三方网络服 IP/端口连接。

mcpywrap-0.3.2/docs/local-dependencies.md

@@ -0,0 +1,30 @@
+# 复用本地 Addon
+
+已有的 Addon 可以直接作为依赖，不需要先初始化或安装。
+
+```powershell
+mcpy add --path "../shared-addon"
+mcpy remove --path "../shared-addon"
+```
+
+请选择 Addon 根目录，例如：
+
+```text
+shared-addon/
+  behavior_pack/manifest.json
+  resource_pack/manifest.json
+```
+
+可以只有行为包或资源包；目录名也支持工具识别的 `BehaviorPack*`、`ResourcePack*` 等名称。
+不支持直接引用单个包目录、地图、普通源码目录，或同一 Addon 中多个同类型包。
+
+引用保存在 `tool.mcpywrap.local_dependencies`，相对路径以声明它的项目为基准。
+移除引用不会删除源目录。已有 mcpywrap 项目的子依赖会一并解析；循环依赖或失效路径会报错。
+
+需要发布的 Python 包使用 `mcpy add "package-name>=1.0"`。本地路径不会自动转换为可分发的包依赖；
+共享项目时需同步引用目录，或把组件发布为 Python 包。本地引用的包依赖未安装时，按警告显式安装。
+
+构建时主项目优先于依赖；同级依赖按声明顺序处理，后者覆盖重复内容。
+这不代表游戏运行时的资源包优先级。修改依赖声明后重启 `mcpy dev`。
+
+遇到结构错误先核对目录和清单；查看参数使用 `mcpy add --help`。

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

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

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

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 
 import click
+from . import __version__
+from .command_context import OperationGroup, configure_context
 
 from .commands.run_cmd import run_cmd
 from .commands.init_cmd import init_cmd
@@ -8,6 +10,7 @@ from .commands.add_cmd import add_cmd
 from .commands.remove_cmd import remove_cmd
 from .commands.build_cmd import build_cmd
 from .commands.dev_cmd import dev_cmd
+from .commands.package_cmd import package_cmd
 from .commands.publish_cmd import publish_cmd
 from .commands.default_cmd import default_cmd
 from .commands.modsdk_cmd import modsdk_cmd
@@ -15,16 +18,26 @@ from .commands.mod_cmd import mod_cmd
 from .commands.edit_cmd import edit_cmd
 from .commands.ui_cmd import ui_cmd
 from .commands.doctor_cmd import doctor_cmd
+from .commands.sync_cmd import sync_cmd
+from .commands.session_cmd import status_cmd, logs_cmd, stop_cmd
 
 
-@click.group(invoke_without_command=True)
+@click.group(cls=OperationGroup, invoke_without_command=True)
+@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.version_option(__version__)
 @click.pass_context
-def cli(ctx):
+def cli(ctx, project, non_interactive, json_output):
     """mcpywrap - 《我的世界》中国版 依赖管理与项目构建工具"""
+    configure_context(project, non_interactive)
     # 如果没有提供子命令，则运行 default_cmd
     if ctx.invoked_subcommand is None:
         # 导入并运行默认命令
-        default_cmd()
+        from .command_context import non_interactive as unattended
+        if unattended():
+            raise click.UsageError("请指定子命令，例如 doctor、init 或 sync")
+        return default_cmd.callback()
 
 # 注册其他子命令
 cli.add_command(modsdk_cmd, name='modsdk')
@@ -33,12 +46,17 @@ cli.add_command(add_cmd, name='add')
 cli.add_command(remove_cmd, name='remove')
 cli.add_command(build_cmd, name='build')
 cli.add_command(dev_cmd, name='dev')
+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(edit_cmd, name='edit')
 cli.add_command(ui_cmd, name='ui')
 cli.add_command(doctor_cmd, name='doctor')
+cli.add_command(sync_cmd, name='sync')
+cli.add_command(status_cmd)
+cli.add_command(logs_cmd)
+cli.add_command(stop_cmd)
 
 if __name__ == '__main__':
     cli()

mcpywrap-0.3.2/mcpywrap/command_context.py

@@ -0,0 +1,130 @@
+"""CLI 的项目上下文、交互策略和统一输出；不改变进程工作目录。"""
+import contextlib
+import contextvars
+import json
+import os
+import sys
+import tempfile
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+
+@dataclass
+class CommandContext:
+    project: Path
+    non_interactive: bool = False
+    json_output: bool = False
+
+
+_context = contextvars.ContextVar('mcpy_context', default=None)
+
+
+def project_dir():
+    current = _context.get()
+    return current.project if current else Path.cwd()
+
+
+def non_interactive():
+    current = _context.get()
+    return bool(current and current.non_interactive) or not sys.stdin.isatty()
+
+
+def json_output():
+    current = _context.get()
+    return bool(current and current.json_output)
+
+
+@contextlib.contextmanager
+def project_scope(path):
+    previous = _context.get()
+    token = _context.set(CommandContext(Path(path).resolve(),
+                                       previous.non_interactive if previous else False,
+                                       previous.json_output if previous else False))
+    try:
+        yield
+    finally:
+        _context.reset(token)
+
+
+def require_project():
+    if not (project_dir() / 'pyproject.toml').is_file():
+        raise click.ClickException('未找到 pyproject.toml；请先执行 mcpy init --type addon 或 --type map')
+
+
+class OperationCommand(click.Command):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.params.append(click.Option(['--json', 'json_output'], is_flag=True,
+                                        help='输出单个 JSON 结果'))
+
+    def invoke(self, ctx):
+        ctx.params.pop('json_output', None)
+        return super().invoke(ctx)
+
+
+class OperationGroup(click.Group):
+    def main(self, args=None, prog_name=None, complete_var=None, standalone_mode=True, **extra):
+        args = list(sys.argv[1:] if args is None else args)
+        structured = '--json' in args and '--help' not in args
+        output = sys.stdout
+        state = CommandContext(Path.cwd(), '--non-interactive' in args, structured)
+        token = _context.set(state)
+        code, result = 0, None
+        try:
+            with contextlib.redirect_stdout(sys.stderr) if structured else contextlib.nullcontext():
+                try:
+                    result = super().main(args=args, prog_name=prog_name, complete_var=complete_var,
+                                          standalone_mode=False, **extra)
+                    if isinstance(result, dict) and result.get('ok') is False:
+                        code = 1
+                except click.ClickException as exc:
+                    code = exc.exit_code
+                    result = {'ok': False, 'error': exc.format_message(),
+                              'hint': '使用 mcpy <命令> --help 查看所需参数。'}
+                except (KeyboardInterrupt, click.Abort):
+                    code = 130
+                    result = {'ok': False, 'error': '操作已中断', 'hint': None}
+                except (ValueError, OSError) as exc:
+                    code = 1
+                    result = {'ok': False, 'error': str(exc), 'hint': '请核对项目配置和相关文件路径。'}
+                except Exception as exc:
+                    code = 1
+                    with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', prefix='mcpy-error-',
+                                                     suffix='.log', delete=False) as log:
+                        traceback.print_exc(file=log)
+                    result = {'ok': False, 'error': str(exc), 'hint': f'意外错误详情: {log.name}'}
+            if isinstance(result, int):
+                code = result
+                result = None
+            if structured:
+                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)
+            elif code:
+                click.echo('错误: ' + str((result or {}).get('error') or '操作失败'), err=True)
+                if (result or {}).get('hint'):
+                    click.echo(result['hint'], err=True)
+            elif isinstance(result, dict):
+                # 保留命令原有进度输出，为交接和产物结果补充可读信息。
+                for key, value in result.items():
+                    if key not in ('ok', 'error', 'hint') and value is not None:
+                        click.echo(f'{key}: {value}')
+        finally:
+            _context.reset(token)
+        if standalone_mode:
+            raise SystemExit(code)
+        if code:
+            raise click.exceptions.Exit(code)
+        return result
+
+
+def configure_context(project, interactive_disabled):
+    current = _context.get()
+    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}')

{mcpywrap-0.3.1 → mcpywrap-0.3.2}/mcpywrap/commands/add_cmd.py

@@ -2,18 +2,19 @@
 import os
 from pathlib import Path
 import click
+from ..command_context import OperationCommand, project_dir as current_project, non_interactive, require_project
 from ..dependencies import DependencyDeclaration, DependencyError, DependencyService
 from .dependency_prompt import prompt_dependency, require_interactive
 
 
-@click.command()
+@click.command(cls=OperationCommand)
 @click.argument('package', required=False)
 @click.option('--path', 'local_path', help='直接引用本地 Addon 根目录，不安装目录')
 def add_cmd(package, local_path):
     """添加依赖；不带参数时进入类型选择向导。"""
     if package is not None and local_path is not None:
         raise click.UsageError('包名与 --path 不能同时使用')
-    if not (Path.cwd() / 'pyproject.toml').exists():
+    if not (current_project() / 'pyproject.toml').exists():
         raise click.ClickException('项目尚未初始化，请先运行 mcpy init')
     try:
         if package is None and local_path is None:
@@ -21,7 +22,7 @@ def add_cmd(package, local_path):
             entry = prompt_dependency()
         else:
             entry = DependencyDeclaration('local' if local_path is not None else 'package', local_path if local_path is not None else package)
-        service = DependencyService(os.getcwd())
+        service = DependencyService(str(current_project()))
         if entry.kind == 'local':
             changed, warnings = service.add_local(entry.value)
             for warning in warnings:
@@ -30,5 +31,6 @@ def add_cmd(package, local_path):
             click.echo(f'正在安装 {entry.value}...')
             changed = service.add_package(entry.value)
         click.secho('依赖已添加' if changed else '依赖已存在', fg='green')
+        return {'changed': changed, 'dependency': entry.value, 'source': entry.kind, 'warnings': warnings if entry.kind == 'local' else []}
     except (DependencyError, OSError) as exc:
         raise click.ClickException(str(exc)) from exc

{mcpywrap-0.3.1 → mcpywrap-0.3.2}/mcpywrap/commands/build_cmd.py

@@ -4,22 +4,21 @@
 """
 import os
 import click
+from ..command_context import OperationCommand, project_dir as current_project, non_interactive, require_project
 from ..config import config_exists, get_mcpywrap_config, get_project_type, ensure_map_setuptools_sync
 from ..builders.project_builder import AddonProjectBuilder, MapProjectBuilder
 
 
-base_dir = os.getcwd()
 
-@click.command()
+@click.command(cls=OperationCommand)
 @click.option('--merge', '-m', is_flag=True, help='强制合并所有资源文件')
 def build_cmd(merge):
     """构建为 MCStudio 工程"""
     if not config_exists():
-        click.secho('❌ 错误: 未找到配置文件。请先运行 `mcpywrap init` 初始化项目。', fg="red")
-        return False
+        require_project()
     
     # 确保 map 项目的 setuptools 配置同步
-    ensure_map_setuptools_sync(interactive=True)
+    ensure_map_setuptools_sync(interactive=False)
     
     # 获取mcpywrap特定配置
     mcpywrap_config = get_mcpywrap_config()
@@ -28,14 +27,15 @@ def build_cmd(merge):
 
     if not target_dir:
             click.secho('❌ 错误: 配置文件中未找到target_dir。请手动添加。', fg="red")
-            return False
+            raise click.ClickException("缺少 target_dir，请设置 tool.mcpywrap.target_dir")
     
     # 转换为绝对路径
-    target_dir = os.path.normpath(os.path.join(os.getcwd(), target_dir))
+    target_dir = os.path.normpath(os.path.join(str(current_project()), target_dir))
 
     # 实际构建
-    if not build(os.getcwd(), target_dir, force_merge=merge):
+    if not build(str(current_project()), target_dir, force_merge=merge):
         raise click.ClickException('构建失败')
+    return {'output': target_dir}
 
     
 def build(source_dir, target_dir, force_merge: bool = False):

mcpywrap-0.3.2/mcpywrap/commands/default_cmd.py

@@ -0,0 +1,14 @@
+"""交互入口复用初始化与项目同步。"""
+import click
+from ..command_context import OperationCommand, project_dir, non_interactive
+from .init_cmd import init
+from .sync_cmd import sync_project
+
+
+@click.command(cls=OperationCommand)
+def default_cmd():
+    if non_interactive():
+        raise click.UsageError('请明确指定 init 或 sync 子命令')
+    if not (project_dir() / 'pyproject.toml').exists():
+        return init()
+    return sync_project(project_dir(), install=True)

{mcpywrap-0.3.1 → mcpywrap-0.3.2}/mcpywrap/commands/dependency_prompt.py

@@ -1,12 +1,13 @@
 """命令行依赖类型选择；显式参数路径不会进入向导。"""
 import sys
 import click
+from ..command_context import non_interactive
 from packaging.requirements import Requirement, InvalidRequirement
 from ..dependencies import DependencyDeclaration, DependencyError
 
 
 def require_interactive():
-    if not sys.stdin.isatty():
+    if non_interactive():
         raise click.UsageError('请提供包名或 --path 目录；交互向导需要终端。')
 
 

{mcpywrap-0.3.1 → mcpywrap-0.3.2}/mcpywrap/commands/dev_cmd.py

@@ -6,6 +6,7 @@
 import os
 import time
 import click
+from ..command_context import OperationCommand, project_dir as current_project, non_interactive, require_project
 from ..config import get_mcpywrap_config, config_exists, read_config, get_project_type, CONFIG_FILE, ensure_map_setuptools_sync
 from ..builders.watcher import ProjectWatcher
 from .build_cmd import build
@@ -24,22 +25,25 @@ def file_change_callback(src_path, dest_path, success, output, is_python, is_dep
     else:
         click.secho(f'❌ 处理失败 {output}', fg="red")
 
-@click.command()
+@click.command(cls=OperationCommand)
 def dev_cmd():
     """使用watch模式，实时构建为 MCStudio 工程，代码更新时，自动构建"""
+    from ..command_context import json_output
+    if json_output():
+        raise click.UsageError("dev 持续输出文本日志，不支持 --json")
     if not config_exists():
         click.secho('❌ 错误: 未找到配置文件。请先运行 `mcpywrap init` 初始化项目。', fg="red")
         raise click.ClickException('无法启动开发监控')
     
     # 确保 map 项目的 setuptools 配置同步
-    ensure_map_setuptools_sync(interactive=True)
+    ensure_map_setuptools_sync(interactive=False)
     
     # 获取mcpywrap特定配置
     mcpywrap_config = get_mcpywrap_config()
 
     if get_project_type() == "addon":
         # 源代码目录固定为当前目录
-        source_dir = os.getcwd()
+        source_dir = str(current_project())
         # 目标目录从配置中读取
         target_dir = mcpywrap_config.get('target_dir')
         
@@ -83,6 +87,7 @@ def dev_cmd():
         except KeyboardInterrupt:
             project_watcher.stop()
             click.secho("🛑 监控已停止", fg="bright_yellow")
+            raise
     else:
         click.secho('❌ 暂未支持: 当前仅支持Addons项目的构建', fg="red")
-        raise click.ClickException('无法启动开发监控')
+        raise click.ClickException('无法启动开发监控')

mcpywrap-0.3.2/mcpywrap/commands/doctor_cmd.py

@@ -0,0 +1,33 @@
+"""不创建项目、不启动程序的本机诊断。"""
+import click
+from ..command_context import OperationCommand, project_dir as current_project, non_interactive, require_project
+
+from ..mcstudio.discovery import (
+    discover_engines, engine_options, resource_issues, studio_installation,
+)
+
+
+@click.command(cls=OperationCommand)
+@engine_options
+def doctor_cmd(**overrides):
+    """诊断游戏发现和运行资源（只读，无需初始化项目）"""
+    result = discover_engines(current_project(), overrides=overrides)
+    data = result.to_dict()
+    data['resources'] = {'run': [], 'editor': [], 'safaia': []}
+    if result.selected:
+        data['resources']['run'] = resource_issues(result.selected)
+        data['resources']['editor'] = resource_issues(result.selected, 'editor')
+    for purpose in ('editor', 'safaia'):
+        _, issues = studio_installation(purpose)
+        data['resources'][purpose].extend(issues)
+    data['ok'] = bool(result.selected and not result.error and not data['resources']['run'])
+    from ..command_context import json_output
+    if not json_output():
+        for candidate in result.candidates:
+            click.echo(f'候选 [{candidate.source}] {candidate.version}: {candidate.executable}')
+        for issue in result.diagnostics:
+            click.echo(f'{issue["path"]}: {issue["message"]}')
+        for kind, issues in data['resources'].items():
+            for issue in issues:
+                click.echo(f'资源 [{kind}]: {issue}')
+    return data