mcmodsdevbridge

dsh plugin --profile web add mcmodsdevbridge

MC Mods Dev Bridge














[English](README.md) | 简体中文 | [状态](docs/STATE.md) | [架构](docs/architecture.md) | [部署拓扑](docs/deployment-topology.md)

把「AI 写完 mod 只能靠人进游戏点一遍」变成一条可执行的端到端流水线：起真实测试服 → 起真实客户端 → 连服 + op → 执行场景 JSON → 取证 → 收尾，一次覆盖 Fabric / Forge / NeoForge 三家加载器。

目标 MC 版本 26.3，Java 25，Windows。

这是开发辅助套件，不是给最终玩家用的 mod。它自带的探针 mod 只服务于「让 agent 能看见并操作真实游戏」。

---

它做什么

• 服务端探针（lab/shared/.../ProbeServer.java）：状态、命令、方块 / NBT、掉落、日志、tick 控制、动作后端；方块读写可指定维度（dim 参数，未知维度回 400）。
• 客户端探针（lab/shared/.../ClientProbeServer.java + action/ClientActionBackend.java）：UI 控件树、槽位、脚本化输入（点击 / 右键 / 按键）、截图、聊天命令、/chat/tail（读客户端当前看到的聊天与 actionbar，用来断言「玩家屏幕上真的出现了」）。
• 端到端编排（scripts/devrun.ps1）：读实例登记 → 起服务端 → 等就绪 → 起客户端 → 连服并 op → 逐步执行场景 → 收集证据 → 收尾；失败退出码非 0。场景步骤支持 retry（等状态出现），断言支持等值 / 字段包含子串 / 字段不包含子串（notContains）/ 响应体包含子串（text）/ 响应体不包含子串（textNot）；两端探针都有 GET /mods，跨加载器组合时靠它断言「每端到底加载了什么」。LWJGL 的 natives 只解一次，放在 .cache/natives/<MC 版本>-<架构>/（用文件锁串行化），所以取证目录通常只有几十 KB 日志，而不是 18 MB。
• DSH 插件（tools/dsh-plugin/mcdev-devrun/）：把同一套编排包成 mcdev_devrun / mcdev_scenarios 两个工具，供 agent 直接调用。

它不做什么

它只提供能力，不提供「该测什么」的答案。

• 不带针对某个 mod 的测试用例：测哪些功能、断言什么文本、跑到多细，取决于你当时在开发什么。scenarios/ 里的几个 JSON 是示例与自检，不是覆盖率承诺，也不是推荐清单。
• lab/fixtures/ 与 scenarios/fixtures/ 是套件自己的自测样本：它们是拿来自证「套件能把『装在哪一端』变成 PASS/FAIL」的，不是给你照抄的模板，也不进发布产物。
• 不替你做决定：凡是「下一步该干嘛 / 这个现象可能是什么原因」的内容，一律以提示的形式给出并标「不参与判定」，判绿判红只来自探针、日志、API 与你自己写的断言。
• 不替代人自己上手：音效、紫屏过渡动画、F3 读数、UI 手感、连招的爽快程度，这些没有数据通道，仍然要人进游戏看。套件的价值是把「能不能自动验」的那部分从人手里接过来，把人的时间留给只能靠人的那部分。
• 不替你判断「够了」：场景跑绿只说明你写下的断言成立，不说明功能完整。

本仓库不含什么

不包含任何服务端、客户端或加载器文件。 它们由使用者在自己的机器上准备，再用向导登记：

• instances/（实例登记，含本机绝对路径）不入库，由 scripts/setup-wizard.ps1 或 scripts/register-instance.ps1 现场生成；
• dist/（打包产物）、tmp/、lab//build/、lab//.gradle/ 同样不入库。

基于什么进一步开发

本仓库是在 yan-mc/minecraft-mod-dev 的基础上继续开发的，必须明确声明：

项 · 内容

上游工具 · yan-mc/minecraft-mod-dev

上游许可 · MIT，Copyright (c) 2026 yan-mc（全文转载在 [NOTICE](NOTICE)）

