NexusWindows for Antigravity

适用于 Antigravity 的 NexusWindows

为 Antigravity 提供后台 Windows 电脑操作能力。 一个 MCP 服务（nexus-windows-antigravity），可让 Google Antigravity（Gemini）查看并操作 Windows 桌面应用，同时用户仍可使用鼠标、键盘和前台窗口。专为快速模型打造：先查看一次，再批量执行带标签的目标步骤；每次回复都会说明下一步操作。

版本 3.0.1 · Windows 10/11 · Python 3.11+ · MIT 许可证

Nexus 系列产品之一：NexusWindows （Claude · Codex · Antigravity）， NexusBrowser（仓库）， NexusAndroid（仓库）。 项目页面：julienpiron.fr/nexuswindows。

为什么

通过截图和点击来操作电脑，会移动真实光标并将窗口置于前台，因此 Agent 操作时，电脑前的人必须停止工作。大多数 Windows 应用都可以在不这样做的情况下进行操作：原生控件可接收窗口消息，现代框架则提供 UI Automation。此服务优先在后台操作，并读回操作结果；只有在步骤允许时（foreground=True），才会回退到真实鼠标或键盘操作。

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，uv（winget install astral-sh.uv）。

从 PyPI 安装，无需克隆：在 Antigravity 的 mcp_config.json（%USERPROFILE%\.gemini\config\mcp_config.json）中声明该服务：

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

指导 Antigravity 使用这五个工具的 Agent 指南是 SKILL.md：将 plugins/nexus-computer 文件夹复制到 Antigravity 的插件目录，即可与服务一并安装。

从克隆仓库安装（用于开发），需使用 PowerShell 7：

git clone https://github.com/pironjulien/NexusWindows-Antigravity.git
cd NexusWindows-Antigravity
pwsh -NoProfile -File install.ps1

此后，Python 环境、日志和屏幕截图会保存在 %USERPROFILE%\.nexusagy（克隆目录之外），并通过 "command": "pwsh"、"args": ["-NoProfile", "-File", "C:/path/to/NexusWindows-Antigravity/scripts/start-computer-mcp.ps1"] 声明该服务。

工具

列出的五个 MCP 工具与其他 NexusWindows 工具（Claude、Codex）的命名方式相同；旧名称（computer_look、 computer_act、computer_click……）仍可作为未列出的别名调用。

工具	用途
windows	应用窗口（by_app=true：按应用分组）
look	每个元素占一行，格式为 [N] role « name » = « value » states @x,y，并附带图像，不会将窗口置于前台
act	一次调用执行多个步骤（点击、输入、检查、取消勾选、选择、菜单、按键……），每步都会读回确认：✓ = ~ ✗
launch	打开应用、文档、文件夹、脚本或快捷方式；打开结果会读回确认
window	action="close"：关闭窗口（先使用 UI Automation，再使用 WM_CLOSE）

工具说明、服务指令、工具和参数名称使用英文；工具回复使用法语。

功能说明

• 专为 Gemini 设计：黄金法则是 先观察，再一次性执行带标签目标的操作；每条操作回复都包含一行 next（✓ 已完成 · = 已完成，不要重做 · ~ 未观察到效果，请查看附图 · ✗ 失败，说明原因和可尝试的方法），如果没有读回操作效果，还会附上一张窗口的精简 WebP 图片（≤ 1280 px）。如果同一窗口在最近 10 s 内发送过完全相同的批次，且中间没有执行 look，则会拒绝该批次（repeat=true 可强制执行）。
• 优先后台操作，即使设置了 foreground=True 也一样：box_2d 或 (x, y) 目标会映射到窗口自身 UI Automation 树中该位置下方的元素（包括被遮挡的窗口），并像标签目标一样处理；点击文本字段后会保留该字段，因此不带目标的 type、ctrl+a、ctrl+v 和擦除键都会作为后台写入并读回；普通按键会在 Win32、WinForms 和 WPF 中发送为消息（WM_KEYDOWN/WM_KEYUP）。只有在设置 foreground=True 时，才会把真实鼠标和键盘输入作为后备方案；否则会明确拒绝（needs_foreground），且不会发送任何输入。
• 按 UI 类型分别处理：Win32 → 直接发送消息（BN_CLICKED、BM_SETCHECK、EM_REPLACESEL、带通知的 CB_SETCURSEL / LB_SETCURSEL、菜单 WM_COMMAND）；WinForms → UI Automation，然后发送消息；WPF、UWP、Chromium → 仅使用 UI Automation。绝不对 Win32 按钮调用 UI Automation Invoke（其代理会激活窗口），也不对 Win32 列表调用 Select（无响应）。
• 一次跨进程读取：窗口范围内的 UI Automation 树会通过一次往返读取（IUIAutomationCacheRequest + BuildCache，AutoSetFocus = False）。读取被截断或失败时会报告（uia.status、warning），绝不会静默返回空列表。
• 每次操作后都读回：根据真实读取结果（字段值、勾选状态、选择项、焦点元素、窗口标题、图像）返回 verified true/false/None；仅仅“已发送命令”绝不会让 success 变为 true。步骤可以接受后置条件 expect（如果条件已满足，则跳过该步骤并设为 already: true；如果执行后条件不满足，则步骤失败）。批次会在第一个失败或未经验证的步骤处停止，不再发送下一项操作，也不会自动重放。已验证的后置条件可确认操作效果并允许批次继续；效果未知时，必须先观察，再准备剩余步骤。
• 通过 Raw Input 检测用户的实体输入（忽略注入的输入）：执行任何真实鼠标或键盘操作前，先等待用户暂停；如果用户触碰键盘或鼠标，则在下一个检查点停止（interrupted_by_user）。
• 防护措施写在代码中，而不只是说明里：始终明确指定窗口名称（默认绝不使用前台窗口；标题有歧义时会列出候选项并拒绝操作）；标签有歧义时会列出候选项并拒绝操作；每次 SendInput 前都会在前台读回目标窗口；绝不查看、捕获或操控密码管理器（KeePass、KeePassXC、Bitwarden、1Password、Dashlane、NordPass、RoboForm、LastPass）；拒绝操作登录屏幕、锁屏界面和 UAC 提示。标记为 pay、buy、order、transfer money、send、publish、delete permanently、uninstall、format、reset、cancel a subscription、erase data 或 make a repository public 的操作，以及会触发这些操作的任何按键、submit 或坐标点击，都必须在步骤中设置 confirm: true。在 MCP 服务环境中设置 NEXUS_AGY_CONFIRM=off 可完全关闭确认（默认：开启）。
• 剪贴板：保存并还原剪贴板的所有格式；放入其中的文本不会进入 Win+V 历史记录或云剪贴板。仅在输入文本的最后手段中使用（多行文本或超过 300 个字符）。
• Agent 正在工作：操作运行期间（act、打开、关闭、聚焦及操作别名；读取操作除外），驱动窗口所在屏幕的右下角会显示一个小徽标，并像游戏加载画面一样原地旋转，带有呼吸式蓝色光晕；最后一次操作完成 1.6 s 后消失。始终置顶、无边框、可穿透点击、从不激活、不显示在任务栏中，也不会被屏幕捕获（busy_indicator.py）。设置 NEXUS_WINDOWS_INDICATOR=0 可将其关闭。
• 与这台 PC 上的其他桌面 Agent 共享：前台令牌（%USERPROFILE%\.nexus\foreground.lock）和紧急停止（Ctrl+Alt+Shift+Esc，%USERPROFILE%\.nexus\stop）使用与 NexusWindows for Claude 相同的文件协议。

