专业键盘控制鼠标解决方案 - 为Windows平台量身定制的高效鼠标控制工具
KeyMouse 是一个专为 Windows 平台设计的键盘转鼠标控制应用程序，通过键盘输入实现对鼠标的精确控制，包括移动、点击和滚动操作。采用现代化的模块化架构，结合物理引擎和状态机模式，为用户提供流畅、高效的鼠标控制体验。
- 物理引擎驱动: 基于物理计算的平滑鼠标移动和滚动
- 多速度模式: 支持 Shift 和 CapsLock 调节移动速度
- Sticky点击: 支持拖拽操作的粘性左键模式
- 状态机管理: 流畅的模式切换体验
- 区域选择: 可视化网格区域快速定位
- 热键模式: 支持自定义宏命令执行
- 进程隔离架构: GUI 和核心功能独立运行
- 模块化日志: 分层日志系统便于调试
- 错误恢复: 智能错误处理和自动恢复机制
- 系统托盘集成: 便捷的状态监控和控制
- 可视化配置: 直观的图形界面配置工具
- 开机自启: 无缝融入日常工作流程
| 组件 | 要求 |
|---|---|
| 操作系统 | Windows 10/11 |
| Python版本 | 3.8+ (仅开发环境) |
| 内存 | 最少 50MB RAM |
| 权限 | 管理员权限 (用于键盘钩子) |
- 下载: 从 GitHub Releases 下载最新的
KeyMouse-v2.0.0-Windows-x64.zip - 解压: 解压到任意目录（如桌面或D盘）
- 运行: 以管理员身份运行
KeyMouse.exe
# 1. 克隆项目
git clone <repository-url>
cd KeyMouse-test
# 2. 安装依赖
pip install -r requirements.txt
pip install cx_Freeze
# 3. 构建可执行文件
python setup.py build
# 4. 创建发布包
create_release.bat# 安装依赖后直接运行源码
pip install -r requirements.txt
python main.py| 功能 | 按键 | 说明 |
|---|---|---|
| 移动 | i/k/j/l |
上/下/左/右移动 |
| 点击 | ; |
左键点击 |
| 右键 | ' |
右键点击 |
| 中键 | Right Shift |
中键点击 |
| 滚动 | ,/m |
向上/向下滚动 |
| 拖拽 | n |
切换sticky左键模式 |
| 功能 | 按键 | 说明 |
|---|---|---|
| 快速切换 | q |
在控制模式间切换 |
| 全局切换 | Alt + a |
全局热键切换 |
| 区域选择 | f |
进入屏幕区域选择 |
| 命令模式 | h |
进入热键宏模式 |
| 退出程序 | Esc |
安全退出程序 |
| 修饰键 | 效果 | 速度倍数 |
|---|---|---|
| 无 | 正常速度 | 1.0x |
| Shift | 慢速精确 | 0.5x |
| CapsLock | 超慢速 | 0.2x |
- 按
f进入区域选择模式 - 屏幕显示9宫格网格
- 按数字键
1-9快速定位到对应区域 - 自动切换回控制模式
- 按
h进入命令模式 - 执行预定义的宏命令
- 支持发送键盘组合键
# 启动配置界面
python main.py --gui
# 或双击可执行文件并在托盘图标右键选择"配置"KeyMouse 使用 config.ini 文件进行配置：
[Keybindings]
# 基本移动控制
move_up = i
move_down = k
move_left = j
move_right = l
# 鼠标操作
left_click = semicolon
right_click = apostrophe
middle_click = rshift
sticky_left_click = n
# 滚动操作
scroll_up = comma
scroll_down = m
# 模式切换
toggle_mode_internal = q
toggle_mode_hotkey = <alt>+a
enter_region_select_mode = f
command_mode_toggle = h
exit_program = esc
[Settings]
# 移动速度设置
mouse_move_speed = 16
mouse_speed_shift_multiplier = 0.5
mouse_speed_capslock_multiplier = 0.2
delay_per_step = 0.010
# 系统设置
run_as_admin = true
temp_data_dir = temp_data
[SmoothScrolling]
# 物理滚动引擎参数
initial_velocity = 150.0
max_velocity = 1500.0
acceleration = 700.0- 所有键位均可自定义
- 特殊键格式: 用
<>包裹，如<alt>,<ctrl>,<shift> - 组合键支持: 如
<ctrl>+c,<alt>+<f4>
mouse_move_speed: 基础移动速度 (像素/步)mouse_speed_*_multiplier: 修饰键速度倍数delay_per_step: 移动步进间隔 (秒)
initial_velocity: 滚动初始速度max_velocity: 最大滚动速度acceleration: 滚动加速度
KeyMouse 采用多层架构 + 进程隔离的设计模式：
KeyMouse 核心架构
├── 核心逻辑层
│ ├── main.py # 应用入口 & 鼠标控制
│ ├── modeswitch.py # 状态机管理
│ └── scroll_controller.py # 物理滚动引擎
├── 用户界面层
│ ├── gui.py # 配置界面
│ ├── tray_icon.py # 系统托盘
│ └── gui_widgets.py # UI组件库
├── 平台适配层
│ ├── win_platform.py # Windows API
│ └── autostart_manager.py # 系统集成
├── 工具支撑层
│ ├── config_loader.py # 配置管理
│ ├── utool.py # 键码映射
│ ├── path_manager.py # 路径解析
│ └── log_manager.py # 日志管理
├── 扩展功能层
│ ├── key_mapping_mode.py # 热键模式
│ └── region_selector.py # 区域选择器
└── 运行时支持
├── app_runtime.py # 运行时管理
├── process_manager.py # 进程管理
└── event_handler.py # 事件处理
| 模式 | 应用场景 | 优势 |
|---|---|---|
| 状态机模式 | 模式切换管理 | 状态清晰、切换流畅 |
| 观察者模式 | 托盘图标状态同步 | 实时反映程序状态 |
| 策略模式 | 不同平台滚动策略 | 易于扩展和维护 |
| 依赖注入 | 组件间解耦 | 提高测试性和灵活性 |
| 进程隔离 | GUI 和区域选择器 | 提高稳定性和安全性 |
- main.py: 程序入口点，生命周期管理，键盘监听，鼠标控制
- modeswitch.py: 状态机实现，模式切换逻辑，键盘钩子控制
- log_manager.py: 模块化日志系统，调试基础
- scroll_controller.py: 物理滚动引擎，平滑滚动计算
- config_loader.py: 配置文件管理，参数验证
- win_platform.py: Windows API封装，底层鼠标控制
- gui.py: 配置界面实现
- tray_icon.py: 系统托盘集成
- region_selector.py: 屏幕区域选择
- autostart_manager.py: 开机自启管理
# 1. 克隆项目
git clone <repository-url>
cd KeyMouse-test
# 2. 创建虚拟环境 (推荐)
python -m venv venv
venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 安装开发工具 (可选)
pip install pytest pylint black
# 5. 运行测试
pytest tests/KeyMouse-test/
├── main.py # 程序入口
├── config.ini # 配置文件
├── setup.py # 打包脚本
├── requirements.txt # 依赖清单
├──
├── 3_Doc/ # 技术文档
│ ├── README.md # 文档导航
│ ├── architecture/ # 架构文档
│ └── modules/ # 模块文档
├──
├── logs/ # 运行时日志
│ ├── main.log # 主程序日志
│ ├── event_handler.log # 事件处理日志
│ └── error.log # 错误日志
├──
├── tests/ # 测试文件
│ ├── unit/ # 单元测试
│ └── integration/ # 集成测试
└──
└── build/ # 构建输出 (打包后生成)
└── exe.win-amd64-3.13/
├── KeyMouse.exe
├── RegionSelector.exe
└── ...
- Python 风格: 遵循 PEP 8 代码风格
- 类型提示: 使用 typing 模块进行类型标注
- 文档字符串: 使用 Google 风格的 docstring
- 遵循现有模式: 新功能必须符合既定架构
- 配置优先: 可调参数放入 config.ini
- 错误处理: 统一的错误处理和日志记录
- 不要创建用于关闭程序的宏 (如
<alt>+<f4>) - 这会导致键盘钩子残留，造成系统键盘失灵
- 请使用托盘菜单的"退出"选项安全关闭程序
# 运行所有测试
pytest
# 运行特定测试
pytest tests/unit/test_config_loader.py
# 生成覆盖率报告
pytest --cov=. --cov-report=html# 实时监控主日志
tail -f logs/main.log
# 查看错误日志
cat logs/error.log
# 检查特定模块日志
ls logs/*.log- 键盘失灵: 重启程序或重启系统
- 权限不足: 以管理员身份运行
- 配置错误: 检查 config.ini 语法
| 文件 | 描述 | 重要性 |
|---|---|---|
main.py |
程序主入口 | ⭐⭐⭐ |
config.ini |
配置文件 | ⭐⭐⭐ |
modeswitch.py |
状态机实现 | ⭐⭐⭐ |
win_platform.py |
Windows API | ⭐⭐⭐ |
| 文件 | 描述 | 重要性 |
|---|---|---|
gui.py |
配置界面 | ⭐⭐ |
tray_icon.py |
系统托盘 | ⭐⭐ |
region_selector.py |
区域选择器 | ⭐⭐ |
| 文件 | 描述 | 重要性 |
|---|---|---|
log_manager.py |
日志管理 | ⭐⭐ |
config_loader.py |
配置加载 | ⭐⭐ |
utool.py |
键码映射 | ⭐ |
症状: 双击程序无反应或立即关闭
解决方案:
# 检查是否以管理员权限运行
# 查看 logs/error.log 获取错误信息
# 确认 config.ini 文件存在且格式正确症状: 键盘输入不能控制鼠标
解决方案:
# 1. 检查程序模式状态 (托盘图标颜色)
# 2. 尝试按 'q' 切换模式
# 3. 检查 config.ini 中的键位绑定症状: 整个键盘无法输入
解决方案:
# 紧急情况:
# 1. Ctrl+Alt+Del 打开任务管理器
# 2. 结束 KeyMouse.exe 进程
# 3. 如仍无效，重启计算机症状: 鼠标滚动过快或过慢
解决方案:
# 调整 config.ini 中的滚动参数:
[SmoothScrolling]
initial_velocity = 100.0 # 降低初始速度
max_velocity = 1000.0 # 降低最大速度
acceleration = 500.0 # 降低加速度| 代码 | 含义 | 解决方案 |
|---|---|---|
ERR_001 |
配置文件解析错误 | 检查 config.ini 语法 |
ERR_002 |
权限不足 | 以管理员身份运行 |
ERR_003 |
依赖模块缺失 | 重新安装程序 |
KeyMouse 提供详细的模块化日志:
logs/
├── main.log # 主程序日志
├── event_handler.log # 事件处理日志
├── process_manager.log # 进程管理日志
└── error.log # 错误汇总日志使用 create_release.bat 创建的发布包包含：
KeyMouse-v2.0.0-Windows-x64/
├── KeyMouse.exe # 主程序 (23KB)
├── RegionSelector.exe # 区域选择器 (23KB)
├── config.ini # 配置文件
├── python313.dll # Python运行时
├── lib/ # 依赖库目录
├── share/ # 共享资源
├── 启动KeyMouse.bat # 便捷启动脚本
├── 打开配置界面.bat # 配置界面快捷方式
├── 快速使用指南.txt # 简明使用说明
├── 使用说明.txt # 完整README
└── LICENSE # 开源许可证
# 1. 构建程序
python setup.py build
# 2. 创建发布包
create_release.bat
# 3. 得到可分发的zip文件
KeyMouse-v2.0.0-Windows-x64.zip- 下载解压: 用户下载zip文件并解压
- 简单运行: 双击
启动KeyMouse.bat或以管理员身份运行KeyMouse.exe - 即用体验: 无需复杂安装，配置文件就在程序旁边
- ✅ 架构重构: 完成项目整体模块化重构
- ✅ Bug修复: 修复n键sticky模式、滚动功能等已知问题
- ✅ 日志系统: 实现模块化日志系统，各模块日志分离
- ✅ 错误处理: 统一错误处理模式，减少代码冗余75+行
- ✅ 稳定性: 优化进程管理和重启逻辑
- ✅ 打包支持: 完善cx_Freeze打包配置
- 多显示器支持优化
- 自定义鼠标光标样式
- 更多预设配置模板
- 跨平台支持 (macOS, Linux)
- 插件系统
- 云端配置同步
我们欢迎各种形式的贡献！
- Bug 报告: 在 Issues 中详细描述问题
- 功能建议: 提出新功能需求和改进建议
- 代码贡献: Fork 项目并提交 Pull Request
- 文档改进: 完善文档和示例
# 提交信息格式
type(scope): description
# 示例
feat(scroll): 添加自定义滚动速度配置
fix(config): 修复配置文件解析错误
docs(readme): 更新安装说明本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
- 文档: 查看
3_Doc/目录下的详细技术文档 - Issues: 在 GitHub Issues 中搜索已知问题
- 日志: 检查
logs/目录下的运行日志
- 问题反馈: [GitHub Issues]
- 功能建议: [GitHub Discussions]
感谢以下开源项目的支持: