mcpywrap 0.3.0__tar.gz → 0.3.2__tar.gz

mcpywrap-0.3.2/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 更新记录
+
+## 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
+
+- 完善游戏引擎自动发现：优先检查当前用户注册表的两个视图，失败后搜索固定磁盘中的标准下载目录。
+- 仅选择包含游戏 EXE 的有效版本目录，跳过残缺安装和杂项目录，按语义版本稳定排序。
+- 支持通过项目配置、环境变量和 CLI 指定游戏 EXE、下载目录及引擎版本；无效覆盖和版本冲突明确报错。
+- 新增只读 `mcpy doctor` 和 JSON 诊断，分别报告游戏、编辑器及 Safaia 的资源状态。
+- CLI 与 GUI 共用发现结果，运行配置和实际 EXE 保持一致；已有实例默认保留原版本，不再自动切换到最新版。
+- 新增 27 项隔离测试，完整回归共 60 项通过；本机只读验证选中 MCS 引擎 3.10.0.420447。
+- 精简 README 为上手指引，将依赖、引擎配置和开发验证细节整理为独立文档。
+
+## 0.3.0
+
+- 新增本地 Addon 目录依赖：CLI、初始化向导和 GUI 支持直接添加、预检和移除目录引用，无需初始化或安装被引用项目。
+- Python 包和本地目录共用依赖图，支持相对路径、真实路径去重、循环检测及标准 requirement 版本和环境标记校验。
+- `build/run/edit/dev` 接入本地依赖；运行前重新校验，避免缓存过期的依赖集合。
+- **构建行为变更**：主项目优先，完整与增量构建统一依赖顺序；删除高优先级文件后恢复低优先级来源。
+- 构建前拒绝输出与源目录重叠；无效依赖不清空已有输出。
+- Windows 链接保留其他项目内容，支持无符号链接权限时使用目录 junction；游戏启动使用实际进程句柄。
+- 修正最低 Python 版本为 3.9，与现有运行代码要求一致。
+- 显式依赖 pip，确保通过 uv 安装的隔离工具环境也能执行 Python 包的添加和初始化安装。
+- 新增自动化测试、打包校验和 GitHub Actions → PyPI Trusted Publishing 流程。
+
+本机已通过 33 项自动化测试及 MCS 3.10.0.420447 的四组实际游戏加载测试。

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

@@ -1,6 +1,8 @@
 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.2/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: mcpywrap
