Minecraft Java Mod Search Skill

1. 概述

本技能帮助用户在 Minecraft Java Edition 生态中搜索和推荐模组（Mod）。支持多平台搜索、智能排序、依赖解析、版本过滤和卡片化结果展示。

2. 支持的平台

| 平台 | API 类型 | 国内可访问性 | API Key | 优先级 | |------|----------|-------------|---------|--------| | 快查表 | 本地文件 | ✅ 离线 | ❌ 不需要 | 🥇 最优先 | | Modrinth | REST API | ✅ 可裸连 | ❌ 不需要 | 🥈 主平台 | | CurseForge | REST API | ⚠️ 需 Key | ✅ 需要（免费） | 🥉 备选 | | MC百科 mcmod.cn | 网页抓取 | ✅ 国内直连 | ❌ 不需要 | 4️⃣ 兜底补充 |

策略：

快查表优先（离线命中，零延迟）

Modrinth 多关键词并行搜索（asyncio+aiohttp，超时 8s）

CurseForge 若有 API Key 则并行搜索（超时 5s）；无 Key 时在回答中提示用户如何填写

Modrinth 结果 < 3 条时，抓取 MC百科搜索页补充（超时 8s）

CurseForge API Key 配置方法

前往 https://console.curseforge.com/ 申请免费 API Key
编辑 references/curseforge_api.md，在文件末尾添加：CF_API_KEY=你的key
或设置环境变量：export CF_API_KEY=你的key
或运行时通过 --api-key 你的key 参数传入

3. 搜索参数

用户可通过以下任意维度进行单一或组合搜索：

| 参数类型 | 示例 | 说明 | |---------|------|------| | 功能描述 | "帧率优化"、"自动 farming"、"新增生物群系" | AI 解析并转换为搜索关键词 | | 模糊/精确名称 | "OptiFine" / "optif" | 支持前缀匹配和精确搜索 | | 游戏版本 | "1.20.4"、"1.19.2"、"1.18.2" | 自动过滤不兼容版本 | | 前置依赖 | "forge"、"fabric"、"rift" | 仅返回指定 Loader 的 Mod | | 类别 | "科技"、"魔法"、"生存"、"装饰"、"优化" | 按分类筛选 |

搜索优先级规则

组合搜索 > 精确名称 > 模糊名称 > 功能描述

若用户提供精确 Mod 名称，优先精确匹配，再横向扩展推荐相似 Mod
若提供功能描述，将描述拆分为关键词进行多词联合搜索
版本参数：默认返回与指定版本兼容的最新 Mod，不兼容版本自动过滤
Loader 参数：优先识别 Forge / Fabric / Quilt / Rift

4. 搜索执行流程

Step 1 — 解析用户输入

从用户描述中提取以下字段：

query: 搜索关键词（功能描述 / Mod 名称）
minecraft_version: 游戏版本（如 1.20.4）
loader: 加载器类型（forge / fabric / quilt / rift）
category: Mod 类别

若用户未指定版本，询问确认或使用当前主流版本（优先 1.20.4 / 1.21.x）。

Step 1.2 — 快查表优先命中（新功能）

在所有 API 搜索之前，先检索 references/mod_quickref.md：

search_quickref(query, version)
    │
    ├─ 命中 → 优先展示快查表结果（带 [📚 快查表] 标记）
    │         后续 API 搜索继续进行作为补充
    │
    └─ 未命中 → 继续 Step 1.5

快查表查询时同时匹配：Mod 名称、slug、功能描述、分类关键词、同义词表。

Step 1.3 — 多关键词提取（新功能）

从用户查询中提取 3-5 个候选搜索词，并行发起搜索：

keywords = _extract_keywords(query)
# 示例：query="自然生成的中立幸存者 NPC"
# 提取：["survivor", "npc", "neutral", "spawn"]

提取策略：

