前言¶
在構建 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 主機間遷移的門檻。
