NeoForge 1.21.1 AI Starter

这个项目是干什么的？

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

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

---

仓库结构（多模组工作区）

本仓库是一个工作区：一份共享的 AI 工具包 + 一个或多个并列的模组工程。 工具包通过 .agents/workspace.json 的 active_mod 字段定位当前要操作的模组（mods/<mod_id>/）。

| | 部分 | 是什么 | 主要提供 | |---|------|--------|----------| | ① | .agents/ | AI 辅助开发工具包（工作区级，只有一份） | 开发红线、NeoForge skills/参考文档、源码 MCP 探针、各级门禁、workspace.json 寻址 | | ② | mods/<mod_id>/ | 各模组工程（可多个并列，各自独立可构建） | src/、build.gradle、gradle.properties、gradlew、docs/features/ 合同 | | ③ | docs/（工作区级） | 跨模组文档 | docs/ai/（AI 状态/交接）、docs/toolkit/（工具包规划）、docs/archive/ |

neoforge-1.21.1-ai-starter/
├── .agents/              ← ① AI 工具包（共享）
│   └── workspace.json    ← 多模组寻址：active_mod -> mods/<mod_id>
├── mods/                 ← ② 模组目录（可并列多个）
│   └── tutorialmod/      ← 示例模组（src/、build.gradle、gradle.properties、gradlew）
├── docs/                 ← ③ 工作区级文档（ai/ toolkit/ archive/）
├── AGENTS.md / README.md / rule.md
└── .github/  .gitignore  LICENSE

模组级 vs 工作区级：跟着单个模组走的（src/、构建脚本、gradle.properties、 该模组的 docs/features/ 合同、dependencies-manifest.json）放在 mods/<mod_id>/ 下； 跨模组共享的（.agents/、docs/ai|toolkit|archive）留在工作区根。

• 开新模组：优先用 .agents/tools/new_mod.py 从种子复制出 mods/<新mod_id>/ （或手工复制 mods/tutorialmod/），改其 gradle.properties 元数据，跑初始化（见下）， 并把 workspace.json 的 active_mod 指向它。tutorialmod 是种子与回归基线 （workspace.json 的 roles 标记），禁止在其上直接开发玩法功能。
• 只要 AI 能力：只拷 .agents/ 到已有工程（版本需同为 1.21.1 / Neo 21.1.x）； 该工程即为单模组布局，workspace.json 可省略（解析器自动回退）。
• mods/tutorialmod/ 只是可编译骨架，不是完整玩法。

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

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

---

核心 Skills

| Skill | 用途 | |-------|------| | neoforge_modding（目录 skills/neoforge/） | 1.21.1 写法、references、playbooks、MCP 检索剧本、编译门禁 | | workspace_setup | 改名/初始化（python .agents/run.py .agents/init_workspace.py；门禁脚本在 .agents/gates/） | | systematic-debugging | 按需：崩溃与诡异 bug 的根因排障 | | task_monitor | 按需：长 Gradle/Git 任务防假死监控 |

[!NOTE] 过程型 skills（brainstorming、test-driven-development、多代理等）已解耦移除（口径见 .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. 配置元数据

编辑目标模组的 mods/<mod_id>/gradle.properties（示例模组为 mods/tutorialmod/gradle.properties）：

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

随后把 .agents/workspace.json 的 active_mod 改为该模组的目录名（如 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% 绑定到这条证据链。

维护 .agents 工具包时，提交前运行 python .agents/run.py .agents/tools/check_toolkit_hygiene.py --check-normative-commands。它审计 Git changed set（包括未跟踪的 docs/ai/handoffs/），不要求工作区为空；release 的非 dry-run pipeline 必须使用独立的显式 --json-report PATH。

可选：在模组根（mods/<mod_id>/）运行 ./gradlew runClient（仓库根没有 gradlew）

---

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

<details> <summary><strong>目录树</strong></summary>

.agents/
├── AGENTS.md           # AI 红线（请加载到客户端）
├── README.md           # 接入说明（MCP 等）
├── ARCHITECTURE.md     # 职责地图：每处负责什么、新东西往哪放
├── VERSION             # 工具包版本与目标平台
├── workspace.json      # 多模组寻址（active_mod -> mods/<mod_id>；单模组可省略）
├── run.py              # 统一 Python 启动器（解释器探测 + UTF-8 环境）
├── agent_workflow.md   # 可选：外部多智能体协作指针（非默认路径）
├── init_workspace.py   # 一键初始化入口
├── mcp/
│   └── minecraft_mcp.py
├── contracts/          # Major 功能合同通用 Schema（实际合同放宿主 docs/features）
├── scaffolds/          # Major 合同 / GameTest / AI 状态 / 红队协议脚手架
├── gates/              # pipeline 档位 + L0/L1/L2/L2.5/L4/追踪/L3 + 安全/依赖/覆盖/产物审计门禁
├── tools/              # 发布披露、证据核对、AI 状态初始化、文档归档、CI 模组发现等辅助工具
├── witness/            # G9 运行时行为见证（独立构建的 Java agent，永不进发布 jar）
├── coverage/           # G10 覆盖率取件（JaCoCo，独立构建，不改宿主脚本）
├── eval/               # 微能力批卷 + 六场景旗舰生产评测
└── skills/
    ├── neoforge/             # ★ 1.21.1 写法与 references
    ├── workspace_setup/      # 初始化与改名引擎
    ├── systematic-debugging/ # 按需：排障
    └── task_monitor/         # 按需：长任务监控

