# win-pilot [English](./README.md) | 中文 ![License](https://img.shields.io/badge/license-MIT-blue) ![Platform](https://img.shields.io/badge/platform-Windows-0078D4) ![Node](https://img.shields.io/badge/node-%3E%3D22.12-339933) 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： ```text 请按照 https://raw.githubusercontent.com/JeremyWangCY/win-pilot/main/AGENT_INSTALL.md 安装并验证 Win-Pilot。 ``` Agent 会优先安装完整插件；只有宿主不支持插件时，才回退到 MCP 或 CLI。 ### 手动安装支持插件的宿主可以安装 `JeremyWangCY/win-pilot`。插件包已经包含 `.mcp.json` 和 `skills/win-pilot`。其他宿主使用： ```powershell npm install -g win-pilot@latest win-pilot doctor --probe ``` 再通过宿主的插件/工具设置注册本地 MCP Server： ```json { "mcpServers": { "win-pilot": { "command": "win-pilot", "args": ["mcp"] } } } ``` 已知宿主提供便捷安装器，其他 Agent 仍可使用通用模式： ```powershell 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 ``` 验证： ```powershell win-pilot --version win-pilot status --json win-pilot doctor --probe --json ``` 本版预期版本为 `0.6.1`、平台为 `win32`，doctor 的必要检查全部为 `ok`。doctor 检查安装条件；独立任务会话是否可用仍需实际连接验证。 ### 更新先结束正在进行的界面任务，再更新 runtime，并重启或重新加载宿主的插件/MCP 进程： ```powershell 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 接口： ```powershell 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 是完整参数和默认值的权威定义。 ## 设置在 DeepSeek Harness **0.2.0-rc.2 或更新版本**中，打开「设置 → Win-Pilot」或插件详情页。当前宿主直接投射插件的 `Config`。显示偏好实时生效；电脑操作环境从下一次电脑操作起生效，同一聊天也会切换。 | 偏好 | 默认值 | 作用 | |---|---|---| | `overlay` | `true` | 显示操作光标 | | `statusPill` | `true` | 显示运行状态提示 | | `browserHeadlessDefault` | `false` | 浏览器在后台运行，不显示窗口 | | `ignoreUserInput` | `false` | 你操作键鼠时继续执行，不停下来重新观察 | | `desktopEnvironment` | `current` | 电脑动作的执行位置：当前桌面或独立任务窗口 | | `remoteControlPolicy` | `fallback` | 远程控制接入时：改在当前桌面执行，或停止并提示 | `desktopEnvironment` 默认 `current`（当前桌面），可选 `task`（独立任务窗口）。保存后从下一次电脑操作起切换，同一聊天也生效。切换前先取消并清理旧控制会话，释放旧浏览器控制权，再要求重新列出窗口或截取桌面后才能输入；旧目标不可沿用，清理失败则停止切换。关闭时，模型工具定义、运行时技能和诊断不宣传独立桌面选项。开启后，电脑动作、观察、剪贴板和恢复都使用同一任务桌面；连接失败不会转到主桌面。浏览器动作只能使用同一任务启动的浏览器。小窗采用浅色、无原生标题栏的样式，默认432×300，用彩色圆点显示状态，工具栏只留放大收回、置顶和关闭。放大后直接点击、拖动或输入即可接管；AI 停止输入确认后才交付第一个手势。空闲10秒后交还 AI，按住鼠标或按键期间不会自动交还。缩小后为只读预览；右键工具栏可打开本机登录设置。首次完成 Windows 功能准备与本机登录，可选择通过当前用户 DPAPI 和凭据管理器记住登录，密码只在本机窗口输入。需要 .NET 8 Windows Desktop Runtime 及可用的 Windows 子会话功能；更换 Windows 用户、密码或系统策略后可能需要重新设置。独立桌面不会出现在远程画面里：远程控制接入时不会打开；打开后才有人接入，动作会改在当前桌面执行，选 `remoteControlPolicy: refuse` 则直接停止。UU（网易 GameViewer）按流量判断是否有人接入，空闲的 UU 不会阻止独立桌面，独立桌面内自启的 UU 托盘会被关闭。关闭独立桌面时，若远程控制软件在注销期间改动了主桌面的显示缩放，会自动恢复。设置页是一屏放得下的紧凑面板：三个开关和两个图标分段控件，已改动的项可单独恢复默认。底部左侧显示运行版本，右侧是未保存数量、放弃和保存；Ctrl+S 保存，Esc 放弃。安装新的托管版本后，可安全等待当前操作完成并释放控制，再重新加载；旧运行版本或原地更新可能仍需重启 DeepSeek Harness。行为和验证限制见[独立任务桌面](./docs/task-desktop.md)。查看原生窗口：`win-pilot desktop --preview`。预览不能连接会话或执行电脑动作。正常连接入口为 `win-pilot desktop`，受启动拦截约束。源码构建使用 `npm run build:desktop`，无会话测试使用 `npm run test:desktop`。数值限制和输入策略采用内部默认值，旧设置不再改变它们；必需的 Windows/Meta 系统按键能力始终开启。后台输入、锁屏检查、用户输入中断、焦点让路和窗口文字读取遵循本项目自己的[桌面控制契约](docs/desktop-control-contract.md)。没有宿主的 CLI/MCP 安装使用内置默认值。 ## 工作原理 ```text 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` | | `computer use provider ... already registered` | DSH 已启用另一个 Computer Use Provider | 只保留一个桌面 Provider | 当前兼容构建的诊断文件仍位于 `%TEMP%\win-pilot-diag.log`。 ## 开发 ```powershell git clone https://github.com/JeremyWangCY/win-pilot.git cd win-pilot npm run build:wgc npm run build:desktop npm run test:desktop npm test npm pack --dry-run ``` 测试覆盖 CLI 公开协议、MCP 发现/调用、插件清单、安装计划，以及自有 Windows/浏览器 fixture。 ## 许可证 [MIT](./LICENSE)