# GUI-QA-Agent

**Repository Path**: sg-first/gui-qa-agent

## Basic Information

- **Project Name**: GUI-QA-Agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# desktop-agent-tools

三个独立的桌面 Agent 工具，可单独使用也可管道组合。

**跨平台支持**：Windows / Linux / macOS，纯 Python 实现。

## 前置依赖

### 1. 安装 Python 3
```bash
# Windows: 下载安装 https://www.python.org/downloads/
# 安装时勾选 "Add Python to PATH"

# macOS
brew install python3

# Ubuntu / Debian
sudo apt install python3 python3-pip
```

### 2. 安装 Python 依赖
```bash
cd desktop-agent-tools
pip install -r requirements.txt
```

## 工具概览

| 文件 | 功能 | 输入 | 输出 |
|------|------|------|------|
| `screenshot.py` | 桌面截图 (mss + Pillow) | 无 | PNG 文件 + 可选 base64 |
| `decide.py` | LLM 视觉决策 | 截图 + 指令 | JSON 动作 |
| `act.py` | 模拟操作执行 (pyautogui) | JSON 动作 | JSON 结果 |

## 配置 API 密钥

```bash
# Windows PowerShell
$env:OPENAI_API_KEY="sk-xxx"
$env:OPENAI_BASE_URL="https://your-api.com/v1"
$env:DECIDE_MODEL="gpt-4o"

# Linux / macOS
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://your-api.com/v1"
export DECIDE_MODEL="gpt-4o"
```

## 快速开始

```bash
# 1. 截图
python screenshot.py --output shot.png

# 2. 决策
python decide.py --screenshot shot.png --instruction "点击登录按钮"

# 3. 执行
python act.py --action '{"type":"click","x":500,"y":300}'
```

## 管道组合

```bash
# 三步管道：截图 → 思考 → 操作
python screenshot.py --output shot.png
python decide.py --screenshot shot.png --instruction "打开浏览器" > action.json
python act.py --action "$(cat action.json)"
```

## 完整循环脚本 (Windows PowerShell)

```powershell
$INSTRUCTION = "打开浏览器，搜索 hello world"
$MAX_STEPS = 20

for ($step = 1; $step -le $MAX_STEPS; $step++) {
    Write-Host "=== Step $step ==="

    python screenshot.py --output "shot-$step.png"

    $OUTPUT = python decide.py --screenshot "shot-$step.png" --instruction $INSTRUCTION 2>$null
    if ($LASTEXITCODE -eq 2 -or $LASTEXITCODE -eq 3) { Write-Host "任务完成"; break }

    if ($OUTPUT) { python act.py --action $OUTPUT }
}
```

## 完整循环脚本 (Linux/macOS)

```bash
#!/bin/bash
INSTRUCTION="打开浏览器，搜索 hello world"
MAX_STEPS=20

for step in $(seq 1 $MAX_STEPS); do
  echo "=== Step $step ==="

  python screenshot.py --output "shot-$step.png"

  OUTPUT=$(python decide.py --screenshot "shot-$step.png" --instruction "$INSTRUCTION" 2>/dev/null)
  EXIT=$?
  if [ $EXIT -eq 2 ] || [ $EXIT -eq 3 ]; then echo "任务结束"; break; fi
  if [ $OUTPUT ]; then python act.py --action "$OUTPUT"; fi
done
```

## act.py 支持的动作类型

| type | 参数 | 说明 |
|------|------|------|
| `click` | `x`, `y` | 移动鼠标并单击 |
| `double_click` | `x`, `y` | 移动鼠标并双击 |
| `type` | `text` | 输入文本 |
| `key` | `key` | 按键组合 (如 `ctrl+l`, `Return`) |
| `scroll` | `direction`, `amount`, `x?`, `y?` | 滚轮滚动 |
| `drag` | `x`, `y`, `toX`, `toY` | 拖拽 |
| `move` | `x`, `y` | 移动鼠标 |
| `wait` | `ms` | 等待毫秒 |

## 环境变量

| 变量 | 工具 | 说明 |
|------|------|------|
| `OPENAI_API_KEY` | decide | API 密钥 |
| `OPENAI_BASE_URL` | decide | 自定义 API 端点 |
| `DECIDE_MODEL` | decide | 默认模型 (默认 `gpt-4o`) |