Qflow - 시각화 데스크톱 자동화 엔진 (DesktopAutomationEngine)
<p align="center">
<img width="800" src="https://github.com/user-attachments/assets/9156e397-70e3-4da1-a7a4-4250bccbc2d9" alt="Qflow Demo">
<br>
<b style="font-size: 1.1em;">프로그래밍 지식 없이, 노드 드래그 및 연결을 통해 강력한 Windows 데스크톱 사무 자동화 워크플로우를 구축할 수 있습니다.</b>
</p>
📖 개요 (Introduction)
Qflow는 Python 기반으로 개발된 경량의 시각적 노드형 오피스 자동화 엔진입니다. 간단하고 직관적인 노드 드래그 및 베지어 곡선 연결을 통해 복잡한 데스크톱 자동화 작업을 빠르게 구성할 수 있습니다.
- 완전 오픈소스: 투명한 로직 구현으로 백도어가 없습니다.
- 녹색 휴대성: 번거로운 데이터베이스나 서비스 설정이 필요 없으며, 즉시 사용 가능합니다.
.qflow 프로젝트 파일에 직접 연결하여 더블클릭만 하면 열립니다.
- 개인 정보 보호 및 보안: 순수하게 오프라인 로컬에서 실행되며, 네트워크 연결이나 사용자 데이터 업로드가 없습니다.
- 낮은 리소스 점유율: 별도의 그래픽 카드는 필요하지 않으며, 일반 사무용 컴퓨터에서도 원활하게 구동됩니다.
✨ 핵심 기능 (Features)
🎨 시각적 노드 구성
- 20가지의 핵심 노드를 지원합니다.
- 방향 화살표 곡선 및 라인 중계점을 지원합니다.
- 실시간 좌표 상태 표시줄을 제공합니다.
- 50단계의 히스토리 되돌리기/다시 실행 기능을 지원합니다.
👁️ 시각 및 다중 모드 인식
- 스마트 이미지 검색: OpenCV를 통합하여 스마트 혼합, 다중 스케일 템플릿 매칭, AKAZE 특징 매칭을 지원합니다. 시각적 클릭 앵커 오프셋 픽업과 이미지를 찾지 못했을 때의 자동 화면 스크롤 기능을 지원합니다.
- 다중 이미지 감지: 여러 참고 이미지가 모두 나타났는지 동시에 감지할 수 있습니다.
- 정지 모니터링: 지정된 ROI(Region of Interest) 영역의 픽셀 차이를 실시간으로 계산하여 웹페이지나 소프트웨어 화면이 로딩을 완료하고 정지 상태를 유지하는지 판단합니다.
- 음성 감지: Windows WASAPI 기반으로 시스템 오디오 피크를 실시간 모니터링하여 '소리가 출력됨' 또는 '정적 유지' 트리거를 구현할 수 있습니다.
🖱️ 물리 수준의 키보드/마우스 및 시스템 제어
- 마우스 조작: 클릭(단일 / 더블, 좌클릭 / 중앙클릭 / 우클릭), 이동, 드래그, 휠 스크롤을 지원하며, 화면 절대 좌표를 한 번에 가져올 수 있습니다.
- 키보드 입력: 클립보드 보호 붙여넣기 모드(빠른 중국어 입력 시 깨짐 방지 및 입력 후 원본 클립보드 자동 복원)와 전체 키 조합 전송을 내장했습니다.
- 시스템 협업: 프로그램 실행, CMD 명령 실행, 웹페이지 열기, 클립보드 읽기/쓰기, 데스크톱 알림(배너) 기능을 지원합니다.
📋 업데이트 로그 (Changelog)
[3.0.0] - 2026-11-10
- 추가: 완전히 새로운 다크/라이트 투톤 인터페이스를 지원하며, 고해상도 화면에서 선명한 렌더링을 제공하여 글자가 흐릿하게 보이는 문제를 근본적으로 해결했습니다.
- 추가: 캔버스 빈 공간 더블클릭 시 빠르게 검색하고 노드를 추가하는 기능을 지원합니다. 왼쪽 컴포넌트 라이브러리에서 키워드 필터링 및 더블클릭으로 바로 추가할 수 있습니다.
- 추가: [분기] 노드의 단일 조건 판단 및 다중 분기 설정 인터페이스를 개선했으며, [순차] 노드의 단계별 개수 설정을 지원합니다.
- 추가: 노드 우클릭 메뉴에 '이 노드부터 테스트 실행', '디버깅 중단점 전환', '모든 연결 해제'와 다양한 정렬 배치 방식이 추가되었습니다.
- 추가:
.qflow 프로젝트 파일 더블클릭으로 직접 열기, 저장하지 않은 수정 시 종료 알림, 테마 및 단축키 설정 자동 저장을 지원합니다.
- 개선: 화면 이미지 검색 및 화면 모니터링 시 소프트웨어 자체 창을 자동으로 차단하여 에디터 내부의 스크린샷 미리보기를 오인식하는 것을 방지했습니다.
- 개선: 다중 노드를 동시에 드래그할 때의 부드러움을 대폭 향상시켰으며, 마우스 휠 확대/축소 기능이 현재 포인터 위치를 중심으로 이루어지도록 최적화되었습니다.
- 개선: 연결선에 방향 화살표 지시가 추가되었고, 오른쪽 속성 패널에서 매개변수를 수정하면 캔버스 위의 노드 내용이 실시간으로 동기화되어 업데이트됩니다.
- 수정: 이미지 검색 컴포넌트가 테스트 위치 오프셋을 지정할 때 현재 매칭 알고리즘 및 스케일 비율을 동기화하지 않아 이미지를 찾지 못하는 문제를 수정했습니다.
[2.0.0] - 2026-06-20
- 추가: 독립적인
.exe 실행 파일을 내보낼 수 있게 되었으며, 헤드리스/시스템 트레이 무음 실행 및 다중 실행 방지 보호 기능을 지원합니다.
- 추가: [지연] 컴포넌트에 '랜덤 지연' 모드가 추가되어 실제 사람의 작업 리듬을 스마트하게 시뮬레이션할 수 있습니다.
- 추가: 오른쪽 속성 패널에 유휴 상태일 때 그림과 글로 된 가이드를 추가하여, [변수] 컴포넌트 사용법 교육 자료를 포함했습니다.
- 개선: [키보드] 컴포넌트 조합 키 하위 드라이버를 재구성하여 F 구역 및 숫자 키패드가 작동하지 않던 문제를 수정하고, 텍스트 입력 붙여넣기 모드의 깨짐 방지 능력을 강화했습니다.
- 개선: [마우스] 컴포넌트의 상호작용 구조를 정리하여 더블클릭 동작을 클릭 옵션으로 통합했습니다. 방향 스크롤 시 좌표가 이동을 따라가지 않아 스크롤이 작동하지 않던 문제를 수정했습니다.
- 개선: AKAZE 특징 이미지 식별의 유사도 점수 매핑을 최적화하여 '테스트는 통과하지만 실제 실행에서 실패'하는 엄격한 임계값 문제를 해결했습니다.
- 개선: 이미지 검색 컴포넌트의 '미검색 시 스크롤 시도' 기능이 이제 자동으로 마우스를 인식 영역 중앙으로 이동시킨 후 스크롤을 수행하여 경계를 벗어나는 오류를 방지합니다.
[1.7.6] - 2026-06-19
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
- 수정:
WindowEngine이 시스템 프로세스 스냅샷을 순회하는 과정에서 디코딩 예외로 인해 발생하던 핸들 누수 문제를 해결했습니다.
- 수정: 이미지 매칭 테스트(TestMatch)가 백그라운드 스레드에서 UI를 호출할 때 발생하던 간헐적인 충돌(Crash) 현상을 수정했습니다.
- 최적화: 선택적 의존 라이브러리(예:
pyperclip, opencv)의 임포트 및 검사 로직을 통일했습니다.
[1.7.5] - 2026-05-23
- 추가: 알림 노드(
notify)에 {ALL_VARS} 매크로를 추가하여, 모든 메모리 변수를 한 번에 출력해 디버깅할 수 있게 했습니다.
- 최적화: 절대 물리 좌표 검색을 위해 네이티브
user32.GetCursorPos 사용으로 변경하여, 혼합 DPI 스케일링 환경에서의 픽셀 오차를 해결했습니다.
🎮 빠른 시작 (Quick Start)
1. 인터페이스 개요
- 상단 도구 모음: 새로 만들기, 열기, 저장, 다른 이름으로 저장, 실행 취소/다시 실행, EXE로 내보내기, 캔버스 지우기, 시스템 설정 및 실행/일시정지 제어 기능을 제공합니다.
- 좌측 컴포넌트 라이브러리: '흐름 제어', '마우스 및 키보드', '애플리케이션 및 시스템', '이미지 및 인식', '변수 및 클립보드'로 그룹화되어 있으며, 키워드 검색과 드래그/더블 클릭을 통해 추가할 수 있습니다.
- 중앙 노드 캔버스: 핵심 오케스트레이션 영역입니다. 노드의 우측 포트에서 연결선을 끌어내어 다음 노드의 좌측 입력 포트에 연결합니다. 하단 상태 표시줄에는 노드 통계, 좌표 및 스케일 비율이 실시간으로 표시됩니다.
- 우측 속성 패널: 단일 노드를 선택했을 때 상세 매개변수를 편집하며, 여러 노드를 선택했을 때는 빠른 정렬 및 일괄 작업을 제공합니다.
- 하단 실행 로그: 노드의 실행 흐름을 실시간 추적하고, 소요 시간 및 예외 정보를 통계적으로 보여줍니다.
2. 단축키 비교표 (Shortcuts)
| 작업 | 단축키 / 마우스 상호작용 |
|---|
| 흐름 시작 | F9 (설정에서 사용자 정의 가능) |
| ... | |
3. 첫 번째 자동화 흐름 만들기
- 시작점: 소프트웨어를 실행하면, 캔버스에 기본적으로
▶ 시작 노드가 있습니다.
- 이미지 검색: 좌측에서
🎯 이미지 검색/찾기 노드를 드래그하여 가져온 후, 선택된 상태에서 상단의 “🎯 목표 영역 캡처” (또는 우측 패널의 “📸 목표 이미지 캡처”)를 클릭하고 화면상의 목표 아이콘을 사각형으로 지정합니다.
- 연결:
▶ 시작 노드의 우측 출력 포트를 누른 채 곡선으로 끌어내어 🎯 이미지 검색/찾기 노드의 좌측 입력 포트에 연결합니다.
- 후속 동작:
🎯 이미지 검색/찾기 노드는 기본적으로 '찾은 후 왼쪽 클릭' 동작을 포함하고 있습니다. 또한, ⌨️ 키보드 또는 ⏳ 지연(Delay) 노드를 계속해서 드래그하여 가져온 다음, 이미지 검색 노드의 '찾음(Found)' 포트에 연결할 수 있습니다.
- 실행: 상단 도구 모음의 **“▶ 실행 (F9)”**을 클릭하거나 키보드
F9를 직접 누르면 자동으로 실행됩니다.
⚙️ 소스 코드 배포 및 설치 (Installation)
1. 환경 준비
Windows 10 / Windows 11 시스템, **Python 3.8+**가 설치되어 있어야 합니다.
2. 프로젝트 클론
git clone https://github.com/Qwejay/Qflow.git
cd Qflow
3. 의존성 설치
pip install -r requirements.txt
4. 프로그램 실행
📦 핵심 의존성 설명 (Dependencies)
| 의존 라이브러리 | 주요 용도 |
|---|
tkinter / ttk | 네이티브급 경량 데스크톱 GUI 인터페이스 구축. |
| ... | |
⚠️ 면책 조항 (Disclaimer)
본 도구는 개인 학습 및 합법적인 일상 업무 자동화 보조 목적으로만 제공됩니다. 어떠한 소프트웨어/게임 서비스 약관을 위반하는 스크립트나 악성 프로그램 개발에 사용해서는 안 됩니다. 개발자는 본 도구 사용으로 인해 발생하는 모든 직접적 또는 간접적 결과에 대해 책임을 지지 않습니다.
📄 오픈소스 프로토콜 (License)
본 프로젝트는 GPL-3.0 License를 기반으로 오픈소스로 제공됩니다.
📈 Star History
<a href="https://www.star-history.com/?repos=Qwejay%2FQflow&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Qwejay/Qflow&type=date&theme=dark&legend=top-left">
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Qwejay/Qflow&type=date&legend=top-left">
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Qwejay/Qflow&type=date&legend=top-left">
</picture>
</a>