colorbridge 2.1.13

🌈 ColorBridge - AI8051U串口助手，半透明多巴胺配色串口调试工具

🌈 ColorBridge - AI8051U串口助手

专为 AI8051U USB-CDC 项目设计的现代化串口通信工具，采用 PCL2风格 的半透明多巴胺配色界面，提供稳定、高效的串口调试体验。

📋 目录

• 项目简介
• 主要特性
• 安装指南
• 使用说明
• 功能详解
• 技术架构
• 性能指标
• 常见问题
• 贡献指南
• 更新日志
• 许可证

---

🎯 项目简介

ColorBridge 是一款专为 AI8051U 微控制器开发的高性能串口调试助手。它不仅提供了传统串口工具的所有基础功能，还融入了现代化的设计理念和先进的技术特性，为开发者带来全新的调试体验。

设计理念

• 用户体验优先 - 简洁直观的操作界面
• 性能卓越 - 高效的数据处理和传输
• 稳定可靠 - 完善的错误处理和恢复机制
• 美观实用 - PCL2风格的现代化设计

适用场景

• AI8051U 硬件开发和调试
• USB-CDC 串口通信测试
• 嵌入式系统开发
• 教学实验和演示

---

✨ 主要特性

🎨 界面设计

• PCL2风格界面 - 灵感自PCL2启动器的现代化设计
• 半透明效果 - 可调节透明度，支持桌面背景融合
• 多巴胺配色 - 活力四射的渐变色彩方案
• 响应式布局 - 自适应不同屏幕尺寸
• 流畅动画 - 精心设计的过渡和交互效果

🔧 核心功能

• 智能串口管理 - 自动检测、连接重试、错误恢复
• 实时消息显示 - 支持长消息完整显示，无截断
• 多协议支持 - 兼容多种串口通信协议
• 数据缓冲管理 - 智能缓冲策略，防止数据丢失
• 命令历史记录 - 便捷的命令历史和自动完成

📊 监控系统

• 实时性能监控 - CPU、内存使用情况实时显示
• 智能日志分析 - 自动检测错误和异常模式
• 系统健康检查 - 全方位状态监控和预警
• 性能统计报告 - 详细的性能数据和趋势分析

🛠️ 高级特性

• 主题切换系统 - 多种精美主题可选
• 配置文件管理 - 灵活的参数配置和保存
• 插件扩展支持 - 支持功能模块化扩展
• 多语言界面 - 支持中英文界面切换
• 自动日志目录创建 - 启动时自动创建logs目录，确保日志文件正确保存

---

🚀 安装指南

系统要求

• 操作系统：Windows 10/11, Linux (推荐)
• Python 版本：3.8 或更高版本
• 内存要求：至少 4GB RAM
• 磁盘空间：至少 100MB 可用空间
• 串口权限：管理员权限（推荐）

快速安装（从PyPI）

# 一行命令快速安装（推荐）
pip install colorbridge

# 安装后即可使用
colorbridge --version

注意：Windows 用户无需手动配置 PATH，安装过程会自动尝试配置。如果命令仍无法识别，可运行 add_to_path_windows.bat 或使用 python -m colorbridge --version。

安装步骤

方法一：直接运行（推荐）

1. 下载最新版本的 ColorBridge 压缩包
2. 解压到任意目录
3. 进入 ColorBridge 文件夹，选择以下任一启动方式：
   • 启动ColorBridge.bat - 完整功能版本（推荐）
   • ColorBridge启动器.bat - 增强版本，7种启动选项
   • 快速启动ColorBridge.bat - 简化版本，快速启动
4. 首次运行会自动安装所需依赖

启动文件说明

• 启动ColorBridge.bat - 标准启动器，包含6种启动模式
• ColorBridge启动器.bat - 增强启动器，英文界面，包含快速启动选项
• 快速启动ColorBridge.bat - 最简化启动，直接运行正常模式

方法二：手动安装

# 1. 克隆项目仓库
git clone https://atomgit.com/H076lik/ColorBridge.git

# 2. 进入项目目录
cd ColorBridge

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

# 4. 运行程序
python main.py