中文词通过 _CN_EN_MAP 映射为英文
保留查询中的英文词
最多 5 个候选词，去重

Step 1.5 — 枪械意图检测与 TACZ 优先搜索

当检测到用户查询涉及枪械/武器类需求时，优先使用 TACZ（Timeless and Classics Zero）枪包生态搜索，而非普通 Mod 搜索。

枪械意图关键词

以下关键词命中时自动触发 TACZ 优先模式：

| 语言 | 关键词 | |------|--------| | 中文 | 枪、枪械、枪包、枪mod、枪模组、射击、武器、手枪、步枪、狙击、霰弹、冲锋枪、机枪、左轮、燧发枪、火枪、现代战争、军事、弹药、子弹 | | 英文 | gun, firearm, weapon, pistol, rifle, sniper, shotgun, smg, machine gun, revolver, musket, gunpack, gun pack, tacz, bullet, ammo, fps, combat, warfare, military |

TACZ 优先搜索流程

用户查询 "步枪" (含枪械关键词)
    │
    ├─ detect_gun_intent(query) == True ?
    │       │
    │       ├─ Yes → search_tacz_gunpacks(query, version, loader)
    │       │         │
    │       │         ├─ 策略1: "tacz <英文关键词>" + facets=[equipment + version]
    │       │         ├─ 策略2: "tacz <英文关键词>" + facets=[version]（无分类限制）
    │       │         │
    │       │         ├─ 找到结果 → 输出 TACZ 基础 Mod + 枪包列表
    │       │         │                包含：安装路径、枪包放置说明、依赖关系
    │       │         │
    │       │         └─ 无结果 → 回退到普通 Mod 搜索（Step 2）
    │       │
    │       └─ No → 直接进入普通 Mod 搜索（Step 2）

TACZ 枪包搜索特点

| 特点 | 说明 | |------|------| | 基础 Mod | timeless-and-classics-zero（Forge 1.18.2–1.20.1），Fabric 有非官方移植 tacz-refabricated | | 枪包格式 | .zip 压缩包，放入 .minecraft/tacz/ 目录后执行 /tacz reload | | 搜索平台 | Modrinth（category=equipment），脚本自动将中文枪械词翻译为英文关键词 | | 多枪包共存 | 支持，命名空间不冲突即可同时加载 | | 依赖解析 | 自动提取枪包的 required 前置依赖并补入结果列表 |

TACZ 相关参考

详细的 TACZ 生态信息（枪包安装路径、已知枪包列表、兼容性规则）参考：references/mod_compat.md 第 12 节。

Step 1.6 — 机械/自动化意图检测与 Create 优先搜索

当检测到用户查询涉及机械、自动化、科技类需求时，优先使用 Create（机械动力）附属 mod 搜索，而非普通 Mod 搜索。

机械/自动化意图关键词

以下关键词命中时自动触发 Create 优先模式：

| 语言 | 关键词 | |------|--------| | 中文 | 机械、机械动力、自动化、传送带、齿轮、活塞、动力、轴承、铁路、火车、旋转、应力、流水线、工厂、制造、加工、搅拌、碾压、装配、机械臂、部署器、蒸汽、风车、水车 | | 英文 | create mod, create addon, conveyor, belt, gear, pulley, bearing, piston, automation, factory, assembly, mechanical, train, railway, steam, windmill, waterwheel, rotational, kinetic, stress, deployer, mixer, press, millstone |

Create 优先搜索流程

用户查询 "传送带" (含机械/自动化关键词)
    │
    ├─ detect_create_intent(query) == True ?
    │       │
    │       ├─ Yes → search_create_addons(query, version, loader)
    │       │         │
    │       │         ├─ 策略1: "create <英文关键词>" + facets=[technology + version]
    │       │         ├─ 策略2: "create <英文关键词>" + facets=[version]（无分类限制）
    │       │         │
    │       │         ├─ 找到结果 → 输出 Create 基础 Mod + 附属 mod 列表
    │       │         │                包含：功能描述、版本兼容、依赖关系
    │       │         │
    │       │         └─ 无结果 → 回退到普通 Mod 搜索（Step 2）
    │       │
    │       └─ No → 直接进入普通 Mod 搜索（Step 2）

