Windows Harness

Windows Harness 是一个极简、轻薄的 Python 库，赋予大语言模型（LLM）在 Windows PC 上执行几乎任何任务的完全自由。它不依赖特定的应用插件或复杂的框架，而是通过提供一组原始的 Windows 交互原语，让代理能够像人类一样观察窗口、操作键盘鼠标、访问文件系统并控制浏览器。

核心理念：无框架、无限制、全自由

与传统的 RPA 工具或特定应用的 API 不同，Windows Harness 不提供“Spotify 工具”或“Excel 工具”。相反，它提供了一组通用的底层原语，让代理自行编写逻辑来完成复杂任务。

• 直接连接：一个直接的 Python 进程，连接到真实的 Windows 桌面、浏览器和文件系统。
• 自我补全：代理在任务进行中自行编写缺失的逻辑部分，无需预设的配方。
• 后台运行：能够捕获和操作后台、被遮挡甚至最小化的窗口，无需将其强制置于前台（尽管前台模式是更可靠的默认值）。

六大核心原语

Windows Harness 仅通过六个核心函数暴露整个桌面的控制权：

1. win.see(app): 观察指定应用的窗口状态。
2. win.key(keys, app): 发送键盘快捷键。
3. win.type(text, app): 输入文本（支持多种注入方式以确保可靠性）。
4. win.click(x, y, app): 在指定坐标点击。
5. win.ax(x, y, app): 获取指定坐标的 UI Automation 元素信息。
6. win.script(code): 执行 PowerShell 脚本。

此外，它还原生支持标准的 Python Path 和 subprocess，并通过 browser 对象惰性连接到你已登录的真实浏览器实例。

# 示例：在记事本中搜索并替换文本
frame = win.see("Notepad")
win.key("ctrl+h", app="Notepad")
win.type("Alessia Cara", app="Notepad")
win.click(640, 420, app="Notepad")

工作原理与技术细节

• 诚实的输入模式：
  • Foreground (默认)：将目标窗口置于前台并使用 SendInput。这是最可靠的方式，因为许多现代 UI 框架（如 CEF/XAML）仅在前台且获得焦点时才接受输入。
  • Background (可选)：通过合成笔注入或 PostMessage 进行静默操作。Harness 会预先检测哪些应用会静默丢弃后台事件，并以结构化的 BackgroundUnavailable 错误拒绝，而非假装成功。
• 可靠的文本输入：按优先级尝试 UIA set_value（带回读验证）、前台 Unicode 输入和剪贴板粘贴，确保即使有钩子软件拦截按键也能成功输入。
• 防篡改证明：每次坐标操作都会生成带有动画指针标记的截图，并返回路径供代理检查操作是否落在正确位置。
• UI Automation 兜底：当视觉识别不足时，直接暴露原始的 UI Automation 接口。

快速开始

1. 安装与注册技能

将以下指令粘贴到 Codex 或 Claude Code 中：

使用 Python 3.12 通过 uv 从 PyPI 安装或升级 Windows Harness。使用 windows-harness install-skill 注册其代理技能（默认安装到 ~/.agents、~/.codex、~/.claude 和 ~/.cursor），然后运行 windows-harness doctor。最后，通过捕获一个已在运行的应用而不将其置于前台来验证 harness。

2. 验证环境

运行 windows-harness doctor 检查运行时依赖，确保你处于交互式桌面（非 Session 0）且拥有必要的 Python 环境。

隐私与安全

• 无需管理员权限：除非你需要控制以提升权限运行的应用（受 UIPI 保护）。
• 匿名遥测：默认启用，仅记录命令类别、成功状态、持续时间等元数据。绝不记录提示词、应用名称、截图、UI 文本或窗口标题。
• 关闭遥测：可通过 windows-harness telemetry disable 完全关闭。