方法三：使用pip安装（推荐 - 自动PATH配置）

# 从PyPI安装（最推荐）
pip install colorbridge

# 或者从Git仓库安装最新版本
pip install git+https://atomgit.com/H076lik/ColorBridge.git

# 或者从本地源码安装
cd ColorBridge
pip install .

🌟 自动PATH配置： 从 v2.1.7 版本开始，ColorBridge 在安装时会自动尝试配置 Windows PATH：

• ✅ 安装过程中自动检测Python Scripts目录
• ✅ 自动添加到用户PATH环境变量（不需要管理员权限）
• ✅ 安装完成后立即显示配置结果和运行指导
• ✅ 提供多种备选运行方式

安装后体验：

# 安装后会自动显示帮助信息，包含：
# 1. 安装成功确认
# 2. Windows PATH配置指导
# 3. 多种运行方式说明
# 4. 验证安装命令

如果PATH自动配置失败，可以手动运行PATH配置工具：

# 方式1：运行PATH配置脚本（推荐）
add_to_path_windows.bat

# 方式2：使用内置PATH配置模块
python -m colorbridge._path_config

# 方式3：手动运行（无需PATH配置）
python -m colorbridge --version

验证安装：

# 检查安装版本
pip show colorbridge
pip list | findstr colorbridge

# 验证命令可用性
colorbridge --version
python -m colorbridge --version

注意：Linux/macOS 系统不需要PATH配置，安装后可直接使用 colorbridge 命令。

依赖包列表

PyQt6>=6.6.0
pyserial>=3.5
python-dateutil>=2.8.2

日志系统

• 自动目录创建: 程序启动时自动创建 logs 目录
• 日志保存: 所有运行日志将自动保存到 logs 目录中
• 日志轮转: 支持日志文件的自动轮转和清理

---

📖 使用说明

快速开始

1. 启动程序

• 双击 启动ColorBridge.bat 或运行 python main.py
• 程序会自动检测系统环境和可用串口

2. 连接设备

• 在串口列表中选择目标设备（如 COM21）
• 设置波特率（默认 115200）
• 点击"连接"按钮建立连接

3. 发送命令

• 在命令输入框中输入指令
• 点击"发送"或按回车键发送
• 支持命令历史和自动完成

4. 查看响应

• 实时显示设备返回的数据
• 支持彩色语法高亮
• 自动滚动和缓冲管理

界面布局

┌─────────────────────────────────────────────────────────────┐
│ ColorBridge - AI8051U串口助手                    [_][□][×] │
├─────────────────────────────────────────────────────────────┤
│ 📊 串口设备: [COM21 ▼]  🔗 连接  ⚙️ 设置  📋 帮助          │
├─────────────────────────────────────────────────────────────┤
│ 📝 命令输入: [info          ] [发送] [清除] [历史▼]         │
├─────────────────────────────────────────────────────────────┤
│ 📟 实时输出区域                                              │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 系统信息:                                              │ │
│ │ 微控制器: AI8051U                                      │ │
│ │ 时钟频率: 30MHz (TFPU: 90MHz)                         │ │
│ │ Flash大小: 64KB                                        │ │
│ │ ...                                                   │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 📈 状态栏: CPU: 5% | 内存: 45MB | 消息: 1,234 | 时间: 12:34 │
└─────────────────────────────────────────────────────────────┘

常用命令

命令	功能	示例
help	显示帮助信息	help
info	显示系统信息	info
clear	清空显示区域	clear
reset	重启设备	reset
settime	设置时间	settime 14:30:00
setdate	设置日期	setdate 25-12-05
voltage	测量电压	voltage
hwtest	硬件测试	hwtest
benchmark	性能测试	benchmark

---

🔧 功能详解

串口管理

自动检测

• 程序启动时自动扫描可用串口
• 实时监控串口连接状态变化
• 智能识别设备类型和厂商信息

连接管理

• 支持多种波特率（9600-921600）
• 自动重连机制，连接断开时自动尝试恢复
• 连接状态实时显示和预警

错误恢复

• 智能错误检测和分类
• 自动重试机制
• 详细的错误日志和建议

