WinWright

WinWright

适用于 Model Context Protocol 的 Windows 自动化服务。 提供 52 个整合工具，用于桌面应用（WPF、WinForms、Win32）、浏览器（通过 CDP 支持 Chrome/Edge） 和系统管理，可通过 MCP 供 AI Agent 使用，也可在 MCP 受阻时直接通过命令行调用（winwright call …）。

用通俗英语描述测试——其余工作交给 AI Agent

用通俗英语编写测试用例。AI Agent 使用 WinWright 的 MCP 工具来发现 UI 控件、执行操作， 并将所有内容记录为可移植的 JSON 脚本。

重放录制的脚本——无需 AI Agent

录制完成后，可通过 winwright run 确定性地运行脚本——无需 AI Agent、 无需调用大模型，也没有令牌费用。每次运行的结果都相同。

如果 UI 布局发生变化，WinWright 可以自动自愈失效的选择器 （winwright heal）。对于较大的 UI 重新设计，可让 AI Agent 更新脚本—— 这仍比从头重写测试更快。

这很重要，因为：

• 节省 AI 成本——Agent 只需录制一次，之后即可免费重放脚本
• 结果确定——每次运行都会产生相同、可复现的结果
• 易于维护——选择器可自愈，脚本可由 AI 辅助修复

目录

• 快速开始
• 安装
• MCP 客户端配置
• CLI 模式（MCP 受阻时）
• 使用场景
• 工具
• 配置
• 适用人群
• 对比
• 支持
• 许可证

快速开始

安装并配置 MCP 客户端，然后让 Agent 执行操作：

“启动记事本，输入‘Hello from WinWright’，然后读回你输入的内容。”

Agent 调用 WinWright 工具并返回结果：

ww_launch    → { "processId": 12840, "mainWindowTitle": "Untitled - Notepad" }
ww_type      → { "success": true }
ww_get_value → { "value": "Hello from WinWright" }

每个工具都会返回结构化 JSON。由 Agent 决定调用哪些工具以及调用顺序—— 你只需用通俗语言描述目标。

安装

从 GitHub Releases 下载：

资源	架构
winwright-*-win-x64.zip	Intel/AMD 64 位
winwright-*-win-arm64.zip	ARM64（Surface Pro 等）

MCP 客户端配置

Claude Code / VSCode（stdio）

{
  "servers": {
    "winwright": {
      "type": "stdio",
      "command": "C:/path/to/Civyk.WinWright.Mcp.exe",
      "args": ["mcp"]
    }
  }
}

Claude Code / VSCode（HTTP）

先启动服务：Civyk.WinWright.Mcp.exe serve --port 8765

{
  "servers": {
    "winwright": {
      "type": "http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "winwright": {
      "command": "C:/path/to/Civyk.WinWright.Mcp.exe",
      "args": ["mcp"]
    }
  }
}

CLI 模式（MCP 受阻时）

许多企业环境会阻止 MCP。此时可完全通过命令行驱动 WinWright—— 使用相同的工具和自动化流程，Agent 与工具之间无需 MCP 客户端。后台守护进程（一个 loopback serve 实例）负责管理活动会话，因此 ww_launch 返回的 appId 在不同命令之间仍然有效。

winwright tools                          # discover the tool surface (replaces MCP advertisement)
winwright call ww_launch --exePath "C:\Apps\MyApp.exe"   # -> {"appId":"app-1", ...}
winwright call ww_click  --appId app-1 --selector "#submit"
winwright call ww_get_value --appId app-1 --selector "#status"
winwright call ww_close  --appId app-1

JSON 结果输出到 stdout（可安全地通过管道传给 jq）；诊断信息输出到 stderr。守护进程会在首次执行 call 时自动启动，仅绑定到 loopback 地址，并在空闲时自行退出。

由于 CLI 不会像 MCP 那样公布自身功能，因此请安装捆绑的 Claude Code skill，让 Agent 知道如何使用它——该 skill 内嵌于二进制文件中，因此可离线安装：

winwright skills install --scope user      # -> %USERPROFILE%\.claude\skills\winwright\
winwright skills install --scope project   # -> <cwd>\.claude\skills\winwright\

使用场景

每张卡片都链接到一份详细指南，其中包含真实提示词、工具调用参数 和示例输出。可在 docs/use-cases/ 浏览所有指南。

用于 CI 的脚本化 UI 测试自动化

