免手操作 Windows 控制

一项用于自动化原生 Windows 应用（UIA）和网页浏览器（Playwright）的引导式技能，通过 handsfree-windows CLI 实现。

首次使用：自动配置

首次使用时，请先运行配置脚本，再执行其他任何命令：

python scripts/setup.py

该命令将执行以下操作：

1. 从 GitHub 克隆 handsfree-windows 仓库至 ~/.handsfree-windows/cli/（公开仓库，仅读取权限）
2. 通过 pip install -e 安装（标准 pip 可编辑安装）
3. 安装 Playwright 及 Chromium 浏览器二进制文件（约 200 MB，一次性从 cdn.playwright.dev 下载）
4. 运行 check_setup.py 验证全部组件是否正常工作

如需跳过浏览器安装（所有以 browser- 开头的命令将不可用）：

python scripts/setup.py --no-browser

如需安装到自定义目录：

python scripts/setup.py --install-dir "C:yourpreferredpath"

已安装？可随时验证：

python scripts/check_setup.py

写入磁盘的内容（完全透明）

• CLI 源代码：~/.handsfree-windows/cli/（或由 --install-dir 指定的路径）
• pip 可编辑链接：标准 site-packages 中的 egg-link（由 pip 管理）
• 浏览器持久化用户资料：~/.handsfree-windows/browser-profiles// 包含 Cookie 和登录会话。删除该目录可重置浏览器身份认证状态。
• 浏览器会话状态：~/.handsfree-windows/browser-state.json（最近访问的 URL）
• Playwright 浏览器二进制文件：~\AppData\Local\ms-playwright（Windows 平台，约 800 MB）

如需彻底卸载全部内容：

pip uninstall handsfree-windows -y
Remove-Item -Recurse -Force "$env:USERPROFILE\.handsfree-windows"

核心规则

• 切勿猜测 UI 控件。请先运行 hf tree 或 hf inspect，再对实际存在的元素进行操作。
• 切勿输入凭据信息。导航至登录页面后，由人工完成身份验证。
• 优先使用 UIA 选择器（name + control_type），而非原始坐标定位。
• drag-canvas 仅适用于画布/墨迹类界面（如 Paint、绘图类应用等）。
• 对破坏性操作（如 delete、submit、send），须首先向人工确认。

工作流：桌面应用（UIA）

# 启动任意已安装的应用
hf start --app "Outlook"

# 查找窗口
hf list-windows --json

# 探查控件（不依赖猜测）
hf tree --title-regex "Outlook" --depth 10 --max-nodes 30000

# 对探查结果执行操作
hf click --title "Outlook" --name "New mail" --control-type "Button"

# 检查光标下方的元素
hf inspect --json

工作流：浏览器（Playwright）

# 打开 URL —— 登录会话将自动保存在用户资料中
hf browser-open --url "https://example.com"

# 操作前先检查页面结构
hf browser-snapshot --fmt text

# 执行操作
hf browser-click --text "Sign in"
hf browser-type --selector "#email" --text "user@example.com"

# 验证结果
hf browser-screenshot --out result.png

混合宏（单个 YAML 文件中同时控制桌面与 Web）

- action: start
  args:
    app: "My Desktop App"

- action: browser-open
  args:
    url: "https://app.example.com"
    headless: false

- action: browser-click
  args:
    text: "Get Started"

- action: sleep
  args:
    seconds: 1

运行方式：hf run macro.yaml

参考文档

• 完整命令参考及选择器模式说明：references/api_reference.md