uia-agent 是一个开源 LLM agent 框架，用 UIA 无障碍树驱动 Windows 老古董桌面软件。 浏览器场景有 browser-use， 桌面场景这块一直没人认真做。这就是这块。
国内做政企、医疗、制造业开发的同行心里都清楚：
- 2008 年的 WinForms ERP、SAP GUI 客户端、SCADA 控制台、各种"绝对不能换"的 in-house 桌面软件，至今还在被人手动点鼠标驱动。
- 这些软件没有 API、没有 SDK、没有官方自动化通道。UiPath 这种 RPA 工具能用，但写脚本的成本几乎和招实习生手动操作差不多。
- 现在 Claude 4.x / GPT-5 这一代模型，多步工具调用的稳定性终于够了；
pywinauto和uiautomation这两个 Python 绑定也在最近 18 个月内追上了 .NET 版本的能力。
把这三个时间窗一对齐，结论很自然：把 UIA 无障碍树当成 LLM agent 的 action space，让模型每一步只输出一个结构化的 Action，由代码确定性地分发回 UIA。和 browser-use 同一个套路，只是把"DOM"换成了"UIA 树"。
自然语言目标进入 Typer CLI（run），CLI 启动 agent 循环：① observe — 快照当前焦点窗口的 UIA 树并剪枝到 ≤400 节点；② think — 把序列化后的树交给 LLM 适配层（Anthropic tool-use 或 OpenAI JSON-schema），拿回恰好一个结构化 Action；③ act — 通过真实 UIA 控件模式（Invoke / Value / SelectionItem / ExpandCollapse）把动作分发回正在运行的 Windows 软件；④ verify — 流式打出这一步并重新快照。没有服务、没有 daemon、没有 IPC——一个进程跑完，约 700 行 Python。
前置：Windows 10/11 交互式桌面会话；
ANTHROPIC_API_KEY或OPENAI_API_KEY至少有一个。
pip install uia-agent
export ANTHROPIC_API_KEY=sk-ant-... # 或者 OPENAI_API_KEY=sk-...
uia-agent run --app Notepad "输入 'hello world'，存到桌面，文件名 hello.txt"完事。agent 会一行一行打出每一步：它选了什么动作、目标节点是哪个、为什么——直到它输出 done 或者用完 step 预算为止。
典型输出
step 01 click → ee4f3c2a1d80 ✓ clicked Edit:'Document'
why: 先把焦点放到编辑区再输入
step 02 type → ee4f3c2a1d80 text='hello world' ✓ typed into Edit:'Document'
why: 把用户要的内容写进编辑区
step 03 key text='^s' ✓ sent keys '^s'
why: 用快捷键调出"另存为"对话框
step 04 type → a182be09f5cc text='hello.txt' ✓ typed into Edit:'文件名:'
why: 按要求填写文件名
step 05 click → 5b1c44e0aa10 ✓ clicked Button:'保存'
why: 提交保存
step 06 done ✓ agent reported done
why: 文件已经落盘
一句话进去，agent 先 dump 出 Notepad 剪枝后的 UIA 树，再端到端驱动它——聚焦编辑区、输入、调出"另存为"对话框、填文件名、点保存——全程一行一行流式打出每一步。
整个项目不到 700 行 Python，承重的就三个文件：
| 文件 | 职责 |
|---|---|
src/uia_agent/uia_tree.py |
抓取当前焦点窗口的 UIA 树，剪枝到 ≤400 节点 / ≤12 层深；丢掉离屏 + 无名噪声叶子；给每个节点算一个稳定的 hash id。 |
src/uia_agent/actions.py |
7 种有类型的动作（click / type / select / expand / key / wait / done），全部走真实 UIA pattern：Invoke、Value、SelectionItem、ExpandCollapse。 |
src/uia_agent/agent.py |
observe → think → act 循环。一个 while，不引入任何 framework，默认 25 步预算。 |
新意不在数据结构本身，而在框架：把 UIA 树看成 LLM agent 的一类 action space——和 DOM（browser-use）、像素（VLM）、人写的 selector（UiPath）并列。可防御的手艺是剪枝规则：怎么在真实老软件上把序列化后的树压到 8k token 以内，同时保留住所有可点的节点。
每一行都是真比过的，不是营销话术：
| uia-agent | browser-use | UiPath / Power Automate | VLM 截屏 agent | |
|---|---|---|---|---|
| 行动空间 | Windows UIA 树 | DOM | 人写的 selector 脚本 | 原始像素 |
| 每步成本 | UIA 遍历 + ~3-6k token | DOM 遍历 + 类似量级 | 0（预编译） | ~50× 倍 token（图像输入） |
| 确定性 | Pattern 分发（Invoke / Value / ...） | DOM event | 高，但 UI 一改就脆 | 低，模型依赖 |
| 不用人写 selector | ✓ | ✓ | ✗ | ✓ |
| 跨平台 | ✗（故意只做 Windows） | ✓（任何浏览器） | 部分 | ✓ |
| OSS + 自带模型 | ✓ MIT | ✓ MIT | ✗ | 因模型而异 |
老实说：browser-use 在跨平台和受众规模上明显赢。uia-agent 赢在那些真实存在却没人愿意做的场景——国企/医疗/制造业老 Windows 软件。这是我们故意挑的楔子。
没有配置文件，三个环境变量管全部：
| 变量 | 类型 | 默认值 | 含义 |
|---|---|---|---|
ANTHROPIC_API_KEY |
string | 未设 | 设了就用 Anthropic。 |
OPENAI_API_KEY |
string | 未设 | 设了就用 OpenAI 作为备选。 |
UIA_AGENT_PROVIDER |
anthropic | openai |
自动 | 两个 key 都有时强制选其一。 |
UIA_AGENT_MODEL |
string | 各 provider 默认 | 钉死一个具体模型 id（如 claude-sonnet-4-6、gpt-4o-2024-11-20）。 |
CLI 只有两个子命令：
uia-agent dump --app Notepad --indent 0
uia-agent run --app Calculator --max-steps 15 "算一下 17 * 23"- m1 —
uia-agent dump把任意 Windows 焦点窗口的 UIA 树剪枝后打成 JSON。 - m2 —
uia-agent run跑完 observe → think → act 循环，7 种动作 + 结构化 LLM 输出。 - m3 — 自带 Notepad / Calculator demo，README 录屏脚本（vhs），benchmark 脚手架。
- v0.2 — 框架适配层 — LangChain / AutoGen / CrewAI 的接入做成可选 extras。
- v0.2 — 视觉兜底 — UIA 拿不到有效节点时退到 OCR + bbox 点击，不要直接放弃。
- v0.3 — 多窗口 — 跨两个焦点应用编排（比如 SAP GUI ↔ Excel）。
- v0.3 —
BENCHMARK.md活的成绩单 — 按 (app × LLM × 版本) 维度公开 hit-rate，每次发版刷新。
- 只支持 Windows。 macOS 的 Accessibility API、Linux 的 AT-SPI 是完全不同的形状，v0.1 不承诺移植。
- 只支持有人值守的桌面。 UIA 需要交互式 session，v0.1 不跑无人值守 / 服务器场景。
- 唯一值得信任的指标是 hit-rate。 如果你目标软件的 UIA 树本身就坏（节点没名字、没 Invoke、没 Value），这个工具救不了你。我们会在
BENCHMARK.md公开 5 个参考应用的真实 hit-rate；如果均值 < 40%，我们会自己宣布 kill 项目而不是粉饰。 - API key 自带。 没有云端 runner、没有 telemetry、没有付费层。v0.1 就是 MIT + BYO。
- browser-use/browser-harness — 同样的 LLM-驱动 UI 树的范式，只不过 target 是 DOM。uia-agent 是它的桌面补集。
- HKUDS/nanobot — agentic action-space 方向比较新的研究工作；他们在 DOM 类目标上的抽象，搬到 UIA 上是吻合的。
- pywinauto / uiautomation — 让这个 700 行的小项目能跑起来的真正功臣，所有 Windows 交互的脏活累活都是它们扛的。
MIT，详见 LICENSE。欢迎 PR；超过单屏改动的修改建议先开 issue 对一下范围。
推到 GitHub 之后顺手设一下 topic，让发现路径正常：
gh repo edit --add-topic agent --add-topic windows --add-topic uia \
--add-topic llm --add-topic accessibilityMIT © 2026 supermario-leo · 由 @supermario-leo 公开维护。