Create 附属 mod 搜索特点

| 特点 | 说明 | |------|------| | 基础 Mod | create（Forge + Fabric 双平台），需配合 Flywheel（Forge 版） | | 附属生态 | Steam 'n' Rails、Crafts & Additions、Slice & Dice、Big Cannons、Copycats+ 等 100+ 附属 | | 搜索平台 | Modrinth（category=technology），脚本自动将中文机械词翻译为英文关键词 | | 版本支持 | 1.14.4 / 1.15.2 / 1.16.5 / 1.18.2 / 1.19.2 / 1.20.1 | | 依赖解析 | 自动提取附属 mod 的 required 前置依赖并补入结果列表 | | OptiFine 警告 | Create 与 OptiFine 不兼容，需使用 Oculus（Forge）或 Iris（Fabric） |

Create 相关参考

详细的 Create 生态信息（核心机制、已知附属 mod、兼容性规则）参考：references/mod_compat.md 第 13 节。

Step 2 — 执行多平台并发搜索（新功能：asyncio + aiohttp）

性能改进：脚本使用 asyncio + aiohttp 并发请求，多关键词并行发起，同步等待最快结果。

Modrinth（主平台）：

调用 GET https://api.modrinth.com/v2/search（并发 3-5 个关键词）
参数：query, facets=[categories, versions, loaders]，每请求超时 DEFAULT_TIMEOUT=8s
总并发超时：MULTI_SEARCH_TIMEOUT=12s
参考文档：references/modrinth_api.md

CurseForge（备选）：

调用 GET https://api.curseforge.com/v1/mods/search
参数：gameId=432, searchFilter, classId（mods=6）
参考文档：references/curseforge_api.md
⚠️ 注意：需要 X-API-Key 请求头。若未配置，在回答中明确告知用户：

"当前未设置 CurseForge API Key，已跳过该平台搜索。前往 https://console.curseforge.com/ 申请免费 Key，然后编辑 references/curseforge_api.md 填写。"

MC百科 mcmod.cn（兜底补充）：

仅在 Modrinth 搜索结果 < 3 个时触发
URL：https://www.mcmod.cn/s?key=<query>&mold=1&version=<version>
优先使用原始中文查询词（MC百科是中文数据库，中文命中率更高）
解析结果补充到搜索列表末尾，标注 [MC百科]
超时设置 8s，失败静默跳过

Step 3 — 数据合并与去重（优先级：快查表 > Modrinth > CurseForge > MC百科）

快查表命中结果放在最前面，标注 [📚 快查表]
相同 Mod 在多平台出现时，保留下载量更高的记录，并标注来源
去重规则：优先保留 Modrinth 记录（生态更活跃），其次 CurseForge

Step 4 — 依赖关系解析（默认关闭，`--deps` 参数开启）

重要变更（v2.0）：为提升搜索速度，依赖查询默认关闭。

默认模式：不额外发起 /dependencies API 请求（比 v1.0 快约 3-5x）
开启方式：脚本传入 --deps 参数，或在需要时告知用户该参数
开启后使用 asyncio 并发查询所有 Mod 的依赖，不会串行卡顿

依赖查询逻辑（开启时）：

提取 dependencies 字段
识别前置 Mod（如 Sodium → Fabric API）
若前置 Mod 未在结果中，自动调用 API 补充查询
将依赖 Mod 合并到推荐列表中，标注为 [前置依赖]

Step 5 — 智能排序

按以下权重综合评分（满分 100）：

