Neoforge 1.21.1 Ai Starter

Build Minecraft NeoForge Java

这个项目是干什么的？

这是一个面向 Minecraft Java 版 1.21.1 + NeoForge 的开箱即用开发起点。
你 clone / 使用本模板之后，会同时得到：

1. 一套 1.21.1 NeoForge 模组工程模板（能编译、能跑客户端）；
2. 一个 .agents 文件夹：内含工具、skills、MCP 探针等，用来帮助 AI 按统一红线写代码、查源码、做编译自检。

仓库结构（两部分）

neoforge-1.21.1-ai-starter/
├── .agents/           ← ① AI 工具包
├── src/               ← ② 模组源码（tutorialmod starter）
├── build.gradle       ← ② 构建
├── gradle.properties  ← ② 模组元数据（mod_id 等）
├── gradlew / .bat     ← ② Gradle Wrapper
└── README.md          ← 本页（GitHub 首页）

• 开新模组：整仓当模板 → 改元数据 → 初始化 → 接 MCP → 写代码。
• 只要 AI 能力：只拷 .agents/ 到已有工程（版本需同为 1.21.1 / Neo 21.1.x）。
• tutorialmod 只是可编译骨架，不是完整玩法。

GitHub Languages 会偏 Python/JS（工具包脚本多）；模组本体仍是 Java + Gradle。

更细的文件级说明见下方 .agents 目录说明（可折叠）。

核心 Skills（白名单仅 4 个）

[!NOTE] 过程型 skills（brainstorming、test-driven-development、多代理等）已移入 .agents/_archive/，非默认路径、默认禁止加载（口径见 .agents/AGENTS.md 部分三）。交付前的编译/静态证据要求已并入 AGENTS.md 的「完成证据协议」。

环境要求

• JDK 21（JAVA_HOME 或 PATH；java -version 显示 21）
• Python 3.10+（init / MCP / 自检脚本）。若默认 python 较旧，仓库的 .agents/run.py 会自动寻找可用的 3.10+ 解释器。
• 文件编码提示：Windows PowerShell 5.1 环境下读取 .agents/ 内的 .md 文档时，请显式指定 -Encoding UTF8（例如 Get-Content -Encoding UTF8 .agents/AGENTS.md），防止系统默认 GBK 导致乱码。
• Git；首次构建会拉取依赖，需网络与足够磁盘

起手四步

1. 配置元数据

编辑 gradle.properties：

mod_id=yourmod
mod_name=Your Mod Name
mod_group_id=com.yourpackage.yourmod

2. 初始化工作区

对 AI 说：帮我初始化一下这个工作区

或在终端执行：

python .agents/run.py .agents/init_workspace.py

按 gradle.properties 对齐包名、资源命名空间、主类常量、mixins 等。

3. 注册源码 MCP（必需）

脚本：.agents/mcp/minecraft_mcp.py

在 AI 客户端的 MCP 配置中注册；步骤见 .agents/README.md。
未接入时 AI 不应凭记忆编造原版 / NeoForge API。

4. 分档质量门禁

# 日常：文档信任链 + 编译 L1 + 静态 L2
python .agents/run.py .agents/gates/pipeline.py --profile fast

# Major：再强制合同 L0、DataGen/资源 L2.5、真实 GameTest L4，并生成验收追踪报告
python .agents/run.py .agents/gates/pipeline.py --profile major

# 可选严格模式：v2 必选验收项必须全部绑定到精确运行时 GameTest 符号
python .agents/run.py .agents/gates/pipeline.py --profile major --strict-traceability

# 发布：再强制生成物零漂移、专服 L3 与旗舰评测协议完整性
python .agents/run.py .agents/gates/pipeline.py --profile release

major / release 会在缺少 docs/features/*.json 或真实 @GameTest 时失败，这是防止“无测试假全绿”的设计。脚手架见 .agents/scaffolds/。 L4 同时核对官方注解的编译后字节码、外置运行时事件和精确 GameTestClass#method 集合；控制台文本不能单独充当通过证据。普通 major 生成非阻断追踪报告，--strict-traceability 才要求 v2 必选验收项 100% 绑定到这条证据链。

可选：./gradlew runClient

.agents 目录说明（点开查看）

.agents/
├── AGENTS.md           # AI 红线（请加载到客户端）
├── README.md           # 接入说明（MCP 等）
├── VERSION             # 工具包版本与目标平台
├── agent_workflow.md   # 可选：外部多智能体协作指针（非默认路径）
├── init_workspace.py   # 一键初始化入口
├── mcp/
│   └── minecraft_mcp.py
├── contracts/          # Major 功能合同通用 Schema（实际合同放宿主 docs/features）
├── scaffolds/          # Major 合同 / GameTest 防假绿脚手架
├── gates/              # pipeline + L0/L1/L2/L2.5/L4/追踪/L3 门禁
├── studio/             # provisional 外置证据、执行策略、Runner 与 Verifier
├── eval/               # 微能力批卷 + 六场景旗舰生产评测
├── _archive/           # 禁读归档（过程型 superpowers 等）
└── skills/
    ├── neoforge/             # ★ 1.21.1 写法与 references
    ├── workspace_setup/      # 初始化与改名引擎
    ├── systematic-debugging/ # 按需：排障
    └── task_monitor/         # 按需：长任务监控

相关链接

• 红线全文：.agents/AGENTS.md（根目录 AGENTS.md 仅作指针）
• 接入 Checklist：.agents/README.md
• 许可：LICENSE（MIT）；MDK 原文见 TEMPLATE_LICENSE.txt
• 你发布的具体模组：在 gradle.properties 的 mod_license 自行声明

English

NeoForge 1.21.1 AI Starter — ready-to-use Minecraft 1.21.1 / NeoForge 21.1.x setup in two parts:

1. Set mod_id / mod_name / mod_group_id in gradle.properties
2. python .agents/run.py .agents/init_workspace.py
3. Register .agents/mcp/minecraft_mcp.py as MCP (guide)
4. python .agents/run.py .agents/gates/pipeline.py --profile fast

Requires JDK 21 and Python 3.10+. If the default python is older, use the checked-in .agents/run.py launcher. Folder details: expandable section 「.agents 目录说明」 above.