CLAWS-UIS -- 人类示教的计算机操控智能体

中文 | English

CLAWS-UIS -- 人类示教的计算机操控智能体

Computer Learning from Actions With Screenshots — UI + Agent-S

教你的电脑一次，CLAWS 学会工作流并自动执行新的任务变体。
录制 | 学习 | 规划 | 行动 | 执行

什么是 CLAWS-UIS？

CLAWS-UIS 是一个面向真实 Windows 和 macOS 桌面的人类示教计算机操控智能体。

录制人类操作演示（屏幕 + 鼠标 + 键盘）
学习从演示中提取语义化的操作轨迹
规划与行动 基于学习到的工作流执行新任务
执行通过操作系统级别的点击、拖拽、输入、滚动和快捷键可靠地完成任务

CLAWS 通过抽象而非记忆来学习——一次演示即可泛化到整个任务族。

本项目基于两个优秀的开源工作：

ShowUI（ShowLab）—— 用于 GUI 视觉定位的视觉-语言-动作模型。ShowUI 提供了视觉理解基础，使 CLAWS 能够理解截图并定位 UI 元素。
Agent-S（Simular AI）—— 首个在 OSWorld 上超越人类表现的 GUI 自动化智能体（72.60%）。CLAWS 集成了 Agent-S3 作为自主执行引擎，利用其截图分析、动作规划和自我反思能力。

五大核心模式

CLAWS-UIS 支持五种使用模式，覆盖不同的自动化场景：

模式	输入	输出	入口脚本	典型耗时
模式 1：录制 -> 学习 -> 执行	人类演示 + 新任务	智能体执行任务	`hybrid_run.py`	1-3 分钟
模式 2：纯智能体执行	仅任务描述	直接完成任务（无脚本）	`pipeline_run.py`	1-3 分钟
模式 3：智能体执行 -> 生成脚本	仅任务描述	可复用的混合脚本	`pipeline_run.py`	5-10 分钟
模式 4：录制 -> 编译 -> 脚本	人类演示	可复用的混合脚本	`pipeline_run.py`	3-8 分钟
模式 5：脚本回放	编译脚本 + 参数	直接完成任务	`workflow_run.py`	30秒-2分钟

模式 1：录制 -> 学习 -> 执行

录制一段操作演示，然后让智能体在学到的轨迹引导下执行相似任务。

# 1. 录制操作演示（GUI 录制器）
python -m Aloha_Learn.recorder.recorder_gui

# 2. 解析录制内容为轨迹
cd Aloha_Learn && python parser.py my_demo

# 3. 将轨迹复制到执行目录
cp projects/my_demo/my_demo_trace.json ../Aloha_Act/trace_data/

# 4. 以学到的轨迹为引导执行任务
cd ../Aloha_Act
python scripts/hybrid_run.py --task "你的任务描述" --trace-id my_demo

模式 2：纯智能体执行

让智能体从头到尾自主执行任务。不生成脚本——智能体直接完成任务后退出。

cd Aloha_Act
python scripts/pipeline_run.py --mode agent-execute --task "打开微信，搜索联系人Alice，发送消息你好"

执行过程： Agent-S3 接管桌面，实时分析截图，执行点击/输入/滚动等操作，直到任务完成或达到步数上限。

适用场景： 不需要可复用脚本的一次性快速任务。智能体立即执行并退出。

模式 3：智能体执行 -> 生成脚本

让智能体自主执行任务，然后将执行结果编译为可复用的混合脚本（RPA + 智能体）。

cd Aloha_Act
python scripts/pipeline_run.py --mode agent-only --task "打开微信，搜索联系人Alice，发送消息你好"

执行逻辑（两个阶段）：

阶段一：智能体执行（约 1-3 分钟）
  Agent-S3 截屏 -> VLM 分析 -> 生成 pyautogui 代码
  -> 在真实桌面执行点击/输入/滚动 -> 重复直到任务完成
  -> 保存执行轨迹 + 截图至 Aloha_Act/agent_runs/{task_id}/

阶段二：工作流编译（约 3-7 分钟）
  VLM (Gemini) 分析每步的截图 + 操作
  -> 分类为 RPA（图像匹配）或 Agent（VLM 驱动）
  -> 为 RPA 步骤生成参考裁剪图
  -> 用 VLM 验证定位器准确性
  -> 提取可参数化变量（联系人名、消息内容等）
  -> 输出编译脚本至 Aloha_Act/trace_data/{task_id}_compiled.json

