minecraft-modding-workbench

Minecraft Modding Workbench

支持快速、感知版本的 Minecraft 模组开发。将 minecraft-modding MCP 服务作为首要事实来源，然后将经过验证的发现转化为可运行的代码和资源。

范围

• 支持 Fabric、NeoForge 和 Architectury。
• 需要来自 @adhisang/minecraft-modding-mcp 的 minecraft-modding MCP 服务。
• 存在工作区时，优先使用感知项目的 MCP 调用。将仓库根目录用作 projectPath 并重复使用。
• 首先使用高级 MCP 工作流工具：inspect-minecraft、 analyze-symbol、compare-minecraft、validate-project、analyze-mod 和 manage-cache。
• 适用时，也使用 MCP 验证和批处理辅助工具： 使用 verify-mixin-target 一次性检查 Mixin 所有者／成员，并获取 访问器／调用器建议；对于共享同一个已解析制品或 Minecraft 版本的固定短名单， 使用 batch-class-source、batch-class-members、 batch-symbol-exists 或 batch-mappings。
• 除 Fabric 风格的访问拓宽器外，还通过 validate-project（任务 access-transformer）支持 NeoForge 的 Forge 风格访问转换器。
• 处理 level.dat、区块、playerdata 或命令驱动的 NBT 时，使用 NBT 辅助工具（nbt-to-json、json-to-nbt、nbt-apply-json-patch）。编辑期间使用有类型的 JSON，最后只重新编码一次。编辑实时存档数据前，先备份原始二进制文件。这些辅助工具读取原始 NBT 负载，而非 .mca 区域文件：先使用区域工具提取区块负载，否则停止并说明不支持此输入。

默认行为

• 交付可运行的功能切片，而非泛泛建议。
• 提问前，先根据工作区推断加载器、版本、映射、modid、包名、Java 版本和项目约定。
• 仅当工作区缺失或信息相互矛盾时，提出最少的阻塞性问题。
• 美术或平衡细节尚未确定时，优先使用明确的 TODO 或占位资源，不要因此停滞。
• 用户明确要求实现而非解释时，默认交付代码。
• 条件允许时，使用用户的语言回复，但工作流和触发逻辑应与语言无关。
• 当回答会指导后续实现时，按验证来源区分事实：由 MCP 验证、由工作区／源代码 JAR 回退验证、运行时／用户观察和未验证。

实施指导输出约定

对于会指导后续实现的计划、调试说明、MCP 负载／错误恢复答复、评估答复和交接内容，在给出依赖版本的建议之前，应明确标示信息来源：

• 项目配置：记录已确认的工作区根目录、加载器、Minecraft 版本、映射命名空间、Java 版本、modid 和基础包名（如相关）。如果没有工作区或文件证据，在将提示词提供的版本用作示例之前，明确标记缺失或假定的字段。
• MCP 状态：在给出依赖 MCP 的结论之前，记录预检／模式状态。如果尚未实际运行工具，应将 MCP 步骤标记为计划中或未验证，而不要写得像已经获得结果。
• 验证来源：将实施事实分别归入由 MCP 验证、由工作区／源代码 JAR 回退验证、运行时／用户观察和未验证。对于回退／错误恢复任务或评估式答复，如果省略空类别会模糊来源边界，则将其标记为尚无。
• 除非用户要求审计，或需要解释回退／来源判定，否则不要向用户展示捆绑参考资料的内部路由信息。

快速路径

