MC AI Coding Assistant Tool

写在前面的

如果你是 agent

本文件是项目总说明。安装与配置 MCP 请读 AUTO_SETUP.md；本文的配置章节是同一内容的副本，用于兜底没读 AUTO_SETUP.md 的情况。

如果你是人类

请读人类读本；需要细节可以直接让 agent 讲解。
English | 简体中文 · 人类读本

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

为 AI 提供一个「读懂 MC Mod 开发生态」的环境，消除知识陈旧、API 版本混淆、构建系统复杂、映射不一致等结构性障碍。

为 AI 提供一个完整的端到端的的全流程开发环境,提供完整的编写,测试模组的开发环境

它是什么：AI 帮你干活，你只用明确创意与取舍

模组开发不是确定性流水线。创意设计（做什么内容）、性能权衡、调试策略必须由人判断，Agent 不代劳；版本兼容取舍与 API 选择你无法拍板时可以代劳 —— 低风险的，做完就按「解释模板」（见「快速开始」一节）说明取舍、替代方案与回退方法；高风险的（换加载器、改包结构、删依赖、改构建脚本），动手前先说明并等你确认。
Agent 负责版本门禁、文档检索、规则/反模式、骨架草稿、校验与崩溃分诊等。

下列高风险操作默认停在清单或 dryRun，必须有人在环（先展示、经用户确认后再做）：写盘、运行 Gradle、拷贝 jar 到游戏目录、上传发布。

项目结构

MC_skill/
├── README.md                    # 你在这里
├── AGENTS.md                    # 根总纲：引导 AI 选择正确的平台规则
├── CONTRIBUTING.md              # 贡献指南
├── AUTO_SETUP.md                # 任意 MCP 宿主：编译 + 按宿主格式生成配置草稿
├── REPORT-FORMAT.md             # 交付底稿全量表单（agent 用：判档 / 主档四块 / 维护档六块 / 硬约束）
├── DELIVERY_LOG.md              # 每轮交付底稿正文（滚动，最新在上；聊天只给人看三件）
├── THIRD_PARTY_NOTICES.md       # 第三方文档 / 映射数据许可说明
├── LICENSE                      # 本仓库代码：MIT
├── Minecraft 社区常用库模组全览（2026 版）.md  # 跳转指针；正文在 community_knowledge/authored/library-catalog-2026
│
├── forge/                       # Forge 规则 / skills / scaffold / knowledge（多版本）
├── fabric/                      # Fabric 规则与知识（多版本）
├── neoforge/                    # NeoForge 规则与知识
├── quilt/                       # Quilt QSL 差异规则（02–10 读同版 fabric）
├── liteloader/                  # LiteLoader（主推 1.12.2）+ HYBRID.md
├── rift/                        # Rift 1.13.2
├── modloader/                   # Risugami ModLoader 1.6.4 + 安全 API 表
├── bedrock/                     # 基岩 Add-On 规则（扁平 bedrock/）
│
├── doc/                         # 落点台账（工具错误码：实跑取证 + 全工具覆盖清单 + tier 快照）
├── community_knowledge/         # 社区实务知识库 → MCP search_community_docs
│   ├── authored/                # 自写短文（含 48 篇 lib-* 库集成 + 发布/崩溃/GUI 等）
│   ├── permitted/               # 许可入库的社区帖提炼（如 mcmod 3993）
│   ├── links/                   # 仅标题 / 摘要 / 外链（如 mcmod 6071）
│   ├── patterns/                # 代码模式示范（mcskill://patterns/README）
│   ├── indexes/index-l0.json    # L0 索引（实测 110 条：authored 95 / links 11 / permitted 4；含 generatedAt 构建时间戳）
│   ├── AGENT_USAGE.md           # Agent 用法规则（短文不能当 API 规范）
│   └── README.md                # 主题 id 速查
│
├── knowledge/                   # 仓库级知识源稿（不落盘到平台 .cursor/skills）
│   ├── libs/                    # 库模组 Skill 源稿：36 份 / 34 唯一 skillId
│   │   ├── all-platforms/       # 20（含 mc-lib-catalog 路由中枢）
│   │   ├── fabric-only/         # 10（Trinkets / CCA / Polymer…）
│   │   ├── forge-only/          # 2（Curios / KFF）
│   │   ├── neo-only/            # 2（Curios / KFF 镜像）
│   │   ├── bedrock-only/        # 2（Script API）
│   │   └── README.md            # 分组规则、解析流程、数据链指针
│   └── patterns/                # 短片段模式库（与 community_knowledge/patterns 互补）
│
├── scripts/                     # 维护脚本（库数据链 + skill 同步 + 规则校验）
│   ├── sync-skills.ps1          # 多 IDE skill 镜像（-All / -TargetDir）
│   ├── resolve-lib-skills.mjs   # knowledge/libs §3.6 解析校验
│   ├── （库 catalog 脚本在 mcp-server/scripts/，见下）
│   ├── build-lib-manifest.mjs   # → mcp-server/data/lib-manifests/
│   ├── build-api-summaries.mjs  # → mcp-server/data/lib-api-summaries/
│   ├── batch-decompile.mjs      # 分批反编译（源码 → $MC_SKILL_CACHE，不入库）
│   └── merge-verified-api.mjs   # 回填 catalog verifiedApi
│
├── mcp-server/                  # 本地 stdio MCP Server（86 个工具）
│   ├── src/                     # 工具实现（api / docs / diagnostics / wave…）
│   ├── scripts/                 # 文档抓取、语义索引、数据审计；含 build-library-catalog-from-authored.mjs
│   └── data/                    # 随仓分发的 MCP 侧数据（非 MC_SKILL_DATA）
│       ├── lib-manifests/       # Modrinth 版本矩阵（49 slug / 3003 条目）
│       ├── lib-api-summaries/   # 48 库 public API 摘要
│       └── loader-api-summaries/ # Forge/Neo/Fabric-API/QSL 类摘要
│
└── data/                        # 离线官方数据（MC_SKILL_DATA 指向此处根）
    ├── forge_* / fabric_* / neoforge_* / …  # 各平台文档 L0/L1/L2 + semantic/
    └── mappings/                # 分平台版本目录（Yarn SQLite、MCP CSV 等），不是单一扁平文件

平台版本目录内另有 .cursor/rules/（00–10）、.agents/skills/、scaffold、knowledge/antipatterns 等；库 Skill 只在根 knowledge/libs/，经 activate_platform_pack 或按路径 Read，不写进各平台 skills 目录。

平台说明

平台	状态	规则 / 数据（摘要）
Forge	✅ 完成	多版本规则（主推 1.20.1）；数据目录 `data/forge_`*
Fabric	✅ 完成	多版本规则（主推 1.20.1 / 1.21.x / 26.x）；数据目录 `data/fabric_`；26.1+ 仅 mojmap*
NeoForge	✅ 完成	规则集在 `neoforge/`（主推 1.20.4+ / 26.x）；文档数据见 `data/neoforge_`（主文档默认 26.1；26.2 / 26.3 走迁移指南*，见「支持版本」表注）
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
基岩版	✅ 完成	扁平 `bedrock/`；`search_bedrock_docs` + 滞后 `docsStatus`；实验开关按 `min_engine_version` 分层
LiteLoader	✅ 完成	`liteloader/1.12.2/` 纯客户端 + `HYBRID.md`；`diagnose_gradle` 对 liteloader 插件走轻量模式
Rift	✅ 完成	`rift/1.13.2/`（`code-patterns/` 3 件 + `knowledge/common/` 4 篇）；元数据 `riftmod.json`；Rift 侧签名已对真构件 `javap` 核过（`verified-api.md`，39 个 listener 接口全量表），MC 侧未核；依赖走 JitPack `com.github.DimensionalDevelopment:Rift:1.0.4-106`（`dev` classifier；原 `www.dimdev.org/maven/` 已 DNS `ENOTFOUND`）
ModLoader	✅ 完成	`modloader/1.6.4/` + 安全 API 表；禁止用 Forge Javadoc / `func_*` 冒充

支持版本

规则树（activate_platform_pack action=list）与官方文档数据（list_*_versions）可能不一致：有规则无文档、或有文档无完整 00–10 规则均属正常。Agent 须以工程精确版本为准，禁止用邻档顶上。

平台	规则树（`平台/<ver>/`）	文档数据（`list_*_versions`）	主推	备注
Forge	`1.7.10` · `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）。`forge/1.21.1` 为 draft（无完整规则树，`PACK_NOT_FOUND`；仅改口文档搜索）
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`	`list_fabric_versions` 含上述档（无 1.21.5）	1.20.1 / 1.21.x / 26.1.2	`26.1.2` 仅 `fabric-docs`、无 wiki；26.1+ 仅 mojmap。`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` 规则里是负例，不是空洞），禁止抄邻版
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`	`1.20.1`（回退 Forge）· `1.20.4` · `1.20.6` · `1.21.1`–`1.21.11` · `26.1`	1.20.4+ / 26.1	主文档默认 26.1；26.2 / 26.3 走迁移指南（见表注）。`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 标注
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"})`	随 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`
LiteLoader	`1.8.9` · `1.10.2` · `1.12.2`	`search_docs({platform:"liteloader"})`（官方 wiki + hybrid 语义库；API 以核实表为准）	1.12.2	`1.8.9` / `1.10.2` 为 draft（`PACK_NOT_FOUND`，只能走 `search_docs`）；纯客户端；与 Forge 混合见 `HYBRID.md`
Rift	`1.13.2`	`search_docs({platform:"rift"})`（官方 wiki + hybrid；方法名以核实表为准）	1.13.2	方法名只来自已抓 wiki/源码
ModLoader	`1.2.5` · `1.5.2` · `1.6.4`	无 Java 文档树	1.6.4	`1.2.5` / `1.5.2` 为 draft（`PACK_NOT_FOUND`，禁止用 `1.6.4` 顶替）；只用 safe-api 表；禁止 Forge Javadoc
基岩版	扁平 `bedrock/`（`*`）	`search_bedrock_docs` + `docsStatus`	按 manifest	无 `平台/<ver>/` 分档；实验开关按 `min_engine_version`

MC 26.2 / 26.3 怎么支持：本仓库没有这两档的规则树与文档（list_*_versions 也不含）；支持方式 = 官方 26.1 → 26.2 → 26.3 迁移指南（get_migration_guide 的 route="26.1->26.2" / "26.2->26.3"，源 = NeoForge Primer），配合 analyze_porting_path。官方文档发布后同步补档。

查询本机已建档列表：node mcp-server/dist/cli.js activate_platform_pack --action=list；文档档：list_forge_versions / list_fabric_versions / list_neoforge_versions / list_doc_versions。

快速开始

对 AI（打开一个 MC Mod 项目时）：

按根目录 AGENTS.md 判断平台与精确版本，然后调用 activate_platform_pack action=session 加载该档规则 / Skill 索引（不要直接读邻版 平台/<ver>/.cursor）。官方文档先 list_*_versions，再把 version 写死成工程版本去 search_*_docs / search_docs。创意设计由用户拍板；兼容取舍 / API 选择默认也由用户决定，用户不想或没能力决定时可代劳，但必须按下方「解释模板」说明（模板已同步写入根 AGENTS.md「人在环」节，对 Agent 强制生效）；写盘 / Gradle / 拷 jar / 上传须确认后再做（人在环，不是无人值守流水线）。

解释模板（代劳决策时的强制说明格式）

权威文本在根 AGENTS.md「代劳决策解释模板」。本节是同结构副本 —— 改任一处必须同步 README.md / README.en.md / AGENTS.md 三处（暂无机器门，靠人工守）。

先判风险，再决定什么时候开口：

这一代是什么性质	什么时候说	等不等回复
低风险：某个 API 写法、某个依赖版本	做完就说，写在同一轮回复里	不等
高风险：换加载器平台、改包结构、删依赖、改构建脚本	动手前说	等用户回复
用户已说「不用问我，直接做」「你决定就行」	做完就说	不等，但必须给回退方法

说明必须含五要素，按此顺序，一段只讲一件事：

选择了什么 —— 写名字和版本。例：Forge 1.20.1 的 SimpleChannel。
为什么这样选 —— 只写与当前版本或用户工程实况有关的理由。「业界惯例」不算理由。
替代方案与未采用的原因 —— 一到两个，每个一句。
影响与风险 —— 用户因此要检查什么、注意什么。
怎么回退 —— 改哪几处、改回什么。

第一行照这个格式开头：

我已替你选择使用 DeferredRegister，原因见下。

每条出处必须能核对：给 search_*_docs 的命中页 id 或 URL、规则编号、或官方文档链接，三者之一。查不到就写 // TODO(未核实)，不得凭记忆补名字，不得只写「最佳实践」。

语言跟着用户走：用户说「不太懂技术」或「你决定就行」，就讲结果、少堆术语（例：「这样写以后升级 Forge 时要多改两处」）；用户是专业开发者，就给类名、方法签名、文档链接。两种写法都要满足上面的五要素与出处要求 —— 换的是措辞，不是内容。

完整示例（照形状写，事实按你的版本重查）：

我已替你选择使用 SimpleChannel，原因见下。

网络包注册用 Forge 1.20.1 的 SimpleChannel（NetworkRegistry.newSimpleChannel）。

你的加载器是 NeoForge 1.20.1，它是 Forge 兼容层，官方文档仍只给 SimpleChannel（出处：search_neoforge_docs version=1.20.1 命中页 1.20.1/networking_simpleimpl，该页正文逐字含此名）。

另一条路是 CustomPacketPayload + IPayloadRegistrar：这一套从 NeoForge 1.20.4 起才有文档页（networking/payload 在 1.20.1 返回 DOC_NOT_FOUND），你的版本用不了。

影响：代码在编译期依赖 net.minecraftforge 包，请确认工程已含该依赖。

回退：改动只在你自己的网络注册类（官方文档示例命名 ModidPacketHandler）；日后升到 1.20.4+ 时，把该类的 channel 建法换成 payload 注册即可。

对新项目使用脚手架：

使用对应平台版本下的 scaffold/（如 forge/1.20.1/scaffold/）生成带规则的项目骨架。

多 IDE 同步：

修改 .cursor/ 后，在该版本目录运行 sync-skills.ps1。

配置本地 MCP Server：

将 AUTO_SETUP.md 拖入当前 AI IDE / CLI。Agent 应识别宿主（Cursor / Claude Code / VS Code / Continue / Trae / OpenCode / Codex 等），编译 mcp-server，按该宿主格式生成配置草稿，经你确认后合并（不会静默覆盖）。
要求 Node.js >= 22.5（22.5–22.12 与 23.0–23.3 必须加 --experimental-sqlite 启动——内置 node:sqlite 在 22.13 / 23.4 起才默认开启；MCP/CLI 入口会在任何 sqlite 使用之前检测该窗口，命中即打印醒目指引并以非零码退出）；服务名 MC-AI-Coding-Assistant-Tool（stdio，86 个工具）。无 MCP 客户端时用 node mcp-server/dist/cli.js。

模组测试流程 loop：两段

真机测试拆成两段 loop，覆盖面不同：

段	loop 内容	覆盖面	承载
前半	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`）
后半	自动起游戏 → 进游戏自己操作、测试 → 拿证据回传 → 改码 → 再测试	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`

两条路线：

