# qflow

**Repository Path**: yeguangsen/qflow

## Basic Information

- **Project Name**: qflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## GA - 可视化桌面自动化引擎 (Desktop Automation Engine)

<p align="center">
  <img width="800" src="https://github.com/user-attachments/assets/9156e397-70e3-4da1-a7a4-4250bccbc2d9" alt="GA Demo">
  <br>
  <b>无需编程基础，通过节点拖拽实现强大的桌面自动化流程。</b>
</p>

## 📖 简介 (Introduction)

**GA** 是一个基于 Python 开发的轻量级、可视化自动化流程引擎。通过简单直观的节点拖拽与连线，即可构建复杂的桌面自动化任务。

*   **完全开源**：透明的逻辑实现，无后门。
*   **绿色便携**：无需繁琐的数据库配置，即开即用。
*   **隐私安全**：纯离线运行，不联网，不上传任何数据。
*   **低资源占用**：无需独显，普通办公电脑即可流畅运行。

---

## 🔥 核心功能 (Features)

*   **🎨 可视化编排**：支持节点拖拽、无限画布缩放/平移、框选操作、历史记录（撤销/重做）。
*   **👁️ 视觉感知**：
    *   **智能找图**：集成 OpenCV，支持智能混合、模板匹配、特征匹配，支持未找到时自动滚动页面。
    *   **静止监控**：监控屏幕区域画面是否停止变化（非常适合判断网页或软件是否加载完成）。
*   **🖱️ 物理级外设控制**：支持鼠标点击/移动/拖拽/定向滚动，支持防乱码文本输入及组合键触发。
*   **🔊 音频触发**：内置音频峰值检测（Windows），实现"听到指定声音大小即触发"的自动化操作。
*   **🧠 复杂逻辑流**：
    *   **流控制**：循环 (Loop)、多路径顺序尝试 (Sequence)、条件判断 (Switch)。
    *   **变量与数据**：支持内存变量存取、剪贴板读写，轻松实现多软件之间的数据流转与协同。
*   **🛠️ 沉浸式辅助工具**：内置像素级屏幕截图截取、窗口智能拾取绑定、坐标扣除补偿、实时匹配测试。
*   **📦 一键打包**：支持将构建好的自动化流程一键编译为独立的 `.exe` 应用程序，支持隐藏运行和系统托盘驻留。
*   **⏰ 定时任务**：支持 Windows 任务计划集成，实现自动化流程的定时执行。

---

## 🏗️ 项目架构 (Architecture)

### 目录结构

```
GA/
├── main.py                    # 主程序入口
├── scheduler.py               # 定时任务调度器
├── requirements.txt           # 依赖列表
├── build.cmd                  # 构建脚本
├── Example.ga                 # 示例项目
├── ARCHITECTURE.md            # 架构设计文档
├── LICENSE                    # 许可证
├── src/
│   └── ga/
│       ├── core/              # 核心引擎层
│       │   ├── engine.py      # 自动化引擎 (AutomationCore)
│       │   ├── memory.py      # 运行时内存管理
│       │   ├── event_bus.py   # 事件总线
│       │   └── node_handlers/ # 节点处理器
│       │       ├── flow.py    # 流程控制节点
│       │       ├── io.py      # 输入输出节点
│       │       ├── logic.py   # 逻辑节点
│       │       ├── system.py  # 系统操作节点
│       │       └── vision.py  # 视觉节点
│       ├── services/          # 服务层
│       │   ├── window_service.py    # 窗口服务
│       │   ├── vision_service.py    # 视觉服务
│       │   ├── keyboard_service.py  # 键盘服务
│       │   ├── audio_service.py     # 音频服务
│       │   └── clipboard_service.py # 剪贴板服务
│       ├── ui/                # 用户界面层
│       │   ├── config.py              # UI 配置与主题
│       │   ├── components.py          # UI 组件 (ToolTip, LogPanel)
│       │   ├── flow_editor.py         # 流程编辑器画布
│       │   ├── graph_node.py          # 图形节点类
│       │   ├── history.py             # 历史记录管理
│       │   ├── property_panel.py      # 属性面板
│       │   ├── dialogs.py             # 对话框 (导出/定时/设置)
│       │   └── visual_tips.py         # 视觉提示工具
│       └── utils/             # 工具层
│           ├── helpers.py     # 辅助函数 (safe_float, safe_int)
│           └── image.py       # 图像处理工具 (ImageUtils)
└── tests/                     # 测试用例
    ├── test_helpers.py        # 辅助函数测试
    ├── test_image_utils.py    # 图像处理测试
    └── test_runtime_memory.py # 内存管理测试
```