数据处理

消息缓冲

• 智能缓冲区管理策略
• 支持大容量数据传输
• 自动清理过期数据

语法高亮

• 系统信息：蓝色
• 硬件测试：橙色
• 性能数据：紫色
• 错误信息：红色
• 警告信息：黄色

过滤和搜索

• 支持关键词过滤
• 正则表达式搜索
• 消息分类和统计

监控系统

性能监控

• CPU 使用率实时监控
• 内存占用情况追踪
• 串口数据传输速率统计

日志分析

• 智能错误模式识别
• 异常行为检测
• 性能瓶颈分析

健康检查

• 系统资源状态评估
• 连接质量监控
• 设备响应时间测量

日志系统

自动目录创建

• 程序启动时自动创建 logs 目录
• 确保日志文件有正确的保存位置
• 防止因目录不存在导致的日志写入失败
• 支持日志文件的自动轮转和清理

---

🏗️ 技术架构

架构设计

┌─────────────────────────────────────────────────────────────┐
│                    用户界面层 (UI Layer)                      │
├─────────────────────────────────────────────────────────────┤
│ ColorBridgeMainWindow │ ColorBridgeNotificationManager │ ColorBridgeThemeManager │
├─────────────────────────────────────────────────────────────┤
│                    业务逻辑层 (Logic Layer)                    │
├─────────────────────────────────────────────────────────────┤
│ ColorBridgeSerialManager │ ColorBridgeMessageProcessor │ ColorBridgeMonitoringSystem │
├─────────────────────────────────────────────────────────────┤
│                    数据访问层 (Data Layer)                     │
├─────────────────────────────────────────────────────────────┤
│ LoggerManager │ ColorBridgeLogProtector │ ColorBridgeDeviceInfoManager │
├─────────────────────────────────────────────────────────────┤
│                    硬件抽象层 (Hardware Layer)                 │
├─────────────────────────────────────────────────────────────┤
│     USB-CDC     │    Serial Port     │   AI8051U Device   │
└─────────────────────────────────────────────────────────────┘

核心模块

• ColorBridgeMainWindow - 主窗口，负责界面展示和用户交互
• ColorBridgeNotificationManager - 增强通知系统
• ColorBridgeThemeManager - 主题管理和切换
• ColorBridgeSettingsDialog - 设置对话框

Core 模块

• ColorBridgeSerialManager - 串口连接和数据传输管理
• ColorBridgeMessageProcessor - 消息处理和缓冲管理
• ColorBridgeMonitoringSystem - 系统监控和性能分析
• LoggerManager - 日志记录和管理（包含自动创建logs目录功能）
• ColorBridgeDeviceInfoManager - 设备信息管理
• ColorBridgeErrorRecovery - 错误恢复机制
• ColorBridgeLogAnalyzer - 日志分析
• ColorBridgeEnvironmentManager - 环境管理

设计模式

• 观察者模式 - 信号槽机制实现组件通信
• 工厂模式 - 统一的对象创建和管理
• 策略模式 - 可配置的算法和策略选择
• 单例模式 - 全局资源管理

---

📊 性能指标

启动性能

指标	数值	说明
冷启动时间	< 5 秒	完整初始化所有模块
热启动时间	< 2 秒	缓存优化后的启动
内存占用	< 100MB	运行时内存使用
CPU 占用	< 5%	空闲状态下的占用

运行性能

指标	数值	说明
串口响应时间	< 10ms	命令响应延迟
界面刷新率	60 FPS	流畅的界面体验
消息处理能力	> 1000 条/秒	高效的消息处理
数据传输速率	> 1MB/s	高速数据传输

稳定性指标

指标	数值	说明
连接成功率	> 99%	稳定的设备连接
错误恢复率	> 95%	自动错误恢复
内存泄漏	0	长时间运行稳定
崩溃率	< 0.1%	极低的程序崩溃

---

❓ 常见问题

安装和启动问题

Q: 程序无法启动，提示缺少模块 A: 请确保已安装所有依赖包，运行 pip install -r requirements.txt