1. 阅读或构建项目概况：工作区根目录、加载器、Minecraft 版本、映射、Java 版本、模块和常规验证命令。 如果工作区不存在，请先记录缺失的概况信息，再对版本、加载器、 映射或 Java 敏感的内容作出判断。
2. 在假设 minecraft-modding 工具可调用之前，先运行 MCP 预检。
3. 针对相关事实，先进行一次高级 MCP 调用。
4. 加载捆绑参考资料之前，先选择范围较窄的内部参考资料。确定 任务类型后，从对应的检查清单章节开始；仅在条件匹配时，再添加加载器、 MCP 配方、回退方案或任务专用参考资料。
5. 如果工作进程重启、超时或传输失败，请使用范围更窄的高级调用载荷重试一次， 然后切换到对应的回退指南。 验证器重启一次后不再重试：将其记录为此任务不可用，并使用 references/validator-fallbacks.md。
6. 对于无效载荷，仅查阅相关的 references/mcp-recipes.md 配方，修正格式一次，然后重试同一个高级工具，再考虑更换工具。
7. 对于 Mixins、访问扩展器和访问转换器，请在编辑前记录所有者、名称、描述符、 命名空间、配置声明和侧端。
8. 对于资源、世界生成、战利品、模型、编解码器、HUD、界面和运行时钩子，请运行 任务专用检查清单，不要将 build 视为运行时行为的证明。

MCP 预检

在 Minecraft 模组任务开始时、首次依赖 MCP 作出判断之前，运行一次此预检：

1. 检查宿主是否提供 minecraft-modding 工具，并在首次请求前检查 可调用的架构，尤其是 inspect-minecraft、analyze-symbol 及其转换后的可调用名称。
2. 记录可用的高级工具名称、要用作 projectPath 的工作区根目录、 检测到的 Minecraft 版本、加载器、映射和 Java 版本。
3. 如果 inspect-minecraft 和 analyze-symbol 均不可用，请说明 minecraft-modding MCP unavailable，然后切换到 references/mcp-unavailable-fallback.md。
4. 如果此技能提到的工具或参数被拒绝为未知项，请先排查 MCP 升级后启动失败的情况 （references/mcp-unavailable-fallback.md）；否则，将已安装的 MCP 视为版本低于这些配方面向的 MCP 接口，或存在版本偏差，并使用最接近的 旧版本兼容路径或工作区回退方案。不要继续猜测工具名称。
5. 如果 MCP 可用，在当前工具接受这些字段时，优先使用包含 projectPath、 preferProjectVersion 和 preferProjectMapping 的项目感知调用。

初步检查

1. 判断项目结构。
   • 阅读 gradle.properties、build.gradle、build.gradle.kts、settings.gradle、fabric.mod.json、neoforge.mods.toml、mixin 配置文件以及附近的注册类。
   • 推断加载器、Minecraft 版本、映射、Java 版本、modid、基础包名、项目是否已使用数据生成，以及工作区是单加载器还是 Architectury 多模块。
   • 记录将作为 projectPath 传递给 MCP 工具的工作区根目录。
2. 编写新代码前，先阅读现有代码。
   • 遵循项目的命名规范、包布局、注册辅助工具，以及客户端/服务端划分。
   • 如果已有注册表、标签页、数据包模式和数据生成提供器，请予以复用。
   • 优先使用可感知工作区的 MCP 解析方式，再手动选择版本或映射。
3. 使用下方“参考路由”章节，只加载相关参考资料。
4. 实现行为前，先查找最接近的原版示例。
   • 从 inspect-minecraft 或 analyze-symbol 开始。
   • 仅当高层工具的回答仍无法明确实现方式时，才使用底层工具。

如果尚无项目，只询问加载器、Minecraft 版本、modid 和包名。 对于无法访问工作区、仅需解释的任务，请在给出示例前列出缺失或假设的事实。 如果任务依赖当前不存在的外部生成器或模板，请明确说明，而不要捏造生成文件。

参考资料路由

随附参考资料是可选的条件上下文。不要仅仅因为触发了此技能，就读取或复述整套参考资料。

• 默认路由：
  • 使用 SKILL.md、项目概况、MCP 预检，以及一个可用的高层 MCP 查询。
  • 确定任务类型后，只读取 references/task-checklists.md 中匹配的部分一次。
• 加载器路由：
  • 仅在涉及 Fabric 项目结构、注册、API、入口点、数据生成、网络、Mixins 或常见问题时，读取 references/fabric.md。
  • 仅在涉及 NeoForge 项目结构、DeferredRegister、事件、能力、访问转换器、数据生成、网络、端侧访问或常见问题时，读取 references/neoforge.md。
  • 仅在涉及 Architectury 多模块代码放置，或跨越通用端与平台端边界的代码切片时，读取 references/architectury.md。
  • 仅当工作区使用多个加载器，且改动涉及这些加载器时，才读取多个加载器参考资料。
