win-pilot

dsh plugin --profile web add win-pilot

<p align="center">

<img src="./docs/images/social-preview.png" alt="Win-Pilot — 面向 DeepSeek Harness 的 Windows 电脑操控" width="820">

</p>

win-pilot

[English](./README.md) | 中文

Win-Pilot 提供 Windows 电脑操控，优先适配 DeepSeek Harness。computer 工具可操作当前桌面，或由用户在设置中开启独立任务桌面，通过紧凑窗口查看、暂停和接管。插件、MCP、CLI 与原生接入共用同一运行时。

功能

功能 · 具体行为

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 系列消费者

DSH Provider 生命周期 · 配置表单要求 DSH 0.2.0-rc.2+；占用唯一的 computerUse Provider 槽位

可选独立任务桌面 · Windows 子会话，默认432×300无标题栏小窗，展开后自动接管与空闲交还

环境要求

• Windows 10/11 x64
• Node.js 22.12 或更高版本
• Windows PowerShell 5.1
• 可选 .NET 8 Runtime，用于 WGC 截图
• 独立任务桌面需要 .NET 8 Windows Desktop Runtime
• 支持 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.6.1、平台为 win32，doctor 的必要检查全部为 ok。doctor 检查安装条件；独立任务会话是否可用仍需实际连接验证。

更新

先结束正在进行的界面任务，再更新 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。

使用方法

0.6.1 把顶部状态窗改成步骤记录：列出最近 5 步操作，标出进行中、完成或失败及耗时；旧步骤逐渐变淡而不是立刻清空，两次操作之间保留 20 秒，模型思考时不再闪退。输入的文字和剪贴板内容不会显示。多个会话同时存在时，控制按钮跟随仍在操作的那个。新增设置 ignoreUserInput（默认关闭），开启后你使用键鼠时 Win-Pilot 不会因此暂停。

0.6.0 把设置页重做为一屏放得下的紧凑面板，并换上新的产品图标。辅助进程启动更快：WGC 组件未变化时不再重复复制，大尺寸截图回包的分帧改为线性耗时。独立任务桌面方面：前台坐标点击会校验 expected_name，截图会清除 observation_required；空闲的 UU（网易 GameViewer）不再阻止独立桌面，有人通过 UU 接入时仍会拦截；关闭独立桌面时，若远程控制软件在注销期间改动了主桌面的显示缩放，会自动恢复。

0.5.0 让独立任务桌面采用与主显示器相同的像素尺寸与缩放比例，并在检测到远程控制接入时拒绝打开：默认改在当前桌面执行，选择 remoteControlPolicy: refuse 则直接停止。本版同时合入贡献者的修复——技能提供者返回 thenable、控制类动作结果保持无损 JSON；并停止用 fs.cpSync 复制随包文件，该调用在非 ASCII 安装路径（如 C:\Users\<中文名>\.dsh）下会直接终止宿主进程。

0.4.0 让 DSH 原生工具及其启动的 CLI、MCP 共享当前设置，其他宿主保持独立。顶部提示条汇总多个运行来源，提供暂停、继续和结束控制；独立桌面的准备、登录等待状态持续可见。设置页区分已安装与正在运行的版本，并在支持时提供安全重新加载。

win-pilot session 从标准输入接收逐行 JSON，并为每个请求输出一行响应，保留请求的 id。观察和输入之间保持标准输入打开，使快照和浏览器控制权留在同一运行会话。发送 {"id":"done","action":"session_close"} 或关闭标准输入可取消待执行操作并释放控制。单次 request 命令仍各自结束运行会话。

0.3.1 支持在同一聊天内切换电脑操作环境，并让 CLI 观察动作和长动作持续显示运行提示条。切换后先重新观察，再执行输入。

0.3.0 新增会话级 stop / resume、正在执行及排队请求的取消，以及每用户的原子控制锁。停止后仍可观察。桌面元素使用稳定的稀疏编号，无障碍树输出 full / delta / no_change；隐藏观察不推进模型可见基线。富文本 paste 支持 format: text | html | md，恢复受支持的原剪贴板格式，并保留用户并发复制的新内容。Markdown 仅支持部分语法。

浏览器新增 browser_frames、browser_filechooser、browser_claim_tab 和 browser_finalize。同源子框架使用 frame_id 及语义引用；跨域框架和 OOPIF 明确拒绝。标签认领绑定当前控制会话，修改时传回 claim_id，完成后交付释放控制，不主动切换标签。先开启文件选择器监听，再打开选择器、读取事件，随后在 60 秒内将单次 filechooser_id 及明确的绝对文件路径传给 browser_upload。当前仍使用显式本机 CDP 连接，尚未提供用户浏览器扩展。

原生取消在系统调用之间检查；阻塞的系统/UIA 调用可能需要限时结束子进程，并返回结果不确定，此时应先观察。剪贴板恢复无法提供操作系统级的原子比较交换保证。

插件和 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 是完整参数和默认值的权威定义。

设置

在 DeepSeek Harness 0.2.0-rc.2 或更新版本中，打开「设置 → Win-Pilot」或插件详情页。当前宿主直接投射插件的 Config。显示偏好实时生效；电脑操作环境从下一次电脑操作起生效，同一聊天也会切换。

偏好 · 默认值 · 作用

overlay · true · 显示操作光标

statusPill · true · 显示运行状态提示

browserHeadlessDefault · false · 浏览器在后台运行，不显示窗口

ignoreUserInput · false · 你操作键鼠时继续执行，不停下来重新观察

desktopEnvironment · current · 电脑动作的执行位置：当前桌面或独立任务窗口

remoteControlPolicy · fallback · 远程控制接入时：改在当前桌

…(truncated)