Skip to content

README_CN.md

Latest commit

 

History

History
147 lines (112 loc) · 7.38 KB

README_CN.md

File metadata and controls

147 lines (112 loc) · 7.38 KB
Raw

MCDebugLauncher

专为快速测试、Mod 开发和 AI 代理自动化设计的命令行 Minecraft 启动器。支持所有主流 Mod 加载器（Forge、NeoForge、Fabric、Quilt、OptiFine）、全面的错误诊断，以及用于程序化控制的结构化输出。

English Documentation

特性

  • 单命令启动: 单条命令安装并启动任意 Minecraft 版本和任意 Mod 加载器
  • 多加载器支持: Vanilla、Forge、NeoForge、Fabric、Quilt、LegacyFabric、OptiFine、Aprism JE Native
  • Agent 游戏操控（Despotes）: 不抢占焦点地观察与操控运行中的游戏——GPU 截图（Windows.Graphics.Capture + 游戏内帧缓冲）、输入注入（按键/鼠标/视角/聊天）、状态查询；切到别的应用游戏仍继续运行（自动处理 pauseOnLostFocus）
  • Modrinth 整合包导入: mdl import 按整合包声明的版本/加载器创建实例，复制 overrides 并自动补全所有缺失文件（sha1 校验、幂等）
  • JE 专用服务器: mdl server create/launch/stop 下载官方 server.jar、管理 eula/properties、后台运行
  • 镜像与可靠下载: 内置官方 + 国内镜像源实时测活、分块并行下载、自动换源、sha1 校验的 7 天副本安装缓存
  • 内容搜索安装: 一条命令从 Modrinth 搜索并安装 mod/资源包/光影
  • 微软账号: 设备码登录（无头友好）、账号列表、皮肤下载
  • 完整性与自修复: 启动前校验客户端 JAR、库与资源文件，损坏自动重新下载；启动时自动补装 Fabric API
  • 智能诊断: 自动崩溃报告收集、日志分析和错误检测
  • 代理友好: JSON 结构化输出，内置带启动进度与游戏就绪事件的 HTTP/WebSocket 服务器
  • 实例管理: Mod 管理、配置导入导出、世界备份恢复、可选启动队列（--no-queue）
  • 中文本地化: --lang zh 消息与 Windows UTF-8 控制台输出

快速开始

# 创建并启动 Fabric 实例（自动安装 Fabric API + ModMenu）
mdl create my-instance --mc-version 1.21.1 --loader fabric
mdl launch my-instance

# 导入 Modrinth 整合包（.mrpack）自动补全
mdl import my-pack ./cool-pack.mrpack

# 搜索并安装内容
mdl search mod sodium --mc-version 1.21.1 --loader fabric --instance my-instance

# 后台带 agent 控制启动，等待游戏就绪广播
mdl launch my-instance --detach --agent --wait-ready
mdl game status my-instance
mdl game screenshot my-instance --output shot.png

# JE 专用服务器
mdl server create my-server --mc-version 1.21.4
mdl server launch my-server
mdl server stop my-server

# Mod / 备份 / 诊断管理
mdl mod list my-instance
mdl backup create my-instance world1
mdl logs my-instance --follow
mdl diagnose my-instance --analyze

Agent API

MCDebugLauncher 内置 HTTP/WebSocket 服务器，供 AI 代理和自动化工具进行程序化控制。

# 启动 agent 服务器
mdl agent --port 8080

REST API:

# 获取服务器状态
curl http://localhost:8080/api/v1/status

# 执行命令
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"command":"list","args":[],"options":{}}'

WebSocket 事件流:

import asyncio
import websockets

async def listen():
    async with websockets.connect("ws://localhost:8080/api/v1/events") as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"[{event['type']}] {event.get('message', '')}")

完整 API 文档请查看 docs/specification.md。

文档

状态

当前版本: v26.5