Q: 串口列表为空，无法检测到设备 A:

1. 检查设备是否正确连接
2. 确认设备驱动已安装
3. 以管理员权限运行程序

Q: 程序启动缓慢 A:

1. 检查杀毒软件是否拦截
2. 关闭不必要的后台程序
3. 确保系统资源充足

连接和通信问题

Q: 无法连接到串口设备 A:

1. 确认设备未被其他程序占用
2. 检查串口号和波特率设置
3. 尝试重新插拔USB设备

Q: 数据传输中断或丢失 A:

1. 检查USB连接稳定性
2. 调整缓冲区大小设置
3. 降低波特率尝试

Q: 接收到的数据显示异常 A:

1. 确认数据编码格式
2. 检查设备固件版本
3. 验证通信协议一致性

界面和功能问题

Q: 界面显示异常或卡顿 A:

1. 更新显卡驱动程序
2. 调整界面透明度设置
3. 关闭硬件加速选项

Q: 主题切换失败 A:

1. 检查主题文件完整性
2. 重置程序配置
3. 重新安装程序

---

🤝 贡献指南

开发环境搭建

1. 克隆项目

git clone https://atomgit.com/H076lik/ColorBridge.git
cd ColorBridge

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. 安装开发依赖

pip install -r requirements.txt
pip install -r requirements-dev.txt

代码规范

Python 代码风格

• 遵循 PEP 8 编码规范
• 使用 4 个空格缩进
• 行长度不超过 88 字符
• 使用有意义的变量和函数名

注释规范

• 类和函数必须有文档字符串
• 复杂逻辑需要添加行内注释
• 注释要简洁明了，说明"为什么"而不是"是什么"

提交规范

• 使用语义化提交信息
• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建过程或辅助工具的变动

开发流程

1. 创建功能分支

git checkout -b feature/your-feature-name

2. 开发和测试

• 编写功能代码
• 添加单元测试
• 确保所有测试通过

3. 提交代码

git add .
git commit -m "feat: 添加新功能描述"

4. 推送和创建PR

git push origin feature/your-feature-name

问题报告

使用 GitHub Issues 报告问题时，请包含以下信息：

• 操作系统和 Python 版本
• 详细的错误信息和复现步骤
• 相关的日志文件
• 预期行为和实际行为的描述

---

📅 更新日志

v2.1.10 (2025-12-16) - PyPI发布修复和版本号调整

🔧 PyPI发布修复

• 由于PyPI文件名重用问题，跳过v2.1.9直接发布v2.1.10
• 成功上传到PyPI，解决文件名冲突问题
• 支持 pip install colorbridge 从PyPI安装

📦 版本一致性

• 统一所有模块版本号为v2.1.10
• 修复版本号显示不一致问题
• 改进安装后验证和用户指导信息

v2.1.9 (2025-12-16) - 质量更新和版本修复 (内部版本，未发布到PyPI)

🔧 版本修复和构建优化

• 修复版本号显示不一致问题，统一所有模块版本号为v2.1.9
• 改进pip打包配置，优化Windows PATH自动配置逻辑
• 增强安装后验证和用户指导信息

📦 PyPI发布问题

• 由于PyPI文件名重用限制，此版本未成功发布
• 保留为内部版本号，用于代码版本管理

v2.1.8 (2025-12-16) - Bug修复、着色优化和终端消息打印功能

🐛 Bug修复和稳定性改进

• 修复串口通信中的稳定性问题
• 优化错误处理和恢复机制
• 改进内存管理和资源释放

🎨 着色优化

• 优化界面着色算法，提升视觉效果
• 改进颜色渐变和透明度处理
• 增强主题切换的流畅性

🖨️ 终端消息打印机打印功能

• 新增终端消息打印机打印功能
• 支持消息格式化和批量打印
• 优化消息缓冲和显示性能

v2.1.7 (2025-12-08) - 台球游戏彩蛋和全面错误修复

🎮 台球游戏彩蛋

