前言¶
在构建 Windows 端的智能体时，开发者常面临桌面应用与浏览器控制不一致的问题。现有方案往往缺乏统一的恢复协议与结果定义。win-pilot 作为一个 Agent 中立插件，为 Windows 计算机使用场景提供了统一的 computer 工具，覆盖桌面应用与隔离的 Chromium 会话。
这是什么¶
win-pilot 是一个 Agent Plugin 包，旨在为 Windows 代理提供一致的操作接口。它支持 MCP（模型上下文协议）、CLI、Skills 和原生主机适配器，确保跨插件、CLI 和原生集成的行为一致性。该插件由 JeremyWangCY 维护，采用 MIT 许可证。
核心功能¶
插件提供了以下核心能力：
- Agent Plugin package：将 MCP 服务器和操作系统技能打包在
.codex-plugin/plugin.json中。 - Native Windows control：通过 UI Automation、Win32 输入/窗口管理和窗口范围截图进行原生控制。
- Background-first actions：支持后台捕获和输入路径，避免不必要的窗口抢夺焦点。
- Isolated browser control：启动 Edge 会话并通过 CDP（Chrome DevTools Protocol）绑定目标进行控制。
- Recoverable protocol：使用稳定的
ok、outcome、error_code和后操作观察结果，支持未知结果处理。 - Universal fallbacks：为工具感知型代理提供本地 stdio MCP，为 Shell 能力型代理提供 JSON CLI 和 Skill。
- Schema portability：工具架构经过验证，适用于 OpenAI 和 Gemini 家族消费者。
- DSH provider lifecycle：要求 DSH 0.2.0-rc.2+ 以支持 Config 表单，并占用专用的
computerUse提供者槽位。
安装与启用¶
安装前请确保满足系统要求：Windows 10/11 x64、Node.js 22.12 或更新版本、Windows PowerShell 5.1。
安装过程如下：
1、通过 npm 全局安装最新版本：
npm install -g win-pilot@latest
2、安装完成后，运行诊断命令验证环境：
win-pilot doctor --probe
安装插件不会绕过主机批准、沙盒规则或任务授权。
典型用法¶
对于非插件主机的 Shell Agent，可以使用 JSON CLI 接口进行操作。
1、列出系统应用：
win-pilot request --payload '{"action":"list_apps"}' --
2、获取指定窗口的状态，包含文本内容：
win-pilot request --payload '{"action":"get_window_state","hwnd":12345,"include_text":true}' --
3、执行点击操作，通过快照 ID 和元素索引定位：
win-pilot request --payload '{"action":"click","hwnd":12345,"element_index":7,"snapshot_id":"<snapshot>"}' --
适用场景与注意¶
- 权限与隐私：插件以当前 Windows 用户的权限运行。它不包含遥测功能，不会上传截图。浏览器导航仅对请求的站点发起普通网络请求。
- 沙盒限制：在沙盒环境中使用时，需在持久化的插件或 MCP 监督器中配置
win-pilot mcp，切勿将进程从临时命令中分离。 - DSH 配置：安装插件后，DSH 配置文件必须单独重启才能生效。
总结¶
win-pilot 提供了一套标准化的 Windows 计算机使用协议，解决了 Agent 在桌面与浏览器控制上的割裂问题。通过统一的 MCP 接口和可恢复协议，它降低了开发者在不同 Agent 主机间迁移的门槛。
