WinAgent-Lite 🤖🖱️

本地视觉模型驱动的 GUI Agent，还是一个即插即用的 MCP 插件——让任何 AI 平台拥有"眼睛"和"手"。

🎯 目标驱动（v0.6.0 新增，端到端实测）

只说目标，Agent 自己规划、自己动手：

winagent plan "打开记事本，输入你好世界" --execute

本地文本模型把目标分解为步骤 JSON（白名单校验）→ 闭环执行 → 真实窗口输入中文。全程本地推理、零云 API。MCP 宿主同样可调用 plan 工具拿到步骤再自行编排。

📺 B站视频介绍：一分钟看懂 ZCode：会操作浏览器和软件的 AI 编程智能体

安装（Windows / macOS / Linux）

• 便携整合包：下载 Release 里的 winagent-*-portable.zip → 解压 → 运行 install.bat（Win）/ sh install.sh（macOS/Linux）→ 自动装好并自检

• pip 直装：pip install <Release 里的 .whl 下载链接>（py3-none-any，全平台通用）

• 接入 ZCode / Claude / Cursor 等 MCP 平台：见 docs/PLUGINS.md

• 详细安装与硬件矩阵：见 docs/INSTALL.md

一台没有独立显卡的普通电脑：本地小模型当眼睛（识别屏幕元素）＋ 真实键鼠事件当手（像人一样操作任何软件），再用评测集把成功率量化。从"能演示"到"能度量"，再到"能被任何平台调用"。

它能做什么

像插件一样按需调用：平台把 10 个工具挂进自己的工具列表（plan / look / click / type_text / key / act / run_scenario / doctor / screenshot / discover），业务需要"点哪个按钮"就调 act，需要"看屏幕"就调 screenshot，需要"从目标生成步骤"就调 plan——多软件协作由宿主编排，WinAgent 只负责真实的"眼"、"手"和"脑干"。接入方法见 docs/PLUGINS.md。

架构

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：健康环境下 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. 提权窗口对非提权 agent 免疫 → 评测必须清场

  7. 眼睛模型梯度：3b 盲 / 7b+容差=性价比甜点 / 27b 慢且偏（无独显机器）

性能与配置

• 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

• 学生作品：从一台没有 N 卡的电脑、一个"不知道 AI 方向"的问题开始，到 4 个版本的可度量 Agent 项目

License

MIT