| 维度 | 权重 | 说明 | |------|------|------| | 下载量 | 30% | 标准化到 0-100，取对数平滑 | | 更新频率 | 25% | 最近 6 个月内更新 = 100，每增加 1 年 -20 | | 评价指数 | 25% | 下载量 × 评分系数 | | 版本匹配度 | 20% | 完全匹配指定版本 = 100，邻近版本 = 60 |

Step 6 — 过滤不兼容 Mod

过滤条件：game_versions 不包含用户指定版本 → 标记为 [版本不兼容] 并降权
若 Mod 无版本标注，跳过该过滤

5. 结果展示

卡片化展示

每个 Mod 以独立卡片形式展示，结构如下：

┌─────────────────────────────────────────────┐
│  [🏷️ 类别标签]  [🔧 Loader标签]               │
│                                             │
│  Mod 名称                                   │
│  作者：<author>   发布：<date>                │
│                                             │
│  📥 下载量：<downloads>  ⭐ 收藏：<favorites>  │
│  🎮 游戏版本：<versions>                     │
│                                             │
│  简介：<description, 最多3行>               │
│                                             │
│  🔗 链接：<modrinth_link> / <cf_link>      │
│  ⚠️ 警告：<dependency_note> / <update_note>  │
└─────────────────────────────────────────────┘

特殊标注

[🔥 推荐] — 综合评分 Top 3 Mod
[⬆️ 需前置] — 存在未安装的前置依赖
[⚠️ 久未更新] — 超过 12 个月未更新
[🚫 版本不兼容] — 与指定游戏版本不兼容
[🇨🇳 国内可直连] — 来源为 Modrinth

6. 脚本工具（v2.0）

核心搜索脚本位于 scripts/search_mods.py。

v2.0 新特性：

asyncio + aiohttp 并发请求（需安装 pip install aiohttp；无 aiohttp 时自动降级到同步模式）
多关键词并行搜索（_extract_keywords 提取 3-5 个候选词）
快查表优先命中（references/mod_quickref.md）
默认不查依赖（用 --deps 开启）
CurseForge API Key 未配置时输出提示信息
Modrinth 结果 < 3 条时自动触发 MC百科补充搜索
所有请求统一设置超时时间（DEFAULT_TIMEOUT=8s），避免卡死

安装依赖

pip install aiohttp  # 强烈推荐，启用并发模式

使用方法

# 普通 Mod 搜索（async 并发，多关键词）
python scripts/search_mods.py --query "帧率优化" --version "1.20.4" --loader "fabric"
python scripts/search_mods.py --query "自然生成的中立幸存者 NPC" --version "1.20.1"

# 开启依赖查询
python scripts/search_mods.py --query "存储系统" --version "1.20.1" --deps

# TACZ 枪包搜索（自动检测枪械意图）
python scripts/search_mods.py --query "步枪" --version "1.20.1" --loader "forge"

# Create 附属 mod 搜索（自动检测机械/自动化意图）
python scripts/search_mods.py --query "传送带" --version "1.20.1"

# 整合包分析模式
python scripts/search_mods.py --modpack --query "科技包" --version "1.20.1" --loader "forge" --directions 能源 自动化 物流

参数说明

| 参数 | 默认值 | 说明 | |------|--------|------| | --query | （必填） | 搜索关键词 | | --version | 无 | Minecraft 版本，如 1.20.4 | | --loader | 无 | 加载器类型（forge/fabric/quilt） | | --platform | all | 搜索平台（modrinth/curseforge/all） | | --limit | 15 | 返回结果数量 | | --timeout | 8 | 单请求超时（秒） | | --api-key | 无 | CurseForge API Key | | --output | text | 输出格式（text/json） | | --deps | False | 开启依赖查询（默认关闭） | | --modpack | False | 启用整合包分析模式 | | --directions | 无 | 整合包各功能方向关键词（配合 --modpack） |

7. Mod 快查表（新模块）

快查表文件位于 references/mod_quickref.md，包含：

