minecraft-mod-dev

让 AI 团队真正“玩到”自己写的 Minecraft 模组。
DeepSeek Harness 插件 + Minecraft 1.20.1 Forge 探针：写代码、构建、启动真实服务端/客户端、点 UI、截图、读日志、跑 GameTest、修 bug，全在一个工具层里完成。

研究/原型项目，不是生产级产品。当前只支持 Windows 10/11 x64 + Minecraft 1.20.1 + Forge 47.4.x + Java 17 + DSH 0.2.1-rc.2。

它解决什么问题

传统上，AI 写 MC 模组只能停在“代码看起来对”。改一个 GUI、一个物品条、一个配方掉落，都要人手动进游戏点一遍、看日志、截图、修。

这个项目把“AI 能自己看到游戏里发生了什么”做成可调用的工具：

服务端探针：状态、命令、方块/NBT、配方、掉落、物品、世界破坏、日志、run dump；
客户端探针：UI 控件树、槽位、鼠标点击、右键、截图、聊天命令；
启动器：mcdev_prepare 启动真实 runServer / runClient，等进服，失败自动重试；
卡片执行器：YAML 卡片 → 可重复的 in-game 检查（含断言、截图、干跑）；
团队模式：Builder / Tester / Reviewer 在 Agent Teams 里分工，Lead 收口。

核心能力

能力	说明
🧱 构建	`mcdev_build`：Gradle 构建，返回 exitCode/tail
🧪 自动化测试	`mcdev_gametest`：Forge GameTestServer，当前参考模组 12/12
🚀 启动真实游戏	`mcdev_prepare`：server / client / both；TitleScreen 后显式 `/connect`，不用 quickPlay
🖥️ 客户端观察	`mcdev_ui`、`mcdev_click`、`mcdev_use`、`mcdev_screenshot`
📊 服务端检查	`mcdev_status`、`mcdev_command`、`mcdev_run_dump`
🃏 卡片执行	`mcdev_scenario`：YAML 卡片、`dryRun`、步骤/断言、`warnings` 不静默通过
🧩 游戏内语义	方块/NBT、comparator analog、recipe、loot、craft、item bar、生存挖掘
🤝 团队协作	`mcmod` preset + Agent Teams；任务板、Tester/Reviewer 复核
🧯 稳定性	devJar 校验、独立 run 目录、Disconnected 提前判失败、最多 3 次重试

快速开始

1. 安装 release

从 Releases 下载：

minecraft-mod-dev-0.5.1.zip（插件）
mcdev_probe-0.1.0-dev.jar（dev-mapped 探针）

在 DSH 中安装插件：

plugin_manager install_bundle target=<解压目录>/minecraft-mod-dev

2. 构建/安装探针

从源码：

cd lab\mcdev-probe
.\gradlew.bat clean devJar

把 lab\mcdev-probe\build\libs\mcdev_probe-0.1.0-dev.jar 放进：

lab\forge-1.20.1-test\run-server\mods\
lab\forge-1.20.1-test\run-client\mods\

或用工具校验并复制：

mcdev_install_probe
  probeJar=F:\...\lab\mcdev-probe\build\libs\mcdev_probe-0.1.0-dev.jar
  runDirs=["F:\...\lab\forge-1.20.1-test\run-server",
           "F:\...\lab\forge-1.20.1-test\run-client"]

必须使用 *-dev.jar；普通 reobf jar 在 dev 环境会 NoSuchMethodError。

3. 启动

mcdev_prepare
  projectDir=F:\...\lab\forge-1.20.1-test
  kind=both

客户端不依赖 quickPlay：到 TitleScreen 后由插件调用 /connect 显式连接。期望：

{"ok":true,"results":[
  {"kind":"server","port":39001,"ready":true},
  {"kind":"client","port":39002,"ready":true,"joined":true}
]}

4. 跑一张卡片

mcdev_scenario card=F:\...\lab\forge-1.20.1-test\cards\F-002.yml

期望：

{"ok":true,"warnings":[],"steps":[...]}

5. 收尾

mcdev_stop side=all

卡片执行

卡片是 YAML，可直接给 AI 或人复用：

id: F-002
setup:
  commands:
    - "setblock 0 64 0 examplemod:charger"
    - "tp Dev 0.5 64 1.5 180 0"
actions:
  - {wait: 300}
  - {use_on: {x: 0, y: 64, z: 0, face: up}}
  - {wait: 300}
assert:
  - {screen_title: "Charger"}
  - {slot_exists: 0}

mcdev_scenario 支持：

