actl

仓库私有期间 Actions 徽章仅登录可见;crates.io/License 徽章为公开数据。

让 AI 像人一样操作 Windows 软件——但更快、更准、每一步可验证。

为什么是 actl

actl 是一个给 AI agent 用的 Windows 命令行工具:agent 在 shell 里敲一条条命令,就能点击按钮、输入文字、读写剪贴板、操作任何桌面应用。它不看截图、不猜坐标——直接读取系统的无障碍树(UIA),像 Playwright 读网页 DOM 一样精确找到控件再操作,输出结构化 JSON。

常见方案	问题
截图 + 视觉模型(Agent-S、UI-TARS 等)	慢、贵:每步过一遍 VLM,看图猜坐标,点错无法归因
让 AI 写 AutoHotkey 脚本	能力够,但是"整段盲跑":没有逐步反馈,失败只能整段重来
挂一个 MCP server	重、占 agent 上下文;actl 是普通 CLI,任何能跑 shell 的 agent 拿来就用

一句话定位:Playwright 之于浏览器,actl 之于 Windows 桌面。Codex Computer Use 的官方降级顺序即"有结构化集成就优先于 computer use"——actl 就是 Windows 桌面上的那个结构化集成(对照分析)。

安装

要求:Windows x64(UIA 为系统自带,无需驱动或后台服务)。

scoop(推荐):

scoop install https://raw.githubusercontent.com/gqy20/actl/main/scoop/actl.json

从 Releases 拿 actl_vX.Y.Z_windows_amd64.exe,主程序单文件即可用;完整包 zip 额外含 actl-signal.exe(桌面信号条,建议同装)。

cargo install actl-cli

crate 名 actl-cli,二进制名 actl;workspace 另有 actl-core(协议层)与 actl-uia(UIA 后端)两个可独立复用的 crate。

快速上手

三条命令走一遍"感知 → 执行 → 断言":

# 1. 感知:目标窗口有哪些可操作元素(拿到稳定引用 @eN)

actl snapshot --app 记事本 --skeleton

#    浏览器页面用内容域投影:工具栏整枝丢弃,token 削减 70-80%(实测)

actl snapshot --app Edge --view content --skeleton


# 2. 执行:点击(UIA Invoke,后台执行不抢鼠标)

actl click id:clearButton --app 计算器


# 3. 断言:组合键后新窗口必须出现,否则立即报 ASSERTION_FAILED,不静默假成功

actl press ctrl+s --app 记事本 --expect window:另存为

中文输入法环境下,actl type ... --paste 走剪贴板通道输入文字,更稳。

输出统一为 envelope JSON(ok/command/data|error/duration_ms),错误带机器可读错误码 + 恢复建议 + 结构化证据,agent 可自我恢复:

{"version":"1","ok":false,"command":"click","error":{
  "code":"AMBIGUOUS",
  "message":"role:Button matches 34 elements in the window",
  "hint":"tighten the selector or pick by index",
  "evidence":{"candidates":[{"ref":"@e2","role":"Button","name":"最小化 计算器"}]}},
 "duration_ms":1563}

定位歧义时,错误里直接带结构化候选(含可重放 ref),不用重拍快照:

actl click role:Button --app 计算器                          # → AMBIGUOUS + candidates[]

actl click role:Button#3 --app 计算器                        # 序数直选

actl click role:Button --near id:clearButton --app 计算器    # 锚点就近

每条命令 actl <cmd> -h 均有四要素 help(用途/参数/示例/错误码);完整命令语义与协议契约见设计蓝图。

核心特性

精准定位,不猜坐标:直接读系统 UIA 无障碍树,支持 @eN 引用、name:/id:/role: 选择器、序数与锚点就近消歧;虚拟化大列表(资源管理器条目级)、老 Win32 报表 (msinfo32)、Chromium/Electron 系正文读取均实测通达。
逐步可验证:verify/wait 支持值断言与属性谓词等待(--property value=OK/ name=子串/checked=on);batch 步级可观测;每个错误都带错误码 + hint + evidence,agent 拿到就能自我恢复。
安全护栏,宁可拒绝不错发:
- 键鼠注入前以物理前台窗口为唯一判据核对目标,不匹配即拒绝;长注入分批复核焦点, 被抢自动停在批边界并如实上报;
- type/press 必须显式 --app,指针物理动作必须显式 --physical——默认走 UIA 后台调用,不抢用户的鼠标键盘;
- 检测到用户按住 Ctrl/Shift 时拒绝注入(防语义劫持),绝不踩掉用户按键;多 actl 实例输入互斥。
桌面信号条 actl-signal(建议同装):自动化运行时的知情权与逃生口——右上角常驻迷你状态条(不抢焦点、DPI 感知),绿=执行中 · 琥珀=正在注入键鼠 · 红=已停止 · 灰=空闲 · 暗=失联;Ctrl+Alt+F12 全局紧急停止,在途注入在动作边界被拒 (ABORTED),点击状态条清除停止标志恢复。

命令一览(33 条,`actl commands` 自发现)

类别	命令
感知	`snapshot` `find` `get` `list-windows` `screenshot` `status` `commands`
执行	`click` `right-click` `double-click` `middle-click` `triple-click` `hover` `drag` `scroll` `type` `paste` `press` `key-down` `key-up` `set-value` `select` `toggle`
窗口	`launch` `focus-window` `close-window` `resize-window` `wait` `batch`
验证	`verify` `extract`
系统	`get-clipboard` `set-clipboard`

文档

设计蓝图——完整命令语义与协议契约
场景实测记录——Office 三闭环、微信核心通道等真实应用战记
浏览器场景战记——Edge/Chrome 双验证、xhs/bili/douyin 登录态深度闭环、扩展操作面、视觉兜底 xy: 端到端
调研与设计全索引——竞品调研、PRD、技术选型、实测战记
Agent Skill——给 agent 的 actl 使用技能与应用档案
路线图——阶段划分与版本口径

项目状态

当前 v0.1.x(M2 阶段):33 条命令全链路可用;计算器与记事本保存的端到端任务、跨 3 应用数据搬运均实测全绿;Office(Excel/Word)与微信核心通道已实测通达;浏览器内容通道(--view content 投影、--stable settle、坐标寻址 xy: 视觉兜底)经 Edge/Chrome 双验证,xhs/bili/douyin 登录态深度闭环实测;场景结论持续沉淀进 docs 与应用档案。阶段划分与版本口径见 ROADMAP。

参与开发

Rust workspace,trunk-based(main 始终绿)。克隆后 make setup 一步配好 git hooks 与锁定工具链,提交前 make gate 过门禁;协作规范(Conventional Commits、测试纪律、门禁单点等)见 AGENTS.md,人与 AI 共用。

License

MIT

actl-core 0.1.5