热门/经典 Mod 数据（Modrinth 热门榜 2025-05 整理）
按分类组织：前置库、性能优化、存储、机械动力、魔法、食物农业、NPC/村民、枪械、建筑装饰等
关键词同义词对照表（便于 AI 意图扩展匹配）
数据格式：- 英文名 | slug: xxx | 功能描述 | 支持加载器和版本

快查表匹配规则

| 匹配优先级 | 条件 | 加分 | |----------|------|------| | 1（最高） | Mod 名称在查询中或查询在名称中 | +100 | | 2 | slug 在查询中 | +80 | | 3 | 提取关键词命中快查表 keywords 字段 | +30/词 | | 4 | 分类名称在查询中 | +20 | | 5（扣分） | 版本不匹配 | -20 |

更新快查表

当发现有价值的新 Mod 时，在对应 ## 分类 下追加一行：

- Mod英文名 [| 中文名] | slug: slug名 | 功能描述（20字以内）| fabric/forge 版本范围

8. 版本兼容性参考

Minecraft Java Edition 主要版本及兼容性说明参考： references/mc_versions.md

9. 整合包分析模式（Modpack Analyzer）

当用户提供整合包设想（含 MC 版本 + 多功能方向）时，启用本模式。

8.1 触发条件

以下表述任一出现即触发：

"做一个整合包" / "modpack" / "整合包推荐"
"我想玩科技包" / "魔法包" / "生存包" / "工业包"
描述中包含 3 个及以上功能方向（如自动化 + 能源 + 物流 + 机器）
"这些 mod 兼容吗" / "帮我配一个包" / "推荐一个 1.20.4 的整合包"

8.2 分析流程

Step A — 解析整合包需求

从用户描述中提取：

| 字段 | 来源 | 示例 | |------|------|------| | minecraft_version | 用户明确指定或询问确认 | 1.20.4 | | loader | 用户指定或根据方向推断 | forge / fabric | | 功能方向列表 | 从描述中拆解 | ["自动化农场", "能源管理", "物流传输", "机器制造"] | | 包规模 | 从描述推断或询问 | 轻量(10-20个) / 中型(20-50个) / 大型(50+个) |

功能方向 → 关键词映射：

| 功能方向 | 搜索关键词（英文） | 对应 Mod 类别 | |---------|----------------|--------------| | 帧率优化/性能 | optimization, fps boost, performance | optimization | | 基础优化 | sodium, lithium, phosphor, ferritecore | optimization | | 自动化农场 | auto farm, mob farm, crop automation | farming, automation | | 能源管理 | energy, power, rf, eu, generator | technology, energy | | 物流传输 | logistics, pipes, item transport | technology, storage, transportation | | 机器制造/工业 | industrial, factory, machines | technology | | 魔法/法术 | magic, spells, enchantment, Thaumcraft | magic | | 新增生物 | new mobs, creatures, vanilla+ | mobs, nature | | 存储管理 | storage, inventory, warehouse | storage, organization | | 战斗增强 | combat, weapons, armor | equipment, combat | | 建筑/装饰 | building, decoration, aesthetics | decoration, construction | | 科技/红石替代 | automation, redstone, computercraft | redstone, technology | | 探索/地牢 | adventure, dungeon, exploration | adventure | | 生态/生物群系 | biomes, terrain, generation | nature, world generation | | 工具/物品 | tools, items, utility | equipment, utility | | 村民交易 | villager, trades | gameplay, economy | | 地狱/末地 | nether, end, dimensions | adventure |

Step B — 逐方向搜索最佳 Mod

对每个功能方向，按以下优先级选取最佳 Mod：

在该方向中下载量最高且版本兼容的 Mod → 标记为 [🔥 核心推荐]
补充 1-2 个功能互补的备选 Mod → 标记为 [✅ 备选]
自动查询每个推荐 Mod 的前置依赖，补入推荐列表

单方向 Mod 选取规则：

