# python project base code 

**Repository Path**: dengxinhua/python-project-base-code

## Basic Information

- **Project Name**: python project base code 
- **Description**: python 桌面项目基础框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-09
- **Last Updated**: 2025-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Coze自动化工具

## 项目概述

Coze自动化工具是一个基于Python开发的Windows桌面GUI应用程序，用于自动化管理和执行Coze.cn平台的智能体和工作流。该工具提供了完整的配置管理、定时任务调度和可视化操作界面。

## 核心功能

### 1. Coze API集成
- **智能体管理**: 连接和管理Coze平台的AI智能体
- **工作流执行**: 自动化执行预定义的工作流程
- **API配置**: 安全存储和管理Coze API密钥和端点
- **实时监控**: 监控API调用状态和执行结果

### 2. 定时任务系统
- **灵活调度**: 支持cron表达式和自定义时间规则
- **任务队列**: 管理多个并发任务执行
- **执行历史**: 记录任务执行日志和结果
- **错误处理**: 完善的异常处理和重试机制

### 3. 配置管理
- **安全存储**: 加密存储敏感配置信息
- **环境配置**: 支持开发、测试、生产环境切换
- **配置验证**: 实时验证配置有效性
- **备份恢复**: 配置文件备份和恢复功能

### 4. 用户界面
- **现代化设计**: 基于Qt Quick (QML)的专业界面
- **响应式布局**: 适配不同分辨率显示器
- **主题支持**: 支持明暗主题切换
- **国际化**: 支持中英文界面

## 技术架构

### 架构设计原则
- **模块化**: 松耦合的模块设计
- **可扩展性**: 易于添加新功能和集成
- **可维护性**: 清晰的代码结构和文档
- **安全性**: 数据加密和安全访问控制

### 技术栈
- **GUI框架**: PySide6 (Qt Quick/QML)
- **HTTP客户端**: httpx/requests
- **定时任务**: APScheduler
- **配置管理**: pydantic + YAML
- **日志记录**: structlog + rich
- **数据存储**: SQLite + SQLAlchemy
- **加密**: cryptography
- **测试**: pytest + pytest-qt

## 项目结构

```
coze_auto_tool/
├── src/                        # 源代码目录
│   ├── core/                   # 核心模块
│   │   ├── config/            # 配置管理
│   │   ├── scheduler/         # 定时任务
│   │   ├── api/              # API客户端
│   │   └── database/         # 数据存储
│   ├── gui/                   # 用户界面
│   │   ├── qml/              # QML文件
│   │   │   ├── components/   # QML组件
│   │   │   └── views/        # QML视图
│   │   ├── components/       # Python-QML桥接组件
│   │   ├── dialogs/          # 对话框
│   │   └── windows/          # 主窗口
│   ├── services/             # 业务服务
│   │   ├── coze/            # Coze服务
│   │   ├── task/            # 任务服务
│   │   └── notification/    # 通知服务
│   └── utils/               # 工具函数
├── tests/                   # 测试代码
├── docs/                    # 项目文档
├── resources/              # 资源文件
│   ├── icons/             # 图标
│   ├── themes/            # 主题文件
│   └── translations/      # 翻译文件
├── scripts/               # 脚本文件
├── config/               # 配置文件
└── requirements/         # 依赖管理
```

## 开发规范

### 代码规范
- **PEP 8**: 遵循Python官方代码规范
- **类型注解**: 使用完整的类型提示
- **文档字符串**: 遵循Google风格文档
- **单元测试**: 测试覆盖率>90%

### Git工作流
- **分支策略**: GitFlow工作流
- **提交规范**: Conventional Commits
- **代码审查**: 必须通过代码审查
- **CI/CD**: 自动化测试和部署

### 安全要求
- **敏感数据**: 必须加密存储
- **API密钥**: 安全管理和轮换
- **输入验证**: 严格的输入验证
- **日志安全**: 避免记录敏感信息

## 部署和分发

### 开发环境运行
```bash
# 克隆项目
git clone <repository-url>
cd coze_auto_tool

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (Windows)
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行应用程序
python src/main_qml.py
# 或使用启动脚本
run.bat
```

### 打包可执行程序

本项目使用PyInstaller将Python应用程序打包为独立的可执行文件。

#### 1. 安装打包依赖
```bash
pip install pyinstaller
```

#### 2. 普通打包（快速测试）
```bash
# 使用预配置的批处理脚本
build.bat

# 或手动执行PyInstaller命令
pyinstaller --clean build.spec
```

#### 3. 调试模式打包
```bash
# 用于开发调试的打包版本
build_debug.bat

# 生成的调试版本包含控制台输出
pyinstaller --clean build_debug.spec
```

#### 4. 打包配置说明

**build.spec配置文件**：
- 包含完整的应用程序资源（QML文件、图标、主题等）
- 自动收集PySide6和其他依赖
- 优化文件大小和启动速度
- 生成单个可执行文件

**输出目录**：
- `build/build/` - 普通版本输出
- `build/build_debug/` - 调试版本输出
- 主要文件：`CozeAutoTool.exe`