架构

路径	作用
client/mcp_server.py	MCP 服务 nexus-windows-antigravity（stdio），由 scripts/start-computer-mcp.ps1 启动
client/computer_client.py	Windows 引擎：窗口、UI Automation、Win32 消息、捕获、操作和读回
client/uia_fast.py、client/win32_controls.py	单次往返的 UI Automation 读取、原生控件消息
client/physical_input.py、client/agent_guard.py、client/emergency_stop.py	用户在场检测（Raw Input）、批处理防护、共享紧急停止
client/foreground_lock.py、client/garde_fous.py、client/garde-fous.json	共享前台令牌和护栏策略，供作者的桌面 Agent 共用（NexusWindows for Claude 也使用）。公开副本中包含这些文件；在作者的环境中，它们位于同级的 shared 文件夹中
plugins/nexus-computer/	Antigravity 插件和 Agent 指南（SKILL.md）
tests/	单元测试（pytest）和真实桌面验证

隐私

NexusWindows for Antigravity 完全在你的 PC 上运行。它没有账户、遥测或分析功能，也不会自行发出 网络请求。

• 读取内容：仅在调用工具时读取 Agent 正在操作的应用的窗口标题、辅助功能树和窗口图像。不会读取或操作密码管理器。
• 数据去向：工具结果会返回给 Antigravity，后者可能会根据自身隐私政策将其发送给 Google；此服务不会将任何内容发送到其他地方。
• 存储内容，位于 ~/.nexusagy/：Python 环境（仅克隆安装时；uvx 使用自身的 uv 缓存）、操作日志 computer.log（记录操作、方法、窗口、耗时、结果和简短详情，例如目标标签、坐标、按键名称、菜单路径或输入的字符数；绝不记录输入或预期文本；达到 5 MB 后轮换，保留三份备份），以及屏幕截图（每次捕获后最多保留 50 张；超过 24 小时的截图会在下次捕获和服务启动时清除，因此服务停止后，最后一批截图可能会保留到下次启动）。位于 ~/.nexus/：共享前台令牌和紧急停止状态。位于 %LOCALAPPDATA%\NexusJournal\windows\antigravity\（或 NEXUS_JOURNAL_HOME）：简短的月度 JSONL 日志，格式与其他 NexusWindows 工具相同（应用可执行文件名称、操作、技术、结果、耗时、是否使用了前台，以及错误的开头部分；在任何引号、冒号或方括号之前截断）；绝不记录输入文本、屏幕文本、标签、标题或路径。服务绝不会删除此日志。
• 移除方法：从 Antigravity 的 MCP 设置中移除此服务，然后删除 ~/.nexusagy/（以及 %LOCALAPPDATA%\NexusJournal）。

如有疑问或顾虑，请在此代码库中提交问题。

限制

• 仅支持 Windows。工具说明为英文；工具回复和代码注释为法文。
• 后台操作时，UWP/WinUI、Firefox 和 Tk 中的键盘输入会被拒绝，WPF 中的 Ctrl/Alt 快捷键也会被拒绝；Chromium/Electron 会通过模拟激活接收按键、快捷键和输入，并通过读回检查（若没有任何变化，则为 ~）。对于网页，NexusBrowser 更可靠。
• 没有可读取内容的效果会标记为 ~（未验证）。

开发

pwsh -NoProfile -File test.ps1         # offline: ruff, Pyright, pytest
pwsh -NoProfile -File test.ps1 -Full   # plus the real desktop validation on its own Win32, WinForms and WPF windows

真实验证会在不激活测试窗口的情况下显示它们，并在结束时关闭；只有当 PC 空闲达到 120 s 时才会进行真实鼠标和键盘检查，否则会报告为已跳过。

许可证

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