v2.1.0 — i18n Internationalization & Bug Fixes

v2.1.0

🌐 国际化 (i18n)

• 基于 JSON 的翻译系统，自动检测系统语言
• 100% 中文 UI 字符串已包裹 _() 调用
• 392 条英文翻译条目（en_US.json）
• Header 栏语言切换按钮，偏好持久化到 configs/locale.json
• 语言切换通过 subprocess.Popen 干净重启
• 系统中文环境自动加载中文，其他环境加载英文

🐛 Bug 修复

• 修复 _instance_add 字典创建缩进在 if 块内的 Bug（点击添加实例无反应）
• 修复 PyInstaller 缺少 PIL._imagingtk hidden import（ttkbootstrap 滚动条主题崩溃）
• 修复 _ 变量遮蔽导致的 UnboundLocalError（列表解包中 _ 覆盖 i18n 函数）

🏗 架构优化

• gguf_reader.py：独立 GGUF 二进制解析器（205 行）
• config_store.py：原子 JSON 配置存储（87 行）
• _sync_instance_ui()：统一刷新/同步/保存三连调用
• _kill_instance_process() + _clear_instance_run_state()：统一进程查杀逻辑

📦 构建

• Windows 单文件 exe，--windowed 模式编译
• locales/ 目录通过 --add-data 打包

---

🌐 Internationalization (i18n)

• JSON-based translation system with auto language detection
• 100% Chinese UI strings wrapped in _() calls
• 392-entry English locale (en_US.json)
• Language toggle button in header bar, preference persisted to file
• Clean restart via subprocess.Popen when switching languages

🐛 Bug Fixes

• Fix _instance_add dict creation indented inside if block (Add Instance button crash)
• Fix PIL._imagingtk missing from PyInstaller hidden imports (ttkbootstrap crash)
• Fix _ variable shadowing UnboundLocalError (list unpacking _ overrides i18n)

🏗 Architecture

• gguf_reader.py: independent GGUF binary parser (205 lines)
• config_store.py: atomic JSON config storage (87 lines)
• _sync_instance_ui(): consolidates triple refresh/sync/save pattern
• _kill_instance_process() + _clear_instance_run_state(): unified kill logic

📦 Build

• Single-file Windows exe compiled with --windowed mode
• locales/ directory bundled via --add-data

v2.0.0

v2.0.0 — 架构重构

🏗 模块解耦

• gguf_reader.py (205行): GGUF 二进制解析器独立模块 — read_metadata(), classify_file(), is_embedding_model(), metadata_display() 等
• config_store.py (87行): 原子 JSON 配置存储 — save_atomic(), load_json(), params_to_dict(), params_from_dict()

🔧 代码优化

• _sync_instance_ui(): 封装 _refresh_instance_tree + _sync_bottom_bar + _auto_save 三重调用，4 处重复 → 一行
• _kill_instance_process() + _clear_instance_run_state(): 统一进程查杀逻辑，消除 stop_server 和 _stop_all_instances 中 ~60 行重复
• 主文件精简: 3,829 → 3,635 行（-194 行），131 个方法
• 无黑框启动: 使用 --windowed 模式编译

🐛 修复

• 恢复被 GGUF 提取时误删的 create_entry() 方法
• 移除死模块 download_manager.py（API 不匹配）
• 修复 config_store.save_atomic 未集成问题

📦 构建

dist/llama-server-gui.exe — Windows 单文件 ~31MB，双击启动无黑框

Full Changelog: v1.9.1...v2.0.0

v1.9.1

v1.9.1 代码质量全面修复 & 跨平台兼容

崩溃修复

• 修复移除通配符导入后 setup_server_api_tab() 中 8 处裸几何常量导致闪退的问题
• 修复 self.is_running 在启动服务器后从未设为 True，健康检查形同虚设
• 修复 on_closing / quit_application 不会停止所有运行中的实例（僵尸进程）
• 修复 JSON 配置文件非原子写入导致崩溃时数据损坏
• 修复自定义参数未做 shell 元字符过滤（注入风险）
• 修复 process.wait() 无超时，服务器进程僵死时界面永久阻塞
• 修复 server_stopped() TOCTOU 竞态——线程启动时捕获 inst_id 而非读取共享变量
• 修复 _instances 字典在多线程中非线程安全（添加 _instances_lock）