#### 5. 测试打包结果
```bash
# 测试普通打包版本
test_build.bat

# 手动测试
cd build/build
CozeAutoTool.exe
```

### 创建专业安装程序

本项目使用NSIS (Nullsoft Scriptable Install System) 创建Windows专业安装程序。

#### 1. 安装NSIS
- 下载并安装 [NSIS 3.08+](https://nsis.sourceforge.io/Download)
- 确保NSIS安装路径已添加到系统PATH环境变量

#### 2. 自动构建安装程序
```bash
# 完整的构建流程（推荐）
build_installer.bat
```

这个脚本会自动执行以下步骤：
1. 清理旧的构建文件
2. 使用PyInstaller打包应用程序
3. 使用NSIS创建专业安装程序
4. 生成最终的安装包

#### 3. 手动构建步骤

**步骤1：打包应用程序**
```bash
pyinstaller --clean build.spec
```

**步骤2：编译安装程序**
```bash
# 使用NSIS编译器
makensis installer.nsi
```

#### 4. 安装程序特性

**installer.nsi配置**：
- **现代化界面**：使用MUI2现代界面
- **智能安装**：自动检测系统要求
- **路径管理**：用户数据存储在AppData目录
- **卸载支持**：完整的卸载功能
- **快捷方式**：桌面和开始菜单快捷方式
- **版本检测**：检查是否已安装旧版本
- **权限处理**：合理的权限配置，避免管理员权限问题

**安装程序功能**：
- 安装程序文件到Program Files
- 创建用户数据目录（AppData\Local\CozeAutoTool）
- 注册卸载信息到控制面板
- 创建桌面和开始菜单快捷方式
- 智能检测并处理文件占用

#### 5. 输出文件
```
CozeAutoTool_Setup_v1.0.0.exe    # 最终安装程序（约126MB）
```

#### 6. 安装程序配置选项

**installer_options.py**：动态生成安装程序配置，包括：
- 应用程序版本信息
- 文件路径配置
- 安装选项设置

### 高级打包选项

#### 1. 自定义图标
```python
# 在build.spec中配置
icon='resources/icons/app.ico'
```

#### 2. 包含额外资源
```python
# 在build.spec的datas配置中添加
datas=[
    ('src/gui/qml', 'gui/qml'),
    ('resources', 'resources'),
    ('config', 'config')
]
```

#### 3. 优化打包大小
- 排除不必要的模块
- 压缩资源文件
- 使用UPX压缩（可选）

#### 4. 多平台支持
虽然当前专注于Windows，但架构设计支持未来扩展到其他平台：
- macOS：使用py2app
- Linux：使用PyInstaller + AppImage

### 故障排除

#### 常见打包问题
1. **模块缺失**：在build.spec中添加hiddenimports
2. **资源文件缺失**：检查datas配置
3. **Qt插件问题**：确保包含所需的Qt插件
4. **路径问题**：使用绝对路径或相对于spec文件的路径

#### 安装程序问题
1. **权限问题**：检查UAC设置和requestExecutionLevel
2. **文件占用**：确保应用程序完全关闭后再安装
3. **路径问题**：检查NSIS脚本中的路径配置

### 打包方式
- **PyInstaller**: 打包为独立可执行文件
- **NSIS**: Windows安装程序
- **自动更新**: 内置更新检查机制

### 系统要求
- **操作系统**: Windows 10/11 (64位)
- **Python版本**: 3.9+ (开发环境)
- **内存**: 最小512MB，推荐1GB+
- **磁盘空间**: 150MB（安装程序约126MB）
- **依赖**: Visual C++ Redistributable（通常系统已安装）

### 版本发布流程
1. **代码测试**：确保所有测试通过
2. **版本标记**：更新版本号和changelog
3. **自动打包**：执行`build_installer.bat`
4. **质量检查**：测试安装程序和主要功能
5. **发布分发**：上传到发布渠道

## 运行项目

### 快速开始
### 快速开始

**对于最终用户**：
1. 下载 `CozeAutoTool_Setup_v1.0.0.exe`
2. 运行安装程序，按提示完成安装
3. 启动应用程序开始使用

**对于开发者**：
```bash
# 克隆项目
git clone <repository-url>
cd coze_auto_tool

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行应用程序
python src/main_qml.py
```

### 开发环境配置
```bash
# 安装开发依赖
pip install -r requirements/dev.txt

# 运行测试
pytest

# 代码格式化
black src/
isort src/

# 类型检查
mypy src/
```

### 构建和打包
```bash
# 构建可执行程序
build.bat

# 构建专业安装程序
build_installer.bat

# 测试打包结果
test_build.bat
```

## 开发计划

### 第一阶段 (核心功能)
1. 项目框架搭建
2. 基础QML界面
3. Coze API集成
4. 配置管理系统

### 第二阶段 (高级功能)
1. 定时任务系统
2. 日志和监控
3. 错误处理机制
4. 单元测试覆盖

### 第三阶段 (优化完善)
1. 界面美化和优化
2. 性能优化
3. 文档完善
4. 打包和分发

## 许可证

本项目采用MIT许可证。详见 [LICENSE](LICENSE) 文件。