+Version: 0.3.2
+Summary: A wrapper for Minecraft China Edition Addons management
+Author-email: boybook <boybook@easecation.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EaseCation/mcpywrap
+Project-URL: Bug Tracker, https://github.com/EaseCation/mcpywrap/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+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
+Requires-Dist: tomli
+Requires-Dist: tomli-w
+Requires-Dist: setuptools
+Requires-Dist: packaging>=21
+Requires-Dist: PyQt5>=5.15.0
+Requires-Dist: psutil>=5.8.0
+Requires-Dist: rich>=10.0.0
+Dynamic: license-file
+
+# mcpywrap
+
+**用 Python 标准项目与依赖管理方式开发《我的世界》中国版 Mod 和资源包。**
+
+[![PyPI Version](https://img.shields.io/pypi/v/mcpywrap)](https://pypi.org/project/mcpywrap/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+mcpywrap 使用 `pyproject.toml` 管理项目，支持安装 Python 包依赖，也支持直接引用本地 Addon 目录。它将依赖管理、资源构建、游戏运行和 MC Studio 编辑器串成一套开发流程，方便多个项目共享代码与资源。
+
+## 安装
+
+需要 Python 3.9 或更高版本。游戏和编辑器启动功能需要 Windows、MC Studio 及已下载的游戏引擎。
+
+推荐通过 [uv](https://docs.astral.sh/uv/) 安装：
+
+```powershell
+uv tool install mcpywrap
+```
+
+也可以使用 `pip install mcpywrap`。安装完成后，运行 `mcpy --help` 查看命令。
+
+## 开始使用
+
+进入你的 Addon 或地图项目目录，按向导初始化：
+
+```powershell
+mcpy init
+```
+
+之后可以直接运行游戏测试，或在 MC Studio 编辑器中打开项目：
+
+```powershell
+mcpy run
+mcpy edit
+```
+
+需要查看项目和管理依赖时，运行 `mcpy ui` 打开图形界面。
+
+## 复用代码和资源
+
+对于已发布的 Python 包，使用包名添加依赖：
+
+```powershell
+mcpy add "package-name>=1.0"
+```
+
+对于本机已有的 Addon，直接引用它的目录：
+
+```powershell
+mcpy add --path "../shared-addon"
+```
+
+本地 Addon 无需先初始化或安装，可以直接使用 MCS 导出的目录。请选择包含行为包或资源包的 Addon 根目录；相对路径以当前项目目录为基准。
+
+移除依赖使用 `mcpy remove <包名>` 或 `mcpy remove --path <目录>`。移除本地引用不会删除源目录。不带参数运行 `mcpy add` / `mcpy remove` 可进入选择向导。
+
+本地路径适合同机开发；与他人共享项目时，需要同步这些目录，或将可复用组件发布为 Python 包。目录结构、配置及构建规则见[本地依赖参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/local-dependencies.md)。
+
+## 构建与日常开发
+
+| 命令 | 用途 |
+|---|---|
+| `mcpy build` | 将项目和依赖构建到配置的输出目录 |
+| `mcpy package` | 构建项目和依赖，在 `dist` 中生成可分发 ZIP |
+| `mcpy dev` | 监控 Addon 源码与依赖变化，持续更新构建结果 |
+| `mcpy mod` | 通过向导创建 Python Mod 框架 |
+| `mcpy modsdk` | 管理网易 ModSDK |
+| `mcpy run -n` | 创建新的游戏测试实例 |
+| `mcpy run -l` | 查看已有实例 |
+| `mcpy run -d <ID前缀>` | 删除指定实例 |
+
+`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 登记的安装，必要时搜索固定磁盘中的标准下载目录，并跳过不完整的引擎版本。
+
+遇到找不到游戏或缺少资源的提示，先运行：
+
+```powershell
+mcpy doctor
+```
+
+需要使用特定版本时，可以临时指定：
+
+```powershell
+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` 查看该命令的选项。
+- [更新记录](https://github.com/EaseCation/mcpywrap/blob/main/CHANGELOG.md)
+- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/docs/development.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/docs/releasing.md)
+- 欢迎通过 [Issues](https://github.com/EaseCation/mcpywrap/issues) 反馈问题或提交 PR。
+
+[MIT License](LICENSE) © EaseCation

mcpywrap-0.3.2/README.md

@@ -0,0 +1,130 @@
+# mcpywrap
+
+**用 Python 标准项目与依赖管理方式开发《我的世界》中国版 Mod 和资源包。**
+
+[![PyPI Version](https://img.shields.io/pypi/v/mcpywrap)](https://pypi.org/project/mcpywrap/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+mcpywrap 使用 `pyproject.toml` 管理项目，支持安装 Python 包依赖，也支持直接引用本地 Addon 目录。它将依赖管理、资源构建、游戏运行和 MC Studio 编辑器串成一套开发流程，方便多个项目共享代码与资源。
+
+## 安装
+
+需要 Python 3.9 或更高版本。游戏和编辑器启动功能需要 Windows、MC Studio 及已下载的游戏引擎。
+
+推荐通过 [uv](https://docs.astral.sh/uv/) 安装：
+
+```powershell
+uv tool install mcpywrap
+```
+
+也可以使用 `pip install mcpywrap`。安装完成后，运行 `mcpy --help` 查看命令。
+
+## 开始使用
+
+进入你的 Addon 或地图项目目录，按向导初始化：
+
+```powershell
+mcpy init
+```
+
+之后可以直接运行游戏测试，或在 MC Studio 编辑器中打开项目：
+
+```powershell
+mcpy run
+mcpy edit
+```
+
+需要查看项目和管理依赖时，运行 `mcpy ui` 打开图形界面。
+
+## 复用代码和资源
+
+对于已发布的 Python 包，使用包名添加依赖：
+
+```powershell
+mcpy add "package-name>=1.0"
+```
+
+对于本机已有的 Addon，直接引用它的目录：
+
+```powershell
+mcpy add --path "../shared-addon"
+```
+
+本地 Addon 无需先初始化或安装，可以直接使用 MCS 导出的目录。请选择包含行为包或资源包的 Addon 根目录；相对路径以当前项目目录为基准。
+
+移除依赖使用 `mcpy remove <包名>` 或 `mcpy remove --path <目录>`。移除本地引用不会删除源目录。不带参数运行 `mcpy add` / `mcpy remove` 可进入选择向导。
+
+本地路径适合同机开发；与他人共享项目时，需要同步这些目录，或将可复用组件发布为 Python 包。目录结构、配置及构建规则见[本地依赖参考](https://github.com/EaseCation/mcpywrap/blob/main/docs/local-dependencies.md)。
+
+## 构建与日常开发
+
+| 命令 | 用途 |
+|---|---|
+| `mcpy build` | 将项目和依赖构建到配置的输出目录 |
+| `mcpy package` | 构建项目和依赖，在 `dist` 中生成可分发 ZIP |
+| `mcpy dev` | 监控 Addon 源码与依赖变化，持续更新构建结果 |
+| `mcpy mod` | 通过向导创建 Python Mod 框架 |
+| `mcpy modsdk` | 管理网易 ModSDK |
+| `mcpy run -n` | 创建新的游戏测试实例 |
+| `mcpy run -l` | 查看已有实例 |
+| `mcpy run -d <ID前缀>` | 删除指定实例 |
+
+`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 登记的安装，必要时搜索固定磁盘中的标准下载目录，并跳过不完整的引擎版本。
+
+遇到找不到游戏或缺少资源的提示，先运行：
+
+```powershell
+mcpy doctor
+```
+
+需要使用特定版本时，可以临时指定：
+
+```powershell
+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` 查看该命令的选项。
+- [更新记录](https://github.com/EaseCation/mcpywrap/blob/main/CHANGELOG.md)
+- [开发与验证](https://github.com/EaseCation/mcpywrap/blob/main/docs/development.md) · [发布流程](https://github.com/EaseCation/mcpywrap/blob/main/docs/releasing.md)
+- 欢迎通过 [Issues](https://github.com/EaseCation/mcpywrap/issues) 反馈问题或提交 PR。
+
+[MIT License](LICENSE) © EaseCation

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.0 → mcpywrap-0.3.2}/mcpywrap/__init__.py

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

{mcpywrap-0.3.0 → 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,22 +10,34 @@ 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
 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')
@@ -32,11 +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()
+    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}')