first commit

README.md

@@ -0,0 +1,122 @@
+# 听泉助手
+
+听泉助手是一个用于管理 Cursor 编辑器激活的工具软件。
+
+## 功能特点
+
+- 激活码管理
+- Cursor 编辑器授权刷新
+- 机器码重置
+- 更新禁用
+- 系统托盘支持
+- 自动更新检查
+
+## 项目结构
+
+```
+├── services/           # 服务层 - 处理核心业务逻辑
+│   ├── cursor_service.py   # Cursor服务管理类
+│   └── __init__.py
+│
+├── gui/               # GUI层 - 处理界面相关逻辑
+│   ├── components/    # 可复用的GUI组件
+│   │   ├── widgets.py     # 基础UI组件
+│   │   ├── workers.py     # 后台工作线程
+│   │   └── __init__.py
+│   ├── windows/      # 窗口类
+│   │   ├── main_window.py # 主窗口实现
+│   │   └── __init__.py
+│   └── __init__.py
+│
+├── utils/            # 工具类
+│   ├── version_manager.py  # 版本管理
+│   └── __init__.py
+│
+├── config.py         # 配置管理
+├── logger.py         # 日志管理
+├── common_utils.py   # 通用工具函数
+└── tingquan_assistant.py  # 程序入口文件
+```
+
+## 开发规范
+
+1. 分层设计
+   - services层: 处理核心业务逻辑,与界面解耦
+   - gui层: 只处理界面相关逻辑,通过services层调用业务功能
+   - 工具类: 独立的功能模块(如日志、配置等)
+
+2. 代码规范
+   - 使用类型注解
+   - 函数必须有文档字符串
+   - 遵循PEP 8命名规范
+   - 异常必须合理处理和记录日志
+
+3. 界面设计
+   - 使用PyQt5构建GUI
+   - 所有耗时操作必须在后台线程中执行
+   - 界面组件需实现合理的状态管理
+
+4. 配置管理
+   - 用户配置存储在 %APPDATA%/TingquanAssistant/
+   - 激活信息使用JSON格式存储
+   - 配置文件需要权限控制
+
+5. 日志规范
+   - 所有关键操作必须记录日志
+   - 日志按日期分文件存储
+   - 包含足够的错误诊断信息
+
+## 使用说明
+
+1. 运行入口: `python tingquan_assistant.py`
+2. 开发新功能流程:
+   - 在services层添加业务逻辑
+   - 在gui/components添加必要的界面组件
+   - 在gui/windows中整合界面
+   - 更新配置和日志相关代码
+
+## 环境要求
+
+- Python 3.8+
+- PyQt5
+- Windows 10/11
+
+## 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+## 开发环境设置
+
+1. 克隆仓库
+```bash
+git clone https://git.586vip.cn/oadmin/tingquanzhushou.git
+cd tingquanzhushou
+```
+
+2. 创建虚拟环境
+```bash
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+```
+
+3. 安装依赖
+```bash
+pip install -r requirements.txt
+```
+
+## 构建和打包
+
+使用 `build.bat` 脚本进行构建和打包：
+
+```bash
+build.bat
+```
+
+打包后的文件将在 `dist` 目录中生成。
+
+## 许可证
+
+版权所有 © 2024 听泉助手