无桥（进程内 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 + 截图。
有桥（第三方桥 mod）：预编译桥 mod（当前 = BlackBoxPro，MIT）装进游戏实例，经 127.0.0.1:38081 用 playtest_bridge 发动作/查询/截图；证据 = calls.jsonl + 截图 + query 响应。桥件的 MC 覆盖由第三方发布决定（BlackBoxPro 现行件覆盖 fabric/neoforge 1.21.1 与 1.21.11、forge 1.12.2）。

证据判读统一入口：inspect_playtest_evidence（三态 present|absent|unreadable，缺件不得读成“没有失败”）；执行权与授权见根 AGENTS.md「人在环例外：游玩自测（三通道）」。

测试要求：交付前必须测到什么程度

上面的 loop 是机制，本节是交付门槛：改动不以编译通过为交付，交付前必须测全。逐层「用什么工具、红会长什么样」的完整表在根 AGENTS.md「游玩测试要求（交付门槛）」，本节是其摘要。

阶梯（低层判红即不得进入高层）：L0 构建 → L1 结构与静态校验 → L2 数据面（配方 / 战利品 / 标签 / 方块状态 / lang）→ L3 GameTest 自动化 → L4 真机冒烟 → L5 场景验收（本次改动那个玩家可见行为）→ L6 服务端与多人 → L7 回归与共存 → 发布前收口。

最低线按改动面取最大者：

改动	最低测到
逻辑 / 注册	L3（GameTest）
玩家可见行为（方块 / 物品 / 实体 / GUI / 配方效果 / 世界生成）	L4 + L5
网络 / 存档 / 服务端侧	L6
升 loader 或 MC 版本	L0–L7 全跑
纯文档 / 注释	L0

「全面」指把维度铺开，不是同一条路径重复多遍：改动面（代码 / 资源 / 数据 / 配置 / 平台元数据）、平台 × 版本（每个目标档各测一遍，不得用邻版结果顶替）、客户端与服务端双侧、新世界与旧存档升级、权限档（生存 / 创造 / 授权）、边界与异常（空满背包、目标方块不存在、区块未加载、死亡与重连、非房主加入）、表现面（模型与纹理、GUI 溢出与缩放、en_us 与 zh_cn 每个键都有值）、日志面（latest.log 无新增 ERROR、crash-reports/ 为空；基岩看 content log）。

判红（fail-closed）：缺证据 = 没通过。absent 不等于「没有失败」；exit-code.txt 非 0 或不在盘上 ⇒ 红。真 driver 覆盖 = 生成器内 PLAYTEST_VERIFIED_TIER（唯一真源，正文不数档），表外版本不等于免测 —— 走桥路线或人工游玩，并如实写「人工验过 / 未验」。MC_SKILL_PLAYTEST_INTENT_E2E 未设 ⇒ 按未验证处理，不静默通过。

与人在环的边界：门槛规定「必须测」，不改变「谁去跑」—— 跑 Gradle、起游戏仍受三通道授权约束。没拿到授权就在交付里写明「本轮未真机验证」，并把上面这张清单交给用户照着跑，不得替用户宣布通过。

后半 loop 教程：三条路线，逐步跑通

本节回答"从零怎么把游戏跑起来、让 agent 在里面自己玩并留下证据"：三条路线逐步走 + 运维散件集中在这里。跑前必读的真机台账与能力边界见文末「指针表」。

三条路线怎么选：

路线	driverMode / 工具	覆盖	适合	主要代价
① 有桥	桥 mod + `playtest_bridge`	BlackBoxPro 预编译件（fabric/neoforge 1.21.1+1.21.11、forge 1.12.2）或本仓自建最小桥（8 目标 = `forge 1.7.10–1.12.2` + `rift 1.13.2` + `modloader 1.6.4`，`generate_playtest_driver driverMode=external_bridge` 附赠；rift 是真模板，modloader 只到骨架）	到手最快、动作集大	版本覆盖窄；自建桥动作 10 个、按档 fail-closed；桥无鉴权 ⇒ 只本机短会话
② 无桥剧本	`generate_playtest_driver driverMode=temporary_client_tick_driver`	已验证档出真 driver；其余档结构壳	确定性回归 / CI 复现	要装驱动 + 供世界
③ 无桥意图会话	`driverMode=in_jvm_player_agent` + `playtest_intent`	真执行器覆盖 = `PLAYTEST_VERIFIED_TIER`（生成器内表，随取证扩面，正文不数档；表外档只出菜单契约 + 结构壳）	agent 实时决策、"选错→判红→换意图"	观测粒度 = 每条意图一次；v1 `goto` 无寻路

路线 ① 有桥（最快）

授权：MC_SKILL_PLAYTEST_ALLOW=1 + MC_SKILL_PLAYTEST_ROOT=<绝对路径>（三通道与禁令见根 AGENTS.md「人在环例外：游玩自测」）。
装桥：BlackBoxPro 对应端 jar + 依赖（fabric 端需 fabric-api 与 FLK）；来源/版本/sha256 记账，jar 只进授权根。
起游戏 → 探活：playtest_bridge action=status ⇒ ready=true 才算"已进世界"（actions 每档不同：1.21.1 实测 114、1.21.11 116）。
进世界：execute create_world / join_world —— 建世界要几十秒，响应超时 ≠ 失败（实测超时后世界里其实已建好）。
驱动：动作序列由 generate_playtest_driver driverMode=external_bridge 出（playtest/actions.json + 后置条件 + 证据约定）；单步 execute，复合动作 batch + delay，"等条件"用 await（桥没有 wait_until；超时映射 PLAYTEST_TIMEOUT，不得塌成"没失败"）。
判读：inspect_playtest_evidence（三态 present|absent|unreadable）+ calls.jsonl + 截图；失败 → 改码 → mc-build-mod 重建 → 重跑。

路线 ② 无桥剧本 driver（面最广）

建工程：把对应档 scaffold 拷到 <ROOT>/<平台>-<版本> —— 工程目录即游戏根（run/ 就是 gameDir，不改 runDir DSL）。JDK 分线：1.20.1 线 JDK 17、1.21.x 线 JDK 21。
关失焦暂停（必做）：<gameDir>/options.txt 写 pauseOnLostFocus:false —— 否则按键位移恒 0.00（强杀进程时 MC 不会自己写这份文件，得手建）。
生成驱动：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();。
供世界：<gameDir>/saves/<存档名>/level.dat 必须存在 + allowCommands=1（/locate 等 cmd 类步骤需要）—— 做法见下面「运维散件」。
跑：gradlew build → gradlew runClient；日志里程碑 [QA] driver registered → [QA] open world requested → [QA] ROUND 1 START → [QA] DONE :: / [QA] ERROR:。
热载：改动作/断言/坐标只改 <evidenceDir>/plan.txt（同一进程内开新一轮，不重启游戏）；只有 driver/被测 mod 的 Java 源码变了才重建重启。
判读 + 撤除：同路线 ① 的判读；收工按 playtest/REVERT.md 删驱动与调用行（绝不提交）。

路线 ③ 无桥意图会话（agent 实时下意图；详细）

与路线 ② 的关系（两条不是并行系统）：同一个驱动、同一个解释器；意图只是"展开成原语子计划"的步骤，外层剧本退化成一条 waitintent 守候环。同一 tick 只有一个计划在跑。

前置：同路线 ② 的 1–2 步＋ 已验证档（真执行器覆盖 = PLAYTEST_VERIFIED_TIER，唯一真源、随取证扩面——正文不数档；表外档只出菜单契约 + 结构壳，不会假装能跑）。
进世界：按该档配方 —— 冻结族（fabric 1.20.4 / 1.21.1 / 1.21.3）用 vanilla quick play（build.gradle 的 loom runs 加 programArgs "--quickPlaySingleplayer", "<存档名>"）且 enterWorld 留空；1.21.11 线可直接 enterWorld:"<存档名>"。
生成：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。
装 + 跑：同路线 ②；到 [QA] ROUND 1 START 后，进世界的第一条 waitintent tick 会把 state.json（观测面）补种出来。
观测（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）。
下意图（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。
会话循环：read 看观测 → 选意图（失败就按 nextSteps 换）→ write → driver 消费（intent.json 改名 intent.done.json）→ 展开原语执行 → 判唯一一条类型化后置条件 → 写 intents[] + 刷新 state.json → 回守候。失败不得自动重试（一次性意图重试会重复消耗方块/触发副作用），只许换意图。
收尾：write {"intent":"stop"} ⇒ 收尾本轮（不关游戏）；之后按 playtest/REVERT.md 撤除。

两条运维口径（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 的「意图空间 · 执行器落地面」节（入口行在文末「指针表」）。

失败语义（三条线里最要紧的差别）：邮箱形态失败 = 数据（intents[] 记 ok:false ＋ failure 字段）并继续守候（会话不死）；协议违规（禁列/不在菜单/档位不符）在写侧就被工具拒；脚本形态（plan.txt 里的 intent 步骤）失败 = 判红停轮。

预算与协议：单意图上限 = 菜单 budgetTicks 列（walk_to 1200 / find_and_goto 9000 / 其余 60–600）；单次守候 5 min（waitintent max=6000）；整轮默认 30 min（budgetTicks=36000）；邮箱单槽（一条在跑时新写的只在邮箱等，再写会被拒）。参数写错（如 x=abc）判红 param_not_number，不会静默用默认值。

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 格；村内扫不到村民先怀疑废弃村（换个村再扫）。

四会话真机读数（quilt 1.21.11 / operator：换意图链、实体 / 方块正例、截图 ageMs 新鲜度判据、walk_to{x:abc} 负例，四条全 exit-code=0）见上文「意图空间 · 执行器落地面」节（同一口径单源）；逐档矩阵与现行判据见文末「指针表」的游玩自测行（§真机台账 = 现行判据 T5 + 历史归档 T0–T4）。

后半 loop 运维散件（散在各处，集中在这里）

