NexusWindows for Claude

Claude 版 NexusWindows

面向 Claude 的后台 Windows 计算机操控。 MCP 服务（nexus-windows-claude）让 Claude Desktop 和 Claude Code 能够查看并操控 Windows 桌面应用，同时用户仍可使用鼠标和键盘，并继续使用前台窗口。

版本 3.7.0 · Windows 10/11 · Python 3.14 · MIT 许可证

Nexus 系列的一部分：NexusWindows （Claude · Codex · Antigravity）、 NexusBrowser（仓库）、 NexusAndroid（仓库）。 项目页面：julienpiron.fr/nexuswindows。

为什么

Anthropic 自带的计算机操控功能（在 Cowork 和 Claude Desktop 中的 Claude Code 里）目前处于测试阶段，仅面向 Pro 和 Max 订阅用户：“Team 和 Enterprise 方案目前无法使用计算机操控功能” （Claude 帮助中心）。 Claude 版 NexusWindows 是本地 MCP 服务，因此只要方案支持本地 MCP 服务，就能与 Claude Desktop 和 Claude Code 搭配使用，包括 Team 和 Enterprise 方案。

通过截图和点击来操控计算机会移动真实光标并将窗口置于前台，因此 Agent 操作时，电脑前的人必须停止工作。大多数 Windows 应用都能以其他方式操控：原生控件可接收窗口消息，现代框架会公开 UI Automation，而 Chromium 则可通过其辅助功能树进行访问。 本服务会针对每类 UI 选择一种经过实测、不会窃取焦点的技术，读取操作结果，并且只有在用户明确允许时才会退回到真实鼠标或键盘操作。

NexusWindows 系列

三个 MCP 服务，每个 Agent 一个。由于每个模型所需的工具形态各不相同，因此分别构建，但承诺一致：用户可以继续使用鼠标、键盘和前台窗口，且每项操作都会回读。

	Claude	Codex	Antigravity
安装	uvx --python 3.14 nexus-windows-claude	npx -y nexus-windows-codex	uvx --python 3.14 nexus-windows-antigravity
软件包	PyPI	npm	PyPI
工具	windows look act launch window，以及 notifications 和 logs	windows look act launch window	windows look act launch window
仓库	NexusWindows-Claude	NexusWindows-Codex	NexusWindows-Antigravity

每个步骤都会报告 ✓ 已验证、= 已完成、~ 未知（从未重放）或 ✗ 失败或拒绝。三者共用防护策略、前台令牌、紧急停止快捷键（Ctrl+Alt+Shift+Esc）、通用日志格式和通用基准测试。

安装

适用于 Windows 10 或 11。无需安装 Python：uv 会自行下载 Python 3.14。

一步安装（若缺少 uv 则安装；下载并检查服务；将其注册到 Claude Code，并在 Claude Desktop 的配置中声明；合并前会备份；保留你自己的条目；启用 Claude Code 插件后不会添加第二个服务）：打开 Windows PowerShell（在“开始”菜单中输入 powershell）并粘贴：

irm https://raw.githubusercontent.com/pironjulien/NexusWindows-Claude/main/setup.ps1 | iex

然后完全关闭 Claude，再重新打开。setup.ps1 脚本很短，可以先阅读；再次运行时只会执行缺少的操作。

Claude Code 插件（相同的服务，另附一个技能；需要 uv）：

/plugin marketplace add pironjulien/nexus-plugins
/plugin install nexus-windows@nexus-plugins

Claude Desktop 扩展（需要 uv）：从最新版本下载 nexus-windows-claude-<version>.mcpb，然后在 Claude Desktop 中打开“设置” → “扩展”，将文件拖放到那里（或选择“高级设置” → “安装扩展”），再点击“安装”。对于 Microsoft Store 版本的 Claude Desktop，双击文件不会打开：Windows 没有可处理 .mcpb 的应用。

**手动安装。**安装 uv（官方软件包）：

winget install --id=astral-sh.uv -e

然后重启 Claude，让它识别 uv，并从 PyPI 注册服务。 Claude Code：

claude mcp add --scope user -e PYTHONUTF8=1 --transport stdio nexus-windows -- uvx --python 3.14 nexus-windows-claude

Claude Desktop：打开“设置” → “开发者” → “编辑配置”，将以下内容添加到 claude_desktop_config.json（如果已有 mcpServers，则添加到其中），保存，然后完全退出 Claude 并重新打开：