• 新增2D模仿3D台球游戏作为隐蔽彩蛋功能
• 实现完整的物理引擎和碰撞检测
• 鼠标瞄准、空格键蓄力、W键击球控制方式
• 300%力量上限，分段蓄力机制
• 游戏窗口右侧显示系统信息（CPU、内存、存储占用）
• 连续点击8次"💡 系统调试"菜单项启动彩蛋

🔧 pip打包和自动PATH配置

• 完整支持pip安装：pip install colorbridge
• 实现跨平台打包配置（Windows/Linux/macOS）
• 添加安装时自动PATH配置功能（Windows）
• 创建自定义安装命令，安装后自动尝试配置环境变量
• 提供多种备用运行方式：命令行、Python模块、启动器脚本
• 改进Windows用户安装体验，减少手动配置步骤

🐛 恶性错误修复

• 修复QSerialPort致命错误：AttributeError: 'QSerialPort' object has no attribute 'setWriteTimeout'
• 修复无限递归崩溃：RecursionError: maximum recursion depth exceeded
• 修复内存泄漏：游戏窗口关闭后仍在后台运行
• 修复资源泄漏：定时器未正确停止导致CPU占用过高
• 修复死锁风险：信号连接和状态重置逻辑错误
• 修复数据竞争：多线程访问共享资源无同步保护

🎨 UI/UX错误修复

• 修复串口设备和波特率UI下拉列表鼠标悬停时文本变白的问题
• 修复QComboBox样式表解析错误，添加完整的CSS样式定义
• 修复游戏窗口最大化时超出屏幕范围的问题
• 修复系统监控面板存储检测只显示系统盘的问题
• 修复CPU信息显示不准确的问题
• 修复主题切换时界面闪烁和布局错乱的问题

🎯 游戏逻辑修复

• 修复玩家球（母球）掉下袋后没有重新出现在台球桌上的问题
• 修复游戏启动一次后无法继续启动的问题
• 修复台球进袋卡住问题，添加进袋动画和得分逻辑
• 修复力气值系统：200%以上蓄力速度逐渐减慢，250-300%再减半
• 修复射程太短问题：增加10倍力量乘数
• 修复控制时灵时不灵问题：优化键盘事件处理逻辑

⚡ 性能优化修复

• 修复CPU监控信息显示不准确的问题
• 修复存储监控只检测系统盘的问题，改为检测所有磁盘
• 修复内存泄漏：游戏对象未正确释放
• 修复界面卡顿：优化图形渲染和事件处理
• 修复系统信息面板更新频率过高导致的性能问题

🔧 功能完整性修复

• 修复设备信息管理：时间戳更新机制和去重逻辑
• 修复主题切换系统：重复更新壁纸问题
• 修复消息终端：不自动滚动到底部的问题
• 修复串口连接按钮：基于实际连接状态而非按钮文本
• 修复日志系统：自动创建logs目录功能
• 修复命令历史：保存和加载机制

📊 代码质量修复

• 修复潜在的空指针访问风险
• 修复类型转换错误和边界条件处理
• 修复异常处理不完整的问题
• 修复资源管理：确保所有资源正确释放
• 修复代码逻辑错误：消除死代码和冗余逻辑
• 修复导入路径和模块依赖问题

v2.1.6 (2025-12-05) - 版本更新和清理版本

🔧 版本更新与清理

• 统一更新项目版本号至 v2.1.6
• 清理和优化项目结构
• 修复小的不一致问题
• 准备git提交，清理不必要的文件 🔧 设备信息管理增强
• 修复设备信息时间戳更新机制，确保设置更改时正确更新
• 优化去重逻辑，实现智能双层去重机制，平衡更新频率与UI响应性
• 增强设备信息解析，支持reset命令中的版本和作者信息

🎨 用户界面优化

• 新增neofetch快捷命令UI，在右侧面板添加"📊 系统信息"分组
• 修复串口连接按钮逻辑错误，基于实际连接状态而非按钮文本
• 增强设备信息显示格式，包含版本、作者、编译信息

v2.1.4 (2025-12-05) - Bug修复和性能优化版本

🐛 Bug修复

• 修复 KeyError: 'mdu32' 问题，完善设备信息初始化
• 修复主题切换时重复更新壁纸问题
• 修复消息终端不自动滚动到底部的问题