事项	做法
JDK 分线	1.20.1 线 JDK 17；1.21.x 线 JDK 21（`JAVA_HOME` 指到对应版本；旧线可加 `-Porg.gradle.java.installations.paths=<jdk17>`）
授权	`MC_SKILL_PLAYTEST_ALLOW=1` + `MC_SKILL_PLAYTEST_ROOT=<绝对路径>`；证据与驱动只留该根
失焦暂停	`<gameDir>/options.txt` 写 `pauseOnLostFocus:false`（强杀后 MC 不会自己写；只有这一行也能跑）
世界供给	用同 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）
进世界（冻结族）	`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`
资源卡住	首跑 `:downloadAssets` 失败/长时间无输出：ForgeGradle 与 Loom 的 assets 缓存可互借；缺件按官方 manifest → `assetIndex.id` → `indexes/<id>.json` 定位对象 → 比大小补件；坏件（截断）用真实例 `assets/objects/xx/<hash>`（内容寻址、同路径）覆盖
首跑死在 mixin prepare	`fabric 1.20.1 / 1.20.4 / 1.21.1` 的老 clone：scaffold 的 `filesMatching` 补 `examplemod.mixins.json`（已在库修）
关客户端	精确杀真身 JVM（命令行含 `-Dfabric.dli.config` 的那个 `java`）；只杀 `gradlew` wrapper 不够 —— 残留客户端会占存档 `session.lock`，下一轮进世界报"另一个程序已锁定文件的一部分"
独立实例	每次运行用独立 runId / 独立实例（共用 runDir 会静默互相覆盖截图）
证据判读	`inspect_playtest_evidence`（三态；缺件不得读成"没有失败"）；`rounds.jsonl` 每行一条合法 JSON（条目 `{intent,params,ok,postcondition
撤除	删驱动文件 + `register()` 调用行，证据只留授权根；`git status` 自检零命中 —— 绝不提交

社区知识与库模组

与 data/ 下的官方 Forge/Fabric/NeoForge 文档分离，本仓库另有两套实务知识，供 Agent 在「发布 / 崩溃 / 软依赖 / 库选型 / 依赖树」等场景使用。二者都不替代 search_*_docs 或 query_api。

社区实务知识（`community_knowledge/`）

目录	含义	Agent 注意
`authored/`	本仓库自写短文（可改）	实务清单与反模式，不是 API 规范
`permitted/`	作者许可入库的社区帖提炼	仍不确定时打开原文 URL
`links/`	仅标题 / 摘要 / 外链	禁止把网页正文当已入库全文

索引：indexes/index-l0.json（约 110 条）。MCP：list_community_sources → search_community_docs → get_community_doc_summary / get_community_doc_full。环境变量 MC_SKILL_COMMUNITY 可改根路径。

主题速查：发布 / 崩溃 / 软依赖 / 机器 GUI / 本地化 / 代码模式（patterns/）等。库集成另有 48 篇 authored/lib-*.md + 总览 library-catalog-2026、陷阱 lib-traps-2026、配方集成 library-integration / library-integration-jei-emi。

强制规则：依据社区短文写代码前，若方法名 / 版本细节不确定，必须先查短文给出的原文或官方文档。

库模组知识体系（`knowledge/libs/` + 数据链）

三层结构（详见下文 MCP 工具 §7 / §7.5）：

社区短文 — authored/lib-*.md，经 search_community_docs 检索；含反编译验证小节（verifiedApi 来源）。
库 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。
数据链 — 短文 frontmatter → mcp-server/scripts/build-library-catalog-from-authored.mjs → library-catalog.ts（50 条 / 2632 verifiedApi 键）+ lib-manifests/all.json（49 slug / 3,003 版本条目，口径 = 该文件顶层数组的 length = slug 数、各元素 entries 数组长度求和 = 版本条目数）+ lib-api-summaries/（48 库 API 摘要）→ check_dependencies 识别依赖与版本窗口。（计数口径与脚本位置见 §7.5）

Agent 推荐路径（库相关）：check_dependencies（看 detectedLibraries）→ search_community_docs（lib-<name> 或 library-catalog-2026）→ 按 skillId 或名称 Read knowledge/libs/.../SKILL.md → 仍缺签名再走 search_*_docs / query_loader_api。

环境变量

常设（多数用户会碰到的）

变量	说明	示例
`MC_SKILL_DATA`	数据目录根路径（指向 `data/`，不含版本子目录）	`<仓库根>/data`
`MC_SKILL_COMMUNITY`	社区知识库根路径（默认仓库根 `community_knowledge/`）	`<仓库根>/community_knowledge`
`MC_SKILL_ALLOW_WRITE`	`1` 时允许 `port_project` 写盘	`1`
`MC_SKILL_PROJECT_ROOT`	写盘允许的项目根（绝对路径）	`<你的模组工程绝对路径>`
`MC_SKILL_STRICT`	`1` 时数据无效则 MCP 启动失败	`1`
`MC_SKILL_DEBUG_PATHS`	`1` 打印路径解析过程（诊断“找不到 data/”时先开它）	`1`
`MC_SKILL_CACHE`	反编译/MDK/loader-jar 缓存根。MCP 与脚本都读此变量；不设则 MCP 默认 APPDATA、脚本默认 `os.tmpdir()/mc-skill-cache`，会分家	`%APPDATA%/mc-skill-cache`（脚本回退 `os.tmpdir()/mc-skill-cache`）
`JAVA_HOME`	反编译 / remap 用的 JDK（需 17+；缺失 ⇒ 工具回 `TOOLCHAIN_MISSING`）	`<Temurin 17+ 安装目录>`
`MC_SKILL_PLAYTEST_ALLOW`	`1` 时放开游玩自测三通道的授权闸（须与 `MC_SKILL_PLAYTEST_ROOT` 成对出现）	`1`
`MC_SKILL_PLAYTEST_ROOT`	游玩自测授权根（绝对路径；目标 realpath 必须落在其内）	`<授权实例存档根>`
`MC_SKILL_SKIP_DOWNLOAD`	`1` 时反编译工具跳过一切下载并诚实失败。须显式设成逐字 `1` 才生效（实现是严格比较 `=== "1"`，见 `mcp-server/src/decompile/java/java-process.ts:168`；不设或设 `true` 均不生效）。本仓 `.github/workflows/` 四支工作流均已设该变量（实测）	未设（默认按需下载）

进阶 / 排障（按需；多数场景不必设）

变量	说明	默认 / 示例
`MC_SKILL_JAVA_SCAN_MAX_FILES`	`validate_project` 等 Java 源码扫描的文件上限	`300`
`MC_SKILL_JAVA_TIMEOUT_MS`	反编译子进程超时毫秒数（非法值忽略并下沉）	内建回落值
`MC_SKILL_SCRIPT_TIMEOUT_MS`	CLI 侧脚本子进程超时毫秒数（不设 = 不设超时，长跑不被误杀）	未设
`MC_SKILL_MAX_ENTRY_BYTES`	解压时单条目未压缩大小上限（防 zip 炸弹）	`268435456`（256 MB）
`MC_SKILL_MDK_CHECKSUMS`	MDK 校验和 pin 文件路径覆盖	`mcp-server/data/mdk-checksums.json`
`MC_SKILL_BEDROCK_API_PIN`	基岩 Script API pin 文件路径覆盖	`mcp-server/data/bedrock-script-api-pin.json`
`MC_SKILL_FETCH_BACKEND`	设 `curl` 时 GitHub 抓取改走系统 `curl.exe`（Node TLS 失败时的逃生口）	未设（先试 Node，失败回落 curl）
`MC_SKILL_GITHUB_API_BASE`	GitHub API 镜像基址（同时被加入抓取 host 白名单）	未设（`api.github.com`）
`MC_SKILL_GITHUB_TIMEOUT_MS`	GitHub 请求超时毫秒数	内建回落值
`MC_SKILL_GITHUB_TOKEN` / `GITHUB_TOKEN`	自更新 / 上游查询的 GitHub token（提速率、免匿名限流）	未设
`MC_SKILL_UPDATE_REPO` / `MC_SKILL_UPDATE_REMOTE`	自更新仓库 slug / 强制 git remote 名	`guguzea/MC-AI-Coding-Assistant-Tool`
`MC_SKILL_UPDATE_CACHE_TTL_SEC`	自更新检查缓存 TTL（秒）	`3600`
`MC_SKILL_UPDATE_DOWNLOAD_TIMEOUT_MS`	自更新下载超时毫秒数	`600000`
`MC_SKILL_UPSTREAM_CACHE`	设 `0` 整体关掉 `query_upstream_releases` 磁盘缓存	未设（按档 TTL）
`HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`（含全小写）	抓取的代理	未设
`APPDATA`	Windows 下缓存根默认基址（`MC_SKILL_CACHE` 未设时）	系统值
`NODE_OPTIONS`	Node 22.5–22.12 / 23.0–23.3 需含 `--experimental-sqlite`	未设（22.13+ / 23.4+ 无需）
`MCP_TIMEOUT_MS`	测试/CI 侧超时毫秒数（`test-mcp.mjs` / `release-smoke.mjs` / 四支 CI 工作流读它；MCP 服务进程本身不读）	`30000`

上表覆盖对用户有行为影响的面，非穷尽：服务端源码实际读取 37 个环境变量名，其余为内部调试开关。要拿全量清单，扫 mcp-server/src/** 的 process.env.* 即可（MC_SKILL_STRICT / MC_SKILL_DEBUG_PATHS 属本表已列；ComSpec / COMSPEC 等为 spawn 细节，无需配置）。

MCP 工具使用注意

本地 MCP 服务名：MC-AI-Coding-Assistant-Tool（86 个工具）。配置时请使用 绝对路径 + 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）。

测试：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，全量档（权威名单跑时现取）：入口契约探针 + 真实调用 + 逐条豁免原因，不默认跑）。

安装后验收与 npm 脚本速查

装完（或首次 clone）后，跑下面四条确认环境是对的；全绿再往下走：

(cd mcp-server && npm ci && npm run build)    # dist/ 不入库，必须自建
node mcp-server/dist/cli.js --version                    # 应打印版本号（当前 package.json = 2.0.0）
node mcp-server/dist/cli.js list-tools --names-only      # 应回 86 个工具名
node mcp-server/dist/cli.js activate_platform_pack --action=list   # 应回本机已建档的平台 / 版本
node mcp-server/dist/cli.js diagnose_data_paths          # 各平台应为 found；empty / not_found = MC_SKILL_DATA 没指对

MCP 宿主里工具全不可调 ⇒ 多半是 dist/ 未编译或宿主未重载（装了新 dist/ 也要重载 MCP）。排查清单见下节「工具不可用排查」。

cd mcp-server 后的常用脚本（完整 35 条以 mcp-server/package.json 为准）：

脚本	用途	何时跑
`npm run build`	`tsc` 编译到 `dist/`	改源码后；跑 MCP/CLI 前
`npm ci`	安装依赖	首次 clone（仓库/Release 不含 `node_modules`）
`npm test`	全量门链（构建 + 单测 + 各 `assert-*.mjs` 门）	提交前
`npm run test:core`	核心单测（含规则加载 / 兼容注释钉子）	改了 core / 规则加载
`npm run test:cli`	CLI 契约单测（参数解析 + 信封 + 退出码）	改了 CLI 入口 / 信封 / 退出码
`npm run test:cli:quick` / `test:cli:full`	CLI 快档（已进默认门链）/ 全量档（不默认跑，权威名单跑时现取）	改了 CLI
`npm run test:scripts`	`mcp-server/scripts/**` 门链	改了脚本 / 门（收口必跑）
`npm run test:audit`	数据审计单测	改了 `data/` 或审计器
`npm run test:semantic`	语义索引单测	重建语义库后
`npm run test:decompile` / `test:deep-mixin`	反编译 / deep mixin（需 JDK 17+）	改了反编译 / 字节码校验
`npm run test:update`	自更新单测	改了 `src/update/`
`npm run build:yarn-sqlite`	重建 Yarn 映射 SQLite（`--all`）	首次 / 换档后；用 `convert_mapping` 前
`npm run fetch:embedding-model`	下载本地嵌入模型	首次建语义索引前
`npm run build:semantic-index`	重建语义索引（`npm run … -- --all`）	要离线 / 语义检索时
`npm run build:vanilla-registries`	重建 Vanilla Registry 数据（`-- --version=<v>`）	改了 `query_registry` 数据
`npm run audit:data`	全平台数据一致性审计（任何 ERROR = 不宜发布）	发布数据包前
`npm run audit:data:forge` / `:fabric` / `:neoforge` / `:fail-on-error`	单平台 / 全平台失败即错	只改了一个平台时
`npm run community:index`	重建社区 L0 索引（`--write`）	增删 `community_knowledge/` 条目后
`npm run smoke:release`	发布冒烟	打包前

其余脚本（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。

两个一等公民入口：MCP 与 CLI

同一条 core、两个适配器（互不分叉）：MCP（stdio，给 AI 宿主）与 CLI（终端 / 脚本，给人）。前提与 MCP 相同：Node ≥ 22.5 + cd mcp-server && npm ci && npm run build（CLI 跑 dist/）。

入口一：工具线（= MCP 工具，全量可调）

node mcp-server/dist/cli.js --version
node mcp-server/dist/cli.js list-tools --names-only                    # 工具名清单
node mcp-server/dist/cli.js list-tools --tool resolve_lib_skills       # 单工具 schema
node mcp-server/dist/cli.js search_docs --platform fabric --version 1.21.1 --query registry
node mcp-server/dist/cli.js resolve_lib_skills --platform fabric --mcVersion 1.21.1
node mcp-server/dist/cli.js check_dependencies --project .
node mcp-server/dist/cli.js crash_analyze --crashReport @./crash-reports/latest.txt

参数约定：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。参数名按各工具 schema（如 resolve_lib_skills 用 --mcVersion；拿不准先 … <工具名> --help）。
输出：恒定 JSON 包装 {success, tool, result|error}；退出码 0=成功 / 1=工具失败或超时（errorKind: tool_failure | timeout）/ 2=用法错误（usage | validation）。
工程类工具：--project <dir> 映射 projectPath；--fail-on-error 把 found:false / 非空 errors[] 升为退出码 1。

入口二：仓库线（维护侧脚本子命令）

node mcp-server/bin/mc-skill-scripts.mjs --help                 # 命令总表
node mcp-server/bin/mc-skill-scripts.mjs lib resolve --platform fabric --version 1.21.1
node mcp-server/bin/mc-skill-scripts.mjs lib resolve --validate # 逐组合解析校验（组合清单以脚本内 VALIDATE_COMBOS 为准；= test-core §S15 同一门）
node mcp-server/bin/mc-skill-scripts.mjs lib summary --only libgui --write
node mcp-server/bin/mc-skill-scripts.mjs lib ownership          # G1 库归属门
node mcp-server/bin/mc-skill-scripts.mjs corpus decompile --filter slug=cloth-config,jei
node mcp-server/bin/mc-skill-scripts.mjs corpus merge --input x.jsonl --dry-run
node mcp-server/bin/mc-skill-scripts.mjs cloth project          # 注入标记 ↔ versions.json 校验
node mcp-server/bin/mc-skill-scripts.mjs gate list
node mcp-server/bin/mc-skill-scripts.mjs gate run lib-ownership # 跑一道门（退出码透传）

九个命令 = lib resolve|summary|ownership · corpus decompile|emit|merge · cloth project · gate list|run；
薄壳：转发 scripts/ 与 mcp-server/scripts/ 的既有脚本，参数与退出码原样透传；… <组> <命令> --help 给命令说明（脚本自带参数的 --help 走直跑脚本）；
边界：CLI 需在仓库内运行（脚本位于仓库根 scripts/ 与 mcp-server/scripts/）；仓库线属维护侧作业（批量反编译 / 摘要重建 / G1 门 / 注入回填），MCP 工具面不暴露。
冒烟门：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。

库模组文件保持 AI 直接可读：knowledge/libs/** 是"源稿即用"——AI 按 AGENTS.md「库模组 Skill」规则直接读文件；resolve_lib_skills（MCP 与 CLI lib resolve 同一 core）只做解析与真值提示（返回仓库相对路径 + versionsJson），不代替文件、不缓存正文。

向量 / 语义搜索（T1）

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 表示该次检索用上了语义库。

三档降级（缺什么就退一档，不报错、不造数据、运行时不远程拉模型 allowRemoteModels=false）：

档	条件	行为
`hybrid`	有 `semantic/db.sqlite` 且 embeddings 非空，且 `data/_models/Xenova/all-MiniLM-L6-v2` 就绪	L0 + 向量 + FTS5，RRF 融合
`fts5-only`	有语义库但嵌入模型缺失，或 embeddings 表为空	全文关键词（FTS5），不再算向量
`l0-only`	该版本/数据源没有语义库（`semanticSearch` 返回 `null`）	只匹配 L0 索引字段（`label` / `id` / `url` / `tags`）；结果 `semantic: false`，并带 warning

全局 get_server_status.semanticIndex.modeHint 是本机总体档位（有任一 hybrid 树且模型就绪 → hybrid）。单次查询仍可能是 L0：例如 Forge 1.7.10 没有教程语义库。看该次 JSON 的 semantic 与 warning，不要只看 modeHint。

构建期缺模型：警告并降级 FTS5-only（不 exit 1）。diagnose_data_paths.semantic 报告各文档树旁 db 是否存在。

数据与模型位置：语义库在 data/{platform}_{ver}/{source}/{ver}/semantic/db.sqlite（跳过 forge_javadoc），当前 61 个（实算：find data -type f -name db.sqlite -path "*/semantic/*"；不含 db.sqlite.tmp-* / -journal 残渣，forge_javadoc 树本就没有语义库）；嵌入模型在 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；可中断续跑）。产物清单：data/semantic-index-manifest.json。

Agent 怎么调用（两条入口、两步走、一个字段）

入口 A：MCP 工具（AI IDE 已挂 MC-AI-Coding-Assistant-Tool 时，这是 Agent 的正规调用方式）。按平台选工具，参数只有 version + query，语义层自动参与、没有任何开关：

Forge → search_forge_docs { version: "1.14.4", query: "entity goal" }
Fabric → search_fabric_docs { version: "1.21.4", query: "custom enchantment effect" }（先 list_fabric_versions 确认入库档名）
NeoForge → search_neoforge_docs { version: "1.20.1", query: "..." }（1.20.1 回退 Forge 语料，属预期）
通用（quilt / liteloader / rift / modloader 等）→ search_docs { platform: "...", version: "...", query: "..." }

入口 B：独立 CLI（无 MCP 客户端，或想在 shell 里立刻验证——改完源码没重载宿主时也用它）：

node mcp-server/dist/cli.js search_forge_docs --version=1.14.4 --query="entity goal selector"

（MC_SKILL_DATA 指向 data/；工具输出恒为 JSON，--json 不改变工具输出。）

两步走：search_*_docs 拿结果里的 id（不是网站 URL）→ get_*_doc_full / get_*_doc_summary 读正文。一次最多 2 页，防止上下文溢出。

响应契约：{ 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 字段：

semantic: true = 该次检索走语义库（FTS5 BM25 + MiniLM 向量余弦、RRF 融合），命中可视为按相关性排序的 coverage 证据；
semantic: false = 降级 L0 关键词（该树没建语义库 / 嵌入模型缺失 / semanticSearch 返回 null），带 warning——此时命中不穷尽，found:false 什么都不能证明；
命中可带 matches[]（sectionHeading / snippet / score），snippet 来自 chunks 表真实正文，可直接引用。

Agent 侧规矩（根 AGENTS.md「不确定时」条款）：查 API / 文档 / 机制先语义搜索；query_api / query_loader_api 是兼容工具（见下节），只作兜底。

query_* 兼容工具与 1.14.4/1.15.2 边界报告

query_api / query_loader_api 被标记为兼容工具（类名/签名索引类，覆盖按版本而异且有限）。每次调用的响应都显式提醒，不再静默：

query_api 每次响应：notes 末尾追加「query_api 是兼容工具……文档与语义面请优先 search_forge_docs / search_docs 语义搜索」。
query_api 查 1.14.4 / 1.15.2：warning 显式报告边界——这两档 api-index 为空是设计行为（MCP stable CSV 仅成员级 searge↔named，Parchment 索引自 1.16.5 起才有），found:false 不代表游戏里没有该类；响应推荐改用 search_forge_docs 语义搜索（这两档语料与语义库完整：1.68MB / 1.32MB，实测 semantic: true）+ convert_mapping（1.14–1.15 CSV 仅 searge↔named，类名不可查，方法名可以）。背景：这两档旧版原先被通用分支静默返回（未报边界），sweep104 补上专门分支。
query_loader_api 每次响应：notes 追加兼容注释（覆盖以已 ingest 的档为界）。
第二档出处 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。

钉子：test-core.mjs（1.20.1 兼容注释 / 1.14.4 与 1.15.2 边界 warning / 1.12.2 数据健康（不再有空壳警告） / S1′ 三腿：接线（1.21.1 StatusEffect 给得出 nameIndex 且 found:false）、证伪（乱造的名字必须 exists:false）、披露（三句 note 缺一即红）+ 无库档 26.1.2 与命中路径 1.20.1 都不得出现 nameIndex）与 test-loader-api.mjs（兼容注释）。

文档查询（Forge / Fabric / NeoForge）

页面 ID 必须用搜索结果里的 id，不要用网站 URL 路径。

正确：get_fabric_doc_full({ id: "1.20.4/develop_items_first-item", version: "1.20.4" })
错误：id: "items/first-item"

推荐流程：search_*_docs →（可选）get_*_doc_summary → get_*_doc_full。
搜索默认 hybrid（见上一节）。只有降级到 l0-only 时才「只匹配索引字段」。
前缀查询示例：class:Item、event:lifecycle。
NeoForge 1.20.1 文档查询会回退到 Forge 1.20.1 视图（兼容层），属预期。
若某平台数据包未下载，对应 list/search 会返回 PLATFORM_DATA_MISSING（可用 diagnose_data_paths 确认）。
先 list_*_versions / list_doc_versions，确认本机有该版再搜。search_forge_docs 与 search_docs({ platform: "forge" }) 走同一套 Forge 索引。
按版本选工具（不要用 query_api 顶官方文档）：

目标	文档搜索	Vanilla / 映射	平台 API
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 类）
Forge 1.7.10–1.11.2	无教程规则树；落到 `forge_javadoc` / `search_docs`，`semantic: false`	同上（SRG 类名 + `func_/field_` 成员名，无 javadoc）；不要用它核签名	无 loader 摘要（`search_loader_api mode=list` 的 `noIngest`）
Forge 1.13.2	`search_forge_docs` / javadoc	SRG 类名与成员名可列（无 Parchment javadoc）	`1.13.2-forge` 已索引
Forge 1.14.4 / 1.15.2	`search_forge_docs`（语义库完整，1.68MB / 1.32MB，实测 `semantic: true`——查这两档优先用语义搜索）	`query_api` 索引为 `{}`（0 类，设计边界——每次查询响应带边界 `warning` 并推荐语义搜索，见「向量 / 语义搜索」节；类名在文档语料里逐字可引，见 sweep103 验证）	`*-forge` 已索引
Forge 1.16.5–1.20.4	`search_forge_docs`	Vanilla 可用 `query_api`（真方法签名）	`query_loader_api` 或文档
Fabric	先 `list_fabric_versions`；禁止把邻版 wiki 当本版。26.1.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` 的 fabric-api 已索引（不要再当成 maven 404；*11 档 = 14 个 `fabric/` 规则树 − 薄档 `1.21.4` / `1.21.8` / `1.21.10`**）
Quilt	`search_docs({platform:"quilt"})`；问 QSL 禁止把 Fabric Registry 当命中	同左版本的 Vanilla 边界	QSL 摘要见 `mode=list`（如 `1.19.4-qsl` / `1.21.1-qsl`）
NeoForge	先 `list_neoforge_versions`。`1.20.1` 回退 Forge 文档（兼容层）	26.1+ 无 `query_api`	`*-neoforge` 多档已索引
LiteLoader / Rift / ModLoader	`search_docs`。LiteLoader/Rift 有官方 wiki hybrid 语义库；ModLoader 仍为 L0-only	`convert_mapping` / 反编译	仓库内核实表仍是 API 准绳；未 ingest → `PLATFORM_SKIPPED`。用户自备 jar 走 `ingest_loader_api`（默认 dryRun）
基岩	`search_bedrock_docs`（带 `docsStatus`）	无 Java `query_api`	`validate_addon_manifest` / `validate_bp_json`，不是 `validate_project`

查询用类名或短词（Block、class:RegistryEvent）。失败先换短查询或改走 search_docs，不要把崩溃/空结果当成「该版没有文档」。
改完 mcp-server 源码后：npm run build，然后在宿主里重载 MCP。Cursor 里正在跑的进程不会自动换成新 dist/；用 node mcp-server/dist/cli.js 才能立刻验证。

工具陷阱（实测，同类问题）

下表现象都出自索引 / 查找写法或文档过时，不代表游戏里没有该类：

现象	实际	Agent 应做
`search_*_docs` 查 `constructor` 抛 `abbr is not iterable`	`ABBREV_EXPAND[query]` 命中 `Object.prototype.constructor`	已改为 `Object.hasOwn` / `ownGet`。若 MCP 仍崩 → 重载服务
`get_version_info({version:"constructor"})` 返回 `undefined。注册流程：DeferredRegister…`	`VERSION_DB["constructor"]` 是 Function	未知 version 必须 `forgeVersion=unknown`，禁止套 1.20 注册流程
`get_migration_guide({route:"constructor"})` `found:true`	自由字符串查 `MIGRATION_GUIDES[key]`，命中 Function	已 `ownGet`，必须 `found:false`
`get_workflow_template({name:"constructor"})`	MCP schema 是工作流名 enum（Zod 直接拒）；函数层仍要 `ownGet`	不要把校验失败理解成「没有工作流系统」
`query_api` 1.12.2 `Block` `found:true`	3344 个类名，其中 3256 类含成员（`func_/field_` 混淆名，无参数名/javadoc）	看 `warning` / `notes`；改 `search_forge_docs` / `query_loader_api`
`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
`get_version_info` 1.12.2 action=register 仍教 DeferredRegister	gotchas 写「不支持」，recommendation 被强行追加 1.20 流程	1.12.2 注册是 `RegistryEvent.Register<T>`
`search_loader_api` 对 Fabric 1.14.4 等返回空	文档曾写 maven 404 / `LOADER_API_NOT_INDEXED`	以 `mode=list` 为准；`skipped-ingest.json` 的 `mavenNotIndexed` 现为空数组
文档 `semantic: false` 或 warning 含 `stale`	故意 L0-only（仅 ModLoader 三档），或 sqlite 落后于 processed/	看该次 JSON，不要只看 `get_server_status.semanticIndex.modeHint`

同类查找一律走 ownGet（mcp-server/src/utils/own-record.ts），不要写 record[userString]。

规则包加载（`activate_platform_pack`）

知识库里的 forge/<ver>/.cursor 不会被用户模组工程的 IDE 扫到。编码期用 MCP 把该档送进当前对话，不要把规则拷进 MC_skill 仓库根。

`action`	作用
`list`	已建档平台 / 版本
`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/`。
`write`	写入用户模组工程的 IDE 目录。`hosts` 必填（`cursor` / `claude` / … / `all`）。默认 `dryRun`。不要再用 `includeSkills`，改用 `writeSkillStubs`（二者都未传时默认 true，写入 stub，提示去读知识库路径，不是 Skill 全文）。`includeSkillBodies` 才写全文。目标不能是本知识库（整棵仓库树均拒绝，含版本子目录）。破坏性变更（2026-08）：设置 `MC_SKILL_PROJECT_ROOT` 时它是硬边界——`projectPath` 必须落在其内，否则拒绝（`PATH_OUTSIDE_ALLOWLIST`，响应带 `breakingChange: true` 与 `allowRoot`）；此前 `projectPath` 可覆盖 env。迁移：把 env 指向包含目标工程的目录，或改用其内的 projectPath。
`deactivate`	按清单撤写

不能开关 Cursor/Claude 等 Skill 扫描器。重载 MCP 不会让设置页出现条目。

工具边界

文档向量搜索 补不了 Vanilla 方法签名。缺索引时保持 found:false / 空结果 + 说明，

情况	表现	Agent 应改用
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`
Forge 1.14.4 / 1.15.2 `api-index.json`	占位 `{}`，Parchment 约从 1.16.5 才有。每次 `query_api` 查询都会报此边界并推荐 `search_forge_docs` 语义搜索（sweep104；这两档 docs 语料与语义库完整）	换 `version=1.16.5+` 查相近 Vanilla 名，或靠文档 / MCP 映射，不要当有完整 javadoc
Fabric 26.1.2	仅 `fabric-docs`（页数少），无 `fabric-wiki`	`source` 保持默认 `fabric-docs`；不要把 1.21.x wiki 当 26.1.2
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_` 名当完整签名
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
`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 含「检查可能不完整」）
`get_server_status.updateHint` 显示有更新	可能是检查缓存过期	以 `mc_skill_update action=check` 为准；git describe 已超前 Release 则不必 apply

Agent 不得把「工具返回空 / found:false / warning」解释成「游戏或文档里不存在」，也不得用错平台的工具硬查。对照：

误判	实际边界
`query_api` 能查 `DeferredRegister` / Fabric API	不能。只含 Vanilla Parchment extracted（约 1.16.5–1.20.4）。平台 API → `query_loader_api`（必填 platform+minecraftVersion）或对应 `search_*_docs`
`query_api` 能查 Forge 1.12.2 `Block` 构造	不能当 javadoc。该版无 Parchment 方法条目，只有 SRG 类名与 `func_/field_` 成员名。改 `search_forge_docs` / `query_loader_api` / `convert_mapping`
`search_forge_docs` 报错或空 = 该版无文档	先 `list_forge_versions`。1.12.2 有教程树。查询词 `constructor` 曾因原型键崩溃，已修；若仍崩则重载 MCP。失败换短查询或 `search_docs({platform:"forge"})`
`query_api` `found:false` = 类不存在	索引没有该类、简名歧义（`Handler` 不会命中 `MouseHandler`），或 `action.code=DATA_UNAVAILABLE`（该版无 extracted / Worker 未就绪）。26.1+ 收录 0 类；1.14.4/1.15.2 空 `{}`。1.12.2 有 SRG 类名索引（成员名为 `func_/field_` 混淆名）。改文档搜索或 `get_minecraft_source`
`get_method_params` 覆盖所有 MC 版本	与 `query_api` 同一数据源，边界相同
`get_version_info` 适用于 Fabric/NeoForge	仅 Forge
`diagnose_gradle` 能修 Loom / NeoGradle	覆盖 ForgeGradle + Loom + NeoGradle/MDG；Rift / BaseMod / 基岩仍早退。liteloader 插件走轻量模式
`validate_project` 能校验 `fabric.mod.json`	Fabric/Quilt/NeoForge 真检查；LiteLoader/Rift/ModLoader/基岩仍 `skipped`。基岩用 `validate_addon_manifest`
`query_registry` 能查模组注册名	只查原版 `minecraft:` 资源 ID
文档搜索为空 = 数据包坏了	可能是 L0 降级、标签不对、或该版无 wiki。看 `semantic` / `warning`
用网站 URL 当 `get_*_doc_full` 的 `id`	必须用搜索结果里的 `id`
`search_community_docs` 可当官方 API	不能。`links` 条目不抓网页正文
`port_project` 会改用户工程	默认 dryRun；真写需 `confirmed` + `MC_SKILL_ALLOW_WRITE` + 路径在 `MC_SKILL_PROJECT_ROOT` 内
工作流 / MCP 不跑 Gradle、不拷 jar、不上传 = 漏做无人值守	人在环设计。创意、性能、调试由人决定；兼容取舍 / API 选择可代劳但须按「解释模板」说明；高风险操作须确认后再执行
`analyze_porting_path` 对任意文件夹都有移植路径	非模组目录 → `NOT_A_MOD_PROJECT`；LiteLoader / Rift / ModLoader / 基岩 → `UNSUPPORTED_PORT`
`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.4+ Attachment；fabric/quilt 改口 CCA
`localize_mod` 会自动译成中文	无机器翻译，只标 `needsTranslation`
`check_dependencies` = 完整 Gradle 解析	启发式 + library-catalog，会漏未收录库
`mixin_analyze deep:true` 会下载 MC jar	不会。未缓存 → `CACHE_MISS`，先 `get_minecraft_source`
`search_mod_code` 能搜任意 jar	须先 `decompile_mod_jar`（或已有反编译目录），否则 `NOT_FOUND`
`analyze_mod_jar` 会给出方法体	只解析元数据（toml/json/mixin 列表），不反编译
`convert_mapping` / `lookup_obfuscated` 用于 26.1	返回 `UNOBFUSCATED_NO_YARN`（已去混淆）
`validate_datapack_json` 覆盖所有 pack_format	精简 schema，偏 1.20.1 / 1.21.1
`get_*_doc_full` 一次拉很多页	最多 2 页，避免上下文溢出
`updateHint.available` = 必须更新	缓存可能过期；先 `mc_skill_update check`
缺 26.2 / 26.1.2 wiki 就复制邻版	禁止克隆冒充
`DOC_NOT_FOUND` / 规则树空壳就抄邻版 API	禁止。保持未核实 stub，不是漏写

写模组时的选用顺序：平台规则（AGENTS.md）→ search_*_docs（平台 API）→ query_api（仅有索引的 Vanilla）→ 反编译（确实要源码）。不要反过来用 query_api 猜 Forge 事件名。

工具与网络边界（只写边界，不写结论）

下列两条本机核不到上游本身（能核的只有通道，见下表）。这里登记的是「不许推出什么」，不是「已核实为否」。

边界	已核实到的程度	禁止的推断
外网可达性只能核到本机通道层面，不是「通 / 不通」一个布尔	`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` 或「缺档」。相关条目保持「未核实」标注，换网络或让用户在本机复验，不要改成另一套自猜的值
基岩 `description.identifier` 等命名空间 ID 的长度上限与字符集	Microsoft Learn 只规定要带命名空间，未给出长度上限与允许字符集；社区只给「小写、无空格/特殊字符」「路径长度受主机限制」这类建议	不要把建议当硬限制，也不要因 Learn 没写就断言「无限制」。`validate_addon_manifest` / `validate_bp_json` 不据长度/字符集报错；生成 ID 时按建议取保守形式并说明这是约定不是官方约束

fetch 通道矩阵（写维护脚本时按这张表选腿；任一腿失败推不出「这台机器没网」）：

腿	本机实测	用法
Node `fetch`（github / gradle / maven 域）	一律 `TLS_VERIFY_FAILED`	不得当主腿；失败必须归 TLS 类，与 404 / 限流分开
`curl.exe --ssl-no-revoke` GET	`200` / `307`（本机唯一稳定可用腿）	win32 主腿。冷连接首试可能超时（实测一次 15s 零字节），必须带退避重试
`curl.exe --head`	同一 URL 跨轮实测 `502` 与 `200` 都出现过	禁止用 HEAD 判可达性，探测一律 GET
`api.github.com`	实测 `git/trees?recursive=1` 单次超时	需要它建表时先单独复验；不能假设与 `raw` 行为一致

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 互不混用）。

映射转换（`convert_mapping` + Yarn）

走预建 yarn-mappings.sqlite（现批次 schema v4，含 fields；v2/v3 旧库仍可读）惰性点查，运行时禁止全量加载 yarn-mappings.json。
支持矩阵（摘要）：

版本区间	数据源 / era	类互转	方法互转	字段互转	备注
1.16+（有 Fabric tiny）	`yarn-tiny`	✅	✅ 需 `ownerClass`；重载建议 `descriptor`	✅ `memberKind=field`	`to=mojang` = Tiny official 短名
1.13 Forge	`tsrg` + MCP CSV	✅	✅ 可带 `ownerClass`	✅ + `fields.csv`	`joined.tsrg` + CSV
1.7–1.12 Forge	`forge-srg` + MCP CSV	✅	✅ 可带 `ownerClass`	✅ + `fields.csv`	`joined.srg` + CSV
1.14–1.15	`mcp-csv`（partial）	❌	仅全局 `searge↔named`	仅全局 `field_*`	勿传 `ownerClass`

mcp↔parchment 为同名层（identity）；参数名用 get_method_params。
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 可用）。
字段查询：传 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 ...。
失败默认 found:false、converted:null；过渡参数 allow_fallback 可回传原名并设 fallbackUsed（禁止假成功）。
构建：cd mcp-server && npm run build:yarn-sqlite（本地 temp 写入后复制，避免盘符 I/O 问题）。
from=mojang（拿 mojmap 可读名来查）有两档出处：第一档 = 上表的 official 列，而那一列对被混淆的类存 Tiny 混淆短名，只有本来不混淆的少数类带可读全路径（13 档 100 985 行实测：短名 100 310 ／可读路径 675 = 0.67%，如 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 直接拒答，不回落第一档。

工作流模板与知识资源（Prompts / Resources + 工具兜底）

Cursor 主路径是 tools；协议层仍注册 Prompt/Resource，工具兜底保证同款正文可读：

能力	工具	说明
工作流	`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/`（普通文档待遇，不进受管门）
知识列表	`list_knowledge_resources`	列出 `mcskill://` URI
知识读取	`read_knowledge_resource`	按 URI 读正文

常用 URI：mcskill://patterns/README（→ community_knowledge/patterns/README.md）、mcskill://schema/sqlite、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- 前缀条目，登记由盘派生）。

移植分析（`analyze_porting_path`）

平台识别综合源码与构建/元数据（build.gradle、mods.toml、fabric.mod.json 等）。空目录 / 无构建也无元数据 → ok:false + NOT_A_MOD_PROJECT（不是 platform: unknown）。

输出契约：targetPlatform 必填（未指定 → INVALID_INPUT，不做静默默认）；routeSteps 始终是给人读的 string[]；机器可读交接是并行的 nextSteps[]，每项 { text, tool?, args? }，其中 tool + args 必须能直接调用（必填参数齐备、无占位值），填不齐就只给 text。port_project 按 nextSteps 续跑。

写操作（`port_project`）

默认只读。真正写盘需要同时设置 MC_SKILL_ALLOW_WRITE=1 与 MC_SKILL_PROJECT_ROOT=<允许写入的项目根>，且目标路径必须落在该根目录下。

数据复现与分发

data/ 中的索引和文本由 mcp-server/scripts/ 生成。大型 *.jar / *.zip 默认被 .gitignore 排除（data/** 有例外保留规则），不要假定 Git 一定含全部二进制。

只从脚本声明的官方来源重建数据。
运行 cd mcp-server && npm run audit:data；任何 ERROR 表示数据包不宜发布。
完整数据包可通过 GitHub Release 的 mc-skill-data-full-*.zip + SHA256SUMS-*.txt + data-manifest.json 分发。
本地原始包丢失时应重新 fetch，不要跨版本复制改名。

目录约定

平台按 平台/版本/ 分目录（如 forge/1.20.1/、fabric/1.20.1/）
规则文件在 .cursor/rules/，编号 00~`10`
每个规则含约束与 Decision Flow

规则文件说明

文件	主题	说明
`00-project-setup.mdc`	项目结构	Java / Gradle / 版本号
`01-registry.mdc`	注册系统	按版本选择注册方式
`02-block.mdc`	方块	方块 / 方块实体 / 流体
`03-item.mdc`	物品	物品 / 工具 / 盔甲 / 食物
`04-entity.mdc`	实体	EntityType / Renderer / Goal
`05-events.mdc`	事件	按场景选事件类
`06-networking.mdc`	网络	同步需求 → 包类型
`07-datagen.mdc`	DataGen	Provider 选择
`08-client-server.mdc`	端分离	代码放哪侧
`09-anti-patterns.mdc`	反模式	症状与正确方案
`10-gui.mdc`	GUI	Menu / Screen / Container

Agent Skills（35 个 Forge 唯一名 + 平台扩展，多 IDE 镜像）

路径示例：forge/1.20.1/.agents/skills/<name>/（另有 .cursor / .continue / .opencode / .zcode 等宿主镜像）。Wave D 新增 skill 曾用 scripts/_oneoff/propagate-wave-d-skills.mjs 同步（一次性，勿再跑），日常镜像用 scripts/sync-skills.ps1 -All。

库模组 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 不再包含库项。当前库源稿（现扫 find knowledge/libs -name SKILL.md）：all-platforms 20 + fabric-only 10 + forge-only 2 + neo-only 2（Curios/KFF 镜像）+ bedrock-only 2 = 36 份 / 34 唯一 skillId（口径：份数 = 各组 mc-*/SKILL.md 数；唯一 skillId 按目录名去重与按 frontmatter name: 去重同数 34，差额来自 mc-curios / mc-kotlin-for-forge 在 forge-only 与 neo-only 各一份镜像）。与本文 §7.5「② 库 Skill 源稿」行及 knowledge/libs/README.md「当前清单」一致。