### 模块说明

| 模块 | 职责 | 关键类/函数 |
| :--- | :--- | :--- |
| **core.engine** | 自动化流程引擎 | `AutomationCore` |
| **core.memory** | 运行时变量存储 | `RuntimeMemory` |
| **core.event_bus** | 事件发布订阅 | `event_bus`, `EngineEvents` |
| **core.node_handlers** | 节点执行逻辑 | `NodeHandler`, `register_handler` |
| **services.window** | 窗口管理 | `WindowService`, `smart_find_window` |
| **services.vision** | 图像识别 | `VisionService`, `locate`, `compare_images` |
| **services.keyboard** | 键盘操作 | `KeyboardService`, `safe_write` |
| **services.audio** | 音频检测 | `AudioService`, `get_max_audio_peak` |
| **ui.flow_editor** | 流程画布 | `FlowEditor` |
| **ui.property_panel** | 属性配置 | `PropertyPanel` |
| **utils.helpers** | 数据处理 | `safe_float`, `safe_int` |
| **utils.image** | 图像工具 | `ImageUtils`, `img_to_b64`, `b64_to_img` |

---

## 🎮 快速上手 (Quick Start)

### 界面概览

*   **左侧工具箱**：包含所有可用的流程控制节点，按应用控制、逻辑组件、动作执行、视觉/感知分组。
*   **中间画布**：主要工作区。拖入节点进行连接，右键点击节点可呼出操作菜单。
*   **右侧属性面板**：点击任意节点后，在此配置该节点的详细参数（如坐标、图片、命令等）。
*   **底部日志栏**：实时显示当前运行状态、执行节点追踪及报错信息。

### 快捷键

| 操作 | 快捷键 |
| :--- | :--- |
| **启动流程** | `F9` |
| **停止 / 紧急中断** | `F10` |
| **保存项目** | `Ctrl + S` |
| **撤销 / 重做** | `Ctrl + Z` / `Ctrl + Y` |
| **删除选中节点** | `Delete` |
| **多选节点** | 按住鼠标左键拖拽框选 |

### 创建你的第一个流程

1. **拖拽**：从左侧工具栏拖入一个 `▶ 开始` 节点。
2. **抓图**：拖入一个 `🎯 找图` 节点，选中它并在右侧属性面板点击 "📸 抓取目标"，框选屏幕上的图标（如微信图标）。
3. **连接**：点击开始节点右侧的圆圈端口，拖出连线连接到找图节点的输入端口。
4. **动作**：拖入一个 `👆 鼠标` 节点，动作设置为"点击"，连接找图节点的 `found` (找到) 端口。
5. **执行**：点击顶部工具栏的 `▶ 启动`，或按键盘 `F9` 即可自动执行找图点击。

---

## ⚙️ 安装与运行 (Installation)

### 环境要求

*   **操作系统**：Windows 7/10/11
*   **Python 版本**：Python 3.8+

### 可选依赖

| 依赖 | 功能 | 安装命令 |
| :--- | :--- | :--- |
| `pyperclip` | 剪贴板读写 | `pip install pyperclip` |
| `opencv-python` | 高级图像识别 | `pip install opencv-python` |
| `pycaw` / `comtypes` | 音频检测 | `pip install pycaw comtypes` |
| `pystray` | 系统托盘 | `pip install pystray` |

---

## 📋 节点参考 (Node Reference)

### 应用控制

| 节点 | 说明 |
| :--- | :--- |
| `open_app` | 启动外部应用程序 |
| `bind_win` | 绑定指定窗口（支持按标题、进程名、类名匹配） |
| `cmd` | 执行系统命令 |
| `web` | 打开网页 |

