\r \r

Minecraft Java Mod Search Skill\r

\r

1. 概述\r

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

2. 支持的平台\r

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

策略：\r

1. 快查表优先（离线命中，零延迟）\r
2. Modrinth 多关键词并行搜索（asyncio+aiohttp，超时 8s）\r
3. CurseForge 若有 API Key 则并行搜索（超时 5s）；无 Key 时在回答中提示用户如何填写\r
4. Modrinth 结果 \x3C 3 条时，抓取 MC百科搜索页补充（超时 8s）\r \r

CurseForge API Key 配置方法\r

\r

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

3. 搜索参数\r

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

搜索优先级规则\r

\r

组合搜索 > 精确名称 > 模糊名称 > 功能描述\r
```\r
\r
- 若用户提供精确 Mod 名称，优先精确匹配，再横向扩展推荐相似 Mod\r
- 若提供功能描述，将描述拆分为关键词进行多词联合搜索\r
- 版本参数：默认返回与指定版本兼容的最新 Mod，**不兼容版本自动过滤**\r
- Loader 参数：优先识别 Forge / Fabric / Quilt / Rift\r
\r
## 4. 搜索执行流程\r
\r
### Step 1 — 解析用户输入\r
\r
从用户描述中提取以下字段：\r
\r
- `query`: 搜索关键词（功能描述 / Mod 名称）\r
- `minecraft_version`: 游戏版本（如 1.20.4）\r
- `loader`: 加载器类型（forge / fabric / quilt / rift）\r
- `category`: Mod 类别\r
\r
若用户未指定版本，询问确认或使用当前主流版本（优先 1.20.4 / 1.21.x）。\r
\r
### Step 1.2 — 快查表优先命中（新功能）\r
\r
在所有 API 搜索之前，**先检索 `references/mod_quickref.md`**：\r
\r
```\r
search_quickref(query, version)\r
    │\r
    ├─ 命中 → 优先展示快查表结果（带 [📚 快查表] 标记）\r
    │         后续 API 搜索继续进行作为补充\r
    │\r
    └─ 未命中 → 继续 Step 1.5\r
```\r
\r
快查表查询时同时匹配：Mod 名称、slug、功能描述、分类关键词、同义词表。\r
\r
### Step 1.3 — 多关键词提取（新功能）\r
\r
从用户查询中提取 **3-5 个候选搜索词**，并行发起搜索：\r
\r
```python\r
keywords = _extract_keywords(query)\r
# 示例：query="自然生成的中立幸存者 NPC"\r
# 提取：["survivor", "npc", "neutral", "spawn"]\r
```\r
\r
提取策略：\r
- 中文词通过 `_CN_EN_MAP` 映射为英文\r
- 保留查询中的英文词\r
- 最多 5 个候选词，去重\r
\r
### Step 1.5 — 枪械意图检测与 TACZ 优先搜索\r
\r
**当检测到用户查询涉及枪械/武器类需求时**，优先使用 TACZ（Timeless and Classics Zero）枪包生态搜索，而非普通 Mod 搜索。\r
\r
#### 枪械意图关键词\r
\r
以下关键词命中时自动触发 TACZ 优先模式：\r
\r
| 语言 | 关键词 |\r
|------|--------|\r
| 中文 | 枪、枪械、枪包、枪mod、枪模组、射击、武器、手枪、步枪、狙击、霰弹、冲锋枪、机枪、左轮、燧发枪、火枪、现代战争、军事、弹药、子弹 |\r
| 英文 | gun, firearm, weapon, pistol, rifle, sniper, shotgun, smg, machine gun, revolver, musket, gunpack, gun pack, tacz, bullet, ammo, fps, combat, warfare, military |\r
\r
#### TACZ 优先搜索流程\r
\r
```\r
用户查询 "步枪" (含枪械关键词)\r
    │\r
    ├─ detect_gun_intent(query) == True ?\r
    │       │\r
    │       ├─ Yes → search_tacz_gunpacks(query, version, loader)\r
    │       │         │\r
    │       │         ├─ 策略1: "tacz \x3C英文关键词>" + facets=[equipment + version]\r
    │       │         ├─ 策略2: "tacz \x3C英文关键词>" + facets=[version]（无分类限制）\r
    │       │         │\r
    │       │         ├─ 找到结果 → 输出 TACZ 基础 Mod + 枪包列表\r
    │       │         │                包含：安装路径、枪包放置说明、依赖关系\r
    │       │         │\r
    │       │         └─ 无结果 → 回退到普通 Mod 搜索（Step 2）\r
    │       │\r
    │       └─ No → 直接进入普通 Mod 搜索（Step 2）\r