平台/版本	数量	结构	说明
`forge/1.12.2`–`1.20.4` 主档	35	目录（每 skill 一目录）	15 核心 + 19 Wave D + `mc-events`（2026-08 D-1 补齐；1.7.10 为诚实 stub）
`forge/1.15.2` / `forge/1.17.1`	35 / 34	目录	1.17.1 有 `mc-events`、无 `mc-capability`（与 1.20.1 集合不同）
`forge/1.7.10`	3 规则 + 3 技能	目录	仅 00/01/09 + `mc-item` / `mc-registry` / `mc-events`（stub：无 05 规则，事件 API 未核实禁止生成）
`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 技能顶替
`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 顶上
`fabric/`（14 档*，骨架全档同数；26.1.2 为 Mojmap）	38	`.md` 文件（薄档/26.1.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 为 Mojmap，禁止 Yarn）。薄档 `1.21.4`/`1.21.8`/`1.21.10` 的规则 11 条 + Skill 38 项与其余 11 档完全同数（实测（`readdir <pack>/.cursor/rules` 计 `.mdc`、`.cursor/skills` 计条目）：fabric 全部 14 档均为 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"` 与这一自述不矛盾——判据取盘上实测、不取本句自称（2026-09-08 裁定「薄档即声明」）
`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
`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
`liteloader/<ver>`（1.8.9 / 1.10.2 / 1.12.2）	3	目录	`mc-events` / `mc-gui` / `mc-networking`（LiteLoader 专用口径，非 Forge API）
`rift/1.13.2`	3	目录	`mc-events` / `mc-gui` / `mc-networking`
`modloader/1.6.4`；`modloader/1.2.5`、`1.5.2`	2；1	目录	1.6.4：`mc-item` + `mc-registry`；其余仅 `mc-registry`（safe-api 表外禁止输出）
`bedrock`	10	目录（×7 IDE 镜像）	Script API / manifest / 资源与行为包等，见 `bedrock/.cursor/skills/`；不钉版本号，live docsStatus

