claws-uis

name	claws-uis
description	CLAWS-UIS：人类示教的计算机操控智能体，支持 Windows 和 macOS。适用场景：(1) 录制人类操作演示（屏幕 + 鼠标 + 键盘），(2) 解析录制内容为语义化操作轨迹，(3) 基于学习到的轨迹执行 GUI 自动化任务，(4) 将工作流编译为可复用的混合 RPA+Agent 脚本，(5) 回放编译脚本并支持参数替换，(6) 配置双模型 API（Gemini + Kimi），(7) 涉及桌面自动化、GUI 智能体、录屏、轨迹学习或工作流编译的任何任务。触发关键词：录制演示、解析轨迹、运行智能体、编译工作流、回放脚本、CLAWS、Aloha、GUI 自动化、计算机操控智能体、RPA。

CLAWS-UIS

人类示教的计算机操控智能体。录制一次，永久执行。

快速决策树

你想做什么？
├─ 录制一段演示             → 下方"录制工作流"
├─ 执行任务（有演示）        → 模式 1：hybrid_run.py
├─ 执行任务（无演示）        → 模式 2：pipeline_run.py --mode agent-execute
├─ 执行任务 + 生成脚本       → 模式 3：pipeline_run.py --mode agent-only
├─ 将演示编译为脚本          → 模式 4：pipeline_run.py --mode compile-only
├─ 回放已编译的脚本          → 模式 5：workflow_run.py
├─ 配置 API 密钥            → "配置"章节
└─ 了解架构                 → 参见 references/architecture.md

录制工作流

# GUI 录制器（推荐）
python -m Aloha_Learn.recorder.recorder_gui

# CLI 替代方式
python -m Aloha_Learn.recorder.recorder_app --project 项目名

# 解析录制内容为轨迹
cd Aloha_Learn && python parser.py 项目名

# 将轨迹复制到执行目录
cp projects/项目名/项目名_trace.json ../Aloha_Act/trace_data/

执行工作流

五种模式——根据输入和期望输出选择：

模式 1：引导执行（有演示 + 新任务）

cd Aloha_Act
python scripts/hybrid_run.py --task "任务描述" --trace-id 轨迹名

模式 2：纯智能体执行（仅任务，无脚本输出）

cd Aloha_Act
python scripts/pipeline_run.py --mode agent-execute --task "任务描述"

模式 3：智能体 + 编译脚本（仅任务 -> 可复用脚本）

cd Aloha_Act
python scripts/pipeline_run.py --mode agent-only --task "任务描述"

模式 4：演示 -> 编译脚本（演示 -> 可复用脚本）

cd Aloha_Act
python scripts/pipeline_run.py --mode compile-only --trace-id 轨迹名

模式 5：脚本回放（编译脚本 + 参数）

cd Aloha_Act
python scripts/workflow_run.py --trace-id 轨迹名
python scripts/workflow_run.py 轨迹名 --参数名 参数值
python scripts/workflow_run.py --trace-id 轨迹名 --params '{"键":"值"}'

配置

环境搭建

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

API 密钥（.env）

将 .env.example 复制为 .env。推荐双模型配置：

变量	用途
OPENAI_API_KEY	VLM 编译、定位器验证
OPENAI_BASE_URL	API 代理端点（如 aigc2d 代理 Gemini）
PLANNER_MODEL	编译模型（默认：gemini-3-flash-preview）
AGENTS3_API_KEY	Agent-S3 执行引擎
AGENTS3_BASE_URL	Agent-S3 端点（如 DashScope）
AGENTS3_MODEL	执行模型（默认：kimi-k2.5）
CLAUDE_API_KEY	可选，仅在使用 Claude 作为 actor 后端时需要

优先级：.env > config.yaml > api_keys.json

单模型模式：只填 OPENAI_*，AGENTS3_* 留空即可。

模型配置（Aloha_Act/config/config.yaml）

planner_model: "gemini-3-flash-preview"   # 编译 + 定位器验证
agents3:
  model: "kimi-k2.5"                      # 执行 + 截图理解
  api_base: "https://coding.dashscope.aliyuncs.com/v1"
  api_key: ""
os_name: "windows"                         # 或 "mac"、"linux"

核心概念

• 轨迹（Trace）：记录每步 observation/think/action/expectation 的 JSON 文件
• 编译脚本（Compiled Script）：混合 RPA+Agent 脚本。RPA 步骤使用图像匹配（零 VLM 成本），Agent 步骤调用 VLM
• 自愈机制（Self-healing）：RPA 图像匹配失败时，自动回退到 Agent-S3
• 参数（Parameters）：编译脚本可包含可参数化变量（contact_name、message_text 等）

文件位置

路径	内容
Aloha_Learn/projects/{name}/	录制的演示项目
Aloha_Act/trace_data/	轨迹和编译脚本
Aloha_Act/agent_runs/{id}/	智能体执行日志 + 截图
Aloha_Act/config/config.yaml	模型和系统配置
.env	API 密钥（项目根目录）

常见问题排查

• API 密钥错误：检查项目根目录的 .env 文件
• 找不到轨迹：确认文件存在于 trace_data/（自动解析 {name}.json 或 {name}_trace.json）
• 坐标偏移：确认 selected_screen 与物理显示器布局匹配
• 解析器失败：确保 inputs/ 下恰好有一个日志文件 + 一个视频文件

参考资料

• 架构详解：参见 references/architecture.md，包含模块结构、执行路径、坐标系统和操作格式
• 模式对比：参见 references/modes.md，包含详细的模式选择指南及优缺点分析