• MCP 配方路由：
  • 仅在涉及负载结构、高层工具错误恢复、ERR_INVALID_INPUT、新旧结构不匹配，或高层调用未涵盖的辅助工具时，读取 references/mcp-recipes.md。
  • 如果高层 MCP 答案已足够，就不要复述无关配方。
• 回退路由：
  • 仅在预检显示没有 MCP 工具、指定的工具或参数被判定为旧版 MCP，或失败预算要求回退时，读取 references/mcp-unavailable-fallback.md。
  • 仅在 validate-project、validate-mixin、validate-access-widener 或 validate-access-transformer 不可用、重启、超时、无法作答、因运行时 JAR 上下文而拒绝，或返回近似判定后，读取 references/validator-fallbacks.md。
• 任务专用路由：
  • 查询依赖 API 源码时，读取 references/dependency-jars.md。
  • 涉及 HUD 叠加层、屏幕、投影、GUI 缩放、FOV 或客户端渲染时，读取 references/rendering-hud.md。
  • 涉及 GameTest 或测试框架接线时，读取 references/gametest.md。
  • 仅对稀疏模板读取 references/bootstrap-from-template.md。
  • 当持久化项目概况有用时，读取 references/project-profile-template.md。
  • 仅在将 Minecraft 工作委派给其他 Agent 时，读取 references/subagent-mcp-contract.md。

默认情况下，内部记录已加载或跳过的参考资料。仅当用户要求审计，或回退、缺失源码或来源限制会实质影响建议时，才说明这些信息。

MCP 护栏

在详细构造 MCP 负载、选择专家工具或批处理工具、解读响应字段、决定重试或回退，或给出对版本或映射敏感的建议之前，先阅读 references/mcp-guardrails.md。始终遵守以下原则：

• 从能够回答该事实的最高层级只读工具开始；
• 检查可调用工具的架构；遇到无效输入时先纠正一次，再更换工具；
• 仅在有限的传输或重启故障后，才重试一次范围更窄的高层请求；绝不重试完全相同的确定性服务端故障；验证器重启一次后不再重试；
• 明确标注项目版本、映射、构件和工作区的来源信息；
• 将回退所得事实标记为“经回退验证”，而非“经 MCP 验证”。

不支持或存在风险的请求

• 不要把 Quilt 或旧版 Forge 悄悄当作 Fabric、NeoForge 或 Architectury 处理。
• 对于仅支持旧版 Forge 的加载器或其他不受支持的加载器，只针对已验证的工作区事实、日志和迁移边界提供帮助。说明完整指导不在本技能范围内。
• 如果 MCP 不可用、配置错误或已过时，请立即说明，并改为检查工作区和日志，且修复范围应尽可能小。版本不匹配也遵循同一规则：如果本技能列出的工具、任务、响应调整参数或输入格式（例如，detail / include[]、manage-cache action: "verify"、validate-project 任务 access-transformer、analyze-symbol 生命周期范围控制项、get-class-source / get-class-members target.kind，或 NBT 辅助工具）被拒绝并提示未知，请先执行 MCP Preflight 第 4 步，包括升级后的检查，然后再判定为版本不匹配；说明适用的结论，并通过最近的旧版兼容工具或仅检查工作区的替代方案处理请求，不要凭空编造其他载荷格式。
• 如果下载因大小上限而被拒绝，请用户调高 MCP_MAX_DOWNLOAD_BYTES 并重启 MCP；只有在有证据表明内部 jar 过大时，才请用户调高 MCP_MAX_NESTED_JAR_ENTRY_BYTES 并重启；如果 ERR_REPO_FETCH_FAILED 提示中包含缓存路径和 errno，请用户修复该路径的权限或磁盘状态。在此期间使用本地替代方案（references/mcp-unavailable-fallback.md）。
• 如果工作区文件与提示内容相矛盾，请指出矛盾，并在编码前依据已检查的文件解决。
• 如果请求依赖于你无法验证的符号、事件、注册项或原版钩子，请说明其未经验证或不受支持，不要凭空编造。提供最接近的已验证替代方案。