从上游继承并改写 · lab/shared/ + lab/{fabric,forge,neoforge}/ 的探针 Java（源自上游 lab/mcdev-probe/）；tools/dsh-plugin/（源自上游 plugin/minecraft-mod-dev/）

上游形态 · MC 1.20.1 + Forge 单一加载器 + Java 17；工具面为 mcdev_build / mcdev_prepare / mcdev_ui / mcdev_click 等

本仓库的差异 · MC 26.3；Fabric / Forge / NeoForge 三家；Java 25；把「起服 + 起客户端 + 连服 + 执行场景 + 取证」收敛成 devrun 一层编排，工具面为 mcdev_devrun / mcdev_scenarios

除此之外：

• 三份构建骨架分别生成自各自上游 MDK —— Fabric fabric-example-mod（CC0 1.0）、Forge MDK（LGPL 2.1）、NeoForge MDK（MIT），骨架内的 LICENSE / LICENSE.txt / TEMPLATE_LICENSE.txt 原样保留，不并入本仓库的 Apache-2.0；
• DSH 插件层面向 DeepSeek Harness 的公开插件 API 编写，DSH 本身及其各包保留自身许可证；
• 明细见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

快速开始

前置：JDK 25；一份自己装好的 MC 26.3 服务端目录（含 eula.txt 与 server.properties 的那一层）。

只做客户端时可以没有服务端目录 —— 实例登记里 side: client 就是这种形态。

探针 jar 从哪来（devrun 要把它放进服务端 mods\；客户端侧走 install-probe.ps1）：

• 自己构建：lab\fabric\gradlew.bat build（forge / neoforge 同理），产物在 lab\<加载器>\build\libs\mcdev_probe-*.jar；
• 或用发布包里的 jar，跑的时候加 -ProbeJar <路径>，或在实例 JSON 里写 probeJar。

# 1) 登记一个实例（交互式向导，或直接用命令行）
pwsh -NoProfile -File scripts\setup-wizard.ps1
pwsh -NoProfile -File scripts\register-instance.ps1 -Name local -Dir '<你的服务端目录>' -Loader fabric

# 2) 只做环境检查（不起游戏）
pwsh -NoProfile -File scripts\devrun.ps1 -Family fabric -PreflightOnly

# 3) 跑一遍 smoke 场景
pwsh -NoProfile -File scripts\devrun.ps1 -Instance local -Scenario scenarios\smoke.json

装进 DSH（可选，装完需重启 DSH 使插件生效）：

pwsh -NoProfile -File scripts\install-dsh-plugin.ps1 -Mode install

从插件市场安装（可选）

本仓库同时是一个 DSH 插件包（package.json 里有 dsh.bundle，根目录有 cordis.patch.yml）：

dsh plugin add github:7starsseeker/MCModsDevBridge

scripts/、scenarios/、tools/ 随包一起装进来，包根就是工作区根，插件自己会找到它

（也可以用 MCDEV_ROOT 指到别处）。装完重启 DSH。这个包不带 Minecraft 服务端 / 客户端 / 加载器

文件 —— 装完仍要按上面的「快速开始」登记实例，或用 -ProbeJar 指定探针 jar。

客户端怎么来

客户端有三种形态，选一种写进实例登记的 client.mode：

client.mode · 谁启动客户端 · 适合

gradle · 套件跑本仓 lab\<loader> 的 runClient · 在本仓里改探针/改 mod，改完即生效

standalone · 套件按启动器留下的版本清单自己拼 java 命令行 · 套件使用者：手里只有一份装好的客户端，没有 gradle 工程

external · 你自己开 · 任何启动器/任何形态，套件只等探针上线

standalone 是「启动器的最后一步」，不是另一个启动器：它读 versions\<版本>\<版本>.json（启动器合并后的自包含清单），

按 rules 过滤库、展开 ${...} 占位符、拼出 classpath 与参数，然后起 java。不下载任何东西，缺库直接报错。

…(truncated)