只需录制一次 AI 会话——Agent 探索 UI、执行操作并嵌入断言—— 然后导出可移植的 JSON 脚本，在 CI 中无需 AI Agent 即可重放。描述你的应用， 或粘贴现有的手动测试套件；Agent 会自动编写脚本。

自主桌面自动化

让 AI Agent 访问你的桌面。它可以启动应用、在应用间传输数据、 填写表单，并截取屏幕截图以供验证——无需编写或维护脚本。

旧版应用数据提取

许多企业应用没有 API。只要 Windows UI Automation 能识别控件， WinWright 就能读取其值。从从未为集成而构建的应用中提取数据。

重复任务的脚本化桌面自动化

只需录制一次重复的日常工作流。导出为 RPA 脚本，按需重放—— 录制完成后无需 AI Agent。适用于导出报告、导入数据 以及任何每次执行方式都相同的多步骤任务。

AI 驱动的 UI 测试

AI Agent 会探索你的 WinForms 或 WPF 应用，查找元素并断言状态。 无需维护脆弱的 XPath 选择器——UI 发生变化时，Agent 会自动适应。

批量数据验证

自动驱动应用处理 50 条以上记录。将每条显示的值与 参考表进行比较，并获取包含差异详情的结构化通过/失败报告。

跨应用工作流

自动化跨桌面应用和浏览器的工作流——从会计应用读取数据， 提交到 Web 门户，并截取确认信息的屏幕截图。

应用健康监控

验证正在运行的应用是否正常运行且响应正常——进程正在运行、连接状态显示 “Connected”、服务运行正常。配合 Windows Task Scheduler 执行定时检查。

远程管理

通过 HTTP 管理远程计算机上的进程、服务、注册表和计划任务。 五层安全防护：IP 允许列表、Windows Negotiate 身份验证、AD 组授权、 速率限制和按用户设置的会话数限制。

无障碍审计

遍历完整的 UIA 元素树。检查控件是否有名称、按钮是否有标签， 以及是否存在键盘操作路径。AI Agent 会生成合规报告。

对话框和模态窗口处理

在每次点击后检测意外的确认对话框、文件保存提示和 Win32 MessageBox 弹窗。 处理或关闭它们，且不会中断自动化流程。

工具

52 个整合工具，分为四个类别，另有一层贯穿各类的安全层 （通过 action/mode 参数将 110 多个工具合并而成）：

类别	工具数	功能
桌面自动化	33	启动/附加到/关闭应用、点击、输入、读取值、截图、树形导航和查询、等待、网格（ww_grid）、对话框（ww_dialog）、窗口（ww_window）、剪贴板、会话句柄（UIA3）
系统	8	进程、注册表、环境变量、文件系统、网络、服务、计划任务、计算机控制
AI Agent	7	语义快照和状态差异比较（ww_snapshot）、元素检查（ww_inspect）、事件监视、测试用例录制、选择器修复（ww_heal_script）、用于发现工具的 ww_get_schema
浏览器	4	通过 CDP 操作 Chrome/Edge——会话、页面、元素、高级功能（eval/表单/对话框）。无需依赖 Selenium
安全	—	贯穿各类：运行时权限控制，支持 AD 组覆盖设置；JSONL 审计日志

每个工具都通过 action 参数支持多种操作（例如，ww_service(action="list")、ww_snapshot(action="get")），在保留完整功能的同时减少工具总数。随时通过 winwright tools 查看当前可用工具。

配置

在二进制文件旁边（或 %APPDATA%\WinWright\winwright.json）创建 winwright.json。 所有设置都位于顶层的 WinWright 节下：

{
  "WinWright": {
    "Permissions": {
      "AllowShell": false,
      "AllowProcessKill": false,
      "AllowRegistryWrite": false,
      "AllowFileWrite": false,
      "AllowServiceControl": false,
      "AllowTaskScheduler": false,
      "AllowPower": false,
      "AllowLockScreen": false,
      "AllowMachineEnv": false,
      "AllowBrowserEval": false,
      "AllowNetworkProbe": true,
      "AllowFileRead": true
    },
    "Audit": {
      "Enabled": true,
      "RetentionDays": 30
    }
  }
}