完成后输出：

=== Agent-only pipeline complete ===
Compiled script: Aloha_Act/trace_data/{task_id}_compiled.json
Summary: 6 steps (RPA=2, AGENT=3, CHECKPOINT=1)
Parameters: contact_name (default: "Alice")

To replay:
  python scripts/workflow_run.py --trace-id {task_id}
  python scripts/workflow_run.py {task_id} --contact_name Bob

为什么需要 5-10 分钟？ 阶段一每步都需要 VLM API 调用（每次包含完整截图）。阶段二将所有截图发送给 Gemini 批量编译，然后进行定位器验证和重新裁剪。每次 VLM 调用需 5-15 秒。

模式 4：录制 -> 编译 -> 脚本

录制人类操作演示，直接编译为可复用的混合脚本（无需智能体执行）。

# 1. 录制演示
python -m Aloha_Learn.recorder.recorder_gui
cd Aloha_Learn && python parser.py my_demo
cp projects/my_demo/my_demo_trace.json ../Aloha_Act/trace_data/

# 2. 将轨迹编译为可复用脚本
cd ../Aloha_Act
python scripts/pipeline_run.py --mode compile-only --trace-id my_demo

执行逻辑：

步骤 1：加载人类轨迹 + 截图（来自 Aloha_Learn/projects/）
步骤 2：VLM (Gemini) 将每步分类为 RPA 或 Agent
步骤 3：生成参考裁剪图 + 验证定位器
步骤 4：提取参数 + 输出编译脚本
-> Aloha_Act/trace_data/{trace_id}_compiled.json

完成后输出：

=== Compilation complete ===
Compiled script: Aloha_Act/trace_data/my_demo_compiled.json
Summary: 8 steps (RPA=5, AGENT=2, CHECKPOINT=1)
Parameters: contact_name, message_text

To replay:
  python scripts/workflow_run.py --trace-id my_demo
  python scripts/workflow_run.py my_demo --contact_name Bob --message_text "你好呀"

相比模式 3 的优势： 人类演示提供更高质量的截图和更精确的坐标。模式 4 编译出的脚本通常比模式 3 具有更好的 RPA 准确性。

模式 5：脚本回放

执行之前编译好的脚本。这是最快的模式——RPA 步骤使用图像匹配（无 VLM 调用），仅 Agent 步骤调用 VLM。

cd Aloha_Act

# 基本回放
python scripts/workflow_run.py --trace-id my_demo

# 参数替换（同一脚本，不同输入）
python scripts/workflow_run.py my_demo --contact_name Bob --message "你好呀"

# 或以 JSON 传递参数
python scripts/workflow_run.py --trace-id my_demo --params '{"contact_name":"Bob","message":"你好呀"}'

混合回放工作原理：

对于每个编译步骤：
  如果 mode=rpa：        图像匹配参考裁剪图 -> 在匹配位置点击（快速，无 VLM）
  如果 mode=agent：      将截图发送给 Agent-S3 VLM -> 执行返回的操作
  如果 mode=rpa_checkpoint：图像匹配 + Agent-S3 验证完成情况
  如果 RPA 失败：       自动回退到 Agent-S3（自愈机制）

所有步骤完成后：Agent-S3 进行最终验证 -> 确认任务成功/失败

参数替换： 编译脚本可能包含可参数化变量（如 contact_name、message_text）。在命令行传入 --param_name value 或使用 --params '{...}' JSON 来覆盖默认值。可用参数列在编译 JSON 的 parameters 字段中。

生成文件

所有流水线输出存储在 Aloha_Act/trace_data/ 下：

文件	描述
`{trace_id}_trace.json`	VLM 标注的演示轨迹
`{trace_id}_merged.json`	合并轨迹（人类 + 智能体）
`{trace_id}_compiled.json`	编译后的混合脚本（可回放）

智能体执行日志和截图存储在 Aloha_Act/agent_runs/{task_id}/ 下。

演示展示

机票预订

Excel：矩阵转置

PowerPoint 批量背景编辑

GitHub 仓库编辑

快速开始

环境要求

Windows 10+ 或 macOS
Python 3.10+
至少一个 VLM API 密钥（OpenAI / Claude）

1. 克隆并安装

git clone https://github.com/showlab/CLAWS-UIS.git
cd CLAWS-UIS
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2. 配置 API 密钥和模型

