umbriel

这是什么？

Umbriel 会像人一样操控 Windows 桌面——根据当前应用的实际情况，使用真正有效的方式：

1. 像素与 OCR——当应用完全不提供控件树时（画布、自定义绘制界面、游戏），回退到全屏捕获、模板匹配和文本识别。
2. 语义控件——读取应用提供的 UI Automation 树，按名称和角色定位控件，而不是依赖坐标。即使 DPI、布局和主题发生变化，也能继续工作，不会像像素脚本那样失效。
3. 查看与窗口控制——捕获任意窗口的实时像素（即使窗口完全由 GPU 合成或被遮挡），检查原始 HWND 层级，并移动、置顶或调整窗口大小。
4. 输入路由——对支持后台操作的控件使用语义 UIA 和消息投递输入；只有当无 HWND 的编辑器或真实指针手势确实需要前台操作时，才回退到经验证的 SendInput。
5. 操控操作系统，而不仅是 GUI——当任务就是操作系统本身时，直接对其进行操作：读取和写入注册表（包括值和项），列出 / 终止 / 挂起 / 调整优先级进程，查询 / 启动 / 停止 / 配置服务，创建 / 删除 / 枚举计划任务，读取防火墙规则，枚举网络适配器和实时连接，控制会话电源（锁定 / 重启 / 睡眠 / 休眠），列出卷和可用空间，获取和设置环境变量，读取事件日志，以及读取或更改显示模式——全部使用原生功能，无需 PowerShell 或调用 shell。

底层只需几 KB 的 TypeScript，运行于 Bun 内置的 FFI 之上——无需 Appium 服务、.NET、node-gyp 或预编译二进制文件。

安装

bun add umbriel

安装就这么简单。无需构建，也无需编译任何内容。

专为 AI Agent 打造

Umbriel 的用途就在于此。将已发布的服务注册到 Codex（ChatGPT 桌面应用、CLI 和 IDE 共用此配置）：

codex mcp add umbriel -- bunx umbriel

也可以将其注册到 Claude：

claude mcp add umbriel -- bunx umbriel

之后，任何支持 MCP 的 Agent 都能以每步约 15 ms 的速度根据无障碍树确定操作目标，并根据目标需要使用语义操作、发送消息、合成输入或像素回退方式。大多数经典控件在窗口处于后台时仍可操作；没有自身 HWND 的 Chromium/WPF/WinUI 编辑器则需要短暂解锁前台租约，才能接收真实输入。Umbriel 会在注入前验证目标窗口，可以验证操作后的编辑器状态，并默认恢复之前的前台窗口。

截图 Agent 每一步都要消耗图像令牌——然后还要再消耗一次，对自己的操作结果截图，因为它无法从像素中读取状态。Umbriel 会将整个窗口映射为纯文本，只需缓存一次，就能在后续步骤中重复使用，并直接从该映射中读取结果。微软的 UFO2 和 OSWorld-Human 基准测试所建议的 grounding 方式也是如此（结构优先，视觉其次）——而且不用付出高昂成本。

umbriel.tree(app, { agentProfile: true });
// → one cached round-trip → { role, name, automationId, bounds, children }

⚡ 约 13 ms 即可映射一个窗口 · 令牌是缓存一次即可重复使用的文本，而不是每一步都要重新购买的图像 · grounding 速度最高可比 3–26 s 的截图流程快约 2000 倍

每个 Agent 步骤	截图 Agent	Umbriel
令牌	1.5–2.7k 图像令牌——然后重新截图自检	约 3k 文本令牌——缓存后可在多个步骤中重复使用
grounding 时间	3–26 s	约 13 ms
能否读取状态？	不能——必须再截一张图	能——直接从快照中读取

_{Umbriel 数据在 Windows 11、Bun 1.4 上测得（计算器上为 14.3 ms · 约 3k 令牌；单次属性读取约 58 µs）——可通过 bun run example/benchmark.ts 复现。截图流程数据来自已发布的第三方结果（OSWorld-Human；计算机使用场景的图像令牌成本）。}

MCP 服务提供 99 个快照优先工具（默认 safe 配置文件下为 76 个；readonly 下为 41 个；23 个 os/fs 工具需要 full 或 UMBRIEL_OS=1），并受你控制的部署策略约束：

UMBRIEL_PROFILE=readonly   # observe only
UMBRIEL_PROFILE=safe       # default — observe + cursor-free control + window management
UMBRIEL_PROFILE=full       # everything, including launch/run/file tools