分类	Skills
核心	`mc-registry`、`mc-block`、`mc-item`、`mc-blockentity`、`mc-entity`、`mc-mixin`、`mc-networking`、`mc-datagen`、`mc-capability`、`mc-gui`
内容	`mc-fluid`、`mc-particle`、`mc-sound`、`mc-recipe`、`mc-enchantment`、`mc-potion`、`mc-effect`、`mc-command`、`mc-villager`、`mc-ai`
渲染 / 模型	`mc-renderer`、`mc-model`
世界 / 数据包	`mc-worldgen`、`mc-structure`、`mc-advancement`、`mc-loottable`、`mc-datapack`、`mc-resourcepack`、`mc-dimension`、`mc-weather`
配置 / 测试 / 能源	`mc-gametest`、`mc-energy`、`mc-multiblock`
兼容 / 文档库	`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` = 33 库类 + `mc-compat-jei` = 34 唯一 skillId（36 份源稿；现扫 `find knowledge/libs -name SKILL.md` = 36、目录名去重 = 34，份数差 = `mc-curios` / `mc-kotlin-for-forge` 在 forge-only 与 neo-only 各一份镜像 ⇒ 唯一 skillId 只多数一次。口径与本文「项目结构」的库 Skill 源稿行、「工具陷阱」表的 validate_datapack_json 行、「工具参考 §1b」的 query_loader_api 行，及 `knowledge/libs/README.md` §当前规模一致）→ `knowledge/libs`）

Fabric 另含 mc-fabric-api、mc-kotlin、mc-cloth-config；Forge 1.12.2–1.20.4 与 Fabric 主档均含 mc-events（2026-08 D-1 补齐，经 FABRIC_SKILL_DONORS 回填的薄档带 DONOR_SKILL 横幅）。代码模式示范见 community_knowledge/patterns/（也可经 mcskill://patterns/README 读取）。

MCP/CLI TOOLS:86

服务名：MC-AI-Coding-Assistant-Tool。

推荐通用流程：

diagnose_data_paths / list_*_versions / get_server_status 确认数据与版本
文档：search_* → get_*_summary → get_*_full（全文勿一次超过 2 页；id 必须来自搜索结果）
平台 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 索引，见上文「规则包加载」）
映射：convert_mapping / lookup_obfuscated（26.1+ 无混淆层）
工程：diagnose_gradle / validate_project / generate_datagen / crash_analyze / analyze_build_log / inspect_runtime（日志型）。Forge/Fabric/Quilt/NeoForge 跑对应检查；LiteLoader/Rift/基岩的 validate_project 仍 skipped
移植：analyze_porting_path →（确认后）port_project（默认 dryRun）
社区 / 库模组：实务与库选型 → search_community_docs（lib-* / library-catalog-2026；遵守 AGENT_USAGE.md）→ Read knowledge/libs/.../SKILL.md（先 mc-lib-catalog）；check_dependencies 看 detectedLibraries
工作流 / 知识：get_workflow_template / list_knowledge_resources → read_knowledge_resource

工具限制与误判对照见上文「工具边界」。

1. API 与映射 / 状态（6）

工具	作用
`query_api`	查询 Vanilla/Parchment 类的方法签名、参数名、返回类型与 javadoc（按 `version` 加载 extracted 索引，必填 version，禁止默认 1.20.1）。不含 Forge 特有类。覆盖约 1.16.5–1.20.4。1.7.10–1.12.2 为 SRG 名（`func_/field_`），无参数名/javadoc；1.14.4/1.15.2 / 26.1+ 无可用方法索引。精确 FQCN 或唯一简名（如 `Item`）才 `found:true`（改写时带 `autoCorrected`）；`Handler` 等歧义子串 `found:false` + suggestions。平台 loader API 用 `query_loader_api`。
`get_method_params`	按类名 + 方法名查询完整参数名列表（可带 JNI `descriptor` 区分重载）。多重载未传 descriptor → `found:false` + `ambiguous` + `candidates`。26.1+ 无索引 → `DATA_UNAVAILABLE`。
`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`），只有本来不混淆的少数类带可读全路径（13 档 100 985 行实测：短名 100 310 ／可读路径 675 = 0.67%）⇒ 拿 `Container`／`Level` 这类 mojmap 可读名点查必然 `found:false`，不得读成「该版本没有这个类」；第二档 = 派生对照表 `data/_yarn-mojmap-pairs/`（类名级 `obf`／`mojmap`／`yarn` + 两侧 FQCN，无 intermediary 列），只在 `from=mojang` 且 `to` 为 `yarn`／`obfuscated` 时参与，命中带 `fallbackUsed:true` 且 notes 点名表与条数，`to=intermediary` 直接拒答不回落第一档。
`lookup_obfuscated`	崩溃日志反混淆：单 token（`method_6032` / `er` / `func_110143_aJ` / `field_100013_f`）反查 → yarn 可读名 + ownerClass + descriptor。方法→字段→类；多命中 AMBIGUOUS；26.1+ 返回 `UNOBFUSCATED_NO_YARN`。
`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`）。
`get_version_info`	【Forge only】按 MC 版本 + 操作（如「注册方块」）给出推荐做法、关键变更、gotchas 与官方 Changelog 链接。

1b. Loader API 与平台包（5）

工具	作用
`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`）。
`search_loader_api`	在 `fqcnIndex` 上子串搜索（`limit` 默认 20 封顶 50）。`mode=list` 列出已索引档 / skipped / cache overlay。
`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` 并列出候选，不猜、不新造键名。
`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。
`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 扫描器。

2. 工程辅助（7）

工具	作用
`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 / 基岩仍早退。
`generate_datagen`	生成 DataGen Provider 模板。platform 与 version 必填。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`。
`crash_analyze`	解析崩溃报告全文（或传 `crashReportPath` 直接读文件），推断 `crashKind`（含 `fml` / `client` / `server` / `fabric` / `quilt` / `liteloader` / `rift` / `modloader`）、可能成因、缺前置/版本不兼容与 `logHints`。优先于盲目网页搜索；实务分类可配合社区工具。
`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`）。
`check_publish_ready`	发布前清单：license/version、`build/libs` 是否像正式 jar，并读 `community_knowledge/authored/publishing.md` 的清单（缺项只 warning）。不上传、不调 Curse/Modrinth API。
`inspect_runtime`	日志型 inspector：优先 `logsDir`/`crashReportsDir`；否则有界探测 `run/logs` 等。禁止全盘 / JVM attach。默认读文件尾部。
`resolve_lib_skills`	按平台 + 精确 MC 版本解析 `knowledge/libs` 库 skill 源稿（§3.6：组映射 + `platforms`/`mcVersions` 过滤）；返回仓库相对 `path` 与 `versionsJson` 真值提示（带该文件的库写坐标前先读对应 MC 版本 slot）。与 CLI `lib resolve` 同一 core；只解析、不返回正文 —— AI 仍直接读源稿（文件即用）。

3. Forge 官方文档（5）

