Windows 桌面操控 JeremyWangCY/win-pilot

win-pilot

License Platform Node

Win-Pilot 是面向 Windows Computer Use 的 Agent Plugin。它通过同一个 computer 工具操作桌面应用和隔离 Chromium 会话，并让插件、MCP、CLI、Skill 与原生宿主 Adapter 共用完全一致的动作、恢复规则和返回结果。

功能

| 功能 | 具体行为 |
| Agent Plugin 包 | .codex-plugin/plugin.json 同时携带 MCP Server 与操作 Skill |
| Windows 原生操控 | UI Automation、Win32 输入/窗口管理和按窗口截图 |
| 后台优先 | 受支持的截图与输入路径尽量避免抢占焦点 |
| 隔离浏览器控制 | 启动 Edge 会话并使用与 CDP 页面绑定的目标和令牌 |
| 可恢复协议 | 统一 ok、outcome、error_code、动作后观察与未知结果处理 |
| 通用后备入口 | 支持工具的 Agent 使用 stdio MCP；仅支持 shell 的 Agent 使用 JSON CLI + Skill |
| Schema 可移植性 | 工具 Schema 持续验证 OpenAI 与 Gemini 系列消费者 |

环境要求

- Windows 10/11 x64
- Node.js 22.12 或更高版本
- Windows PowerShell 5.1
- 可选 .NET 8 Runtime，用于 WGC 截图
- 支持 Agent Plugin、stdio MCP 或 shell 的 Agent

快速开始

让 Agent 安装（推荐）

把下面这句话发送给 Windows 机器上的 Agent：

请按照 https://raw.githubusercontent.com/JeremyWangCY/win-pilot/main/AGENT_INSTALL.md 安装并验证 Win-Pilot。

Agent 会优先安装完整插件；只有宿主不支持插件时，才回退到 MCP 或 CLI。

手动安装

支持插件的宿主可以安装 JeremyWangCY/win-pilot。插件包已经包含 .mcp.json 和 skills/win-pilot。

其他宿主使用：

npm install -g win-pilot@latest
win-pilot doctor --probe

再通过宿主的插件/工具设置注册本地 MCP Server：

{
"mcpServers": {
"win-pilot": { "command": "win-pilot", "args": ["mcp"] }
}
}

已知宿主提供便捷安装器，其他 Agent 仍可使用通用模式：

win-pilot install --agent codex
win-pilot install --agent claude
win-pilot install --agent qoder
win-pilot install --agent pi
win-pilot install --agent dsh
win-pilot install --agent mcp
win-pilot install --agent cli

验证：

win-pilot --version
win-pilot status --json
win-pilot doctor --probe --json

预期版本为 0.1.1、平台为 win32，doctor 的必要检查全部为 ok。

更新

先结束正在进行的界面任务，再更新 runtime，并重启或重新加载宿主的插件/MCP 进程：

npm install -g win-pilot@latest
win-pilot doctor --probe

DSH profile 需要单独重启。需要刷新 Win-Pilot 管理的 Skill 副本时重新运行 win-pilot install；用户自行维护的自定义 Skill 不会在后台更新。

沙箱 Agent

如果沙箱会在每条命令结束后回收子进程，应由宿主的常驻插件或 MCP supervisor 启动 win-pilot mcp，不要从一次性命令中强行脱离进程。仅支持 shell 的 Agent 可以调用一次性的 win-pilot request。

使用方法

插件和 MCP 宿主会获得 computer 工具。仅支持 shell 的宿主使用相同的 JSON 接口：

win-pilot request --payload '{"action":"list_apps"}' --json
win-pilot request --payload '{"action":"get_window_state","hwnd":12345,"include_text":true}' --json
win-pilot request --payload '{"action":"click","hwnd":12345,"element_index":7,"snapshot_id":""}' --json

| 类别 | 动作 | 主要输入 |
| 发现 | list_apps、list_windows、get_app_identity | app、hwnd |
| 观察 | get_window_state、get_window、screenshot | include_text、include_screenshot |
| 指针 | click、double_click、mouse_move、drag、scroll | x、y、element_index、snapshot_id |
| 键盘 | type_text、press_key、hold_key、set_value | text、key、keys、duration_ms |
| 窗口 | launch_app、activate_window、minimize_window、close_window | name、hwnd、foreground |
| 浏览器 | browser_state、browser_observe、browser_open、browser_click、browser_click_text、browser_click_point、browser_type、browser_replace、browser_key、browser_upload | browser、tab_id、browser_element、screenshot_id、url |
| 顺序执行 | wait、批量 actions | seconds、when、expect |

MCP tools/list 返回的实时 Schema 是完整参数和默认值的权威定义。

工作原理

Windows Agent
├─ Agent Plugin ─┐
├─ stdio MCP ────┼─> Win-Pilot runtime ─> PowerShell helper ─> UIA / Win32 / WGC
├─ CLI + Skill ──┤ └────────────> CDP provider ─────> 隔离 Edge └─ 原生 Adapter ─┘

Runtime 是深模块，负责动作语义和返回结果。Adapter 只注册和渲染接口，因此一次修复可以覆盖所有宿主。

安全与隐私

Win-Pilot 以当前 Windows 用户权限运行，不包含遥测，也不会上传截图。浏览器导航会按任务要求产生正常网络请求。安装插件不会绕过宿主审批、沙箱规则或任务授权。

故障排查

| 现象 | 常见原因 | 处理方法 |
| 找不到 computer | 会话启动后才安装插件/MCP | 重启 Agent 或重新加载 MCP Server |
| MCP 立即退出 | 从一次性沙箱命令启动 | 改由常驻宿主 supervisor 管理 |
| browser_endpoint required | 没有自有浏览器会话 | 先以 headless: true 启动 Edge |
| 令牌过期 | 目标状态变化或令牌到期 | 重新观察同一目标 |
| doctor 失败 | runtime 条件缺失 | 查看 win-pilot doctor --probe --json |

当前兼容构建的诊断文件仍位于 %TEMP%\win-pilot-diag.log。

开发

git clone https://github.com/JeremyWangCY/win-pilot.git
cd win-pilot
npm test
npm pack --dry-run

测试覆盖 CLI 公开协议、MCP 发现/调用、插件清单、安装计划，以及自有 Windows/浏览器 fixture。

许可证

MIT