```\r
\r
#### TACZ 枪包搜索特点\r
\r
| 特点 | 说明 |\r
|------|------|\r
| **基础 Mod** | `timeless-and-classics-zero`（Forge 1.18.2–1.20.1），Fabric 有非官方移植 `tacz-refabricated` |\r
| **枪包格式** | `.zip` 压缩包，放入 `.minecraft/tacz/` 目录后执行 `/tacz reload` |\r
| **搜索平台** | Modrinth（category=`equipment`），脚本自动将中文枪械词翻译为英文关键词 |\r
| **多枪包共存** | 支持，命名空间不冲突即可同时加载 |\r
| **依赖解析** | 自动提取枪包的 required 前置依赖并补入结果列表 |\r
\r
#### TACZ 相关参考\r
\r
详细的 TACZ 生态信息（枪包安装路径、已知枪包列表、兼容性规则）参考：`references/mod_compat.md` 第 12 节。\r
\r
### Step 1.6 — 机械/自动化意图检测与 Create 优先搜索\r
\r
**当检测到用户查询涉及机械、自动化、科技类需求时**，优先使用 Create（机械动力）附属 mod 搜索，而非普通 Mod 搜索。\r
\r
#### 机械/自动化意图关键词\r
\r
以下关键词命中时自动触发 Create 优先模式：\r
\r
| 语言 | 关键词 |\r
|------|--------|\r
| 中文 | 机械、机械动力、自动化、传送带、齿轮、活塞、动力、轴承、铁路、火车、旋转、应力、流水线、工厂、制造、加工、搅拌、碾压、装配、机械臂、部署器、蒸汽、风车、水车 |\r
| 英文 | 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 |\r
\r
#### Create 优先搜索流程\r
\r
```\r
用户查询 "传送带" (含机械/自动化关键词)\r
    │\r
    ├─ detect_create_intent(query) == True ?\r
    │       │\r
    │       ├─ Yes → search_create_addons(query, version, loader)\r
    │       │         │\r
    │       │         ├─ 策略1: "create \x3C英文关键词>" + facets=[technology + version]\r
    │       │         ├─ 策略2: "create \x3C英文关键词>" + facets=[version]（无分类限制）\r
    │       │         │\r
    │       │         ├─ 找到结果 → 输出 Create 基础 Mod + 附属 mod 列表\r
    │       │         │                包含：功能描述、版本兼容、依赖关系\r
    │       │         │\r
    │       │         └─ 无结果 → 回退到普通 Mod 搜索（Step 2）\r
    │       │\r
    │       └─ No → 直接进入普通 Mod 搜索（Step 2）\r
```\r
\r
#### Create 附属 mod 搜索特点\r
\r
| 特点 | 说明 |\r
|------|------|\r
| **基础 Mod** | `create`（Forge + Fabric 双平台），需配合 Flywheel（Forge 版） |\r
| **附属生态** | Steam 'n' Rails、Crafts & Additions、Slice & Dice、Big Cannons、Copycats+ 等 100+ 附属 |\r
| **搜索平台** | Modrinth（category=`technology`），脚本自动将中文机械词翻译为英文关键词 |\r
| **版本支持** | 1.14.4 / 1.15.2 / 1.16.5 / 1.18.2 / 1.19.2 / 1.20.1 |\r
| **依赖解析** | 自动提取附属 mod 的 required 前置依赖并补入结果列表 |\r
| **OptiFine 警告** | Create 与 OptiFine 不兼容，需使用 Oculus（Forge）或 Iris（Fabric） |\r
\r
#### Create 相关参考\r
\r
详细的 Create 生态信息（核心机制、已知附属 mod、兼容性规则）参考：`references/mod_compat.md` 第 13 节。\r
\r
### Step 2 — 执行多平台并发搜索（新功能：asyncio + aiohttp）\r
\r
**性能改进**：脚本使用 asyncio + aiohttp 并发请求，多关键词并行发起，同步等待最快结果。\r
\r
**Modrinth（主平台）**：\r
- 调用 `GET https://api.modrinth.com/v2/search`（并发 3-5 个关键词）\r
- 参数：`query`, `facets=[categories, versions, loaders]`，每请求超时 `DEFAULT_TIMEOUT=8s`\r
- 总并发超时：`MULTI_SEARCH_TIMEOUT=12s`\r
- 参考文档：`references/modrinth_api.md`\r
\r
**CurseForge（备选）**：\r
- 调用 `GET https://api.curseforge.com/v1/mods/search`\r
- 参数：`gameId=432`, `searchFilter`, `classId`（mods=6）\r
- 参考文档：`references/curseforge_api.md`\r
- **⚠️ 注意**：需要 `X-API-Key` 请求头。若未配置，**在回答中明确告知用户**：\r
  > "当前未设置 CurseForge API Key，已跳过该平台搜索。前往 https://console.curseforge.com/ 申请免费 Key，然后编辑 `references/curseforge_api.md` 填写。"\r
