WinAgent-Lite 🤖🖱️

로컬 비전 모델 기반 GUI 에이전트이자 플러그 앤 플레이 MCP 플러그인 — 모든 AI 플랫폼에 '눈'과 '손'을 부여합니다.

일개별 그래픽 카드가 없는 일반 컴퓨터: 로컬 소형 모델이 눈이 되어 화면 요소를 인식하고, 실제 키보드/마우스 이벤트가 손이 되어 사람처럼 어떤 소프트웨어든 조작합니다. 그리고 평가 세트로 성공률을 정량화합니다. "시연 가능"에서 "측정 가능", 더 나아가 "어떤 플랫폼에서든 호출 가능"에 이르는 과정입니다.

무엇을 할 수 있나요

플러그인처럼 필요한 만큼만 호출: 플랫폼은 look / click / type_text / key / act / run_scenario / doctor / screenshot / discover라는 9개 도구를 자체 도구 목록에 통합합니다. 업무상 "어느 버튼을 클릭할지"가 필요하면 act를 호출하면 되고, "화면을 봐야 한다면" screenshot을 호출하면 됩니다. 다중 소프트웨어 협조는 호스트가 조율하하고, WinAgent는 진품의 '눈'과 '손'만 담당합니다. 접속 방법은 docs/PLUGINS.md에 있습니다.

Related MCP server: atomic-computer-mcp

구조

vision.py    眼睛: 截屏 -> 降采样 -> Ollama VLM -> 坐标/问答      （跨平台）
hand/        手:   win32(user32) | x11(XTest) | macos(Quartz)   （平台后端分发）
agent.py     脑干: 闭环 + 步骤解释器 + 焦点等待 + 容差自愈
bench.py     度量: 任务 YAML(含 setup/teardown) -> 成功率报告
planner.py   规划: 目标 -> 步骤 JSON（本地模型，云 API 适配器预留）
mcp_server.py 插件: MCP stdio server，9 工具，协议一致性 CI 验证

빠르게 시작하기

git clone https://github.com/ZYYDI1959/winagent-lite && cd winagent-lite
python -m venv .venv && .venv/Scripts/pip install -e .
# 需要本机 Ollama（默认模型 qwen2.5vl:7b）
cp config.example.yaml config.yaml

winagent doctor                          # 环境自检（一条命令诊断一切）
winagent look "任务栏右下角的时钟"         # 眼睛：FOUND x,y
winagent click 1824 1056                 # 手：真实点击
winagent run scenarios/notepad_save.yaml # 闭环：YAML 步骤
winagent bench                           # 评测：全任务成功率报告
winagent plan "打开记事本输入你好并保存"     # 规划：目标 -> 步骤
winagent-mcp                             # 以 MCP 插件模式运行

MCP 플러그인으로 사용하기 (30초 연동)

{ "mcpServers": { "winagent": {
    "command": "D:\\winagent-lite\\.venv\\Scripts\\python.exe",
    "args": ["-m", "winagent.mcp_server"] } } }

이제 여러분의 AI 플랫폼은: screenshot으로 화면을 보고 → click으로 어떤 소프트웨어든 클릭하고 → type_text로 입력할 수 있습니다. 플랫폼별 상세 연동 방법, 안전 경계, 문제 해결은 **docs/PLUGINS.md**를 참조하세요.

플랫폼 지원

추가 논문·평가 결과

• 기준 v0.2: 정상 환경에서 7/10 테스크 100%, 나머지 3개는 정줄한 고모델의 능력 한계를 드러낸 데이터 포인트

• 전체 리포트: docs/baseline_v0.2.md; 매 실행 궤적이 재현 가능 (winagent bench)

• 핵심 결론 (7가지, 모두 대조 실험에 근거):

  1. "다른 이름으로 저장" 유형의 대화상자는 합성 키보드 입력에 반응하지 않음 → 상호작용 설계는 "대화 유형 없음" 쪽으로

  2. 시각 좌표에 1~3%의 정형적 편차가 발생함 → 폐루프가 "검증+허용 범위 재시도"로 실재적으로 자가 치유된 으로 확인

  3. 입력은 문자 타입별로 분류해서 전달: 영문·숫자·중국어는 UNICODE로 보내(IME 우회), 문장 부호와 산술 연산자는 가상 키보드 자체 전송으로 처리

  4. 고정 sleep으로 창이 준비될 것이라고 기대하는 것은 반드시 페배함 → 전경(포그라운드) 창 제목 폴링 (focus wait)

  5. Win11 메모장의 세션 복구가 이전 탭을 다시 기르므로 → 평가 셋업에서 TabState 초기화함

  6. 상승된 권한(관리자) 창은 비상승 에이전트에 대해 충돌되지 않음 → 평가 전 해당 수 없는 오가 반드시 차단되어야 함

  7. "눈" 모델의 등급: 3b는 아경도 못 둥청 / 7b+허용 오차=성능비 절정 / 27b는 느리면서 편향됨 (별도 GPU 없는 머신)

성능 및 구성

• image_format: jpeg는 요청 본문을 약 10배 줄인다; capture_monitor는 단일 모니터만 캡처하여 자원을 절약; typing_interval_ms는 타이핑 속도를 조절

• 모델의 상주 유지에는 서버 측 OLLAMA_KEEP_ALIVE를 사용 (전역적으로 적용)

• 전체 설정 항목은 config.example.yaml 참조, 부숙된 값은 로드 시 기본 값으로 안전 처리됨

안전 경계

• 네트워크 요청은 본인 PC/내부망으로만 제한 (SSRF 방지), subprocess는 白hooting 문자 그 리스트만 허용, 파일 조작은 임시 디렉터리로 제한

• 동작 도구는 실제 키보드/리부터를 조작하므로 — 호스트에서 인증한 뒤 호출해야 합니다; doctor/discover/screenshot은 항상읽기 및 관측 전용입니다

프로젝트 상태

• 버전 이력 및 변경 내용: CHANGELOG.md (v0.1 → v0.4)

• 커뮤니티 파일: 기여 가이드 / Issue 템플릿 / PR 템플릿 / 행동 강령 / 보안 정책 — 커뮤니티 건강 점수 100점

• 대학생 프로젝트: 독립 그래픽 카드 없는 PC와 "어떤 AI 계열을 양지 몰랐던" 질문에서 시작하여, 4버째의 측정 가능한 Agent 프로젝트까지 완성

License

MIT