每个功能方向最多推荐 3 个 Mod（1 个核心 + 2 个备选）
优先选择同一个 Loader 下的 Mod（减少兼容性问题）
若多个 Mod 功能高度重叠（同类替代），只推荐 1 个

Step C — 整体兼容性检查

MC 版本兼容性验证：

对整合包中所有推荐 Mod 逐一验证：

for mod in all_recommended_mods:
    if target_version not in mod.game_versions:
        mark [🚫 版本不兼容: mod_name — 最高支持 version]

若存在不兼容 Mod，给出替代方案。

Mod 间兼容性矩阵检查（参考 references/mod_compat.md）：

known_conflicts = {
    ("optifine", "sodium"): "两者功能重叠，安装后会冲突",
    ("optifine", "sodium"): "两者功能重叠，安装后会冲突",
    ("optifine", "iris"): "OptiFine 着色器与 Iris 不兼容，应使用 Iris + Sodium",
    ("forge", "fabric"): "加载器不同，Mod 生态不互通，Fabric 和 Forge Mod 不可混用",
    ("applicants", "create"): "两者都修改物品处理逻辑，可能导致机械联动异常",
    ("mekanism", "ic2"): "两个能源 Mod 可能存在 EU/RF 单位冲突",
    ("ae2", "refinedstorage"): "两个存储系统不可同时启用",
    ("jade", "wthit"): "同类信息展示 Mod，仅需一个",
    ("roughly enough items", "emi"): "REI 与 EMI 功能重叠，只能选择一个",
}

check_compatibility(all_mods):
    for (mod_a, mod_b), reason in known_conflicts:
        if mod_a in selected and mod_b in selected:
            report conflict with reason

依赖完整性检查：

for mod in all_recommended_mods:
    for dep in mod.dependencies:
        if dep.required and dep.slug not in all_selected_slugs:
            auto_add_dependency(dep)
            report [⬆️ 自动补充前置: dep.name]

Step D — 整合包规划输出

最终输出包含以下部分：

1. 整合包概览

┌─────────────────────────────────────────────────┐
│  🎮 整合包规划报告                               │
│  版本: 1.20.4  |  加载器: Forge  |  规模: 中型   │
│  功能方向: 自动化农场 / 能源管理 / 物流传输       │
└─────────────────────────────────────────────────┘

2. 分模块推荐卡片

按功能方向分组展示，每个方向的 Mod 卡片后接兼容性说明。

3. 兼容性总览表

| Mod A | Mod B | 兼容状态 | 说明 | |-------|-------|---------|------| | Sodium | Lithium | ✅ 兼容 | 无冲突，均为优化 Mod | | Create | Mekanism | ✅ 兼容 | 可联动，推荐使用 Create 管道连接 | | AE2 | Refined Storage | ❌ 冲突 | 两者均为存储系统，不可同时安装 | | OptiFine | Sodium | ⚠️ 替代关系 | 功能重叠，应选择 Sodium（Fabric 生态）或 OptiFine（Forge 生态）|

4. 安装顺序建议

按依赖层级给出推荐安装顺序：

安装顺序（按此顺序安装，避免启动崩溃）：

[1] 前置依赖层
    ├── Fabric API / Architectury API
    └── Cloth Config API

[2] 核心优化层
    ├── Sodium（帧率优化）
    ├── Lithium（物理/AI 优化）
    └── Phosphor（光照优化）

[3] 功能层
    ├── Storage Drawers（存储）
    ├── Create（机械自动化）
    └── Mekanism（能源管理）

[4] UI/辅助层
    ├── Jade（信息展示）
    └── REI（物品查看）

5. 警告与注意事项

[❌ 冲突] 开头的行列出所有不可兼容的 Mod 组合
[⚠️ 注意] 开头列出可能的兼容性问题
[💡 建议] 开头给出优化建议（如轻量化方案）

9. 脚本工具