工具	作用
`list_forge_versions`	列出本地已加载的 Forge 文档版本。无数据时返回 `PLATFORM_DATA_MISSING`。
`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:` 前缀与 `
`get_forge_doc_summary`	取单页 L1 摘要：首段 + 各章节标题/短摘要，用于判断是否值得读全文。
`get_forge_doc_full`	取单页 L2/L2+ 全文；默认 `highlight_key=true` 突出 🔴🟠🟢 关键段。不要一次加载超过 2 个全文页。
`get_forge_doc_related`	根据路径骨架、标签与章节关键词返回相关页面列表。

4. Fabric 官方文档（5）

工具	作用
`list_fabric_versions`	列出本地 Fabric 文档版本（`fabric-docs` / `fabric-wiki` 有索引即计入）。无数据 → `PLATFORM_DATA_MISSING`。
`search_fabric_docs`	hybrid 搜索；可选 `source`：`fabric-docs`（默认）/ `fabric-wiki` / `all`。wiki 偏入门；26.1.2 无 wiki。
`get_fabric_doc_summary`	Fabric 页 L1 摘要（可指定 source）。
`get_fabric_doc_full`	Fabric 页全文 + 关键段高亮（可指定 source）。
`get_fabric_doc_related`	Fabric 相关页推荐。

5. NeoForge 官方文档（5）

工具	作用
`list_neoforge_versions`	列出本地 NeoForge 文档版本；主文档默认 26.1（26.2 构建已发布，但官方主文档不按版本分线且本仓无 26.2 语料 ⇒ 不克隆冒充）；1.20.1 可回退 Forge 数据。
`search_neoforge_docs`	hybrid 搜索（DeferredRegister、Data Components、Payload 等）；无语义库则纯 L0。须传 version（先 `list_neoforge_versions`）。
`get_neoforge_doc_summary`	NeoForge 页 L1 摘要。
`get_neoforge_doc_full`	NeoForge 页全文 + 关键段高亮。
`get_neoforge_doc_related`	NeoForge 相关页推荐。

6. 跨平台通用文档（5）

与专用工具能力对应，通过 platform（forge / fabric / neoforge / quilt / liteloader / rift / modloader，必填）统一入口。基岩请用 search_bedrock_docs（见 §6b）。

工具	作用
`list_doc_versions`	列出指定 platform 的可用版本（不会一次返回三平台）。
`search_docs`	多平台 hybrid 搜索；Fabric 时可传 `source`。无语义库 → 纯 L0；缺平台数据 → `PLATFORM_DATA_MISSING`。
`get_doc_summary`	多平台 L1 摘要，用于判断某篇文档是否包含所需内容。Quilt 缺页回退 Fabric（`fallback=fabric`）；FAPI 专属 Registry/ItemGroup 页拒绝（ok=false）。
`get_doc_full`	多平台全文。适用于查看 API 完整步骤、事件列表、配置项清单；`highlight_key` 默认突出 🔴🟠🟢 关键段。Quilt 缺页回退 Fabric；FAPI 专属页拒绝，不返回 Registry 正文。
`get_doc_related`	多平台相关页，返回共享最多关键词的其他页面。成功时 JSON 根是数组。Quilt 回退 Fabric 时仍为数组（条目带 `sourcePlatform:"fabric"` / `warning`），并丢掉 FAPI 专属页；FAPI 专属 id 拒绝（ok=false）。

6b. 基岩 Add-On（9）

与 Java search_*_docs / validate_project 分开。基岩用 Learn 文档与 pack JSON，不要用 Yarn / Mixin / query_api。

工具	作用	判读（三态）	错误码
`search_bedrock_docs`	检索 Microsoft Learn 基岩文档（带滞后 `docsStatus`）。可按调用放宽 `limit`（默认口径不变；只加宽窗口，不改排序与 release-notes 降权，池大小与放宽后的差额会在 `demotion` / `warning` 里说破）。	命中类：`ok` + `results[]`；空 ≠ 没有该文档 —— 先看 `docsStatus` / `demotion` / `warning`	—
`get_bedrock_doc_summary`	基岩页 L1 摘要。	命中类：`ok` + 摘要；缺页走 `ok:false` + `error`	—
`get_bedrock_doc_full`	基岩页全文。	命中类：`ok` + 全文；一次不超过 2 页	—
`get_bedrock_doc_related`	基岩相关页。	命中类：`ok` + 数组；空数组 ≠ 失败	—
`validate_addon_manifest`	校验 Add-On `manifest.json`（header/modules uuid 与 version）。不是 `validate_project`。	校验类：结论在 `errors[]`；本档未记载其专属三态名，以响应 `ok` / `error` 为准	—
`validate_bp_json`	校验行为包实体等 JSON。	校验类：同上	—
`generate_addon_manifest`	只吐 manifest JSON 文本，不写盘。	生成类：`resultKind` 三态同 §10（`ok` / `generation_failed` / `write_blocked`）	—
`generate_bp_entity`	只吐行为包实体 JSON 文本，不写盘。	生成类：同上	—
`analyze_bedrock_log`	基岩 content-log（`content_log.txt`）分诊。不是 Java `crash_analyze`。	读取类：无匹配 ⇒ 空结果 ≠ 无问题	—

判读列口径：ok:true = 有结果；ok:false = 工具失败（原因在 errors[] / error）。命中类工具的空结果不等于目标不存在（索引缺失、语义降级、工具边界都会写明）。生成类另有 resultKind 三态，见 §10。
错误码列的 — = 本仓库文档未记载该工具的专属错误码；实际错误以响应里的 errors[] / error.code 为准，禁止凭记忆补码。

7. 社区知识库（4）

与官方文档分离；不替代 search_*_docs。适合发布、崩溃分类、软依赖、机器 GUI、库选型等实务。索引 110 条（authored 95 / links 11 / permitted 4，直读 community_knowledge/indexes/index-l0.json）；库集成占其中 48 篇 lib-*.md。用法规则见 community_knowledge/AGENT_USAGE.md；主题 id 速查见 community_knowledge/README.md。

工具	作用
`list_community_sources`	列出 `community_knowledge` 条目（permitted / authored / links）及来源统计。
`search_community_docs`	搜索社区库；命中含 `sourceKind`、`url`、`summary`。库集成可搜 `lib-curios`、`library-catalog-2026` 等。
`get_community_doc_summary`	社区条目摘要（含署名）；links 仅元数据 + 外链。
`get_community_doc_full`	permitted/authored 返回仓库内 Markdown；links 只给 URL，不抓网页正文。

7.5 库模组知识体系（短文 + Skill + 数据链）

三层结构，覆盖「库模组是什么 → 怎么用 → 数据从哪来」：

① 社区短文（community_knowledge/authored/，经 search_community_docs 检索）

48 篇 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 等 15 篇）
总目录 library-catalog-2026（全览导航）、陷阱专篇 lib-traps-2026（8 条选型陷阱）、配方集成 library-integration / library-integration-jei-emi
每篇含「核对（2026-08 反编译验证）」小节：已反编译核对的 MC 版本 × loader 的顶层 API 包/入口，细节以官方为准

② 库 Skill 源稿（knowledge/libs/，按 AGENTS.md「库模组 Skill」解析使用，不落盘平台目录）

五组：all-platforms 20 / fabric-only 10 / forge-only 2 / neo-only 2（Curios、KFF 与 forge-only 镜像）/ bedrock-only 2 = 36 份 mc-*/SKILL.md（34 唯一 skillId）
解析规则：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

③ 数据链（短文 frontmatter → 脚本生成 → MCP 消费）

authored/lib-*.md frontmatter（+ library-integration / library-integration-jei-emi 导航专篇）
  → mcp-server/scripts/build-library-catalog-from-authored.mjs → library-catalog.ts（50 条 catalog / 2632 verifiedApi 键 / officialUrls）
  → scripts/build-lib-manifest.mjs（Modrinth API）→ lib-manifests/all.json（49 slug / 3,003 版本条目）
  → scripts/batch-decompile.mjs（分批反编译，源码按需生成到 $MC_SKILL_CACHE，不入库）
  → scripts/merge-verified-api.mjs → 回填 verifiedApi
  → scripts/build-api-summaries.mjs → lib-api-summaries/（48 份库 API 摘要）
  → check_dependencies 消费 catalog + manifest（库识别 / 版本摘要）

脚本位置分散，两处都有（勿只查一处）：

脚本	位置
`build-library-catalog-from-authored.mjs`	`mcp-server/scripts/`
`build-lib-manifest.mjs`	`scripts/`（仓库根）
`batch-decompile.mjs`	`scripts/`（仓库根）
`merge-verified-api.mjs`	`scripts/`（仓库根）
`build-api-summaries.mjs`	`scripts/`（仓库根）

数据位置见反编译数据产物一节。

这两个口径的权威出处与复算纪律见 CONTRIBUTING.md §库数据链计数口径；本处只给现场读数与结论。

计数口径 A（verifiedApi 键）：分母 = mcp-server/src/diagnostics/library-catalog.ts 中各 entry 的 verifiedApi 顶层 "<gameVersion>/<loader>" 键之和，实算 2632；复核命令 grep -cE '"[0-9][^"]*/[a-z]+": \{' mcp-server/src/diagnostics/library-catalog.ts（同数钉在 mcp-server/scripts/assert-lib-ownership.mjs 的 LEDGER.verifiedApiKeys，磁盘实算与钉值不一致该门即红；其他处出现的 1880 / 1836 / 1830 均为过期值）。
计数口径 B（库 API 摘要侧）：分母 = mcp-server/data/lib-api-summaries/*.json 的份数与其 versions 组键合计，实算 48 份 / 824 组；复核命令 node -e "const fs=require('fs'),p='mcp-server/data/lib-api-summaries';const f=fs.readdirSync(p).filter(x=>x.endsWith('.json'));console.log(f.length,f.reduce((a,x)=>a+Object.keys(JSON.parse(fs.readFileSync(p+'/'+x,'utf8')).versions||{}).length,0))"。A 与 B 是两个不同分母（2632 ≠ 824），禁止互相顶替或混写。
版本窗口另见各 entry 的 supportedVersions: string[]（Modrinth 实测的受支持 MC 版本列表），
与 verifiedApi 的 gameVersion/loader 键是两个独立字段，二者并存。

8. 移植、数据诊断与上游可用性（4）

工具	作用
`diagnose_data_paths`	诊断数据目录配置（高级排障用）。诊断 `MC_SKILL_DATA` / `MC_SKILL_COMMUNITY` 解析结果，以及 forge/fabric/neoforge/quilt/liteloader/rift/modloader/bedrock/community 是 `found` / `empty` / `not_found`。排障首选。
`analyze_porting_path`	扫描项目，识别平台/版本/Mappings/Architectury，输出风险、`routeSteps`、参考链接与建议的 `query_api` 调用。`targetPlatform` 必填（禁止静默默认 forge→neoforge，缺失 → `INVALID_INPUT`）。`routeSteps` 是给人读的 `string[]`；机器可读交接在 `nextSteps[]`（`tool` + 可直接调用的 `args`）。LiteLoader / Rift / ModLoader / 基岩 → `UNSUPPORTED_PORT`。
`port_project`	执行移植步骤：`init_architectury` / `extract_common` / `apply_version_migration`。默认 dryRun；真正写入需 `dryRun=false` + `confirmed=true` + `MC_SKILL_ALLOW_WRITE=1` + 路径在 `MC_SKILL_PROJECT_ROOT` 内。
`query_upstream_releases`	查上游发布源「某个加载器/映射/模组的版本到底存在吗、最新出到第几 build」。`source` 七选一：`forge` / `neoforge`（maven-metadata.xml，全量可查）、`fabric-loader` / `fabric-yarn` / `quilt-loader` / `parchment`（端点按 MC 版本分列，必须带 `minecraftVersion`；parchment 的 artifact 名是 `parchment-<mc>`、版本串本身是日期如 `2023.09.03`）、`modrinth`（`slug`，任意第三方模组/库）。*与 `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` 位。

9. Registry / Mixin / 资源（9）

工具	作用	判读（三态）	错误码
`query_registry`	查询 Vanilla 资源 ID（`nameLayer: registry_id`）；类/方法名用 `convert_mapping`。	命中类：`ok` + 结果；空 ≠ 没有该 ID（只覆盖 `minecraft:`）	—
`mixin_analyze`	解析 mixins.json 与 @Mixin 注入目标（多映射层；高风险，见 supportMatrix）。`deep:true` 时基于已缓存 remapped 客户端 jar 做字节码级校验（目标类/选择器/@At 调用点）；jar 未缓存 → CACHE_MISS 引导（不自动下载）。	校验类：`ok` + 结论；jar 未缓存 = `CACHE_MISS` 引导，不是失败（先调 `get_minecraft_source`）	`CACHE_MISS`
`validate_at`	字节码级校验 Forge/NeoForge `*_at.cfg`：类/成员存在性（继承链/record/内部类）、映射层不匹配建议、跨文件冲突。	校验类：结论在 `errors[]`；本档未记载其专属三态名，以响应 `ok` / `error` 为准	—
`validate_aw`	字节码级校验 Fabric `.accesswidener`：header/namespace、条目类型、存在性、transitive、跨文件冲突。	校验类：同上	—
`audit_resources`	静态检查模型纹理引用、孤儿纹理、modId 命名等。	校验类：同上（静态面，不做字节码级）	—
`validate_datapack_json`	recipe / loot_table / advancement / tag 精简 JSON 校验（1.21+ recipe `result` 可为对象；不是完整 pack_format schema）。	校验类：精简 schema ⇒ 通过 ≠ 完整 pack_format 合规，只证明覆盖了本节列出的面	—
`get_workflow_template`	工作流全文（以 `get_workflow_template` 列表为准；与 MCP Prompt 同名；Cursor tools 兜底）。	命中类：`ok` + 全文；模板名以该工具的列表为准（不是靠猜名字）	—
`list_knowledge_resources` / `read_knowledge_resource`	列出/读取 `mcskill://`（含 patterns、schema、workflow、community 等）。	命中类：`ok` + URI 列表 / 正文；缺 URI ⇒ `ok:false`	—

判读列口径：ok:true = 有结果；ok:false = 工具失败（原因在 errors[] / error）。命中类工具的空结果不等于目标不存在。生成类另有 resultKind 三态，见 §10。
错误码列的 — = 本仓库文档未记载该工具的专属错误码；实际错误以响应里的 errors[] / error.code 为准，禁止凭记忆补码。本组唯一的确证码是 CACHE_MISS（mixin_analyze deep 的 jar 未缓存引导，不是错误而是"先补缓存"）。

计数口径：本组 9 个工具 / 8 行 —— 末行把 list_knowledge_resources 与 read_knowledge_resource 合并为一行，标题「（9）」数的是工具数。

字节码级校验（mixin_analyze deep / validate_at / validate_aw）依赖 T2 缓存管线：
jar 未缓存时返回 CACHE_MISS 引导（先调 get_minecraft_source），绝不自动大下载。

10. 代码生成模板（9）

本组 9 项工具默认只吐文本 + 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）。计数口径：本组就是下表 9 项；generate_datagen（DataGen Provider 模板）归 §2 工程辅助，不在本组内。

工具	作用
`generate_model`	方块/物品 JSON 模型与 blockstate 模板。`version` 必填；`kind` 默认 `block`，`kind=item` 只出物品模型（无 blockstates）。
`generate_lang`	en_us + zh_cn lang JSON 骨架。`version` 必填；骨架不随 pack_format 变。空 `entries` 不静默（S6-③）：仍 `ok:true`，但响应带披露 warning + 机读 `emptyEntries:true` ⇒ 那是空骨架，不是成品。
`generate_network_packet`	网络包（C2S / S2C）骨架，按平台与版本给注册与收发样板。
`generate_capability`	Capability / DataAttachment 骨架。`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。
`generate_config`	配置骨架。`loader` 与 `version` 必填，禁止默认 forge。neoforge 1.21+/26.1/1.20.4/1.20.6 用 ModConfigSpec；1.20.1 用 ForgeConfigSpec（Forge 兼容）；fabric/quilt 吐 Cloth Config 最小骨架并 warning 声明依赖（不是改口 mc-config）。fabric/quilt 的默认永远是 Cloth；YACL 只作显式 opt-in（`library` 参数已实现：枚举 `cloth
`generate_entity_renderer`	实体渲染器骨架。`platform` 与 `version` 必填；fabric/quilt 直接 error。
`generate_worldgen`	世界生成 JSON 骨架。`platform` 与 `version` 必填，且有两端版本哨兵：1.x 只收 1.18.2–1.21.x、26.x 只收 `26.<n>[.<n>]`（编造版本号如 `1.99.9` 一律拒绝并点名 `WORLDGEN_MAX_MINOR_1X` 抬哨兵出口，不默默生成）；`platform=forge` × 26.x 直接拒绝（Forge 无 26.x）。forge / neoforge 的 feature JSON；fabric / quilt 仅 `configured_feature` / `placed_feature`（禁止 forge `biome_modifier`）。无模板时 `errors` 列出支持档。
`localize_mod`	汉化：自有模组 `diff` / `draft_zh`，或第三方 jar `extract` / `pack_draft`。无机器翻译，未填项标 `needsTranslation`；无 `en_us` 时可回退其它语言作源。
`generate_playtest_driver`	游玩自测骨架：`driverMode` 默认 `external_bridge`（桥动作序列 + 后置条件 + 证据约定）；`in_jvm_player_agent` 在 `PLAYTEST_VERIFIED_TIER` 列出的档（唯一真源；正文不数档，档位列表以生成器现读为准）出真执行器（意图菜单 + 邮箱消费 + 类型化后置条件 + 逐意图预算），表外档只出契约 + 结构壳。不装桥、不跑游戏。