\r
**MC百科 mcmod.cn（兜底补充）**：\r
- **仅在 Modrinth 搜索结果 \x3C 3 个时触发**\r
- URL：`https://www.mcmod.cn/s?key=\x3Cquery>&mold=1&version=\x3Cversion>`\r
- 优先使用原始中文查询词（MC百科是中文数据库，中文命中率更高）\r
- 解析结果补充到搜索列表末尾，标注 `[MC百科]`\r
- 超时设置 8s，失败静默跳过\r
\r
### Step 3 — 数据合并与去重（优先级：快查表 > Modrinth > CurseForge > MC百科）\r
\r
- 快查表命中结果放在最前面，标注 `[📚 快查表]`\r
- 相同 Mod 在多平台出现时，保留下载量更高的记录，并标注来源\r
- **去重规则**：优先保留 Modrinth 记录（生态更活跃），其次 CurseForge\r
\r
### Step 4 — 依赖关系解析（默认关闭，`--deps` 参数开启）\r
\r
**重要变更（v2.0）**：为提升搜索速度，依赖查询**默认关闭**。\r
\r
- 默认模式：不额外发起 `/dependencies` API 请求（比 v1.0 快约 3-5x）\r
- 开启方式：脚本传入 `--deps` 参数，或在需要时告知用户该参数\r
- 开启后使用 asyncio 并发查询所有 Mod 的依赖，不会串行卡顿\r
\r
**依赖查询逻辑（开启时）**：\r
\r
1. 提取 `dependencies` 字段\r
2. 识别前置 Mod（如 Sodium → Fabric API）\r
3. 若前置 Mod 未在结果中，自动调用 API 补充查询\r
4. 将依赖 Mod 合并到推荐列表中，标注为 `[前置依赖]`\r
\r
### Step 5 — 智能排序\r
\r
按以下权重综合评分（满分 100）：\r
\r
| 维度 | 权重 | 说明 |\r
|------|------|------|\r
| **下载量** | 30% | 标准化到 0-100，取对数平滑 |\r
| **更新频率** | 25% | 最近 6 个月内更新 = 100，每增加 1 年 -20 |\r
| **评价指数** | 25% | 下载量 × 评分系数 |\r
| **版本匹配度** | 20% | 完全匹配指定版本 = 100，邻近版本 = 60 |\r
\r
### Step 6 — 过滤不兼容 Mod\r
\r
- 过滤条件：`game_versions` 不包含用户指定版本 → 标记为 `[版本不兼容]` 并降权\r
- 若 Mod 无版本标注，跳过该过滤\r
\r
## 5. 结果展示\r
\r
### 卡片化展示\r
\r
每个 Mod 以独立卡片形式展示，结构如下：\r
\r
```\r
┌─────────────────────────────────────────────┐\r
│  [🏷️ 类别标签]  [🔧 Loader标签]               │\r
│                                             │\r
│  Mod 名称                                   │\r
│  作者：\x3Cauthor>   发布：\x3Cdate>                │\r
│                                             │\r
│  📥 下载量：\x3Cdownloads>  ⭐ 收藏：\x3Cfavorites>  │\r
│  🎮 游戏版本：\x3Cversions>                     │\r
│                                             │\r
│  简介：\x3Cdescription, 最多3行>               │\r
│                                             │\r
│  🔗 链接：\x3Cmodrinth_link> / \x3Ccf_link>      │\r
│  ⚠️ 警告：\x3Cdependency_note> / \x3Cupdate_note>  │\r
└─────────────────────────────────────────────┘\r
```\r
\r
### 特殊标注\r
\r
- `[🔥 推荐]` — 综合评分 Top 3 Mod\r
- `[⬆️ 需前置]` — 存在未安装的前置依赖\r
- `[⚠️ 久未更新]` — 超过 12 个月未更新\r
- `[🚫 版本不兼容]` — 与指定游戏版本不兼容\r
- `[🇨🇳 国内可直连]` — 来源为 Modrinth\r
\r
### 推荐排序输出顺序\r
\r
1. 🔥 综合评分 Top 3（带推荐理由）\r
2. ✅ 版本兼容 + 无需依赖的 Mod\r
3. ⬆️ 需要前置依赖的 Mod（依赖也需安装）\r
4. ⚠️ 久未更新的 Mod（低优先级）\r
\r
## 6. 脚本工具（v2.0）\r
\r
核心搜索脚本位于 `scripts/search_mods.py`。\r
\r
**v2.0 新特性**：\r
- `asyncio + aiohttp` 并发请求（需安装 `pip install aiohttp`；无 aiohttp 时自动降级到同步模式）\r
- 多关键词并行搜索（`_extract_keywords` 提取 3-5 个候选词）\r
- 快查表优先命中（`references/mod_quickref.md`）\r
- 默认不查依赖（用 `--deps` 开启）\r
- CurseForge API Key 未配置时输出提示信息\r
- Modrinth 结果 \x3C 3 条时自动触发 MC百科补充搜索\r
- 所有请求统一设置超时时间（`DEFAULT_TIMEOUT=8s`），避免卡死\r
\r
### 安装依赖\r
\r
```bash\r
pip install aiohttp  # 强烈推荐，启用并发模式\r
```\r
\r
### 使用方法\r
\r
```bash\r
# 普通 Mod 搜索（async 并发，多关键词）\r
python scripts/search_mods.py --query "帧率优化" --version "1.20.4" --loader "fabric"\r
python scripts/search_mods.py --query "自然生成的中立幸存者 NPC" --version "1.20.1"\r
\r
# 开启依赖查询\r
python scripts/search_mods.py --query "存储系统" --version "1.20.1" --deps\r
\r
# TACZ 枪包搜索（自动检测枪械意图）\r
python scripts/search_mods.py --query "步枪" --version "1.20.1" --loader "forge"\r
\r
# Create 附属 mod 搜索（自动检测机械/自动化意图）\r
python scripts/search_mods.py --query "传送带" --version "1.20.1"\r
\r
# 整合包分析模式\r
python scripts/search_mods.py --modpack --query "科技包" --version "1.20.1" --loader "forge" --directions 能源 自动化 物流\r
```\r
\r
### 参数说明\r
\r
| 参数 | 默认值 | 说明 |\r
|------|--------|------|\r
| `--query` | （必填） | 搜索关键词 |\r
| `--version` | 无 | Minecraft 版本，如 1.20.4 |\r
| `--loader` | 无 | 加载器类型（forge/fabric/quilt） |\r
| `--platform` | all | 搜索平台（modrinth/curseforge/all） |\r
| `--limit` | 15 | 返回结果数量 |\r
| `--timeout` | 8 | 单请求超时（秒） |\r
| `--api-key` | 无 | CurseForge API Key |\r
| `--output` | text | 输出格式（text/json） |\r
| `--deps` | False | **开启依赖查询**（默认关闭） |\r
| `--modpack` | False | 启用整合包分析模式 |\r
| `--directions` | 无 | 整合包各功能方向关键词（配合 --modpack） |\r
\r
## 7. Mod 快查表（新模块）\r
\r
快查表文件位于 `references/mod_quickref.md`，包含：\r
\r
- **热门/经典 Mod 数据**（Modrinth 热门榜 2025-05 整理）\r
- **按分类组织**：前置库、性能优化、存储、机械动力、魔法、食物农业、NPC/村民、枪械、建筑装饰等\r
- **关键词同义词对照表**（便于 AI 意图扩展匹配）\r
- **数据格式**：`- 英文名 | slug: xxx | 功能描述 | 支持加载器和版本`\r
\r
### 快查表匹配规则\r
\r
| 匹配优先级 | 条件 | 加分 |\r
|----------|------|------|\r
| 1（最高） | Mod 名称在查询中或查询在名称中 | +100 |\r
| 2 | slug 在查询中 | +80 |\r
| 3 | 提取关键词命中快查表 keywords 字段 | +30/词 |\r
| 4 | 分类名称在查询中 | +20 |\r
| 5（扣分） | 版本不匹配 | -20 |\r
\r
### 更新快查表\r
\r
当发现有价值的新 Mod 时，在对应 `## 分类` 下追加一行：\r
\r
```markdown\r
- Mod英文名 [| 中文名] | slug: slug名 | 功能描述（20字以内）| fabric/forge 版本范围\r
```\r
\r
## 8. 版本兼容性参考\r
\r
Minecraft Java Edition 主要版本及兼容性说明参考：\r
`references/mc_versions.md`\r
\r
## 9. 整合包分析模式（Modpack Analyzer）\r
\r
当用户提供**整合包设想**（含 MC 版本 + 多功能方向）时，启用本模式。\r
\r
### 8.1 触发条件\r
\r
以下表述任一出现即触发：\r
\r
- "做一个整合包" / "modpack" / "整合包推荐"\r
- "我想玩科技包" / "魔法包" / "生存包" / "工业包"\r
- 描述中包含 **3 个及以上功能方向**（如自动化 + 能源 + 物流 + 机器）\r
- "这些 mod 兼容吗" / "帮我配一个包" / "推荐一个 1.20.4 的整合包"\r
\r
### 8.2 分析流程\r
\r
#### Step A — 解析整合包需求\r
\r
从用户描述中提取：\r
\r
| 字段 | 来源 | 示例 |\r
|------|------|------|\r
| `minecraft_version` | 用户明确指定或询问确认 | `1.20.4` |\r
| `loader` | 用户指定或根据方向推断 | `forge` / `fabric` |\r
| `功能方向列表` | 从描述中拆解 | `["自动化农场", "能源管理", "物流传输", "机器制造"]` |\r
| `包规模` | 从描述推断或询问 | `轻量(10-20个)` / `中型(20-50个)` / `大型(50+个)` |\r
\r
**功能方向 → 关键词映射**：\r
\r
| 功能方向 | 搜索关键词（英文） | 对应 Mod 类别 |\r
|---------|----------------|--------------|\r
| 帧率优化/性能 | optimization, fps boost, performance | optimization |\r
| 基础优化 | sodium, lithium, phosphor, ferritecore | optimization |\r
| 自动化农场 | auto farm, mob farm, crop automation | farming, automation |\r
| 能源管理 | energy, power, rf, eu, generator | technology, energy |\r
| 物流传输 | logistics, pipes, item transport | technology, storage, transportation |\r
| 机器制造/工业 | industrial, factory, machines | technology |\r
| 魔法/法术 | magic, spells, enchantment, Thaumcraft | magic |\r
| 新增生物 | new mobs, creatures, vanilla+ | mobs, nature |\r
| 存储管理 | storage, inventory, warehouse | storage, organization |\r
| 战斗增强 | combat, weapons, armor | equipment, combat |\r
| 建筑/装饰 | building, decoration, aesthetics | decoration, construction |\r
| 科技/红石替代 | automation, redstone, computercraft | redstone, technology |\r
| 探索/地牢 | adventure, dungeon, exploration | adventure |\r
| 生态/生物群系 | biomes, terrain, generation | nature, world generation |\r
| 工具/物品 | tools, items, utility | equipment, utility |\r
| 村民交易 | villager, trades | gameplay, economy |\r
| 地狱/末地 | nether, end, dimensions | adventure |\r
\r
#### Step B — 逐方向搜索最佳 Mod\r
\r
对每个功能方向，按以下优先级选取最佳 Mod：\r
\r
1. 在该方向中**下载量最高**且**版本兼容**的 Mod → 标记为 `[🔥 核心推荐]`\r
2. 补充 1-2 个**功能互补**的备选 Mod → 标记为 `[✅ 备选]`\r
3. 自动查询每个推荐 Mod 的**前置依赖**，补入推荐列表\r
\r
**单方向 Mod 选取规则**：\r
\r
- 每个功能方向最多推荐 **3 个 Mod**（1 个核心 + 2 个备选）\r
- 优先选择**同一个 Loader** 下的 Mod（减少兼容性问题）\r
- 若多个 Mod 功能高度重叠（同类替代），只推荐 1 个\r
\r
#### Step C — 整体兼容性检查\r
\r
**MC 版本兼容性验证**：\r
\r
对整合包中所有推荐 Mod 逐一验证：\r
\r
```\r
for mod in all_recommended_mods:\r
    if target_version not in mod.game_versions:\r
        mark [🚫 版本不兼容: mod_name — 最高支持 version]\r
```\r
\r
若存在不兼容 Mod，给出**替代方案**。\r
\r
**Mod 间兼容性矩阵检查**（参考 `references/mod_compat.md`）：\r
\r
```\r
known_conflicts = {\r
    ("optifine", "sodium"): "两者功能重叠，安装后会冲突",\r
    ("optifine", "sodium"): "两者功能重叠，安装后会冲突",\r
    ("optifine", "iris"): "OptiFine 着色器与 Iris 不兼容，应使用 Iris + Sodium",\r
    ("forge", "fabric"): "加载器不同，Mod 生态不互通，Fabric 和 Forge Mod 不可混用",\r
    ("applicants", "create"): "两者都修改物品处理逻辑，可能导致机械联动异常",\r
    ("mekanism", "ic2"): "两个能源 Mod 可能存在 EU/RF 单位冲突",\r
    ("ae2", "refinedstorage"): "两个存储系统不可同时启用",\r
    ("jade", "wthit"): "同类信息展示 Mod，仅需一个",\r
    ("roughly enough items", "emi"): "REI 与 EMI 功能重叠，只能选择一个",\r
}\r
\r
check_compatibility(all_mods):\r
    for (mod_a, mod_b), reason in known_conflicts:\r
        if mod_a in selected and mod_b in selected:\r
            report conflict with reason\r
```\r
\r
**依赖完整性检查**：\r
\r
```\r
for mod in all_recommended_mods:\r
    for dep in mod.dependencies:\r
        if dep.required and dep.slug not in all_selected_slugs:\r
            auto_add_dependency(dep)\r
            report [⬆️ 自动补充前置: dep.name]\r
```\r
\r
#### Step D — 整合包规划输出\r
\r
最终输出包含以下部分：\r
\r
**1. 整合包概览**\r
\r
```\r
┌─────────────────────────────────────────────────┐\r
│  🎮 整合包规划报告                               │\r
│  版本: 1.20.4  |  加载器: Forge  |  规模: 中型   │\r
│  功能方向: 自动化农场 / 能源管理 / 物流传输       │\r
└─────────────────────────────────────────────────┘\r
```\r
\r
**2. 分模块推荐卡片**\r
\r
按功能方向分组展示，每个方向的 Mod 卡片后接兼容性说明。\r
\r
**3. 兼容性总览表**\r
\r
| Mod A | Mod B | 兼容状态 | 说明 |\r
|-------|-------|---------|------|\r
| Sodium | Lithium | ✅ 兼容 | 无冲突，均为优化 Mod |\r
| Create | Mekanism | ✅ 兼容 | 可联动，推荐使用 Create 管道连接 |\r
| AE2 | Refined Storage | ❌ 冲突 | 两者均为存储系统，不可同时安装 |\r
| OptiFine | Sodium | ⚠️ 替代关系 | 功能重叠，应选择 Sodium（Fabric 生态）或 OptiFine（Forge 生态）|\r
\r
**4. 安装顺序建议**\r
\r
按依赖层级给出推荐安装顺序：\r
\r
```\r
安装顺序（按此顺序安装，避免启动崩溃）：\r
\r
[1] 前置依赖层\r
    ├── Fabric API / Architectury API\r
    └── Cloth Config API\r
\r
[2] 核心优化层\r
    ├── Sodium（帧率优化）\r
    ├── Lithium（物理/AI 优化）\r
    └── Phosphor（光照优化）\r
\r
[3] 功能层\r
    ├── Storage Drawers（存储）\r
    ├── Create（机械自动化）\r
    └── Mekanism（能源管理）\r
\r
[4] UI/辅助层\r
    ├── Jade（信息展示）\r
    └── REI（物品查看）\r
```\r
\r
**5. 警告与注意事项**\r
\r
- `[❌ 冲突]` 开头的行列出所有不可兼容的 Mod 组合\r
- `[⚠️ 注意]` 开头列出可能的兼容性问题\r
- `[💡 建议]` 开头给出优化建议（如轻量化方案）\r
\r
## 9. 脚本工具\r
\r
核心搜索脚本位于 `scripts/search_mods.py`。\r
\r
### 9.1 单 Mod 搜索\r
\r
```bash\r
# 普通 Mod 搜索\r
python scripts/search_mods.py --query "帧率优化" --version "1.20.4" --loader "fabric"\r
python scripts/search_mods.py --query "optifine" --version "1.20.1"\r
python scripts/search_mods.py --query "自动化" --version "1.19.2" --loader "forge"\r
\r
# TACZ 枪包搜索（自动检测枪械意图）\r
python scripts/search_mods.py --query "步枪" --version "1.20.1" --loader "forge"\r
python scripts/search_mods.py --query "rifle" --version "1.20.1" --limit 5\r
python scripts/search_mods.py --query "狙击枪" --version "1.20.1" --output json\r
\r
# Create 附属 mod 搜索（自动检测机械/自动化意图）\r
python scripts/search_mods.py --query "传送带" --version "1.20.1"\r
python scripts/search_mods.py --query "automation factory" --version "1.20.1" --limit 8\r
python scripts/search_mods.py --query "齿轮轴承" --version "1.20.1" --output json\r
```\r
\r
### 9.2 参数说明\r
\r
- `--query`: 搜索关键词（支持多词，用空格分隔）\r
- `--version`: Minecraft 版本（如 1.20.4）\r
- `--loader`: 加载器类型（forge / fabric / quilt）\r
- `--platform`: 搜索平台（modrinth / curseforge / all），默认 all\r
- `--limit`: 返回结果数量，默认 15\r
- `--timeout`: 请求超时秒数，默认 8\r
\r
### 9.3 输出格式\r
\r
支持 `--output text`（人类可读）和 `--output json`（JSON 格式）。\r
\r
**text 格式示例（含快查表命中）**：\r
\r
```\r
【快查表命中 — 高可信度推荐】\r
★ 1. Human Companions  [📚 快查表]\r
    添加中立幸存者 NPC，可自然生成于世界中\r
    Modrinth: https://modrinth.com/mod/human-companions\r
\r
【API 搜索结果】\r
▶ 1. Easy NPC  [🔥 TOP推荐]\r
    ...\r
```\r
\r
## 10. 版本兼容性参考\r
\r
Minecraft Java Edition 主要版本及兼容性说明参考：\r
`references/mc_versions.md`\r
\r
## 11. Mod 兼容性矩阵参考\r
\r
Mod 之间已知冲突与兼容关系参考：\r
`references/mod_compat.md`\r
\r
## 12. 注意事项\r
\r
- **避免虚假信息**：仅返回实际 API / 网页查询到的结果，不编造 Mod 数据\r
- **版本敏感性**：明确告知用户当前 Mod 兼容的版本范围，避免误导\r
- **依赖提示（按需）**：默认不查询依赖（节省时间）；若用户明确要求查看依赖，运行时加 `--deps` 参数\r
- **失效检测**：若 Mod 超过 12 个月未更新，标注 `[⚠️ 久未更新]`\r
- **中文友好**：返回给用户的内容使用中文描述\r
- **CurseForge 无 Key 时提示**：若 CurseForge API Key 未配置，**必须在回答中明确告知**用户配置方法（不可静默跳过）\r
- **整合包模式**：始终先确认 MC 版本和加载器，再进行多方向搜索和兼容性检查\r
- **诚实报告不兼容**：若用户选择的 Mod 之间确实存在冲突，必须如实报告，不可忽略或回避\r
- **枪械类 Mod → TACZ 优先**：当检测到枪械/武器需求时，优先搜索 TACZ 枪包生态，告知用户需先安装 TACZ 基础 Mod；仅当 TACZ 枪包无结果时才回退到普通 Mod 搜索\r
- **TACZ 版本限制**：TACZ 官方版仅支持 Forge 1.18.2–1.20.1；若用户使用 Fabric 或更高 MC 版本，需提示关注社区移植版\r
- **机械/自动化类 Mod → Create 优先**：当检测到机械、自动化、科技需求时，优先搜索 Create 附属 mod 生态，告知用户需先安装 Create 基础 Mod；仅当 Create 附属无结果时才回退到普通 Mod 搜索\r
- **Create 与 OptiFine 互斥**：Create 依赖 Flywheel 渲染引擎，与 OptiFine 不兼容；Forge 环境需使用 Oculus，Fabric 环境使用 Iris\r