HMCL-AE

更新日志

各版本的完整技术变更记录,含每次新增的 AI 工具动作、修复与界面改动。

未发布 开发中 滚动更新

0.1.1-alpha 之后的开发进展,发布版本号与日期待定。

重要更新
AI 助手 — 实例工具动作大幅扩充

instance 工具本轮新增下列动作,均复用 HMCL 原生的对应实现(不另写一套逻辑),权限按动作细分(只读 / 受控写入 / 危险写入)。

配置类
  • set_java:设置实例的 Java 运行时选择(mode = auto / version / detected / custom)。
  • set_window:游戏窗口模式与尺寸(windowed / fullscreen / maximized,窗口模式附 width / height)。
  • set_launch_behavior:启动前后行为(启动器可见性、进程优先级、自动 agent、是否禁用自动 game options、日志窗口、调试日志、跳过完整性检查)。
  • set_graphics:图形后端与渲染器(default / opengl / vulkan,不带参数先报告本机支持的渲染器)。
  • set_launch_args:每实例启动参数覆盖(游戏命令行参数、环境变量、默认 / 优化 JVM 参数开关、JVM 校验开关)。
  • list_presets(只读):列出全局游戏设置预设。
  • set_memory:修复自动 / 固定内存切换未正确写入 overrideProperties、导致设置值被预设静默继承的问题。
内容与存档类
  • mods_rollback:把模组回滚到归档的旧版本(不带 version 则列出可回滚版本)。
  • resourcepacks_check_updates:列出有新版本的资源包(apply=true 下载替换;未设 apply 时只读)。
  • worlds_export:把世界存档打包为 zip(不覆盖已存在文件)。
  • worlds_duplicate:把世界复制到新的存档文件夹。
  • datapacks_toggle / datapacks_remove:单个数据包的启停 / 删除(删除为危险动作,优先进回收站)。
  • install_local_content:把本地已有文件(mod / 资源包 / 光影)按类型装进实例对应目录,尊重版本隔离;类型不符即拒绝。
维护与管理类
  • instance_maintenance:对应原生「版本管理」菜单(clean_junk / redownload_assets / clear_resources / clear_libraries);后两者为危险动作,需 confirm 且游戏运行时拒绝;不带 scope 时只报告可回收空间。
  • java_manage:管理 HMCL 的 Java 运行时注册表(refresh 重扫 / add 登记已有 Java / uninstall 删除托管运行时);uninstall 只删 HMCL 自己下载的运行时,不碰系统或用户自装 JDK。
  • generate_launch_script:生成可在启动器外运行的启动脚本(.bat / .sh / .command),需已选账户。
  • set_instance_icon:设置实例图标,复用 HMCL 原生图标系统(内置图标名、auto,或自定义图片)。
  • schematics_list / import / delete / reveal:管理实例 schematics/ 下的 Litematica 投影文件。
game 工具 · 批量与富化
  • launch 新增 testMode:复用原生「测试游戏」入口,本次启动强制保留窗口并显示日志,不改动持久化设置。
  • mods_install 支持 ids 数组一次安装多个已知项目(不自动装依赖,逐项回执)。
  • mods_update 支持 all=truemods 数组一次更新多个模组。
  • 实例列表富化:每个实例附带检测到的加载器与本地模组数(纯本地)。
AI 助手 — 知识库(RAG)开发预览,发布版暂时隐藏

知识库(RAG)相关能力仍不成熟,发布版中隐藏其设置与实现:AI 设置的「知识库」分区、模型的「嵌入」能力勾选、以及 kb_search 工具在发布构建中不出现,提示词也不会提及它。代码与已保存配置保留不动,由构建标志 KNOWLEDGE_BASE_UI_ENABLED 控制(开发构建可见,或 -Dhmcl.experimental.ai.kb=true 强制开启)。

知识库关闭时保证有下位替代:AI 仍可用搜索 / 联网搜索 / 内置知识作答;开启时 kb_search 与它们并存,不冲突。

变更明细
  • AI 助手 — 工具编码修复(Windows)Shell 工具在 Windows + JDK 21 下按控制台编码(sun.jnu.encoding,通常 GBK)解码输出,修复中文乱码;文件读取改为先严格 UTF-8、失败再回退本地编码,修复非 UTF-8 文件读取崩溃。
  • AI 助手 — 搜索结果透出兼容信息模组 / 资源包 / 光影搜索结果补充各条目支持的游戏版本与加载器(来自 Modrinth / CurseForge 响应),便于按用户实际需要选择,减少装错构建。
  • AI 助手 — 工具增强grep 支持上下文行(-B / -A,重叠窗口去重);web_fetch 在正则抽取前对不可信响应体加输入大小上限,消除多 MB 页面上的 O(n²) 回溯风险。
  • 界面 — 图标统一AI 界面改用 HMCL 原生的 Material Symbols 图标,导航采用未选中 fill=0 / 选中 fill=1 的填充切换。
  • 界面 — 对话工具调用卡片恢复分组摘要(工具名 + 「+N」折叠)并配 SVG 图标;Markdown 代码块复制按钮改为图标式(悬停涟漪 + 提示,成功时短暂切为对钩)。
  • 测试新增 Monocle 离屏运行 TestFX 的 -PmonocleTest,UI 测试可真实执行且不弹窗抢焦点;修复受工具卡片改动影响的相关 UI 测试。