### 逻辑组件

| 节点 | 说明 |
| :--- | :--- |
| `start` | 流程开始节点 |
| `end` | 流程结束节点 |
| `loop` | 循环执行（支持无限循环和指定次数） |
| `sequence` | 多路径顺序尝试 |
| `set_var` | 设置内存变量 |
| `var_switch` | 变量条件判断 |
| `clipboard` | 剪贴板读写 |
| `notify` | 显示提示信息 |

### 动作执行

| 节点 | 说明 |
| :--- | :--- |
| `mouse` | 鼠标操作（点击/移动/拖拽/滚动） |
| `keyboard` | 键盘操作（文本输入/组合键） |
| `wait` | 等待延时（支持随机延时） |
| `timer` | 定时等待（指定时间触发） |

### 视觉/感知

| 节点 | 说明 |
| :--- | :--- |
| `image` | 找图并点击（支持多种匹配策略） |
| `if_img` | 条件判断：图片是否存在 |
| `if_static` | 条件判断：屏幕区域是否静止 |
| `if_sound` | 条件判断：是否检测到声音 |

---

## 📦 导出与部署 (Export & Deployment)

### 打包为 EXE

1. 点击顶部工具栏的 `📦 打包发布` 按钮。
2. 在导出向导中配置：
   *   导出目录
   *   应用图标
   *   热键设置（启动/停止/退出）
   *   运行模式（前台/后台/隐藏）
3. 点击"开始打包"，等待编译完成。

### 命令行参数

```bash
python main.py [选项] [文件路径]

选项:
  --run           加载文件后自动运行
  --hidden-run    隐藏窗口后台运行
  --schedule      启动定时任务服务模式
```

---

## 📝 更新日志 (Changelog)

### [2.0.1] - 2026-07-01
- **重构**：项目架构升级为模块化分层设计（core/services/ui/utils）
- **重构**：节点处理器采用注册表模式，替换原有的 if-elif 链
- **重构**：UI 层抽取为独立模块，解耦 App 类依赖
- **新增**：项目名称从 Qflow 更名为 GA

### [2.0.0] - 2026-06-20
- **新增**：支持导出独立（需要GA.exe）的引导执行程序，支持无头/托盘静默运行。
- **新增**：组件增加"随机延时"参数支持。
- **新增**：右侧属性面板在空闲状态下增加图文引导，包含对【变量】组件的用法科普。
- **优化**：重构【键盘】组件组合按键底层驱动，修复 F 区及小键盘无法触发的问题，增强文本输入粘贴模式的防乱码能力。
- **优化**：梳理【鼠标】组件的交互结构，双击操作合并至点击选项；修复定向滚动时坐标未跟随移动导致滚动失效的问题。
- **优化**：优化 AKAZE 特征识图的相似度分值映射，解决"测试能通过但实际运行失败"的严格阈值问题。

### [1.7.6] - 2026-06-19
- **修复**：解决 `WindowEngine` 遍历系统进程快照时，因解码异常导致的句柄泄露问题。
- **修复**：修复图像匹配测试（Test Match）在后台线程调用 UI 导致的偶发性闪退。
- **优化**：统一可选依赖库（如 `pyperclip`, `opencv`）的导入与检查逻辑。

### [1.7.5] - 2026-05-23
- **新增**：提示节点（`notify`）增加 `{ALL_VARS}` 宏支持，可一键打印所有内存变量供调试。
- **优化**：改用原生 `user32.GetCursorPos` 检索绝对物理坐标，解决混合 DPI 缩放下的像素偏离。

---

## 🧪 测试 (Testing)

```bash
# 运行所有测试
python -m pytest tests/ -v

# 运行指定测试
python -m pytest tests/test_helpers.py tests/test_image_utils.py -v
```

当前测试覆盖率：
- `test_helpers.py`：6 个测试用例（safe_float, safe_int）
- `test_image_utils.py`：6 个测试用例（图像编解码、缩略图）
- `test_runtime_memory.py`：10 个测试用例（内存操作、线程安全）

---