{
  "mcpServers": {
    "nexus-windows": {
      "command": "uvx",
      "args": ["--python", "3.14", "nexus-windows-claude"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

首次启动会下载约 100 MB 的内容（Python 3.14 和服务的依赖项）；之后启动耗时不到一秒。3.0.0 之前的软件包名为 nexus-windows；该名称仍然有效，会安装 nexus-windows-claude。

从克隆版本安装（开发）：

git clone https://github.com/pironjulien/NexusWindows-Claude.git
cd NexusWindows-Claude
$env:UV_PROJECT_ENVIRONMENT = "$env:LOCALAPPDATA\claude-windows-computer-use\venv"   # optional: venv outside the clone
uv sync --frozen

将其注册到 Claude Code（用户范围）：

claude mcp add --scope user `
  -e "UV_PROJECT_ENVIRONMENT=$env:LOCALAPPDATA\claude-windows-computer-use\venv" -e PYTHONUTF8=1 `
  --transport stdio nexus-windows '--' uv run --project "$PWD" --frozen python -m nexus_windows

从克隆版本安装到 Claude Desktop：

{
  "mcpServers": {
    "nexus-windows": {
      "command": "uv",
      "args": ["run", "--project", "C:/path/to/NexusWindows-Claude", "--frozen", "python", "-m", "nexus_windows"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

本地状态（日志、例程）保存在 %USERPROFILE%\.claude\nexus-claude\；设置 NEXUS_WINDOWS_HOME 可改用其他文件夹。

工具

工具	用途
windows(filter)	按从前到后的顺序列出应用窗口：hwnd、标题、进程、UI 系列、大小；[hidden] 表示在后台启动的 Store 应用（从不显示，但仍可操作）；然后是任务栏和桌面
look(window, show, query, region, detail, marks)	列出带编号的 [N] 元素（角色、名称、值、状态、位置），不将窗口置于前台；优先显示文本：只有当元素树过于稀疏，或在未经验证的步骤之后，才显示图像（show="both" 始终附带图像）；还可指定 window="taskbar"、"desktop" 和 "screen"（整个屏幕及各窗口的位置）
act(steps, window, then, foreground, remember, routine, params)	一次调用执行多个步骤，每步都会读取结果，然后返回更新后的状态；foreground=true 时可操作 Windows 面板 "quick settings"、"notifications"、"start"
launch(app, args, devtools, restart)	启动应用（开始菜单名称、Store 应用、可执行文件）、文件夹、文档或地址（ms-settings:<page>、mailto:、https:），不将其置于焦点；会验证是否已打开
window(action, ...)	还原到后台、最小化、最大化、关闭、移动、调整大小
notifications(limit, app)	从 Windows 通知数据库读取通知（只读），不会在屏幕上打开任何内容；安全码会被遮盖
logs(count, errors_only)	调试日志：尝试过的技术、耗时、错误、服务状态

步骤操作：click、double_click、right_click、type、set、clear、key、select、check、uncheck、 toggle、expand、collapse、scroll、focus、menu、wait、drag、hover。目标可以是上次 look 返回的 [N]、可见名称（"OK"）、带角色的名称（"button:OK"、"edit:Name"、"checkbox:Subscribe"），或上次图像中的 x,y 坐标。

windows、notifications 和 logs 除了返回相同的文本内容，还会返回结构化内容（MCP outputSchema 和 structuredContent： 窗口行、通知、日志记录），供读取数据而非散文的客户端使用。

用法

典型流程：look(window="Notepad")，然后用一次 act 执行所有步骤，最后读取每步报告。

act(window="Settings form", steps=[
  {"do": "set",   "target": "edit:Name", "text": "Ada",
   "check": {"target": "Name", "value": "Ada"}},
  {"do": "check", "target": "Subscribe"},
  {"do": "click", "target": "button:Save", "expect": "Saved"}
], remember="save-form")

稍后：act(window="Settings form", routine="save-form")。

功能说明

仅显示变更（then="changes"、show="changes"）

操作后，act(then="changes")（或 look(show="changes")）只返回该窗口上次显示的列表之后发生的变更：+ 表示新增，~ 表示变更（文本、状态或位置），- 表示移除；其他所有元素都保留其 [N]。大量元素因滚动而产生的常见变更会合并为一行，以范围形式列出这些元素（[2-21]），而不是返回完整列表。比较基于窗口自身的坐标系，因此移动窗口不算变更。已移除的 [N] 永不重新分配；如果某个元素的变更内容在长报告中被截断，该元素就会失去其 [N]，直到下一次 look。当几乎所有内容都发生变化（60 %）时，将返回完整列表。实测：点击后，报告比完整列表短 2 到 2.6 倍。

从图像中读取文本（OCR 回退）

当窗口几乎不提供 UI Automation 元素（少于 6 个：Tk、画布），或 Chromium 页面停止提供内容时，会使用 Windows 内置 OCR 引擎（Windows.Media.Ocr，本地运行、离线）读取窗口图像中的文本，并将其列为带位置的 [N] Text "…" (OCR)；可按编号或名称定位此类元素（在其位置点击，若窗口已移动则重新计算位置）。在实验室应用中的实测：每个窗口耗时 10 到 21 ms；文本准确率为 WPF 16/16、Edge 20/23、Tk 6/7。

每个步骤的四种结果

每个步骤都会报告以下结果之一：

• ✓ 已回读效果（值、状态、窗口、图像）。没有 expect 或 check 的点击或菜单选择，也仅凭被点击的元素本身即可证明：回读其自身状态（已选中、已展开、已选择），或应用在控件收到点击时发出的 UI Automation“Invoked”事件（WPF、Chromium、Electron；不包括 WinForms 或 Win32，其按钮始终为 ~）。“Invoked”表示点击已送达，不表示产生了什么结果：这由 expect 检查。控件已确认的点击绝不会再通过其他技术发送；
• = 步骤的 check 所请求的状态原本就为真，因此未发送任何内容；
• ~ 已发送输入，但无法回读其效果（绝不计为成功）；
• ✗ 失败、拒绝，或未满足后置条件；批次在此处停止。

批次结束时会列出四种结果的数量。

后置条件（check）

步骤可以包含 check：指定一个元素及其必须达到的状态（value、contains、checked、selected、expanded、focused、enabled、exists）。如果步骤执行前状态已经为真，则跳过该步骤（=）。执行后为真：✓。执行后为假：✗，并停止批次。元素未公开的状态始终为未知，绝不会视为假。

例程

只有当每个步骤的结果均为 ✓ 或 =，且每个目标都是可见名称（不能是 [N] 或坐标点）时，act(remember="name") 才会保存批次。{{x}} 表示变量文本，重放时会通过 params 填入。act(routine="name") 会按名称重新查找每个目标，并重新验证每个步骤；如果应用已更新，则会报告更新；如果重放失败，则会将该例程标记为待检查。例程按可执行文件存储在 %USERPROFILE%\.claude\nexus-claude\routines 下。可选的镜像文件夹（NEXUS_ROUTINES_MIRROR）可在多台 PC 之间共享定义；输入的文本绝不会以明文镜像（未使用 {{x}} 模板的例程文本会保留在本地）。

已验证的路径打开方式

launch(app=<folder or document>) 会通过文件关联打开路径（ShellExecuteEx，不请求激活），然后检查实际打开的内容：文件资源管理器中显示的文件夹（通过 Shell.Application 读取），或标题中包含文件名的窗口。脚本、快捷方式和安装程序会被拒绝。

按 UI 系列

• 原生 Win32：直接向控件发送消息（BN_CLICKED、带通知的 CB_SETCURSEL/LB_SETCURSEL、EM_REPLACESEL、菜单 WM_COMMAND、TCM_SETCURFOCUS），然后读回结果。避免使用 UI Automation，因为测得它会窃取焦点（按钮 Invoke），或静默失败（列表 Select）。
• Win32 和 WinForms 下拉列表：使用 CB_SHOWDROPDOWN 打开和关闭，使用 CB_GETDROPPEDSTATE 读回状态（在列表上执行 expand、collapse 或 click）。在打开的列表中选择项目时，先关闭列表（Windows 会将关闭视为取消，丢弃关闭前做出的选择），再向父窗口发送 CB_SETCURSEL、CBN_SELCHANGE 和 CBN_SELENDOK，并从应用中读回结果（索引和标签）；空值或其他值均为 ✗。列表打开时，不遍历其 UI Automation 树（它会链式遍历桌面上的每个顶层窗口）：选项从 ComboLBox 弹出列表本身读取。
• WinForms、WPF、UWP、WinUI：使用 UI Automation，并禁用 AutoSetFocus，同时设置有界超时。若选择操作后 WPF 下拉列表仍保持打开，则将其关闭并读回选择结果。
• Chromium 和 Electron（不激活窗口）：对于已打开且没有 DevTools 的应用，多行字段、富文本编辑器、<select>、按键和 Ctrl/Alt 快捷键都通过模拟激活处理：仅向该窗口发送 WM_NCACTIVATE 和 WM_ACTIVATE（Chromium 根据这些消息获取激活状态；Windows 不会更改前台窗口），使用 MSAA accSelect(SELFLAG_TAKEFOCUS) 设置 DOM 焦点并读回，字符通过 WM_CHAR 发送，停用消息则以投递方式发送，使其在这些操作之后处理。页面会收到可信的 keydown 和 input 事件。测得一个注意事项：刚启动的应用可能会短暂使用一次启动时的前台状态（约 10 ms，由守护逻辑交还），因此每个进程的首次模拟激活都按短暂激活处理。使用 launch(devtools=true) 启动的应用则通过 DevTools 协议驱动。
• Steam（SDL 窗口中的 CEF）：识别为 Chromium；launch(app="Steam") 会添加 Steam 自带的 -cef-disable-occlusion -cef-force-accessibility 开关，使 UI 在被遮挡时仍可读取。
• Tk：不使用 UI Automation；通过 OCR 回退机制查找文本。仅对 Tk 线程将鼠标按钮标记为按下状态（Tk 使用 GetKeyState 读取）；按键和快捷键会模拟焦点（仅向该窗口发送 WM_SETFOCUS，绝不发送 WM_ACTIVATE）；列表通过原生滚动条滚动；所有操作都会读回结果。被遮挡的 Tk 画布无法接收滚轮事件（Tk 会将其路由到事件发生位置可见的窗口）：对于完全被遮挡的 Tk 窗口，会在手势期间将其移至桌面范围之外（不激活窗口），将滚轮事件投递到该窗口中的同一控件，然后将窗口移回原位，并精确读回像素位置；部分可见、最大化或最小化的窗口绝不移动（拒绝操作）。
• 在无 DevTools 时滚动被遮挡的 Chromium 页面：当其他窗口位于上方时，Chromium 会丢弃滚轮事件；滚动区域也不提供 ScrollPattern。因此，会将该区域下一行隐藏内容滚动到视野内（UI Automation ScrollItem），并读回该行在区域内的偏移量。

捕获

使用 PrintWindow（10 到 26 ms，包括被遮挡的窗口）；仅在回退时使用 Windows.Graphics.Capture。图像遵循通用的 Nexus 图像规则：最长边不超过 2000 px，且不超过 2.56 MP，这样 Claude Code 和大模型都不会缩小图像（坐标保持精确）；优先使用不超过 500 KB 的无损 WebP，之后再使用有损压缩，直到图像不超过 500 KB，尺寸保持不变（2560×1440 屏幕会以 2000×1125 发送，无损时约为 110 KB）。若要读取小字，请使用 region 放大，而不是发送更大的图像。若某窗口（或缩放区域）的图像与上次发送的图像完全相同，则不会再次附加；回复会说明这一点，而 show="image" 始终会附加图像。坐标绑定到窗口：窗口移动时坐标会随之移动；窗口调整大小时则拒绝操作。

Agent 工作中

执行操作时（act、launch、window；读取操作除外），驱动窗口屏幕的右下角会有一个小徽标原地旋转，周围带有蓝色呼吸光晕，就像游戏加载画面。最后一次操作结束 1.6 s 后，徽标便会消失。该覆盖层始终置顶、无边框、可穿透点击、不会被激活、不显示在任务栏中，也不会出现在屏幕截图里（模型在 look 中看不到它）。设置 NEXUS_WINDOWS_INDICATOR=0 可将其关闭。

真实鼠标和键盘

仅限使用 act(foreground=true)，且须由用户批准。随后整个批次期间，窗口都会保持在前台；批次结束时，光标和前台状态会还给用户；批次期间用户的任何物理输入都会使其停止。

与其他 Agent 协同工作

该服务通过两种基于文件的轻量协议，与同一台 PC 上的其他桌面 Agent 协作（它与 Codex 层 NexusWindows for Codex 及 Antigravity 层配合使用）。任何 Agent 都可以实现这些协议。

前台令牌（%USERPROFILE%\.nexus\foreground.lock）：仅在真正持有鼠标或前台时获取（真实输入、短暂激活、将窗口置于前台），后台操作不会获取。持有该令牌意味着在偏移量 2^32 处对 1 个字节执行独占 LockFileEx，打开文件时允许共享读取、写入和删除；句柄关闭时（包括进程退出时），Windows 会释放锁，因此不会有残留令牌。持有者会在文件开头写入 {"owner", "pid", "since", "purpose"}，仅供诊断。等待者最多等待数秒（此处为 8 s），之后便不执行操作，并说明令牌由谁持有。如果前台保护程序发现另一个 Agent 正持有令牌，就会跟随该 Agent 的窗口，而不是重新夺回前台。

紧急停止（Ctrl+Alt+Shift+Esc，文件位于 %USERPROFILE%\.nexus\）：每个 Agent 都会尝试调用 RegisterHotKey(MOD_NOREPEAT)；其中一个会成功，其余每隔 3 s 重试。持有者每隔 3 s 向 stop.owner 写入一次心跳。按下快捷键时，它会将 stop 重写为 {"by", "pid", "at", "hold_s": 120, "nonce"}。每个 Agent 至少每隔 0.2 s 检查一次 stop，并在每次操作前检查：如果该文件版本较新且未满 120 s，就会在剩余时间内阻止所有桌面操作（读取仍然允许）。停止状态会以单调时钟锁存在内存中：删除文件或更改时钟都无法解除停止状态；再次按下快捷键会重新启动计时。

架构

flowchart LR
    Claude["Claude Code or Claude Desktop"] -->|"MCP stdio"| Server["server.py MCP tools"]
    Server --> Worker["COM worker thread with hard timeout"]
    Worker --> Snapshot["snapshot and capture"]
    Worker --> Actions["actions per UI family"]
    Actions --> Win32["Win32 messages"]
    Actions --> UIA["UI Automation"]
    Actions --> Chromium["Chromium simulated activation and DevTools"]
    Actions --> Real["real input only with foreground true"]
    Server --> Safety["policy, emergency stop, foreground guard"]
    Safety --> Shared["shared files in USERPROFILE nexus"]
    Real --> Shared

src/nexus_windows/
  reloader.py      stdio supervisor: restarts the server on new code and replays the client handshake
  server.py        MCP tools, dedicated COM thread, per-call log
  actions.py       executor facade, assembled from the act_*.py modules
  act_base.py      targets read back live, technique chains, outcomes, shared refusals
  act_win32.py     Win32 messages
  act_uia.py       UI Automation (WinForms, WPF, UWP/WinUI) and dispatch per family
  act_chromium.py  Chromium/Electron/CEF: verified click, DevTools, simulated activation, <select>
  act_pointer.py   points, message clicks, scrolling, drag, hover
  act_wait.py      text presence and waiting
  snapshot.py      window + popups, [N] elements, image, coordinates, changes since the last list
  ocr.py           Windows built-in OCR (Windows.Media.Ocr) for windows without UI Automation
  uia.py           UI Automation with a single cross-process cache request
  methods.py       Win32 message techniques
  cdp.py           minimal Chrome DevTools Protocol client
  capture.py       PrintWindow / Windows.Graphics.Capture
  foreground.py    foreground monitoring and restoration, brief activation
  agentlock.py     shared foreground token
  postcond.py      step postconditions (check)
  routines.py      verified routines per application
  physical.py      the user's physical input (Raw Input, no hook), told apart from injected input
  launch.py        background launch, DevTools, throwaway browser profiles
  steam.py         Steam switches, clean restart, DevTools port
  realinput.py     real mouse/keyboard (SendInput), only when authorised
  policy.py        where to act and what to launch (hard blocks of the shared policy, launch switches)
  act_confirm.py   confirmation of irreversible gestures (confirm: true), whatever key or click triggers them
  shared/          the guard-rail policy shared with NexusWindows for Antigravity (garde-fous.json)
  packages.py      resumes Store apps that Windows suspended in the background
  offwindows.py    outside Windows: the server starts and lists its tools, every desktop tool says Windows is required
  stop.py          shared emergency stop
  freshness.py     detects a server whose code changed on disk
  codeprint.py     code fingerprint and location of the shared policy (no dependencies)
  worker.py        COM thread with a hard timeout
  log.py           JSONL log, 14 days
lab/     test applications (Win32, WinForms, WPF, Tk, a web page for Electron/Edge)
bench/   technique benchmarks and raw results
tests/   unit tests (pytest) and end-to-end tests (pytest -m live)

测量数据

所有数据均来自 bench/RESULTS.md 和 bench/results/ 中的原始文件（在一台 PC 上于 2026 年 10 月测得；RESULTS.md 中的注释为法语）。

项目	结果
捕获，PrintWindow	10 到 26 ms，包括被遮挡的窗口
真实 MCP 服务，在实验室应用上执行 73 次操作（0.4.0 到 0.5.0）	69 次成功，5 次明确拒绝，0 次误报成功，0 次光标移动，从未触碰剪贴板；中位数 78 ms，p90 为 321 ms
输入 2,000 个字符，含 20 个换行符	Win32 38 ms，WinForms 66 ms，WPF 141 ms，启用 DevTools 的 Electron/Edge 为 82 到 108 ms
Chromium 模拟激活，18 步场景（0.7.0）	Electron 18/18，获取前台 1 次，耗时 9 ms（正确启动，首次）；Edge 18/18，未获取前台
同上，Electron 不带开关，隐藏运行	17/18；失败原因是页面每次按键都会重建 1,500 个元素，标记为 ✗
模拟激活时输入 700 个字符，分 6 行	0.85 到 1.1 s（Electron、Edge）；被遮挡时为 1.9 到 2 s
act 最终渲染（0.7.0 与 0.6.1 对比）	Win32 418 → 221 ms，Electron 341 → 205 ms（窗口稳定状态检测取代固定的 300 ms 等待）
打开下拉列表并选择其中一项（WinForms 和 WPF 表单，真实 MCP 服务）	8/8 个场景，每次应用都收到了选择结果；在打开的 WinForms 列表中执行 select 耗时 113 ms（之前耗时 22 s 且失败）；每隔 5 ms 采样时获取前台次数为 0，光标从未移动

跨 Agent 对等基准测试（2026 年 10 月 26 日）

三个 NexusWindows 版本（此版本、Codex 版和 Antigravity 版）对 Electron、WinForms 和 WPF 实验窗口执行了相同的 33 项任务，每项 3 轮。实验窗口置于 z 序底部，并被不透明遮罩覆盖；PC 前无人操作（用户一触碰鼠标或键盘，基准测试就会立即停止）。效果由应用程序判定（收到事件或读回的值），绝不依据工具的报告。原始结果：bench/results/2026-10-26_1045-parity.json（旁边附有法语摘要）。

	效果准确	未造成干扰	虚报成功	中位数	p95
nexus-windows for Claude 3.3.0	84/99	83/99	0	957 ms	5.6 s
NexusWindows for Codex	84/99	82/99	0	691 ms	3.8 s
NexusWindows for Antigravity	84/99	80/99	0	817 ms	3.4 s

三者之间的差距：0。所有三者的每项 Electron 任务均为 3/3。15 项失败在三者中完全相同，都是如实拒绝的后台限制，而非虚报成功：WPF 原始点击、WPF 中的 Ctrl+K、WPF 上下文菜单，以及 WinForms 和 WPF 中的双击（遮罩覆盖了目标点；WinForms 会忽略发送到被遮盖点的双击）。“干扰”指尝试期间前台被切换、光标移动或剪贴板被写入。

离线测试套件：请参阅 Tests 徽章（Windows 上的 test.ps1，以及 Linux 上的启动检查）。

与 Cua Driver 和 Windows-MCP 的并排对比（2026 年 10 月 26 日）

Cua Driver 0.38.0 是最接近的其他工具：它默认也在后台运行。Windows-MCP 0.8.8 是使用最广泛的 Windows MCP 服务；它没有后台模式。三者都通过各自实际的 MCP 服务（bench/cua_vs_nexus.py）进行操作，在同一批实验室 Windows 窗口上测试，窗口被不透明窗口遮挡，电脑旁无人；测试需在没有物理输入满 2 分钟后才能启动，并在首次检测到物理输入时停止。每种工具都按照其自身指南所述的方式供 Agent 使用（Cua：先在后台操作，然后点击，最后使用前台回退方案；Windows-MCP：通过 App switch 将窗口调到前台，然后在屏幕上操作）。效果以应用程序为准（收到事件或读回值），而非工具的报告。每毫秒采样一次前台窗口变化，并在每次尝试前后检查真实光标位置。共测试 51 项任务，涵盖 Win32、WinForms、WPF、Tk、Electron 和 Edge（bench/tally_cua.py，原始结果见 bench/results/2026-10-26_1210-cua-vs-nexus.json）。复现方法：在空闲的 Windows 电脑上运行 python bench/cua_vs_nexus.py，并按照脚本顶部的说明安装 Cua Driver 和 Windows-MCP。

全部 51 项任务，目标窗口被遮挡	nexus-windows 3.3.0	Cua Driver 0.38.0	Windows-MCP 0.8.8
后台操作成功产生效果	44	26（点击方式 +1，调到前台后 +6）	0（无后台模式；前台操作产生 10 次效果）
虚报成功（报告已完成，但应用未收到任何内容）	0	4	不可直接比较，见下文
滚动被遮挡的列表（Tk、Electron、Edge）	3/3	0/3	0/3
抢占前台	0	3	15（从未恢复）
移动真实光标	0	0	34
成功操作的中位耗时	598 ms	728 ms	1,478 ms

Windows-MCP 在 App switch 将窗口调到前台后，成功在全部 9 项 Win32 任务中产生效果。在 WinForms、WPF、Tk、Electron 和 Edge 窗口中，切换操作有 30 次未能将窗口调到前台，随后点击或输入落在了最上层窗口（本次测试中是遮挡窗口；实际使用中则是用户自己的窗口），但工具仍报告已点击：36 次回答“已完成”却未产生任何效果。这更能说明它缺少后台模式，而非其报告机制有问题，因此表中未将这些情况计为虚报成功。另外还有 5 次尝试在测试适配器中失败（屏幕上未找到已打开列表或菜单中的项目）。

本次运行中该服务未能成功的操作：WPF 原始点击、滚轮和 Ctrl+K；Tk、Electron、Edge 上对被遮挡画布的滚轮操作；以及本次 Win32 上的 Ctrl+K。每项都报告为拒绝操作或结果未知（~），从未报告为已完成。

历史表现：从 3.0.1（45 行被遮挡的测试中成功 35 项）到 3.0.2（10 月 23 日，在与 Cua 的对比中成功 51 项中的 44 项；详见 bench/RESULTS.md）：支持 Tk 点击和快捷键、Win32 Ctrl+K，以及滚动被遮挡的列表。仍然拒绝执行的操作及原因均从各工具包的源代码中查明并经测试确认：WPF 点击、滚轮和快捷键；对被遮挡画布的滚轮操作；以及在隐藏的 Electron 页面中的指定位置输入。从 Cua 借鉴：仅读取变化的内容（then="changes"）。未借鉴：其注入式 WPF 点击（会移动用户的真实光标）；在已打开的 Chrome 中使用 CDP 点击（会在用户的真实配置文件中启用远程调试）。试验后放弃：用于 WPF 快捷键的模拟激活（WPF 会抢占前台）；WM_POINTERWHEEL（Windows 拒绝发送）；向 Chromium 渲染器发送 WM_VSCROLL（无效果）；InjectSyntheticPointerInput（事件会发给最上层窗口）。

跨 Agent 基准测试（2026 年 10 月 16 日）

在这台电脑上使用的三个 Windows 桌面 Agent（本服务、Codex 层和 Antigravity 层）都执行了相同任务：在 WinForms 和 WPF 窗体上操作。这些窗体创建时未激活，位于 Z 序底部，用户则继续工作：填写三个字段、勾选一个复选框、打开“Formule”下拉列表、在打开的列表中选择“Bravo”，然后确认。验证依据是应用程序中读回的结果标签。禁止并统计了物理输入。

	上午	修复后	测量结果
本服务（0.7.0 + 下拉列表修复）	17/20	19/20	两类窗体中均读回了打开的列表；在打开的 WinForms 列表中执行 select 耗时 113 ms，而不是 22 s；应用程序收到 Formule=Bravo;Envois=1；在 1,371 和 773 个样本（20 ms）中均未抢占前台，未移动光标，未进行物理输入
NexusWindows for Codex 1.4.0	16/20	19/20	两类窗体中的每个步骤都经过验证；观察 + 批处理耗时 1.2 到 1.4 s
Antigravity 层	18/20	19/20	已读取并选中打开的 WinForms 列表；批处理状态是最差的一步

阻止本服务达到 20 分的剩余问题：单击“Validate”后状态仍为 ~，除非使用 expect（应用程序确实收到了该操作）；对于已关闭的 WPF 列表，click 的状态是 ~，而 expand 的状态是 ✓。

安全

• 紧急停止：按 Ctrl+Alt+Shift+Esc 可在下一个检查点中断正在运行的操作（包括输入），并在 2 分钟内拒绝所有新操作；此限制适用于所有对话和其他 Agent（协议如上）。
• 硬性拦截（共享策略，src/nexus_windows/shared/garde-fous.json，与 Antigravity 使用的 NexusWindows 文件相同）：绝不读取或操作安全桌面（UAC、锁屏和登录屏幕）及密码管理器。策略缺失或无法读取时，拒绝所有操作（默认拒绝）。
• 不可逆操作的确认：付款、购买、下单、转账、发送、发布、发帖、永久删除、清空回收站、格式化、卸载、重置、取消订阅、删除账户或将仓库设为公开，都需要在步骤中设置 confirm: true；模型只能在用户明确下令或回答“是”时设置此项。检查会覆盖手势触发的操作：通过 [N]、名称或坐标点击，双击，按 Enter（目标、默认按钮、附近的发送按钮）、Ctrl+Enter、Space、Alt+字母、输入换行符，以及 DevTools 页面和 Win32 菜单。常规操作不会记录或重放 confirm。
• 确认须绑定确切操作：向外执行的手势（发送、拨打、付款、发布、转账）还需要 accord: "<token>"。首次尝试会在输入任何内容前被拒绝，并显示确切操作的摘要（触发方式、进程、窗口标题、窗口可编辑字段的值）以及一次性令牌；只有在用户本人回答“是”后，才会使用 confirm: true 和该令牌重新发送同一步骤。期间任何变更都会使确认失效。
• 提示词注入信号：如果屏幕上读取到的文本看起来像是针对 AI 的指令，响应中会附加警告（仅作提示，绝不能用于授权操作）。
• 启动：浏览器绝不会使用由模型选择的配置文件、DevTools 端口或已加载的扩展程序（devtools=true 会打开全新的临时配置文件）。控制台、文件资源管理器、任务栏和其他应用不会被拒绝：此服务面向已经允许 Claude 运行命令的用户；如果希望在那里设置关卡，请保持 Claude 自身的权限提示开启。
• 密码字段：绝不输入内容。不会记录输入的文本（仅记录长度）。
• 账户：使用 devtools=true 启动的浏览器会使用不含账户或同步数据的临时配置文件；启动后会进行检查，之后会将其删除。
• 屏幕内容是数据：每次 look 都会提醒模型，屏幕上的文本不是指令。
• 保持代码最新：入口是一个小型 stdio 监控程序（reloader.py）。每次调用工具前，它都会比较磁盘上的代码和运行中服务的代码；如果代码已更改，它会等待正在进行的调用完成，启动新服务并重放客户端握手，因此更新无需重新连接（/mcp）。如果服务代码在两次检查之间发生更改，则会拒绝 act、launch 和 window，并在新服务上重放该调用。
• 超时：已放弃的调用会在下一个检查点取消，而不是稍后继续执行。
• 剪贴板：绝不使用。

隐私

NexusWindows for Claude 完全在你的 PC 上运行。它没有账户、不会收集遥测数据，也不会进行分析。它唯一主动发出的网络请求是检查更新：每天最多一次，在启动时于后台从 PyPI 读取最新版本号（https://pypi.org/pypi/nexus-windows-claude/json，除请求本身外不会发送任何内容）；如果它是由 uvx 启动的，则会将该版本准备到 uv 的缓存中，供 Claude 下次启动时使用。 设置 NEXUS_UPDATE_CHECK=off 可关闭此功能。DevTools 连接始终使用 127.0.0.1。

• 读取的内容：仅在调用工具时读取 Claude 所操作应用的窗口标题、UI Automation 树和窗口图像。不会检查密码管理器和安全桌面（look），也不会与之交互（act）；不过，windows 仍会列出它们的窗口标题，就像任务栏一样。OCR 后备功能使用 PC 上 Windows 内置的引擎；用于 OCR 的图像不会离开 PC。look(window="screen") 会读取整个屏幕，如你所见，包括所有可见窗口。notifications 工具以只读方式读取 Windows 通知数据库（应用、时间、文本；绝不修改），并会遮蔽安全码。
• 数据去向：工具结果会返回给 Claude Desktop 或 Claude Code，并由它们根据 Anthropic 自身的隐私政策发送给 Anthropic；此服务不会将任何内容发送到其他地方。
• 存储的内容：在 %USERPROFILE%\.claude\nexus-claude\（或 NEXUS_WINDOWS_HOME）下存储保留 14 天的 JSONL 调试日志（工具、技术、耗时、错误；输入的文本会替换为其长度）、你选择记住的操作流程，以及通过 devtools=true 创建的临时浏览器配置文件（之后会删除）。只有设置 NEXUS_WINDOWS_DEBUG_IMAGES=1 时，图像才会写入日志。在 %USERPROFILE%\.nexus\ 下存储共享的前台令牌和紧急停止状态，以及 status\windows-claude.json（已安装和最新版本、更新状态）；上次检查日期则存储在 windows-claude\update.json 中。在 %LOCALAPPDATA%\NexusJournal\windows\claude\（或 NEXUS_JOURNAL_HOME）下存储简短的月度 JSONL 日志，格式与其他 NexusWindows 工具相同（应用可执行文件名称、框架、操作、技术、结果、耗时、是否使用前台，以及错误的首几个词；在任何引号、冒号或方括号之前截断）；绝不记录输入文本、屏幕文本、标签、标题或路径。此服务绝不会删除该日志。
• 移除方式：从 Claude 中移除此服务（claude mcp remove nexus-windows），然后删除这些文件夹（以及 %LOCALAPPDATA%\NexusJournal）。

如有疑问或顾虑，请在此仓库中提交 issue。

限制

• 代码注释为法语。MCP 客户端收到的所有内容（指令、工具说明、步骤报告、拒绝消息）均为英语。
• 仅支持 Windows。在 Windows 11 上使用实验室应用和少数真实应用进行了测试；并非所有应用都经过检查。
• 没有 UI Automation、且会忽略已发送输入的应用（某些游戏、画布）需要真实输入，因此需要用户批准，并且窗口必须处于前台；OCR 回退机制能识别其中的文本，但无法在后台输入。
• WPF：在后台时会拒绝对某个位置的原始点击、鼠标滚轮和键盘快捷键（真实光标不在窗口上时，WPF 会丢弃点击；获得焦点时则会切换到前台）；支持 UI Automation 模式的控件可以正常工作。
• 被遮挡的 Chromium 画布无法响应鼠标滚轮（Chromium 会将其传递给最上层窗口）；此操作会被拒绝或报告为 ~，绝不会报告为成功。在 Tk 中，只有窗口被完全遮挡时滚轮才有效（见“按 UI 系列划分”）。列表和可滚动区域无需滚轮即可滚动（见“按 UI 系列划分”）。
• 被遮挡且已变为 hidden 的 Electron 页面（曾处于前台，之后失去前台）会停止渲染：对某个位置的点击会报告为 ~。
• Windows 在后台挂起的商店应用会通过 IPackageDebugSettings.Resume 恢复（不切换到前台）；如果 Windows 仍无法渲染该应用，则只能将其切换到前台显示；此情况会被报告。
• 在 Chromium 中，如果页面对每次按键的响应都非常慢，可能会超出读取回显的时限，并被报告为 ✗。
• 没有可读取内容的效果（例如按钮写入文件）会保持为 ~；请添加一个能够观测该效果的 check。
• 端到端测试套件（pytest -m live）会操作真实窗口，如果 PC 在过去 2 分钟内曾被使用，则会拒绝启动。

开发

pwsh -NoProfile -File test.ps1         # unit tests, ruff check and format; venv and caches outside the clone
pwsh -NoProfile -File test.ps1 -Full   # also the end-to-end tests on the lab windows
uv run python bench/bench.py           # technique benchmark (when nobody is using the PC)

许可证

MIT，详见 LICENSE。版权所有 (c) 2026 Julien Piron。