Skip to content
Back to search

MC-AI-Coding-Assistant-Tool

让 AI 编程助手(Cursor / Claude Code 等)能更好地编写 Minecraft 模组的完整工具包。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/guguzea/MC-AI-Coding-Assistant-Tool with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/guguzea/MC-AI-Coding-Assistant-Tool'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/guguzea--mc-ai-coding-assistant-tool/badge.svg)](/listings/guguzea--mc-ai-coding-assistant-tool)

HTML

<a href="/listings/guguzea--mc-ai-coding-assistant-tool"><img src="/api/listings/guguzea--mc-ai-coding-assistant-tool/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,423 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # MC AI Coding Assistant Tool
  3. **简体中文** · [English](README.en.md) · [人类读本](README_human.md) · [Human Guide](README_human.en.md)
  4. ### 一个跑在本地的 MCP知识/工具库:一站式MC模组解决方案
  5. ### 显著降低AI幻觉·AI不再瞎编
  6. #### 检查不好找?AI也是一个好老师!
  7. #### 显著降低模组开发,整合包开发的工作量!
  8. #### 帮助你实现想过但是受限于学习成本的没有完成的梦想!
  9. **规则、官方文档、映射表、库模组、真机自测**
  10. **[人类读本](README_human.md) · [安装说明](AUTO_SETUP.md) · [贡献指南](CONTRIBUTING.md)** · [平台说明](#平台说明) · [工具清单](#mcpcli-tools89)
  11. </div>
  12. > [!IMPORTANT]
  13. > 只从本仓库获取工具与数据。同名仓库或复制本文档不代表官方下载源。
  14. > **你是人类读者 → [人类读本](README_human.md)**(人话版:能干什么、怎么开始 · [English](README_human.en.md))
  15. > 本文件是给 AI 执行用的技术契约,长且密;细节让 agent 讲,比你自己翻快。
  16. - **8 个加载器 + 2 个服务端面,逐版规则**:Forge · Fabric · NeoForge · Quilt · LiteLoader · Rift · ModLoader · 基岩 | Paper · Spigot
  17. - **官方文档原文检索**:查的是你这个版本那一页,向量搜索,准确命中!
  18. - **六层映射互转 + 崩溃日志分析**:mojang · mcp · yarn · parchment · obfuscated · intermediary,把 crash-report 直接扔给 AI,它会帮你解析出可能的原因
  19. - **库模组与社区知识**:48 个常用库模组的 API 摘要、成套 Skill、精选各个MC社区的帖子
  20. - **复合工程工具**:脚手架、Gradle 诊断、项目校验、Datagen、崩溃分诊、跨版本移植分析、AT/AW、mixin 分析、资源审计、发布前检查、翻译工具...等等!
  21. - **移植工具**:找到个好模组但只有 Forge 版,你想在 Fabric 玩?AI 会先分析移植路径、列出风险,确认之后再使用移植工作流,不会乱改你的文件。最后完成移植!
  22. - **解放人力**:不用再把时间耗在重复劳动上:注册方块、注册物品、数据生成、网络同步……AI 可以照着内置的规则和脚手架直接生成,新方块、新实体、GUI、崩溃分诊、移植、构建、真机测试,都有现成的工作流模板,AI 全部搞定。
  23. - **反编译工具**:支持反编译MC 源码,解析本地 mod jar,下载模组解析,帮助你解决编程时的问题d(´ω`*)
  24. - **游戏内自测**:客户端 driver / 桥 / 服务端 driver,标准软件测试流程,测试全面,能够防止类似于MCR的兼容困难问题,拒绝屎山!出截图、`qa.log`、`state.json` 才算过
  25. ---
  26. ## 写在前面的
  27. ### 如果你是 agent
  28. 本文件是项目总说明。包括详细的功能说明
  29. ### 如果你是人类
  30. 见文首那条提示:人类读本 = `README_human.md`;需要细节直接让 agent 讲解。
  31. 让 AI 编程助手(Cursor / Claude Code 等)能更好地编写 Minecraft 模组的完整工具包:消除知识陈旧、API 版本混淆、构建系统复杂、映射不一致等结构性障碍,覆盖从编写到测试模组的全流程。
  32. ### 安装(第一次用先看这里)
  33. **最省事的装法:让你的 AI 帮你装**
  34. ## 给小白的安装教程
  35. 1. **让你的 AI 装它**:在harness中新建对话,输入:
  36. > 帮我把这个 MCP <https://github.com/guguzea/MC-AI-Coding-Assistant-Tool.git>安装到 `<你想装的位置>`
  37. Agent 会自己认宿主 → 检查 Node → `cd mcp-server && npm ci && npm run build` → 按该宿主格式生成配置草稿;**它先把目标文件与 diff 给你看,你确认后它才写**(不会静默覆盖已有 MCP 配置)。宿主不在已列清单里也能装(见 [AUTO_SETUP.md](./AUTO_SETUP.md) Step 4.11)。
  38. 3. **重载宿主**:按AI指导重载 MCP(有的是重启、有的是重连,对照表在 [AUTO_SETUP.md](./AUTO_SETUP.md) Step 5)。重载后让它调一次 `get_server_status`;通了就是装好了。
  39. **前置要求**:**Node.js >= 22.5**(`node -v` 自查)。**22.5–22.12 与 23.0–23.3 必须加 `--experimental-sqlite` 启动**——内置 `node:sqlite` 在 22.13 / 23.4 起才默认开启;MCP/CLI 入口会在**任何 sqlite 使用之前**检测该窗口,命中即打印醒目指引并以非零码退出。**建议直接装 Node 22.13+ / 24 LTS 省心。**
  40. ## 可以让AI帮你安装node
  41. **没看到工具 / 不想重载宿主** —— 不配 MCP 也能用,直接让AI使用 CLI工具
  42. **想手动装 / 装坏了要修**:唯一说明书是 [AUTO_SETUP.md](./AUTO_SETUP.md)(Step 0-pre 校验旧路径 → Step 0 识别宿主 → Step 2 编译 → Step 4 按宿主生成配置 → Step 5 重载并验收);服务名 `MC-AI-Coding-Assistant-Tool`(stdio,**89** 个工具)。另一种装法(把 npm 包装进任意工程、平台数据另取):见 [`mcp-server/README.md`](./mcp-server/README.md)「npm 安装」。
  43. > **给 Agent**:用户说「帮我装 / 怎么装 / 装不上」时按上面三步走;**配置格式以 `AUTO_SETUP.md` 为准;写盘前必须先给清单 + diff 等用户确认。**Skill 安装(Step 6)与 MCP 无关**,重载 MCP 不会让 Skill 面板出现条目,skill是动态上下文插入机制。
  44. ## 项目结构
  45. ```
  46. MC_skill/
  47. ├── README.md # 你在这里
  48. ├── AGENTS.md # 根总纲:引导 AI 选择正确的平台规则
  49. ├── CONTRIBUTING.md # 贡献指南
  50. ├── AUTO_SETUP.md # 任意 MCP 宿主:编译 + 按宿主格式生成配置草稿
  51. ├── REPORT-FORMAT.md # 交付底稿全量表单(agent 用:判档 / 主档四块 / 维护档六块 / 硬约束)
  52. ├── DELIVERY_LOG.md # 每轮交付底稿正文(滚动,最新在上;聊天只给人看三件)
  53. ├── THIRD_PARTY_NOTICES.md # 第三方文档 / 映射数据许可说明
  54. ├── LICENSE # 本仓库代码:PolyForm Noncommercial 1.0.0 + 强 Copyleft 附加条款(非商业、署名、衍生须同许可开源)
  55. ├── Minecraft 社区常用库模组全览(2026 版).md # 跳转指针;正文在 community_knowledge/authored/library-catalog-2026
  56. │
  57. ├── forge/ # Forge 规则 / skills / scaffold / knowledge(多版本)
  58. ├── fabric/ # Fabric 规则与知识(多版本)
  59. ├── neoforge/ # NeoForge 规则与知识
  60. ├── quilt/ # Quilt QSL 差异规则(02–10 读同版 fabric)
  61. ├── liteloader/ # LiteLoader(主推 1.12.2)+ HYBRID.md
  62. ├── rift/ # Rift 1.13(原生档)+ 1.13.2(社区分支实验档)
  63. ├── modloader/ # Risugami ModLoader 1.6.4 + 安全 API 表
  64. ├── bedrock/ # 基岩 Add-On 规则(扁平 bedrock/)
  65. │
  66. ├── doc/ # 落点台账与专题(18 篇,摘录):工具错误码 / 平台覆盖(forge·fabric·neoforge·quilt)/ 服务端面 / 游玩 loop 与阶梯 / 检索纪律 / 排障
  67. ├── community_knowledge/ # 社区实务知识库 → MCP search_community_docs
  68. │ ├── authored/ # 自写短文(含 lib-* 库集成系列 + 发布/崩溃/GUI 等)
  69. │ ├── permitted/ # 许可入库的社区帖提炼(如 mcmod 3993)
  70. │ ├── links/ # 仅标题 / 摘要 / 外链(如 mcmod 6071)
  71. │ ├── patterns/ # 代码模式示范(mcskill://patterns/README)
  72. │ ├── indexes/index-l0.json # L0 索引(逐来源计数见文件本身;重建:`npm run community:index`)
  73. │ ├── AGENT_USAGE.md # Agent 用法规则(短文不能当 API 规范)
  74. │ └── README.md # 主题 id 速查
  75. │
  76. ├── knowledge/ # 仓库级知识源稿(不落盘到平台 .cursor/skills)
  77. │ ├── libs/ # 库模组 Skill 源稿(份数/skillId 现读 `knowledge/libs/README.md` §当前规模)
  78. │ │ ├── all-platforms/ # 20(含 mc-lib-catalog 路由中枢)
  79. │ │ ├── fabric-only/ # 10(Trinkets / CCA / Polymer…)
  80. │ │ ├── forge-only/ # 2(Curios / KFF)
  81. │ │ ├── neo-only/ # 2(Curios / KFF 镜像)
  82. │ │ ├── bedrock-only/ # 2(Script API)
  83. │ │ └── README.md # 分组规则、解析流程、数据链指针
  84. │ └── patterns/ # 短片段模式库(与 community_knowledge/patterns 互补)
  85. │
  86. ├── scripts/ # 维护脚本(库数据链 + skill 同步 + 规则校验)
  87. │ ├── sync-skills.ps1 # 多 IDE skill 镜像(-All / -TargetDir)
  88. │ ├── resolve-lib-skills.mjs # knowledge/libs §3.6 解析校验
  89. │ ├── (库 catalog 脚本在 mcp-server/scripts/,见下)
  90. │ ├── build-lib-manifest.mjs # → mcp-server/data/lib-manifests/
  91. │ ├── build-api-summaries.mjs # → mcp-server/data/lib-api-summaries/
  92. │ ├── batch-decompile.mjs # 分批反编译(源码 → $MC_SKILL_CACHE,不入库)
  93. │ └── merge-verified-api.mjs # 回填 catalog verifiedApi
  94. │
  95. ├── mcp-server/ # 本地 stdio MCP Server(89 个工具)
  96. │ ├── src/ # 工具实现(api / docs / diagnostics / wave…)
  97. │ ├── scripts/ # 文档抓取、语义索引、数据审计;含 build-library-catalog-from-authored.mjs
  98. │ └── data/ # 随仓分发的 MCP 侧数据(非 MC_SKILL_DATA)
  99. │ ├── lib-manifests/ # Modrinth 版本矩阵(slug / 条目数以文件现读为准;键结构陷阱见「反编译数据产物」表)
  100. │ ├── lib-api-summaries/ # 48 库 public API 摘要
  101. │ └── loader-api-summaries/ # Forge/Neo/Fabric-API/QSL 类摘要
  102. │
  103. └── data/ # 离线官方数据(MC_SKILL_DATA 指向此处根)
  104. ├── forge_* / fabric_* / neoforge_* / … # 各平台文档 L0/L1/L2 + semantic/
  105. ├── paper_stable/ # 服务端面**教程层**:paper-docs/(67 页,**CC BY-SA 4.0**)
  106. ├── paper-api_stable/ # 服务端面**签名层**(当前档):paper-javadoc/(Paper API 2116 类,随上游条款)
  107. ├── paper-api_<ver>/ # 服务端面签名层**历史档 ×5**(1.21.4/1.21.1/1.20.1/1.16.5/1.12.2)—— javadoc 页抽取
  108. ├── spigot_stable/ # 服务端面签名层(当前档):Spigot/Bukkit Javadoc 1396 类(**无教程正文**,见 THIRD_PARTY_NOTICES.md)
  109. ├── spigot_<ver>/ # 服务端面签名层**历史档 ×8**(1.21.8/1.21.4/1.21.1/1.20.6/1.20.1/1.19.4/1.16.5/1.12.2)—— **构件 javap** 抽取,非 javadoc
  110. ├── vanilla_<ver>/ # 原版 Registry 数据(query_registry 的数据源)
  111. ├── _models/ # 本地嵌入模型(transformers.js;唯一允许远程拉模的入口)
  112. ├── _yarn-mojmap-pairs/ # 类名级派生对照表(from=mojang 的第二档出处)
  113. └── <平台>_<ver>/mappings/ # 该档映射(Yarn SQLite / MCP CSV / TSRG 等);映射按档存放,没有全仓统一的 mappings/ 目录
  114. ```
  115. 平台版本目录内另有 `.cursor/rules/`(00–10)、`.agents/skills/`、scaffold、`knowledge/antipatterns` 等;库 Skill **只**在根 `knowledge/libs/`,经 `activate_platform_pack` 或按路径 Read,不写进各平台 skills 目录。
  116. ## 平台说明
  117. | 平台 | 状态 | 规则 / 数据(摘要) |
  118. | -------- | ---- | -------------------------------------------------------- |
  119. | Forge | ✅ 完成 | 多版本规则(主推 **1.20.1**);数据目录 `data/forge_`* |
  120. | Fabric | ✅ 完成 | 多版本规则(主推 **1.20.1 / 1.21.x / 26.1.2 / 26.2**);数据目录 `data/fabric_*`;**26.1.2 / 26.2 仅 mojmap**;26.3 只有博客级迁移摘要,无规则树 |
  121. | NeoForge | ✅ 完成 | 规则集在 `neoforge/`(主推 **1.20.4+ / 26.1 / 26.2 / 26.3**);文档数据见 `data/neoforge_*`(主文档默认 **26.1**;**26.2 / 26.3 有规则树、无本版文档**,游戏侧变更走迁移指南,见「支持版本」表注) |
  122. | Quilt | ✅ 混合 | `quilt/<ver>/` 只写 QSL 差异(00/01/05/06)+ **本档 QSL Skill 3**(registry/events/networking),02–04/07–08/10 读 `fabric/<ver>`;`search_docs(platform=quilt)` 问 QSL 不回退 Fabric Registry |
  123. | 基岩版 | ✅ 完成 | 扁平 `bedrock/`;`search_bedrock_docs` + 滞后 `docsStatus`;实验开关按 `min_engine_version` 分层 |
  124. | LiteLoader | ✅ 完成 | `liteloader/1.12.2/` 纯客户端 + `HYBRID.md`;`diagnose_gradle` 对 liteloader 插件走轻量模式 |
  125. | Rift | ✅ 完成 | **原生档 `rift/1.13/`**(Rift 件内 `profile.json` 的 `inheritsFrom` = 1.13)+ **`rift/1.13.2/` 标注为社区分支实验档**(件仍是 1.13 的,跨版本不保证);元数据 `riftmod.json`;Rift 侧签名已对真构件 `javap` 核过(`verified-api.md`);依赖走 JitPack `com.github.DimensionalDevelopment:Rift:1.0.4-106`(`dev` classifier;原 `www.dimdev.org/maven/` 已 DNS `ENOTFOUND`) |
  126. | ModLoader | ✅ 完成 | `modloader/1.6.4/` + 安全 API 表;禁止用 Forge Javadoc / `func_*` 冒充 |
  127. | Paper(服务端) | ✅ 服务端面 | (载体 `runServer`、Bukkit 抽象层、`plugin.yml`+`onEnable`;逐档 javap 改写表在插件侧零适用)。`data/paper_stable/paper-docs/`(教程 **67 页**,**CC BY-SA 4.0**);`search_docs(platform=paper)`。**签名层另占 `platform=paper-api`**:当前档 `paper-api_stable`(**2116 类**)+ **历史档 ×5**(`paper-api_1.21.4/1.21.1/1.20.1/1.16.5/1.12.2`,javadoc 页抽取)—— 教程面与签名面同平台不同树,`FabricDocStore` 单源故各占一个平台 id。规则树 `paper/26.3/rules/`(10 条);**版本档 `paper/<ver>/rules/00-applicability.md` ×5**(26.3 规则在各版的适用性 + 该版 Bukkit 核心 vs Paper 扩展) |
  128. | Spigot(只签名面)| ✅ 只签名 | 当前档 `data/spigot_stable/spigot-javadoc/`(**1396 类**)+ **历史档 ×8**(`data/spigot_<ver>/`,1.21.8/1.21.4/1.21.1/1.20.6/1.20.1/1.19.4/1.16.5/1.12.2)—— 历史档**从 maven 构件 `javap` 抽**(javadoc 无版本轴),每页 `sourceType: javap`;`search_docs(platform=spigot)`。**没有教程正文** —— SpigotMC Wiki 实测**无任何开放许可**(仅 `© SpigotMC Pty. Ltd.`)⇒ 按本仓准入不入库;要教程请用 `platform=paper` |
  129. ### 支持版本
  130. 规则树(`activate_platform_pack action=list`)与官方文档数据(`list_*_versions`)**可能不一致**:有规则无文档、或有文档无完整 00–10 规则均属正常。Agent 须以工程**精确**版本为准,禁止用邻档顶上。
  131. | 平台 | 规则树(`平台/<ver>/`) | 文档数据(`list_*_versions`) | 主推 | 备注 |
  132. |------|-------------------------|-------------------------------|------|------|
  133. | **Forge** | `1.7.10` · `1.8.9` · `1.9.4` · `1.10.2` · `1.11.2` · `1.12.2` · `1.13.2` · `1.14.4` · `1.15.2` · `1.16.5` · `1.17.1` · `1.18.2` · `1.19.4` · `1.20.1` · `1.20.4` | `1.7.10`–`1.20.4`(含 `1.8.9` / `1.9.4` / `1.10.2` / `1.11.2` 等 javadoc 档) | **1.20.1** | `1.12.2` 有 forge-docs 教程;`1.7.10` 为 javadoc 核实表 + 短规则(**ready**);`1.8.9`–`1.11.2` 是 **3 条规则 / 0 技能**的薄档(`pack.meta.json` 为 `ready`,session 可加载,但只有 00/01/09)。`forge/1.21.1` 为 **draft**(连 `.cursor/` 都没有 ⇒ `PACK_NOT_FOUND`;仅改口文档搜索) |
  134. | **Fabric** | `1.14.4` · `1.16.5` · `1.17.1` · `1.18.2` · `1.19.4` · `1.20.1` · `1.20.4` · `1.21.1` · `1.21.3` · `1.21.4` · `1.21.8` · `1.21.10` · `1.21.11` · `26.1.2` · `26.2` | `list_fabric_versions` 含上述档(**无 1.21.5**) | **1.20.1** / **1.21.x** / **26.1.2** / **26.2** | `26.1.2` / `26.2` 仅 `fabric-docs`、无 wiki;**两档均仅 mojmap**。`26.2` 的语料来自上游 latest 面(`versions/26.2` 上游仍 404),有 versioned fabric-docs 正文。`1.21.4`/`1.21.8`/`1.21.10` 有 versioned fabric-docs **和** 现行 `fabric-wiki`(wiki 不是该档历史快照)。**`1.21.5` 无 versions/ 源** → `PACK_NOT_FOUND`。禁止拷 `1.21.11`。附加数据(Data Attachments)逐档覆盖:`1.21.10` / `1.21.11` / `26.1.2` 已按**本档语料页**登记(只写该页出现的简名,FQCN / 模块 id 未核实者已注明);`1.21.4` / `1.21.8` / `1.14.4` 本档无该主题来源 → 见各档 `pack.meta.json` 的 `gaps.attachments`(`1.14.4` 规则里是**负例**,不是空洞),禁止抄邻版 |
  135. | **NeoForge** | `1.20.1` · `1.20.4` · `1.20.6` · `1.21.1` · `1.21.3` · `1.21.5` · `1.21.8` · `1.21.10` · `1.21.11` · `26.1` · `26.2` · `26.3` | `1.20.1`(回退 Forge)· `1.20.4` · `1.20.6` · `1.21.1` · `1.21.3` · `1.21.5` · `1.21.8` · `1.21.10` · `1.21.11` · `26.1`(NeoForge **没有** `1.21.4` / `1.21.6` / `1.21.7` / `1.21.9` 档;`26.2` / `26.3` 有规则树、无本版文档) | **1.20.4+** / **26.1** / **26.2** / **26.3** | 主文档默认 **26.1**;**`26.2` / `26.3` 的规则树已建、本版主文档语料缺失**(00 条的工程口径来自官方 MDK 与 sources jar,01–10 的变更走迁移指南,见表注)。`1.20.1` 本档核实表 + 短规则(Forge 兼容数据)。附加数据(Data Attachments):`1.20.4` / `1.20.6` 已按本档 `datastorage/attachments` 页 + 本档 loader-api 摘要核实(`1.20.4` docs 页把静态方法写成 `AttachmentSerializer.serializable()`,摘要内无该类,真实为 `AttachmentType.serializable()`,已在核实表钉为禁止输出);`26.1` 本档无独立 attachments 页,规则自带 fallback 标注 |
  136. | **Quilt** | `1.18.2` · `1.19.4` · `1.20.1` · `1.20.4` · `1.21.1` · `1.21.3` · `1.21.4` · `1.21.8` · `1.21.10` · `1.21.11`(**10** 档) | `search_docs({platform:"quilt"})`;`data/quilt_*` 只有 **6** 档(`1.18.2` / `1.19.4` / `1.20.1` / `1.20.4` / `1.21.1` / `1.21.11`),其余 4 档有规则无语料 ⇒ 命中会带 `fallback:"fabric"` + `sourcePlatform`,那不是 QSL 证据 | 随 Fabric 同版 | **本档 QSL Skill 3** + Fabric overlay;00/01/05/06 为 QSL 差异(有 `06-networking.mdc` 的档不要 overlay Fabric 网络),02–04/07–08/10 读 `fabric/<ver>`。`1.21.11` 是 MC **1.21.11**,不是 `1.21.1` 笔误(两档并存、不得互顶);该档 QSL / QFAPI 已停更且本版本无可用构件,口径见 `quilt/1.21.11/AGENTS.md` 顶部横幅与 `00-project-setup.mdc` |
  137. | **LiteLoader** | `1.8.9` · `1.10.2` · `1.12.2` | `search_docs({platform:"liteloader"})`(官方 wiki + hybrid 语义库;API 以核实表为准) | **1.12.2** | 三档都有**构件级签名面**(各档 `knowledge/common/api-surface.md`,由构件 `javap` 直读:1.12.2 73 类 / 249 签名、1.10.2 72 / 230、1.8.9 70 / 209);`1.8.9` / `1.10.2` 的 `pack.meta.json` 是 `draft` ⇒ `session` 直接拒(`PACK_NOT_FOUND`,盘上那 11 条规则不得当已加载),只能走 `search_docs`;纯客户端;与 Forge 混合见 `HYBRID.md` |
  138. | **Rift** | `1.13`(原生档)· `1.13.2`(社区分支实验档) | `search_docs({platform:"rift"})`(官方 wiki + hybrid;方法名以核实表为准) | **1.13** | 件内 `profile.json` 的 `inheritsFrom` = **1.13** ⇒ 原生线只到 1.13;1.13.2 无原生件、跨版本不保证;两档 Rift API 同构件(39 个 listener 接口),Gradle `runClient` 里 listener **不派发**(dev 环境 deobf vs target notch 名),验它要用真实 client jar |
  139. | **ModLoader** | `1.2.5` · `1.5.2` · `1.6.4` | 无 Java 文档树 | **1.6.4** | `1.2.5` / `1.5.2` 的 `pack.meta.json` 是 `draft` ⇒ `session` 直接拒(`PACK_NOT_FOUND`);盘上规则不得当已加载,禁止用 `1.6.4` 顶替;只用 safe-api 表;禁止 Forge Javadoc |
  140. | **基岩版** | 扁平 `bedrock/`(`*`) | `search_bedrock_docs` + `docsStatus` | 按 manifest | 无 `平台/<ver>/` 分档;实验开关按 `min_engine_version` |
  141. | **Paper(服务端面)** | `26.3`(规则树 `paper/26.3/rules/` 10 条)+ **版本档 ×5**(`paper/<ver>/rules/00-applicability.md`:`1.21.4` · `1.21.1` · `1.20.1` · `1.16.5` · `1.12.2`) | `search_docs({platform:"paper"})`:教程 **67 页**(**CC BY-SA 4.0**,上游**不按 MC 版本分**,只有当前文档) | **26.3** | 载体 `runServer`(不是 `runClient`);版本档**不复制** 26.3 的十条正文 —— 只给「26.3 规则在该版的存活」+「**该版 Bukkit 核心 vs Paper 扩展**」(后者实测抓到 `ItemMeta#setDamageType` 只在 Paper 面) |
  142. | **Paper API(签名面)** | 无规则树(签名面不是规则载体) | `search_docs({platform:"paper-api"})`:当前档 `stable` **2116 类** + 历史档 ×5(`1.21.4` 1871 · `1.21.1` 1702 · `1.20.1` 1496 · `1.16.5` 1254 · `1.12.2` 877) | **stable** | 与 `paper` 同平台**不同树**(`FabricDocStore` 单源故各占一个平台 id);历史档走 javadoc 页(`jd.papermc.io/paper/<ver>/`);**全部已建语义库** |
  143. | **Spigot(签名面)** | 无规则树 | `search_docs({platform:"spigot"})`:当前档 `stable` **1396 类** + 历史档 ×8(`1.21.8` 1352 · `1.21.4` 1335 · `1.21.1` 1282 · `1.20.6` 1251 · `1.20.1` 1186 · `1.19.4` 1173 · `1.16.5` 1027 · `1.12.2` 779) | **stable** | 历史档从 **maven 构件 `javap`** 抽(javadoc 站无版本轴),每页 `sourceType: javap`;无教程正文(SpigotMC Wiki 无开放许可)⇒ 要教程用 `platform=paper`;GPL-3.0 构件派生面的边界见 `THIRD_PARTY_NOTICES.md` |
  144. > **MC 26.2 / 26.3 怎么支持(模组面)**:按加载器分开看。**Fabric 26.2** 是完整档:`fabric/26.2` 11 条规则 + 脚手架 + `data/fabric_26.2` 的 fabric-docs 正文(`list_fabric_versions` 含 26.2)。**NeoForge 26.2 / 26.3** 规则树已建(`neoforge/26.2` / `neoforge/26.3` 各 11 条),但官方主文档没按版本分线、本仓没有这两版语料(`list_neoforge_versions` 不含):00 条的工程口径(plugin、`neo_version`、Java 25、runs、modMetadata)来自官方 MDK 与 sources jar,01–10 的变更走 **26.1 → 26.2 → 26.3 迁移指南**(`get_migration_guide` 的 `route="26.1->26.2"` / `"26.2->26.3"`,源 = NeoForge Primer),配合 `analyze_porting_path`。**Fabric 26.3** 上游 docs 移植 PR 尚未合并,既没有规则树也没有正文,只有博客级迁移摘要(`data/fabric_porting/26.3.md`,`source=porting-extra`),不能当类签名出处。官方文档发布后同步补档。
  145. > **服务端面的 `26.3` 是另一条线**:`paper/26.3/rules/` 是 Paper 服务端规则树(载体 `runServer`),与上面这条模组面迁移路线无关,两者不要互相套。
  146. 查询本机已建档列表:`node mcp-server/dist/cli.js activate_platform_pack --action=list`;文档档:`list_forge_versions` / `list_fabric_versions` / `list_neoforge_versions` / `list_doc_versions`。
  147. ## 快速开始
  148. ### 安装
  149. 见开头
  150. **对 AI(打开一个 MC Mod 项目时):**
  151. > 按根目录 `AGENTS.md` 判断平台与**精确**版本,然后调用 `activate_platform_pack action=session` 加载该档规则 / Skill 索引(不要直接读邻版 `平台/<ver>/.cursor`)。官方文档先 `list_*_versions`,再把 `version` 写死成工程版本去 `search_*_docs` / `search_docs`。创意设计由用户拍板;兼容取舍 / API 选择默认也由用户决定,用户不想或没能力决定时可代劳,但必须按下方「解释模板」说明(模板已同步写入根 `AGENTS.md`「人在环」节,对 Agent 强制生效);写盘 / Gradle / 拷 jar / 上传须确认后再做(人在环,不是无人值守流水线)。
  152. ### 解释模板(代劳决策时的强制说明格式)
  153. > 权威文本在根 `AGENTS.md`「代劳决策解释模板」。本节是同结构副本 —— **改任一处必须同步 `README.md` / `README.en.md` / `AGENTS.md` 三处**(暂无机器门,靠人工守)。
  154. **先判风险,再决定什么时候开口**:
  155. | 这一代是什么性质 | 什么时候说 | 等不等回复 |
  156. | --- | --- | --- |
  157. | 低风险:某个 API 写法、某个依赖版本 | 做完就说,写在同一轮回复里 | 不等 |
  158. | 高风险:换加载器平台、改包结构、删依赖、改构建脚本 | 动手前说 | 等用户回复 |
  159. | 用户已说「不用问我,直接做」「你决定就行」 | 做完就说 | 不等,但必须给回退方法 |
  160. **说明必须含五要素,按此顺序,一段只讲一件事**:
  161. 1. **选择了什么** —— 写名字和版本。例:Forge 1.20.1 的 `SimpleChannel`。
  162. 2. **为什么这样选** —— 只写与当前版本或用户工程实况有关的理由。「业界惯例」不算理由。
  163. 3. **替代方案与未采用的原因** —— 一到两个,每个一句。
  164. 4. **影响与风险** —— 用户因此要检查什么、注意什么。
  165. 5. **怎么回退** —— 改哪几处、改回什么。
  166. **第一行照这个格式开头**:
  167. > 我已替你选择使用 `DeferredRegister`,原因见下。
  168. **每条出处必须能核对**:给 `search_*_docs` 的命中页 id 或 URL、规则编号、或官方文档链接,三者之一。查不到就写 `// TODO(未核实)`,不得凭记忆补名字,不得只写「最佳实践」。
  169. **语言跟着用户走**:用户说「不太懂技术」或「你决定就行」,就讲结果、少堆术语(例:「这样写以后升级 Forge 时要多改两处」);用户是专业开发者,就给类名、方法签名、文档链接。两种写法都要满足上面的五要素与出处要求 —— 换的是措辞,不是内容。
  170. **完整示例**(照形状写,事实按你的版本重查):
  171. > 我已替你选择使用 `SimpleChannel`,原因见下。
  172. >
  173. > 1. 网络包注册用 Forge 1.20.1 的 `SimpleChannel`(`NetworkRegistry.newSimpleChannel`)。
  174. > 2. 你的加载器是 NeoForge 1.20.1,它是 Forge 兼容层,官方文档仍只给 `SimpleChannel`(出处:`search_neoforge_docs version=1.20.1` 命中页 `1.20.1/networking_simpleimpl`,该页正文逐字含此名)。
  175. > 3. 另一条路是 `CustomPacketPayload` + `IPayloadRegistrar`:这一套从 NeoForge 1.20.4 起才有文档页(`networking/payload` 在 1.20.1 返回 `DOC_NOT_FOUND`),你的版本用不了。
  176. > 4. 影响:代码在编译期依赖 `net.minecraftforge` 包,请确认工程已含该依赖。
  177. > 5. 回退:改动只在你自己的网络注册类(官方文档示例命名 `ModidPacketHandler`);日后升到 1.20.4+ 时,把该类的 channel 建法换成 payload 注册即可。
  178. **对新项目使用脚手架:**
  179. > 使用对应平台版本下的 `scaffold/`(如 `forge/1.20.1/scaffold/`)生成带规则的项目骨架。
  180. **多 IDE 同步:**
  181. > 修改 `.cursor/` 后,在该版本目录运行 `sync-skills.ps1`。
  182. **配置本地 MCP Server:** 见上面「安装(第一次用先看这里)」;各宿主的配置格式与验收步骤以 [AUTO_SETUP.md](./AUTO_SETUP.md) 为准(**不要默认 Cursor 的 `mcp.json`**)。
  183. ## 模组测试流程 loop:两段
  184. 真机测试拆成两段 loop,**覆盖面不同**:
  185. | 段 | loop 内容 | 覆盖面 | 承载 |
  186. | --- | --- | --- | --- |
  187. | **前半** | agent 写码 → 构建 → **自动起游戏** → 看崩溃 → 改码 → 再测试 | **所有平台**(Forge / Fabric / NeoForge / Quilt / LiteLoader / Rift / ModLoader / 基岩) | `mc-build-mod`、`mc-ingame-iterate`(步骤清单,人在环);构建/启动报错与崩溃由 `inspect_runtime` / `analyze_log` / `crash_analyze` 读 `<gameDir>/logs/latest.log` + `crash-reports/`;基岩侧读 content log(`analyze_bedrock_log`) |
  188. | **后半** | 自动起游戏 → **进游戏自己操作、测试** → 拿证据回传 → 改码 → 再测试 | **MC 1.20.1 及以上(含 1.20.1)** 的 Java 平台:Fabric / Quilt / Forge / NeoForge | `generate_playtest_driver`(无桥:进程内临时 driver;有桥:BlackBoxPro 动作序列)+ `playtest_bridge` / `playtest_intent` / `inspect_playtest_evidence`;工作流 `mc-ingame-playtest` |
  189. **两条路线**:
  190. - **无桥(进程内 driver)**:`generate_playtest_driver driverMode=temporary_client_tick_driver`(或 `in_jvm_player_agent`:LLM 通过 `<evidenceDir>/intent.json` 邮箱逐步下意图)。driver 编进被测工程,进游戏后按剧本(`smoke` / `village` / 自定义 `plan` DSL)自己操作、断言、取证;**长驻 + 剧本热载**(改 `<evidenceDir>/plan.txt` 即在同一进程开新一轮,不重启游戏)。证据 = `state.json` / `exit-code.txt` / `qa.log` / `rounds.jsonl` + 截图。
  191. - **有桥(第三方桥 mod)**:预编译桥 mod(当前 = BlackBoxPro,MIT)装进游戏实例,经 `127.0.0.1` 用 `playtest_bridge` 发动作/查询/截图(**端口不传即从 38081 递减扫描到 38071**,按 `/status` 载荷形状握手选实例);证据 = `calls.jsonl` + 截图 + query 响应。桥件的 MC 覆盖由第三方发布决定:BlackBoxPro 现行件覆盖 fabric/neoforge **1.21.1**、**1.21.11** 与 forge **1.12.2**;本仓只按实测过的组合记账,明细见 `community_knowledge/authored/ingame-playtest-automation.md`,别把别的档当成已验证。
  192. **证据判读统一入口**:`inspect_playtest_evidence`(三态 `present|absent|unreadable`,缺件不得读成“没有失败”);**多客户端(多会话)**用 `inspect_playtest_multi`(逐客户端三态 + **联合判绿** + 锚点 + 会合 marker,任一客户端目录越出授权根整体拒);执行权与授权见根 `AGENTS.md`「人在环例外:游玩自测(三通道)」。
  193. ### 测试要求:交付前必须测到什么程度
  194. 上面的 loop 是机制,本节是**交付门槛**:改动不以编译通过为交付,交付前必须测全。逐层「用什么工具、红会长什么样」的完整表在根 `AGENTS.md`「游玩测试要求(交付门槛)」,本节是其摘要。
  195. **阶梯(低层判红即不得进入高层)**:L0 构建 → L1 结构与静态校验 → L2 数据面(配方 / 战利品 / 标签 / 方块状态 / lang)→ L3 GameTest 自动化 → L4 真机冒烟 → L5 场景验收(**本次改动**那个玩家可见行为)→ L6 服务端与多人 → L7 回归与共存 → 发布前收口。
  196. **最低线按改动面取最大者**:
  197. | 改动 | 最低测到 |
  198. | --- | --- |
  199. | 逻辑 / 注册 | L3(GameTest) |
  200. | 玩家可见行为(方块 / 物品 / 实体 / GUI / 配方效果 / 世界生成) | L4 + L5 |
  201. | 网络 / 存档 / 服务端侧 | L6 |
  202. | 升 loader 或 MC 版本 | L0–L7 全跑 |
  203. | 纯文档 / 注释 | L0 |
  204. **「全面」指把维度铺开,不是同一条路径重复多遍**:改动面(代码 / 资源 / 数据 / 配置 / 平台元数据)、平台 × 版本(每个目标档各测一遍,不得用邻版结果顶替)、客户端与服务端**双侧**、新世界与旧存档升级、权限档(生存 / 创造 / 授权)、边界与异常(空满背包、目标方块不存在、区块未加载、死亡与重连、非房主加入)、表现面(模型与纹理、GUI 溢出与缩放、`en_us` 与 `zh_cn` 每个键都有值)、日志面(`latest.log` 无新增 `ERROR`、`crash-reports/` 为空;基岩看 content log)。
  205. **判红(fail-closed)**:缺证据 = 没通过。`absent` 不等于「没有失败」;`exit-code.txt` 非 `0` 或不在盘上 ⇒ 红。真 driver 覆盖 = 生成器内 `PLAYTEST_VERIFIED_TIER`(唯一真源,正文不数档),**表外版本不等于免测** —— 走桥路线或人工游玩,并如实写「人工验过 / 未验」。`MC_SKILL_PLAYTEST_INTENT_E2E` 未设 ⇒ 按未验证处理,不静默通过。
  206. **与人在环的边界**:门槛规定「必须测」,不改变「谁去跑」—— 跑 Gradle、起游戏仍受三通道授权约束。没拿到授权就在交付里写明「本轮未真机验证」,并把上面这张清单交给用户照着跑,**不得**替用户宣布通过。
  207. ### 后半 loop 教程:三条路线,逐步跑通
  208. > 本节回答"**从零怎么把游戏跑起来、让 agent 在里面自己玩并留下证据**":三条路线逐步走 + 运维散件集中在这里。**跑前必读的真机台账与能力边界见文末「指针表」。**
  209. **三条路线怎么选**:
  210. | 路线 | driverMode / 工具 | 覆盖 | 适合 | 主要代价 |
  211. | --- | --- | --- | --- | --- |
  212. | ① 有桥 | 桥 mod + `playtest_bridge` | BlackBoxPro 预编译件(fabric/neoforge 1.21.1+1.21.11、forge 1.12.2)**或**本仓自建最小桥(**9 目标** = `forge 1.7.10–1.12.2` + `rift 1.13` / `1.13.2` + `modloader 1.6.4`,`generate_playtest_driver driverMode=external_bridge` 附赠;**rift 两档同一真模板,modloader 只到骨架**) | 到手最快、动作集大 | 版本覆盖窄;自建桥动作 10 个、按档 fail-closed;桥无鉴权 ⇒ 只本机短会话 |
  213. | ② 无桥剧本 | `generate_playtest_driver driverMode=temporary_client_tick_driver` | 已验证档出真 driver;其余档结构壳 | 确定性回归 / CI 复现 | 要装驱动 + 供世界 |
  214. | ③ 无桥意图会话 | `driverMode=in_jvm_player_agent` + `playtest_intent` | 真执行器覆盖 = `PLAYTEST_VERIFIED_TIER`(生成器内表,随取证扩面,**正文不数档**;表外档只出菜单契约 + 结构壳) | agent 实时决策、"选错→判红→换意图" | 观测粒度 = 每条意图一次;v1 `goto` 无寻路 |
  215. > **能力分界(先读这条,别混读)**:路线 ①(桥)是**命令级** —— 发聊天包、不是键位输入 ⇒ 读数 / 观察 + `/tp` `/setblock` 这类命令可用(受实例 op 约束);**走位 / 跳跃 / 挖掘耗时 / 碰撞 / GUI 点击测不了**。路线 ② ③(driver)是**玩家级** —— 真按键原语(`forward` / `back` / `left` / `right` / `jump` / `sneak` / `sprint` / `attack` / `use`)+ 步骤 `move` / `goto` / `break` / `gui` / `look` / `scan` / `shot` / `assert` ⇒ **走位 / 跳跃 / 挖掘 / GUI 交互都做得到**。**「测不了」那条只限定路线 ①,不是整条链的上限。**
  216. #### 路线 ① 有桥(最快)[部分第3方模组支持与远古版本预制]
  217. 1. **授权**:`MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT=<绝对路径>`(三通道与禁令见根 `AGENTS.md`「人在环例外:游玩自测」)。
  218. 2. **装桥**:BlackBoxPro 对应端 jar + 依赖(fabric 端需 fabric-api 与 FLK);**来源/版本/sha256 记账**,jar 只进授权根。
  219. 3. **起游戏 → 探活**:`playtest_bridge action=status` ⇒ `ready=true` 才算"已进世界"(`actions` 每档不同,以桥 `/status` 自报为准,不抄别档数字)。
  220. 4. **进世界**:`execute create_world` / `join_world` —— 建世界要几十秒,**响应超时 ≠ 失败**(实测超时后世界里其实已建好)。
  221. 5. **驱动**:动作序列由 `generate_playtest_driver driverMode=external_bridge` 出(`playtest/actions.json` + 后置条件 + 证据约定);单步 `execute`,复合动作 `batch` + `delay`,"等条件"用 `await`(桥没有 `wait_until`;超时映射 `PLAYTEST_TIMEOUT`,**不得塌成"没失败"**)。
  222. 6. **判读**:`inspect_playtest_evidence`(三态 `present|absent|unreadable`)+ `calls.jsonl` + 截图;失败 → 改码 → `mc-build-mod` 重建 → 重跑。
  223. #### 路线 ② 无桥剧本 driver(面最广)
  224. 1. **建工程**:把对应档 scaffold 拷到 `<ROOT>/<平台>-<版本>` —— **工程目录即游戏根**(`run/` 就是 gameDir,不改 runDir DSL)。JDK 分线:1.20.1 线 JDK 17、1.21.x 线 JDK 21、**26.1+ 线 JDK 25**(`diagnose_gradle` 对 26.1 的 toolchain 是硬判,见「工具陷阱」前的工具表)。
  225. 2. **关失焦暂停(必做)**:`<gameDir>/options.txt` 写 `pauseOnLostFocus:false` —— 否则按键位移恒 `0.00`(强杀进程时 MC 不会自己写这份文件,得手建)。
  226. 3. **生成驱动**:`generate_playtest_driver{platform, version, driverMode:"temporary_client_tick_driver", enterWorld:"<存档名>" 或留空, evidenceDir:"<授权根内绝对路径>", plan:[…] 或 scenario:"smoke"|"village"}` ⇒ `PlaytestQaDriver.java` 放进 `src/main/java/<pkg>/playtest/`,客户端入口加一行 `PlaytestQaDriver.register();`。
  227. 4. **供世界**:`<gameDir>/saves/<存档名>/level.dat` 必须存在 + `allowCommands=1`(`/locate` 等 `cmd` 类步骤需要)—— 做法见下面「运维散件」。
  228. 5. **跑**:`gradlew build` → `gradlew runClient`;日志里程碑 `[QA] driver registered` → `[QA] open world requested` → `[QA] ROUND 1 START` → `[QA] DONE ::` / `[QA] ERROR:`。
  229. 6. **热载**:改动作/断言/坐标只改 `<evidenceDir>/plan.txt`(同一进程内开新一轮,**不重启游戏**);只有 driver/被测 mod 的 Java 源码变了才重建重启。
  230. 7. **判读 + 撤除**:同路线 ① 的判读;收工按 `playtest/REVERT.md` 删驱动与调用行(**绝不提交**)。
  231. #### 路线 ③ 无桥意图会话(agent 实时下意图;详细)
  232. > 与路线 ② 的关系(**两条不是并行系统**):同一个驱动、同一个解释器;意图只是"展开成原语子计划"的步骤,外层剧本退化成一条 `waitintent` 守候环。同一 tick 只有一个计划在跑。
  233. 1. **前置**:同路线 ② 的 1–2 步 + **已验证档**(真执行器覆盖 = `PLAYTEST_VERIFIED_TIER`,唯一真源、随取证扩面——正文不数档;表外档只出菜单契约 + 结构壳,不会假装能跑)。
  234. 2. **进世界**:按该档配方 —— 冻结族(`fabric 1.20.4 / 1.21.1 / 1.21.3`)用 vanilla quick play(`build.gradle` 的 loom runs 加 `programArgs "--quickPlaySingleplayer", "<存档名>"`)且 `enterWorld` **留空**;`1.21.11` 线可直接 `enterWorld:"<存档名>"`。
  235. 3. **生成**:`generate_playtest_driver{platform:"quilt", version:"1.21.11", driverMode:"in_jvm_player_agent", capabilityProfile:"operator"|"creative"|"strict_survival", evidenceDir:"<授权根内绝对路径>", budgetTicks:36000}` ⇒ 出五件产物 + **`playtest/intent-menu.json`**(菜单契约);默认剧本 = `mark in_jvm:intent-session` + `waitintent max=6000`。
  236. 4. **装 + 跑**:同路线 ②;到 `[QA] ROUND 1 START` 后,进世界的第一条 `waitintent` tick 会把 `state.json`(观测面)补种出来。
  237. 5. **观测(read)**:`playtest_intent{action:"read", evidenceDir}` ⇒ 观测面:`intentState`(档位/菜单/邮箱/剩余预算/当前意图)、`intents[]`、`lastIntent`、`scan.nearest{found,id,x,y,z}`、`goto{x,z,arrived,arrivedDist}`,外加 `menu`、`mailbox` 状态与 **`nextSteps`**(上一条失败时 = 该意图菜单里的 fallback)。
  238. 6. **下意图(write)**:`playtest_intent{action:"write", evidenceDir, intent:"walk_to", params:{x:10,z:-20,tol:3}, confirmed:true}` ⇒ 写 `<evidenceDir>/intent.json`(扁平 JSON)。**写侧六段校验**:confirmed → 禁列(`kill`/`tnt`/`fill`)→ 13 意图菜单 → 参数白名单 → 必填 → 邮箱占用(占用回 `MAILBOX_BUSY`,除非 `overwrite=true`);非法**在写侧就拒**,不进执行器。**两条易用性边界(`fabric 26.1.2` 真机实测)**:① **菜单默认查找会落空** —— 生成器把 `playtest/intent-menu.json` 写在**工程根**,而工具默认按 `<evidenceDir>/intent-menu.json` → `<evidenceDir>/../playtest/intent-menu.json` 两级找;`evidenceDir` 推荐放在工程之外(`<授权根>/instances/<tag>/evidence-intent`)时两级同时不中 ⇒ **必须显式传 `menuPath=<工程根>/playtest/intent-menu.json`**,否则 `MENU_NOT_FOUND`。② **`observe` 必须给 `entities=` 或 `blocks=`** —— 只给 `radius=` 会被判红 `observe_need_scan`(v1:空扫无判据),这是 fail-closed 设计、不是 bug。
  239. 7. **会话循环**:`read` 看观测 → 选意图(失败就按 `nextSteps` 换)→ `write` → driver 消费(`intent.json` 改名 `intent.done.json`)→ 展开原语执行 → 判**唯一一条**类型化后置条件 → 写 `intents[]` + 刷新 `state.json` → 回守候。**失败不得自动重试**(一次性意图重试会重复消耗方块/触发副作用),只许换意图。
  240. 8. **收尾**:`write {"intent":"stop"}` ⇒ 收尾本轮(**不关游戏**);之后按 `playtest/REVERT.md` 撤除。
  241. **两条运维口径(`fabric 26.1.2` 真机实测)**:`state.json` 的 `at` 是**最后一条意图的时间**(不是文件写入时间)⇒ 判驱动是否在跑要看**进程 + 文件 mtime + `intent.done.json`**,`at` 不可用作存活判据;`screenshot` 的 PNG 落 **`<gameDir>/screenshots/`**(`runClient` 的 gameDir = `run/`),不是工程根。默认剧本 `waitintent max=6000`(5 min)可能在你发首条意图前过期(整轮判红)——**驱动不退出**、回到守候 `plan.txt` 的 idle 态,**重写一次 `plan.txt` 即在同一进程开新一轮**(`max=30000` 更稳)。该链逐条读数(`observe`→`walk_to`→`screenshot`→`stop` 五意图全绿、`exit-code=0`)见游玩自测口径单源 [`community_knowledge/authored/ingame-playtest-automation.md`](./community_knowledge/authored/ingame-playtest-automation.md) 的「意图空间 · 执行器落地面」节(入口行在文末「指针表」)。
  242. **失败语义(三条线里最要紧的差别)**:邮箱形态失败 = **数据**(`intents[]` 记 `ok:false` + `failure` 字段)并**继续守候**(会话不死);协议违规(禁列/不在菜单/档位不符)在写侧就被工具拒;脚本形态(`plan.txt` 里的 `intent` 步骤)失败 = **判红停轮**。
  243. **预算与协议**:单意图上限 = 菜单 `budgetTicks` 列(`walk_to` 1200 / `find_and_goto` 9000 / 其余 60–600);单次守候 5 min(`waitintent max=6000`);整轮默认 30 min(`budgetTicks=36000`);邮箱**单槽**(一条在跑时新写的只在邮箱等,再写会被拒)。参数写错(如 `x=abc`)判红 `param_not_number`,**不会**静默用默认值。
  244. **v1 落地面与已知限制**:已实现 = `walk_to` / `look_at`(yaw|pos) / `find_and_goto`(structure|block|entity) / `observe` / `open_gui` / `inventory` / `screenshot` / `wait`(ticks) / `tp`(op/creative) / `stop`;`mine`/`place`/`interact` 与 `wait until=` 未实现(命中即判红,不静默)。`goto` **无寻路**(直线 + `fly` + 巡航 140/防卡;复杂地形超时 → 换意图);`structure` 形态需该世界开作弊;`block` 形态垂直采样只有 `-4..+8` 薄层(先在目标高度附近);`entity` 只覆盖追踪范围 ≈48 格;村内扫不到村民先怀疑废弃村(换个村再扫)。
  245. **四会话真机读数**(`quilt 1.21.11` / `operator`:换意图链、实体 / 方块正例、截图 `ageMs` 新鲜度判据、`walk_to{x:abc}` 负例,四条全 `exit-code=0`)见上文「意图空间 · 执行器落地面」节(同一口径单源);逐档矩阵与现行判据见文末「指针表」的游玩自测行(§真机台账 = 现行判据 T5 + 历史归档 T0–T4)。
  246. #### 后半 loop 运维散件(散在各处,集中在这里)
  247. | 事项 | 做法 |
  248. | --- | --- |
  249. | JDK 分线 | 1.20.1 线 **JDK 17**;1.21.x 线 **JDK 21**;26.1+ 线 **JDK 25**(`JAVA_HOME` 指到对应版本;旧线可加 `-Porg.gradle.java.installations.paths=<jdk17>`) |
  250. | 授权 | `MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT=<绝对路径>`;证据与驱动只留该根 |
  251. | 失焦暂停 | `<gameDir>/options.txt` 写 `pauseOnLostFocus:false`(强杀后 MC 不会自己写;只有这一行也能跑) |
  252. | 世界供给 | 用**同 MC 版本**的 vanilla 服务端造一次世界(`eula=true` + `server.properties` 指定 `level-name` / `gamemode=creative` / `online-mode=false`)→ 到 `Done (…)` 后 `stop` → 把 `saves/<名字>/` 复制进各档 `<gameDir>/saves/`(同版本跨加载器互通);**开作弊** = `level.dat`(gzip NBT)把 `allowCommands` 载荷字节 `0→1`(等长改写;定位按"名字前 3 字节是 tag 类型、前 2 字节是长度");改完**先确认没有客户端持有该世界**(否则旧客户端退出时会把值写回 0) |
  253. | 进世界(冻结族) | `fabric 1.20.4 / 1.21.1 / 1.21.3` **不要**让 driver 调 `IntegratedServerLoader.start`(会把 Render thread 冻在等服务器载入的 `Thread.sleep`,jstack 实证)⇒ vanilla quick play(`--quickPlaySingleplayer "<存档名>"`)+ `enterWorld` 留空;`1.21.11` 线可用 `enterWorld` |
  254. | 资源卡住 | 首跑 `:downloadAssets` 失败/长时间无输出:ForgeGradle 与 Loom 的 assets 缓存**可互借**;缺件按官方 manifest → `assetIndex.id` → `indexes/<id>.json` 定位对象 → 比大小补件;坏件(截断)用真实例 `assets/objects/xx/<hash>`(内容寻址、同路径)覆盖 |
  255. | 首跑死在 mixin prepare | `fabric 1.20.1 / 1.20.4 / 1.21.1` 的老 clone:scaffold 的 `filesMatching` 补 `examplemod.mixins.json`(已在库修) |
  256. | 关客户端 | 精确杀真身 JVM(命令行含 `-Dfabric.dli.config` 的那个 `java`);**只杀 `gradlew` wrapper 不够** —— 残留客户端会占存档 `session.lock`,下一轮进世界报"另一个程序已锁定文件的一部分" |
  257. | 独立实例 | 每次运行用独立 runId / 独立实例(共用 runDir 会静默互相覆盖截图) |
  258. | 证据判读 | `inspect_playtest_evidence`(三态;**缺件不得读成"没有失败"**);`rounds.jsonl` **每行一条合法 JSON**(条目 `{intent,params,ok,postcondition\|failure,detail}`);截图看新鲜度 `ageMs`(负值属时钟抖动);`qa.log` 必须是 `.log`(判读器按"目录内任意 `.log` 尾部"抽 `[QA]` 段) |
  259. | 撤除 | 删驱动文件 + `register()` 调用行,证据只留授权根;`git status` 自检零命中 —— **绝不提交** |
  260. ## 社区知识与库模组
  261. 与 `data/` 下的**官方** Forge/Fabric/NeoForge 文档分离,本仓库另有两套实务知识,供 Agent 在「发布 / 崩溃 / 软依赖 / 库选型 / 依赖树」等场景使用。**二者都不替代** `search_*_docs` 或 `query_api`。
  262. ### 社区实务知识(`community_knowledge/`)
  263. | 目录 | 含义 | Agent 注意 |
  264. |------|------|------------|
  265. | `authored/` | 本仓库自写短文(可改) | 实务清单与反模式,**不是 API 规范** |
  266. | `permitted/` | 作者许可入库的社区帖提炼 | 仍不确定时打开原文 URL |
  267. | `links/` | 仅标题 / 摘要 / 外链 | **禁止**把网页正文当已入库全文 |
  268. 索引:`indexes/index-l0.json`(逐来源计数以该文件为准,重建:`npm run community:index`)。MCP:`list_community_sources` → `search_community_docs` → `get_community_doc_summary` / `get_community_doc_full`。环境变量 `MC_SKILL_COMMUNITY` 可改根路径。
  269. **主题速查**:发布 / 崩溃 / 软依赖 / 机器 GUI / 本地化 / 代码模式(`patterns/`)等。**库集成**另有 `authored/lib-*.md` 系列短文 + 总览 `library-catalog-2026`、陷阱 `lib-traps-2026`、配方集成 `library-integration` / `library-integration-jei-emi`。
  270. **强制规则**:依据社区短文写代码前,若方法名 / 版本细节不确定,必须先查短文给出的原文或官方文档。
  271. ### 库模组知识体系(`knowledge/libs/` + 数据链)
  272. 三层结构(详见下文 MCP 工具 **§7 / §7.5**):
  273. 1. **社区短文** — `authored/lib-*.md`,经 `search_community_docs` 检索;含反编译验证小节(`verifiedApi` 来源)。
  274. 2. **库 Skill 源稿** — `knowledge/libs/<group>/mc-<name>/SKILL.md`,**不落盘**到平台 `.cursor/skills`;按 `AGENTS.md`「库模组 Skill」解析:platform → 组映射(`forge-only`+`all-platforms` / `fabric-only`+`all-platforms` / `neo-only`+`all-platforms` / `bedrock-only`)+ frontmatter 二次过滤。不确定选哪个库 → 先读 `knowledge/libs/all-platforms/mc-lib-catalog/SKILL.md`。
  275. 3. **数据链** — 短文 frontmatter → `mcp-server/scripts/build-library-catalog-from-authored.mjs` → `library-catalog.ts` + `lib-manifests/all.json` + `lib-api-summaries/` → `check_dependencies` 识别依赖与版本窗口。(计数与口径见 `CONTRIBUTING.md` §库数据链计数口径;脚本位置见 §7.5 表)
  276. **Agent 推荐路径(库相关)**:`check_dependencies`(看 `detectedLibraries`)→ `search_community_docs`(`lib-<name>` 或 `library-catalog-2026`)→ 按 `skillId` 或名称 Read `knowledge/libs/.../SKILL.md` → 仍缺签名再走 `search_*_docs` / `query_loader_api`。
  277. ## 环境变量
  278. **常设(多数用户会碰到的)**
  279. | 变量 | 说明 | 示例 |
  280. | ----------------------- | -------------------------------------- | --------------------------------- |
  281. | `MC_SKILL_DATA` | 数据目录根路径(指向 `data/`,不含版本子目录) | `<仓库根>/data` |
  282. | `MC_SKILL_COMMUNITY` | 社区知识库根路径(默认仓库根 `community_knowledge/`) | `<仓库根>/community_knowledge` |
  283. | `MC_SKILL_ALLOW_WRITE` | `1` 时允许 `port_project` / `mc_skill_update` 等写盘 | `1` |
  284. | `MC_SKILL_AUTO_MODE` | `1` 时开启**工程沙箱内全自动模式**(默认关闭):放开 `MC_SKILL_PROJECT_ROOT` 内写盘确认 / Gradle / 自主决策与工作流停顿;`MC_SKILL_PLAYTEST_ROOT` 仍须单独显式设置(设了则免确认并放开根内 `eula.txt` 与 `kill`/`tnt`/`fill`);`mc_skill_update`、MDK SHA256 校验、禁写本仓、正式 `.minecraft` 与上传发布仍严格保持禁止/需确认 | `1` |
  285. | `MC_SKILL_PROJECT_ROOT` | 写盘允许的项目根(绝对路径) | `<你的模组工程绝对路径>` |
  286. | `MC_SKILL_STRICT` | `1` 时数据无效则 MCP 启动失败 | `1` |
  287. | `MC_SKILL_DEBUG_PATHS` | `1` 打印路径解析过程(诊断“找不到 data/”时先开它) | `1` |
  288. | `MC_SKILL_CACHE` | 反编译 / MDK / loader-jar 缓存根。MCP 与脚本都读此变量;不设则 **MCP 默认 APPDATA、脚本默认 `os.tmpdir()/mc-skill-cache`**,两边会分家(批处理请显式设成同一路径) | `%APPDATA%/mc-skill-cache`(脚本回退 `os.tmpdir()/mc-skill-cache`) |
  289. | `JAVA_HOME` | 反编译 / remap 优先探这个 JDK(需 17+)。**未设或指向 <17 会回退 PATH 上的 `java`**,两者取可用的最高 major;都不可用才回 `TOOLCHAIN_MISSING` | `<Temurin 17+ 安装目录>` |
  290. | `MC_SKILL_PLAYTEST_ALLOW` | `1` 时放开游玩自测三通道的授权闸(须与 `MC_SKILL_PLAYTEST_ROOT` 成对出现) | `1` |
  291. | `MC_SKILL_PLAYTEST_ROOT` | 游玩自测授权根(绝对路径;目标 realpath 必须落在其内) | `<授权实例存档根>` |
  292. | `MC_SKILL_SKIP_DOWNLOAD` | `1` 时反编译工具跳过一切下载并诚实失败。**须显式设成逐字 `1`** 才生效(实现是严格比较 `=== "1"`,见 `mcp-server/src/decompile/java/java-process.ts:168`;不设或设 `true` 均不生效)。本仓 `.github/workflows/` **四支工作流均已设该变量**。覆盖范围只有 `get_minecraft_source` / `decompile_mod_jar`(`download_official_mdk` 不读它,走自己的 pin 门) | 未设(默认按需下载) |
  293. **进阶 / 排障(按需;多数场景不必设)**
  294. | 变量 | 说明 | 默认 / 示例 |
  295. | ----------------------- | -------------------------------------- | --------------------------------- |
  296. | `MC_SKILL_JAVA_SCAN_MAX_FILES` | `validate_project` 等 Java 源码扫描的文件上限 | `300` |
  297. | `MC_SKILL_JAVA_TIMEOUT_MS` | remap / 反编译的 Java 子进程超时毫秒数。非数字或 ≤0 一律忽略并下沉(拼错不会变成 0ms 立刻杀进程);`java -version` 探针固定 15s,不受影响 | `900000`(15 分钟) |
  298. | `MC_SKILL_SCRIPT_TIMEOUT_MS` | **CLI 侧**脚本子进程超时毫秒数(不设 = 不设超时,长跑不被误杀) | 未设 |
  299. | `MC_SKILL_MAX_ENTRY_BYTES` | 解压时单条目未压缩大小上限(防 zip 炸弹) | `268435456`(256 MB) |
  300. | `MC_SKILL_MDK_CHECKSUMS` | MDK 校验和 pin 文件路径覆盖 | `mcp-server/data/mdk-checksums.json` |
  301. | `MC_SKILL_BEDROCK_API_PIN` | 基岩 Script API pin 文件路径覆盖 | `mcp-server/data/bedrock-script-api-pin.json` |
  302. | `MC_SKILL_FETCH_BACKEND` | 设 `curl` 时 GitHub 抓取改走系统 `curl.exe`(Node TLS 失败时的逃生口) | 未设(先试 Node,失败回落 curl) |
  303. | `MC_SKILL_GITHUB_API_BASE` | GitHub API 镜像基址(同时被加入抓取 host 白名单) | 未设(`api.github.com`) |
  304. | `MC_SKILL_GITHUB_TIMEOUT_MS` | GitHub 请求超时毫秒数 | 内建回落值 |
  305. | `MC_SKILL_GITHUB_TOKEN` / `GITHUB_TOKEN` | 自更新 / 上游查询的 GitHub token(提速率、免匿名限流) | 未设 |
  306. | `MC_SKILL_UPDATE_REPO` / `MC_SKILL_UPDATE_REMOTE` | 自更新仓库 slug / 强制 git remote 名 | `guguzea/MC-AI-Coding-Assistant-Tool` |
  307. | `MC_SKILL_UPDATE_CACHE_TTL_SEC` | 自更新检查缓存 TTL(秒) | `3600` |
  308. | `MC_SKILL_UPDATE_DOWNLOAD_TIMEOUT_MS` | 自更新下载超时毫秒数 | `600000` |
  309. | `MC_SKILL_UPSTREAM_CACHE` | 设 `0` 整体关掉 `query_upstream_releases` 磁盘缓存 | 未设(按档 TTL) |
  310. | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`(含全小写) | 抓取的代理 | 未设 |
  311. | `APPDATA` | Windows 下缓存根默认基址(`MC_SKILL_CACHE` 未设时) | 系统值 |
  312. | `NODE_OPTIONS` | Node 22.5–22.12 / 23.0–23.3 需含 `--experimental-sqlite` | 未设(22.13+ / 23.4+ 无需) |
  313. | `MCP_TIMEOUT_MS` | **测试/CI 侧**超时毫秒数(`test-mcp.mjs` / `release-smoke.mjs` / 四支 CI 工作流读它;**MCP 服务进程本身不读**) | `60000` |
  314. > 上表已列**用户可配置面**。服务端源码按大小写敏感去重共读 **38** 个环境变量名;差出来的几个是同一开关的大小写别名与进程细节(`HTTP_PROXY` / `http_proxy`、`ComSpec` / `COMSPEC`),不需要单独配置。要拿全量清单,扫 `mcp-server/src/**` 的 `process.env.*` 即可。
  315. ## MCP 工具使用注意
  316. 本地 MCP 服务名:`MC-AI-Coding-Assistant-Tool`(**89** 个工具)。配置时请使用 **绝对路径** + `MC_SKILL_DATA` 指向本仓库 `data/`。要求 **Node.js >= 22.5**(Yarn 映射使用内置 `node:sqlite`;**22.5–22.12 与 23.0–23.3 需在 NODE_OPTIONS 或启动参数加 `--experimental-sqlite`,22.13+ / 23.4+ 无需**)。仓库 / Release **不含** `node_modules`,需自行 `npm ci && npm run build`(建议再跑 `npm run build:yarn-sqlite`)。
  317. **测试**:`cd mcp-server && npm test`(构建 + 全部单测:核心 / 脚本 / 数据审计 / Wave BCD / localize / update / CLI / 反编译 / 深 mixin / MCP 协议)。CI 语义:`.github/workflows/` 四支工作流的 job env 统一设 `MC_SKILL_SKIP_DOWNLOAD=1`,下载类工具在 CI 里诚实失败而非静默拉网络(该变量须在 mcp-server 内跑 `node test-decompile.mjs` 实测绿后方可依赖此语义)。CLI 另有两档独立门:`npm run test:cli:quick`(`mcp-server/scripts/assert-cli-quick.mjs`,快档,已进默认门链)与 `npm run test:cli:full`(`mcp-server/scripts/assert-cli-full.mjs`,全量档(权威名单跑时现取):入口契约探针 + 真实调用 + 逐条豁免原因,**不默认跑**)。
  318. ### 安装后验收与 npm 脚本速查
  319. 装完(或首次 clone)后,跑下面四条确认环境是对的;**全绿再往下走**:
  320. ```bash
  321. (cd mcp-server && npm ci && npm run build) # dist/ 不入库,必须自建
  322. node mcp-server/dist/cli.js --version # 应打印版本号(与 `mcp-server/package.json` 的 `version` 一致)
  323. node mcp-server/dist/cli.js list-tools --names-only # 应回 89 个工具名
  324. node mcp-server/dist/cli.js activate_platform_pack --action=list # 应回本机已建档的平台 / 版本
  325. node mcp-server/dist/cli.js diagnose_data_paths # 各平台应为 found;empty / not_found = MC_SKILL_DATA 没指对
  326. ```
  327. MCP 宿主里工具全不可调 ⇒ 多半是 `dist/` 未编译或宿主未重载(装了新 `dist/` 也要**重载 MCP**)。排查清单见下节「工具不可用排查」。
  328. `cd mcp-server` 后的常用脚本(完整 35 条以 `mcp-server/package.json` 为准):
  329. | 脚本 | 用途 | 何时跑 |
  330. |---|---|---|
  331. | `npm run build` | `tsc` 编译到 `dist/` | 改源码后;跑 MCP/CLI 前 |
  332. | `npm ci` | 安装依赖 | 首次 clone(仓库/Release 不含 `node_modules`) |
  333. | `npm test` | 全量门链(构建 + 单测 + 各 `assert-*.mjs` 门) | 提交前 |
  334. | `npm run test:core` | 核心单测(含规则加载 / 兼容注释钉子) | 改了 core / 规则加载 |
  335. | `npm run test:cli` | CLI 契约单测(参数解析 + 信封 + 退出码) | 改了 CLI 入口 / 信封 / 退出码 |
  336. | `npm run test:cli:quick` / `test:cli:full` | CLI 快档(已进默认门链)/ 全量档(不默认跑,权威名单跑时现取) | 改了 CLI |
  337. | `npm run test:scripts` | `mcp-server/scripts/**` 门链 | 改了脚本 / 门(**收口必跑**) |
  338. | `npm run test:audit` | 数据审计单测 | 改了 `data/` 或审计器 |
  339. | `npm run test:semantic` | 语义索引单测 | 重建语义库后 |
  340. | `npm run test:decompile` / `test:deep-mixin` | 反编译 / deep mixin 单测(**无需 JDK 17+、无需联网**:fixture jar/class 在用例内构造,探测类用例只要求「探测结论诚实」) | 改了反编译 / 字节码校验 |
  341. | `npm run test:update` | 自更新单测 | 改了 `src/update/` |
  342. | `npm run build:yarn-sqlite` | 重建 Yarn 映射 SQLite(`--all`) | 首次 / 换档后;用 `convert_mapping` 前 |
  343. | `npm run fetch:embedding-model` | 下载本地嵌入模型 | 首次建语义索引前 |
  344. | `npm run build:semantic-index` | 重建语义索引(`npm run … -- --all`) | 要离线 / 语义检索时 |
  345. | `npm run build:vanilla-registries` | 重建 Vanilla Registry 数据(`-- --version=<v>`) | 改了 `query_registry` 数据 |
  346. | `npm run audit:data` | 全平台数据一致性审计(任何 ERROR = 不宜发布) | 发布数据包前 |
  347. | `npm run audit:data:forge` / `:fabric` / `:neoforge` / `:fail-on-error` | 单平台 / 全平台失败即错 | 只改了一个平台时 |
  348. | `npm run community:index` | 重建社区 L0 索引(`--write`) | 增删 `community_knowledge/` 条目后 |
  349. | `npm run smoke:release` | 发布冒烟 | 打包前 |
  350. > 其余脚本(`test:w3` / `assert:no-yarn-slurp` / `build:yarn-named` / `repair:quilt-indexes` / `audit:quilt-indexes` / `fetch:quilt-docs` / `fetch:bedrock-docs` / `fetch:vanilla-registries` 等)按需直查 `mcp-server/package.json`。
  351. ### 两个一等公民入口:MCP 与 CLI
  352. 同一条 core、两个适配器(**互不分叉**):MCP(stdio,给 AI 宿主)与 CLI(终端 / 脚本,给人/AI)。前提与 MCP 相同:Node ≥ 22.5 + `cd mcp-server && npm ci && npm run build`(CLI 跑 `dist/`)。
  353. #### 入口一:工具线(= MCP 工具,全量可调)
  354. ```bash
  355. node mcp-server/dist/cli.js --version
  356. node mcp-server/dist/cli.js list-tools --names-only # 工具名清单
  357. node mcp-server/dist/cli.js list-tools --tool resolve_lib_skills # 单工具 schema
  358. node mcp-server/dist/cli.js search_docs --platform fabric --version 1.21.1 --query registry
  359. node mcp-server/dist/cli.js resolve_lib_skills --platform fabric --mcVersion 1.21.1
  360. node mcp-server/dist/cli.js check_dependencies --project .
  361. node mcp-server/dist/cli.js crash_analyze --crashReport @./crash-reports/latest.txt
  362. ```
  363. - **短名别名**(共 5 个,其余工具名直调):`query`→`query_api`、`convert`→`convert_mapping`、`update`→`mc_skill_update`、`status`→`get_server_status`、`warmup`→`get_server_status`(自动带 `warmup=true`)。
  364. - **参数约定**:flags-only(`--key value` / `--key=value` / 裸 `--flag`→true);`--file field=path`、`@path` / `@-`(读文件 / stdin)、`--stdin-json`、`--raw [field]`、`--timeout <ms>`、`--quiet`、`--project <dir>`、`--output-format json`。**完整全局 flag 清单(含 `--compact` / `--json` / `-h` / `-V` 的边界)只维护在本文「独立 CLI」节**,这里不复制。**参数名按各工具 schema**(如 `resolve_lib_skills` 用 `--mcVersion`;拿不准先 `… <工具名> --help`)。
  365. - **输出**:恒定 JSON 包装 `{success, tool, result|error}`;**退出码** 0=成功 / 1=工具失败或超时(`errorKind: tool_failure | timeout`)/ 2=用法错误(`usage | validation`)。
  366. - **工程类工具**:`--project <dir>` 映射 `projectPath`;`--fail-on-error` 把 `found:false` / 非空 `errors[]` 升为退出码 1。
  367. #### 入口二:仓库线(维护侧脚本子命令)
  368. ```bash
  369. node mcp-server/bin/mc-skill-scripts.mjs --help # 命令总表
  370. node mcp-server/bin/mc-skill-scripts.mjs lib resolve --platform fabric --version 1.21.1
  371. node mcp-server/bin/mc-skill-scripts.mjs lib resolve --validate # 逐组合解析校验(组合清单以脚本内 VALIDATE_COMBOS 为准;= test-core §S15 同一门)
  372. node mcp-server/bin/mc-skill-scripts.mjs lib summary --only libgui --write
  373. node mcp-server/bin/mc-skill-scripts.mjs lib ownership # G1 库归属门
  374. node mcp-server/bin/mc-skill-scripts.mjs corpus decompile --filter slug=cloth-config,jei
  375. node mcp-server/bin/mc-skill-scripts.mjs corpus merge --input x.jsonl --dry-run
  376. node mcp-server/bin/mc-skill-scripts.mjs cloth project # 注入标记 ↔ versions.json 校验
  377. node mcp-server/bin/mc-skill-scripts.mjs gate list
  378. node mcp-server/bin/mc-skill-scripts.mjs gate run lib-ownership # 跑一道门(退出码透传)
  379. ```
  380. - 九个命令 = `lib resolve|summary|ownership` · `corpus decompile|emit|merge` · `cloth project` · `gate list|run`;
  381. - **薄壳**:转发 `scripts/` 与 `mcp-server/scripts/` 的既有脚本,参数与退出码原样透传;`… <组> <命令> --help` 给命令说明(脚本自带参数的 `--help` 走直跑脚本);
  382. - **边界**:CLI 需在仓库内运行(脚本位于仓库根 `scripts/` 与 `mcp-server/scripts/`);仓库线属**维护侧**作业(批量反编译 / 摘要重建 / G1 门 / 注入回填),MCP 工具面不暴露。
  383. - 冒烟门:`mcp-server/scripts/assert-cli-smoke.mjs`(双入口 `--version`/`--help` + 8 组 `--help` + `gate list` + `lib resolve` 真跑×2)已接 `test-core` §S16。装包后(如 `npm i -g ./mcp-server`)两入口暴露为 bin:mc-skill 与 mc-skill-scripts。
  384. > **库模组文件保持 AI 直接可读**:`knowledge/libs/**` 是"源稿即用"——AI 按 `AGENTS.md`「库模组 Skill」规则**直接读文件**;`resolve_lib_skills`(MCP 与 CLI `lib resolve` 同一 core)只做**解析与真值提示**(返回仓库相对路径 + `versionsJson`),**不代替文件、不缓存正文**。
  385. ### 向量 / 语义搜索(T1)
  386. `search_forge_docs` / `search_fabric_docs` / `search_neoforge_docs` / `search_docs` **默认就是混合检索**,不是「只搜 L0 标题」。实现:L0 关键词排行 ∪(FTS5 全文 + MiniLM 向量余弦)再做 **RRF 合并**;命中可带 `matches[]`(chunks 表 top-K:`sectionHeading` / `snippet` / `score`)。返回里 `semantic: true` 表示该次检索用上了语义库。
  387. **三档降级**(缺什么就退一档,不报错、不造数据、运行时不远程拉模型 `allowRemoteModels=false`):
  388. | 档 | 条件 | 行为 |
  389. |----|------|------|
  390. | `hybrid` | 有 `semantic/db.sqlite` 且 embeddings 非空,且 `data/_models/Xenova/all-MiniLM-L6-v2` 就绪 | L0 + 向量 + FTS5,RRF 融合 |
  391. | `fts5-only` | 有语义库但嵌入模型缺失,或 embeddings 表为空 | 全文关键词(FTS5),不再算向量 |
  392. | `l0-only` | 该版本/数据源没有语义库(`semanticSearch` 返回 `null`) | 只匹配 L0 索引字段(`label` / `id` / `url` / `tags`);结果 `semantic: false`,并带 warning |
  393. 全局 `get_server_status.semanticIndex.modeHint` 是**本机总体**档位(有任一 hybrid 树且模型就绪 → `hybrid`)。**单次查询**仍可能是 L0:例如 Forge 1.7.10 没有教程语义库。看该次 JSON 的 `semantic` 与 `warning`,不要只看 modeHint。
  394. 构建期缺模型:警告并降级 FTS5-only(不 exit 1)。`diagnose_data_paths.semantic` 报告各文档树旁 db 是否存在。
  395. **数据与模型位置**:语义库在 `data/{platform}_{ver}/{source}/{ver}/semantic/db.sqlite`(跳过 `forge_javadoc`,该树不建语义库;`db.sqlite.tmp-*` / `-journal` 为构建残渣),清单以 `data/semantic-index-manifest.json` 为准;嵌入模型在 `data/_models/Xenova/all-MiniLM-L6-v2`(transformers.js,**唯一允许远程拉模型的入口**)。构建:`npm run fetch:embedding-model`;`npm run build:semantic-index -- --all`(可 `--platform` / `--version` / `--source` / `--no-embed` / `--force`;可中断续跑)。
  396. #### Agent 怎么调用(两条入口、两步走、一个字段)
  397. **入口 A:MCP 工具**(AI IDE 已挂 `MC-AI-Coding-Assistant-Tool` 时,这是 Agent 的正规调用方式)。按平台选工具,参数只有 `version` + `query`,语义层**自动**参与、没有任何开关:
  398. - Forge → `search_forge_docs { version: "1.14.4", query: "entity goal" }`
  399. - Fabric → `search_fabric_docs { version: "1.21.4", query: "custom enchantment effect" }`(先 `list_fabric_versions` 确认入库档名)
  400. - NeoForge → `search_neoforge_docs { version: "1.20.1", query: "..." }`(1.20.1 回退 Forge 语料,属预期)
  401. - 通用(quilt / liteloader / rift / modloader 等)→ `search_docs { platform: "...", version: "...", query: "..." }`
  402. **入口 B:独立 CLI**(无 MCP 客户端,或想在 shell 里立刻验证——改完源码没重载宿主时也用它):
  403. ```bash
  404. node mcp-server/dist/cli.js search_forge_docs --version=1.14.4 --query="entity goal selector"
  405. ```
  406. (`MC_SKILL_DATA` 指向 `data/`;工具输出恒为 JSON,`--json` 不改变工具输出。)
  407. **两步走**:`search_*_docs` 拿结果里的 **`id`**(不是网站 URL)→ `get_*_doc_full` / `get_*_doc_summary` 读正文。一次最多 2 页,防止上下文溢出。
  408. **响应契约**:`{ ok, total, totalPool, truncated, semantic, results: [{ id, score, … }], matches? }`。**`total` 在文档检索面 = 本次返回条数(= `results.length`,随你传的 `limit` 变),不是语料命中总数**;判断「是否已取尽」看另外两个**无条件**在载荷里的键:`totalPool` = 该面进窗口前可用的候选条数,`truncated` = (`total < totalPool`)(八个发射点全覆盖;`limitWindow.candidates` 在多数面仍是窗口不是池,bedrock 面的窗口块在 `demotion` 下)。**残余口径**:`totalPool` 只到「本面可得」这一层,不等于语料全量(fusion 输入与 L0 检索各有上限)。`query_loader_api`/`query_upstream_releases`/`search_mod_code` 三面的 `total` 才是全池 ⇒ 两族判式符号相反,别照抄。Agent 必须读 `semantic` 字段:
  409. - `semantic: true` = 该次检索走语义库(FTS5 BM25 + MiniLM 向量余弦、RRF 融合),命中可视为按相关性排序的 coverage 证据;
  410. - `semantic: false` = 降级 L0 关键词(该树没建语义库 / 嵌入模型缺失 / `semanticSearch` 返回 null),带 warning——此时命中**不穷尽**,`found:false` 什么都不能证明;
  411. - 命中可带 `matches[]`(`sectionHeading` / `snippet` / `score`),snippet 来自 chunks 表**真实正文**,可直接引用。
  412. **Agent 侧规矩**(根 `AGENTS.md`「不确定时」条款):查 API / 文档 / 机制**先语义搜索**;`query_api` / `query_loader_api` 是兼容工具(见下节),只作兜底。
  413. #### query_\* 兼容工具与索引覆盖边界
  414. `query_api` / `query_loader_api` 被标记为**兼容工具**(类名/签名索引类,覆盖按版本而异且有限)。每次调用的响应都显式提醒,不再静默:
  415. 1. **query_api 每次响应**:`notes` 末尾追加「query_api 是兼容工具……文档与语义面请优先 search_forge_docs / search_docs 语义搜索」。
  416. 2. **query_api 查 1.14.4 / 1.15.2**:这两档有**真索引**(MCPConfig `joined.tsrg` → `tsrg-extractor.js`:1.14.4 = 4,976 类 / 32,570 方法,1.15.2 = 5,137 类 / 34,159 方法)。类名写**该版 SRG 路径**(如 `net.minecraft.item.Item`),成员名是 `func_/field_`,无参数名/javadoc。只有 `extracted/api-index.json` 缺件或 0 类时才回落到「索引为空」的降级 `warning`——那时 `found:false` 不代表游戏里没有该类,改用 `search_forge_docs` **语义搜索**(这两档 docs 语料与语义库完整,查询返回 `semantic: true`)。
  417. 3. **query_loader_api 每次响应**:`notes` 追加兼容注释(覆盖以已 ingest 的档为界)。
  418. 4. **第二档出处 `nameIndex`**:`query_api` 在 api-index 未命中、或该版本没有 Parchment 索引(如 1.21.x Fabric / 无 extracted 索引的 NeoForge 档)时,会再查一次在盘映射索引 `data/<平台>_<版本>/mappings/yarn-mappings.sqlite`,把结果挂在响应里的 `nameIndex`:`exists` / `matchKind`(exact|simple-unique|ambiguous|contains|none)/ `named` / `memberCounts` / `memberSample` / **`mappingEra` + `dbKind`**。边界有三条,缺一不可:`found` 恒仍为 `false`(存在性证据不等于签名命中)、`mappingEra` 必须读(`yarn-tiny` 的 `named` 是 Yarn 名,`forge-srg`/`tsrg`/`mcp-csv` 的 `named` 是 MCP `func_/field_` 名,`mcp-config-srg`(Forge 1.16.5–1.20.4 六档)的是 SRG 类名 + `m_N_/f_N_` 成员名)、该档没有库或表为空时**整键缺席**(不凭空造一档)。**选库按加载器**:本工具的 api-index 只读 `data/forge_<ver>/extracted` ⇒ `nameIndex` 也按 Forge 线取库,两棵树都有库的 1.16.5–1.20.4 不再由 fabric 的 yarn-tiny 代答(`RenderCall` 在 Yarn 与本档分属 `blaze3d/systems/` 与 `blaze3d/pipeline/`,包名不能跨映射层推定);forge 无库时照旧回落 fabric。要签名仍走 `search_*_docs` 或按需 `get_minecraft_source`。
  419. 钉子:`test-core.mjs`(1.20.1 兼容注释 / 1.14.4 与 1.15.2 真索引命中(`Item` 带方法清单、且不得报空索引 warning) / 1.12.2 数据健康 / nameIndex 三腿:接线(1.21.1 `StatusEffect` 给得出 nameIndex 且 `found:false`)、证伪(乱造的名字必须 `exists:false`)、披露(三句 note 缺一即红)+ 无库档 26.1.2 与命中路径 1.20.1 都不得出现 nameIndex)与 `test-loader-api.mjs`(兼容注释)。
  420. ### 文档查询(Forge / Fabric / NeoForge)
  421. 1. **页面 ID 必须用搜索结果里的** `id`,不要用网站 URL 路径。
  422. - 正确:`get_fabric_doc_full({ id: "1.20.4/develop_items_first-item", version: "1.20.4" })`
  423. - 错误:`id: "items/first-item"`
  424. 2. **推荐流程**:`search_*_docs` →(可选)`get_*_doc_summary` → `get_*_doc_full`。
  425. 3. 搜索默认 **hybrid**(见上一节)。只有降级到 `l0-only` 时才「只匹配索引字段」。
  426. 4. 前缀查询示例:`class:Item`、`event:lifecycle`。
  427. 5. NeoForge `1.20.1` 文档查询会回退到 Forge 1.20.1 视图(兼容层),属预期。
  428. 6. 若某平台数据包未下载,对应 list/search 会返回 `PLATFORM_DATA_MISSING`(可用 `diagnose_data_paths` 确认)。
  429. 7. **先 `list_*_versions` / `list_doc_versions`**,确认本机有该版再搜。`search_forge_docs` 与 `search_docs({ platform: "forge" })` 走同一套 Forge 索引。
  430. 8. **按版本选工具**(不要用 `query_api` 顶官方文档):
  431. | 目标 | 文档搜索 | Vanilla / 映射 | 平台 API |
  432. |------|----------|----------------|----------|
  433. | Forge **1.12.2** | `search_forge_docs` / `search_docs`(`version=1.12.2`)。有 `data/forge_1.12.2/forge-docs` 教程(如 `1.12.2/blocks_blocks`) | **不要**把 `query_api` 当 javadoc:该版只给 SRG 类名与 `func_/field_` 成员名(无参数名/javadoc)。映射用 `convert_mapping`(MCP SRG) | `query_loader_api` / `search_loader_api`(`1.12.2-forge` 已索引,约 1100 类) |
  434. | Forge **1.7.10–1.11.2** | 无教程规则树;落到 `forge_javadoc` / `search_docs`,`semantic: false` | 同上(SRG 类名 + `func_/field_` 成员名,无 javadoc);不要用它核签名 | 无 loader 摘要(`search_loader_api mode=list` 的 `noIngest`) |
  435. | Forge **1.13.2** | `search_forge_docs` / javadoc | SRG 类名与成员名可列(无 Parchment javadoc) | `1.13.2-forge` 已索引 |
  436. | Forge **1.14.4 / 1.15.2** | `search_forge_docs`(**语义库完整**,查询返回 `semantic: true`) | `query_api` 有真索引(MCPConfig `joined.tsrg` 派生:4,976 / 5,137 类;类名写该版 SRG 路径,成员名为 `func_/field_`,无参数名/javadoc) | `*-forge` 已索引 |
  437. | Forge **1.16.5–1.20.4** | `search_forge_docs` | Vanilla 可用 `query_api`(真方法签名) | `query_loader_api` 或文档 |
  438. | Fabric | 先 `list_fabric_versions`;**禁止**把邻版 wiki 当本版。26.1.2 / 26.2 仅 `fabric-docs`、无 wiki | 26.1+ 无 `query_api` 索引 | `search_loader_api mode=list`:`1.14.4` / `1.16.5` / `1.17.1` / `1.18.2` / `1.19.4` / `1.20.1` / `1.20.4` / `1.21.1` / `1.21.3` / `1.21.11` / `26.1.2` / `26.2` 的 fabric-api **已索引**(不要再当成 maven 404;**12 档 = 15 个 `fabric/*` 规则树 − 薄档 `1.21.4` / `1.21.8` / `1.21.10`**) |
  439. | Quilt | `search_docs({platform:"quilt"})`;问 QSL 禁止把 Fabric Registry 当命中 | 同左版本的 Vanilla 边界 | QSL 摘要见 `mode=list`(如 `1.19.4-qsl` / `1.21.1-qsl`) |
  440. | NeoForge | 先 `list_neoforge_versions`。`1.20.1` 回退 Forge 文档(兼容层) | 26.1+ 无 `query_api` | `*-neoforge` 多档已索引 |
  441. | LiteLoader / Rift / ModLoader | `search_docs`。LiteLoader/Rift 有官方 wiki **hybrid** 语义库;ModLoader 仍为 **L0-only** | `convert_mapping` / 反编译 | 仓库内核实表仍是 API 准绳;未 ingest → `PLATFORM_SKIPPED`。用户自备 jar 走 `ingest_loader_api`(默认 dryRun) |
  442. | 基岩 | `search_bedrock_docs`(带 `docsStatus`) | 无 Java `query_api` | `validate_addon_manifest` / `validate_bp_json`,不是 `validate_project` |
  443. | **Paper / Paper API / Spigot(服务端)** | `search_docs({platform:"paper"})` 取**教程正文**(`data/paper_stable/paper-docs/`,67 页);`{platform:"paper-api"}` 取 **Paper 的 API 签名面**(当前档 `paper-api_stable` **2116 类**,含 `io.papermc.paper.*` 这类 Paper 专有类;历史档 ×5);`{platform:"spigot"}` 取 **Bukkit/Spigot 签名面**(当前档 `spigot_stable` **1396 类**;历史档 ×8)。版本键:三个 platform **都有** 当前档伪版本 `stable`,`paper-api` 另有 5 个真 MC 版本、`spigot` 另有 8 个 | 无 Java `query_api` —— 插件打的是 Bukkit **抽象层**,正常插件代码不碰 `net.minecraft.*`;逐档 javap 改写表在插件侧**零适用** | 真实上游版本串在各页 `asOfVersion`(Paper `26.3.build.178-stable` / Spigot `26.3-R0.1-SNAPSHOT`)。**所有签名档都已建语义库**(各档旁 `semantic/db.sqlite`,`semantic: true`);但签名页正文只有签名行,**正文词项 0 命中 ≠ 该 API 不存在** —— 查类/成员用 `search_docs` 的 L0 索引字段更稳 |
  444. 9. 查询用类名或短词(`Block`、`class:RegistryEvent`)。失败先换短查询或改走 `search_docs`,不要把崩溃/空结果当成「该版没有文档」。
  445. 10. **改完 `mcp-server` 源码后**:`npm run build`,然后在宿主里**重载 MCP**。Cursor 里正在跑的进程不会自动换成新 `dist/`;用 `node mcp-server/dist/cli.js` 才能立刻验证。
  446. ### 工具陷阱
  447. 下表现象都出自索引 / 查找写法或文档过时,不代表游戏里没有该类:
  448. | 现象 | 实际 | Agent 应做 |
  449. |------|------|------------|
  450. | `search_*_docs` 查 `constructor` 抛 `abbr is not iterable` | `ABBREV_EXPAND[query]` 命中 `Object.prototype.constructor` | 已改为 `Object.hasOwn` / `ownGet`。若 MCP 仍崩 → 重载服务 |
  451. | `get_version_info({version:"constructor"})` 返回 `undefined。注册流程:DeferredRegister…` | `VERSION_DB["constructor"]` 是 Function | 未知 version 必须 `forgeVersion=unknown`,禁止套 1.20 注册流程 |
  452. | `get_migration_guide({route:"constructor"})` `found:true` | 自由字符串查 `MIGRATION_GUIDES[key]`,命中 Function | 已 `ownGet`,必须 `found:false` |
  453. | `get_workflow_template({name:"constructor"})` | MCP schema 是工作流名 **enum**(Zod 直接拒);函数层仍要 `ownGet` | 不要把校验失败理解成「没有工作流系统」 |
  454. | `query_api` 1.12.2 `Block` `found:true` | 3344 个类名,其中 3256 类含成员(`func_/field_` 混淆名,无参数名/javadoc) | 看 `warning` / `notes`;改 `search_forge_docs` / `query_loader_api` |
  455. | `generate_datagen` platform=forge version=1.12.2 吐出 Java | 1.12.2 **无 DataGen**;旧模板还曾发出 1.21 的 `ResourceLocation.fromNamespaceAndPath` | Forge **1.20.1**(`Consumer<FinishedRecipe>`)与 **1.20.4**(仅 recipe,`buildRecipes(RecipeOutput)`);NeoForge 1.20.1 改口 `search_neoforge_docs`、1.20.4/1.20.6 仅 recipe、1.21.x 与 26.1;**Fabric** 1.21.1/**1.21.3**/1.21.4/1.21.8/1.21.10/1.21.11 与 26.1(**无 1.21.5**);**Quilt 无** generate_datagen(改口 `search_docs platform=quilt` + Fabric overlay 手写);其它 version 返回 error |
  456. | `get_version_info` 1.12.2 action=register 仍教 DeferredRegister | gotchas 写「不支持」,recommendation 被强行追加 1.20 流程 | 1.12.2 注册是 `RegistryEvent.Register<T>` |
  457. | `search_loader_api` 对 Fabric 1.14.4 等返回空 | 文档曾写 maven 404 / `LOADER_API_NOT_INDEXED` | 以 `mode=list` 为准;`skipped-ingest.json` 的 `mavenNotIndexed` 现为空数组 |
  458. | 文档 `semantic: false` 或 warning 含 `stale` | 故意 L0-only(**仅 ModLoader** 三档),或 sqlite 落后于 processed/ | 看该次 JSON,不要只看 `get_server_status.semanticIndex.modeHint` |
  459. 同类查找一律走 `ownGet`(`mcp-server/src/utils/own-record.ts`),不要写 `record[userString]`。
  460. ### 规则包加载(`activate_platform_pack`)
  461. 知识库里的 `forge/<ver>/.cursor` **不会**被用户模组工程的 IDE 扫到。编码期用 MCP 把该档送进**当前对话**,不要把规则拷进 `MC_skill` 仓库根。
  462. | `action` | 作用 |
  463. |----------|------|
  464. | `list` | 已建档平台 / 版本 |
  465. | `session` | **不写盘**、不依赖项目根。返回该档 `AGENTS.md`、规则正文、Skill **索引**(`name` / `description` / `relPosix` / `absPath`)。默认只注入规则 **00 / 01 / 09**;`topics` 与 `task` **追加**到底座(并集,永不替换);`skillNames` 与 `task` 建议名去重后注入 `skillBodies`(总条数上限 8)。`topics` 永不注入 Skill 正文。库 Skill 不进 `nextReads`,只有显式 `skillNames` 才注入库正文。`includeAllRules=true` 才灌 00–10 规则全文。ok=true 且带「仅底座」warning = 包可用但规则未按任务扩展(`rulesMode=base`,含 `next` 对象)。包存在但缺 00/01/09 文件 → `ok:false` + `PACK_INCOMPLETE`(不是 `PACK_NOT_FOUND`)。库 Skill 仍读 `knowledge/libs/`。 |
  466. | `write` | 写入**用户模组工程**的 IDE 目录。`hosts` 必填(`cursor` / `claude` / … / `dsh` / `all`)。默认 `dryRun`。不要再用 `includeSkills`,改用 `writeSkillStubs`(二者都未传时默认 **true**,写入 stub,提示去读知识库路径,不是 Skill 全文)。`includeSkillBodies` 才写全文。目标不能是本知识库(**整棵仓库树**均拒绝,含版本子目录)。**破坏性变更**:设置 `MC_SKILL_PROJECT_ROOT` 时它是**硬边界**——`projectPath` 必须落在其内,否则拒绝(`PATH_OUTSIDE_ALLOWLIST`,响应带 `breakingChange: true` 与 `allowRoot`);此前 `projectPath` 可覆盖 env。迁移:把 env 指向包含目标工程的目录,或改用其内的 projectPath。 |
  467. | `deactivate` | 按清单撤写 |
  468. **不能**开关 Cursor/Claude 等 Skill 扫描器。重载 MCP 不会让设置页出现条目。
  469. ### 工具边界
  470. 文档向量搜索 **补不了** Vanilla 方法签名。缺索引时保持 `found:false` / 空结果 + 说明,
  471. | 情况 | 表现 | Agent 应改用 |
  472. |------|------|----------------|
  473. | MC **26.1+** 的 `query_api` / `get_method_params` | 该类 extracted 为 **0 个类**(无 Parchment api-index) | `search_neoforge_docs`(须传 version,先 `list_neoforge_versions`)/ `search_fabric_docs`(先 `list_fabric_versions`,如 26.1.2);或 `get_minecraft_source` / 反编译。映射层返回 `UNOBFUSCATED_NO_YARN` |
  474. | Forge **1.14.4 / 1.15.2** `api-index.json` | MCPConfig `joined.tsrg` 派生(4,976 / 5,137 类),**不是**占位 `{}`。类名与成员名都是 SRG(`net/minecraft/item/Item` + `func_77658_a`),无参数名/javadoc(Parchment 约从 1.16.5 才有) | 要参数名/javadoc 换 `version=1.16.5+`;在本档就按该版 SRG 名查,不要写 1.17+ 的 `world/item/Item` |
  475. | Fabric **26.1.2** | 仅 `fabric-docs`(页数少),**无** `fabric-wiki` | `source` 保持默认 `fabric-docs`;不要把 1.21.x wiki 当 26.1.2 |
  476. | Forge **1.12.2** | `list_forge_versions` **含** 1.12.2;有 `forge-docs` 教程树。`query_api` 给 SRG 类名与 `func_/field_` 成员名(非可读签名) | `search_forge_docs` / `search_docs({platform:"forge", version:"1.12.2"})` → `get_forge_doc_full`。Forge 类用 `query_loader_api`。**禁止**把 `func_/field_` 名当完整签名 |
  477. | Forge **1.7.10–1.11.2** | `1.7.10` 有 javadoc 核实表与短 00/01/09;其余档搜索落到 Javadoc 类名,`semantic: false` | 当类名索引用;`search_forge_docs version=1.7.10` / `search_docs({platform:"forge"})`。不要用 1.12.2 / 1.20.1 规则顶上,也不要假 pin 1.7.10 MDK |
  478. | `diagnose_gradle` / `validate_project` | **ForgeGradle + Loom + Neo/MDG**;Rift / BaseMod / 基岩仍早退。`validate_project` 对 Fabric/Quilt/NeoForge 做真检查(`passed`/`failed`);LiteLoader/Rift/ModLoader/基岩 `skipped`。基岩 → `validate_addon_manifest` | Java 扫描上限默认 300,可用 `MC_SKILL_JAVA_SCAN_MAX_FILES` 提高(超限 warning 含「检查可能不完整」) |
  479. | `get_server_status.updateHint` 显示有更新 | 可能是检查缓存过期 | 以 `mc_skill_update action=check` 为准;git describe 已超前 Release 则不必 apply |
  480. Agent **不得**把「工具返回空 / found:false / warning」解释成「游戏或文档里不存在」,也不得用错平台的工具硬查。对照:
  481. | 误判 | 实际边界 |
  482. |------|----------|
  483. | `query_api` 能查 `DeferredRegister` / Fabric API | **不能**。只含 Vanilla Parchment extracted(约 1.16.5–1.20.4)。平台 API → `query_loader_api`(必填 platform+minecraftVersion)或对应 `search_*_docs` |
  484. | `query_api` 能查 Forge **1.12.2** `Block` 构造 | **不能**当 javadoc。该版无 Parchment 方法条目,只有 SRG 类名与 `func_/field_` 成员名。改 `search_forge_docs` / `query_loader_api` / `convert_mapping` |
  485. | `search_forge_docs` 报错或空 = 该版无文档 | 先 `list_forge_versions`。1.12.2 **有**教程树。查询词 `constructor` 曾因原型键崩溃,已修;若仍崩则重载 MCP。失败换短查询或 `search_docs({platform:"forge"})` |
  486. | `query_api` `found:false` = 类不存在 | 索引没有该类、简名歧义(`Handler` 不会命中 `MouseHandler`),或 `action.code=DATA_UNAVAILABLE`(该版无 extracted / Worker 未就绪)。26.1+ 收录 **0** 类;1.7.10–1.15.2 有 SRG 类名索引(成员名为 `func_/field_` 混淆名;1.14.4/1.15.2 的类名同样是该版 SRG 路径)。改文档搜索或 `get_minecraft_source` |
  487. | `get_method_params` 覆盖所有 MC 版本 | 与 `query_api` 同一数据源,边界相同 |
  488. | `get_version_info` 适用于 Fabric/NeoForge | **仅 Forge** |
  489. | `diagnose_gradle` 能修 Loom / NeoGradle | **覆盖** ForgeGradle + Loom + NeoGradle/MDG;Rift / BaseMod / 基岩仍早退。liteloader 插件走轻量模式 |
  490. | `validate_project` 能校验 `fabric.mod.json` | Fabric/Quilt/NeoForge **真检查**;LiteLoader/Rift/ModLoader/基岩仍 `skipped`。基岩用 `validate_addon_manifest` |
  491. | `query_registry` 能查模组注册名 | 只查原版 `minecraft:` 资源 ID |
  492. | 文档搜索为空 = 数据包坏了 | 可能是 L0 降级、标签不对、或该版无 wiki。看 `semantic` / `warning` |
  493. | 用网站 URL 当 `get_*_doc_full` 的 `id` | **必须**用搜索结果里的 `id` |
  494. | `search_community_docs` 可当官方 API | **不能**。`links` 条目不抓网页正文 |
  495. | `port_project` 会改用户工程 | 默认 **dryRun**;真写需 `confirmed` + `MC_SKILL_ALLOW_WRITE` + 路径在 `MC_SKILL_PROJECT_ROOT` 内 |
  496. | 工作流 / MCP 不跑 Gradle、不拷 jar、不上传 = 漏做无人值守 | **人在环设计**。创意、性能、调试由人决定;兼容取舍 / API 选择可代劳但须按「解释模板」说明;高风险操作须确认后再执行 |
  497. | `analyze_porting_path` 对任意文件夹都有移植路径 | 非模组目录 → `NOT_A_MOD_PROJECT`;LiteLoader / Rift / ModLoader / 基岩 → `UNSUPPORTED_PORT` |
  498. | `generate_*` / `generate_datagen` 会写文件 | **默认只返回文本骨架 + `suggestedPath`**。可选写盘须 `write=true` + `confirmed=true` + `MC_SKILL_ALLOW_WRITE=1` + 绝对 `MC_SKILL_PROJECT_ROOT`,路径相对工程根且不含 `..`;缺任一条件只吐文本,不会静默落盘。**三态语义**:默认不传 `write` = **dry-run**(只吐文本,恒 `ok:true`、`resultKind:"ok"`,`ok` 不对写盘作任何承诺);版本/平台不支持等**生成失败** ⇒ `ok:false` + `resultKind:"generation_failed"`(原因在 `errors[]`);骨架已出但**写入未完成**(缺 `confirmed` 或写盘被沙箱拒)⇒ `ok:false` + `resultKind:"write_blocked"`(CLI `success:false` + exit 1,写盘未发生,文本预览仍在 `result`,细粒度原因在 `writeError.code`:`CONFIRMATION_REQUIRED` / `PROJECT_ROOT_REQUIRED` / `PATH_OUTSIDE_ALLOWLIST` / `NOTHING_TO_WRITE` / `WRITE_FAILED`)。`platform`/`loader` 与(datagen/config/capability/renderer 的)`version` 必填,禁止默认 forge。datagen:**Forge 1.20.1 与 1.20.4**(1.20.4 仅 recipe)、NeoForge 1.20.4/1.20.6(仅 recipe)/1.21.x/26.1、**Fabric** 1.21.1/**1.21.3**/1.21.4/1.21.8/1.21.10/1.21.11 与 26.1(无 1.21.5);Quilt 无 generate_datagen(改口 `search_docs platform=quilt`);其它 Forge 版本(含 1.12.2)error。`generate_capability`:forge=Capability;neoforge 1.20.1 同 Capability、1.20.4+ Attachment;fabric/quilt 改口 CCA |
  499. | `localize_mod` 会自动译成中文 | **无机器翻译**,只标 `needsTranslation` |
  500. | `check_dependencies` = 完整 Gradle 解析 | 启发式 + library-catalog,会漏未收录库 |
  501. | `mixin_analyze deep:true` 会下载 MC jar | **不会**。未缓存 → `CACHE_MISS`,先 `get_minecraft_source` |
  502. | `search_mod_code` 能搜任意 jar | 须先 `decompile_mod_jar`(或已有反编译目录):jar 存在但没反编译 ⇒ `NOT_DECOMPILED`,jar 本身不存在 ⇒ `NOT_FOUND`;两者都不是「搜不到」 |
  503. | `analyze_mod_jar` 会给出方法体 | 只解析元数据(toml/json/mixin 列表),不反编译 |
  504. | `convert_mapping` / `lookup_obfuscated` 用于 26.1 | 返回 `UNOBFUSCATED_NO_YARN`(已去混淆) |
  505. | `validate_datapack_json` 覆盖所有 pack_format | 精简 schema,偏 **1.20.1 / 1.21.1** |
  506. | `get_*_doc_full` 一次拉很多页 | **最多 2 页**,避免上下文溢出 |
  507. | `updateHint.available` = 必须更新 | 缓存可能过期;先 `mc_skill_update check` |
  508. | 缺 26.2 / 26.1.2 wiki 就复制邻版 | **禁止克隆冒充** |
  509. | `DOC_NOT_FOUND` / 规则树空壳就抄邻版 API | **禁止**。保持未核实 stub,不是漏写 |
  510. 写模组时的选用顺序:平台规则(`AGENTS.md`)→ `search_*_docs`(平台 API)→ `query_api`(仅有索引的 Vanilla)→ 反编译(确实要源码)。不要反过来用 `query_api` 猜 Forge 事件名。
  511. ### 工具与网络边界
  512. 下列两条**核不到上游本身**(能核的只有通道,见下表)。这里登记的是「不许推出什么」,不是「已核实为否」。
  513. | 边界 | 已核实到的程度 | 禁止的推断 |
  514. |------|----------------|------------|
  515. | 外网可达性只能核到**此机器通道**层面,不是「通 / 不通」一个布尔 | `download_official_mdk` 的 pin commit、`mc_skill_update` 的 Release、以及规则/AGENTS 里钉的 example-mod commit 短哈希,都只能在可达网络下复验。实测:**Node `fetch`** 对 `raw.githubusercontent.com` 与 `services.gradle.org` 一律 `TLS_VERIFY_FAILED`(同口径见 `$MC_SKILL_CACHE/loader-api-summaries/fetch-qsl-last.json` 台账);**同一 URL** 换 `curl.exe --ssl-no-revoke` GET = `200`(719 B / 0.1s),`services.gradle.org/distributions/…` = `307`;`api.github.com` 的 `git/trees?recursive=1` 单次 12s 超时(未复测) | **本机拉不到 ≠ 上游不存在 / 校验和不对 / 那个 commit 是假的**;也**不得**把 TLS 类失败记成 `NOT_FOUND` 或「缺档」。相关条目保持「未核实」标注,换网络或让用户在本机复验,不要改成另一套自猜的值 |
  516. | 基岩 `description.identifier` 等命名空间 ID 的长度上限与字符集 | Microsoft Learn 只规定要带命名空间,**未**给出长度上限与允许字符集;社区只给「小写、无空格/特殊字符」「路径长度受主机限制」这类**建议** | **不要把建议当硬限制**,也不要因 Learn 没写就断言「无限制」。`validate_addon_manifest` / `validate_bp_json` 不据长度/字符集报错;生成 ID 时按建议取保守形式并说明这是约定不是官方约束 |
  517. fetch 通道矩阵(写维护脚本时按这张表选腿;任一腿失败推不出「这台机器没网」):
  518. | 腿 | 本机实测 | 用法 |
  519. |----|----------|------|
  520. | Node `fetch`(github / gradle / maven 域) | 一律 `TLS_VERIFY_FAILED` | 不得当主腿;失败必须归 TLS 类,与 404 / 限流分开 |
  521. | `curl.exe --ssl-no-revoke` GET | `200` / `307`(本机唯一稳定可用腿) | win32 主腿。**冷连接首试可能超时**(实测一次 15s 零字节),必须带退避重试 |
  522. | `curl.exe --head` | 同一 URL 跨轮实测 `502` 与 `200` 都出现过 | **禁止**用 HEAD 判可达性,探测一律 GET |
  523. | `api.github.com` | 实测 `git/trees?recursive=1` 单次超时 | 需要它建表时先单独复验;不能假设与 `raw` 行为一致 |
  524. `scripts/_lib/fetch-with-ua.mjs` 把这张表落成代码:`downloadWithFallback({ preferCurl: process.platform === "win32" })`,curl 腿恒带 `--ssl-no-revoke` + UA,fetch 腿恒带 `AbortSignal.timeout()` + UA,失败类别见 `FETCH_FAILURE`(`TLS_VERIFY_FAILED` / `TLS_REVOCATION_CHECK_FAILED` / `TLS_HANDSHAKE_FAILED` / `RATE_LIMITED` / `NOT_FOUND` 互不混用)。
  525. ### 映射转换(`convert_mapping` + Yarn)
  526. 1. 走预建 `yarn-mappings.sqlite`**(现批次 schema v4,含 fields;v2/v3 旧库仍可读)惰性点查**,运行时**禁止**全量加载 `yarn-mappings.json`。
  527. 2. **支持矩阵(摘要)**:
  528. | 版本区间 | 数据源 / era | 类互转 | 方法互转 | 字段互转 | 备注 |
  529. | -------------------- | --------------------- | --- | ---------------------------------- | -------------------- | ------------------------------ |
  530. | 1.16+(有 Fabric tiny) | `yarn-tiny` | ✅ | ✅ 需 `ownerClass`;重载建议 `descriptor` | ✅ `memberKind=field` | `to=mojang` = Tiny official 短名 |
  531. | 1.13 Forge | `tsrg` + MCP CSV | ✅ | ✅ 可带 `ownerClass` | ✅ + `fields.csv` | `joined.tsrg` + CSV |
  532. | 1.7–1.12 Forge | `forge-srg` + MCP CSV | ✅ | ✅ 可带 `ownerClass` | ✅ + `fields.csv` | `joined.srg` + CSV |
  533. | 1.14–1.15 | `mcp-csv`(partial) | ❌ | 仅全局 `searge↔named` | 仅全局 `field_*` | **勿传** `ownerClass` |
  534. 1. `mcp↔parchment` 为同名层(identity);参数名用 `get_method_params`。
  535. 2. **obfuscated / intermediary 层**(T5):`obfuscated` = Tiny official 混淆短名(`er`),`intermediary` = `method_6032` 类;`yarn/mcp→obfuscated` 与 `to=mojang` 同值,`obfuscated/intermediary→yarn/mcp` 支持**无 ownerClass 全局反查**(崩溃日志单 token)。`to=mojang` 保持旧行为,notes 提示改用 `to=obfuscated`。**26.1+ 无混淆层**:obfuscated/intermediary 请求返回 `UNOBFUSCATED_NO_YARN`(仅 1.14–1.21.11 可用)。
  536. 3. **字段查询**:传 `memberKind: "field"`(或 `"auto"` 时按名称风格推断),建议带 `ownerClass`;1.14–1.15 仅全局 `field_`*/`searge↔named`。schema 仍为 v2 时返回 `SCHEMA_FIELDS_UNAVAILABLE`(需重建 sqlite)。CLI:`node mcp-server/dist/cli.js convert --kind field ...`。
  537. 4. 失败默认 `found:false`、`converted:null`;过渡参数 `allow_fallback` 可回传原名并设 `fallbackUsed`(禁止假成功)。
  538. 5. 构建:`cd mcp-server && npm run build:yarn-sqlite`(本地 temp 写入后复制,避免盘符 I/O 问题)。
  539. 6. **`from=mojang`(拿 mojmap 可读名来查)有两档出处**:第一档 = 上表的 `official` 列,而那一列对**被混淆的类**存 Tiny 混淆短名,只有本来不混淆的少数类带可读全路径(可读路径占比不足 1%,如 `com/mojang/blaze3d/…`)⇒ 用 `Container`/`Level` 这类可读名点查必然 `found:false`,**这不代表该版本没有这个类**(未命中回执自带这条披露)。第二档 = 派生对照表 `data/_yarn-mojmap-pairs/`(类名级 `obf`/`mojmap`/`yarn` + 两侧 FQCN,**无 intermediary 列**),只在 `from=mojang` 且 `to` 为 `yarn`/`obfuscated` 时参与,命中带 `fallbackUsed:true` 并在 notes 点名是哪张表、该表多少条;`to=intermediary` 直接拒答,不回落第一档。
  540. ### 工作流模板与知识资源(Prompts / Resources + 工具兜底)
  541. Cursor 主路径是 **tools**;协议层仍注册 Prompt/Resource,工具兜底保证同款正文可读:
  542. | 能力 | 工具 | 说明 |
  543. | ---- | -------------------------- | ---------------------------------------------------------------------------------------------------- |
  544. | 工作流 | `get_workflow_template` | 模板名以 `get_workflow_template` 列表为准(含 `mc-new-block` / `mc-new-item` / `mc-new-blockentity` / `mc-mixin` / `mc-worldgen` / `mc-config` / `mc-gametest` / `mc-setup-env` / `mc-publish` 等,与 Prompt 同名);编排型 `mc-grill` / `mc-handoff` / `mc-router` / `mc-review` / `mc-spec` / `mc-retro` / `mc-breakdown` / `mc-wizard` / `mc-research` / `mc-glossary` / `mc-waitwhat` / `mc-prototype` 源稿在仓库根 `common_skill/`(普通文档待遇,不进受管门) |
  545. | 知识列表 | `list_knowledge_resources` | 列出 `mcskill://` URI |
  546. | 知识读取 | `read_knowledge_resource` | 按 URI 读正文 |
  547. 常用 URI:`mcskill://patterns/README`(→ `community_knowledge/patterns/README.md`)、`mcskill://schema/sqlite?version=<精确 MC>`(裸 URI 被拒)、`mcskill://matrix/mixin-support`、`mcskill://version-changes/1.21`、`mcskill://antipatterns/registry`、`mcskill://workflow/<模板名>`、`mcskill://community/<authored-id>`、`mcskill://skill/<编排技能名>`(读 `common_skill/` 源稿正文;实名单 = `list_knowledge_resources` 的 `skill-` 前缀条目,登记由盘派生)。
  548. ### 移植分析(`analyze_porting_path`)
  549. 平台识别综合源码与构建/元数据(`build.gradle`、`mods.toml`、`fabric.mod.json` 等)。空目录 / 无构建也无元数据 → `ok:false` + `NOT_A_MOD_PROJECT`(不是 `platform: unknown`)。
  550. 输出契约:`targetPlatform` **必填**(未指定 → `INVALID_INPUT`,不做静默默认);`routeSteps` 始终是给人读的 `string[]`;机器可读交接是并行的 `nextSteps[]`,每项 `{ text, tool?, args? }`,其中 `tool` + `args` 必须能直接调用(必填参数齐备、无占位值),填不齐就只给 `text`。`port_project` 按 `nextSteps` 续跑。
  551. ### 写操作(`port_project`)
  552. 默认只读。真正写盘需要同时设置 `MC_SKILL_ALLOW_WRITE=1` 与 `MC_SKILL_PROJECT_ROOT=<允许写入的项目根>`,且目标路径必须落在该根目录下。
  553. ## 数据复现与分发
  554. `data/` 中的索引和文本由 `mcp-server/scripts/` 生成。大型 `*.jar` / `*.zip` 默认被 `.gitignore` 排除(`data/**` 有例外保留规则),不要假定 Git 一定含全部二进制。
  555. - 只从脚本声明的官方来源重建数据。
  556. - 运行 `cd mcp-server && npm run audit:data`;任何 `ERROR` 表示数据包不宜发布。
  557. - 完整数据包可通过 GitHub Release 的 `mc-skill-data-full-*.zip` + `SHA256SUMS-*.txt` + `data-manifest.json` 分发。
  558. - 本地原始包丢失时应重新 fetch,不要跨版本复制改名。
  559. ## 目录约定
  560. - 平台按 `平台/版本/` 分目录(如 `forge/1.20.1/`、`fabric/1.20.1/`)
  561. - 规则文件在 `.cursor/rules/`,编号 `00`~`10`
  562. - 每个规则含 **约束** 与 **Decision Flow**
  563. ## 规则文件说明
  564. | 文件 | 主题 | 说明 |
  565. | ---------------------- | ------- | ---------------------------- |
  566. | `00-project-setup.mdc` | 项目结构 | Java / Gradle / 版本号 |
  567. | `01-registry.mdc` | 注册系统 | 按版本选择注册方式 |
  568. | `02-block.mdc` | 方块 | 方块 / 方块实体 / 流体 |
  569. | `03-item.mdc` | 物品 | 物品 / 工具 / 盔甲 / 食物 |
  570. | `04-entity.mdc` | 实体 | EntityType / Renderer / Goal |
  571. | `05-events.mdc` | 事件 | 按场景选事件类 |
  572. | `06-networking.mdc` | 网络 | 同步需求 → 包类型 |
  573. | `07-datagen.mdc` | DataGen | Provider 选择 |
  574. | `08-client-server.mdc` | 端分离 | 代码放哪侧 |
  575. | `09-anti-patterns.mdc` | 反模式 | 症状与正确方案 |
  576. | `10-gui.mdc` | GUI | Menu / Screen / Container |
  577. ## Agent Skills
  578. 路径示例:`forge/1.20.1/.agents/skills/<name>/`。每档有 **8 套宿主镜像**:`.agents` / `.claude` / `.continue` / `.cursor` / `.opencode` / `.pi` / `.trae` / `.zcode`(DSH 与 Codex 共用 `.agents/skills`,不另建目录;`sync-skills.ps1` 一次刷全部)。Wave D 新增 skill 曾用 `scripts/_oneoff/propagate-wave-d-skills.mjs` 同步(一次性,勿再跑),日常镜像用 `scripts/sync-skills.ps1 -All`。
  579. > 库模组 Skill(`mc-config` / `mc-geckolib` / `mc-curios` / `mc-patchouli` 等)**不落盘**:源稿在根目录 `knowledge/libs/<group>/mc-<name>/SKILL.md`(`all-platforms` / `fabric-only` / `neo-only` / `forge-only` / `bedrock-only`),按 AGENTS.md「库模组 Skill」解析规则使用;`propagate-wave-d-skills.mjs` 与平台 `.cursor/skills` **不再包含库项**。当前库源稿份数与唯一 skillId 数现读 `knowledge/libs/README.md` §当前规模(口径同文:份数 = 各组 `mc-*/SKILL.md` 数,唯一 skillId 按目录名 / frontmatter `name:` 去重,差额来自 `mc-curios` / `mc-kotlin-for-forge` 的双组镜像)。与本文 §7.5「② 库 Skill 源稿」行一致。
  580. | 平台/版本 | 数量 | 结构 | 说明 |
  581. |-----------|------|------|------|
  582. | `forge/1.12.2`–`1.20.4` 主档 | **35** | 目录(每 skill 一目录) | 15 核心 + 19 Wave D + `mc-events`(1.7.10 为诚实 stub) |
  583. | `forge/1.15.2` / `forge/1.17.1` | **35** / **35** | 目录 | 1.17.1 有 `mc-events`、无 `mc-capability`(与 1.20.1 集合不同) |
  584. | `forge/1.7.10` | **3 规则 + 3 技能** | 目录 | 仅 00/01/09 + `mc-item` / `mc-registry` / `mc-events`(stub:无 05 规则,事件 API 未核实禁止生成) |
  585. | `forge/1.8.9` · `1.9.4` · `1.10.2` · `1.11.2` | **3 规则 + 0 技能** | 只有 `rules/` | 四档各 00/01/09,`.cursor/skills` **目录不存在** ⇒ 0 技能是**按设计**(短规则树只做「不得把现代 API 抄进早期档」的门),不是漏建。实测(`readdir <pack>/.cursor/rules` 计 `*.mdc`、`.cursor/skills` 计条目);禁止拿 1.12.2 的 00–10 或 35 技能顶替 |
  586. | `forge/1.21.1` | **0 规则 + 0 技能**(draft) | 只有 `AGENTS.md` + `pack.meta.json` | 实测该目录**连 `.cursor/` 都没有** ⇒ session 必回 `PACK_NOT_FOUND`,也不在 `list_forge_versions`。登记为按设计,禁止为凑一个版本号克隆一棵新树,也禁止用 NeoForge 1.21.1 或 Forge 1.20.4 顶上 |
  587. | `fabric/*`(**15 档**,骨架全档同数;26.1.2 / 26.2 为 Mojmap) | **38** | `.md` 文件(薄档/26.1.2/26.2 为目录 layout) | 各档 18 基础(含 `mc-fabric-api` / `mc-kotlin` / `mc-cloth-config`)+ 19 Wave D + `mc-events`(含 **1.21.3** 与 **26.1.2**;26.1.2 / 26.2 为 Mojmap,禁止 Yarn)。薄档 `1.21.4`/`1.21.8`/`1.21.10` 的**规则 11 条 + Skill 38 项与其余 12 档完全同数**(实测(`readdir <pack>/.cursor/rules` 计 `*.mdc`、`.cursor/skills` 计条目):fabric 全部 15 档均为 11/38,没有例外),「薄」指的是语料不是骨架:该三档 `knowledge/` 实扫 **2 篇**(本档 `common/verified-api-<ver>.md` + 三档共用的 `version-changes/1.21.x.md`;`pack.meta.json` 里写的「1 篇」只数档专属的 `common/` 页),而有 `code-patterns/` 的 7 档为 **12–13 篇**(同为实测),且薄档**不落 `code-patterns/`**。`pack.meta.json` 的 `status:"ready"` 与这一自述不矛盾——判据取盘上实测、不取本句自称(裁定「薄档即声明」) |
  588. | `neoforge/<ver>` session 索引 | **以版本目录为准** | 目录 | 根 `neoforge/.agents/skills` **不是** session 源;主档与薄档(1.20.6 / 1.21.5 / 1.21.10)本档 Skill 同名集合(entity/datagen 等),不再是 6 个。**`neoforge/1.20.1` 本档仅 `mc-registry`**,其余走 Forge 1.20.1 overlay |
  589. | `quilt/<ver>` 本档磁盘(规则 **4** + Skill **3**) | **3** | 目录 | 仅 QSL 差异 `mc-registry` / `mc-events` / `mc-networking`;entity/gui 等继续 Fabric overlay,不计入本档磁盘数。规则实测(`readdir <pack>/.cursor/rules` 计 `*.mdc`、`.cursor/skills` 计条目)全部 10 档均为 4 条(`00-project-setup` / `01-registry` / `05-events` / `06-networking`),**不是** 00–10 全集,其余主题走同版 Fabric overlay |
  590. | `liteloader/<ver>`(1.8.9 / 1.10.2 / 1.12.2) | **3** | 目录 | `mc-events` / `mc-gui` / `mc-networking`(LiteLoader 专用口径,非 Forge API) |
  591. | `rift/1.13.2` | **3** | 目录 | `mc-events` / `mc-gui` / `mc-networking` |
  592. | `modloader/1.6.4`;`modloader/1.2.5`、`1.5.2` | **2**;**1** | 目录 | 1.6.4:`mc-item` + `mc-registry`;其余仅 `mc-registry`(safe-api 表外禁止输出) |
  593. | `bedrock` | **10** | 目录(×8 宿主镜像) | Script API / manifest / 资源与行为包等,见 `bedrock/.cursor/skills/`;不钉版本号,live docsStatus |
  594. | 分类 | Skills |
  595. | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
  596. | 核心 | `mc-registry`、`mc-block`、`mc-item`、`mc-blockentity`、`mc-entity`、`mc-mixin`、`mc-networking`、`mc-datagen`、`mc-capability`、`mc-gui` |
  597. | 内容 | `mc-fluid`、`mc-particle`、`mc-sound`、`mc-recipe`、`mc-enchantment`、`mc-potion`、`mc-effect`、`mc-command`、`mc-villager`、`mc-ai` |
  598. | 渲染 / 模型 | `mc-renderer`、`mc-model` |
  599. | 世界 / 数据包 | `mc-worldgen`、`mc-structure`、`mc-advancement`、`mc-loottable`、`mc-datapack`、`mc-resourcepack`、`mc-dimension`、`mc-weather` |
  600. | 配置 / 测试 / 能源 | `mc-gametest`、`mc-energy`、`mc-multiblock` |
  601. | 兼容 / 文档库 | `mc-compat-jei`(knowledge/libs 源稿 + forge/1.20.1、neoforge/26.1 平台自有副本,非镜像);库类(`mc-config` / `mc-cloth-config` / `mc-yacl` / `mc-geckolib` / `mc-architectury` / `mc-terrablender` / `mc-playeranimator` / `mc-pehkui` / `mc-kubejs` / `mc-balm` / `mc-modern-ui` / `mc-patchouli` / `mc-owo` / `mc-curios` / `mc-kotlin-for-forge` / `mc-trinkets` / `mc-cca` / `mc-polymer` / `mc-text-placeholder` / `mc-satin` / `mc-fabric-language-kotlin` / `mc-libgui` / `mc-lib-catalog` / `mc-author-shared-libs` / `mc-resourceful-lib` / `mc-moonlight-lib` / `mc-caelus` / `mc-spruceui` / `mc-player-ability-lib` / `mc-server-translations` / `mc-impersonate` / `mc-script-ui` / `mc-script-server`)→ `knowledge/libs`;份数 / 唯一 skillId 口径现读 `knowledge/libs/README.md` §当前规模 |
  602. Fabric 另含 `mc-fabric-api`、`mc-kotlin`、`mc-cloth-config`;Forge 1.12.2–1.20.4 与 Fabric 主档均含 `mc-events`(经 `FABRIC_SKILL_DONORS` 回填的薄档带 DONOR_SKILL 横幅)。代码模式示范见 `community_knowledge/patterns/`(也可经 `mcskill://patterns/README` 读取)。
  603. ## 纹理与模型
  604. 建模与贴图不在 MCP 工具面里。模型 JSON 骨架由 `generate_model` 出,纹理走 `mc-texture` 技能。
  605. ### 分工
  606. | 环节 | 用什么 | 本仓库给什么 |
  607. |---|---|---|
  608. | 方块模型 / blockstate / 物品 `items/` | `generate_model`(须传 `version`) | cube 与 `item/generated` 骨架 |
  609. | 有形状的模型、基岩 `.geo.json`、GeckoLib 动画 | 外部 Blockbench MCP | 落位规则(`geo/`、`animations/`、`textures/`) |
  610. | 纹理 / 纹理动画 / 粒子特效 | `mc-texture` | 完整流程 + 三个零依赖脚本 |
  611. | 32px 以上大图、人物立绘 | `pixel-art-upstream` | 上游方法论 + `grid.py` |
  612. | 引用完整性 | `audit_resources` | 不判 `pack_format` |
  613. 模型 MCP 是 GPL-3.0 的独立程序,按外部工具安装,与本仓库通过 MCP 协议通信:<https://github.com/jasonjgardner/blockbench-mcp-plugin>
  614. ### 技能入口
  615. `read_knowledge_resource uri=mcskill://skill/mc-texture`,源稿 `common_skill/mc-texture/SKILL.md`。`activate_platform_pack task=mc-texture` 的 warning 同时指向它与 `pixel-art-upstream`。
  616. 步骤:定尺寸 → 定风格 → 定调色板 → 分层画 → 渲染 → 1× 核对 → 改(≥3 轮)。用户指定的风格、色数、尺寸优先于原版惯例;未指定时按 16×16、可平铺、4–8 色、左上光源。分层顺序为平涂剪影 → 打光 → 内部细节 → 描边 → 五官。
  617. 材质按游戏内状态区分:铜为四级锈蚀(Unoxidized / Exposed / Weathered / Oxidized),绿色自棱角扩散、逐级反转,四套图一并制作;木头分原木 / 去皮 / 木板,石头分石头 / 圆石 / 石砖,金属用高光块而非噪点。依据为 Minecraft Wiki 的 Oxidation 条目与本仓 `data/` 语料。
  618. ### 纹理动画
  619. 竖排图集 + 同名 `.png.mcmeta`(文件名含 `.png`)。字段 `frametime` / `interpolate` / `frames` / `width`·`height`,默认 1 / false / 全部按序 / 按最短边推断。图集总高须被帧高整除;`frames: [0,1,2,1]` 可用于来回循环。
  620. 多帧制作用 `render-pixels.mjs` 的图集模式:一帧一个网格文件,一次渲染出竖排 PNG 并写好 mcmeta。预览用 `gif.mjs` 转 GIF,逐帧核对仍看 PNG 图集。
  621. ### 粒子特效
  622. 按规则逐帧计算:拆元素 → 带种子生成 → 固定步长积分 → 按已飞出距离着色。结构性图案(脸、logo、文字)用栅格,自然扩散(球、火花)用粒子。
  623. MC 烟花的 `shape` 合法值为 `small_ball` / `large_ball` / `star` / `creeper` / `burst`(缺省 `small_ball`),另有 `trail` 与 `flicker`。出处 `data/neoforge_*/…/resources_server_loottables_lootfunctions.md`。
  624. ### 脚本
  625. 三个脚本零依赖,PNG 与 GIF 均由 `node:zlib` 手写。
  626. | 脚本 | 作用 | 写入前校验 |
  627. |---|---|---|
  628. | `render-pixels.mjs` | 调色板 + 像素网格 → 1× PNG;多文件时拼竖排图集并写 mcmeta | 行宽、色号未定义、尺寸不符;警告孤立像素与半透明 |
  629. | `firework.mjs` | 五形状烟花图集 + mcmeta | 参数合法性,剔除尾部空帧 |
  630. | `gif.mjs` | 竖排图集 → GIF 预览 | GIF89a 结构 |
  631. ```bash
  632. # 单张纹理
  633. node common_skill/mc-texture/tools/render-pixels.mjs sprite.txt --out out.png --size 16x16 --scale 16
  634. # 纹理动画:多帧拼竖排图集,同时写出 .png.mcmeta
  635. node common_skill/mc-texture/tools/render-pixels.mjs f0.txt f1.txt f2.txt --atlas out/anim.png --frametime 3
  636. # 烟花特效
  637. node common_skill/mc-texture/tools/firework.mjs temp/firework --shape star --fps 12 --size 32 --trail --flicker
  638. # 转 GIF 预览
  639. node common_skill/mc-texture/tools/gif.mjs temp/firework/firework.png out.gif --delayCs 8 --scale ,6
  640. ## MCP/CLI TOOLS:89
  641. 服务名:`MC-AI-Coding-Assistant-Tool`。
  642. 推荐通用流程:
  643. 1. `diagnose_data_paths` / `list_*_versions` / `get_server_status` 确认数据与版本
  644. 2. 文档:`search_*` → `get_*_summary` → `get_*_full`(全文勿一次超过 2 页;`id` 必须来自搜索结果)
  645. 3. **平台 API** 用 `query_loader_api` / `search_loader_api` 或 `search_*_docs`;**Vanilla 签名**才用 `query_api` / `get_method_params`(仅约 1.16.5–1.20.4;1.12.2 只有 SRG 类名与 `func_/field_` 成员名;26.1+ 无索引)。规则树用 `activate_platform_pack action=session`(默认 00/01/09 + Skill 索引,见上文「规则包加载」)
  646. 4. 映射:`convert_mapping` / `lookup_obfuscated`(26.1+ 无混淆层)
  647. 5. 工程:`diagnose_gradle` / `validate_project` / `generate_datagen` / `crash_analyze` / `analyze_build_log` / `inspect_runtime`(日志型)。Forge/Fabric/Quilt/NeoForge 跑对应检查;LiteLoader/Rift/基岩的 `validate_project` 仍 skipped
  648. 6. 移植:`analyze_porting_path` →(确认后)`port_project`(默认 dryRun)
  649. 7. **社区 / 库模组**:实务与库选型 → `search_community_docs`(`lib-*` / `library-catalog-2026`;遵守 `AGENT_USAGE.md`)→ Read `knowledge/libs/.../SKILL.md`(先 `mc-lib-catalog`);`check_dependencies` 看 `detectedLibraries`
  650. 8. 工作流 / 知识:`get_workflow_template` / `list_knowledge_resources` → `read_knowledge_resource`
  651. 工具限制与误判对照见上文「工具边界」。
  652. ---
  653. ### 1. API 与映射 / 状态(6)
  654. | 工具 | 作用 |
  655. | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  656. | `query_api` | 查询 Vanilla/Parchment 类的方法签名、参数名、返回类型与 javadoc(按 `version` 加载 extracted 索引,**必填 version**,禁止默认 1.20.1)。**不含** Forge 特有类。有索引的档 = **1.7.10–1.20.4**。1.7.10–1.15.2 为 SRG 名(类名是该版 SRG 路径、成员名 `func_/field_`),无参数名/javadoc;1.16.5–1.20.4 为 Parchment;**26.1+** 无可用方法索引。精确 FQCN 或唯一简名(如 `Item`)才 `found:true`(改写时带 `autoCorrected`);`Handler` 等歧义子串 `found:false` + suggestions。平台 loader API 用 `query_loader_api`。 |
  657. | `get_method_params` | 按类名 + 方法名查询完整参数名列表(可带 JNI `descriptor` 区分重载)。多重载未传 descriptor → `found:false` + `ambiguous` + `candidates`。26.1+ 无索引 → `DATA_UNAVAILABLE`。 |
  658. | `convert_mapping` | 在 **mojang / mcp / yarn / parchment / obfuscated / intermediary** 间互转类/方法/**字段**(SQLite **v4**)。`memberKind=field`;`to=mojang` 为 Tiny official 短名(同 obfuscated 层);失败默认 `converted:null`(可选 `allow_fallback`)。**六个层不是每版都可用的**:yarn-tiny 档(fabric **1.14.4–1.21.x**)无 MCP/Parchment 可读层,`to=mcp` / `to=parchment` 直接拒绝 → `YARN_TINY_NO_MCP_LAYER`(改用 `to=yarn` 或 `query_api` / `get_method_params`);`mcp↔parchment` 为同名层(identity)。**批量(S3)**:`memberName` 用逗号 / 分号 / 换行传 ≤50 个名字,一次拿 `results[]` + `batch{requested,found,missing}`(超上限 `INVALID_INPUT`,不静默截断;单个名字时输出形状不变)。**条目行(S2)**:`accessLines=true` 附可粘贴的 AT / AW 行,名字层按加载器分叉——Forge 成员行必须 SRG 名、NeoForge 用可读名 + 粘连描述符、Fabric/Quilt 的 AW 条目名与描述符须同工程映射层(头随 `to` 取 named / intermediary / official);缺名或缺描述符 ⇒ `complete:false` 且行内 `<TODO…>`,完整行回灌 `validate_at` / `validate_aw` 同一解析器(`selfCheckOk`)。**生成面收窄**:AW 侧只出 `accessible` 条目,`validate_aw` 认的 `extendable` / `mutable` / `transitive-*` 并列形与两操作数指令 `inject-interface` / `extend-enum` **不代生成**(校验 ⊃ 生成,需要时手写)。**SRG 成员层覆盖**:Forge 1.16.5 / 1.17.1 / 1.18.2 / 1.19.4 / 1.20.1 / 1.20.4 六档已从 MCPConfig 削减件建出 `mappingEra=mcp-config-srg` 的库(`named` = SRG 名:1.17+ 哈希形 `m_/f_`、1.16.5 老形 `func_/field_`),这六档的 Forge AT 成员行出实名;该库只在 `platform=forge` 时参与选库。neoforge_* / quilt_* 仍无成员库 ⇒ 照旧 `<TODO…>`。**`from=mojang` 两档出处**:第一档 = 该档库的 `official` 列,那一列对**被混淆的类**存 Tiny 混淆短名(`a`/`fac`/`ccv`),只有本来不混淆的少数类带可读全路径(可读名占比不足 1%)⇒ 拿 `Container`/`Level` 这类 mojmap 可读名点查必然 `found:false`,**不得**读成「该版本没有这个类」;第二档 = 派生对照表 `data/_yarn-mojmap-pairs/`(类名级 `obf`/`mojmap`/`yarn` + 两侧 FQCN,**无 intermediary 列**),只在 `from=mojang` 且 `to` 为 `yarn`/`obfuscated` 时参与,命中带 `fallbackUsed:true` 且 notes 点名表与条数,`to=intermediary` 直接拒答不回落第一档。 |
  659. | `lookup_obfuscated` | 崩溃日志反混淆:单 token(`method_6032` / `er` / `func_110143_aJ` / `field_100013_f`)反查 → yarn 可读名 + ownerClass + descriptor。方法→字段→类;多命中 AMBIGUOUS;26.1+ 返回 `UNOBFUSCATED_NO_YARN`。 |
  660. | `get_server_status` | API 索引预热状态、`diagnose_data_paths` 摘要、descriptor 自检与 **updateHint**;可选 `warmup` 先加载指定版本。另返回 **`java`** 探测(`node` / `JAVA_HOME` / `version` / `ready` / `hint`,反编译与 remap 需 JDK 17+)。**只报本机 Java 现状,不做 Gradle ↔ JDK 匹配判定**(那走 `diagnose_gradle`)。 |
  661. | `get_version_info` | **【Forge only】** 按 MC 版本 + 操作(如「注册方块」)给出推荐做法、关键变更、gotchas 与官方 Changelog 链接。 |
  662. ### 1b. Loader API 与平台包(5)
  663. | 工具 | 作用 |
  664. | --- | --- |
  665. | `query_loader_api` | 查 Forge/NeoForge/Fabric-API/QSL 摘要中的类与 `MethodInfo`。**必填** `platform` + `minecraftVersion`,无默认 1.20.1。**不是** `query_api`。`found:false` 不代表游戏里没有该类。LiteLoader/Rift/ModLoader 无摘要 → `PLATFORM_SKIPPED`(可 `ingest_loader_api`)。 |
  666. | `search_loader_api` | 在 `fqcnIndex` 上子串搜索(`limit` 默认 20、封顶 50,**超限是静默 clamp 不是报错**)。`mode=list` 列出已索引档 / skipped / cache overlay。 |
  667. | `ingest_loader_api` | 用户自备 jar(官方不代下的 LiteLoader/Rift/ModLoader)抽成摘要,只写 `$MC_SKILL_CACHE/loader-api-summaries` overlay,**禁止写仓库 `data/`**。`jarPath` 绝对路径 + `mappingsVersion` 必填。默认 dryRun。不要用 `--file`。**同一平台多套构件时用 `library` 选键位**:`platform=fabric` 的候选键是 `<ver>-fabric-api`(API 库)与 `<ver>-fabric`(加载器本体),从前写侧固定取第一个候选键 ⇒ **拿 fabric-loader jar 不传 `library=fabric` 会覆盖该档的 API 摘要**;后缀不在候选里 ⇒ `INVALID_INPUT` 并列出候选,不猜、不新造键名。 |
  668. | `detect_mod_project` | 只读探测模组工程(Quilt 在 Fabric 前)。`projectPath`(CLI `--project`)优先于 `MC_SKILL_PROJECT_ROOT`。知识库根 / 某版 `scaffold` → `KNOWLEDGE_REPO_NOT_MOD`(Architectury 的 `forge/`+`fabric/` 无版本 `pack.meta.json` 不误伤)。对不上规则树 → `PACK_NOT_FOUND`,禁止邻档 00–10。 |
  669. | `activate_platform_pack` | `list` / `session` / `write` / `deactivate`。session 不写盘、不依赖项目根:默认规则 **00/01/09** + Skill **索引**(`topics`/`task` 追加并集;`skillNames` 注入正文上限 8;见上文「规则包加载」)。write 默认 dryRun,`hosts` 必填。不要再用 `includeSkills`,改用 `writeSkillStubs`(默认 true,只写 stub);`includeSkillBodies` 才写全文。目标只能是用户模组工程(拒绝知识库根)。**不能**开关 IDE 扫描器。 |
  670. ### 2. 工程辅助(7)
  671. | 工具 | 作用 |
  672. | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  673. | `diagnose_gradle` | 检查 `build.gradle` / `gradle.properties`:ForgeGradle + Fabric/Quilt Loom + NeoGradle/ModDevGradle。26.1 Loom 必须 `net.fabricmc.fabric-loom`、Java 25、禁止 `modImplementation`。liteloader 插件走轻量模式。Rift / BaseMod / 基岩仍早退。 |
  674. | `generate_datagen` | 生成 DataGen Provider 模板。**必填 `providerType` / `modId` / `targetName` / `version` / `platform`**。**Forge 1.20.1 与 1.20.4**(1.20.4 仅 recipe,`buildRecipes(RecipeOutput)`)、NeoForge 1.20.4/1.20.6(仅 recipe)/1.21.x/26.1、**Fabric** 1.21.1/**1.21.3**/1.21.4/1.21.8/1.21.10/1.21.11 与 26.1(无 1.21.5)。Quilt 无 generate_datagen,改口 `search_docs platform=quilt`。其它 Forge 版本返回 error。需 `modId`、`targetName`。 |
  675. | `crash_analyze` | 解析崩溃报告全文(或传 `crashReportPath` 直接读文件),推断 `crashKind`(含 `fml` / `client` / `server` / `fabric` / `quilt` / `liteloader` / `rift` / `modloader`)、可能成因、缺前置/版本不兼容与 `logHints`。优先于盲目网页搜索;实务分类可配合社区工具。 |
  676. | `validate_project` | Forge:mods.toml / DeferredRegister。Fabric/Quilt:`fabric.mod.json` / `quilt.mod.json` + entrypoint。NeoForge:`neoforge.mods.toml`、`@Mod` + `IEventBus`。LiteLoader/Rift/ModLoader/基岩 `skipped`。坏 recipe 只 warning。Java 扫描上限默认 300(`MC_SKILL_JAVA_SCAN_MAX_FILES`)。 |
  677. | `check_publish_ready` | 发布前清单:license/version、`build/libs` 是否像正式 jar,并读 `community_knowledge/authored/publishing.md` 的清单(缺项只 warning)。**不上传**、不调 Curse/Modrinth API。 |
  678. | `inspect_runtime` | 日志型 inspector:优先 `logsDir`/`crashReportsDir`;否则有界探测 `run/logs` 等。禁止全盘 / JVM attach。默认读文件尾部。支持**字节游标增量读**(传回上次的 `nextOffset`)与**有界等待**(`waitForPattern` + `waitMs`,封顶 60000ms):文件被截断/轮换时显式回 `rotated:true` + `missed:true` + `reason`,等待超时回 `matched:false` + `waitTimedOut:true` —— **缺口与超时一律明说,不得读成「没有新日志」**。 |
  679. | `resolve_lib_skills` | 按平台 + 精确 MC 版本解析 `knowledge/libs` 库 skill 源稿(§3.6:组映射 + `platforms`/`mcVersions` 过滤);返回仓库相对 `path` 与 `versionsJson` 真值提示(带该文件的库写坐标前先读对应 MC 版本 slot)。与 CLI `lib resolve` **同一 core**;只解析、不返回正文 —— AI 仍直接读源稿(文件即用)。 |
  680. ### 3. Forge 官方文档(5)
  681. | 工具 | 作用 |
  682. | ----------------------- | ----------------------------------------------------------------------------------------------------- |
  683. | `list_forge_versions` | 列出本地已加载的 Forge 文档版本。无数据时返回 `PLATFORM_DATA_MISSING`。 |
  684. | `search_forge_docs` | **hybrid** 搜索(L0 + 语义 RRF;无库则纯 L0)。`version` 必填(先 `list_forge_versions`)。与 `search_docs({platform:"forge"})` 等价。1.12.2 走 `forge-docs` 教程,不是 `query_api`。支持 `class:` / `event:` / `method:` 前缀与 `\|` OR、去停用词、标签过滤。返回页面 `id` 供后续工具使用。 |
  685. | `get_forge_doc_summary` | 取单页 L1 摘要:首段 + 各章节标题/短摘要,用于判断是否值得读全文。 |
  686. | `get_forge_doc_full` | 取单页 L2/L2+ 全文;默认 `highlight_key=true` 突出 🔴🟠🟢 关键段。**不要一次加载超过 2 个全文页。** |
  687. | `get_forge_doc_related` | 根据路径骨架、标签与章节关键词返回相关页面列表;成功返回 `{ok,id,version,results[]}`(`results` 恒为数组)。 |
  688. ### 4. Fabric 官方文档(5)
  689. | 工具 | 作用 |
  690. | ------------------------ | ------------------------------------------------------------------------------------- |
  691. | `list_fabric_versions` | 列出本地 Fabric 文档版本(`fabric-docs` / `fabric-wiki` 有索引即计入)。无数据 → `PLATFORM_DATA_MISSING`。 |
  692. | `search_fabric_docs` | **hybrid** 搜索;可选 `source`:`fabric-docs`(默认)/ `fabric-wiki` / `all`。wiki 偏入门;**26.1.2 无 wiki**。 |
  693. | `get_fabric_doc_summary` | Fabric 页 L1 摘要(可指定 source)。 |
  694. | `get_fabric_doc_full` | Fabric 页全文 + 关键段高亮(可指定 source)。 |
  695. | `get_fabric_doc_related` | Fabric 相关页推荐;成功返回 `{ok,id,version,source,results[]}`(`results` 恒为数组)。 |
  696. ### 5. NeoForge 官方文档(5)
  697. | 工具 | 作用 |
  698. | -------------------------- | --------------------------------------------------------------------- |
  699. | `list_neoforge_versions` | 列出本地 NeoForge **文档**版本;主文档默认 **26.1**(官方主文档不按版本分线,本仓无 26.2 / 26.3 语料 ⇒ 不克隆冒充);`26.2` / `26.3` 有规则树但**不进本列表**(文档检索请求这两档会回落并有 warning);**1.20.1** 可回退 Forge 数据。 |
  700. | `search_neoforge_docs` | **hybrid** 搜索(DeferredRegister、Data Components、Payload 等);无语义库则纯 L0。**须传 version**(先 `list_neoforge_versions`)。 |
  701. | `get_neoforge_doc_summary` | NeoForge 页 L1 摘要。 |
  702. | `get_neoforge_doc_full` | NeoForge 页全文 + 关键段高亮。 |
  703. | `get_neoforge_doc_related` | NeoForge 相关页推荐;成功返回 `{ok,id,version,results[]}`(`results` 恒为数组)。 |
  704. ### 6. 跨平台通用文档(5)
  705. 与专用工具能力对应,通过 `platform`(`forge` / `fabric` / `neoforge` / `quilt` / `liteloader` / `rift` / `modloader`,**必填**)统一入口。基岩请用 `search_bedrock_docs`(见 §6b)。
  706. | 工具 | 作用 |
  707. | ------------------- | ---------------------------------------------------------- |
  708. | `list_doc_versions` | 列出**指定** platform 的可用版本(不会一次返回三平台)。 |
  709. | `search_docs` | 多平台 **hybrid** 搜索;Fabric 时可传 `source`。无语义库 → 纯 L0;缺平台数据 → `PLATFORM_DATA_MISSING`。 |
  710. | `get_doc_summary` | 多平台 L1 摘要,用于判断某篇文档是否包含所需内容。Quilt 缺页回退 Fabric(`fallback=fabric`);FAPI 专属 Registry/ItemGroup 页拒绝(ok=false)。 |
  711. | `get_doc_full` | 多平台全文。适用于查看 API 完整步骤、事件列表、配置项清单;`highlight_key` 默认突出 🔴🟠🟢 关键段。Quilt 缺页回退 Fabric;FAPI 专属页拒绝,不返回 Registry 正文。 |
  712. | `get_doc_related` | 多平台相关页,返回共享最多关键词的其他页面。成功时返回对象 `{ok,platform,id,version,results[]}`。Quilt 回退 Fabric 时 `sourcePlatform:"fabric"` / `warning` 同时出现在顶层与条目,并丢掉 FAPI 专属页;FAPI 专属 id 拒绝(ok=false)。 |
  713. ### 6b. 基岩 Add-On(9)
  714. 与 Java `search_*_docs` / `validate_project` 分开。基岩用 Learn 文档与 pack JSON,不要用 Yarn / Mixin / `query_api`。
  715. | 工具 | 作用 | 判读(三态) | 错误码 |
  716. |------|------|------|------|
  717. | `search_bedrock_docs` | 检索 Microsoft Learn 基岩文档(带滞后 `docsStatus`)。可按调用放宽 `limit`(默认口径不变;只加宽窗口,不改排序与 release-notes 降权,池大小与放宽后的差额会在 `demotion` / `warning` 里说破)。 | 命中类:`ok` + `results[]`;**空 ≠ 没有该文档** —— 先看 `docsStatus` / `demotion` / `warning` | — |
  718. | `get_bedrock_doc_summary` | 基岩页 L1 摘要。 | 命中类:`ok` + 摘要;缺页走 `ok:false` + `error` | — |
  719. | `get_bedrock_doc_full` | 基岩页全文。 | 命中类:`ok` + 全文;**一次不超过 2 页** | — |
  720. | `get_bedrock_doc_related` | 基岩相关页。 | 命中类:`ok` + 数组;空数组 ≠ 失败 | — |
  721. | `validate_addon_manifest` | 校验 Add-On `manifest.json`(header/modules uuid 与 version)。不是 `validate_project`。 | 校验类:结论在 `errors[]`;本档未记载其专属三态名,以响应 `ok` / `error` 为准 | — |
  722. | `validate_bp_json` | 校验行为包实体等 JSON。 | 校验类:同上 | — |
  723. | `generate_addon_manifest` | 只吐 manifest JSON 文本,不写盘。 | 生成类:`resultKind` 三态同 §10(`ok` / `generation_failed` / `write_blocked`) | — |
  724. | `generate_bp_entity` | 只吐行为包实体 JSON 文本,不写盘。 | 生成类:同上 | — |
  725. | `analyze_bedrock_log` | 基岩 content-log(`content_log.txt`)分诊。**不是** Java `crash_analyze`。 | 读取类:无匹配 ⇒ 空结果 ≠ 无问题 | — |
  726. > 判读列口径:`ok:true` = 有结果;`ok:false` = 工具失败(原因在 `errors[]` / `error`)。**命中类工具的空结果不等于目标不存在**(索引缺失、语义降级、工具边界都会写明)。生成类另有 `resultKind` 三态,见 §10。
  727. > 错误码列的 `—` = 本仓库文档未记载该工具的专属错误码;实际错误以响应里的 `errors[]` / `error.code` 为准,**禁止凭记忆补码**。
  728. ### 7. 社区知识库(4)
  729. 与官方文档分离;**不替代** `search_*_docs`。适合发布、崩溃分类、软依赖、机器 GUI、库选型等实务。索引 **110** 条(`authored` 95 / `links` 11 / `permitted` 4,直读 `community_knowledge/indexes/index-l0.json`);库集成占其中 **48** 篇 `lib-*.md`。用法规则见 [`community_knowledge/AGENT_USAGE.md`](./community_knowledge/AGENT_USAGE.md);主题 id 速查见 [`community_knowledge/README.md`](./community_knowledge/README.md)。
  730. | 工具 | 作用 |
  731. | --------------------------- | --------------------------------------------------------------- |
  732. | `list_community_sources` | 列出 `community_knowledge` 条目(permitted / authored / links)及来源统计。 |
  733. | `search_community_docs` | 搜索社区库;命中含 `sourceKind`、`url`、`summary`。库集成可搜 `lib-curios`、`library-catalog-2026` 等。 |
  734. | `get_community_doc_summary` | 社区条目摘要(含署名);links 仅元数据 + 外链。 |
  735. | `get_community_doc_full` | permitted/authored 返回仓库内 Markdown;**links 只给 URL,不抓网页正文**。 |
  736. ### 7.5 库模组知识体系(短文 + Skill + 数据链)
  737. 三层结构,覆盖「库模组是什么 → 怎么用 → 数据从哪来」:
  738. **① 社区短文**(`community_knowledge/authored/`,经 `search_community_docs` 检索)
  739. - **`lib-*.md` 系列短文**,按功能分类:配置(Cloth/YACL/Fzzy/owo/MidnightLib…)、动画(GeckoLib/playerAnimator/Satin)、跨加载器(Architectury/Balm/Resourceful/Moonlight)、饰品(Curios/Trinkets/Caelus)、世界生成(TerraBlender)、GUI(LibGui/ObsidianUI/Modern UI)、数据附加(CCA/PAL)、服务端网络文本(Polymer/Text Placeholder/Server Translations/Impersonate/Pehkui)、脚本语言(KubeJS/Kotlin…)、配方(JEI/EMI/REI)、全家桶(Collective/Bookshelf/MaLiLib 等)
  740. - 总目录 `library-catalog-2026`(全览导航)、陷阱专篇 `lib-traps-2026`(8 条选型陷阱)、配方集成 `library-integration` / `library-integration-jei-emi`
  741. - 每篇含反编译核对小节(标题带该轮校验时点,以短文原文为准):已反编译核对的 MC 版本 × loader 的顶层 API 包/入口,细节以官方为准
  742. **② 库 Skill 源稿**(`knowledge/libs/`,按 AGENTS.md「库模组 Skill」解析使用,**不落盘**平台目录)
  743. - 五组目录:`all-platforms` / `fabric-only` / `forge-only` / `neo-only` / `bedrock-only`(各份数现读 `knowledge/libs/README.md` §当前规模;`neo-only` 为 Curios、KFF 与 forge-only 的镜像)
  744. - 解析规则:platform → 组映射(forge→forge-only+all-platforms;fabric/quilt→fabric-only+all-platforms;neoforge→neo-only+all-platforms;bedrock→bedrock-only)+ frontmatter `platforms`/`mcVersions` 二次过滤。路由中枢:`mc-lib-catalog`
  745. **③ 数据链**(短文 frontmatter → 脚本生成 → MCP 消费)
  746. ```
  747. authored/lib-*.md frontmatter(+ library-integration / library-integration-jei-emi 导航专篇)
  748. → mcp-server/scripts/build-library-catalog-from-authored.mjs → library-catalog.ts(catalog 条目 / verifiedApi 键 / officialUrls)
  749. → scripts/build-lib-manifest.mjs(Modrinth API)→ mcp-server/data/lib-manifests/all.json(slug / 版本条目矩阵)
  750. → scripts/batch-decompile.mjs(分批反编译,源码按需生成到 $MC_SKILL_CACHE,不入库)
  751. → scripts/merge-verified-api.mjs → 回填 verifiedApi
  752. → scripts/build-api-summaries.mjs → mcp-server/data/lib-api-summaries/(按库 × 版本组的 API 摘要)
  753. → check_dependencies 消费 catalog + manifest(库识别 / 版本摘要)
  754. ```
  755. **脚本位置分散,两处都有**(勿只查一处):
  756. | 脚本 | 位置 |
  757. |---|---|
  758. | `build-library-catalog-from-authored.mjs` | `mcp-server/scripts/` |
  759. | `build-lib-manifest.mjs` | **`scripts/`(仓库根)** |
  760. | `batch-decompile.mjs` | **`scripts/`(仓库根)** |
  761. | `merge-verified-api.mjs` | **`scripts/`(仓库根)** |
  762. | `build-api-summaries.mjs` | **`scripts/`(仓库根)** |
  763. 数据位置见 [反编译数据产物](#14-反编译数据产物) 一节。
  764. > 两个计数口径(A `verifiedApi` 键 / B 库 API 摘要侧)的**定义、读数与复算纪律一律见** [`CONTRIBUTING.md` §库数据链计数口径](./CONTRIBUTING.md);两个分母不同、禁止互相顶替。本节只描述数据链结构,不抄读数。
  765. ### 8. 移植、数据诊断与上游可用性(4)
  766. | 工具 | 作用 |
  767. | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  768. | `diagnose_data_paths` | 诊断数据目录配置(高级排障用)。诊断 `MC_SKILL_DATA` / `MC_SKILL_COMMUNITY` 解析结果,以及 forge/fabric/neoforge/quilt/liteloader/rift/modloader/bedrock/community 是 `found` / `empty` / `not_found`。排障首选。 |
  769. | `analyze_porting_path` | 扫描项目,识别平台/版本/Mappings/Architectury,输出风险、`routeSteps`、参考链接与建议的 `query_api` 调用。schema 上 `projectPath` 才是必填;**`targetPlatform` 由 handler 强制要求**(禁止静默默认 forge→neoforge,缺失 → `INVALID_INPUT`)。`routeSteps` 是给人读的 `string[]`;机器可读交接在 `nextSteps[]`(`tool` + 可直接调用的 `args`)。LiteLoader / Rift / ModLoader / 基岩 → `UNSUPPORTED_PORT`。 |
  770. | `port_project` | 执行移植步骤:`init_architectury` / `extract_common` / `apply_version_migration`。默认 **dryRun**;真正写入需 `dryRun=false` + `confirmed=true` + `MC_SKILL_ALLOW_WRITE=1` + 路径在 `MC_SKILL_PROJECT_ROOT` 内。 |
  771. | `query_upstream_releases` | 查**上游发布源**「某个加载器/映射/模组的版本到底存在吗、最新出到第几 build」。`source` **十选一**:`forge` / `neoforge`(maven-metadata.xml,全量可查)、`fabric-loader` / `fabric-yarn` / `quilt-loader` / `parchment` / `legacyfabric-loader`(端点按 MC 版本分列,**必须带 `minecraftVersion`**;parchment 的 artifact 名是 `parchment-<mc>`、版本串本身是日期如 `2023.09.03`;legacyfabric 的过滤走查询串 `?game_version=`,路径式 `/<mc>` 实测回 400)、`modrinth`(`slug`,任意第三方模组/库)、`maven`(`slug=<alias>:<group>/<artifact>`,主机别名表写死在 `mcp-server/src/upstream/releases.ts` 的 `MAVEN_HOST_ALIASES`,拼不出任意主机)、`mojang-manifest`(官方 `version_manifest_v2`,给 `minecraftVersion` 就按 `versions[].id` 过滤)。**与 `list_*_versions` 的区别**:那些列的是本仓库已入库的文档档位,不在清单 ≠ 上游没有。三态必读:`ok:false` ⇒ 没查到(网络/HTTP/解析),**不得**据此断言上游没有;`ok:true` + `available:false` ⇒ 上游确实没有。`matchRule` 回显版本归属规则(如 neoforge:MC 1.21.1 → 前缀 `21.1.`)。`releases` 按版本降序截断到 `limit`(默认 12),总数看 `total`;正式版排在同号 nightly 之前。**需联网**;Node TLS 失败自动回退 `curl.exe --ssl-no-revoke`,不改系统证书库;入口与重定向落点都过主机白名单(parchment 的托管后端 `ldtteam.jfrog.io` 已显式登记),落点不在白名单 ⇒ 报 `URL_REJECTED` 且不读正文。仓库首个带 `outputSchema` + `structuredContent` 的工具。**S4′ 磁盘缓存**:按档 TTL —— `available:true` 6 小时 / `available:false` 2 小时(证否会被新版本推翻,故短档)/ `ok:false` **不缓存**;缓存根只许 `$MC_SKILL_CACHE/upstream-cache/`(解析进仓库 ⇒ 拒写);响应带 `cache{hit,tier,ttlMs,ageMs?,wrote?,note?}`,`refresh=true` 强制回源、`MC_SKILL_UPSTREAM_CACHE=0` 整体关掉;缓存键含 `source`/`minecraftVersion`/`slug`/`limit`。`outputSchema` 同步声明了 `cache` 位。 |
  772. ### 9. Registry / Mixin / 资源(9)
  773. | 工具 | 作用 | 判读(三态) | 错误码 |
  774. | ------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------- |
  775. | `query_registry` | 查询 Vanilla 资源 ID(`nameLayer: registry_id`);类/方法名用 `convert_mapping`。 | 命中类:`ok` + 结果;**空 ≠ 没有该 ID**(只覆盖 `minecraft:`) | — |
  776. | `mixin_analyze` | 解析 mixins.json 与 @Mixin 注入目标(多映射层;高风险,见 supportMatrix)。`deep:true` 时基于已缓存 remapped 客户端 jar 做字节码级校验(目标类/选择器/@At 调用点);jar 未缓存 → CACHE_MISS 引导(不自动下载)。 | 校验类:`ok` + 结论;**jar 未缓存 = `CACHE_MISS` 引导,不是失败**(先调 `get_minecraft_source`) | `CACHE_MISS` |
  777. | `validate_at` | 字节码级校验 Forge/NeoForge `*_at.cfg`:类/成员存在性(继承链/record/内部类)、映射层不匹配建议、跨文件冲突。 | 校验类:结论在 `errors[]`;本档未记载其专属三态名,以响应 `ok` / `error` 为准 | — |
  778. | `validate_aw` | 字节码级校验 Fabric `.accesswidener`:header/namespace、条目类型、存在性、transitive、跨文件冲突。 | 校验类:同上 | — |
  779. | `audit_resources` | 静态检查模型纹理引用、孤儿纹理、modId 命名等。 | 校验类:同上(静态面,不做字节码级) | — |
  780. | `validate_datapack_json` | recipe / loot_table / advancement / tag 精简 JSON 校验(1.21+ recipe `result` 可为对象;不是完整 pack_format schema)。 | 校验类:**精简 schema ⇒ 通过 ≠ 完整 pack_format 合规**,只证明覆盖了本节列出的面 | — |
  781. | `get_workflow_template` | 工作流全文(以 `get_workflow_template` 列表为准;与 MCP Prompt 同名;Cursor tools 兜底)。 | 命中类:`ok` + 全文;模板名以该工具的列表为准(不是靠猜名字) | — |
  782. | `list_knowledge_resources` / `read_knowledge_resource` | 列出/读取 `mcskill://`(含 patterns、schema、workflow、community 等)。 | 命中类:`ok` + URI 列表 / 正文;缺 URI ⇒ `ok:false` | — |
  783. > 判读列口径:`ok:true` = 有结果;`ok:false` = 工具失败(原因在 `errors[]` / `error`)。**命中类工具的空结果不等于目标不存在**。生成类另有 `resultKind` 三态,见 §10。
  784. > 错误码列的 `—` = 本仓库文档未记载该工具的专属错误码;实际错误以响应里的 `errors[]` / `error.code` 为准,**禁止凭记忆补码**。本组唯一的确证码是 `CACHE_MISS`(`mixin_analyze deep` 的 jar 未缓存引导,不是错误而是"先补缓存")。
  785. > 计数口径:本组 **9 个工具 / 8 行** —— 末行把 `list_knowledge_resources` 与 `read_knowledge_resource` 合并为一行,标题「(9)」数的是工具数。
  786. 字节码级校验(`mixin_analyze deep` / `validate_at` / `validate_aw`)依赖 T2 缓存管线:
  787. jar 未缓存时返回 `CACHE_MISS` 引导(先调 `get_minecraft_source`),**绝不自动大下载**。
  788. ### 10. 代码生成模板(11)
  789. 本组 11 项工具**默认只吐文本 + `suggestedPath`,不写盘**。可选写盘须同时满足:`write=true` + `confirmed=true` + 环境变量 `MC_SKILL_ALLOW_WRITE=1` + 绝对路径 `MC_SKILL_PROJECT_ROOT`(缺失即 `PROJECT_ROOT_REQUIRED`);写入路径必须相对工程根且不含 `..`,越界报 `PATH_OUTSIDE_ALLOWLIST`。缺任一条件只回文本,不会静默落盘。**三态语义**:默认(无 `write`)= dry-run,恒 `ok:true` + `resultKind:"ok"`;**生成失败** ⇒ `ok:false` + `resultKind:"generation_failed"`(原因在 `errors[]`);**写入未完成** ⇒ `ok:false` + `resultKind:"write_blocked"`(CLI `success:false` + exit 1,写盘未发生,文本预览仍在 `result`,细粒度原因在 `writeError.code`)。计数口径:本组就是下表 11 项;**`generate_datagen`(DataGen Provider 模板)归 §2 工程辅助**,不在本组内。
  790. | 工具 | 作用 |
  791. |------|------|
  792. | `generate_model` | 方块/物品 JSON 模型与 blockstate 模板。**必填** `modId` / `blockName` / `version`;`kind` 默认 `block`,`kind=item` 只出物品模型(无 blockstates,`blockName` 位置传物品名)。物品模型路径按档分叉:`1.21.4+` / `1.21.11` / `26.1` 走 `assets/<mod>/items/`(Client Items),早期走 `models/item/`;另有时代上界哨兵(`eraUpperBoundError`),编造版本直接拒。 |
  793. | `generate_lang` | en_us + zh_cn lang JSON 骨架。**必填** `modId` / `entries` / `version`;骨架不随 pack_format 变。**空 `entries` 不静默(S6-③)**:仍 `ok:true`,但响应带披露 warning + 机读 `emptyEntries:true` ⇒ 那是空骨架,不是成品。 |
  794. | `generate_network_packet` | 网络包(C2S / S2C)骨架,按平台与版本给注册与收发样板。**必填** `modId` / `packetName` / `platform`;`version` 可选,但版本差异(payload vs `SimpleChannel`)只有传了才按档出样板。 |
  795. | `generate_capability` | Capability / DataAttachment 骨架。**必填** `modId` / `name` / `platform` / `version`。forge 1.20.1(及 1.18.2–1.20.4)Capability;neoforge 1.20.1 同 Capability 形态、1.20.4+ Data Attachment;fabric/quilt → error 改口 CCA。 |
  796. | `generate_config` | 配置骨架。**必填** `modId` / `loader` / `version`,禁止默认 forge。neoforge 1.21+/26.1/1.20.4/1.20.6 用 ModConfigSpec;1.20.1 用 ForgeConfigSpec(Forge 兼容);forge 侧只覆盖 ForgeConfigSpec 时代(1.13+,已核实 1.20.1;1.12.2 的 `Configuration` 不出);fabric/quilt 吐 Cloth Config 最小骨架并 warning 声明依赖(不是改口 mc-config)。fabric/quilt 的**默认永远是 Cloth**;YACL 只作**显式 opt-in**(`library` 参数已实现:枚举 `cloth \| yacl`,默认 `cloth`,不传即 Cloth;禁止改默认)。**传 `library=yacl` 拿到的是结构壳**:除类声明与已核实成员名外全是 `// TODO(未核实)`,用户必须另外对自己的 yacl jar 跑 `ingest_loader_api` 才能编译。Cloth / YACL 等**第三方配置库不是 loader API**:要用其方法名,必须先由用户自备 jar 走 `ingest_loader_api` 入库(默认 dryRun,只写 `$MC_SKILL_CACHE` overlay),未入库 → `query_loader_api` 只回 `found:false`,只能留 `// TODO(未核实)`。 |
  797. | `generate_entity_renderer` | 实体渲染器骨架。**必填** `modId` / `entityName` / `platform` / `version`;fabric/quilt 直接 error。 |
  798. | `generate_worldgen` | 世界生成 JSON 骨架。**必填** `modId` / `featureName` / `platform` / `version`,且有**两端版本哨兵**:1.x 只收 1.18.2–1.21.x、26.x 只收本仓核到的 26.1.x(上界常量 `WORLDGEN_MAX_MINOR_1X` / `MC_MAX_MINOR_26X`;编造版本号如 `1.99.9`、越界代如 `26.2` 一律拒绝并点名抬哨兵出口,不默默生成);`platform=forge` × 26.x 直接拒绝(Forge 无 26.x)。forge / neoforge 的 feature JSON;fabric / quilt 仅 `configured_feature` / `placed_feature`(禁止 forge `biome_modifier`)。无模板时 `errors` 列出支持档。 |
  799. | `localize_mod` | 汉化:自有模组 `diff` / `draft_zh`,或第三方 jar `extract` / `pack_draft`。无机器翻译,未填项标 `needsTranslation`;无 `en_us` 时可回退其它语言作源。 |
  800. | `generate_playtest_driver` | 游玩自测骨架(**必填** `platform` / `version`):`driverMode` 默认 `external_bridge`(桥动作序列 + 后置条件 + 证据约定);`in_jvm_player_agent` 在 **`PLAYTEST_VERIFIED_TIER` 列出的档**(唯一真源;正文不数档,档位列表以生成器现读为准)出**真执行器**(意图菜单 + 邮箱消费 + 类型化后置条件 + 逐意图预算),表外档只出契约 + 结构壳。不装桥、不跑游戏。 |
  801. | `generate_paper_plugin` | 生成 Paper 插件工程骨架 —— **服务端面,独立于模组面**(载体 `gradlew runServer` 而非 `runClient`;API 是 Bukkit/Paper 抽象层而非 `net.minecraft.*`;生命周期 `plugin.yml`+`onEnable` 而非 `@Mod`+事件总线;逐档 javap 改写表对本面**零适用**)。**只吐文本**、默认 dry-run,落盘由 `write=true` 控制 —— **不写仓库、不建平台树、不进任何模组面 scaffold 门**。**边界**:`paperApiVersion` 不给 ⇒ 生成一个会在依赖解析期**显式报错**的占位符(不静默取 `latest`);`plugin.yml` 的 `api-version` 默认 `TODO-未核实`(写错会导致加载期拒绝);**不产出二进制**(gradle wrapper jar 须自备);证据等级 = **结构壳**,未构建未运行。**非法输入**:`pluginName` 不是合法 Java 标识符、`packageName` 不是合法 Java 包名 ⇒ 直接拒。 |
  802. | `generate_playtest_server_driver` | 生成**服务端面**(Paper/Bukkit)游玩自测驱动(**必填** `evidenceDir`)—— **用法(最小闭环 / plan verb / 证据契约 / 判据范式 / 无人值守配方 / 起实例必备配置 / BOM 坑)见 `AGENTS.md` 的「服务端面的自动测试 loop 怎么用」**。⚠ 另注:与客户端 driver **证据契约逐字复用**(`state.json` / `exit-code.txt` **仅 0\|1** / `qa.log` / `rounds.jsonl` / `plan.txt` 同名同目录 ⇒ 判读侧 `inspect_playtest_evidence` 与 `inspect_playtest_multi` **零改动**);**执行面另造**:服务端没有客户端 ⇒ `move`/`goto`/`break`/`gui`/`jump`/`look`/`shot`/`scan` 等玩家级原语**一概不生成**。注入点是**新造**的:`JavaPlugin#onEnable` + `Bukkit.getScheduler().runTaskTimer`(同步调度、主线程)。只吐文本、默认 dry-run。**步骤面**:只支持 `wait` / `mark` / `stop` / `touch` / `waitfile` / `cmd` / `assert`(assert 仅 `player_count` / `world_count` / `marker`);**客户端专属步骤或未知 kind 一律判红,不静默跳过**。每个 Bukkit API 名都对着本仓签名语料核过(含 `dispatchCommand` **throws CommandException** 已捕获)。**不声称**进 `PLAYTEST_VERIFIED_TIER` —— 那条目带 `mappings`,服务端无 mappings。证据等级 = **结构壳**。 |
  803. ### 11. 日志与依赖诊断(8)
  804. | 工具 | 作用 | 判读(三态) | 错误码 |
  805. | --------------------- | --------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
  806. | `analyze_log` | 解析游戏/崩溃日志片段(可复用 `crash_analyze` 分类)。 | 读取类:`ok` + 分类结论;片段解析 ⇒ 结论只覆盖你贴进来的那一段 | — |
  807. | `analyze_build_log` | 解析粘贴的 Gradle/javac 构建失败日志(不执行 gradlew);返回符号/文件与建议工具。 | 读取类:`ok` + 符号/文件 + 建议工具;**它不跑 gradlew** | — |
  808. | `get_migration_guide` | 默认 Primer **toc**;`section` 只返回该章;`full=true` 才全文(含 url/license/loader)。route 含 platform 或 `from->to`。 | 命中类:默认只给 toc(三档:`toc` / `section` / `full`);**没给全文不等于没有该章** | — |
  809. | `check_dependencies` | 根据 `build.gradle` / `mods.toml` / `fabric.mod.json` / `quilt.mod.json` / `litemod.json` / `riftmod.json` / 基岩 manifest 提示依赖问题:loader 判定(quilt/fabric/forge/neoforge/liteloader/rift/modloader/bedrock)、库模组识别(catalog 接线)、冲突/陷阱检测。返回 `detectedLibraries`(含 `supportedVersions` 反编译验证版本窗口与 `manifestSummary` 版本/加载器摘要,数据来自 `library-catalog.ts` + `mcp-server/data/lib-manifests/all.json`)。 | 命中类:`ok` + `detectedLibraries`;**启发式 + catalog ⇒ 未收录的库会漏**(不是完整 Gradle 解析) | — |
  810. | `inspect_playtest_evidence` | 读游玩自测证据(exit-code / state.json / `[QA]` 段 / calls.jsonl / 截图),每件三态 `present\|absent\|unreadable`;须 `MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT`(realpath 硬边界)。可选委派 `inspect_runtime` 读日志。 | **三态**:每件 `present` / `absent` / `unreadable`;**缺件不得读成"没有失败"** | — |
  811. | `inspect_playtest_multi` | 多客户端**联合判读**(多会话):`clients[]`({id,evidenceDir})或 `evidenceRoot`(扫直接子目录当客户端;保留名 `sync/` 跳过并在 `autoSkipped` 里留痕)。逐客户端三态 + 联合判绿 + 锚点(state.json 的 `at` / plan.txt mtime / rounds 末轮)+ 会合 marker。 | **联合 fail-closed**:客户端数 ≥1 ∧ 每个 exit-code=0 ∧ state 与 qa 都 present ∧ rounds 末轮 ok≠false ∧(给了 `expectMarkers` 时)每个 marker 都 present;任一客户端目录 realpath 越出授权根 ⇒ **整体拒** | `NO_CLIENTS` · `CLIENT_NOT_GREEN` · `MARKERS_MISSING` · `OUTSIDE_AUTHORIZED_ROOT` · `DUPLICATE_CLIENT_ID` |
  812. | `playtest_intent` | 游玩自测**意图邮箱**(`in_jvm_player_agent` 真执行器的 LLM 侧接线):`action=read\|write`;write 写 `<evidenceDir>/intent.json`(driver 的 `waitintent` 步消费并改名 `intent.done.json`)。校验顺序:confirmed → 禁列(kill/tnt/fill)→ 菜单(`intent-menu.json`)→ 参数白名单 → 必填 → 邮箱占用(overwrite 覆盖)。须 `MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT`。失败码:`CONFIRMATION_REQUIRED` / `INTENT_FORBIDDEN` / `INTENT_NOT_IN_MENU` / `PARAM_NOT_DECLARED` / `MISSING_REQUIRED_PARAM` / `MAILBOX_BUSY` / `MENU_NOT_FOUND`。 | 写侧六段校验;**非法在写侧就拒**,不进执行器。失败形态三档:邮箱形态失败 = 数据(继续守候)/协议违规 = 写侧拒/脚本形态 = 判红停轮 | `CONFIRMATION_REQUIRED` · `INTENT_FORBIDDEN` · `INTENT_NOT_IN_MENU` · `PARAM_NOT_DECLARED` · `MISSING_REQUIRED_PARAM` · `MAILBOX_BUSY` · `MENU_NOT_FOUND` |
  813. | `playtest_bridge` | 调 BlackBoxPro 桥(host 恒 `127.0.0.1`;**端口不传即从 38081 递减扫描到 38071**,按 `/status` 载荷形状握手 —— 严格档要 `type=mc-skill-playtest-bridge` + `bridgeProtocol`,旧桥走 legacy 档并**显式披露**;可用 `expectPlatform`/`expectVersion` 防连错实例):`status` 看 `/status.ready`(已进世界);`execute` 发 `/execute`(原生超时 ⇒ `PLAYTEST_TIMEOUT`);`await` 轮询 `query_*` 等条件(桥无 `wait_until`)。`execute`/`await` 须 `confirmed=true` + 授权。桥无鉴权且通配绑定 —— 只在本机用。 | **超时 ≠ 没失败**:原生超时映射 `PLAYTEST_TIMEOUT`,**不得塌成"没失败"**。`/status.ready` 不可信,判"在不在世界"看 `query_player_state` | `PLAYTEST_TIMEOUT` |
  814. > 判读列口径:`ok:true` = 有结果;`ok:false` = 工具失败(原因在 `errors[]` / `error`)。**命中类工具的空结果不等于目标不存在**。本节三个真三态面:`inspect_playtest_evidence` 的 `present|absent|unreadable`、`playtest_intent` 的三档失败形态、`playtest_bridge` 的超时语义。
  815. > 错误码列的 `—` = 本仓库文档未记载该工具的专属错误码;实际错误以响应里的 `errors[]` / `error.code` 为准,**禁止凭记忆补码**。本节填写的 13 个码均为文档具名值。
  816. ### 12. 自我更新(1)
  817. | 工具 | 作用 |
  818. |------|------|
  819. | `mc_skill_update` | 检查 / 应用本仓库 **tooling + data** 更新(GitHub Release)。`action=check\|apply`;`scope=tooling\|data\|all`;默认 `channel=stable`(忽略预发布)。`apply` 默认 dryRun;真写需 `confirmed=true` + `MC_SKILL_ALLOW_WRITE=1` + `MC_SKILL_PROJECT_ROOT`=**本仓库根**。返回 `filesToOverwrite` / `diskSpace` / `restartRequired`。CLI:`node mcp-server/dist/cli.js update --action check\|apply`(旧位置参数 `check\|apply` 仍兼容,stderr 有迁移提示)。 |
  820. `get_server_status` 附带 `buildStatus`(src 比 dist 新时 `buildRequired=true`,提示重新 `npm run build`)、`updateHint`(上次 check 缓存,默认 TTL 1h)与 `pendingRestart`。
  821. ### 13. 反编译与模组源码(5)
  822. **默认零下载**:不预热、不预取;只有显式调用才下载到 `$MC_SKILL_CACHE`(MCP 默认 `%APPDATA%/mc-skill-cache` 或 `~/.config/mc-skill-cache`;仓库脚本默认 `os.tmpdir()/mc-skill-cache` —— 两者不是同一个目录,长跑批处理请显式设成同一路径),**绝不写项目目录**。
  823. **缓存与并发**:布局是 `<cache>/{jars,mappings,remapped,decompiled,decompiled-mods,registry,resources,locks}/` + `cache.db`(`node:sqlite`;`mdk/` 由 MDK 工具按需另建)。锁粒度、`meta`/`artifacts` 两表的字段与实现口径见 `mcp-server/README.md` §T2 反编译工具族;同版本/同产物目录并发时抢不到锁立即回 `CACHE_LOCK_BUSY` / `LOCK_BUSY`,不排队、不复用别人的半成品。
  824. **Java 17+ 前置**:VineFlower 负责反编译、tiny-remapper 负责 remap,两者都是 Java 17+ 工具,按需下到 `<cache>/resources/`;**固定版本与 SHA256 钉在 `mcp-server/src/decompile/downloaders/resources.ts` 的常量里**(哈希不符即失败,不静默换版本),逐件清单与许可见 `THIRD_PARTY_NOTICES.md`。探测顺序固定为 **参数校验 → `MC_SKILL_SKIP_DOWNLOAD` 门 → Java 探测**,所以 CI 里先看到的是 `DOWNLOAD_DISABLED` 而不是 `TOOLCHAIN_MISSING`;`JAVA_HOME/bin/java` 与 PATH 上的 `java` 都会探,取可用的最高 major,都不达标才报 `TOOLCHAIN_MISSING`(进程不崩溃)。`MC_SKILL_SKIP_DOWNLOAD` 只覆盖本族两个会下载的工具;`analyze_mod_jar` / `search_mod_code` 本来就不下载,`download_official_mdk` 不读该变量。
  825. | 工具 | 入参与行为 | 产物 / 关键边界 |
  826. |---|---|---|
  827. | `get_minecraft_source` | `{version, className, mapping?: "auto"\|"yarn"\|"mojmap", lines?: [start,end], force?}`。`version` 缺 ⇒ `VERSION_REQUIRED`,`className` 缺 ⇒ `MISSING_REQUIRED`;`className` 收点号或斜杠形态;`mapping` 默认 `auto`:1.14–1.21.11 → `yarn`,26.1–26.3 → `mojmap`;`lines` 为 1-based 闭区间,默认前 120 行,区间非法直接 `INVALID_INPUT`(不静默改范围) | 落 `<cache>/decompiled/<version>/<mapping>/<类路径>.java`,返回 `totalLines` / `snippet[]` / `remap ∈ two-step-yarn \| single-step-mojmap \| none`。缓存命中 <1s,首次 3–10 分钟。VineFlower 先 `--only=<类路径>` 定向,目标文件没产出再全量兜底。**`force` 只绕过类文件命中并强制重下 manifest / 映射、重跑 remap;已存在的 `.java` 不会被重写**(要重编译先删该文件) |
  828. | `analyze_mod_jar` | `{jarPath, version?}`;纯 Node 读 zip 中央目录:`quilt.mod.json` / `fabric.mod.json` / `mods.toml` / `neoforge.mods.toml` / `litemod.json` / `riftmod.json` / 基岩 `manifest.json`、mixins 引用、entrypoints、依赖、AW/AT。传 `version` 回显 `requestedVersion` / `mcVersionConstraints[]` / `versionMatch ∈ match \| mismatch \| unknown` | 无 Java、零下载、不写盘、不反编译。`versionMatch: unknown` = jar 里没有可判定的版本约束,**不是**「不兼容」 |
  829. | `decompile_mod_jar` | `{jarPath, version?, mapping?: "yarn"\|"mojmap", force?}`。`version` 给出且落在 1.14–1.21.11 才 remap(`mapping` 默认 `yarn`,两步 official→intermediary→named);26.1–26.3 免 remap;不传 `version` 就是直接反编译原始字节码 | 落 `<cache>/decompiled-mods/<modId>/<modVersion>-<jar sha512 前 12 位>/`。身份段取自 **jar 字节内容**(不是 mod 元数据)⇒ 同 `modId` + 同 `modVersion` 的两个不同构建不会共用一棵树。`modId` 必须自证:jar 自身元数据 → 它自己声明的内层件(`META-INF/jars\|jarjar/*.jar`,多义只回候选不猜)→ 调用方标签(须被该 jar 自己的条目路径证实),都不成立 ⇒ `MOD_ID_UNKNOWN`,**不回落共享的 `unknown-mod` 目录**。写前清空目标子树(失败 ⇒ `CACHE_CLEAN_FAILED`)。remap 失败**降级**为对原 jar 反编译:`remapped:false` + `degraded:true` + warnings,此时名称可能是混淆/中间名,不可当正式 API。完成标记 `.mc-skill-decompiled.json` 写失败 ⇒ `partial:true`(源码树仍可用,`found` 仍为 true)。缓存命中按标记里的 `version`/`mapping` 判,与本次请求不一致 ⇒ `cacheStale:true` 并提示加 `force:true`。返回摘要 `fileCount` / `javaFileCount` / `topLevelDirs` / `sampleFiles` |
  830. | `search_mod_code` | `{query, decompiledDir?, jarPath?, pattern?, maxResults?}`。`decompiledDir` 优先且必须是绝对路径;`jarPath` 走 `cache.db` 反查已反编译目录。默认**忽略大小写的子串**匹配;`pattern:true` 才走正则(只加 `i`,不加 `g`/`y`;`>512` 字符或嵌套量词直接 `INVALID_INPUT`) | 默认扫 `.java` / `.txt` / `.json` / `.toml` / `.cfg`;`maxResults` 默认 100、上限 500;有单次时间与文件数预算,任一触顶都置 `truncated:true`(**截断 ≠ 没命中**)。`pattern` 模式下超长行不参与检索,会随响应带 `PARTIAL_SCAN`。`found:false` 只表示 0 命中;jar 存在但没反编译 ⇒ `NOT_DECOMPILED`,jar 不存在 ⇒ `NOT_FOUND`,两个入口都没给 ⇒ `INVALID_INPUT` |
  831. | `download_official_mdk` | `{platform, minecraftVersion, buildPlugin?, dryRun?, confirmed?, destPath?, allowCacheFallback?, allowUnpinned?}`。默认 `dryRun`(只回 pin 元数据);`dryRun:false` **即使不写用户工程也会联网下载并落 cache**,所以同样要 `confirmed:true`;写用户工程另需 `destPath` + `MC_SKILL_ALLOW_WRITE=1` + `MC_SKILL_PROJECT_ROOT` | 落 `<cache>/mdk/<platform>/<version>/<buildPlugin>/`,解压到 `unpacked/` 并解析 `entryClass` / `loaderVersion` / `mappings`。pin 表 `mcp-server/data/mdk-checksums.json`(可被 `MC_SKILL_MDK_CHECKSUMS` 覆盖):GitHub 源 `ref` 必须是 40 位 commit SHA 且出现在 `archiveUrl` 里,域名过白名单;`sha256` 为空 ⇒ fail-closed `MDK_NOT_PINNED`,只有显式 `allowUnpinned:true` 才接受未校验下载并回写。解压用 `unzip` / `7z` / **bsdtar**(Windows 自带 `System32\tar.exe` 与 7-Zip 默认安装位都会探;GNU tar 解不了 zip);另有 zip-slip 拦截、解压体积预算与「解压产物 vs 中央目录清单」复核。**两种发行形态的数据面不同**:npm 包(`package.json` 的 `files` 含 `data`)自带 MCP 侧小数据 —— `mdk-checksums.json` / `bedrock-script-api-pin.json` / `wrapper-jars.json` / `lib-api-summaries/` / `lib-coords/` / `lib-manifests/` / `loader-api-summaries/`,所以 pin 链在 npm 形态可用;**GitHub Release 的 `mcp-server-*.zip` 只打 `dist/` + 元数据,不含这 7 项**,需从 `mc-skill-data-full-*.zip` 解压补齐(`npm install --data` 也按此合并,保留包内自带项)。平台语料(`forge_*` 等)两种包都不含。`allowUnpinned` 的回写目标在 `<包根>/data/`,升级/重装会被覆盖 ⇒ 长期维护用 `MC_SKILL_MDK_CHECKSUMS` 指向包外 pin 表。LiteLoader / Rift 无官方 MDK(只剩各档 scaffold) |
  832. **版本支持面**(只约束 `get_minecraft_source` 的 MC 源码反编译;**`decompile_mod_jar` 没有版本门** —— 任意版本的 jar 都能反编译,`version` 只决定要不要 remap、用哪套映射)。门在 `mcp-server/src/decompile/version-manager.ts` 的两张已发布上界表(`MAX_RELEASED_PATCH_BY_MINOR` / `MAX_RELEASED_PATCH_BY_26X_MINOR`):表外的 minor/patch 在参数校验就拒,编造的 `1.21.999` 与尚未发布的 minor 都不放行。
  833. **当前所有已发布正式版都在支持面内**(上界表随 Minecraft 发版补测更新;表外版本在参数校验就拒):
  834. | 支持面 | Yarn | Mojmap | 说明 |
  835. |---|---|---|---|
  836. | 1.14 – 1.21.11 | ✅ | ✅ | 默认 yarn(两步 official→intermediary→named);mojmap 单步。mojmap 自 1.14.4 起才有 `client_mappings`:1.14–1.14.3 选它会在下载阶段 `MAPPINGS_NOT_FOUND`,用默认 yarn 即可 |
  837. | 26.1 – 26.3(当前 26.x 正式版全集) | ❌(Yarn 已停更) | ✅(免 remap) | 已去混淆,client jar 里就是可读名 |
  838. | 支持面外 | — | — | 1.13.2 及更早、快照、尚未发布的 minor;`INVALID_INPUT` 并回支持区间 |
  839. 映射面各自还有上游门(yarn 的 build 元数据 / 校验和 sidecar / 三列命名空间,mojmap 的 manifest 下载项),缺一即失败而不是无校验降级;实现与失败码见 `mcp-server/src/decompile/downloaders/yarn.ts`、`mcp-server/src/decompile/services/java-pipeline.ts`。
  840. **本族失败码**(取自实现,具体值以响应里 `error.code` / `action.code` 为准):`TOOLCHAIN_MISSING`(Java <17 或缺失)、`DOWNLOAD_DISABLED`(`MC_SKILL_SKIP_DOWNLOAD=1`)、`CACHE_LOCK_BUSY` / `LOCK_BUSY`(并发)、`CLASS_NOT_FOUND`(反编译跑完但该类不在该命名空间)、`MAPPINGS_NOT_FOUND` / `MAPPINGS_CHECKSUM_MISSING` / `MAPPINGS_EMPTY`(映射缺、sidecar 校验和缺、映射解析为空)、`DISK_INSUFFICIENT`、`DECOMPILE_FAILED`、`MOD_ID_UNKNOWN`、`CACHE_CLEAN_FAILED`、`NOT_DECOMPILED`、`MDK_NOT_PINNED`。`found:false` 不等于「类/库不存在」:命中类工具的空结果只说明**没查到**。
  841. **与 `query_api` 的分工**:`query_api` / `get_method_params` 查 **1.16.5–1.20.4 Vanilla** 签名(快、离线);**不含** Forge/Fabric API,**26.x 无索引**。本节取源码类工具(`get_minecraft_source` / `decompile_mod_jar` / `search_mod_code` / `download_official_mdk`)仅在确实需要完整源码/反编译时使用(下载量大),各工具 description 均带 ⚠️ 边界提示。
  842. ### 14. 反编译数据产物
  843. **已入库的反编译数据产物**(供 `check_dependencies` 等消费,clone 后即用):
  844. | 数据 | 位置 | 内容 |
  845. |---|---|---|
  846. | `library-catalog.ts` | `mcp-server/src/diagnostics/` | catalog 条目(`lib-*` 短文 + 集成导航专篇)/ `verifiedApi` 键(`gameVersion/loader → packages/entrypoints`)+ **`supportedVersions` 版本窗口**(Modrinth 受支持 MC 版本列表,反编译验证)+ `officialUrls`。计数口径 A 见 `CONTRIBUTING.md` §库数据链计数口径 |
  847. | `lib-api-summaries/*.json` | `mcp-server/data/` | 各库 public 类 / 方法签名摘要(按库 × 版本组分文件)。计数口径 B 同上 |
  848. | `lib-manifests/all.json` | `mcp-server/data/` | slug / 版本号 / URL / hash / loader 矩阵(Modrinth API 生成)。**根是数组**,每项 `{slug, entries[]}`;版本条目在 `entries` 里,按顶层 `versions` 取会算出 0 |
  849. > **`packages` 是启发式产物,不可当 import 依据**:`verifiedApi.<版本/加载器>.packages` 由 `scripts/batch-decompile.mjs`
  850. > 从反编译产物的顶层目录截得来(通用 TLD 取前 3 段、其余取前 2 段,且同层只按字母序取首个子目录),
  851. > 所以它只回答「这个库大概活在哪几个包根下」,**不是**可直接照抄的全类名清单。要落到具体类名,
  852. > 必须走 `query_loader_api`(先让用户自备 jar 跑 `ingest_loader_api`)或 IDE 补全核对。
  853. > 归属侧已有硬约束:`scripts/merge-verified-api.mjs` 会整行拒绝「包根已被别的库条目证实」的包名(JiJ 内嵌库泄漏),
  854. > 自检见 `mcp-server/test-scripts.mjs` 的 §S3 块。
  855. > **已知缺口(实测核实,不伪造)**:catalog 中有若干条 `verifiedApi` 为空对象——其中 4 条是拉不到 jar 的第三方库 `lib-config-legacy`、`lib-libgui`、`lib-server-translations`、`lib-spruceui-obsidianui`。根因:这 4 条在 `library-catalog.ts` 中 `modrinthSlug` 为空,且实测 Modrinth `project/libgui`、`project/spruceui`、`project/server-translations-api`、`project/config-legacy` 均返回 **404**(无对应项目),因此 `build-lib-manifest` 拉不到版本清单、`batch-decompile` 无 jar 可反编译,`verifiedApi` 保持 `{}`。这些库的 API 请以各自 `officialUrls`(GitHub 仓库)为准,禁止从邻库或邻版克隆摘要。另 `authored/lib-traps-2026`(`role: "trap"`)与 `authored/library-integration`(汇编条目)按设计不带 `verifiedApi`,不属缺口。
  856. > 注:`lib-spruceui-obsidianui` 条目中的 `obsidianui` 在 Modrinth 确实存在(200)。若后续要为其补摘要,正确做法是在 `community_knowledge/authored/lib-spruceui-obsidianui.md` 的 frontmatter 补 `modrinthSlug` 后重跑数据链,**不要**直接手改生成物 `library-catalog.ts`。
  857. 反编译源码本体**不入库**(按需生成至 `$MC_SKILL_CACHE`;规模随「反编译过哪些库 × 哪些版本」变化,仓库不承诺固定文件数,需要时按缓存目录现读)。`search_mod_code` 在源码缺失时返回 `NOT_DECOMPILED`(jar 存在但没反编译过)或 `NOT_FOUND`(jar / 目录本身不存在)+ 指引先调 `decompile_mod_jar`。相关脚本:`scripts/build-lib-manifest.mjs`(manifest)、`scripts/build-api-summaries.mjs`(API 摘要)、`scripts/batch-decompile.mjs`(分批反编译)、`scripts/merge-verified-api.mjs`(回填 catalog)。
  858. 另:`registerPrompt` / `registerResource`(工作流与知识 URI)供支持 prompts/resources 的客户端使用;详见 `mcp-server/docs/prompts-client-compat.md`。
  859. ### 15. 工作流模板(MCP Prompts)
  860. 工作流模板通过 `registerPrompt` 注册(支持 prompts 的客户端可用);Cursor 等仅 tools 客户端用该工具(`get_workflow_template`)获取同款全文。**模板名以 `get_workflow_template` 的枚举为准**(开发模板 + 编排技能两族,另见本页 `mcskill://skill/` 族)。
  861. 这些模板是 **Agent 步骤清单**(人在环):对齐创意与版本取舍后给出检索/草稿/校验顺序。**没有** Gradle / 拷 jar 进游戏目录 / 上传发布的 MCP 工具;`mc-build-mod` / `mc-ingame-iterate` 只列步骤,须用户确认后在本机执行。不代跑 Gradle、不自动拷 mods、不上传商店——高风险步骤写明「用户确认后执行」,这是设计。
  862. | 模板名 | 标题 | 流程要点 |
  863. | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
  864. | `mc-new-block` | 新方块工作流 | DeferredRegister 注册 → BlockItem → 模型(generate_model)→ lang(generate_lang)→ loot(generate_datagen)→ 可选 tags/recipe |
  865. | `mc-new-entity` | 新实体工作流 | EntityType + 属性 → SpawnPlacement/生物蛋 → 渲染器(generate_entity_renderer)→ loot/音效 |
  866. | `mc-new-gui` | GUI 工作流 | MenuType + AbstractContainerMenu → Screen 注册 → 按平台同步(Forge SimpleChannel / NeoForge Payload / Fabric ServerPlayNetworking) |
  867. | `mc-crash-triage` | 崩溃分诊 | analyze_log/crash_analyze → search_community_docs → validate_project + mixin_analyze → diagnose_gradle |
  868. | `mc-port-mod` | 移植模组 | analyze_porting_path → 确认目标 → port_project dryRun → get_migration_guide |
  869. | `mc-build-mod` | 模组构建流程 | validate_project / diagnose_gradle → **用户确认后** gradlew build → 确认 build/libs jar;失败则分析日志;可接真机循环 |
  870. | `mc-ingame-iterate` | 真机测试与修复循环 | 索取并核对启动器路径(官方/HMCL/PCL2 版本隔离)→ **用户确认后**装 jar → 复现 → 修 → 再测。路径约定见模板正文与 [HMCL 隔离文档](https://docs.hmcl.net/launcher/isolation.html) |
  871. | `mc-ingame-playtest` | 游戏内游玩测试(桥) | preflight(桥 jar/依赖记账)→ `playtest_bridge`(`/execute` + `/status.ready` + `await`)→ 截图/查询证据 → `inspect_playtest_evidence` → 改码回灌;执行权见根 AGENTS.md「人在环例外:游玩自测(三通道)」 |
  872. | `mc-localize-mod` | 模组汉化 | 判定 own/third_party → `localize_mod` diff/draft 或 extract/pack_draft → Agent 填中文 → 自检;见 `authored/localization-lang` |
  873. | `mc-decompile-mod` | 模组反编译研究 | 定位 jar → `analyze_mod_jar` → `decompile_mod_jar` / `get_minecraft_source` → `search_mod_code` → 定位目标类 → 修改建议 → 衔接 `mc-build-mod` / `mc-ingame-iterate` |
  874. | `mc-new-item` | 新物品工作流 | 该档 03-item 注册 → 模型/lang → 合成(有模板才 generate_datagen) |
  875. | `mc-new-blockentity` | 方块实体工作流 | BlockEntityType + 方块 → 渲染/同步;GUI 接 mc-new-gui |
  876. | `mc-mixin` | Mixin 工作流 | mixin_analyze → mixins.json 分桶 → 核 mappings |
  877. | `mc-worldgen` | 世界生成工作流 | configured/placed feature → 该档 biome 注入 |
  878. | `mc-config` | 配置工作流 | generate_config(loader+version 必填)或 Cloth Config |
  879. | `mc-gametest` | GameTest 工作流 | 按平台核文档,禁止默记 Forge 1.20.1 |
  880. | `mc-publish` | 发布清单 | 元数据 / build/libs / changelog / license;尽量让用户自行上传(人在环,不代传) |
  881. | `mc-setup-env` | 开发环境搭建 | detect_mod_project → MDK dryRun 或 Loom/映射清单;genRuns 由用户确认后执行 |
  882. | `mc-full-mod` | 从零新模组总链 | 仅从零:setup-env → mc-new-* → build → ingame-iterate → 可选 localize/publish |
  883. | `mc-networking` | 网络通信清单 | session task=mc-networking → generate_network_packet(带版本后缀) |
  884. | `mc-capability` | 能力 / 附件清单 | Forge/Neo 1.20.1 Capability;Neo 1.20.4+ Attachment |
  885. | `mc-recipe-data` | 配方与数据包 | 07-datagen / mc-recipe / loot / advancement |
  886. | `mc-audio-vfx` | 音效与粒子 | mc-sound / mc-particle |
  887. | `mc-commands` | 命令 | mc-command |
  888. | `mc-dimension-structure` | 维度与结构 | mc-dimension / mc-structure |
  889. | `mc-access` | AT / AW | validate_at / validate_aw |
  890. | `mc-bedrock-addon` | 基岩 Add-On | search_bedrock_docs / validate_addon_manifest;不灌 Java 02–10 |
  891. | `mc-fluid` | 流体 | 02 + mc-fluid |
  892. | `mc-enchant-potion` | 附魔 / 药水 / 效果 | mc-enchantment / mc-potion / mc-effect |
  893. | `mc-energy` | 能量 | mc-energy / mc-capability |
  894. | `mc-creative-tags` | 创造栏与标签 | 03 |
  895. | `mc-kotlin` | Kotlin 模组 | 00;核该档文档 |
  896. | `mc-jei` | JEI 兼容 | mc-compat-jei |
  897. | `mc-ci-publish-extra` | CI 发布附加 | 00;只出步骤名(可复制 YAML 见 `community_knowledge/patterns/examples/mod-ci-github-actions.md`),不代跑 CI、不上传(人在环) |
  898. | `mc-villager` | 村民职业 / 交易 | session task=mc-villager → 04-entity;职业/交易签名核本档文档,禁抄邻档 |
  899. | `mc-multiblock` | 多方块结构 | session task=mc-multiblock → 02-block / 07-datagen;无模板时文档手写 |
  900. | `mc-ai` | 实体 AI / Goal | session task=mc-ai → 04-entity;Goal/Brain 类名核本档文档,禁把 1.12 AI 任务表抄进 1.20+ |
  901. | `mc-events-forge` | Forge 事件系统清单 | session task=mc-events-forge → 05-events / mc-events;注册期 vs 运行期订阅分叉逐版取该档 05-events.mdc(≤1.17 起);类名核 search_forge_docs |
  902. | `mc-events-neoforge` | NeoForge 事件系统清单 | session task=mc-events-neoforge → 05-events / mc-events;mod bus(注册期)vs 游戏总线(运行期)逐档取该档 05-events.mdc;类名核 search_neoforge_docs |
  903. | `mc-events-fabric` | Fabric / Quilt 事件系统清单 | session task=mc-events-fabric → 05-events / mc-events;「初始化里 register 回调 vs 回调内运行期逻辑」逐档取该档 05-events.mdc(薄档 1.21.4/1.21.8/1.21.10 只有指路句);Quilt 分支只走 quilt/<ver>/05-events(QSL 无正式版构件,禁止把 Fabric 回调当 QSL);类名核 search_fabric_docs |
  904. | `mc-rendering` | 渲染工作流(BER / 自定义模型加载器 / 着色器) | 渲染注册入口按平台 + 版本分叉,禁止一条 API 名覆盖全档;先确认平台与精确版本 → session(可 task=mc-new-blockentity / mc-new-entity);表现层接 `mc-audio-vfx` |
  905. | `mc-profiling` | 性能剖析工作流 | 卡顿 / 内存 / 耗时的独立剖析面;原则「先测量后优化」。是 `mc-crash-triage` 第 5 步与 `mc-build-mod` 第 7 步的完整版 |
  906. | `mc-save-migration` | 存档数据结构迁移工作流 | **强制第一步**:改存档 schema 前必须先让用户整份备份世界目录并回报路径。覆盖 SavedData `.dat`、方块实体 / 实体 / 区块读写格式、跨版本旧世界兼容 |
  907. | `mc-server-multiplayer-test` | 服务端与多人联机测试工作流 | 联机侧验证:专用服务端、多客户端同房、状态同步、权限与延迟下行为。构建走 `mc-build-mod`,单机真机走 `mc-ingame-iterate` |
  908. | `mc-combat-attribute` | 伤害 / 属性 / 战斗工作流 | 伤害种类、实体属性与加成、战斗数值。附魔 / 药水 / 效果走 `mc-enchant-potion`,战利品走 `mc-recipe-data` |
  909. | `mc-multi-loader` | 多加载器(Architectury)工作流 | 一份源码产出 Fabric / NeoForge(或 Forge)多加载器构建;构建与调试成本翻倍属取舍,先与用户确认。已有工程改代码走对应平台 session |
  910. | `mc-modpack` | 整合包集成工作流 | 把第三方 mod 装成可跑的包:依赖闭包、加载顺序、冲突分诊。不做自动发布,不代下载 / 代上传 mod 文件 |
  911. | `mc-datapack-standalone` | 独立数据包工作流(无 Java 代码) | 纯数据包:世界 `datapacks/` 目录或独立 zip,无 `build.gradle`、无 Java 源码。模组附带的配方 / 战利品走 `mc-recipe-data` 与对应平台 session |
  912. | `mc-resourcepack-standalone` | 独立资源包工作流 | 纯资源包:`resourcepacks/` 或独立 zip(模型 / 方块状态 / 纹理 / lang / 音效 / GUI 贴图)。模组内资源走对应平台 session 与该档规则 |
  913. | `mc-new-model` | 模型与纹理工作流 | session task=mc-new-model → mc-model / mc-resourcepack / mc-renderer;定形状由用户拍板 → `generate_model` 出 cube 骨架再改 `elements[]`(基岩走 RP `models/` 与 `minecraft:geometry`)→ 16×16 贴图逐像素核对 → `audit_resources` 查引用 → 真机看朝向与 UV 接缝 |
  914. ### 16. 知识暴露(MCP Resources)
  915. **登记共 293 条**(由 `list_knowledge_resources` 枚举;复核:`node mcp-server/dist/cli.js list_knowledge_resources`)。按 URI 族:
  916. ⚠ **293 条 ≠ 293 条都走 `registerResource`** —— 三条路分开投递,别按「全都能在客户端 Resources 面板里看到」理解:
  917. | 投递路径 | 条数 | 说明 |
  918. | --- | --- | --- |
  919. | `registerResource`(MCP Resources) | **133** | code-patterns 116 + skill 12 + 固定 5 |
  920. | `registerPrompt`(MCP Prompts) | **61** | `mcskill://workflow/*` 另走 prompt 面 |
  921. | **只走工具、不注册** | **99** | `mcskill://community/*` 既无 resource 也无 prompt,只能经 `list_knowledge_resources` / `read_knowledge_resource` 取 |
  922. | URI 族 | 条数 | 内容 |
  923. | --- | --- | --- |
  924. | `mcskill://code-patterns/<平台>/<版本>/NN-<主题>-patterns.md` | **116**(forge 61 / fabric 49 / neoforge 6) | 代码模式库正文,按平台 + 版本分档;供 agent 直接 Read 的片段级范式 |
  925. | `mcskill://community/<sourceKind>/<id>` | **99** | `community_knowledge/` 的可读条目 = `authored` 95 + `permitted` 4;11 条 `links` 只有元数据 + 外链,不进可读条目(索引总数 110 见「社区实务知识」一节) |
  926. | `mcskill://workflow/<模板名>` | **61** | 与 Prompt 同名的工作流正文(与 `get_workflow_template` 同一集合;含 49 开发模板 + 12 编排技能) |
  927. | `mcskill://skill/<技能名>` | **12** | 编排技能正文(`common_skill/mc-*/SKILL.md`;与 `get_workflow_template` 尾部 12 个编排技能同名) |
  928. | `mcskill://matrix/mixin-support` | 1 | mixin_analyze 支持矩阵(SRG/Yarn/Mojang/readable/descriptor 形态) |
  929. | `mcskill://schema/sqlite` | 1 | yarn-mappings.sqlite v2/v3/现批次 v4 字段说明(**须带 `?version=<精确 MC>`**,裸 URI 会被拒) |
  930. | `mcskill://version-changes/1.21` | 1 | 1.21 变更专章(知识库) |
  931. | `mcskill://antipatterns/registry` | 1 | 注册反模式短文 |
  932. | `mcskill://patterns/README` | 1 | 代码模式库索引(`community_knowledge/patterns/`) |
  933. > `code-patterns` 只覆盖 forge / fabric / neoforge 三树(quilt / liteloader / rift / modloader / bedrock 无 `code-patterns/` → 该族 0 条);其中 6 条是 `archived` 旧档,注册在册但 `read_knowledge_resource` 会回 `found:false` + 存档说明,不再给正文。
  934. ### 17. 独立 CLI(`node mcp-server/dist/cli.js`,89 工具全可用)
  935. flags-only(`--key value` / `--key=value` / 裸 `--flag`→true),输出统一 JSON 包装 `{success, tool, result|error}`,退出码 0=成功 / 1=工具错误 / 2=用法错误。全局 flag(不进工具 schema):`--help`/`-h`、`--version`/`-V`(放在工具名之前、或整条命令没写工具名时打印 CLI 版本;`--version` 跟在工具名后面时是工具字段,而 `-V` 在那个位置会被解析成布尔 `version` ⇒ schema 校验失败,exit 2)、`--json`(不改变工具输出,仅为兼容保留;只在交互式终端下影响 `--help` 的呈现)、`--compact`、`--fail-on-error`、`--quiet`(静音进度行与心跳,错误 / 警告 / 迁移提示照旧)、`--timeout <ms>`(到点 exit 1 + `errorKind:"timeout"`,退出码仍不越 0/1/2)、`--project <dir>`、`--file field=path`、`--raw [field]`(该字段完全按字面传,裸写则全局关闭 `@` 展开)、`--output-format json`(表达格式意图的规范入口,当前唯一合法值,其它值 exit 2)、`--stdin-json`(从 stdin 一次读入整个参数对象当基座,命令行同名字段恒胜;TTY 下、以及与 `@-` / `=-` / `--file f=-` 同现时一律 exit 2);所有 string 字段支持文件输入——`--crashReport @./latest.txt` 读文件、`--crashReport=-` / `@-` 读 stdin(全进程一次)、`--file crashReport=./latest.txt` 等价写法,单文件与 `--stdin-json` 载荷共用约 8MB 上限。**加 `--fail-on-error` 时,`found:false` 与 `errors[]` 非空也升为退出码 1**。`--fail-on-error=false` **关闭**该行为(不要把写出 `=false` 当成开启)。布尔 flag 只接受 `true/false/1/0/yes/no/on/off`;`--flag=junk` 拒绝。
  936. > ⚠️ **Windows PowerShell 5.1 控制台坑(E-7)**:PS 5.1 在 GBK 代码页下用管道捕获本 CLI 的 UTF-8 JSON 会引入坏控制字符导致 `JSON.parse` 失败;纯 Node `spawnSync` 管道解析同一输出完全正常。脚本化消费请用 Node 子进程,或先 `chcp 65001`。
  937. ```bash
  938. node mcp-server/dist/cli.js status --version 1.20.1 # 服务器状态(含 buildStatus)
  939. node mcp-server/dist/cli.js query --className net.minecraft.world.entity.LivingEntity --methodName getMaxHealth --version 1.20.1
  940. node mcp-server/dist/cli.js convert --from mcp --to mojang --version 1.20.1 --name getHealth --owner net.minecraft.world.entity.LivingEntity '--descriptor=()F'
  941. node mcp-server/dist/cli.js update --action check
  942. node mcp-server/dist/cli.js list-tools # 全部 89 个工具的 schema
  943. ```
  944. **通用 dispatch(v0.2+)**:除上述命令外,**任意 MCP 工具名可直接调用**(handler 自动收集,缺参时返回 zod 校验提示):
  945. ```bash
  946. node mcp-server/dist/cli.js search_docs --platform forge --query DeferredRegister --version 1.20.1
  947. node mcp-server/dist/cli.js check_dependencies --buildGradle "..." --fabricModJson "{...}"
  948. node mcp-server/dist/cli.js analyze_mod_jar --jarPath <path>
  949. node mcp-server/dist/cli.js get_community_doc_summary --id authored/lib-curios
  950. ```
  951. 旧位置参数形式(`query <className>` / `convert ... <memberName>` 等)仍兼容;PowerShell 括号场景用单引号包裹(如 `'--descriptor=()F'`)。
  952. ---
  953. ## 排障与常见问题(FAQ)
  954. 排障数据分布在下面几张专表里,本节只做索引。
  955. **四类高频症状**
  956. | 症状 | 先查什么 | 去哪 |
  957. | --- | --- | --- |
  958. | MCP 宿主里工具全不可调 | `dist/` 编译了没有?宿主**重载**了没有? | 下节「工具不可用排查」 |
  959. | `PLATFORM_DATA_MISSING` / 某平台数据为空 | `MC_SKILL_DATA` 是否指向本仓库 `data/` | `diagnose_data_paths`,或开 `MC_SKILL_DEBUG_PATHS=1` |
  960. | 查不到某个 API / 类 | 索引覆盖外或简名歧义,**≠** 游戏里没有该类 | 本文「工具边界」的误判对照表 |
  961. | 真机起了游戏但驱动没动作 | 授权双开关 / 失焦暂停 / 存档 `session.lock` 被占 | 本文「后半 loop 运维散件」 |
  962. **按症状跳到本文对应专表**
  963. - 工具返回怪结果、崩溃、参数被误解 → 「工具陷阱」
  964. - 拿不准 `found:false` / `CACHE_MISS` / 空 methods 意味着什么 → 「工具边界」误判对照
  965. - 抓取 / 上游查询失败(TLS、超时、404、代理)→ 「工具与网络边界」
  966. - 装了更新却没生效 → `mc_skill_update` 的 `updateHint`(TTL 1h)+ `get_server_status.buildStatus`(`buildRequired`)
  967. - CLI 输出乱码 / `MODULE_NOT_FOUND`(非 ASCII 路径)→ 「独立 CLI」节的 PowerShell 5.1 坑
  968. - 游玩自测:桥超时 / `scan=0` / 世界不加载 / 关不掉客户端 → 本文「后半 loop 运维散件」
  969. ### 工具不可用排查(clone 后必读)
  970. - **MCP 工具全部调用失败(服务未启动)**:`mcp-server/dist/` 未编译(dist 不入库)。执行 `cd mcp-server && npm ci && npm run build`(Node 需 ≥ 22.5;Yarn 映射可再 `npm run build:yarn-sqlite`)。
  971. - **`get_server_status` 报 `buildStatus.buildRequired=true`**:`src` 比 `dist` 新,需重新 `npm run build`,然后**在宿主里重载 MCP**(只编 dist 不够,宿主进程仍跑旧代码)。
  972. - **反编译类工具报 `TOOLCHAIN_MISSING`**:需 Java 17+(VineFlower / tiny-remapper);装 Temurin 17+ 后重启 MCP,或按返回指引设置 `JAVA_HOME`。
  973. - **`search_mod_code` 报 `NOT_DECOMPILED`**:源码尚未反编译(按设计不入库);先按返回指引调 `decompile_mod_jar` / `get_minecraft_source`。
  974. - **无 MCP 客户端**:用独立 CLI `node mcp-server/dist/cli.js <工具名> --参数=值`(89 工具全可用)。
  975. ## 术语表
  976. | 词 | 含义 |
  977. | --- | --- |
  978. | 人在环(HITL) | 高风险步骤停在清单 / `dryRun` 等用户确认;见「它是什么」一节 |
  979. | `dryRun` / 写盘三态 | 预览(不传 `write`)/ 真写(`write+confirmed`+环境变量齐)/ 被拒(`write_blocked`) |
  980. | 证据三态 | `present` / `absent` / `unreadable`;缺件**不得**读成「没有失败」 |
  981. | `resultKind` | 生成类工具的机读结果:`ok` / `generation_failed` / `write_blocked`(两种失败不得混读) |
  982. | `total` | **本次返回条数**,随传的 `limit` 变;**不是**语料命中总数 |
  983. | `totalPool` / `truncated` | 进输出窗口前本面可用的候选数 / 是否还有页没返回 |
  984. | `semantic` | 本次检索是否走了语义索引;`false` = 退化为关键词(`stale` = 索引过期) |
  985. | `verbatim` | 命中是否为「该标识符在页面正文逐字出现」;缺该字段 = 未判定 |
  986. | `sourceKind` | 社区条目来源:`authored` / `permitted` / `links` |
  987. | `verifiedApi` | 库 catalog 里逐条目核过的 API 键(`gameVersion/loader`) |
  988. | `fallback` / `source_version` | 文档回退时:结果实际来自哪一版 / 是否发生回退 |
  989. | 前半 / 后半 loop | 前半 = 写码→构建→自动起游戏→分诊;后半 = 进游戏游玩→取证→回灌 |
  990. | 测试阶梯(L0–L7) | 交付前的最低测试门槛:L0 构建 → L1 结构静态 → L2 数据 → L3 GameTest → L4 真机冒烟 → L5 场景 → L6 服务端 / 多人 → L7 回归;低层红不许跳高层,最低线按改动面取最大者(缺证据即判红,见「证据三态」)。见根 `AGENTS.md`「游玩测试要求(交付门槛)」 |
  991. | 表外版本 | 不在 `PLAYTEST_VERIFIED_TIER` 里的档:真 driver 出不了,**但仍须测** —— 走桥路线或人工游玩,并如实标注「人工验过 / 未验」 |
  992. | 三通道 | 游玩自测执行权的授权通道(A 仓库沙箱 / B 用户 dev 实例 / C 第三方桥) |
  993. ## 卸载与回退
  994. - **撤除写进用户工程的规则 / Skill**:`activate_platform_pack action=deactivate`(按写入清单撤写);先跑 `action=write` 的 `dryRun` 预览看 `planned` / `willDelete`。
  995. - **撤除游玩自测驱动**:按 `generate_playtest_driver` 生成的 `playtest/REVERT.md` 删驱动文件 + 被测工程里的 `PlaytestQaDriver.register();` 调用行;`git status` 自查应零命中(驱动**绝不**提交)。
  996. - **撤除 CLI / MCP 安装**:`npm uninstall -g mc-ai-coding-assistant-tool`(包名;bin 名是 `mc-skill` / `mc-skill-scripts`,也可直接删对应 bin 链接);仓库 `mcp-server/` 与 `data/` 可直接删(都在仓库内,不影响用户模组工程)。
  997. - **回退自更新**:`mc_skill_update` 只做 git `ff-only` 合并,回退用 `git reset --hard <上一个 commit>`(tooling)或换回上一版 data zip;更新前有未提交改动会被拒(可选 `allowDirty` / `stashDirty`)。
  998. - **缓存与临时产物**:反编译 / MDK / 语义模型产物在 `$MC_SKILL_CACHE`(默认 `%APPDATA%/mc-skill-cache`);删它不影响仓库与用户工程。
  999. ## 阶段里程碑
  1000. | 阶段 | 状态 | 内容 |
  1001. | --------- | ----- | ----------------------------------------------------- |
  1002. | Phase 1 | ✅ 完成 | Forge / Fabric / NeoForge 规则集与多版本扩展 |
  1003. | Phase 1.5 | ✅ 完成 | 模组脚手架 + 校验 CLI |
  1004. | Phase 2 | ✅ 完成 | Agent Skills + 代码模式库 |
  1005. | Phase 3 | ✅ 完成 | MCP Server(文档 + 映射 + 移植 + 社区 + Wave B/C/D 扩展 + 五平台;工具数以 `list-tools` 为准) |
  1006. | Phase 4 | ✅ 完成 | 知识库 / 反模式 / 数据审计与 Release 分发 |
  1007. | Phase 4.5 | ✅ 完成 | **库模组全覆盖**:`lib-*` 短文系列 + 库 Skill 源稿体系(现读 `knowledge/libs/README.md` §当前规模)+ check_dependencies 增强 + 反编译数据链(产物按需生成到 `$MC_SKILL_CACHE` 不入库;`verifiedApi` 键口径见 `CONTRIBUTING.md` §库数据链计数口径)+ API 摘要 + manifest + 通用 CLI dispatch |
  1008. | Phase 5 | 📋 部分 | `inspect_runtime` = 日志型 inspector(非 JVM attach);微调数据集仍暂缓 |
  1009. ## 指针表(外部落点索引)
  1010. 本文正文提到的**外部落点**全部集中在此表(本文内部章节互引不列)。用法:按「内容」查落点;第三列给触发条件与读法。
  1011. | 内容 | 落点 | 什么时候读 / 读法 |
  1012. | --- | --- | --- |
  1013. | 常驻铁律(人在环 / 游玩测试门槛 / 工具边界) | `AGENTS.md` | agent 每轮开工前;「这个档能不能跑 / 桥能测到什么」的已核实边界在 [`doc/glob-search-discipline.md`](./doc/glob-search-discipline.md),**逐版本清单读生成器内 `PLAYTEST_VERIFIED_TIER` 数组**(正文不数档) |
  1014. | MCP 安装与宿主配置(唯一说明书) | [`AUTO_SETUP.md`](./AUTO_SETUP.md) | 装 / 修 MCP 时按它的 Step 走(Step 0-pre 校验路径 → Step 6 装 Skill);开头「Agent 必读:执行顺序」是硬约束 |
  1015. | 工具错误码:实跑取证 + 全工具覆盖清单 | [`doc/tool-error-codes.md`](./doc/tool-error-codes.md) | 收到 `code` / `errorKind` 先按表读;**没实跑取证到的一律不写码** |
  1016. | 被 MCP 目录收录(协议件 / 发布链 / 未核实清单) | [`doc/mcp-registry-publishing.md`](./doc/mcp-registry-publishing.md) | 要发版进官方 registry、改 `server.json` / `glama.json`、或判断「某目录收不收」时;**发布动作由人执行** |
  1017. | 逐批实现史(含门与基线台账) | `mcp-server/CHANGELOG.md` | 查「哪批改了什么、为什么」 |
  1018. | 语料来源 / 换源 / 逐档复测史 | `CORPUS_PROVENANCE.md` | 引用档位覆盖 / 语料计数前先核 |
  1019. | 游玩自测:口径 / 坑位 / 逐轮取证史(§真机台账 = 现行判据 T5 + 历史归档 T0–T4) | `community_knowledge/authored/ingame-playtest-automation.md` | 跑任何一档游玩自测**前**先读;台账里查不到你的 combo ⇒ 按「未验证」处理,**不得**拿邻档外推 |
  1020. | 每轮交付底稿(编号块正文,滚动、最新在上) | `DELIVERY_LOG.md` | 交接 / 夜跑 / 事后抽查;只追加、不改写历史节 |
  1021. | 交付表单(判档 + 主档四块 + 维护档六块 + 受管面清单) | `REPORT-FORMAT.md` | 每轮交付写底稿前;读不到它就按 `AGENTS.md` §交付汇报三件回答并点名「缺表单」 |
  1022. | 维护面夜批回执(滚动) | `NIGHT_BATCH.md` | 夜批队列与晨间抽查 |
  1023. | 债务与拍板台账(批次 / 未排期清单) | `CONTRIBUTING_LIST.md` | 找「已定未做 / 等拍板」 |
  1024. | 发布增量台账(V1.0.4..HEAD 逐条) | 根 `CHANGELOG.md` / `bugfix_list.md` | 发版时搬进 Release 正文 |
  1025. | 贡献 / 验证纪律 / 数据链口径 | `CONTRIBUTING.md` | 改门、改脚本、改受管面文档前 |
  1026. | 作者规范(写给 agent 读的文档) | `WRITING-FOR-AGENTS.md` | 动笔写 / 改 agent 读的文档前 |
  1027. | 社区短文使用纪律(短文**不是** API 规范) | `community_knowledge/AGENT_USAGE.md` | 依据短文写代码前;不确定时先打开短文给出的原文 URL |
  1028. | 社区知识索引(主题速查完整表) | `community_knowledge/README.md` | 找短文入口(发布 / 崩溃 / 软依赖 / 机器 GUI / 本地化…) |
  1029. | 库模组 Skill 源稿(按组映射直读,不落盘) | `knowledge/libs/<组>/mc-<name>/SKILL.md`(总览 `knowledge/libs/README.md`) | 库选型 / 用法;不确定选哪个 → 先读 `all-platforms/mc-lib-catalog` |
  1030. | 工具完整语义(CLI 全局 flag 全表 / 独立 CLI 节 / 工具索引 / 安装配置) | `mcp-server/README.md` | CLI 细节、`npm run` 脚本、MCP 工具面 |
  1031. | mcp-server 补充文档(mixin-support / vanilla-registries / registry-data-source / mc-skill-update / prompts-client-compat) | `mcp-server/docs/` | 字节码校验矩阵 / Registry 数据源 / 自更新 / Prompt 兼容等专题 |
  1032. | 人类读本(多 IDE 同步清单、人话版上手) | `README_human.md` | 给人看的入口;英文版 `README_human.en.md` |
  1033. | 第三方文档与映射的许可说明 | `THIRD_PARTY_NOTICES.md` | 分发 / 许可问题 |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.