系统使用两个 VLM 模型分别用于不同目的，可能需要不同的 API 密钥和端点。

第一步：创建 `.env` 文件

cp .env.example .env

第二步：编辑 `.env`

# VLM Planner —— 编译 / 定位器验证 / 轨迹合并
# 推荐：gemini-3-flash-preview（空间推理能力最佳，适合截图分析）
OPENAI_API_KEY=sk-your-planner-key-here
OPENAI_BASE_URL=https://next.aigc2d.com/v1
PLANNER_MODEL=gemini-3-flash-preview

# Agent-S3 执行引擎 —— 自主执行 / 截图理解
# 推荐：kimi-k2.5（对中文应用截图理解最好，如微信、钉钉等）
AGENTS3_API_KEY=sk-your-agents3-key-here
AGENTS3_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
AGENTS3_MODEL=kimi-k2.5

# Claude（可选）
CLAUDE_API_KEY=

变量	使用方	用途
`OPENAI_API_KEY`	VLM 编译、定位器验证、Agent-S3 回退	主 API 密钥（OpenAI 兼容）
`OPENAI_BASE_URL`	VLM 编译与定位器验证	API 代理端点（如 aigc2d 代理 Gemini）
`PLANNER_MODEL`	VLM 编译与定位器验证	模型名称（覆盖 config.yaml 中的 `planner_model`）
`AGENTS3_API_KEY`	Agent-S3 自主执行	Agent-S3 端点的独立密钥
`AGENTS3_BASE_URL`	Agent-S3 自主执行	Agent-S3 API 端点（覆盖 config.yaml 中的 `agents3.api_base`）
`AGENTS3_MODEL`	Agent-S3 自主执行	Agent-S3 模型名称（覆盖 config.yaml 中的 `agents3.model`）
`CLAUDE_API_KEY`	Claude 智能体后端（可选）	仅在使用 Claude 作为 actor 模型时需要

配置解析顺序： 所有入口脚本通过 python-dotenv 在启动时加载 .env。环境变量覆盖 config.yaml 的值。旧版 api_keys.json 文件仍作为后备方案。优先级：.env > config.yaml > api_keys.json。

轨迹生成的端点在 Aloha_Learn/config/llm_config.yaml 中单独设置：

openai:
  base_url: "https://coding.dashscope.aliyuncs.com/v1"   # DashScope 端点
  trace_generation:
    model: "kimi-k2.5"

3. 配置模型和操作系统

编辑 Aloha_Act/config/config.yaml：

# --- 编译和定位器验证模型 ---
# 用于：WorkflowCompiler, LocatorValidator, TrajectoryMerger
# 推荐：空间推理能力强的模型
planner_model: "gemini-3-flash-preview"

# --- 执行模型 (Agent-S3) ---
# 用于：Agent-S3 自主执行、截图理解
# 推荐：中文应用场景使用国产模型（如微信、钉钉等）
agents3:
  model: "kimi-k2.5"
  api_base: "https://coding.dashscope.aliyuncs.com/v1"
  api_key: ""   # 留空则使用 OPENAI_API_KEY，或设置独立密钥

os_name: "windows"   # 或 "mac"、"linux"

为什么使用两个模型？

角色	配置键	默认值	原因
编译与定位器验证	`planner_model`	`gemini-3-flash-preview`	坐标定位和空间推理能力更强
执行与标注	`agents3.model`	`kimi-k2.5`	对中文应用截图理解更好（微信等）

单模型配置： 只填 .env 中的 OPENAI_* 变量，AGENTS3_* 留空——Agent-S3 会自动使用 Planner 模型。所有任务均可正常工作，但如果仅使用 kimi-k2.5，RPA 工作流编译的坐标精度可能不如 Gemini（点击偏移风险更高）。有条件时建议使用双模型：Gemini 编译 + Kimi 执行。

4. 录制操作演示

Python 录制器 GUI（推荐）

python -m Aloha_Learn.recorder.recorder_gui

打开窗口后输入项目名称，点击 Start / Stop，即可查看录制时长、事件数量和输出文件路径。

其他方式：

方式	命令	说明
Python CLI	`python -m Aloha_Learn.recorder.recorder_app --project my_demo`	按 Ctrl+C 停止
独立应用	从 Releases 下载	`.exe`（Windows）/ `.dmg`（macOS）

架构概览

两大模块：

