WinKit

Локальная наблюдаемость и диагностика Windows для AI-агентов, предоставляемая через Model Context Protocol (MCP).

WinKit — это MCP-сервер, по умолчанию только для чтения, ориентированный на локальную работу, который предоставляет кодирующим агентам структурированное, разграниченное по правам представление Windows-машины, на которой они работают: процессы, сеть, хранилище, службы, журналы событий, окна и — через первый глубокий адаптер приложений — живую инспекцию вкладок Chrome, а также изолированный управляемый браузер, принадлежащий WinKit, для диагностики локальных веб-приложений. За инструментами стоит детерминированный диагностический движок, который отделяет то, что было измерено, от того, что интерпретировано, так что агент может отвечать на реальные вопросы без догадок. Никакой телеметрии, никакого облака; единственная внешняя поверхность — это управляемый запуск браузера с проверкой разрешений и шлюзом.

v1 по умолчанию только для чтения. Каждый инструмент инспекции возвращает свидетельства, и ничто не может изменить вашу систему. Единственные действия, которые может предпринять WinKit — запуск или закрытие собственных изолированных сессий управляемого Chrome — отключены, если не установлено [chrome.managed] enabled = true, они ограничены отдельным разрешением application.browser.*, которое режимы safe/read_only никогда не предоставляют, и затрагивают только ресурсы, созданные самим WinKit.

Что WinKit отвечает

WinKit построен вокруг трех вопросов, на каждый из которых отвечает инструмент:

Вместе они рассказывают всю историю менее чем за минуту: сначала машина, затем самая тяжелая вкладка, затем, ухудшается ли ситуация.

Related MCP server: DivLens MCP

Основные возможности

• 69 инструментов MCP по областям: система, процессы, сеть, хранилище, оборудование, питание, службы, события, окна, среда разработчика, приложения, Chrome, управляемый браузер и здоровье машины, организованные в профили инструментов (core, developer [по умолчанию], browser, full), чтобы агент видел только то, что нужно.

• Инструменты рабочего процесса разработчика — diagnose_workspace, diagnose_local_webapp, list_dev_servers, ограниченные инструменты wait_for_*, correlate_recent_failures и system_health_trend решают целые проблемы (устаревший порт, неправильный порт, HTTP 500, пустая страница), а не предоставляют сырые измерения.

• Диагностика на основе свидетельств — каждый высокоуровневый отчет представляет собой стабильную оболочку с ранжированными выводами, стабильными идентификаторами выводов/свидетельств и языком уверенности confirmed/observed/likely/possible/unknown, который никогда не утверждает причинно-следственную связь на основе временной близости. Чистая пороговая логика: никакой LLM, никакой случайности, никаких сфабрикованных утверждений.

• Честная полнота — system_diagnose сообщает evidence_completeness: "full" | "limited", когда измерение не удалось выполнить, и неудачные измерения исключаются из набора здоровых. WinKit сообщает вам, что он не смог увидеть.

• Глубокая инспекция Chrome через CDP — вкладки, производительность, память, сеть, консоль времени выполнения, комбинированный диагностический отчет и выборочный тренд. Заголовки, куки и тела запросов никогда не захватываются.