0.1.1-alpha 2026-07-12

0.1.0-alpha 之后的修订版本。启用微软账户登录,并纳入首发后的一批 AI 助手修复。

重要更新
账户 — 微软账户登录可用

发布构建现内置 HMCL-AE 自建 Azure 应用的 Microsoft OAuth client ID,微软正版账户登录不再被「非官方构建」拦截,登录入口恢复可用。通用「非官方构建」安全性提示与此无关,仍会保留。

AI 助手 — 危险操作防护

Shell 工具禁止用于终止 java / javaw 进程;新增对「终止 java / javaw 或启动器自身进程」的危险 / 关键操作判定,避免误杀运行中的游戏或启动器自身。

变更明细
  • AI 助手 — 工具模组安装前报告依赖状态,避免缺依赖连环崩溃;模组搜索结果透出依赖信息、澄清 loader 描述不参与检索;实例工具补充资源包 / 光影开关,避免裸 shell 改后缀;Ask 工具保留 JSON 语法错误详情。
  • AI 助手 — 崩溃诊断与稳定性崩溃诊断补充「日志读取失败 / 进程卡住需终止」分支;危险操作前同步落盘,避免异常退出丢会话;内容审核拒绝错误信息友好化。
  • 构建与文档README 重写为机械化详细介绍页、新增独立 CHANGELOG;修复 check-codes(全角括号改半角、补标准版权头);修复一处偶发失败的单元测试。
0.1.0-alpha 2026-07-11

Agent 逻辑重写后的首个 alpha 版本,版本序列自本版重置(0.x-beta 系列已废弃)。

重要更新
AI 助手 — Agent 逻辑重构

统一护栏架构(工具调用拒绝态短路、runtime-guard 通道、结构化 BlockReason,消除「假成功」回执);失败回执统一为错误信封,携带原因、作用域内候选、后续动作;文件工具契约化(读取台账、写后校验、替换链、写前强制读取);各工具域失败态统一枚举真实候选名单;资源占用统一守卫,模组启停 / 删除 / 更新收编入状态机,世界备份 / 恢复 / NBT 写入原子性保护,删除实例前运行检测。

AI 助手 — 诊断 Trace 基建

新增独立 append-only JSONL,逐轮记录 request / response / tool 调用完整内容与 token 计数,可配置开关;反馈上传附带 ai-trace / ui-trace / 元信息。

AI 助手 — 模型参数库

内置模型元数据由 65 项扩充至 1604 项,涵盖上下文窗口、输出上限、模态、定价;按模型 ID 自动匹配上下文窗口,新增大小写与 provider 前缀的保守规范化匹配。

AI 助手 — 运行时状态传播修复(单一事实源)

修复下拉切换模型后请求仍用旧模型;每模型参数(温度 / 最大输出 / 推理强度 / 上下文窗口)接入请求侧;审批模式、联网开关、shell / NBT / OCR 工具开关改为运行时实时生效;工具权限跨实例磁盘同步,文件系统工具根随实例切换替换。

变更明细
  • 界面 — 对话栏两行布局(输入框 + 底部工具栏);上下文数值百万级格式;进度条改用原生下载条样式;四类弹窗动画统一、位置按窗口余量自适应;修复空态过高;发送后回底、流式仅贴底跟随。
  • 界面 — 设置与主题设置页分区重构、高级设置精简、模型配置弹窗固定高度滚动;API Key 内联掩码与可见切换;暗色主题配色修复;代码块 One Dark 深色框;定价与成本估算界面归档隐藏。
  • 界面 — Markdown裸 URL 自动链接;国旗 emoji 换源;代码块横向滚动;emoji 与粗体 / 斜体 / 删除线混排保留样式;字号随档位。
  • AI 助手 — 工具与提示词联网搜索、OCR 按开关条件暴露;技能索引扁平化、召回收敛、自适应匹配替代全文注入;提示词注入选中实例的权威 Minecraft 版本与类型。
  • 安全SSRF / DNS 加固;修复路径穿越与符号链接逃逸;锁定 Jackson 依赖 CVE 版本。
  • 构建与发布新增 -PheadlessTest 无头测试;发布产物正文内嵌更新日志与 SHA-256 校验和表格。
  • 其他i18n 文案全量迁移(约 230 键);繁体中文文案重译;移除仓库内截图目录;停止跟踪运行时状态目录。

完整技术记录见仓库 CHANGELOG.md。发布版更新说明见 Releases