模块	职责
`Aloha_Learn`	录制并处理人类演示，生成结构化轨迹
`Aloha_Act`	使用学到的轨迹作为上下文示例执行任务

五条执行路径：

路径 1（引导执行）：
  录制 -> 解析 -> 轨迹 -> 规划器（轨迹引导） -> 执行器 -> 操作执行

路径 2（纯智能体）：
  任务 -> Agent-S3 自主执行 -> 完成

路径 3（智能体生成脚本）：
  任务 -> Agent-S3 自主执行 -> VLM 编译 -> 可复用混合脚本

路径 4（直接编译）：
  录制 -> 解析 -> 轨迹 -> VLM 编译 -> 可复用混合脚本

路径 5（脚本回放）：
  编译脚本 + 参数 -> RPA 图像匹配 / Agent-S3 回退 -> 完成

关键入口脚本（均在 Aloha_Act/scripts/ 下）：

脚本	用途
`hybrid_run.py`	混合执行引擎（RPA + 智能体，模式 1）
`pipeline_run.py`	智能体执行与编译（模式 2、3、4）
`workflow_run.py`	脚本回放与参数替换（模式 5）
`aloha_run.py`	旧版规划器-执行器流水线

轨迹格式

轨迹是 Aloha_Act/trace_data/ 下的 JSON 文件：

{
  "trajectory": [
    {
      "step_idx": 1,
      "caption": {
        "observation": "屏幕显示内容",
        "think": "用户意图推理",
        "action": "点击 X 按钮",
        "expectation": "预期结果"
      }
    }
  ]
}

OSWorld 基准测试

在全部 361 个 OSWorld 风格任务上评估
217 个任务端到端完成（严格二元指标）
支持 Windows 和 macOS

项目结构

CLAWS-UIS/
  Aloha_Learn/          # 录制与学习模块
    recorder/           # 屏幕 + 输入录制器
    parser.py           # 原始日志 -> 结构化轨迹流水线
    cli.py              # 主题到技能聚类 CLI
    projects/           # 录制的演示项目
  Aloha_Act/            # 执行模块
    scripts/            # 入口脚本（hybrid_run, pipeline_run 等）
    config/             # API 密钥与模型配置
    trace_data/         # 上下文学习的轨迹文件
    ui_aloha/
      act/              # 规划器 + 执行器逻辑
      execute/          # 操作系统级执行器（点击、输入、滚动等）
      hybrid/           # 混合执行引擎
  Agent-S/              # 备选智能体实现
  assets/               # 品牌素材、架构图、演示

致谢

CLAWS-UIS 建立在两个优秀项目的基础之上：

项目	贡献	论文
ShowUI	GUI 元素的视觉定位——实现截图理解和 UI 元素定位	arXiv:2411.17465
Agent-S	自主 GUI 智能体（S3）——提供截图分析、动作规划和自我反思的执行引擎	arXiv:2510.02250

感谢 ShowLab 和 Simular AI 团队在 GUI 理解与自主计算机操控领域的开拓性工作。

局限性

CLAWS-UIS 是一个仍在积极开发中的研究项目。以下列出当前已知的局限性，帮助合理设定期望：

1. 长工作流尚未充分验证

混合执行引擎（RPA + 智能体）主要在中短工作流（5-15 步）上测试。对于超长工作流（30+ 步，如多页表单填写、复杂多应用编排），累积误差率和上下文窗口压力可能降低可靠性。该领域仍在积极测试中。

2. 异常场景的恢复能力有限

虽然混合方法相比纯 RPA 改善了泛化能力——Agent-S3 可以处理轻微的 UI 变化、弹窗对话框和布局调整（这些会让传统图像匹配失败）——但其恢复能力仍然有限。对于高度意外的场景（系统级对话框、应用崩溃、网络中断、陌生错误消息），智能体可能无法恢复并完成任务。自愈回退机制有所帮助，但不能替代完整的错误处理。

3. 前沿模型未经测试

本项目尚未使用最新的前沿模型（如 GPT-5.4、Claude Opus 4.6、Gemini 3.1 等顶级模型）进行测试。使用这些模型很可能会显著提高执行准确性和编译质量。但 CLAWS-UIS 的设计理念是通过架构策略来最小化成本、降低对模型的依赖，而非依赖模型能力的暴力堆砌：