• Изолированный управляемый браузер — chrome_start_managed_session запускает Chrome, принадлежащий WinKit, с одноразовым профилем и конечной точкой DevTools только на loopback, инспектирует страницу (chrome_get_page_summary, chrome_capture_screenshot), а chrome_stop_managed_session закрывает его и удаляет профиль. Только Windows x64; Chrome никогда не загружается. По умолчанию с окном: открывается реальное видимое окно Chrome (без флага --headless, без обходных путей для GPU только для headless, размер окна 1280x900). Если запуск с окном по умолчанию аварийно завершается во время запуска (сбой GPU-процесса), проверенный запасной вариант с окном и программным рендерингом (headed-software) открывает то же видимое окно — оно никогда не становится скрытым или безголовым. Headless является опциональным (headless: true) и по замыслу не открывает окно; он рендерит на программном пути с безопасными фиксированными аргументами (headless-software: --disable-gpu --disable-gpu-compositing --use-angle=swiftshader --disable-gpu-program-cache --disable-gpu-shader-disk-cache; запускается запасной внутренний GPU-процесс, если программный режим аварийно завершается при запуске). Выбранный режим всегда сообщается (headless, window_mode, launch_mode) и никогда не изменяется молча. Сессия объявляется ready только после того, как браузер переживает короткую проверку успокоения — DevTools может стать доступным за мгновения до того, как Chrome умирает (например, сбой GPU-процесса), поэтому ready никогда не возвращается только потому, что /json/version ответил один раз. stdout браузера перенаправляется, чтобы он никогда не мог повредить поток MCP, его stderr захватывается в ограниченный отредактированный хвост для диагностики (включая код выхода GPU-процесса, когда Chrome сообщает о нем), а неожиданный выход убивает дерево процессов (crashpad/GPU/utility/renderer, идентифицируемое по точному пути принадлежащего профиля) и удаляет принадлежащий профиль — никогда не профиль пользователя Chrome. Ограниченный функцией, ограниченный разрешениями, без Playwright, без ручных флагов отладки.

• Многоуровневая модель разрешений — четыре режима (safe, read_only, approval, unrestricted) для 14 возможностей чтения v1 плюс отдельно ограниченные возможности действий application.browser.launch/navigate/close. Отказы объясняют, что именно требуется.

• Архитектура провайдеров — все стоит за трейтами WindowsBackend / ApplicationProvider; реальный слой Win32 полностью отделим, а мок-бэкенд с детерминированными фикстурами обеспечивает набор из 381 теста (cargo test --features mocks) без зависимости от машины.

• Укрепленный по построению — ограниченные результаты, тайм-ауты для каждого инструмента, ограничения полезной нагрузки, лимит кадра транспорта 8 МиБ, строгая валидация схемы JSON и stdout, поддерживаемый в чистоте протокола (вся диагностика идет в stderr).

• npm-дистрибуция — два пакета, @winkit/mcp (запускатель) и @winkit/win32-x64-msvc (среда выполнения Windows x64), устанавливаются с помощью npx --yes @winkit/mcp@latest. Никаких скриптов установки, никаких зависимостей для автоматизации браузера; нативный исполняемый файл — деталь реализации.

• Навык агента — skills/winkit-developer-debugging/SKILL.md учит кодирующих агентов маршрутизации вопрос→инструмент, выбору разрешений и профилей, а также границам safe/read-only.

• Набор для оценки — tests/eval/ — это набор из 18 детерминированных сценариев на основе фикстур, который проверяет статус, свидетельства, идентификаторы выводов, подтверждающие/опровергающие свидетельства, редактирование, ограниченный вывод, поведение разрешений и отсутствие ложных утверждений о первопричинах для режимов сбоев, которые WinKit предназначен диагностировать.

Быстрый старт

Требования: Windows 10/11 x64 и Node.js >= 18 (путь npm) или Rust 1.75+ (из исходников).

npx --yes @winkit/mcp@latest doctor   # verify the install

Или сборка из исходников:

cargo build --release
.\target\release\winkit --help

WinKit запускается MCP-клиентом как подпроцесс stdio, либо через запускатель npx, либо напрямую из собранного бинарного файла (см. docs/mcp-integration.md):

• OpenCode — examples/mcp/opencode.json

• Claude Code — examples/mcp/claude-code.json

• Любой MCP-клиент — examples/mcp/generic.json

Без файла конфигурации WinKit работает с безопасными настройками по умолчанию: режим разрешений read_only, оба встроенных провайдера включены и документированные ограничения. См. config/example.toml для полной поверхности и docs/installation.md для полной истории установки.

Инспекция Chrome и управляемый браузер

Глубокая инспекция Chrome требует, чтобы Chrome предоставлял свою конечную точку DevTools. WinKit может сделать это за вас: с [chrome.managed] enabled = true и разрешением application.browser.launch, chrome_start_managed_session запускает собственный изолированный экземпляр Chrome (одноразовый профиль, конечная точка DevTools только на loopback), поэтому не нужны ручные флаги отладки или отдельный процесс браузера. По умолчанию на рабочем столе открывается реальное видимое окно Chrome; передавайте headless: true только тогда, когда нужна невидимая сессия автоматизации/CI (этот режим по замыслу не открывает окно):

