Merge pull request 'docs: 添加操作手册' (#3) from main into master

Reviewed-on: http://192.168.3.32:3000/xiaji/countdown/pulls/3

.gitignore

@@ -7,7 +7,6 @@ __pycache__/
 build/
 dist/
 *.spec
-!dist/*.exe
 
 # IDE
 .idea/

SKILL.md

@@ -0,0 +1,13 @@
+## 元数据
+name: pyinstaller个性化打包
+description: 打包的时候，要求生成为一个exe文件，使用ico等等
+
+## 概述
+此 Skill 用于给有GUI界面的python代码，打包的时候，生成一个统一的要求：生成一个exe文件，去掉控制台窗口，使用本目录下的ico文件作为程序的图标。打包时，如果之前有打包过的文件（dist/build 文件夹），自动覆盖旧文件，不用手动确认，一键打包到底。
+
+## 打包命令示例
+python -m PyInstaller --onefile --windowed --icon=图标文件名.ico --name=guba-indicator --exclude-module PyQt5 --exclude-module PyQt5.QtCore --exclude-module PyQt5.QtGui --exclude-module PyQt5.QtWidgets --exclude-module PyQt6 --exclude-module PyQt6.QtCore --exclude-module PyQt6.QtGui --exclude-module PyQt6.QtWidgets python程序名.py
+
+
+## 清除多余文件
+在windows环境下，执行clean.py

clean.py

@@ -0,0 +1,17 @@
+import os
+import shutil
+import glob
+import subprocess
+
+# 2. 清理打包残留文件 等价：rd /s /q build + del /f *.spec
+print("开始清理打包残留文件...")
+# 删除build文件夹
+if os.path.exists("build") and os.path.isdir("build"):
+    shutil.rmtree("build")
+# 删除所有.spec文件
+spec_files = glob.glob("*.spec")
+for spec_file in spec_files:
+    if os.path.exists(spec_file):
+        os.remove(spec_file)
+
+print("✅ 打包完成 + 残留文件清理完毕！exe文件已生成在当前目录")

countdown.py

@@ -17,6 +17,18 @@ class ConfigDialog(QDialog):
         self.init_ui()
 
     def init_ui(self):
+        self.setStyleSheet("""
+            QDialog {
+                background-color: #f5f5f5;
+            }
+            QLabel {
+                color: #333333;
+                font-size: 14px;
+            }
+            QSpinBox, QCheckBox {
+                padding: 5px;
+            }
+        """)
         layout = QFormLayout(self)
         
         # 自定义倒计时
@@ -181,11 +193,23 @@ class TimerApp(QWidget):
 
     def setup_audio(self):
         self.sound = QSoundEffect()
+        
+        # 优先从外部目录加载音频文件
         if getattr(sys, 'frozen', False):
-            base_path = sys._MEIPASS
+            # exe所在目录
+            external_path = os.path.dirname(sys.executable)
         else:
-            base_path = os.path.dirname(__file__)
+            # 当前工作目录
-        alarm_file = os.path.join(base_path, "alarm.wav")
+            external_path = os.getcwd()
+        
+        alarm_file = os.path.join(external_path, "alarm.wav")
+        if not os.path.exists(alarm_file):
+            # 外部没有则从打包的临时目录加载
+            if getattr(sys, 'frozen', False):
+                alarm_file = os.path.join(sys._MEIPASS, "alarm.wav")
+            else:
+                alarm_file = os.path.join(os.path.dirname(__file__), "alarm.wav")
+        
         if os.path.exists(alarm_file):
             self.sound.setSource(QUrl.fromLocalFile(alarm_file))
         self.sound.setLoopCount(3)

操作手册.md

@@ -0,0 +1,78 @@
+# 述职计时器 操作手册
+
+## 一、概述
+
+述职计时器是一款专为述职演讲设计的倒计时工具，支持快捷计时、提前告警、微缩悬浮窗口等功能。
+
+## 二、快速开始
+
+1. 双击 `countdown.exe` 启动程序
+2. 点击 **5分钟** 或 **6分钟** 按钮开始倒计时
+3. 2秒后窗口自动缩小为悬浮模式
+
+## 三、功能说明
+
+### 3.1 主界面
+
+| 按钮 | 说明 |
+|------|------|
+| 5分钟 | 开始5分钟（300秒）倒计时 |
+| 6分钟 | 开始6分钟（360秒）倒计时 |
+| 其它 | 打开配置窗口 |
+
+### 3.2 配置功能
+
+点击 **其它** 按钮打开配置窗口，可设置以下选项：
+
+| 配置项 | 说明 |
+|--------|------|
+| 自定义秒数 | 设置自定义倒计时时长（1-3600秒） |
+| 提前告警(秒) | 设置提前播放告警音的时间（0-300秒） |
+| 窗口置顶 | 勾选后窗口始终保持在其他窗口上方 |
+| 透明度 | 调节窗口透明度（10%-100%） |
+| 距离右边缘 | 微缩窗口距离屏幕右边缘的像素值 |
+| 距离上边缘 | 微缩窗口距离屏幕上边缘的像素值 |
+
+### 3.3 窗口操作
+
+| 操作 | 功能 |
+|------|------|
+| 拖拽标题栏区域 | 移动窗口位置 |
+| 双击微缩窗口 | 暂停倒计时，恢复正常窗口大小 |
+
+### 3.4 告警与提醒
+
+- **提前告警**：倒计时剩余时间达到"提前告警"设定值时，播放3次提示音
+- **倒计时结束**：
+  - 微缩模式：文字红黄闪烁
+  - 正常模式：文字跳动 + 透明度闪烁
+
+## 四、音频配置
+
+程序支持自定义告警音效：
+
+- 将 `alarm.wav` 音频文件放置在 **exe 同目录** 或 **当前工作目录**
+- 程序会优先从外部目录加载，若未找到则使用内置音频
+
+## 五、打包说明
+
+### 5.1 打包命令
+
+```bash
+pyinstaller --onefile --windowed --noconsole --icon=Timer.ico countdown.py
+```
+
+参数说明：
+- `--onefile`：打包成单个exe文件
+- `--windowed` / `--noconsole`：不显示控制台窗口
+- `--icon`：指定程序图标
+
+### 5.2 清理残留文件
+
+运行 `clean.py` 可自动清理打包残留文件并重新生成exe。
+
+## 六、注意事项
+
+1. 首次运行请确保 `alarm.wav` 与 exe 在同一目录，否则告警功能不可用
+2. 微缩窗口位置可在配置中自定义
+3. 窗口支持拖拽，可放置在屏幕任意位置