跨平台兼容（macOS / Linux）

• 条件化 taskkill——非 Windows 使用 os.kill
• import signal 移至模块顶层
• decode('utf-8') 替换为 locale.getpreferredencoding()
• UI 字符串硬编码去掉，改用 _exe_name()

代码清理

• DEAD-1~5: 移除死代码（self.server_process、_health_check_active、未初始化的 _param_frames、_refresh_instance_combo()、通配符导入）
• R-1/3/4: 消除冗余（提取 _set_state_recursive、移除重复的 reasoning_effort、提取 _refresh_engine_tree_markers）
• BR-1~4: 修复 Bug 风险（_instance_delete try/finally、单文件冲突跳过、保留已完成下载文件、?Recursive=true）
• S-1: 移除不安全的 root.update()
• 删除遗留迁移脚本 enhance_v2.py、fix_mtp.py、fix_v3.py

构建

• 使用 build_exe.py --onefile --windowed 编译，双击无黑框

v1.9.0

v1.9.0 发布说明

🎉 新功能

🖥 跨平台支持

• Windows / Linux / macOS 全兼容：llama-server.exe 不再硬编码，自动检测系统使用正确的可执行文件名
• 跨平台文件管理器：os.startfile / xdg-open / open 自动适配
• 跨平台进程查杀：tasklist/powershell（Windows）、lsof/os.kill（Linux）、signal（macOS）
• 统一 startupinfo：Windows 下隐藏命令行窗口，Linux/macOS 不处理

🚀 CI/CD 自动编译

• GitHub Actions 自动构建：推送 v* 标签时自动编译 Windows + Linux 双平台
• 自动发布 Release：编译产物自动上传到 GitHub Releases 页面
• 支持手动触发：workflow_dispatch

🛡 线程安全

• 实例状态加锁：_instances_lock 保护多线程下的实例读写，防止竞态条件

⚡ GGUF 读取优化

• LRU 缓存：_read_gguf_metadata / _read_gguf_type / _read_gguf_embedding_check 使用 @lru_cache，避免重复 I/O
• 元数据上限：从 100 提升至 500 项，减少遗漏
• 移除手动缓存字典：不再有内存泄漏风险

🔧 问题修复

修复项	说明
跨平台路径	所有 llama-server.exe 硬编码替换为 self._exe_name()
端口查杀 macOS	新增 Linux/macOS 端口查杀支持
进程恢复	_restore_running_instances 不再依赖 PowerShell（改用 tasklist/os.kill）
死代码	移除 _is_embedding_model 和 create_entry 之间的 8 行不可达代码
重复导入	from collections import deque 和 import re 从方法内移到文件顶部
变量遮蔽	update_output 中 tag 参数与局部变量重命名避免冲突
日志正则	添加 \b 单词边界，防止误匹配（如 "error" 匹配到 "terror"）
< 0 值	_params_from_dict 修复 val=0 被当作 falsy 的问题
None 检查	_params_to_dict 按 kind 区分处理，移除冗余的 None 判断
.gguf_file	远程文件分类增加 .gguf_file 后缀识别
build_exe.py	--add-data 分隔符替换改为 list comprehension，修复遍历时修改列表的 bug
_monitor_loop	移除无效的 kwargs={"inst_id": ...}，修复 TypeError
实例选择	_on_instance_tree_select 简化，14 行重复逻辑合并为调用 _sync_bottom_bar_for_active_instance()

📦 构建说明

git clone https://github.com/jerrydong1988/llama-cpp-GUI-zh.git
pip install pyinstaller ttkbootstrap pillow
python build_exe.py --onefile

下载