dryRun：只翻译/报告，不执行；
wait、command、use、ui、click、screenshot、run_dump；
block / break / mine / client_mine / items / recipe / loot / item / craft；
assert.comparator / recipe_output / loot_drop / loot_break / loot_mine / block_state / loot_items / item_bar / craft。

未支持的字段进入 warnings，不会静默当作通过。
完整卡片语法见 docs/TOOLS.md。

参考模组：Charger

lab/forge-1.20.1-test 是完整可玩的参考模组：

充能方块 + 能量 NBT + comparator；
充能物品 + tooltip + 热栏能量条；
GUI（37 槽、shift-click、关闭重开）；
配方、loot、/charger info、advancement、生存挖掘。

7 张功能卡（F-001..F-007）+ 12 个 GameTest + 5 类注入 bug 演练，全部有可复现证据。

卡片	覆盖
F-001	方块右键充能、NBT、comparator
F-002	GUI 打开/槽位/shift-click
F-003	物品 tooltip
F-004	recipe / loot / craft
F-005	命令 raycast / advancement
F-006	item bar visible/width/color
F-007	生存挖掘 + 掉落

截图

Tooltip	Advancement toast

Hotbar energy bar	Raycast command

架构

┌──────────────────────────────┐
│ DeepSeek Harness / Agent Team │
│  Lead · Builder · Tester ...  │
└──────────────┬───────────────┘
               │ mcdev_* tools
┌──────────────▼───────────────┐
│ plugin/minecraft-mod-dev      │
│  14 tools · mcmod preset      │
│  Agent Teams mount            │
└──────────────┬───────────────┘
               │ HTTP 127.0.0.1:39001/39002
┌──────────────▼───────────────┐     ┌────────────────────┐
│ lab/mcdev-probe (Forge mod)   │────▶│ Minecraft server    │
│  server probe + client probe  │     │ Minecraft client    │
│  Mixin tick · GameTest        │     │ (real GUI/world)    │
└──────────────────────────────┘     └────────────────────┘

服务端 probe：39001；客户端 probe：39002；测试服：25566；
独立 run-server/、run-client/、run-gametest/，避免登录超时；
dev-only Mixin：remap=false + tick 字面量，生产 SRG 未支持。

仓库结构

plugin/minecraft-mod-dev/     DSH 插件：14 个工具 + mcmod preset + 团队挂载
lab/mcdev-probe/              服务端/客户端探针 Forge mod
lab/forge-1.20.1-test/        Charger 参考模组、7 张卡、12 个 GameTest
docs/                         安装、手册、工具、团队、排障、演示、发布
docs/assets/                  README banner 与截图

文档

📖 完整说明书 MANUAL.md — 架构、安装、工具、卡片、团队、测试、排障、二次开发
🚀 安装与快速开始
🧰 工具与卡片语法
🤝 团队模式
🩺 常见问题与排障
📊 当前状态
🎬 10 分钟演示
📦 发布说明
📝 Changelog

状态

项	结果
插件版本	`0.5.1`
GameTest	12/12
功能卡	F-001..F-007 全部 live，`warnings=[]`
注入 bug	5/5 检出并修复
Release	v0.5.1（beta）
测试环境	Windows 11 + Temurin 17.0.19 + Forge 47.4.28

已知限制

只支持 MC 1.20.1 + Forge 47.4.x + Java 17 + Windows；
探针 Mixin 是 dev-only，生产 SRG 未支持；
Agent Teams 是 DSH 实验特性，成员/任务状态可能不同步；
客户端本地方块状态可能短暂滞后，以服务端 /world/block 为准；
不做 WASD 实时操作，不替代主观验收；
craft 是服务端合成模拟，不走 GUI；
正式 npm 发布未做；目前本地 link 安装 + GitHub release 资产。

License

原创代码与文档：MIT，见 LICENSE。
Minecraft / Forge / Gradle / Mixin 等第三方组件保留各自许可证，见 THIRD_PARTY_NOTICES.md。本仓库不重新分发 Minecraft 客户端或资源。

Navigation Menu

Repository navigation

About

Repository files navigation

minecraft-mod-dev

它解决什么问题

核心能力

快速开始

1. 安装 release

2. 构建/安装探针

3. 启动

4. 跑一张卡片

5. 收尾

卡片执行

参考模组：Charger

截图

架构

仓库结构

文档

状态

已知限制

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
lab		lab
plugin/minecraft-mod-dev		plugin/minecraft-mod-dev
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md

Latest commit

History

Folders and files

Repository files navigation

minecraft-mod-dev

它解决什么问题

核心能力

快速开始

1. 安装 release

2. 构建/安装探针

3. 启动

4. 跑一张卡片

5. 收尾

卡片执行

参考模组：Charger

截图

架构

仓库结构

文档

状态

已知限制

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages