Skip to content
dsh marketplace

win-pilot

Verified

win-pilot · v0.1.1 · MIT

Agent-neutral Windows and Chromium computer-use runtime for Codex, Claude Code, Qoder, Pi, and DeepSeek Harness.

Install

dsh plugin add win-pilot

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

win-pilot

English | 中文

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":"<snapshot>"}' --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