• Windows: LLaMA-Server-GUI.exe（19 MB，单文件）
• Linux: LLaMA-Server-GUI（31 MB，单文件）

---

v1.9.0 Release Notes

🎉 New Features

🖥 Cross-platform Support

• Windows / Linux / macOS compatible: llama-server.exe no longer hardcoded; auto-detects correct executable name per platform
• Cross-platform file manager: os.startfile / xdg-open / open auto-adaptation
• Cross-platform process kill: tasklist/powershell (Windows), lsof/os.kill (Linux), signal (macOS)
• Unified startupinfo: Windows hides console window; Linux/macOS no-op

🚀 CI/CD Automated Builds

• GitHub Actions: Auto-builds Windows + Linux when v* tags are pushed
• Auto-release: Build artifacts automatically uploaded to GitHub Releases
• Manual trigger: workflow_dispatch supported

🛡 Thread Safety

• Instance state locking: _instances_lock protects instance read/write across threads, preventing race conditions

⚡ GGUF Read Optimization

• LRU cache: _read_gguf_metadata / _read_gguf_type / _read_gguf_embedding_check use @lru_cache, eliminating redundant I/O
• Metadata limit: Increased from 100 to 500 entries
• Removed manual cache dicts: No more memory leak risk

🔧 Bug Fixes

Fix	Description
Cross-platform paths	All llama-server.exe hardcoding replaced with self._exe_name()
Port kill macOS/Linux	Added lsof/os.kill fallback for non-Windows
Process recovery	_restore_running_instances no longer requires PowerShell
Dead code	Removed 8 unreachable lines between _is_embedding_model and create_entry
Duplicate imports	from collections import deque and import re moved to file top
Variable shadowing	Renamed local variable in update_output to avoid shadowing tag param
Log regex	Added \b word boundaries to prevent false matches
Zero-value handling	_params_from_dict fixed falsy-zero bug
None check	_params_to_dict now handles types properly per kind
.gguf_file support	File classification now recognizes .gguf_file extension
build_exe.py	Fixed --add-data separator replacement (safe list comprehension)
_monitor_loop	Removed invalid kwargs={"inst_id": ...} preventing TypeError
Duplicate logic	Simplified instance tree selection handler

📦 Build Instructions

git clone https://github.com/jerrydong1988/llama-cpp-GUI-zh.git
pip install pyinstaller ttkbootstrap pillow
python build_exe.py --onefile

Downloads

• Windows: LLaMA-Server-GUI.exe (19 MB, single-file)
• Linux: LLaMA-Server-GUI (31 MB, single-file)

v1.8.0

v1.8.0 — 稳定性与打包改进

🐛 Bug 修复

• stop_server 修复：三层杀进程机制（taskkill/F + 端口兜底），验证成功后才清状态，彻底解决"UI 显示已停但进程仍在"的问题
• start_server 竞态修复：Popen 移到主线程，消除 running_pid 保存时的竞态条件
• 控制台窗口隐藏：所有 subprocess 调用加 STARTF_USESHOWWINDOW，停止时不再弹黑框

📦 构建变更

• 从 --onefile 改为 --onedir：PyInstaller 不解压到临时目录，彻底消灭 temp 目录清理失败警告
• 配置文件移入 configs/ 子目录：exe 目录更整洁，旧配置首次启动自动迁移

🔧 其他

• 新增 _get_app_dir() / _get_configs_path() 辅助方法，路径管理统一
• 日志目录 logs/ 独立于配置目录

---

v1.8.0 — Stability & Build Improvements

🐛 Bug Fixes

• stop_server fix: three-layer process kill (taskkill /F + port-based fallback), state cleared only after successful termination — eliminates the "UI says stopped but process is still alive" ghost issue
• start_server race condition fix: Popen moved to main thread, eliminating race between running_pid assignment and _auto_save_instances
• Hidden console windows: all subprocess.run calls now use STARTF_USESHOWWINDOW — no more command window flashing on stop

📦 Build Changes