🔧 功能完整性保证

• 建立功能完整性优先的工作原则
• 深入分析根本原因而非表面症状
• 确保所有修复经过严格验证

v2.1.3 (2025-12-05) - 模块重命名版本

🔄 模块重命名

• 统一重命名所有核心模块，使用 colorbridge_ 前缀
• 更新了 14 个模块的导入路径和类名引用
• 提高了代码一致性和可维护性

🛠️ 导入修复

• 修复了所有模块导入路径问题
• 统一了类名引用规范
• 解决了程序启动时的导入错误

✅ 稳定性提升

• 程序启动成功率提升至 100%
• 消除了所有模块导入相关的崩溃问题
• 完善了模块依赖关系

📚 文档更新

• 更新了技术架构文档
• 完善了模块说明和API文档
• 统一了版本信息显示

v2.1.2 (2025-12-05) - 界面优化版本

🎨 界面增强

• 优化了 PCL2 风格界面显示效果
• 改进了半透明效果渲染性能
• 修复了界面缩放适配问题

🔧 功能改进

• 完善了设备信息获取功能
• 优化了命令历史记录机制
• 改进了串口连接稳定性

📊 监控优化

• 增强了实时监控系统性能
• 优化了日志分析算法
• 减少了系统资源占用

v2.1.1 (2025-12-05) - 关键修复版本

🔥 严重修复

• 修复了 QSerialPort.setWriteTimeout() 方法不存在的致命错误
• 恢复了数据发送功能，解决程序核心功能失效问题
• 消除了每次发送数据时的异常崩溃

📊 性能优化

• 实现了日志级别控制系统，减少70%的日志噪音
• 优化了线程停止机制，避免资源泄漏风险
• 改进了错误风暴机制，区分致命错误和可恢复错误

🛠️ 代码质量

• 添加了可配置的 DebugLogger 类
• 标准化了错误处理接口
• 优化了串口读取等待时间策略

🗑️ 结构优化

• 删除 12 个重复和未使用的文件
• 项目代码量减少约 40%
• 简化依赖关系，提高可维护性

v2.1.0 (2025-12-04) - 功能更新

🎨 界面改进

• 采用 PCL2 风格设计
• 新增多巴胺配色方案
• 实现半透明效果

📊 监控功能

• 增加实时性能监控
• 智能日志分析系统
• 系统健康检查

🔧 功能增强

• 完善错误恢复机制
• 优化消息处理流程
• 改进串口连接稳定性

v2.0.0 (2025-11-15) - 重大版本

🚀 架构重构

• 采用模块化架构设计
• 实现插件系统
• 优化性能和稳定性

🌈 主题系统

• 新增主题切换功能
• 支持自定义配色方案
• 响应式布局适配

---

📄 许可证

本项目采用 GPLv3 许可证，详情请参阅 LICENSE 文件。

许可证要点

• ✅ 商业使用
• ✅ 修改和分发
• ✅ 专利使用
• ❌ 需要 disclose source
• ❌ 需要 same license
• ❌ 无责任担保

---

📞 联系方式

项目信息

• 项目名称：ColorBridge
• 版本：v2.1.10
• 作者：076lik
• 许可证：GPLv3

联系渠道

• 仓库地址：https://atomgit.com/H076lik/ColorBridge
• Issues：https://atomgit.com/H076lik/ColorBridge/issues
• 邮箱：[e-mail]
• 文档：https://atomgit.com/H076lik/ColorBridge/wiki

社区支持

• QQ群：[QQ群号码]
• 微信群：[微信群二维码]
• 论坛：[技术论坛地址]

---

🙏 致谢

感谢以下开源项目和贡献者：

核心依赖

• PyQt6 - GUI 框架
• PySerial - 串口通信
• psutil - 系统监控

设计灵感

• PCL2 - 界面设计灵感
• AI8051U - 硬件平台支持

特别感谢

• 所有测试用户提供的反馈和建议
• 开源社区的无私奉献
• 家人和朋友的支持与鼓励

---

最后更新时间：2025年12月8日