默认情况下，所有破坏性操作均处于禁用状态——只启用所需功能。 AllowNetworkProbe（ping/DNS）和 AllowFileRead（ww_file 读取/列出）是仅有的默认值为 true 的权限；两者均为只读权限。通过 HTTP 向远程客户端提供服务时，建议将其设为 false。受权限控制的调用会记录到按日轮换的 audit-YYYY-MM-DD.jsonl 文件中。

CLI

winwright mcp                                    Start MCP server (stdio)
winwright serve --port N                         Start MCP server (HTTP, default 8765)
winwright tools [--json|<name>]                  List the tool surface (CLI discovery; no MCP client needed)
winwright call <tool> [--param value …]          Invoke one tool via the local daemon (CLI automation)
winwright daemon <start|stop|status>             Control the background host that owns CLI sessions
winwright skills <install|list|uninstall>        Install the bundled Claude Code skill (offline)
winwright run <script.json> [--format text|junit] [--output <file>] [--screenshots [--screenshots-dir <dir>]]
                                                 Replay a recorded automation script
winwright heal <script.json> [--output <file>] [--min-confidence <0-1>]
                                                 Probe broken selectors against a live UI and repair them
                                                 (launches/attaches using the script's own metadata)
winwright inspect <pid>                          Dump UIA element tree for a process
winwright doctor                                 Verify environment prerequisites

要求

• Windows 10 或 11（x64 或 ARM64）
• 下载二进制文件无需安装 .NET 运行时——它是独立运行的

适用对象

适合：

• 测试 WinForms、WPF 或 Win32 应用，并希望借助 AI 创建测试的 QA 工程师
• 构建需要与 Windows 桌面交互的 AI Agent 的开发者
• 从没有 API 的旧版企业应用中提取数据的团队
• 任何希望在 Windows 上自动化重复的多应用工作流的人

不适合：

• Linux 或 macOS 自动化——WinWright 仅适用于 Windows（UIA 是 Windows API）
• 仅限 Web 的测试——请改用 Playwright；WinWright 的浏览器工具适用于桌面与浏览器混合工作流
• 高吞吐量数据管道——UIA 一次只读取一个控件；如果需要批量传输数据，使用合适的 API 或数据库连接会更好

对比

	WinWright	UiPath	Power Automate Desktop	Playwright
自动化对象	桌面 + 浏览器 + 系统	桌面 + 浏览器 + 系统	桌面 + 浏览器 + 云	仅浏览器
使用方式	通过 MCP 使用 AI Agent（自然语言）	可视化工作流设计器	可视化工作流设计器	代码（JS/Python/C#）
桌面支持	WPF、WinForms、Win32（UIA3）	WPF、WinForms、Win32、Java、SAP	WPF、WinForms、Win32	无
浏览器支持	通过 CDP 支持 Chrome/Edge	Chrome、Edge、Firefox	Chrome、Edge、Firefox	Chrome、Edge、Firefox、Safari
选择器模型	AI 按名称/类型选择元素	可视化选择器录制器	可视化选择器录制器	CSS/XPath 选择器
成本	免费	需付费许可（按用户/机器人计费）	免费（桌面版），云端版需付费许可	免费
设置	单个二进制文件，无需运行时	完整安装 + Studio	Windows 应用商店应用	npm install
设计用途	AI Agent 和 MCP 客户端	企业 RPA	商业用户自动化	开发者测试

WinWright 不是 RPA 平台，而是一个让 AI Agent 能够访问 Windows 的工具服务。 如果你需要可视化工作流构建器或企业级编排，UiPath 或 Power Automate 是更好的选择。如果你只需要浏览器测试，Playwright 则更成熟。

当其他工具无法满足需求时，WinWright 就能派上用场——例如 AI Agent 需要查看并操作 Windows 桌面，或是你需要在一个 MCP 会话中同时使用桌面和浏览器。

支持

帮助本项目持续发展！

如果 WinWright 为你的开发工作流带来了帮助，不妨支持它的持续开发。你的捐助将用于：

• 持续维护和修复错误
• 开发新功能
• 支付基础设施费用

所有捐款的 50% 将直接捐给帮助有需要者的儿童慈善机构。 其余资金将用于项目维护和功能升级。

无论捐助多少，每一份支持都能带来改变。

• 问题： GitHub Issues
• 更新日志： GitHub Releases

许可证

可免费用于任何用途——个人、学术或商业用途。 完整条款请参阅 LICENSE。重新分发时必须注明出处。

---

以信任为基石，以价值为驱动 — Civyk