Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[Feature] 支持用户自带 API Key 接入 AI 大模型，用于模组与整合包的中文语义搜索

Abierto
  • ¿Algo no está bien?
#7,042 4 comentarios 5 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
java
Área
backend-api-design, search

Línea de trabajo

Start by reading HMCL's existing CurseForge API key settings and the CurseForge and Modrinth search entry points. Trace how search requests include game version and loader, then assess how provider configuration, secure key storage, asynchronous calls, caching, result merging, and fallback behavior fit the current design. Done means an opt-in AI-assisted search works while ordinary keyword search remains available, with keys protected and requests handled without blocking the UI.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement
概述 | Summary

希望 HMCL 提供一层可选的「AI 能力」接入：用户在设置中填写自己申请/购买的 AI API Key
（OpenAI、Anthropic、Gemini、DeepSeek、Moonshot、硅基流动等 OpenAI 兼容服务，或本地 Ollama），
HMCL 在需要的场景下调用该模型，并把结果用于具体功能。

首个、也是最痛的落地场景是模组搜索的语义化匹配：用户可以直接输入中文俗名或功能描述，
由模型推断其对应的英文模组名，再拿这些英文名去 CurseForge / Modrinth 检索。

示例：输入「遥远的地平线」

  • 现状：只命中「自然地平线 (Nature Horizons)」，搜不到真正想要的 Distant Horizons
  • 期望：模型给出候选 Distant Horizons，用它去检索，用户在结果里直接看到目标模组

同类场景：

  • 「小地图」→ JourneyMap / Xaero's Minimap
  • 「连锁挖矿」「一键砍树」→ VeinMiner / FTB Ultimine
  • 「等价交换」→ ProjectE
  • 拼音、缩写、错别字：「jEI」「物品管理器」「机械动力」→ JEI / Create
原因 | Reason
  1. 当前搜索是关键词匹配，用户输入必须接近模组英文原名才能命中。官方帮助文档也明确说明
    中文搜索「匹配结果不一定准确」。
  2. 中文用户通常只知道模组的中文俗名或它的功能，不知道英文原名，于是出现
    「明明知道这个模组，就是搜不到」的困境，只能去搜索引擎或百科绕一圈。
  3. CurseForge 侧还存在结果缺乏相关度排序、按热度靠后的问题，进一步放大了搜不到的概率。
  4. 「中文俗名 / 功能描述 → 英文模组名」本质上是一个很适合交给大模型的语义映射任务：
    候选集有限、结果可校验、出错成本低（最多只是多展示一条无关结果）。
  5. 需要强调的是：搜索增强只是第一个切入点。同样的 AI 能力后续还可用于崩溃日志解读、
    启动失败排查、模组依赖与冲突解释、按需求推荐整合包等。为避免本 issue 范围过大，
    这些将另开 issue 单独讨论。
详情 | Description
配置方式建议

在「设置」中新增一个 AI（或「增强功能」）分组：

  • 总开关，默认关闭，未开启时启动器行为与现在完全一致
  • 提供方预设：OpenAI / Anthropic / Gemini / DeepSeek / Moonshot / 硅基流动 / Ollama（本地）/ 自定义（OpenAI 兼容）
  • 字段：Base URL、API Key、模型名、超时时间、可选的调用次数上限
  • 这里可以复用 HMCL 已有的「用户自带 Key」设计习惯（类似现有的自定义 CurseForge API Key 机制）
搜索流程建议（关键是不要让模型直接"编造"结果）
  1. 用户照常输入关键词，HMCL 照常走 CurseForge / Modrinth 的关键词搜索
  2. 若开启 AI 增强，将「用户输入 + 当前游戏版本 + 加载器类型」交给模型，
    要求它只输出 N 个最可能的英文模组名或 slug（JSON 格式，不要解释）
  3. 用这些候选名分别去平台 API 检索，命中的结果合并进列表，
    并在条目上标注「AI 匹配 / AI match」与置信度
  4. 全部候选都未命中时，展示一条提示：「未找到结果，你是否在找 XXX？」
  5. 同一 query 的 AI 结果本地缓存，避免重复调用产生不必要的费用

这样模型只负责「翻译与联想关键词」，最终展示的项目仍然来自官方 API，
不会返回不存在的模组，用户也能直观判断 AI 帮没帮上忙，随时可以关掉。

隐私与安全
  • API Key 仅保存在本地，建议使用系统凭据存储或至少加密保存，绝不上传 HMCL 的任何服务器
  • 首次开启时弹窗明确告知：调用时会把「搜索关键词、游戏版本、加载器类型」发送给用户自己
    指定的第三方服务商；不发送账户信息、文件路径、实例数据
  • 日志与崩溃报告中自动脱敏 API Key
  • 提供「一键清除已保存的 Key」入口
兼容性与降级
  • 未配置 / 调用超时 / 鉴权失败 / 余额不足时，静默降级为普通关键词搜索，不弹错、不打断用户
  • AI 请求走异步任务，不阻塞 UI，可中断
备选方案（供参考）

如果维护者认为引入大模型的维护成本过高，一个更轻的替代方案是：维护一份官方的
「中文俗名 → 英文模组 slug」映射表，由社区以 PR 方式贡献，随启动器更新或远程拉取。
它的成本与风险更低，但需要长期人工维护、覆盖面有限，也无法处理「能自动整理背包的模组」
这类功能描述型搜索。个人认为两者可以并存：词表兜底高频模组，AI 覆盖长尾与描述型查询。

Lenguaje dominante
Java
Estrellas
10.7k
Forks
1.3k
Merge medio
22 h 16 min
PR fusionados (30 d)
73

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de HMCL-dev/HMCL

Todos los issues de HMCL-dev/HMCL

Issues similares

Más issues de Java

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.