11. 日志与依赖诊断（7）

工具	作用	判读（三态）	错误码
`analyze_log`	解析游戏/崩溃日志片段（可复用 `crash_analyze` 分类）。	读取类：`ok` + 分类结论；片段解析 ⇒ 结论只覆盖你贴进来的那一段	—
`analyze_build_log`	解析粘贴的 Gradle/javac 构建失败日志（不执行 gradlew）；返回符号/文件与建议工具。	读取类：`ok` + 符号/文件 + 建议工具；它不跑 gradlew	—
`get_migration_guide`	默认 Primer toc；`section` 只返回该章；`full=true` 才全文（含 url/license/loader）。route 含 platform 或 `from->to`。	命中类：默认只给 toc（三档：`toc` / `section` / `full`）；没给全文不等于没有该章	—
`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` + `data/lib-manifests/all.json`）。	命中类：`ok` + `detectedLibraries`；启发式 + catalog ⇒ 未收录的库会漏（不是完整 Gradle 解析）	—
`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`；缺件不得读成"没有失败"	—
`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`
`playtest_bridge`	调 BlackBoxPro 桥（host 恒 `127.0.0.1`，端口默认 38081）：`status` 看 `/status.ready`（已进世界）；`execute` 发 `/execute`（原生超时 ⇒ `PLAYTEST_TIMEOUT`）；`await` 轮询 `query_*` 等条件（桥无 `wait_until`）。`execute`/`await` 须 `confirmed=true` + 授权。桥无鉴权且通配绑定 —— 只在本机用。	超时 ≠ 没失败：原生超时映射 `PLAYTEST_TIMEOUT`，不得塌成"没失败"。`/status.ready` 不可信，判"在不在世界"看 `query_player_state`	`PLAYTEST_TIMEOUT`

判读列口径：ok:true = 有结果；ok:false = 工具失败（原因在 errors[] / error）。命中类工具的空结果不等于目标不存在。本节三个真三态面：inspect_playtest_evidence 的 present|absent|unreadable、playtest_intent 的三档失败形态、playtest_bridge 的超时语义。
错误码列的 — = 本仓库文档未记载该工具的专属错误码；实际错误以响应里的 errors[] / error.code 为准，禁止凭记忆补码。本节填写的 8 个码均为文档具名值。

12. 自我更新（1）

工具作用

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 有迁移提示）。

get_server_status 附带 buildStatus（src 比 dist 新时 buildRequired=true，提示重新 npm run build）、updateHint（上次 check 缓存，默认 TTL 1h）与 pendingRestart。

13. 反编译与模组源码（5）— T2 Wave C

默认零下载：不预热、不预取；仅显式调用时按需下载到 $MC_SKILL_CACHE（默认 %APPDATA%/mc-skill-cache / ~/.config/mc-skill-cache），绝不写项目目录。MC_SKILL_SKIP_DOWNLOAD=1（CI）时下载类工具诚实失败并给出指引。Java 17+ 前置（VineFlower / tiny-remapper）：缺失时返回 TOOLCHAIN_MISSING + Adoptium 安装指引，进程不崩溃。

工具	作用
`get_minecraft_source`	按需下载+重映射+反编译真实 MC 源码，返回类源码片段（支持行区间 / `force` 重编译）。首次 3–10 分钟，同版本缓存命中 <1s。
`analyze_mod_jar`	纯 Node 解析本地 mod jar：fabric.mod.json / mods.toml / neoforge.mods.toml、mixins.json 引用、entrypoints、依赖、AW/AT。传 `version` 则回显 `mcVersionConstraints` + `versionMatch`（match / mismatch / unknown，未核实形态不猜）。无 Java、零下载。
`decompile_mod_jar`	VineFlower 按需反编译本地 jar → `$MC_SKILL_CACHE/decompiled-mods/<modId>/<version>/`，返回源码树摘要；可选 remap（需匹配 MC 版本）。
`search_mod_code`	对已反编译源码做行级 grep（子串/正则），返回 file:line 命中；入口：`decompiledDir` 或已反编译过的 `jarPath`。
`download_official_mdk`	下载官方 MDK zip 到 `$MC_SKILL_CACHE`。GitHub pin commit（校验和在 `mcp-server/data/mdk-checksums.json`）；默认 `dryRun`。解压依赖 unzip / 7z / bsdtar。

版本支持矩阵（与 26.x 现状对齐）：

版本区间	Yarn	Mojmap	说明
1.14 – 1.21.11	✅	✅	两步 remap（official→intermediary→named）
26.1+	❌（已停更）	✅	去混淆，免 remap

与 query_api 的分工：query_api / get_method_params 查 1.16.5–1.20.4 Vanilla 签名（快、离线）；不含 Forge/Fabric API，26.1+ 无索引。本节取源码类工具（get_minecraft_source / decompile_mod_jar / search_mod_code / download_official_mdk）仅在确实需要完整源码/反编译时使用（下载量大），各工具 description 均带 ⚠️ 边界提示。

反编译数据产物

已入库的反编译数据产物（供 check_dependencies 等消费，clone 后即用）：

数据	位置	内容
`library-catalog.ts`	`mcp-server/src/diagnostics/`	50 条 catalog（48 篇 `lib-` + 集成导航专篇）/ 2632 个 verifiedApi 键（`gameVersion/loader → packages/entrypoints`）+ `supportedVersions` 版本窗口*（Modrinth 实测受支持 MC 版本列表，反编译验证）+ `officialUrls`
`lib-api-summaries/*.json`	`mcp-server/data/`	48 份库摘要 / 824 个版本组；按库累计 public 类 114,708 / 方法签名 545,127，磁盘约 38 MB。复核：`node -e "const fs=require('fs'),p='mcp-server/data/lib-api-summaries';…"`（见本表下方计数口径 B）
`lib-manifests/all.json`	`mcp-server/data/`	49 slug / 3,003 版本条目（版本号/URL/hash/loader 矩阵，Modrinth API 生成）。复核：`node -e "const j=require('./mcp-server/data/lib-manifests/all.json');console.log(j.length, j.reduce((a,e)=>a+e.entries.length,0))"` ⇒ `49 3003`；嵌套键是 `entries`，按 `versions` 取会算出 0

packages 是启发式产物，不可当 import 依据：verifiedApi.<版本/加载器>.packages 由 scripts/batch-decompile.mjs
从反编译产物的顶层目录截得来（通用 TLD 取前 3 段、其余取前 2 段，且同层只按字母序取首个子目录），
所以它只回答「这个库大概活在哪几个包根下」，不是可直接照抄的全类名清单。要落到具体类名，
必须走 query_loader_api（先让用户自备 jar 跑 ingest_loader_api）或 IDE 补全核对。
归属侧已有硬约束：scripts/merge-verified-api.mjs 会整行拒绝「包根已被别的库条目证实」的包名（JiJ 内嵌库泄漏），
自检见 mcp-server/test-scripts.mjs 的 §S3 块。

已知缺口（已实测核实，不伪造）：catalog 50 条中有 6 条 verifiedApi 为空对象（实算：逐 entry 花括号配对取空体）—— 其中 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 仓库）为准，禁止从邻库或邻版克隆摘要。另 2 条 authored/lib-traps-2026（role: "trap"）与 authored/library-integration（汇编条目）按设计不带 verifiedApi，不属缺口。
注：lib-spruceui-obsidianui 条目中的 obsidianui 在 Modrinth 确实存在（200）。若后续要为其补摘要，正确做法是在 community_knowledge/authored/lib-spruceui-obsidianui.md 的 frontmatter 补 modrinthSlug 后重跑数据链，不要直接手改生成物 library-catalog.ts。

反编译源码本体（28 万 .java）不入库（按需生成至 $MC_SKILL_CACHE）；search_mod_code 在源码缺失时返回 NOT_FOUND + 指引先调 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）。

另：registerPrompt / registerResource（工作流与知识 URI）供支持 prompts/resources 的客户端使用；详见 mcp-server/docs/prompts-client-compat.md。

工作流模板（MCP Prompts）

工作流模板通过 registerPrompt 注册（支持 prompts 的客户端可用）；Cursor 等仅 tools 客户端用该工具（get_workflow_template）获取同款全文。共 61 个（49 个开发模板 + 12 个编排技能，由 get_workflow_template 的枚举实测；另见本页 mcskill://skill/ 族）。

这些模板是 Agent 步骤清单（人在环）：对齐创意与版本取舍后给出检索/草稿/校验顺序。没有 Gradle / 拷 jar 进游戏目录 / 上传发布的 MCP 工具；mc-build-mod / mc-ingame-iterate 只列步骤，须用户确认后在本机执行。不代跑 Gradle、不自动拷 mods、不上传商店——高风险步骤写明「用户确认后执行」，这是设计。

模板名	标题	流程要点
`mc-new-block`	新方块工作流	DeferredRegister 注册 → BlockItem → 模型（generate_model）→ lang（generate_lang）→ loot（generate_datagen）→ 可选 tags/recipe
`mc-new-entity`	新实体工作流	EntityType + 属性 → SpawnPlacement/生物蛋 → 渲染器（generate_entity_renderer）→ loot/音效
`mc-new-gui`	GUI 工作流	MenuType + AbstractContainerMenu → Screen 注册 → 按平台同步（Forge SimpleChannel / NeoForge Payload / Fabric ServerPlayNetworking）
`mc-crash-triage`	崩溃分诊	analyze_log/crash_analyze → search_community_docs → validate_project + mixin_analyze → diagnose_gradle
`mc-port-mod`	移植模组	analyze_porting_path → 确认目标 → port_project dryRun → get_migration_guide
`mc-build-mod`	模组构建流程	validate_project / diagnose_gradle → 用户确认后 gradlew build → 确认 build/libs jar；失败则分析日志；可接真机循环
`mc-ingame-iterate`	真机测试与修复循环	索取并核对启动器路径（官方/HMCL/PCL2 版本隔离）→ 用户确认后装 jar → 复现 → 修 → 再测。路径约定见模板正文与 HMCL 隔离文档
`mc-ingame-playtest`	游戏内游玩测试（桥）	preflight（桥 jar/依赖记账）→ `playtest_bridge`（`/execute` + `/status.ready` + `await`）→ 截图/查询证据 → `inspect_playtest_evidence` → 改码回灌；执行权见根 AGENTS.md「人在环例外：游玩自测（三通道）」
`mc-localize-mod`	模组汉化	判定 own/third_party → `localize_mod` diff/draft 或 extract/pack_draft → Agent 填中文 → 自检；见 `authored/localization-lang`
`mc-decompile-mod`	模组反编译研究	定位 jar → `analyze_mod_jar` → `decompile_mod_jar` / `get_minecraft_source` → `search_mod_code` → 定位目标类 → 修改建议 → 衔接 `mc-build-mod` / `mc-ingame-iterate`
`mc-new-item`	新物品工作流	该档 03-item 注册 → 模型/lang → 合成（有模板才 generate_datagen）
`mc-new-blockentity`	方块实体工作流	BlockEntityType + 方块 → 渲染/同步；GUI 接 mc-new-gui
`mc-mixin`	Mixin 工作流	mixin_analyze → mixins.json 分桶 → 核 mappings
`mc-worldgen`	世界生成工作流	configured/placed feature → 该档 biome 注入
`mc-config`	配置工作流	generate_config（loader+version 必填）或 Cloth Config
`mc-gametest`	GameTest 工作流	按平台核文档，禁止默记 Forge 1.20.1
`mc-publish`	发布清单	元数据 / build/libs / changelog / license；尽量让用户自行上传（人在环，不代传）
`mc-setup-env`	开发环境搭建	detect_mod_project → MDK dryRun 或 Loom/映射清单；genRuns 由用户确认后执行
`mc-full-mod`	从零新模组总链	仅从零：setup-env → mc-new-* → build → ingame-iterate → 可选 localize/publish
`mc-networking`	网络通信清单	session task=mc-networking → generate_network_packet（带版本后缀）
`mc-capability`	能力 / 附件清单	Forge/Neo 1.20.1 Capability；Neo 1.20.4+ Attachment
`mc-recipe-data`	配方与数据包	07-datagen / mc-recipe / loot / advancement
`mc-audio-vfx`	音效与粒子	mc-sound / mc-particle
`mc-commands`	命令	mc-command
`mc-dimension-structure`	维度与结构	mc-dimension / mc-structure
`mc-access`	AT / AW	validate_at / validate_aw
`mc-bedrock-addon`	基岩 Add-On	search_bedrock_docs / validate_addon_manifest；不灌 Java 02–10
`mc-fluid`	流体	02 + mc-fluid
`mc-enchant-potion`	附魔 / 药水 / 效果	mc-enchantment / mc-potion / mc-effect
`mc-energy`	能量	mc-energy / mc-capability
`mc-creative-tags`	创造栏与标签	03
`mc-kotlin`	Kotlin 模组	00；核该档文档
`mc-jei`	JEI 兼容	mc-compat-jei
`mc-ci-publish-extra`	CI 发布附加	00；只出步骤名（可复制 YAML 见 `community_knowledge/patterns/examples/mod-ci-github-actions.md`），不代跑 CI、不上传（人在环）
`mc-villager`	村民职业 / 交易	session task=mc-villager → 04-entity；职业/交易签名核本档文档，禁抄邻档
`mc-multiblock`	多方块结构	session task=mc-multiblock → 02-block / 07-datagen；无模板时文档手写
`mc-ai`	实体 AI / Goal	session task=mc-ai → 04-entity；Goal/Brain 类名核本档文档，禁把 1.12 AI 任务表抄进 1.20+
`mc-events-forge`	Forge 事件系统清单	session task=mc-events-forge → 05-events / mc-events；注册期 vs 运行期订阅分叉逐版取该档 05-events.mdc（≤1.17 起）；类名核 search_forge_docs
`mc-events-neoforge`	NeoForge 事件系统清单	session task=mc-events-neoforge → 05-events / mc-events；mod bus（注册期）vs 游戏总线（运行期）逐档取该档 05-events.mdc；类名核 search_neoforge_docs
`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//05-events（QSL 无正式版构件，禁止把 Fabric 回调当 QSL）；类名核 search_fabric_docs
`mc-rendering`	渲染工作流（BER / 自定义模型加载器 / 着色器）	渲染注册入口按平台 + 版本分叉，禁止一条 API 名覆盖全档；先确认平台与精确版本 → session（可 task=mc-new-blockentity / mc-new-entity）；表现层接 `mc-audio-vfx`
`mc-profiling`	性能剖析工作流	卡顿 / 内存 / 耗时的独立剖析面；原则「先测量后优化」。是 `mc-crash-triage` 第 5 步与 `mc-build-mod` 第 7 步的完整版
`mc-save-migration`	存档数据结构迁移工作流	强制第一步：改存档 schema 前必须先让用户整份备份世界目录并回报路径。覆盖 SavedData `.dat`、方块实体 / 实体 / 区块读写格式、跨版本旧世界兼容
`mc-server-multiplayer-test`	服务端与多人联机测试工作流	联机侧验证：专用服务端、多客户端同房、状态同步、权限与延迟下行为。构建走 `mc-build-mod`，单机真机走 `mc-ingame-iterate`
`mc-combat-attribute`	伤害 / 属性 / 战斗工作流	伤害种类、实体属性与加成、战斗数值。附魔 / 药水 / 效果走 `mc-enchant-potion`，战利品走 `mc-recipe-data`
`mc-multi-loader`	多加载器（Architectury）工作流	一份源码产出 Fabric / NeoForge（或 Forge）多加载器构建；构建与调试成本翻倍属取舍，先与用户确认。已有工程改代码走对应平台 session
`mc-modpack`	整合包集成工作流	把第三方 mod 装成可跑的包：依赖闭包、加载顺序、冲突分诊。不做自动发布，不代下载 / 代上传 mod 文件
`mc-datapack-standalone`	独立数据包工作流（无 Java 代码）	纯数据包：世界 `datapacks/` 目录或独立 zip，无 `build.gradle`、无 Java 源码。模组附带的配方 / 战利品走 `mc-recipe-data` 与对应平台 session
`mc-resourcepack-standalone`	独立资源包工作流	纯资源包：`resourcepacks/` 或独立 zip（模型 / 方块状态 / 纹理 / lang / 音效 / GUI 贴图）。模组内资源走对应平台 session 与该档规则

知识暴露（MCP Resources）

通过 registerResource 注册 mcskill:// URI（支持 resources 的客户端）；list_knowledge_resources / read_knowledge_resource 工具兜底。

实测共 293 条（由 list_knowledge_resources 枚举；复核：node mcp-server/dist/cli.js list_knowledge_resources）。按 URI 族：

URI 族	条数	内容
`mcskill://code-patterns/<平台>/<版本>/NN-<主题>-patterns.md`	116（forge 61 / fabric 49 / neoforge 6）	代码模式库正文，按平台 + 版本分档；供 agent 直接 Read 的片段级范式
`mcskill://community/<sourceKind>/<id>`	99	`community_knowledge/` 可读条目（authored / permitted / links，见「社区实务知识」一节）
`mcskill://workflow/<模板名>`	61	与 Prompt 同名的工作流正文（与 `get_workflow_template` 同一集合；含 49 开发模板 + 12 编排技能）
`mcskill://skill/<技能名>`	12	编排技能正文（`common_skill/mc-*/SKILL.md`；与 `get_workflow_template` 尾部 12 个编排技能同名）
`mcskill://matrix/mixin-support`	1	mixin_analyze 支持矩阵（SRG/Yarn/Mojang/readable/descriptor 形态）
`mcskill://schema/sqlite`	1	yarn-mappings.sqlite v2/v3/现批次 v4 字段说明（须带 `?version=<精确 MC>`，裸 URI 会被拒）
`mcskill://version-changes/1.21`	1	1.21 变更专章（知识库）
`mcskill://antipatterns/registry`	1	注册反模式短文
`mcskill://patterns/README`	1	代码模式库索引（`community_knowledge/patterns/`）

