actl

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

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 桌面上的那个结构化集成,对照分析见 docs/12。)

安装

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:cargo install actl-cli(crate 名 actl-cli,二进制名 actl)。

源码:

git clone https://github.com/gqy20/actl && cd actl

make setup   # 一步配置:git hooks + pinned 工具链(等价 cargo xtask setup)

cargo build --release

快速上手

# 看一眼:目标窗口有哪些可操作元素(拿到稳定引用 @eN)

actl snapshot --app 记事本 --skeleton


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

actl click id:clearButton --app 计算器


# 输入文字(带护栏:焦点被抢自动停在批边界,如实上报已送达量)

actl type role:Document "报告正文..." --app 记事本

actl type role:Document "路径" --app 记事本 --paste   # 中文输入法环境推荐


# 组合键 + 结果断言(新窗口没出现立即报 ASSERTION_FAILED,不静默假成功)

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


# 多候选歧义?错误里直接带结构化候选(含可重放 ref),不用重拍快照

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

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

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


# 立即断言(verify)与耐心等待(wait)

actl verify --value id:CalculatorResults "56,088" --contains --app 计算器

actl wait --window 另存为 --timeout 5000

输出统一为 envelope JSON(ok/command/data|error/duration_ms), 错误带机器可读错误码 + 恢复建议 + 结构化 evidence,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}

桌面信号条(actl-signal)

自动化运行时,人的知情权与逃生口:右上角常驻迷你状态条(不抢焦点、DPI 感知、 Source Code Pro),状态灯取市场通行色——绿=执行中 · 琥珀=正在注入键鼠 · 红=已停止 · 灰=空闲 · 暗=失联。

Ctrl+Alt+F12:全局紧急停止,在途注入在动作边界被拒(ABORTED);
点击状态条:清除停止标志恢复;
状态全部拉取(输入占用锁 + 状态文件),零事件订阅。

安全设计

verify-then-inject:任何键盘/指针注入前以 Win32 物理前台为唯一判据核对目标, 不匹配宁可拒绝不错发;
fail-closed:press/type 必须显式 --app;指针物理动作必须 --physical; ref 回放可带 --snapshot <id> 校验窗口实例(同标题重开 → STALE_REF);
输入占用协调:多 actl 实例互斥;长注入分批复核焦点,被抢即停并上报;
修饰键治理:检测用户按住 ctrl/shift 时拒绝注入(防语义劫持),绝不踩掉用户按键。

命令面(24,`actl commands` 自发现)

感知 snapshot find get list-windows status commands · 执行 click right-click double-click hover drag scroll type press key-down key-up set-value · 窗口 launch focus-window close-window resize-window wait batch · 验证 verify extract · 系统 get-clipboard set-clipboard

完整语义与协议契约见设计蓝图。

项目状态

M2:24 命令全链路,金任务(计算器/记事本保存)10/10,US1 跨 3 应用数据搬运 16/16, envelope 契约测试,显示信号层。阶段与退出标准见 ROADMAP。

文档

调研与设计全索引(竞品调研、PRD、技术选型、设计蓝图、实测战记)· AGENTS.md(协作规范,人与 AI 共用)· skills/actl(Agent Skill)

License

MIT

actl-core 0.1.3