核心工作流

1. 检查已经解决相同问题的原版代码或现有模组代码。
2. 将该模式迁移到用户使用的加载器、模块边界和映射命名空间。
3. 如果模板过于空白，先搭建缺失的项目骨架。
   • 只添加实现请求功能所需的最少入口点、注册类、客户端钩子和数据生成接线。
   • 不要预先创建所有可能的系统。
4. 一次性完成整个功能切片。
   • 包含注册。
   • 在需要时接入客户端。
   • 包含所需的 JSON 资源或数据生成钩子。
   • 在功能需要时包含语言键、战利品表、方块状态、模型、标签、配方或屏幕接线。
   • 在 Architectury 工作区中，除非工作区已有其他经过验证的模式，否则应将共享游戏逻辑放在 common 中，并将加载器专属接线放在平台模块中。
5. 在宣布任务完成前，运行验证流程。
6. 简要报告假设、占位内容、后续任务和验证依据。

交付规则

• 引入新的抽象前，先遵循项目现有风格。
• 不要臆造映射名称、事件名称、注册顺序或描述符。务必核实。
• 如果加载器已提供清晰的钩子，优先使用稳定的加载器 API 或事件，而不是 Mixin。
• 如果项目只有模板，则创建能够编译并承载所需功能的最小可用脚手架。
• 在 Architectury 项目中，默认将代码放在 common 中，只将绑定特定加载器的代码移到 fabric 或 neoforge。
• 对于已通过共享初始化方法接入两个加载器的 Architectury 模板，不要仅为与共享内容变更保持一致而添加无操作的平台改动。
• 只有当代码确实需要平台特定行为时，才使用 @ExpectPlatform、Architectury 抽象，或纯 Java 接口／服务拆分。
• 正确区分侧端。将渲染器、屏幕和其他仅客户端代码放在适当的客户端入口点或事件之后。
• 如果请求会创建重复的 JSON 或超过两三个内容条目，优先使用数据生成。
• 保留现有辅助类、注册表和包结构，不要将它们整体替换。
• 调试时尽量缩小修复范围。先找出具体故障，再修复原因。

验证与调试参考

在宣布实现完成前，或诊断 Mixin／访问权限、注册表／资源编解码器、依赖项、HUD／渲染、GameTest、NBT、缓存／索引、模型／纹理、仅限特定侧端或版本移植故障时，请阅读 references/verification-and-debugging.md。该文档提供详细的 Gradle、数据生成、运行时、资源及各类别验证流程。对于资源密集型或仅在运行时生效的更改，仅构建成功并不能证明运行时正常。

参考资料

• Fabric 模式：references/fabric.md
• NeoForge 模式：references/neoforge.md
• Architectury 模式：references/architectury.md
• 模板引导模式：references/bootstrap-from-template.md
• 按任务类型划分的交付检查清单：references/task-checklists.md
• MCP 载荷与恢复方案：references/mcp-recipes.md
• 详细的 MCP 防护措施：references/mcp-guardrails.md
• MCP 不可用时的回退方案：references/mcp-unavailable-fallback.md
• 依赖项 API 源码查找：references/dependency-jars.md
• HUD 与客户端渲染：references/rendering-hud.md
• 验证器回退方案：references/validator-fallbacks.md
• 验证与快速调试：references/verification-and-debugging.md
• GameTest 接线：references/gametest.md
• 项目配置模板：references/project-profile-template.md
• 子 Agent MCP 契约：references/subagent-mcp-contract.md
• 如需了解当前上游迁移指南，请查阅与目标加载器和 Minecraft 版本相匹配的 Fabric、NeoForge 和 Architectury 官方文档或发行说明，不要依赖硬编码的 URL。