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 接口	本机 shell 调用还需额外服务；actl 的 CLI 可独立使用

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

平台范围：Windows；Linux/macOS 桌面执行后端暂不考虑实现。计划提供可选 MCP 服务，在被控 Windows 设备本地启动，供其他设备调用本设备能力；当前尚未实现，见路线图。

安装

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

scoop(推荐):

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

从 Releases 下载完整 ZIP，将 actl.exe 和同版本 actl-signal.exe 保存在同一目录，并把该目录加入 PATH。只读观察可独立使用主程序；桌面写操作需要配套显示端就绪和人工交接。

后续发布的完整 ZIP 还包含 skills/actl/、README 和 LICENSE。已发布的 0.1.6 ZIP 尚未包含 skills；使用该版本时，请从仓库的 v0.1.6 源码包获取配套文件。

cargo install actl-cli

cargo install actl-uia --bin actl-signal

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

给 Agent 加载技能

技能入口是 skills/actl/SKILL.md，应用知识、错误说明和流程索引在同目录下。解压 ZIP 不会自动安装技能；按所用 Agent 的技能配置方式，将完整的 skills/actl 目录注册或链接到它的技能目录，并确保 Agent 能调用 PATH 中的 actl。流程编写、恢复、任务归档和错误说明随技能保存在 references/ 中，可单独复制完整 skills/actl/ 目录；不要只复制 SKILL.md。技能内仅使用本地相对链接，无需联网查阅使用说明。

快速上手

需要先向用户展示目标时，可用独立预览（当前源码新增，旧版二进制需先更新）：

actl preview id:saveButton --app MyApp --message 'Save this draft here' --duration 5000

只显示边框和说明，不点击、不输入；点击预览窗口右上角关闭或等待自动结束。 ref 目标必须同时传 --snapshot。预览不是授权或业务核验，执行前仍需重新核对目标。

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

# 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)。旧调用不会因恢复复活；新任务可正常发起并点击“开始”。 actl execution-status 查看运行状态；旧格式/损坏状态使用 actl execution-recover 归档修复，修复不授予权限、不续跑任务。CLI 与显示端须成对更新至显示协议 v7。

命令一览(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 使用技能与应用档案
业务流程目录——actl 技能内部的业务 YAML 归属、索引与实现边界
路线图——阶段划分与版本口径

项目状态

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

参与开发

无人值守时可运行 cargo xtask regress --unattended：仅执行明确登记的无输入用例，其余写入报告为 skipped；complete 只表示所选用例全部通过，退出成功不代表整套 Phase 2 验收通过。只读性能与观察采样使用 cargo xtask diagnose phase2-readonly；指定本次观察到的 HWND 可追加快照对照，不启动或关闭应用。人工验收及遗留见 Phase 2 验收记录。

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

License

MIT

actl-core 0.1.7