WinAgent-Lite 🤖🖱️

Гибрид из локального GUI-агента на визуальной модели и MCP-плагина, который подключается без изменения кода, — даёт любой ИИ-платформе настоящие «глаза» и «руки».

Обычный компьютер без дискретной видеокарты: локальная маленькая модель — как глаза (распознаёт элементы экрана), настоящие события клавиатуры и мыши — как руки (управляет любым ПО по-человечески), а контрольный набор превращает это в измеримые показатели успешности. От «умеет показывать демо» к «умеет измерять результат» и далее к «может вызываться с любой платформы».

Возможности

Вызов по требованию, как у плагина: платформа добавляет 9 инструментов в свой список (look / click / type_text / key / act / run_scenario / doctor / screenshot / discover). Нужно «нажать кнопку» — вызывается 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"] } } }

После этого ваша ИИ-платформа сможет: screenshot — смотреть ваш экран → act — кликать в любой программе → type_text — печатать текст.
Подробная настройка для каждой платформы, границы безопасности, устранение неполадок: ** docs/PLUGINS.md**.

Поддерживаемые платформы

Результаты тестов и практические наблюдения

• Базовый уровень v0.2: в чистой среде 7/10 задач выполнены на 100%, остальные 3 — честные точки данных о границах возможностей модели

• Полный отчёт: ** docs/baseline_v0.2.md**; траектории каждого запуска воспроизводимы (winagent bench)

• Основные выводы (семь, все подтверждены контрольными экспериментами):

  1. Диалоги типа «Сохранить как» невосприимчивы к синтетическому клавиатурному вводу → в проектировании взаимодействия выбираем «без диалогов»

  2. Визуальные координаты имеют систематическое отклонение 1~3% → контур «проверка + повтор с допуском» доказывает самовосстановление

  3. Печать разбивается по классам символов: буквы/цифры/китайский — через UNICODE (в обход IME), пунктуация и операторы — атомарно через виртуальные клавиши

  4. Фиксированный sleep в ожидании готовности окна проигрывает → обязан опрос заголовка активного окна (focus wait)

  5. Win11, восстановление сеанса Блокнота способна воскрешать старые вкладки → в setup тестов нужно очищать TabState

  6. Окна с повышенными привилегиями невидимы для агента без прав → перед тестами обязателены чистая площадка

  7. Градиент моделей-«глаз»: 3b — слепая / 7b + допуск = лучшее соотношение цена/качество / 27b — медленная и смещённая (на машинах без дискретной видеокарты)

Производительность и настройка

• image_format: jpeg — тело запроса меньше ~в 10 раз; capture_monitor — экономия при одном мониторе; typing_interval_ms — регулировка скорости

• Держать модель в памяти — серверное OLLAMA_KEEP_ALIVE (действует глобально)

• Полный список опций — в config.example.yaml; при загрузке некорректные значения заменяется на запасные

Безопасные границы

• Сетевые запросы ограничены localhost / внутренней сетью (защита от SSRF); subprocess — строго по белому списку литералов; файловые операции — только в Temp

• Инструменты действий управляют реальной клавиатурой/мышью — хост должен вызывать их после авторизации; doctor/discover/screenshot по своей природе пассивны

Статус проекта

• История версий: one стартой: ** CHANGELOG.md** (v0.1 → v0.4)

• Комьюнити-файлы: гайд по контрибуции / шаблоны Issue и PR / кодекс поведения / политика безопасности — здоровье 100

• Студенческая работа: от компьютера без видеокарты NVIDIA и вопроса «не знаю, куда двигаться в ИИ» до смодульно измеримого агентного проекта в 4 версиях

License

MIT