本技能帮助用户在 Minecraft Java Edition 生态中搜索和推荐模组(Mod)。支持多平台搜索、智能排序、依赖解析、版本过滤和卡片化结果展示。
平台API 类型国内可访问性API Key优先级快查表本地文件✅ 离线❌ 不需要🥇 最优先ModrinthREST API✅ 可裸连❌ 不需要🥈 主平台CurseForgeREST API⚠️ 需 Key✅ 需要(免费)🥉 备选MC百科 mcmod.cn网页抓取✅ 国内直连❌ 不需要4️⃣ 兜底补充
策略:
- 快查表优先(离线命中,零延迟)
- Modrinth 多关键词并行搜索(asyncio+aiohttp,超时 8s)
- CurseForge 若有 API Key 则并行搜索(超时 5s); 无 Key 时在回答中提示用户如何填写
- Modrinth 结果 < 3 条时,抓取 MC百科搜索页补充(超时 8s)
references/curseforge_api.md,在文件末尾添加: CF_API_KEY=你的keyexport CF_API_KEY=你的key--api-key 你的key 参数传入用户可通过以下任意维度进行单一或组合搜索:
参数类型示例说明功能描述"帧率优化"、"自动 farming"、"新增生物群系"AI 解析并转换为搜索关键词模糊/精确名称"OptiFine" / "optif"支持前缀匹配和精确搜索游戏版本"1.20.4"、"1.19.2"、"1.18.2"自动过滤不兼容版本前置依赖"forge"、"fabric"、"rift"仅返回指定 Loader 的 Mod类别"科技"、"魔法"、"生存"、"装饰"、"优化"按分类筛选
text
组合搜索 > 精确名称 > 模糊名称 > 功能描述
从用户描述中提取以下字段:
query: 搜索关键词(功能描述 / Mod 名称)minecraft_version: 游戏版本(如 1.20.4)loader: 加载器类型(forge / fabric / quilt / rift)category: Mod 类别若用户未指定版本,询问确认或使用当前主流版本(优先 1.20.4 / 1.21.x)。
在所有 API 搜索之前, 先检索 references/mod_quickref.md:
text
search_quickref(query, version)
│
├─ 命中 → 优先展示快查表结果(带 [📚 快查表] 标记)
│ 后续 API 搜索继续进行作为补充
│
└─ 未命中 → 继续 Step 1.5
快查表查询时同时匹配:Mod 名称、slug、功能描述、分类关键词、同义词表。
从用户查询中提取 3-5 个候选搜索词,并行发起搜索:
python
keywords = _extract_keywords(query)
# 示例:query="自然生成的中立幸存者 NPC"
# 提取:["survivor", "npc", "neutral", "spawn"]
提取策略:
_CN_EN_MAP 映射为英文当检测到用户查询涉及枪械/武器类需求时,优先使用 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
text
用户查询 "步枪" (含枪械关键词)
│
├─ 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)
特点说明基础 Modtimeless-and-classics-zero(Forge 1.18.2–1.20.1),Fabric 有非官方移植 tacz-refabricated枪包格式.zip 压缩包,放入 .minecraft/tacz/ 目录后执行 /tacz reload搜索平台Modrinth(category= equipment),脚本自动将中文枪械词翻译为英文关键词多枪包共存支持,命名空间不冲突即可同时加载依赖解析自动提取枪包的 required 前置依赖并补入结果列表
详细的 TACZ 生态信息(枪包安装路径、已知枪包列表、兼容性规则)参考: references/mod_compat.md 第 12 节。
当检测到用户查询涉及机械、自动化、科技类需求时,优先使用 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
text
用户查询 "传送带" (含机械/自动化关键词)
│
├─ 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)
特点说明基础 Modcreate(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 生态信息(核心机制、已知附属 mod、兼容性规则)参考: references/mod_compat.md 第 13 节。
性能改进:脚本使用 asyncio + aiohttp 并发请求,多关键词并行发起,同步等待最快结果。
Modrinth(主平台):
GET https://api.modrinth.com/v2/search(并发 3-5 个关键词)query, facets=[categories, versions, loaders],每请求超时 DEFAULT_TIMEOUT=8sMULTI_SEARCH_TIMEOUT=12sreferences/modrinth_api.mdCurseForge(备选):
调用 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(兜底补充):
https://www.mcmod.cn/s?key=<query>&mold=1&version=<version>[MC百科][📚 快查表]--deps 参数开启)#重要变更(v2.0):为提升搜索速度,依赖查询 默认关闭。
/dependencies API 请求(比 v1.0 快约 3-5x)--deps 参数,或在需要时告知用户该参数依赖查询逻辑(开启时):
dependencies 字段[前置依赖]按以下权重综合评分(满分 100):
维度权重说明下载量30%标准化到 0-100,取对数平滑更新频率25%最近 6 个月内更新 = 100,每增加 1 年 -20评价指数25%下载量 × 评分系数版本匹配度20%完全匹配指定版本 = 100,邻近版本 = 60
game_versions 不包含用户指定版本 → 标记为 [版本不兼容] 并降权每个 Mod 以独立卡片形式展示,结构如下:
text
┌─────────────────────────────────────────────┐
│ [🏷️ 类别标签] [🔧 Loader标签] │
│ │
│ Mod 名称 │
│ 作者:<author> 发布:<date> │
│ │
│ 📥 下载量:<downloads> ⭐ 收藏:<favorites> │
│ 🎮 游戏版本:<versions> │
│ │
│ 简介:<description, 最多3行> │
│ │
│ 🔗 链接:<modrinth_link> / <cf_link> │
│ ⚠️ 警告:<dependency_note> / <update_note> │
└─────────────────────────────────────────────┘
[🔥 推荐] — 综合评分 Top 3 Mod[⬆️ 需前置] — 存在未安装的前置依赖[⚠️ 久未更新] — 超过 12 个月未更新[🚫 版本不兼容] — 与指定游戏版本不兼容[🇨🇳 国内可直连] — 来源为 Modrinth核心搜索脚本位于 scripts/search_mods.py。
v2.0 新特性:
asyncio + aiohttp 并发请求(需安装 pip install aiohttp;无 aiohttp 时自动降级到同步模式)_extract_keywords 提取 3-5 个候选词)references/mod_quickref.md)--deps 开启)DEFAULT_TIMEOUT=8s),避免卡死bash
pip install aiohttp # 强烈推荐,启用并发模式
bash
# 普通 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)--platformall搜索平台(modrinth/curseforge/all)--limit15返回结果数量--timeout8单请求超时(秒)--api-key无CurseForge API Key--outputtext输出格式(text/json)--depsFalse开启依赖查询(默认关闭)--modpackFalse启用整合包分析模式--directions无整合包各功能方向关键词(配合 --modpack)
快查表文件位于 references/mod_quickref.md,包含:
- 英文名 | slug: xxx | 功能描述 | 支持加载器和版本匹配优先级条件加分1(最高)Mod 名称在查询中或查询在名称中+1002slug 在查询中+803提取关键词命中快查表 keywords 字段+30/词4分类名称在查询中+205(扣分)版本不匹配-20
当发现有价值的新 Mod 时,在对应 ## 分类 下追加一行:
markdown
- Mod英文名 [| 中文名] | slug: slug名 | 功能描述(20字以内)| fabric/forge 版本范围
Minecraft Java Edition 主要版本及兼容性说明参考:
references/mc_versions.md
当用户提供 整合包设想(含 MC 版本 + 多功能方向)时,启用本模式。
以下表述任一出现即触发:
从用户描述中提取:
字段来源示例minecraft_version用户明确指定或询问确认1.20.4``loader用户指定或根据方向推断forge / fabric``功能方向列表从描述中拆解["自动化农场", "能源管理", "物流传输", "机器制造"]``包规模从描述推断或询问轻量(10-20个) / 中型(20-50个) / 大型(50+个)
功能方向 → 关键词映射:
功能方向搜索关键词(英文)对应 Mod 类别帧率优化/性能optimization, fps boost, performanceoptimization基础优化sodium, lithium, phosphor, ferritecoreoptimization自动化农场auto farm, mob farm, crop automationfarming, automation能源管理energy, power, rf, eu, generatortechnology, energy物流传输logistics, pipes, item transporttechnology, storage, transportation机器制造/工业industrial, factory, machinestechnology魔法/法术magic, spells, enchantment, Thaumcraftmagic新增生物new mobs, creatures, vanilla+mobs, nature存储管理storage, inventory, warehousestorage, organization战斗增强combat, weapons, armorequipment, combat建筑/装饰building, decoration, aestheticsdecoration, construction科技/红石替代automation, redstone, computercraftredstone, technology探索/地牢adventure, dungeon, explorationadventure生态/生物群系biomes, terrain, generationnature, world generation工具/物品tools, items, utilityequipment, utility村民交易villager, tradesgameplay, economy地狱/末地nether, end, dimensionsadventure
对每个功能方向,按以下优先级选取最佳 Mod:
[🔥 核心推荐][✅ 备选]单方向 Mod 选取规则:
MC 版本兼容性验证:
对整合包中所有推荐 Mod 逐一验证:
text
for mod in all_recommended_mods:
if target_version not in mod.game_versions:
mark [🚫 版本不兼容: mod_name — 最高支持 version]
若存在不兼容 Mod,给出 替代方案。
Mod 间兼容性矩阵检查(参考 references/mod_compat.md):
text
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
依赖完整性检查:
text
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]
最终输出包含以下部分:
1. 整合包概览
text
┌─────────────────────────────────────────────────┐
│ 🎮 整合包规划报告 │
│ 版本: 1.20.4 | 加载器: Forge | 规模: 中型 │
│ 功能方向: 自动化农场 / 能源管理 / 物流传输 │
└─────────────────────────────────────────────────┘
2. 分模块推荐卡片
按功能方向分组展示,每个方向的 Mod 卡片后接兼容性说明。
3. 兼容性总览表
Mod AMod B兼容状态说明SodiumLithium✅ 兼容无冲突,均为优化 ModCreateMekanism✅ 兼容可联动,推荐使用 Create 管道连接AE2Refined Storage❌ 冲突两者均为存储系统,不可同时安装OptiFineSodium⚠️ 替代关系功能重叠,应选择 Sodium(Fabric 生态)或 OptiFine(Forge 生态)
4. 安装顺序建议
按依赖层级给出推荐安装顺序:
text
安装顺序(按此顺序安装,避免启动崩溃):
[1] 前置依赖层
├── Fabric API / Architectury API
└── Cloth Config API
[2] 核心优化层
├── Sodium(帧率优化)
├── Lithium(物理/AI 优化)
└── Phosphor(光照优化)
[3] 功能层
├── Storage Drawers(存储)
├── Create(机械自动化)
└── Mekanism(能源管理)
[4] UI/辅助层
├── Jade(信息展示)
└── REI(物品查看)
5. 警告与注意事项
[❌ 冲突] 开头的行列出所有不可兼容的 Mod 组合[⚠️ 注意] 开头列出可能的兼容性问题[💡 建议] 开头给出优化建议(如轻量化方案)核心搜索脚本位于 scripts/search_mods.py。
bash
# 普通 Mod 搜索
python scripts/search_mods.py --query "帧率优化" --version "1.20.4" --loader "fabric"
python scripts/search_mods.py --query "optifine" --version "1.20.1"
python scripts/search_mods.py --query "自动化" --version "1.19.2" --loader "forge"
# TACZ 枪包搜索(自动检测枪械意图)
python scripts/search_mods.py --query "步枪" --version "1.20.1" --loader "forge"
python scripts/search_mods.py --query "rifle" --version "1.20.1" --limit 5
python scripts/search_mods.py --query "狙击枪" --version "1.20.1" --output json
# Create 附属 mod 搜索(自动检测机械/自动化意图)
python scripts/search_mods.py --query "传送带" --version "1.20.1"
python scripts/search_mods.py --query "automation factory" --version "1.20.1" --limit 8
python scripts/search_mods.py --query "齿轮轴承" --version "1.20.1" --output json
--query: 搜索关键词(支持多词,用空格分隔)--version: Minecraft 版本(如 1.20.4)--loader: 加载器类型(forge / fabric / quilt)--platform: 搜索平台(modrinth / curseforge / all),默认 all--limit: 返回结果数量,默认 15--timeout: 请求超时秒数,默认 8支持 --output text(人类可读)和 --output json(JSON 格式)。
text 格式示例(含快查表命中):
text
【快查表命中 — 高可信度推荐】
★ 1. Human Companions [📚 快查表]
添加中立幸存者 NPC,可自然生成于世界中
Modrinth: https://modrinth.com/mod/human-companions
【API 搜索结果】
▶ 1. Easy NPC [🔥 TOP推荐]
...
Minecraft Java Edition 主要版本及兼容性说明参考:
references/mc_versions.md
Mod 之间已知冲突与兼容关系参考:
references/mod_compat.md
--deps 参数[⚠️ 久未更新]