• --onefile → --onedir: PyInstaller no longer extracts to temp directory, completely eliminating the "Failed to remove temporary directory" warning
• Config files moved to configs/ subdirectory: cleaner exe folder, with automatic migration from the old location on first run

🔧 Other

• Added _get_app_dir() / _get_configs_path() helper methods for unified path management
• Log directory logs/ is now independent of config directory

v1.7.0 — 多实例管理 / Multi-Instance Management

v1.7.0 — Multi-Instance Management / 多实例管理

English:

• 🆕 Multi-instance management: add/clone/rename/delete instances with independent configs
• 🖥️ Instance TreeView: status (●/○), port, model, engine per row
• 🔒 Run-lock: parameter panels auto-disabled (🔒) when instance is running
• 💾 Auto-save: all state changes (switch, start, stop, add, clone, rename, delete) persisted to instances.json
• 🔄 PID-based process recovery: running instances auto-detected on restart
• 📋 Per-instance log isolation: logs stored per instance, replayed on switch
• 🐛 Fix: server startup failure now properly clears the "running" state in the tree
• 🐛 Fix: model_repo_roots (custom directories) now persisted across restarts
• 🐛 Fix: clone instance now immediately refreshes engine tree and model repo
• 🐛 Fix: config dropdown removed — instance tree is the sole selection source
• 🐛 Fix: Windows TreeView event reentrancy issues resolved

中文:

• 🆕 多实例管理：支持添加/克隆/重命名/删除实例，每个实例独立配置
• 🖥️ 实例列表树：每行显示状态(●/○)、端口、模型名、引擎名
• 🔒 运行锁：实例运行时参数面板自动禁用（🔒 标记）
• 💾 自动保存：所有操作（切换、启动、停止、添加、克隆等）自动持久化
• 🔄 PID 进程恢复：重启后自动检测之前正在运行的进程
• 📋 实例日志隔离：每个实例独立缓存日志，切换时自动回放
• 🐛 修复：启动失败后树不再错误显示绿色"运行中"
• 🐛 修复：模型仓库自定义目录重启后不再丢失
• 🐛 修复：克隆实例后引擎树和模型仓库立即刷新
• 🐛 修复：移除旧配置下拉框，实例树作为唯一选择入口
• 🐛 修复：Windows TreeView 事件重入问题

v1.6.0

v1.6.0 — Embedding Mode（向量模型自动识别）

✨ 新功能 | New Feature

• 新增 Embedding Mode：加载向量模型（如 Qwen3-Embedding、BGE）时自动识别，切换为纯向量模式。
• Automatically detects vector/embedding models and switches to Embedding Mode.

⚙️ 检测 | Detection

• 本地文件：读取 GGUF 头部 general.basename / general.name 含 "Embedding" → 自动进入 Embedding Mode。
• ModelScope 远程：文件名含 "embed" 且不为 mmproj/imatrix → 自动识别。
• GGUF header scan for general.basename/general.name containing "Embedding", or filename heuristic for remote files.

🔒 禁用参数（30+项自动锁死）| Disabled Parameters

• 采样全部（temp / top-k / top-p / mirostat / DRY / XTC / ...）
• 输出控制（n_predict / ignore-eos / json-schema）
• 对话行为（chat-template / reasoning / jinja / ...）
• 推测解码（draft model / spec-type / ...）
• 模型扩展（LoRA / mmproj / grammar / MoE CPU layers）
• 上下文偏移
• Sampling, output, chat behavior, speculative decoding, model extension params — all greyed out.

🟢 保留参数 | Kept Active

• 核心性能（ctx / ngl / threads / batch / ubatch）
• Flash Attention、内存选项、K/V 缓存类型、NUMA
• 网络与API配置（host / port / ssl / api-key）
• --embedding 自动勾选，--pooling 自动推荐默认为 mean

💡 提示优化 | Tooltip Updates

• Pooling / Reranking / Embedding 复选框提示增强
• NUMA 优化提示补充：仅多路服务器需要
• 状态横幅提示：Embedding Mode 已激活