混合 RPA + 智能体：RPA 步骤使用零成本图像匹配；仅 Agent 步骤调用 VLM，显著降低每次回放的 API 成本
一次编译，多次回放：昂贵的 VLM 编译只进行一次；后续回放复用编译后的脚本
双模型架构：较小/便宜的模型（kimi-k2.5）处理执行，更强的模型（Gemini Flash）处理一次性编译
自愈回退：当 RPA 失败时，智能体自动接管，避免完全重新执行

这种方法牺牲峰值性能以换取实际可部署性——大多数工作流使用中端模型即可可靠运行，成本仅为顶级模型的一小部分。

4. 参数提取基于启发式方法

工作流编译器使用 VLM 启发式方法来识别可参数化变量（如联系人名、消息内容）。它可能遗漏某些参数或提取出不相关的参数。建议在生产使用前手动审查编译 JSON 的 parameters 字段。

Claude Code Skill

CLAWS-UIS 提供了一个 Claude Code 技能包，可将完整的项目工作流直接集成到你的 Claude Code 会话中。

安装

# 从项目根目录安装
claude install-skill skills/claws-uis

# 或从打包好的 .skill 文件安装
claude install-skill skills/dist/claws-uis.skill

使用方式

安装后，当你在 Claude Code 中提及以下任务时，技能会自动激活：

"录制一段演示并解析为轨迹"
"使用 Agent-S3 执行这个任务"
"将我的录制编译为可复用脚本"
"用不同参数回放工作流"
"配置 CLAWS-UIS 的 API 密钥"

技能提供快速决策树、命令参考、配置指南和问题排查提示，全部直接可在 Claude Code 上下文中使用。

引用

如果您觉得 CLAWS-UIS 有用，请引用我们的工作和上游项目：

@article{showui_aloha,
  title   = {CLAWS-UIS: Human-Taught GUI Agent},
  author  = {Zhang, Yichun and Guo, Xiangwu and Goh, Yauhong and Hu, Jessica
             and Chen, Zhiheng and Wang, Xin and Gao, Difei and Shou, Mike Zheng},
  journal = {arXiv:2601.07181},
  year    = {2026}
}

@article{showui,
  title   = {ShowUI: One Vision-Language-Action Model for GUI Visual Agent},
  author  = {Lin, Kevin Qinghong and Xu, Linjie and Gao, Difei and Shou, Mike Zheng and others},
  journal = {arXiv:2411.17465},
  year    = {2024}
}

@article{agent_s3,
  title   = {Agent S: An Open Agentic Framework that Uses Computers Like a Human},
  author  = {Agashe, Saaket and others},
  journal = {arXiv:2510.02250},
  year    = {2025}
}

许可证

Apache-2.0 许可证。

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
Agent-S		Agent-S
Aloha_Act		Aloha_Act
Aloha_Learn		Aloha_Learn
assets		assets
demo_videos/execution_demos		demo_videos/execution_demos
docs		docs
skills		skills
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

CLAWS-UIS -- 人类示教的计算机操控智能体

什么是 CLAWS-UIS？

五大核心模式

模式 1：录制 -> 学习 -> 执行

模式 2：纯智能体执行

模式 3：智能体执行 -> 生成脚本

模式 4：录制 -> 编译 -> 脚本

模式 5：脚本回放

生成文件

演示展示

快速开始

环境要求

1. 克隆并安装

2. 配置 API 密钥和模型

第一步：创建 `.env` 文件

第二步：编辑 `.env`

3. 配置模型和操作系统

4. 录制操作演示

架构概览

轨迹格式

OSWorld 基准测试

项目结构

致谢

局限性

Claude Code Skill

安装

使用方式

引用

许可证

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

CLAWS-UIS -- 人类示教的计算机操控智能体

什么是 CLAWS-UIS？

五大核心模式

模式 1：录制 -> 学习 -> 执行

模式 2：纯智能体执行

模式 3：智能体执行 -> 生成脚本

模式 4：录制 -> 编译 -> 脚本

模式 5：脚本回放

生成文件

演示展示

快速开始

环境要求

1. 克隆并安装

2. 配置 API 密钥和模型

第一步：创建 .env 文件

第二步：编辑 .env

3. 配置模型和操作系统

4. 录制操作演示

架构概览

轨迹格式

OSWorld 基准测试

项目结构

致谢

局限性

Claude Code Skill

安装

使用方式

引用

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

第一步：创建 `.env` 文件

第二步：编辑 `.env`