WinAgent-Lite 🤖🖱️

Ein GUI-Agent, der von lokalen visuellen Modellen angetrieben wird – und zugleich ein Plug-and-Play-MCP-Plugin, das jeder KI-Plattform „Augen“ und „Hände“ verleiht.

Ein gewöhnlicher Rechner ohne separate Grafikkarte: Ein lokales kleines Modell dient als „Auge“ (erkennt Bildelemente auf dem Bildschirm), und echte Tastatur-/Mausereignisse dienen als „Hand“ (bedient beliebige Software wie ein Mensch). Mit einem Evaluationssatz wird die Erfolgsquote messbar. Von „vorführbar“ über „messbar“ bis hin „von jeder Plattform aufrufbar“.

Was es kann

Wie ein Plugin bei Bedarf einbindbar: Die Plattform hängt 9 Werkzeuge in ihre eigene Werkzeugliste (look / click / type_text / key / act / run_scenario / doctor / screenshot / discover). Muss „welcher Button geklickt werden", sucht act erhängt, muss „auf den Bildschirm geschaut“ werden, so kommt screenshot zum Zug – die Zusammenarbeit mehrerer Programme orchestriert der Host, und WinAgent-Lite übernimmt einfach die realen Funktionen der Vision und der task. Die Anbindung ist in docs/PLUGINS.md beschrieben.

Related MCP server: atomic-computer-mcp

Architektur

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 验证

Schnellstart

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 插件模式运行

Als MCP-Plugin verwenden (Einrichtung in 30 Sekunden)

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

Danach kann deine KI-Plattform: mit screenshot deinen Bildschirm sehen → mit click irgendeine Software klicken → mit type_text tippen.

Detaillierte Konfiguration, Sicherheitsgrenzen und Fehlersuche je Plattform: docs/PLUGINS.md.

Plattformunterstützung

Ergebnisse & Messtreiche – Reale Beobachtungen

• Baseline v0.2: In einer gesunden Umgebung 7/10 Aufgaben mit 100 % Erfolg, die restlichen 3 sind ehrliche serving Werte an der Modellgrenze

• Ausführlicher Bericht: docs/baseline_v0.2.md; jede Läuft transversale Ka reproducible (winagent Bench)

• Kernaussagen (sieben Punkte memory jedes durch kontrollierte Experimente unterstützt):

  1. Dialoge wie „Speichern unter“ sind immun gegen synthetische Eingaben → Interaktionsgestaltung ohne Dialoge

  2. Systematische Koordinatenabweichung von 1~3 % der visuellen Erkennung → „Verifizieren + Retry mit Toleranz“ im Regelkreis hat sich als selbstheilend erwiesen

  3. Eingabe nach Zeichentypen getrennt: Unicode für Ziffern/Buchstaben/Chinesisch (umgeht ist das Sommer); Satzzeichen und Operatoren laufen atomar über virtuelle Tasten

  4. Feste sleepswerte als Wetter-Spiel verlieren bei Fensterbereitmachung → stattdessen Fronttitel abrufen (focus wait)

  5. Win11-Notitis Wiederherstellung alt-Tabs wieder auf → das Evaluations, zur SimSetup wird TabState gelöscht

  6. Höherprivilegierte Fenster sind für nicht erhöhte Agents unvorhandenbar → für Evaluierung muss die Umgebung gesichert sein

  7. Abstufungen beim Plagiate-Modell: 3b blind; 7b + Toleranz = guter Kosten-Nutzen; 27b langsam und abgelenkt (auf heimo ohne eigene GPU)

Leistung & Konfiguration

• image_format: jpeg macht den Request-Corpse rund 10× kleiner; capture_monitor erfasstonly den Bildschirm; typing_interval_ms regelt the pace

• Model-Sitzungsspeicherung über den parameterbehafteten Server OLLAMA_KEEP_ALIVE (global weiterfunkt)

• Alle vollständigen Configuration in config.example.yaml, werden beim Registratieren abgefedert/validiert

Sicherheitsgrenzen

• Networknachricht beschränkt auf local host/internet (SSRF-Schutz), subprocess mit Vollweißlisteliteral: Operation auf Dateien nur im Temp-Verbreich-erlaubt

• Aktionswerkzeuge bedienen die echte Maus/Tastatur – der Host soll sie nur nach Authentifizierung abrufen; all doctor/disを/discover/screenshot sind durchgängig passive

Projektstatus

• Versionscalendar und Changelog: CHANGELOG.md (v0.1 → v0.4)

• Community-Daten: Beitragsleitung / Issue-Vorlagen / PR-Vorlagen / Verhaltensandeckung / SicherheitsPolitik – Health Score 100

• Studentenprojekt: oben von angefangen auf einem Rechner ohne Nvidia-Karte und ohne““ die Richtung“ nicht relevant? Bis hin zu einem gemessenen Ablauf

Lizenz

MIT