v26.5 主线主题：自主编排与运行时选择——agent 以事件而非轮询观察并驱动活游戏、按实例绑定 Java 运行时、以声明式方式表达多步意图。依据 v26.4.0 强制鲁棒性评估规划，并在独立 v26.5 分支开发。

v26.5 亮点（Alpha 1–9）：

  • ✅ 安全：mdl jdk remove 路径穿越修复（PoC 确证）、下载资产名写入守卫
  • ✅ Agent API 错误面统一：全 JSON 错误信封、客户端错误 400（非 502）、不再静默降级为十字准星探测
  • ✅ 实例级 JDK 绑定：mdl jdk use <instance> aprism[@ver]|default，Adoptium 回退 + doctor 检查
  • ✅ Despotes v26.11 原语：game circuit（立方体扫描）、game redstone-action（toggle/cycle）、game screen（窗口几何）
  • ✅ 事件驱动编排：WebSocket 事件流推送 schedule_* 与 macro_* 生命周期事件
  • ✅ 电路变化订阅：POST/GET/DELETE /game/:instance/watch → circuit_changed 事件
  • ✅ 声明式 flow：mdl game flow <instance> --file flow.json——既有原语的有序 fail-fast 复合
  • ✅ 修复跨实例窗口错配（陈旧 PID 文件 + Windows PID 复用）

历史主线：

  • ✅ v26.0：核心启动器、实例/模组管理、Agent 游戏控制（Despotes）、整合包导入、JE/基岩专用服、Aprism 产品矩阵、下载进度条、mdl doctor
  • ✅ v26.1：能力清单、agent 错误码与 stop 命令、BDS 全生命周期、实例克隆/重命名
  • ✅ v26.2：空闲看门狗、流式下载（峰值 ~1.9GB→<100MB）、OOM 自保护、JavaAgent 启动/热附加注册表、mrpack 导出往返、服务端 RCON 自动化、Aprism 生态视图、启动指标 + JSON 日志
  • ✅ v26.3：输入加固与 BOM 容错、OOM 二次确认 + 误杀修复、看门狗竞态修复、结构化 properties 编辑、凭据 ACL 收紧、性能基线 mdl bench、对抗性解析套件
  • ✅ v26.4：status 性能优化、JVM 目标注入路由、Forge/NeoForge 判定修复、跨平台 CI 矩阵、cargo-fuzz、NeoForge MANIFEST 注入、AprismJDK（AJR）供给、Despotes v26.9 映射

v26.4 亮点（Alpha 1–8）：

  • ✅ status 单快照性能优化（p95 ~1.7s → ~0.2s）
  • ✅ mdl inject JVM 目标改走 JavaAgent 路径（JDK 25 CFG/CET 兼容）
  • ✅ Forge/NeoForge 判定修复（loader_type 精确判定，消除假 version-mismatch）
  • ✅ Linux/macOS/Windows 三平台 CI 编译矩阵全绿；nightly cargo-fuzz 模糊测试（首跑即修复双 BOM 崩溃）
  • ✅ NeoForge 26.x patched-client MANIFEST 自动注入（Minecraft-Dists: client，OpenLumin 手工步骤消除）
  • ✅ AprismJDK (AJR)：mdl jdk install/list/remove，launch --jdk aprism[@ver]，SHA256 校验，不可用时自动回退 Eclipse Adoptium
  • ✅ Despotes v26.9 四原语封装：schedule/macro/condition/redstone（CLI + Agent API 双面）

已测试配置：

  • Vanilla Minecraft 1.21.x / 1.20.1 ✅
  • Fabric Loader + Fabric API ✅
  • Forge 47.x / NeoForge 21.x–26.x ✅
  • 基岩版专用服 1.26.x ✅
  • JE 专用服 1.21.4 ✅

贡献

欢迎贡献！在提交 Pull Request 之前，请阅读我们的贡献指南。

致谢

本项目在 AI（Claude）的协助下开发。技术研究和实施指导通过人机协作提供。

以下开源项目作为灵感和技术参考：

许可证

根据 Apache License 2.0 许可。详见 LICENSE。