本机生成、不入库：mcp/mcp_jar_cache.json、mcp/mcp_error.log、**/__pycache__/（见根与 mcp/ 下的 .gitignore）。

</details> <details> <summary><strong>根文件</strong></summary>

| 路径 | 作用 | |------|------| | AGENTS.md | 全局红线：Data Components、客户端隔离、网络线程、DataGen 例外、MCP 门禁、编译分级等 | | README.md | 5 分钟接入与 MCP 注册说明 | | VERSION | 版本与平台锚定（当前 1.3.1 / MC 1.21.1 / Neo 21.1.x） | | agent_workflow.md | 可选的外部多智能体协作指针；默认单 Agent 路径与证据协议见其正文 | | init_workspace.py | 初始化入口（转发到 workspace_setup 下真实脚本） |

</details> <details> <summary><strong>mcp/ 源码探针</strong></summary>

| 文件 | 作用 | |------|------| | minecraft_mcp.py | 本地 MCP：搜索/阅读 Gradle 缓存与项目中的 MC、NeoForge 源码（如 search_class、grep_source） |

接入方式见 .agents/README.md。缓存文件仅本机使用。

</details> <details> <summary><strong>skills/ 一览</strong></summary>

每个子目录有一份 SKILL.md，供 AI 按任务选用。当前清单（不设数量上限，新增准入见 .agents/AGENTS.md 部分三）：

| 目录 | 作用 | |------|------| | neoforge | 核心：1.21.1 约束、代码骨架、references/ 专题、examples/、playbooks/；约定 compile / --with-static / --with-data | | workspace_setup | 改名与初始化流程；内含 init_workspace.py（门禁脚本已上收至顶层 gates/） | | systematic-debugging | 按需：根因优先的系统化排错（含崩溃报告分析） | | task_monitor | 按需：长 Gradle/Git 后台任务防假死监控 |

过程型 skills（brainstorming、writing-plans、test-driven-development、code-review 系列等）已整体解耦移除，默认不载入上下文。

</details> <details> <summary><strong>neoforge 与脚本细节</strong></summary>

neoforge/

| 内容 | 作用 | |------|------| | SKILL.md | 总入口：红线、reference 索引（一次最多读 1～2 篇专题） | | references/*.md | 按主题的写法（组件、网络、实体、Mixin、DataGen 等 40+ 篇） | | examples/*.md | 注册、创造栏、DataGen、配方标签等完整案例（5 篇） | | playbooks/*.md | 高频任务剧本（全集固定 5 篇，禁止再增） | | docs_verified_set.txt | 已经源码核验、允许声明 verified 的信任边界 | | docs_core_set.txt | 默认候选的 verified 子集（5～10 篇，仍按任务读取 1～2 篇），不是自动装载项或可信文档总上限 |

文档中的包名可能是占位符或 tutorialmod；写入工程前须按当前 gradle.properties 替换。

gates/（门禁，顶层设施）

| 脚本 | 作用 | |------|------| | pipeline.py | 一键 fast / major / release 档位；按固定顺序运行并可输出 JSON 证据 | | contract_gate.py | L0 Major 合同：Schema、跨端、存档迁移、网络验证、性能预算、依赖图与验收命令 | | compile_and_repair.py | 执行 L1/L2/DataGen/L2.5/L4/L3；失败时给出报错上下文 | | static_gate.py | L2 静态门禁：P0 崩溃写法扫描（仅扫宿主 src/main/java） | | asset_gate.py | L2.5 资源对账：注册项 ↔ 模型/blockstate/loot/lang/贴图引用闭环 | | gametest_gate.py | L4：发现并执行真实 NeoForge GameTest；零测试、模糊日志和任意失败均可 fail-closed | | check_doc_index.py / check_doc_meta.py | 文档索引完整性与核心集元数据自检（附 reference 体量统计） | | crash_triage.py + crash_rules.json | 崩溃分诊：签名查表直指 P0 红线与该读文档（排障入口，非门禁） | | security_gate.py | G1 安全扫描：外联、越权写入、动态加载、telemetry、凭证硬编码等危险模式 | | dependency_gate.py | G8 依赖治理：依赖坐标申报、仓库白名单、校验元数据 | | coverage_gate.py | G10 覆盖遥测：安全敏感类未被任何测试执行的比例（advisory） | | artifact_audit_gate.py | 发布 jar 内容审计：包名白名单、意外文件、与证据账本 sha256 复核 | | traceability_gate.py | 验收溯源：合同验收项 ↔ GameTest 精确符号绑定 |

workspace_setup/scripts/

| 脚本 | 作用 | |------|------| | init_workspace.py | 对齐 assets//data/ 命名空间、mixin json、主类 MODID（先 --dry-run 预览） |

</details>

---

相关链接

• 红线全文：.agents/AGENTS.md（根目录 AGENTS.md 仅作指针）
• 接入 Checklist：.agents/README.md
• 许可：LICENSE（MIT，版权行含 NeoForged 项目归属；原模板附带的独立 MDK 许可文本已于清理提交中移除）
• 你发布的具体模组：在 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:

| Part | Role | |------|------| | .agents/ | AI modding toolkit (rules, skills, local source MCP, init & compile scripts). Reusable in other 1.21.1 NeoForge projects. | | Rest of the repo | Mod template (Gradle scaffold + tutorialmod starter). |

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.