refactor(theme): 将重复的主题逻辑下沉至 ThemeUtils，消除 validateTheme 职责过重

- ALSettingsWidget: BrowseQssButton/RemoveThemeButton 的 + / - 文本改为 fa6s.plus/fa6s.minus 图标
- ALAutoScriptEditDialog: ZoomInBtn/ZoomOutBtn 的全角 ＋/－ 改为 fa6s.plus/fa6s.minus 图标
- 其余图标同步从 fa5s 升级至 fa6s (Font Awesome 6)

Co-Authored-By: Claude <noreply@anthropic.com>

src/gui/ALAutoScriptEditDialog.py

@@ -211,12 +211,16 @@ class ALAutoScriptEditDialog(QDialog):
         Layout.setSpacing(3)
         Layout.setContentsMargins(3, 3, 3, 3)
         ToolbarLayout = QHBoxLayout()
-        self.ZoomInBtn = QPushButton("＋")
+        self.ZoomInBtn = QPushButton("")
+        self.ZoomInBtn.setIcon(qta.icon("fa6s.plus", color=self._iconColor()))
+        self.ZoomInBtn.setIconSize(QSize(14, 14))
         self.ZoomInBtn.setFixedSize(25, 25)
-        self.ZoomOutBtn = QPushButton("－")
+        self.ZoomOutBtn = QPushButton("")
+        self.ZoomOutBtn.setIcon(qta.icon("fa6s.minus", color=self._iconColor()))
+        self.ZoomOutBtn.setIconSize(QSize(14, 14))
         self.ZoomOutBtn.setFixedSize(25, 25)
         self.ZoomResetBtn = QPushButton("")
-        self.ZoomResetBtn.setIcon(qta.icon("fa5s.undo", color=self._iconColor()))
+        self.ZoomResetBtn.setIcon(qta.icon("fa6s.rotate-left", color=self._iconColor()))
         self.ZoomResetBtn.setIconSize(QSize(14, 14))
         self.ZoomResetBtn.setFixedSize(25, 25)
         self.ZoomResetBtn.setToolTip("重置缩放")
@@ -241,7 +245,7 @@ class ALAutoScriptEditDialog(QDialog):
         ToolbarLayout.addWidget(self.ZoomLabel)
         ToolbarLayout.addStretch()
         self.CopyBtn = QPushButton("")
-        self.CopyBtn.setIcon(qta.icon("fa5s.copy", color=self._iconColor()))
+        self.CopyBtn.setIcon(qta.icon("fa6s.copy", color=self._iconColor()))
         self.CopyBtn.setIconSize(QSize(14, 14))
         self.CopyBtn.setFixedSize(25, 25)
         self.CopyBtn.setToolTip("复制脚本")

src/gui/ALConfigWidget.py

@@ -42,6 +42,7 @@ from gui.ALUserTreeWidget import (
     ALUserTreeWidget
 )
 from gui.ALWebDriverDownloadDialog import ALWebDriverDownloadDialog
