WinAgent-Lite 🤖🖱️

ローカル視覚モデル駆動の GUI Agent であり、プラグインとしてすぐ使える MCP プラグインでもあります――あらゆる AI プラットフォームに「目」と「手」をもたらします。

独立 GPU を持たない普通の PC が対象：ローカル小型モデルが「目」となって画面の要素を識別し、実際のキーボード・マウスイベントが「手」となって人間のようにあらゆるソフトウェアを操作する。さらに評価セットで成功率を定量化できる。「デモができる」から「計測できる」へ、そして「あらゆるプラットフォームから呼び出せる」へ。

何ができるか

プラグインのように必要に応じて呼び出す：プラットフォームは 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"] } } }

その後、あなたの AI プラットフォームは次のことを実行できます：screenshot で画面を見る → act ですべてのソフトウェアをクリック → type_text でタイピング。各プラットフォームの詳細設定・安全境界・トラブルシューティング： docs/PLUGINS.md。

対応プラットフォーム

評価結果と実測からのわかったこと

• ベースライン v0.2：クリーンな環境では 10 タスクのうち 7 件が 100%、残り 3 件が誠実なモデル能力の限界を示すデータ

• 完全なレポート：** docs/baseline_v0.2.md**；毎回の実行は再現可能（winagent bench）

• まりな結論（7 つ、すべて対照実験済み）：

  1. 名前をつけて保存のようなダイアログは、合成キーボード入力が効かない → 対話は「ダイアログなし」の配色にする

  2. 視覚座標には 1~3% の系統的な偏りがある → 「検証＋許容誤差リトライ」のクローズドループで実際に自己修復される

  3. タイピングは文字種ごとに振り分ける：アルファベット・数字・中国語は UNICODE（斜めスペース機器入力）、句読点・演算子は仮想キーで原子的に送信

  4. 固定の sleep でタスク開始を待つと初回で負ける → フォアグラウンドのタイトルをポーリング（focus wait）

  5. Win11 メモ帳のセッション復元で古いタブが復活する → 評価前 setup で TabState をクリア

  6. エクスプローラー権限ウィンドウは権限昇格のない seq に「免疫」 → 評価は必ず場をきれいにする

  7. 「目」となるモデルの特性：3b はいずれ / 7b＋容差＝コストパフォーマンスの良いポイント / 27b は遅くて偏る (ディスクリート GPU のない環境)

パフォーマンスと設定

• image_format: jpeg でリクエストボディーが約 10 倍小さくなる；capture_monitor はキャプチャを単一モニタに留めて省力；typing_interval_ms でタイピング速度を可変

• モデルを常駐させたいときは、サーバー側の OLLAMA_KEEP_ALIVE設定が有効（毎回有効）

• 設定の全項目は config.example.yaml を参照。不正な値は読み込み時いつもフォールバックします

セキュリティの境界

• ネットワークリクエストは本機・内網のみ（SSRF 対策）、subprocess は全世界で列挙のリテラルに限定、ファイル操作は Temp ディレクトリに制限

• 操作ツールは実際のキーボード・マウスを通る制御をするため、ホストで認証後に呼び出しください；doctor/discover/screenshot は常に読み取り専用です

プロジェクトの現状

• バージョン履歴と変更内容： CHANGELOG.md（v0.1 → v0.4）

• コミュニティ各種ファイル：愛献ガイド / Issue テンプレート / PR テンプレート / 行為規範 / セキュリティポリシー —— 健全性スコア 100

• 学生プロジェクト：ディスクリート GPU を持たない PC 1 台、「AI のどうやって進んでいいか分からない」といった質問から始まり、4 バージョンにわたる計測可能な Agent に成長した

License

MIT