chrome_start_managed_session(url="http://localhost:3000")  # opens a visible Chrome window
  -> chrome_get_page_summary(session_id)     # runtime errors, failed requests, headings
  -> chrome_capture_screenshot(session_id)   # optional visual check
  -> chrome_stop_managed_session(session_id) # closes Chrome, removes the profile

Чтобы инспектировать уже запущенный Chrome (например, тот, который разработчик запустил с --remote-debugging-port), WinKit обнаруживает конечную точку, опрашивая fallback_port (по умолчанию 9222), и подключается через CDP. См. docs/chrome.md для полного жизненного цикла, состояний и правил безопасности.

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

Медианная задержка от начала до конца, измеренная на Windows 10 (8 ядер, 16 ГБ ОЗУ) с релизной сборкой и новым процессом сервера на каждый вызов — поэтому числа включают запуск процесса и рукопожатие MCP initialize:

Инструменты с окном наблюдения масштабируются с настроенным окном, а не с размером системы; все остальные инструменты остаются менее 100 мс независимо от количества процессов, портов или вкладок. Полная таблица и методология: docs/performance.md.

Поверхность инструментов

Полный справочник со схемами аргументов: docs/tools.md.

Архитектура

Конвейер WinKit представляет собой трёхуровневое разделение обязанностей — WinKit измеряет, WinKit интерпретирует сигналы, WinKit ранжирует выводы, подкреплённые доказательствами; LLM объясняет их:

                 WinKit
                   │
      ┌────────────┼────────────┐
      │            │            │
  Observation  Correlation  Diagnosis
      │            │            │
      ↓            ↓            ↓
  Windows/App   Evidence    Findings
    metrics      linking     ranking

server (MCP over stdio, JSON-RPC 2.0, session lifecycle)
  ├── tools        (59 tool definitions + argument handling + registry)
  │     ├── providers (WindowsBackend / ApplicationProvider traits)
  │     │     └── chrome::managed (isolated WinKit-owned sessions)
  │     └── platform::windows (real Win32 implementations, windows-sys 0.59)
  ├── permissions  (modes, capabilities, policy, approval surface)
  ├── config       (winkit.toml, strict, deny-unknown-keys)
  ├── models       (unified data models shared by providers/tools/diagnostics)
  └── diagnostics  (measurements → signals → ranked findings)

Правила уровней строги: поверхность MCP никогда не взаимодействует напрямую с Win32, а уровень Windows тестируется через фиктивный бэкенд (cargo test --features mocks). Подробнее: docs/architecture.md.

Модель безопасности

• Только чтение по умолчанию — каждый инструмент проверки предназначен только для чтения; единственные действия (запуск/навигация/закрытие управляемого браузера) ограничены функциональным флагом [chrome.managed] enabled и запрещены в режимах safe/read_only.

• Режимы разрешений блокируют каждый вызов инструмента перед отправкой, с отдельным шлюзом действий для инструментов жизненного цикла управляемого браузера.

• Управляемый браузер изолирован и самоочищается — одноразовый профиль в управляемом корневом каталоге, DevTools только через loopback, очистка, которая отказывается от любого пути вне управляемого корневого каталога, и он никогда не подключается к обычному профилю Chrome.

• Секреты не захватываются — проверка сети/времени выполнения Chrome обрезает вывод и явно исключает заголовки, куки и тела; URL-адреса редактируются (строки запроса удаляются).

• Ограниченная работа везде — лимиты результатов, тайм-ауты, лимиты полезной нагрузки, лимиты кадров.

• Полные сведения: SECURITY.md и docs/security.md.

Известные ограничения

WinKit рассматривает ограничения как первоклассный вывод, а не ошибки:

• Процент использования ЦП на процесс — это мгновенный образец, а не накопительная мера. Наивный расчёт системного соотношения вводит в заблуждение на многоядерных машинах, поэтому list_processes (дешёвый полный снимок) сообщает cpu_percent: null. Чтобы обнаружить вышедший из-под контроля процесс, get_process берёт мгновенный образец процента использования ЦП из двух выборок за окно в 300 мс с явной основой (system_capacity_all_cores); агрегированное представление (ApplicationGroupInfo) делает то же самое с выборкой в 1 с.

• Chrome не всегда может сопоставить вкладку с PID — адаптер сообщает process_mapping: "none" и продолжает работу с чистыми доказательствами CDP, вместо того чтобы завершаться ошибкой или гадать.

• Некоторые процессы Windows запрещают доступ на чтение — они по-прежнему перечисляются с null для полей, которые не удалось прочитать, и никогда не отбрасываются молча.

• Диагностика различает измеренное и неизмеренное — system_diagnose содержит evidence_completeness, а отчёты могут включать записи limitations, чтобы агенты не переоценивали частичное представление.

• Проверка уже запущенного Chrome требует порта удалённой отладки. Рабочий процесс управляемого браузера устраняет это требование для диагностики локальных приложений: WinKit запускает собственный изолированный Chrome, когда функция и разрешение включены; обычные профили просмотра всегда остаются нетронутыми.

Разработка

cargo check                 # compile checks
cargo build                 # debug build
cargo test --features mocks # full test suite (381 tests)
cargo clippy --all-targets  # lint

# evaluation suite (fixture-backed failure scenarios)
cargo test --features mocks --test eval

# npm launcher + package validation (after cargo build --release)
powershell -ExecutionPolicy Bypass -File npm/scripts/copy-native.ps1
node --test npm/test/launcher.test.js npm/test/package.test.js
powershell -ExecutionPolicy Bypass -File npm/scripts/test-packed.ps1

# opt-in live tests (need a real Windows machine / Chrome install)
$env:WINKIT_LIVE_WINDOWS = "1"; cargo test --features live-windows
# live managed-Chrome lifecycle, both modes (requires an installed Google
# Chrome on an interactive desktop; run ten consecutive isolated runs per
# mode before any release-ready claim)
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headed_start_inspect_stop -- --nocapture
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headless_start_inspect_stop -- --nocapture

Живые тесты управляемого Chrome выводят явную причину пропуска, когда WINKIT_LIVE_CHROME не равен 1; тест с головным режимом также пропускается (отмечая поведение с головным режимом как непроверенное), когда нет интерактивного рабочего стола. Пропущенный живой тест никогда не считается пройденным, и без прохождения обоих режимов на реальной установке Chrome проект не считается "готовым к релизу" (см. docs/release.md).

Интеграционные тесты проверяют протокол MCP, диспетчеризацию инструментов, применение разрешений и фикстуро-ориентированные провайдеры-заглушки, не затрагивая реальную машину; набор для оценки (tests/eval/) охватывает 18 детерминированных сценариев сбоев. См. docs/development.md и CONTRIBUTING.md.

Документация

• docs/installation.md — сборка, настройка, подключение к MCP-клиенту

• docs/architecture.md — уровни, поток данных, модель провайдеров

• docs/diagnostics.md — форма отчёта на основе доказательств и формулы оценки

• docs/security.md — модель угроз и меры защиты

• docs/permissions.md — режимы, возможности, таблица политик

• docs/tools.md — справочник инструментов с аргументами

• docs/configuration.md — каждый ключ конфигурации и значение по умолчанию

• docs/application-adapters.md — как подключаются адаптеры

• docs/chrome.md — обнаружение Chrome, CDP, управляемые сеансы и оговорки

• docs/performance.md — методология тестирования производительности и полная таблица

• docs/demos.md — сценарий из трёх демонстраций и руководство по записи

• docs/mcp-integration.md — примеры настройки клиента

• docs/development.md — сборка, тестирование, участие

• docs/release.md — процесс выпуска и контрольный список

• tests/eval/README.md — как запустить набор для оценки

• skills/winkit-developer-debugging/SKILL.md — навык агента

Лицензия

MIT — см. LICENSE. WinKit является локально-ориентированным и открытым исходным кодом; он не содержит телеметрии и не выполняет сетевых вызовов, кроме зонда Chrome DevTools через loopback.