+from gui.ALWidgetMixin import CenterOnParentMixin
 from gui.resources.ui.Ui_ALConfigWidget import Ui_ALConfigWidget
 from interfaces.ConfigProvider import (
     CfgKey,
@@ -52,7 +53,7 @@ from utils.JSONReader import JSONReader
 from utils.JSONWriter import JSONWriter
 
 
-class ALConfigWidget(QWidget, Ui_ALConfigWidget):
+class ALConfigWidget(CenterOnParentMixin, QWidget, Ui_ALConfigWidget):
 
     configWidgetIsClosed = Signal()
 
@@ -110,29 +111,6 @@ class ALConfigWidget(QWidget, Ui_ALConfigWidget):
         self.ConfirmButton.clicked.connect(self.onConfirmButtonClicked)
         self.CancelButton.clicked.connect(self.onCancelButtonClicked)
 
-    def showEvent(
-        self,
-        event
-    ):
-
-        result = super().showEvent(event)
-
-        screen_rect = self.screen().geometry()
-        target_pos = self.parent().geometry().center()
-        target_pos.setX(target_pos.x() - self.width()//2)
-        target_pos.setY(target_pos.y() - self.height()//2)
-        if target_pos.x() < 0:
-            target_pos.setX(0)
-        if target_pos.x() + self.width() > screen_rect.width():
-            target_pos.setX(screen_rect.width() - self.width())
-        if target_pos.y() < 0:
-            target_pos.setY(0)
-        if target_pos.y() + self.height() > screen_rect.height():
-            target_pos.setY(screen_rect.height() - self.height())
-        self.move(target_pos)
-
-        return result
-
     def closeEvent(
         self,
         event: QCloseEvent

src/gui/ALSeatMapSelectDialog.py

@@ -24,9 +24,9 @@ from PySide6.QtWidgets import (
 )
 
 from gui.ALSeatMapView import ALSeatMapView
+from gui.ALWidgetMixin import CenterOnParentMixin
 
-
-class ALSeatMapSelectDialog(QDialog):
+class ALSeatMapSelectDialog(CenterOnParentMixin, QDialog):
 
     seatMapSelectDialogIsClosed = Signal(list)
 
@@ -96,29 +96,6 @@ class ALSeatMapSelectDialog(QDialog):
         self.ConfirmButton.clicked.connect(self.onConfirmButtonClicked)
         self.CancelButton.clicked.connect(self.onCancelButtonClicked)
 
-    def showEvent(
-        self,
-        event
-    ):
-
-        result = super().showEvent(event)
-
-        screen_rect = self.screen().geometry()
-        target_pos = self.parent().geometry().center()
-        target_pos.setX(target_pos.x() - self.width()//2)
-        target_pos.setY(target_pos.y() - self.height()//2)
-        if target_pos.x() < 0:
-            target_pos.setX(0)
-        if target_pos.x() + self.width() > screen_rect.width():
-            target_pos.setX(screen_rect.width() - self.width())
-        if target_pos.y() < 0:
-            target_pos.setY(0)
-        if target_pos.y() + self.height() > screen_rect.height():
-            target_pos.setY(screen_rect.height() - self.height())
-        self.move(target_pos)
-
-        return result
-
     def closeEvent(
         self,
         event: QCloseEvent

src/gui/ALSettingsWidget.py

@@ -19,8 +19,7 @@ from PySide6.QtCore import (
     Slot
 )
 from PySide6.QtGui import (
-    QCloseEvent,
-    QShowEvent
+    QCloseEvent
 )
 from PySide6.QtWidgets import (
     QApplication,
@@ -38,6 +37,7 @@ from managers.theme.ThemeManager import(
     instance as themeInstance
 )
 
+from gui.ALWidgetMixin import CenterOnParentMixin
 from gui.resources.ui.Ui_ALSettingsWidget import Ui_ALSettingsWidget
 from interfaces.ConfigProvider import (
     CfgKey,
@@ -83,7 +83,7 @@ def _restartApp(
     QProcess.startDetached(sys.executable, sys.argv)
 
 
-class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
+class ALSettingsWidget(CenterOnParentMixin, QWidget, Ui_ALSettingsWidget):
 
     settingsWidgetIsClosed = Signal()
 
@@ -102,20 +102,36 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         self.connectSignals()
         self.loadSettings()
 
+    def closeEvent(
+        self,
+        event: QCloseEvent
+    ):
+
+        self.settingsWidgetIsClosed.emit()
+        super().closeEvent(event)
+
     def modifyUi(
         self
     ):
 
         self.setWindowFlags(Qt.WindowType.Window)
-        self.NavigationList.setCurrentRow(0)
-        self.populateStyles()
         self.setNavigationIcons()
-        self.ThemeInfoLabel.setTextFormat(Qt.TextFormat.RichText)
-        self.ThemeInfoLabel.setStyleSheet(
+        color = QApplication.instance().palette().color(
+            QApplication.instance().palette().ColorRole.WindowText
+        ).name()
+        self.ImportCustomThemeButton.setIcon(qta.icon("fa6s.plus", color=color))
+        self.ImportCustomThemeButton.setText("")
+        self.RemoveCustomThemeButton.setIcon(qta.icon("fa6s.minus", color=color))
+        self.RemoveCustomThemeButton.setText("")
+        self.CustomThemeInfoLabel.setTextFormat(Qt.TextFormat.RichText)
+        self.CustomThemeInfoLabel.setStyleSheet(
             "border: 1px solid palette(mid);"\
             "border-radius: 2px;"\
             "padding: 5px;"
         )
+        self.NavigationList.setCurrentRow(0)
+        self.populateStyles()
+        self.populateCustomThemes()
 
     def setNavigationIcons(
         self
@@ -125,7 +141,7 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         color = app.palette().color(app.palette().ColorRole.WindowText).name()
         item = self.NavigationList.item(0)
         if item:
-            item.setIcon(qta.icon("fa5s.palette", color=color))
+            item.setIcon(qta.icon("fa6s.palette", color=color))
 
     def populateStyles(
         self
@@ -134,46 +150,36 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         self.StyleComboBox.clear()
         self.StyleComboBox.addItems(QStyleFactory.keys())
 
+    def populateCustomThemes(
+        self
+    ):
+
+        self.CustomThemeComboBox.blockSignals(True)
+        self.CustomThemeComboBox.clear()
+        self.CustomThemeComboBox.addItem("默认", "")
+        self.__theme_cache = {}
+        themes = themeInstance().listThemes()
+        for t in themes:
+            name = t.get("name", "")
+            file = t.get("file", name)
+            author = t.get("author", "")
+            if name:
+                self.__theme_cache[file] = t
+                self.CustomThemeComboBox.addItem(name, file)
+        self.CustomThemeComboBox.blockSignals(False)
+
     def connectSignals(
         self
     ):
 
-        self.BrowseQssButton.clicked.connect(self.onImportThemeButtonClicked)
-        self.ThemeComboBox.currentIndexChanged.connect(self.onThemeComboBoxChanged)
-        self.ResetThemeButton.clicked.connect(self.onResetThemeButtonClicked)
+        self.ImportCustomThemeButton.clicked.connect(self.onImportCustomThemeButtonClicked)
+        self.RemoveCustomThemeButton.clicked.connect(self.onRemoveCustomThemeButtonClicked)
+        self.CustomThemeComboBox.currentIndexChanged.connect(self.onCustomThemeComboBoxChanged)
+        self.ResetCustomThemeButton.clicked.connect(self.onResetCustomThemeButtonClicked)
         self.CancelButton.clicked.connect(self.onCancelButtonClicked)
         self.ApplyButton.clicked.connect(self.onApplyButtonClicked)
         self.ConfirmButton.clicked.connect(self.onConfirmButtonClicked)
 
-    def showEvent(
-        self,
-        event: QShowEvent
-    ):
-
-        result = super().showEvent(event)
-        screen_rect = self.screen().geometry()
-        target_pos = self.parent().geometry().center()
-        target_pos.setX(target_pos.x() - self.width()//2)
-        target_pos.setY(target_pos.y() - self.height()//2)
-        if target_pos.x() < 0:
-            target_pos.setX(0)
-        if target_pos.x() + self.width() > screen_rect.width():
-            target_pos.setX(screen_rect.width() - self.width())
-        if target_pos.y() < 0:
-            target_pos.setY(0)
-        if target_pos.y() + self.height() > screen_rect.height():
-            target_pos.setY(screen_rect.height() - self.height())
-        self.move(target_pos)
-        return result
-
-    def closeEvent(
-        self,
-        event: QCloseEvent
-    ):
-
-        self.settingsWidgetIsClosed.emit()
-        super().closeEvent(event)
-
     def loadSettings(
         self
     ):
@@ -194,44 +200,46 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         if index < 0:
             index = 0
         self.StyleComboBox.setCurrentIndex(index)
-        self.populateThemeList()
         if custom_theme:
-            idx = self.ThemeComboBox.findText(custom_theme)
+            idx = self.CustomThemeComboBox.findData(custom_theme)
             if idx >= 0:
-                self.ThemeComboBox.setCurrentIndex(idx)
-        self.updateThemeStatus()
-        self.updateThemeInfo()
+                self.CustomThemeComboBox.setCurrentIndex(idx)
+        self.updateCustomThemeInfo()
+        self.updateCustomThemeStatus()
 
-    def updateThemeStatus(
+    def updateCustomThemeInfo(
         self
     ):
 
-        name = self.ThemeComboBox.currentText()
-        if name and name != "默认":
-            self.QssStatusLabel.setText(f"当前使用 {name} 主题。")
-        else:
-            self.QssStatusLabel.setText("当前使用 默认 主题。")
-
-    def updateThemeInfo(
-        self
-    ):
-
-        name = self.ThemeComboBox.currentText()
-        if not name or name == "默认":
-            self.ThemeInfoLabel.setText("")
+        file = self.CustomThemeComboBox.currentData()
+        if not file:
+            self.CustomThemeInfoLabel.setText("")
             return
-        t = self.__theme_cache.get(name)
+        t = self.__theme_cache.get(file)
         if t:
-            author = t.get("author", "未知")
+            name = t.get("name", "未知")
+            author = t.get("author", "未知作者")
             need_theme = t.get("need_theme", "both")
             brief = t.get("brief", "没有相关简介")
-            self.ThemeInfoLabel.setText(
+            self.CustomThemeInfoLabel.setText(
                 f"<b>{name}</b> - 适用于 <i>{_themeToReadable(need_theme)}</i> 主题<br>"
                 f"作者：{author}<br><br>"
                 f"{brief}"
             )
         else:
-            self.ThemeInfoLabel.setText("")
+            self.CustomThemeInfoLabel.setText("")
+
+    def updateCustomThemeStatus(
+        self
+    ):
+
+        file = self.CustomThemeComboBox.currentData()
+        t = self.__theme_cache.get(file) if file else None
+        name = t.get("name", "") if t else ""
+        if name:
+            self.CustomThemeStatusLabel.setText(f"当前使用 {name} 主题。")
+        else:
+            self.CustomThemeStatusLabel.setText("当前使用 默认 主题。")
 
     def syncRadioFromNeedTheme(
         self,
@@ -257,8 +265,8 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         else:
             theme = "system"
         style = self.StyleComboBox.currentText()
-        custom_theme = self.ThemeComboBox.currentText()
-        if custom_theme == "默认":
+        custom_theme = self.CustomThemeComboBox.currentData() or ""
+        if not custom_theme:
             custom_theme = ""
         return theme, style, custom_theme
 
@@ -278,8 +286,8 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         theme, _, _ = self.collectSettings()
         self.__cfg_mgr.set(CfgKey.GLOBAL.APPEARANCE.THEME, theme)
         self.setNavigationIcons()
-        self.updateThemeStatus()
-        self.updateThemeInfo()
+        self.updateCustomThemeStatus()
+        self.updateCustomThemeInfo()
         self.__original_theme = theme
         self.__original_custom_theme = custom_theme if custom_theme else ""
         self.__original_style = getActiveStyle()
@@ -300,24 +308,45 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
             return True
         return False
 
-    def populateThemeList(
+    @Slot()
+    def onRemoveCustomThemeButtonClicked(
         self
     ):
 
-        self.ThemeComboBox.blockSignals(True)
-        self.ThemeComboBox.clear()
-        self.ThemeComboBox.addItem("默认")
-        self.__theme_cache = {}
-        themes = themeInstance().listThemes()
-        for t in themes:
-            name = t.get("name", "")
-            if name:
-                self.__theme_cache[name] = t
-                self.ThemeComboBox.addItem(name)
-        self.ThemeComboBox.blockSignals(False)
+        file = self.CustomThemeComboBox.currentData()
+        if not file:
+            QMessageBox.information(
+                self,
+                "提示 - AutoLibrary",
+                "请先选择一个主题。"
+            )
+            return
+        t = self.__theme_cache.get(file)
+        name = t.get("name", file) if t else file
+        reply = QMessageBox.question(
+            self,
+            "删除主题 - AutoLibrary",
+            f"确定要删除主题 \"{name}\" 吗？",
+            QMessageBox.Yes | QMessageBox.No,
+            QMessageBox.No
+        )
+        if reply != QMessageBox.Yes:
+            return
+        try:
+            themeInstance().removeTheme(file)
+            self.populateCustomThemes()
+            self.CustomThemeComboBox.setCurrentIndex(0)
+            self.updateCustomThemeStatus()
+            self.updateCustomThemeInfo()
+        except Exception as e:
+            QMessageBox.warning(
+                self,
+                "删除失败 - AutoLibrary",
+                f"无法删除主题：{e}"
+            )
 
     @Slot()
-    def onImportThemeButtonClicked(
+    def onImportCustomThemeButtonClicked(
         self
     ):
 
@@ -330,13 +359,13 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         if not file_path:
             return
         try:
-            name = themeInstance().importTheme(file_path)
-            self.populateThemeList()
-            idx = self.ThemeComboBox.findText(name)
+            file_id = themeInstance().importTheme(file_path)
+            self.populateCustomThemes()
+            idx = self.CustomThemeComboBox.findData(file_id)
             if idx >= 0:
-                self.ThemeComboBox.setCurrentIndex(idx)
-            self.updateThemeStatus()
-            self.updateThemeInfo()
+                self.CustomThemeComboBox.setCurrentIndex(idx)
+            self.updateCustomThemeStatus()
+            self.updateCustomThemeInfo()
         except Exception as e:
             QMessageBox.warning(
                 self,
@@ -345,37 +374,37 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
             )
 
     @Slot()
-    def onThemeComboBoxChanged(
+    def onCustomThemeComboBoxChanged(
         self,
         index: int
     ):
 
-        self.updateThemeInfo()
+        self.updateCustomThemeInfo()
+        # no status update, because custom theme is not applied yet.
 
     @Slot()
-    def onResetThemeButtonClicked(
+    def onResetCustomThemeButtonClicked(
         self
     ):
 
-        self.ThemeComboBox.blockSignals(True)
+        self.CustomThemeComboBox.blockSignals(True)
         if self.__original_custom_theme:
-            idx = self.ThemeComboBox.findText(self.__original_custom_theme)
+            idx = self.CustomThemeComboBox.findData(self.__original_custom_theme)
             if idx >= 0:
-                self.ThemeComboBox.setCurrentIndex(idx)
+                self.CustomThemeComboBox.setCurrentIndex(idx)
             else:
-                self.ThemeComboBox.setCurrentIndex(0)
+                self.CustomThemeComboBox.setCurrentIndex(0)
         else:
-            self.ThemeComboBox.setCurrentIndex(0)
-        self.ThemeComboBox.blockSignals(False)
+            self.CustomThemeComboBox.setCurrentIndex(0)
+        self.CustomThemeComboBox.blockSignals(False)
         if self.__original_theme == "light":
             self.LightThemeRadio.setChecked(True)
         elif self.__original_theme == "dark":
             self.DarkThemeRadio.setChecked(True)
         else:
             self.SystemThemeRadio.setChecked(True)
-        _applyCustomTheme(self.__original_custom_theme, self.__original_theme)
-        self.updateThemeStatus()
-        self.updateThemeInfo()
+        self.updateCustomThemeInfo()
+        self.updateCustomThemeStatus()
 
     @Slot()
     def onCancelButtonClicked(
@@ -400,9 +429,5 @@ class ALSettingsWidget(QWidget, Ui_ALSettingsWidget):
         self
     ):
 
-        _, style, _ = self.collectSettings()
-        style_changed = self.__original_style != style
-        self.saveAndApply()
-        if style_changed:
-            self.maybeRestart()
+        self.onApplyButtonClicked() # virtually call apply button clicked
         self.close()

src/gui/ALTimerTaskManageWidget.py

@@ -43,6 +43,7 @@ from gui.ALTimerTaskAddDialog import (
     ALTimerTaskStatus
 )
 from gui.ALTimerTaskHistoryDialog import ALTimerTaskHistoryDialog
+from gui.ALWidgetMixin import CenterOnParentMixin
 from gui.resources.ui.Ui_ALTimerTaskManageWidget import Ui_ALTimerTaskManageWidget
 from interfaces.ConfigProvider import (
     CfgKey,
@@ -189,7 +190,7 @@ class ALTimerTaskItemWidget(QWidget):
         Menu.exec(self.mapToGlobal(pos))
 
 
-class ALTimerTaskManageWidget(QWidget, Ui_ALTimerTaskManageWidget):
+class ALTimerTaskManageWidget(CenterOnParentMixin, QWidget, Ui_ALTimerTaskManageWidget):
 
     class SortPolicy(Enum):
 
@@ -299,29 +300,6 @@ class ALTimerTaskManageWidget(QWidget, Ui_ALTimerTaskManageWidget):
             )
             return False
 
-    def showEvent(
-        self,
-        event
-    ):
-
-        result = super().showEvent(event)
-
-        screen_rect = self.screen().geometry()
-        target_pos = self.parent().geometry().center()
-        target_pos.setX(target_pos.x() - self.width()//2)
-        target_pos.setY(target_pos.y() - self.height()//2)
-        if target_pos.x() < 0:
-            target_pos.setX(0)
-        if target_pos.x() + self.width() > screen_rect.width():
-            target_pos.setX(screen_rect.width() - self.width())
-        if target_pos.y() < 0:
-            target_pos.setY(0)
-        if target_pos.y() + self.height() > screen_rect.height():
-            target_pos.setY(screen_rect.height() - self.height())
-        self.move(target_pos)
-
-        return result
-
     def closeEvent(
         self,
         event: QCloseEvent

src/gui/ALWebDriverDownloadDialog.py

@@ -38,6 +38,7 @@ from managers.driver.WebDriverManager import (
     WebDriverStatus
 )
 from gui.ALStatusLabel import ALStatusLabel
+from gui.ALWidgetMixin import CenterOnParentMixin
 
 
 class DownloadWorker(QThread):
@@ -123,7 +124,7 @@ class DownloadWorker(QThread):
                 self.wait()
 
 
-class ALWebDriverDownloadDialog(QDialog):
+class ALWebDriverDownloadDialog(CenterOnParentMixin, QDialog):
 
     def __init__(
         self,
@@ -152,28 +153,6 @@ class ALWebDriverDownloadDialog(QDialog):
         self.initializeDriverManager()
         self.refreshDriverList()
 
-    def showEvent(
-        self,
-        event
-    ):
-
-        result = super().showEvent(event)
-        if self.parent():
-            screen_rect = self.screen().geometry()
-            target_pos = self.parent().geometry().center()
-            target_pos.setX(target_pos.x() - self.width()//2)
-            target_pos.setY(target_pos.y() - self.height()//2)
-            if target_pos.x() < 0:
-                target_pos.setX(0)
-            if target_pos.x() + self.width() > screen_rect.width():
-                target_pos.setX(screen_rect.width() - self.width())
-            if target_pos.y() < 0:
-                target_pos.setY(0)
-            if target_pos.y() + self.height() > screen_rect.height():
-                target_pos.setY(screen_rect.height() - self.height())
-            self.move(target_pos)
-        return result
-
     def setupUi(
         self
     ):

src/gui/ALWidgetMixin.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""
+Copyright (c) 2026 KenanZhu.
+All rights reserved.
+
+This software is provided "as is", without any warranty of any kind.
+You may use, modify, and distribute this file under the terms of the MIT License.
+See the LICENSE file for details.
+"""
+from PySide6.QtGui import QShowEvent
+
+
+class CenterOnParentMixin:
+    """
+        Mixin that centres the widget relative to its parent on first show,
+        clamping the position to the screen bounds.
+
+        Usage::
+
+            class MyWidget(CenterOnParentMixin, QWidget, Ui_MyWidget):
+                pass
+
+            class MyDialog(CenterOnParentMixin, QDialog):
+                pass
+
+        The mixin must appear **before** QWidget / QDialog in the base list
+        so that ``super().showEvent(event)`` resolves up the MRO correctly.
+    """
+
+    def showEvent(
+        self,
+        event: QShowEvent
+    ):
+
+        super().showEvent(event)
+        if self.parent():
+            screen_rect = self.screen().geometry()
+            target_pos = self.parent().geometry().center()
+            target_pos.setX(target_pos.x() - self.width() // 2)
+            target_pos.setY(target_pos.y() - self.height() // 2)
+            if target_pos.x() < 0:
+                target_pos.setX(0)
+            if target_pos.x() + self.width() > screen_rect.width():
+                target_pos.setX(screen_rect.width() - self.width())
+            if target_pos.y() < 0:
+                target_pos.setY(0)
+            if target_pos.y() + self.height() > screen_rect.height():
+                target_pos.setY(screen_rect.height() - self.height())
+            self.move(target_pos)

src/gui/resources/ui/ALSettingsWidget.ui

@@ -115,9 +115,9 @@
         <property name="geometry">
          <rect>
           <x>0</x>
-          <y>0</y>
-          <width>450</width>
-          <height>380</height>
+          <y>-51</y>
+          <width>397</width>
+          <height>434</height>
          </rect>
         </property>
         <layout class="QVBoxLayout" name="AppearancePageLayout">
@@ -138,305 +138,308 @@
          </property>
          <item>
           <widget class="QGroupBox" name="AppearanceGroupBox">
-         <property name="title">
-          <string>主题模式</string>
-         </property>
-         <layout class="QVBoxLayout" name="AppearanceGroupBoxLayout">
-          <property name="spacing">
-           <number>5</number>
-          </property>
-          <property name="leftMargin">
-           <number>3</number>
-          </property>
-          <property name="topMargin">
-           <number>3</number>
-          </property>
-          <property name="rightMargin">
-           <number>3</number>
-          </property>
-          <property name="bottomMargin">
-           <number>3</number>
-          </property>
-          <item>
-           <widget class="QRadioButton" name="LightThemeRadio">
-            <property name="text">
-             <string>浅色</string>
-            </property>
-           </widget>
-          </item>
-          <item>
-           <widget class="QRadioButton" name="DarkThemeRadio">
-            <property name="text">
-             <string>深色</string>
-            </property>
-           </widget>
-          </item>
-          <item>
-           <widget class="QRadioButton" name="SystemThemeRadio">
-            <property name="text">
-             <string>跟随系统</string>
-            </property>
-            <property name="checked">
-             <bool>true</bool>
-            </property>
-           </widget>
-          </item>
-         </layout>
-        </widget>
-       </item>
-       <item>
-        <widget class="QGroupBox" name="InterfaceGroupBox">
-         <property name="title">
-          <string>界面风格</string>
-         </property>
-         <layout class="QVBoxLayout" name="InterfaceGroupBoxLayout">
-          <property name="spacing">
-           <number>5</number>
-          </property>
-          <property name="leftMargin">
-           <number>3</number>
-          </property>
-          <property name="topMargin">
-           <number>3</number>
-          </property>
-          <property name="rightMargin">
-           <number>3</number>
-          </property>
-          <property name="bottomMargin">
-           <number>3</number>
-          </property>
-          <item>
-           <layout class="QHBoxLayout" name="StyleSelectLayout">
+           <property name="title">
+            <string>主题模式</string>
+           </property>
+           <layout class="QVBoxLayout" name="AppearanceGroupBoxLayout">
             <property name="spacing">
              <number>5</number>
             </property>
+            <property name="leftMargin">
+             <number>3</number>
+            </property>
+            <property name="topMargin">
+             <number>3</number>
+            </property>
+            <property name="rightMargin">
+             <number>3</number>
+            </property>
+            <property name="bottomMargin">
+             <number>3</number>
+            </property>
             <item>
-             <widget class="QLabel" name="StyleSelectLabel">
-              <property name="minimumSize">
-               <size>
-                <width>100</width>
-                <height>25</height>
-               </size>
-              </property>
-              <property name="maximumSize">
-               <size>
-                <width>100</width>
-                <height>25</height>
-               </size>
-              </property>
+             <widget class="QRadioButton" name="LightThemeRadio">
               <property name="text">
-               <string>应用程序样式：</string>
+               <string>浅色</string>
               </property>
              </widget>
             </item>
             <item>
-             <widget class="QComboBox" name="StyleComboBox">
-              <property name="minimumSize">
-               <size>
-                <width>160</width>
-                <height>25</height>
-               </size>
+             <widget class="QRadioButton" name="DarkThemeRadio">
+              <property name="text">
+               <string>深色</string>
+              </property>
+             </widget>
+            </item>
+            <item>
+             <widget class="QRadioButton" name="SystemThemeRadio">
+              <property name="text">
+               <string>跟随系统</string>
+              </property>
+              <property name="checked">
+               <bool>true</bool>
               </property>
              </widget>
             </item>
            </layout>
-          </item>
-          <item>
-           <widget class="QLabel" name="StyleHintLabel">
-            <property name="text">
-             <string>更改样式将在下次启动应用程序时生效。</string>
-            </property>
-           </widget>
-          </item>
-         </layout>
-        </widget>
-       </item>
-       <item>
-        <widget class="QGroupBox" name="CustomQssGroupBox">
-         <property name="title">
-          <string>自定义外观</string>
-         </property>
-         <layout class="QVBoxLayout" name="CustomQssGroupBoxLayout">
-          <property name="spacing">
-           <number>5</number>
-          </property>
-          <property name="leftMargin">
-           <number>3</number>
-          </property>
-          <property name="topMargin">
-           <number>3</number>
-          </property>
-          <property name="rightMargin">
-           <number>3</number>
-          </property>
-          <property name="bottomMargin">
-           <number>3</number>
-          </property>
-          <item>
-           <widget class="QLabel" name="CustomQssHintLabel">
-            <property name="text">
-             <string>选择一个主题，或导入新的主题文件：</string>
-            </property>
-            <property name="wordWrap">
-             <bool>true</bool>
-            </property>
-           </widget>
-          </item>
-          <item>
-           <layout class="QHBoxLayout" name="QssPathLayout">
+          </widget>
+         </item>
+         <item>
+          <widget class="QGroupBox" name="InterfaceGroupBox">
+           <property name="title">
+            <string>界面风格</string>
+           </property>
+           <layout class="QVBoxLayout" name="InterfaceGroupBoxLayout">
             <property name="spacing">
              <number>5</number>
             </property>
+            <property name="leftMargin">
+             <number>3</number>
+            </property>
+            <property name="topMargin">
+             <number>3</number>
+            </property>
+            <property name="rightMargin">
+             <number>3</number>
+            </property>
+            <property name="bottomMargin">
+             <number>3</number>
+            </property>
             <item>
-             <widget class="QComboBox" name="ThemeComboBox">
-              <property name="minimumSize">
-               <size>
-                <width>160</width>
-                <height>25</height>
-               </size>
+             <layout class="QHBoxLayout" name="StyleSelectLayout">
+              <property name="spacing">
+               <number>5</number>
+              </property>
+              <item>
+               <widget class="QLabel" name="StyleSelectLabel">
+                <property name="minimumSize">
+                 <size>
+                  <width>100</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="maximumSize">
+                 <size>
+                  <width>100</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="text">
+                 <string>应用程序样式：</string>
+                </property>
+               </widget>
+              </item>
+              <item>
+               <widget class="QComboBox" name="StyleComboBox">
+                <property name="minimumSize">
+                 <size>
+                  <width>160</width>
+                  <height>25</height>
+                 </size>
+                </property>
+               </widget>
+              </item>
+             </layout>
+            </item>
+            <item>
+             <widget class="QLabel" name="StyleHintLabel">
+              <property name="text">
+               <string>更改样式将在下次启动应用程序时生效。</string>
+              </property>
+             </widget>
+            </item>
+           </layout>
+          </widget>
+         </item>
+         <item>
+          <widget class="QGroupBox" name="CustomThemeGroupBox">
+           <property name="title">
+            <string>自定义外观</string>
+           </property>
+           <layout class="QVBoxLayout" name="CustomQssGroupBoxLayout">
+            <property name="spacing">
+             <number>5</number>
+            </property>
+            <property name="leftMargin">
+             <number>3</number>
+            </property>
+            <property name="topMargin">
+             <number>3</number>
+            </property>
+            <property name="rightMargin">
+             <number>3</number>
+            </property>
+            <property name="bottomMargin">
+             <number>3</number>
+            </property>
+            <item>
+             <widget class="QLabel" name="CustomThemeHintLabel">
+              <property name="text">
+               <string>选择一个主题，或导入新的主题文件：</string>
+              </property>
+              <property name="wordWrap">
+               <bool>true</bool>
               </property>
              </widget>
             </item>
             <item>
-             <widget class="QLineEdit" name="QssPathEdit">
+             <layout class="QHBoxLayout" name="CustomThemePathLayout">
+              <property name="spacing">
+               <number>5</number>
+              </property>
+              <item>
+               <widget class="QComboBox" name="CustomThemeComboBox">
+                <property name="minimumSize">
+                 <size>
+                  <width>160</width>
+                  <height>25</height>
+                 </size>
+                </property>
+               </widget>
+              </item>
+              <item>
+               <widget class="QLineEdit" name="CustomThemePathEdit">
+                <property name="minimumSize">
+                 <size>
+                  <width>0</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="visible">
+                 <bool>false</bool>
+                </property>
+                <property name="placeholderText">
+                 <string>选择或输入 QSS 样式表文件路径...</string>
+                </property>
+               </widget>
+              </item>
+              <item>
+               <widget class="QPushButton" name="ImportCustomThemeButton">
+                <property name="minimumSize">
+                 <size>
+                  <width>25</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="maximumSize">
+                 <size>
+                  <width>25</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="text">
+                 <string>+</string>
+                </property>
+               </widget>
+              </item>
+              <item>
+               <widget class="QPushButton" name="RemoveCustomThemeButton">
+                <property name="minimumSize">
+                 <size>
+                  <width>25</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="maximumSize">
+                 <size>
+                  <width>25</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="text">
+                 <string>-</string>
+                </property>
+               </widget>
+              </item>
+             </layout>
+            </item>
+            <item>
+             <widget class="QLabel" name="CustomThemeInfoLabel">
               <property name="minimumSize">
                <size>
                 <width>0</width>
-                <height>25</height>
+                <height>60</height>
                </size>
               </property>
-              <property name="visible">
-               <bool>false</bool>
+              <property name="text">
+               <string/>
               </property>
-              <property name="placeholderText">
-               <string>选择或输入 QSS 样式表文件路径...</string>
+              <property name="textFormat">
+               <enum>Qt::TextFormat::RichText</enum>
+              </property>
+              <property name="alignment">
+               <set>Qt::AlignmentFlag::AlignLeading|Qt::AlignmentFlag::AlignLeft|Qt::AlignmentFlag::AlignTop</set>
+              </property>
+              <property name="wordWrap">
+               <bool>true</bool>
               </property>
              </widget>
             </item>
             <item>
-             <widget class="QPushButton" name="BrowseQssButton">
-              <property name="minimumSize">
-               <size>
-                <width>25</width>
-                <height>25</height>
-               </size>
-              </property>
-              <property name="maximumSize">
-               <size>
-                <width>25</width>
-                <height>25</height>
-               </size>
+             <layout class="QHBoxLayout" name="CustomThemeActionLayout">
+              <property name="spacing">
+               <number>5</number>
               </property>
+              <item>
+               <widget class="QPushButton" name="ResetCustomThemeButton">
+                <property name="minimumSize">
+                 <size>
+                  <width>80</width>
+                  <height>25</height>
+                 </size>
+                </property>
+                <property name="text">
+                 <string>重置主题</string>
+                </property>
+               </widget>
+              </item>
+              <item>
+               <spacer name="CustomThemeActionSpacer">
+                <property name="orientation">
+                 <enum>Qt::Orientation::Horizontal</enum>
+                </property>
+                <property name="sizeHint" stdset="0">
+                 <size>
+                  <width>40</width>
+                  <height>20</height>
+                 </size>
+                </property>
+               </spacer>
+              </item>
+             </layout>
+            </item>
+            <item>
+             <widget class="QLabel" name="CustomThemeStatusLabel">
               <property name="text">
-               <string>...</string>
+               <string>当前使用程序 默认 外观。</string>
+              </property>
+              <property name="wordWrap">
+               <bool>true</bool>
               </property>
              </widget>
             </item>
            </layout>
-          </item>
-          <item>
-           <widget class="QLabel" name="ThemeInfoLabel">
-            <property name="minimumSize">
-             <size>
-              <width>0</width>
-              <height>60</height>
-             </size>
-            </property>
-            <property name="text">
-             <string/>
-            </property>
-            <property name="textFormat">
-             <enum>Qt::TextFormat::RichText</enum>
-            </property>
-            <property name="alignment">
-             <set>Qt::AlignmentFlag::AlignLeading|Qt::AlignmentFlag::AlignTop</set>
-            </property>
-            <property name="wordWrap">
-             <bool>true</bool>
-            </property>
-           </widget>
-          </item>
-          <item>
-           <layout class="QHBoxLayout" name="QssActionLayout">
-            <property name="spacing">
-             <number>5</number>
-            </property>
-            <item>
-             <widget class="QPushButton" name="ApplyQssButton">
-              <property name="minimumSize">
-               <size>
-                <width>80</width>
-                <height>25</height>
-               </size>
-              </property>
-              <property name="visible">
-               <bool>false</bool>
-              </property>
-              <property name="text">
-               <string>应用样式</string>
-              </property>
-             </widget>
-            </item>
-            <item>
-             <widget class="QPushButton" name="ResetThemeButton">
-              <property name="minimumSize">
-               <size>
-                <width>80</width>
-                <height>25</height>
-               </size>
-              </property>
-              <property name="text">
-               <string>重置主题</string>
-              </property>
-             </widget>
-            </item>
-            <item>
-             <spacer name="QssActionSpacer">
-              <property name="orientation">
-               <enum>Qt::Orientation::Horizontal</enum>
-              </property>
-              <property name="sizeHint" stdset="0">
-               <size>
-                <width>40</width>
-                <height>20</height>
-               </size>
-              </property>
-             </spacer>
-            </item>
-           </layout>
-          </item>
-          <item>
-           <widget class="QLabel" name="QssStatusLabel">
-            <property name="text">
-             <string>当前使用程序 默认 外观。</string>
-            </property>
-            <property name="wordWrap">
-             <bool>true</bool>
-            </property>
-           </widget>
-          </item>
-         </layout>
-        </widget>
-       </item>
-       <item>
-        <spacer name="AppearancePageSpacer">
-         <property name="orientation">
-          <enum>Qt::Orientation::Vertical</enum>
-         </property>
-         <property name="sizeHint" stdset="0">
-          <size>
-           <width>20</width>
-           <height>40</height>
-          </size>
-         </property>
-        </spacer>
-       </item>
-       </layout>
+          </widget>
+         </item>
+         <item>
+          <spacer name="AppearancePageSpacer">
+           <property name="orientation">
+            <enum>Qt::Orientation::Vertical</enum>
+           </property>
+           <property name="sizeHint" stdset="0">
+            <size>
+             <width>20</width>
+             <height>40</height>
+            </size>
+           </property>
+          </spacer>
+         </item>
+        </layout>
+       </widget>
       </widget>
-     </widget>
-    </item>
-   </layout>
-  </item>
+     </item>
+    </layout>
+   </item>
    <item>
     <layout class="QHBoxLayout" name="ButtonLayout">
      <property name="spacing">

src/managers/theme/ThemeManager.py

@@ -9,9 +9,7 @@ See the LICENSE file for details.
 """
 import os
 import shutil
-import tempfile
 import threading
-import zipfile
 
 from PySide6.QtCore import Qt
 from PySide6.QtWidgets import (
@@ -23,9 +21,9 @@ from interfaces.ConfigProvider import CfgKey
 from managers.config.ConfigManager import instance as configInstance
 from managers.log.LogManager import instance as logInstance
 from utils.ThemeUtils import (
-    packTheme,
     readThemeInfo,
-    unpackTheme,
+    readThemeQss,
+    validateTheme,
     wrapQssToAtheme
 )
 
@@ -82,6 +80,70 @@ class ThemeManager:
         else:
             return Qt.ColorScheme.Unknown
 
+    def _deleteThemeFile(
+        self,
+        name: str
+    ):
+        """
+            Delete a theme file in the themes storage directory.
+
+            The caller must hold self.__lock before invoking this method.
+
+            **This method ONLY deletes the file**.
+        """
+
+        filepath = os.path.join(self.__themes_dir, name + ".altheme")
+        if os.path.isfile(filepath):
+            os.remove(filepath)
+
+    def _resolveDestPath(
+        self,
+        theme_name: str,
+        author: str
+    ) -> str:
+        """
+            Resolve the destination path for an imported theme.
+
+            If the default {name}.altheme path does not exist, use it directly.
+            If it exists and has a different author, use {name}_{author}.altheme.
+            If it exists and has the same author, raise ValueError.
+
+            Args:
+                theme_name (str): Sanitised theme name.
+                author (str): Theme author string.
+
+            Returns:
+                str: The resolved destination file path.
+
+            Raises:
+                ValueError: If a theme with the same name and author already exists.
+        """
+
+        default_path = os.path.join(self.__themes_dir, theme_name + ".altheme")
+        if not os.path.exists(default_path):
+            return default_path
+        try:
+            existing_info = validateTheme(default_path)
+            existing_author = existing_info.get("author", "")
+        except Exception:
+            self._deleteThemeFile(theme_name)  # caller holds the lock
+            raise ValueError(
+                f"主题 '{theme_name}' 已存在但无法通过验证, 已清理该主题文件"
+            )
+        if existing_author == author:
+            raise ValueError(
+                f"主题名称 '{theme_name}' (作者 '{author}') 已存在"
+            )
+        safe_author = os.path.basename(author) if author else "未知作者"
+        alt_path = os.path.join(
+            self.__themes_dir, f"{theme_name}_{safe_author}.altheme"
+        )
+        if os.path.exists(alt_path):
+            raise ValueError(
+                f"主题名称 '{theme_name}' (作者 '{author}') 已存在"
+            )
+        return alt_path
+
     def themesDir(
         self
     ) -> str:
@@ -119,35 +181,21 @@ class ThemeManager:
 
         if not os.path.isfile(source_path):
             raise FileNotFoundError(source_path)
-        ext = os.path.splitext(source_path)[1].lower()
+        base_name, ext = os.path.splitext(os.path.basename(source_path))
+        ext = ext.lower()
         with self.__lock:
             if ext == ".qss":
-                name = os.path.splitext(os.path.basename(source_path))[0]
-                dest_path = os.path.join(self.__themes_dir, name + ".altheme")
-                if os.path.exists(dest_path):
-                    raise ValueError(f"主题 '{name}' 已存在")
+                dest_path = self._resolveDestPath(base_name, "未知作者")
                 wrapQssToAtheme(source_path, dest_path, "both")
-                return name
+                return os.path.splitext(os.path.basename(dest_path))[0]
             elif ext == ".altheme":
-                with zipfile.ZipFile(source_path, "r") as zf:
-                    if "theme.qss" not in zf.namelist():
-                        raise ValueError("无效的 .altheme: 缺少 theme.qss")
-                info = readThemeInfo(source_path)
-                name = info.get("name", os.path.splitext(os.path.basename(source_path))[0])
+                info = validateTheme(source_path)
+                name = info.get("name", base_name)
                 safe_name = os.path.basename(name)
-                dest_path = os.path.join(self.__themes_dir, safe_name + ".altheme")
-                if os.path.exists(dest_path):
-                    raise ValueError(f"主题 '{safe_name}' 已存在")
-                # Check for name collision with existing themes by the same author
                 new_author = info.get("author", "")
-                for existing in self.listThemes():
-                    if (existing.get("name", "") == safe_name
-                        and existing.get("author", "") == new_author):
-                        raise ValueError(
-                            f"主题名称 '{safe_name}' (作者 '{new_author}') 已存在"
-                        )
+                dest_path = self._resolveDestPath(safe_name, new_author)
                 shutil.copy2(source_path, dest_path)
-                return safe_name
+                return os.path.splitext(os.path.basename(dest_path))[0]
             else:
                 raise ValueError(f"不支持的文件类型: {ext}")
 
@@ -172,10 +220,7 @@ class ThemeManager:
             if filename.endswith(".altheme"):
                 filepath = os.path.join(self.__themes_dir, filename)
                 try:
-                    info = readThemeInfo(filepath)
-                    with zipfile.ZipFile(filepath, "r") as zf:
-                        if "theme.qss" not in zf.namelist():
-                            raise ValueError("缺少 theme.qss")
+                    info = validateTheme(filepath)
                     name = info.get("name", "")
                     author = info.get("author", "")
                     key = (name, author)
@@ -185,6 +230,7 @@ class ThemeManager:
                         )
                         continue
                     seen_keys.add(key)
+                    info["file"] = os.path.splitext(filename)[0]
                     themes.append(info)
                 except Exception as e:
                     logInstance().getLogger("ThemeManager").warning(
@@ -204,22 +250,21 @@ class ThemeManager:
             Remove a theme by name.
 
             If the removed theme is currently active, clears the QSS
-            stylesheet from the application.
+            stylesheet from the application and reverts to the saved
+            colour scheme.
 
             Args:
                 name (str): The theme name to remove.
         """
 
-        filepath = os.path.join(self.__themes_dir, name + ".altheme")
         with self.__lock:
-            if os.path.isfile(filepath):
-                os.remove(filepath)
-                if self.__current_theme_name == name:
-                    self.__current_theme_name = ""
-                    saved_theme = configInstance().get(
-                        CfgKey.GLOBAL.APPEARANCE.THEME, "system"
-                    )
-                    self.clearTheme(saved_theme)
+            self._deleteThemeFile(name)
+            if self.__current_theme_name == name:
+                self.__current_theme_name = ""
+                saved_theme = configInstance().get(
+                    CfgKey.GLOBAL.APPEARANCE.THEME, "system"
+                )
+                self.clearTheme(saved_theme)
 
     def applyTheme(
         self,
@@ -244,21 +289,10 @@ class ThemeManager:
             raise FileNotFoundError(filepath)
         with self.__lock:
             info = readThemeInfo(filepath)
-            with tempfile.TemporaryDirectory() as tmpdir:
-                unpackTheme(filepath, tmpdir)
-                qss_path = os.path.join(tmpdir, "theme.qss")
-                if os.path.isfile(qss_path):
-                    with open(qss_path, "r", encoding="utf-8") as fh:
-                        qss = fh.read()
-                    app = QApplication.instance()
-                    if app:
-                        app.setStyleSheet(qss)
-                else:
-                    raise ValueError(
-                        f"主题 '{name}' 的 .altheme 文件中缺少 theme.qss"
-                    )
+            qss = readThemeQss(filepath)
             app = QApplication.instance()
             if app:
+                app.setStyleSheet(qss)
                 need_theme = info.get("need_theme", "both")
                 app.styleHints().setColorScheme(
                     ThemeManager._colorSchemeFor(need_theme)

src/utils/ThemeUtils.py

@@ -37,7 +37,6 @@ def packTheme(
         zf.writestr("info.json", json.dumps(info, ensure_ascii=False, indent=4))
         zf.write(qss_path, "theme.qss")
 
-
 def unpackTheme(
     altheme_path: str,
     output_dir: str
@@ -65,22 +64,24 @@ def unpackTheme(
                 raise ValueError(f"不安全的 .altheme 入口: {name}")
         zf.extractall(output_dir)
 
-
 def readThemeInfo(
     altheme_path: str
 ) -> dict:
     """
-        Read only the info.json metadata from a .altheme file.
+        Read and validate the info.json metadata from a .altheme file.
+
+        Verifies that all required fields (name, author, need_theme, brief)
+        are present with valid values.
 
         Args:
             altheme_path (str): Path to the .altheme file.
 
         Returns:
-            dict: The theme metadata dictionary.
+            dict: The validated theme metadata dictionary.
 
         Raises:
             FileNotFoundError: If altheme_path does not exist.
-            ValueError: If the .altheme does not contain info.json.
+            ValueError: If info.json is missing or any field is invalid.
     """
 
     if not os.path.isfile(altheme_path):
@@ -89,11 +90,78 @@ def readThemeInfo(
         if "info.json" not in zf.namelist():
             raise ValueError("无效的 .altheme: 缺少 info.json")
         with zf.open("info.json") as fh:
-            info = json.loads(fh.read().decode("utf-8"))
-        if "name" not in info:
-            raise ValueError("无效的 .altheme: info.json 缺少 'name' 字段")
-        return info
+            try:
+                info = json.loads(fh.read().decode("utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError) as e:
+                raise ValueError(f"无效的 .altheme: info.json 解析失败 — {e}")
+    if "name" not in info or not isinstance(info.get("name"), str) or not info["name"].strip():
+        raise ValueError("无效的 .altheme: info.json 缺少有效的 'name' 字段")
+    # reject blank author so that info.json does not drift from the
+    # "未知作者" filename fallback used by wrapQssToAtheme
+    if ("author" not in info or not isinstance(info.get("author"), str)
+            or not info["author"].strip()):
+        raise ValueError("无效的 .altheme: info.json 缺少有效的 'author' 字段")
+    need_theme = info.get("need_theme", "both")
+    if need_theme not in ("light", "dark", "both"):
+        raise ValueError(
+            f"无效的 .altheme: need_theme 值 '{need_theme}' 无效, "
+            f"应为 'light'、'dark' 或 'both'"
+        )
+    if "brief" not in info or not isinstance(info.get("brief"), str):
+        raise ValueError("无效的 .altheme: info.json 缺少有效的 'brief' 字段")
+    return info
 
+def readThemeQss(
+    altheme_path: str
+) -> str:
+    """
+        Read the theme.qss content from a .altheme archive.
+
+        Args:
+            altheme_path (str): Path to the .altheme file.
+
+        Returns:
+            str: The non-empty QSS stylesheet content.
+
+        Raises:
+            FileNotFoundError: If altheme_path does not exist.
+            ValueError: If theme.qss is missing or empty.
+    """
+
+    if not os.path.isfile(altheme_path):
+        raise FileNotFoundError(altheme_path)
+    with zipfile.ZipFile(altheme_path, "r") as zf:
+        if "theme.qss" not in zf.namelist():
+            raise ValueError("无效的 .altheme: 缺少 theme.qss")
+        qss = zf.read("theme.qss").decode("utf-8")
+    if not qss.strip():
+        raise ValueError("无效的 .altheme: theme.qss 为空")
+    return qss
+
+def validateTheme(
+    altheme_path: str
+) -> dict:
+    """
+        Fully validate a .altheme file and return its metadata.
+
+        Delegates info validation to readThemeInfo and QSS validation
+        to readThemeQss, then additionally checks that theme.qss is
+        non-empty.
+
+        Args:
+            altheme_path (str): Path to the .altheme file.
+
+        Returns:
+            dict: The validated theme metadata dictionary.
+
+        Raises:
+            FileNotFoundError: If altheme_path does not exist.
+            ValueError: If validation fails for any reason.
+    """
+
+    info = readThemeInfo(altheme_path)
+    readThemeQss(altheme_path)  # validates existence and non-empty
+    return info
 
 def wrapQssToAtheme(
     qss_path: str,
@@ -119,7 +187,7 @@ def wrapQssToAtheme(
     filename = os.path.splitext(os.path.basename(qss_path))[0]
     info = {
         "name": filename,
-        "author": "未知",
+        "author": "未知作者",
         "need_theme": current_theme,
         "brief": "没有相关简介"
     }