desktop_snapshot 会返回以 ref 为键的视图——Button "Five" [ref=e49#3]——每次操作都会返回最精简但忠实的更新：变化较少时返回紧凑增量，变化较多时返回精简后的快照。模型可以重新确定操作目标，而不会被令牌淹没。

对于按时间顺序排列的聊天记录和日志，desktop_snapshot { root: "Messages in general", tail: 20, maxDepth: 2 } 只会返回最新的直接子项。这样在到达需要回复的消息之前，就不必为数百条已加载的旧记录付费。

如果已知窗口句柄，可以在首次调用时应用相同的范围：attach { hWnd: "0x123", root: "Messages in general", tail: 20, maxDepth: 2 }。若要限制其他大型初始树的范围，可在不指定 root 时使用 maxDepth/maxNodes。

对于 Discord 的 Slate 撰写框等受控 Web 编辑器，请使用 MCP type 工具并设置 method: "paste"、verify: true 和 submit: true（仅在确认可以替换现有草稿后再添加 clear: true）。UIA set_value 可能会修改已公开的 DOM 值，却不更新应用程序内部的编辑器模型，因此不能作为可靠的后台发送方式。提交结果不明确时会报告为未验证；切勿盲目重试。

在代码中使用

Umbriel 也是一款一等公民库，可用于 E2E 测试和桌面自动化——按名称查找 → 等待 → 操作 → 断言，就像在 Web 上使用 getByRole 一样：

import { ControlType, umbriel } from 'umbriel';

const app  = await umbriel.launch(['notepad.exe'], { className: 'Notepad' });
const edit = await app.waitFor({ controlType: ControlType.Document });

edit.focus().type('nothing native compiles, and it just works');
console.log(edit.text()); // → nothing native compiles, and it just works

// Drive Calculator to 5 + 3 = 8 — by name, not pixels:
const calc = await umbriel.launch(['cmd', '/c', 'start', 'calc'], { title: 'Calculator' });

for (const name of ['Five', 'Plus', 'Three', 'Equals'])
  calc.find({ controlType: ControlType.Button, name })?.invoke();

console.log(calc.find({ automationId: 'CalculatorResults' })?.name); // → "Display is 8"

为什么选择 Umbriel？

npm 中用于 Windows 桌面自动化的领域遍布原生插件构建失败、付费墙和弃置的守护进程。此前，Node 或 Bun 一直没有免安装、带类型、进程内运行的 Windows 自动化客户端——直到现在。

由于 Umbriel 是基于 Bun 自带 FFI 的纯 TypeScript，因此它：

• 无法设置付费墙——没有可通过订阅注册表设限的已编译二进制文件。
• 无需构建步骤——没有 ABI 矩阵、无需 MSVC 或 Python 工具链，也无需 node-gyp。
• 在进程内与 Windows 通信——无需通过 127.0.0.1:4723 往返，无需 Appium 守护进程、开发人员模式或 WinAppDriver。

各替代方案对比（npm 每周下载量，2026-06-05 当周）

工具	每周下载量	注意事项
FlaUI / pywinauto / AutoIt	不适用	必须安装并随产品分发一整套外部运行时（.NET / Python / 专用 EXE）。
@bright-fish/node-ui-automation	33	唯一真正的 npm UIA 封装库——自 2022 年起已停止维护。
@nut-tree-fork/nut-js	32,360	已设置付费墙的原项目的分支。仅支持像素／图像匹配——没有语义模型。
appium-windows-driver	30,749	需要 Appium 服务，还需要单独的 WinAppDriver.exe，而 Microsoft 多年来一直没有维护它。
robotjs / @jitsi/robotjs	11,375 / 15,333	需要通过 node-gyp 编译 C++——有记录以来最常见的安装失败原因。只能盲目操作像素和按键，没有元素模型。
uiohook-napi	21,965	维护状态良好，但全局钩子运行在外部线程上，可能导致段错误。

亮点

	能力	功能说明
🌐	Chromium 和 Electron	将 Chrome、Edge 和 Electron 应用（Discord、Slack、Spotify、VS Code）页面中的 DOM 作为真实元素进行操作——与原生控件使用相同的 API。
🛠️	操作整个操作系统，而不只是 GUI	注册表（读取、带类型写入、创建／删除项）、进程（查看信息／终止／挂起／调整优先级）、服务（及配置）、计划任务（及创建／删除）、防火墙规则、网络适配器和连接、会话电源、卷和可用空间、环境变量、事件日志、显示器（读取和设置模式）——全部使用原生方式，无需 PowerShell。
📋	剪贴板	粘贴大段文本，不会因逐键输入而损坏；也可以从任意应用复制并读取内容。
🌑	在后台操作	invoke / scroll / setValue / toggle 不会移动光标——可操作隐藏、最小化、被遮挡或锁定的窗口。
🖼️	像素和 OCR 备用方案	支持坐标点击、全屏捕获、模板匹配和文本识别，可用于画布和游戏。
🔎	读取所有内容	支持 MSAA 树、边界框、数据网格单元格、启用／选中状态、原生 HWND 层级结构、文本和值。
🌍	真正的 Unicode 输入	日语、韩语、带变音符号的拉丁文字和表情符号均可通过三种输入方式完整传输——已有回归测试验证。
👁️	洞察不可见内容	通过 Windows.Graphics.Capture 捕获经 GPU 合成或被遮挡窗口的实时像素。
🎯	语义定位	按 automationId、名称或角色查找控件——在目标应用内筛选精确匹配项，提高速度。
🧩	覆盖整个技术栈	Electron/Chromium、Java、Qt、WPF、Win32、WinForms、WinUI/UWP——每种技术都有各自的回归测试作为保障。
⏳	waitFor	为不稳定的原生 UI 提供 Playwright 风格的自动重试；超时时会列出最接近的候选项和你的选择器。

要求

• 优先使用语义定位，只有没有结构时才使用像素——自定义绘制界面、游戏和 WebGL 表面会回退到内置的像素 + OCR 层；所有具有树结构的界面都可进行精确的语义定位。
• 模拟输入和真实点击需要解锁的桌面——invoke、读取和 setValue 即使在锁定会话中也能工作，因此优先使用它们。
• 最小化状态下的操作适用于经典 Win32 窗口——invoke / setValue / toggle 在经典 Win32/HWND 窗口最小化或完全置于后台时仍可工作，但 UWP/WinUI 商店应用最小化时会挂起其 UI 线程和辅助功能树（树读取结果为空，已发送的操作也不会生效，直到应用恢复），因此请先恢复应用。
• Windows 10 或 11、Bun ≥ 1.1——仅支持 Windows 和 Bun，这是实现零依赖与进程内高速运行所付出的代价。

深入了解

完整的 API 位于 AI.md 中——内容详尽，确保 Agent（或开发者）无需阅读源码。可运行的演示位于 example/。

---