v1.5.3

v1.5.3 — 修复 mmproj 文件识别

🐛 修复 | Fix

• 修复 mmproj 投影文件无法被正确识别的问题。之前只匹配以 mmproj 开头的文件名（如 mmproj-xxx.gguf），遗漏了 Qwen3.6-35B-A3B-mmproj-BF16.gguf 这类中间含 -mmproj- 的文件。
• Fixed mmproj detection — previously only matched filenames starting with mmproj (e.g. mmproj-xxx.gguf), missing files like Qwen3.6-35B-A3B-mmproj-BF16.gguf.

🔧 方案 | Approach

• 新增 _classify_gguf_file() 统一分类方法：
  • 本地文件 → 直接读取 GGUF 头部 general.type 字段（100% 准确）
  • ModelScope 在线文件（仅有文件名）→ 增强文件名启发式（'mmproj' in name）
  • 附缓存机制，重复扫描不重复读头部
• All 4 detection points unified under _classify_gguf_file(): GGUF header for local files, enhanced filename heuristic for ModelScope remote.

v1.5.2

v1.5.2

变更

• WebUI 参数还原为 --no-ui：新版 llama-server 已自动嵌入 WebUI 前端（7.2MB），默认即可使用。勾选「禁用内置 UI」后传 --no-ui 关闭。

v1.5.0 — 全面适配最新 llama.cpp + 引擎目录持久化

v1.5.0 — 全面适配最新 llama.cpp + 引擎目录持久化

⚠️ 重要变更：终止旧引擎兼容

从 v1.5.0 起，程序仅支持最新版 llama.cpp（≥ commit b39a7bf）的参数规范。

• --spec-type 值：mtp → draft-mtp（旧值已移除）
• --no-webui → --no-ui（旧参数仍兼容但建议更新）
• 内置 Web UI：新版 llama.cpp 已移除内置聊天界面，推荐使用外部客户端连接
• 需要旧引擎的请使用 v1.4.0 及之前版本，且不再维护
• 如需自定义修改可自行 Fork 旧版代码

✨ 新功能

• 多引擎目录持久化 — 添加多个自定义引擎目录后保存配置，重启后全部自动恢复
• 引擎点击即选中 — 点击引擎树节点自动设为当前引擎（不再需要额外点"设为默认"）
• 自定义引擎自动补入引擎树 — config 中保存的自定义引擎路径在重启后自动显示在树中

🔧 适配

• 移除 NovaMax 旧引擎目录硬编码扫描
• --spec-type 下拉选项更新：mtp 替换为 draft-mtp，新增 draft-simple、draft-eagle3
• 更新 tooltip 和标签文本反映新版参数

🐛 修复

• 引擎添加后保存配置，重启不再丢失自定义引擎

---

v1.5.0 — Full Adaptation for Latest llama.cpp + Engine Directory Persistence

⚠️ Breaking Change: Old Engine Support Dropped

From v1.5.0 onwards, only the latest llama.cpp (≥ commit b39a7bf) parameter spec is supported.

• --spec-type values: mtp → draft-mtp (old value removed)
• --no-webui → --no-ui (deprecated but still recognized)
• Built-in Web UI: removed upstream — use external clients (Open WebUI, etc.)
• For old engine users: stick with v1.4.0 and earlier, no further maintenance
• Fork the old code if you need custom modifications

✨ New Features

• Multi-engine directory persistence — add multiple custom engines, save config, all restored on restart
• Click-to-select engine — clicking a tree node immediately sets it as the active engine
• Custom engine auto-inclusion — config-saved engine paths appear in the tree on restart

🔧 Adaptations

• Removed NovaMax legacy engine hardcoded scan path
• --spec-type dropdown updated: mtp → draft-mtp, added draft-simple, draft-eagle3
• Updated tooltips and labels for new parameter values

🐛 Fixes

• Engine directories persisted after save — no more losing custom engines on restart