code-patterns 只覆盖 forge / fabric / neoforge 三树（quilt / liteloader / rift / modloader / bedrock 无 code-patterns/ → 该族 0 条）；其中 6 条是 archived 旧档，注册在册但 read_knowledge_resource 会回 found:false + 存档说明，不再给正文。

独立 CLI（`node mcp-server/dist/cli.js`，86 工具全可用）

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 在那个位置会被当未知参数 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 拒绝。

⚠️ Windows PowerShell 5.1 控制台坑（E-7）：PS 5.1 在 GBK 代码页下用管道捕获本 CLI 的 UTF-8 JSON 会引入坏控制字符导致 JSON.parse 失败；纯 Node spawnSync 管道解析同一输出完全正常。脚本化消费请用 Node 子进程，或先 chcp 65001。

node mcp-server/dist/cli.js status --version 1.20.1            # 服务器状态（含 buildStatus）
node mcp-server/dist/cli.js query --className net.minecraft.world.entity.LivingEntity --methodName getMaxHealth --version 1.20.1
node mcp-server/dist/cli.js convert --from mcp --to mojang --name getHealth --owner net.minecraft.world.entity.LivingEntity '--descriptor=()F'
node mcp-server/dist/cli.js update --action check
node mcp-server/dist/cli.js list-tools                          # 全部 86 个工具的 schema

通用 dispatch（v0.2+）：除上述命令外，任意 MCP 工具名可直接调用（handler 自动收集，缺参时返回 zod 校验提示）：

node mcp-server/dist/cli.js search_docs --platform forge --query DeferredRegister --version 1.20.1
node mcp-server/dist/cli.js check_dependencies --buildGradle "..." --fabricModJson "{...}"
node mcp-server/dist/cli.js analyze_mod_jar --jarPath <path>
node mcp-server/dist/cli.js get_community_doc_summary --id authored/lib-curios

旧位置参数形式（query <className> / convert ... <memberName> 等）仍兼容；PowerShell 括号场景用单引号包裹（如 '--descriptor=()F'）。

排障与常见问题（FAQ）

排障数据分布在下面几张专表里，本节只做索引。

四类高频症状

症状	先查什么	去哪
MCP 宿主里工具全不可调	`dist/` 编译了没有？宿主重载了没有？	下节「工具不可用排查」
`PLATFORM_DATA_MISSING` / 某平台数据为空	`MC_SKILL_DATA` 是否指向本仓库 `data/`	`diagnose_data_paths`，或开 `MC_SKILL_DEBUG_PATHS=1`
查不到某个 API / 类	索引覆盖外或简名歧义，≠ 游戏里没有该类	本文「工具边界」的误判对照表
真机起了游戏但驱动没动作	授权双开关 / 失焦暂停 / 存档 `session.lock` 被占	本文「后半 loop 运维散件」

按症状跳到本文对应专表

工具返回怪结果、崩溃、参数被误解 → 「工具陷阱（实测，同类问题）」
拿不准 found:false / CACHE_MISS / 空 methods 意味着什么 → 「工具边界」误判对照
抓取 / 上游查询失败（TLS、超时、404、代理）→ 「工具与网络边界」
装了更新却没生效 → mc_skill_update 的 updateHint（TTL 1h）+ get_server_status.buildStatus（buildRequired）
CLI 输出乱码 / MODULE_NOT_FOUND（非 ASCII 路径）→ 「独立 CLI」节的 PowerShell 5.1 坑
游玩自测：桥超时 / scan=0 / 世界不加载 / 关不掉客户端 → 本文「后半 loop 运维散件」

工具不可用排查（clone 后必读）

MCP 工具全部调用失败（服务未启动）：mcp-server/dist/ 未编译（dist 不入库）。执行 cd mcp-server && npm ci && npm run build（Node 需 ≥ 22.5；Yarn 映射可再 npm run build:yarn-sqlite）。
get_server_status 报 buildStatus.buildRequired=true：src 比 dist 新，需重新 npm run build，然后在宿主里重载 MCP（只编 dist 不够，宿主进程仍跑旧代码）。
反编译类工具报 TOOLCHAIN_MISSING：需 Java 17+（VineFlower / tiny-remapper）；装 Temurin 17+ 后重启 MCP，或按返回指引设置 JAVA_HOME。
search_mod_code 报 NOT_DECOMPILED：源码尚未反编译（按设计不入库）；先按返回指引调 decompile_mod_jar / get_minecraft_source。
无 MCP 客户端：用独立 CLI node mcp-server/dist/cli.js <工具名> --参数=值（86 工具全可用）。

术语表

词	含义
人在环（HITL）	高风险步骤停在清单 / `dryRun` 等用户确认；见「它是什么」一节
`dryRun` / 写盘三态	预览（不传 `write`）/ 真写（`write+confirmed`+环境变量齐）/ 被拒（`write_blocked`）
证据三态	`present` / `absent` / `unreadable`；缺件不得读成「没有失败」
`resultKind`	生成类工具的机读结果：`ok` / `generation_failed` / `write_blocked`（两种失败不得混读）
`total`	本次返回条数，随传的 `limit` 变；不是语料命中总数
`totalPool` / `truncated`	进输出窗口前本面可用的候选数 / 是否还有页没返回
`semantic`	本次检索是否走了语义索引；`false` = 退化为关键词（`stale` = 索引过期）
`verbatim`	命中是否为「该标识符在页面正文逐字出现」；缺该字段 = 未判定
`sourceKind`	社区条目来源：`authored` / `permitted` / `links`
`verifiedApi`	库 catalog 里逐条目核过的 API 键（`gameVersion/loader`）
`fallback` / `source_version`	文档回退时：结果实际来自哪一版 / 是否发生回退
前半 / 后半 loop	前半 = 写码→构建→自动起游戏→分诊；后半 = 进游戏游玩→取证→回灌
测试阶梯（L0–L7）	交付前的最低测试门槛：L0 构建 → L1 结构静态 → L2 数据 → L3 GameTest → L4 真机冒烟 → L5 场景 → L6 服务端 / 多人 → L7 回归；低层红不许跳高层，最低线按改动面取最大者（缺证据即判红，见「证据三态」）。见根 `AGENTS.md`「游玩测试要求（交付门槛）」
表外版本	不在 `PLAYTEST_VERIFIED_TIER` 里的档：真 driver 出不了，但仍须测 —— 走桥路线或人工游玩，并如实标注「人工验过 / 未验」
三通道	游玩自测执行权的授权通道（A 仓库沙箱 / B 用户 dev 实例 / C 第三方桥）

卸载与回退

撤除写进用户工程的规则 / Skill：activate_platform_pack action=deactivate（按写入清单撤写）；先跑 action=write 的 dryRun 预览看 planned / willDelete。
撤除游玩自测驱动：按 generate_playtest_driver 生成的 playtest/REVERT.md 删驱动文件 + 被测工程里的 PlaytestQaDriver.register(); 调用行；git status 自查应零命中（驱动绝不提交）。
撤除 CLI / MCP 安装：npm uninstall -g mc-skill（或删对应 bin 链接）；仓库 mcp-server/ 与 data/ 可直接删（都在仓库内，不影响用户模组工程）。
回退自更新：mc_skill_update 只做 git ff-only 合并，回退用 git reset --hard <上一个 commit>（tooling）或换回上一版 data zip；更新前有未提交改动会被拒（可选 allowDirty / stashDirty）。
缓存与临时产物：反编译 / MDK / 语义模型产物在 $MC_SKILL_CACHE（默认 %APPDATA%/mc-skill-cache）；删它不影响仓库与用户工程。

阶段里程碑

阶段	状态	内容
Phase 1	✅ 完成	Forge / Fabric / NeoForge 规则集与多版本扩展
Phase 1.5	✅ 完成	模组脚手架 + 校验 CLI
Phase 2	✅ 完成	Agent Skills + 代码模式库
Phase 3	✅ 完成	MCP Server（文档 + 映射 + 移植 + 社区 + Wave B/C/D 扩展 + 五平台；工具数以 `list-tools` 为准）
Phase 4	✅ 完成	知识库 / 反模式 / 数据审计与 Release 分发
Phase 4.5	✅ 完成	库模组全覆盖：48 篇 `lib-` 短文 + 33 唯一库 Skill（`knowledge/libs` 35 份源稿）+ check_dependencies 增强 + 全量反编译（jar 数待核，产物按需生成到 `$MC_SKILL_CACHE` 不入库；→ 1836 verifiedApi 键）+ API 摘要 + manifest + 通用 CLI dispatch （行内数字为完成当时实况、不回溯修订；现行值一律现读：库 Skill 见 `knowledge/libs/README.md` §当前规模，`verifiedApi` 键见 §7.5 计数口径）*
Phase 5	📋 部分	`inspect_runtime` = 日志型 inspector（非 JVM attach）；微调数据集仍暂缓

指针表（外部落点索引）

本文正文提到的外部落点全部集中在此表（本文内部章节互引不列）。用法：按「内容」查落点；第三列给触发条件与读法。

内容	落点	什么时候读 / 读法
常驻铁律（人在环 / 游玩测试门槛 / 工具边界）	`AGENTS.md`	agent 每轮开工前；其「人在环例外：游玩自测」的「已核实边界」判「这个档能不能跑 / 桥能测到什么」
MCP 安装与宿主配置（唯一说明书）	`AUTO_SETUP.md`	装 / 修 MCP 时按它的 Step 走（Step 0-pre 校验路径 → Step 6 装 Skill）；开头「Agent 必读：执行顺序」是硬约束
工具错误码：实跑取证 + 全工具覆盖清单	`doc/tool-error-codes.md`	收到 `code` / `errorKind` 先按表读；没实跑取证到的一律不写码
逐批实现史（含门与基线台账）	`mcp-server/CHANGELOG.md`	查「哪批改了什么、为什么」
语料来源 / 换源 / 逐档复测史	`CORPUS_PROVENANCE.md`	引用档位覆盖 / 语料计数前先核
游玩自测：口径 / 坑位 / 逐轮取证史（§真机台账 = 现行判据 T5 + 历史归档 T0–T4）	`community_knowledge/authored/ingame-playtest-automation.md`	跑任何一档游玩自测前先读；台账里查不到你的 combo ⇒ 按「未验证」处理，不得拿邻档外推
每轮交付底稿（编号块正文，滚动、最新在上）	`DELIVERY_LOG.md`	交接 / 夜跑 / 事后抽查；只追加、不改写历史节
交付表单（判档 + 主档四块 + 维护档六块 + 受管面清单）	`REPORT-FORMAT.md`	每轮交付写底稿前；读不到它就按 `AGENTS.md` §交付汇报三件回答并点名「缺表单」
维护面夜批回执（滚动）	`NIGHT_BATCH.md`	夜批队列与晨间抽查
债务与拍板台账（批次 / 未排期清单）	`CONTRIBUTING_LIST.md`	找「已定未做 / 等拍板」
发布增量台账（V1.0.4..HEAD 逐条）	根 `CHANGELOG.md` / `bugfix_list.md`	发版时搬进 Release 正文
贡献 / 验证纪律 / 数据链口径	`CONTRIBUTING.md`	改门、改脚本、改受管面文档前
作者规范（写给 agent 读的文档）	`WRITING-FOR-AGENTS.md`	动笔写 / 改 agent 读的文档前
社区短文使用纪律（短文不是 API 规范）	`community_knowledge/AGENT_USAGE.md`	依据短文写代码前；不确定时先打开短文给出的原文 URL
社区知识索引（主题速查完整表）	`community_knowledge/README.md`	找短文入口（发布 / 崩溃 / 软依赖 / 机器 GUI / 本地化…）
库模组 Skill 源稿（按组映射直读，不落盘）	`knowledge/libs/<组>/mc-<name>/SKILL.md`（总览 `knowledge/libs/README.md`）	库选型 / 用法；不确定选哪个 → 先读 `all-platforms/mc-lib-catalog`
工具完整语义（CLI 全局 flag 全表 / 独立 CLI 节 / 工具索引 / 安装配置）	`mcp-server/README.md`	CLI 细节、`npm run` 脚本、MCP 工具面
mcp-server 补充文档（mixin-support / vanilla-registries / registry-data-source / mc-skill-update / prompts-client-compat）	`mcp-server/docs/`	字节码校验矩阵 / Registry 数据源 / 自更新 / Prompt 兼容等专题
人类读本（多 IDE 同步清单、人话版上手）	`README_human.md`	给人看的入口；英文版 `README_human.en.md`
第三方文档与映射的许可说明	`THIRD_PARTY_NOTICES.md`	分发 / 许可问题