# Gui Support

> 提供屏幕截图网格标注和鼠标点击功能，用于VLM模型精确操作图形界面。#高风险操作警告# 任务开始前必须评估风险并获得用户授权，执行过程中无需再次确认。

- Skill: `4xiaxia/gui-support` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add 4xiaxia/gui-support`
- Raw SKILL.md: https://api.skillmd.com/api/skills/4xiaxia/gui-support/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 4xiaxia (https://skillmd.com/u/4xiaxia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/4xiaxia/gui-support

---


# 屏幕截图网格标注技能

## 功能概述

本技能集成了屏幕截图网格标注工具和鼠标点击工具，专为 VLM（视觉语言模型）设计，帮助 AI 模型通过网格坐标精确定位屏幕上的元素，并执行鼠标点击操作。按照使用流程中的步骤执行以准确操作图形界面. 

## 核心工具

### 1. 网格标注工具

本技能提供两个独立的网格标注工具，分别用于全屏截图和区域截图：

#### 1.1 完整截图工具 (grid_full.py)

**功能：**
- 全屏截图并添加网格和坐标标注
- 自适应网格参数计算
- 对比度网格线（自动选择黑/白对比色）

**使用场景：**
- 需要 VLM 模型识别屏幕元素大致位置时
- 分析整体界面布局时



#### 1.2 区域截图工具 (grid_region.py)

**功能：**
- 以指定中心点截取屏幕 1/5 大小的区域
- 支持自动放大小区域
- 绝对坐标标注
- 对比度网格线

**使用场景：**
- 精确定位界面控件坐标时
- 需要放大查看细节时

**可用参数：**
```
python grid_region.py cx,cy
```

| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `cx,cy` | - | 中心点坐标（必需） | `100,200` 或 `(100, 200)` |

**注意：** 中心点坐标格式支持 `x,y`、`x y` 或 `(x, y)`

### 2. 坐标点击工具 (click_tool.py)

**功能：**
- 在指定坐标执行鼠标点击
- 支持单击、双击、右键点击
- 鼠标平滑移动到目标位置后点击
- 获取当前鼠标位置

**使用场景：**
- VLM 模型已识别目标坐标后
- 需要自动化执行界面操作时
- 验证坐标准确性时

**可用参数：**
```
python click_tool.py [-h] [-c CLICKS] [-i INTERVAL] [-b {left,right,middle}] [-d DURATION] [-p] [x] [y]
```

| 参数 | 简写 | 说明 | 默认值 | 示例 |
|------|------|------|--------|------|
| `x` | - | 屏幕 X 坐标 | - | `100` |
| `y` | - | 屏幕 Y 坐标 | - | `200` |
| `--clicks` | `-c` | 点击次数 | `1` | `-c 2` (双击) |
| `--interval` | `-i` | 多次点击间隔（秒） | `0.0` | `-i 0.5` |
| `--button` | `-b` | 鼠标按钮（left/right/middle） | `left` | `-b right` (右键) |
| `--duration` | `-d` | 鼠标移动时间（秒） | `0.5` | `-d 1.0` |
| `--position` | `-p` | 获取当前鼠标位置 | - | `-p` |
| `--help` | `-h` | 显示帮助信息 | - | `-h` |

**常用示例：**
```bash
# 单击坐标 (100, 200)
python click_tool.py 100 200

# 双击
python click_tool.py 500 300 -c 2

# 右键点击
python click_tool.py 800 600 -b right

# 点击 3 次，间隔 0.5 秒
python click_tool.py 100 200 -c 3 -i 0.5

# 移动 1 秒后点击
python click_tool.py 100 200 -d 1.0

# 获取当前鼠标位置
python click_tool.py --position
```

## 高风险操作警告

⚠️ **重要警告：** 本技能执行的操作具有高风险性，可能导致意外的系统行为或数据丢失。

**必须遵循以下规则：**

1. **任务前风险评估与授权：** 在开始任务前，必须评估操作可能带来的风险并获得用户明确授权，包括：
   - 意外修改系统设置
   - 错误删除文件
   - 干扰正在进行的工作
   - 触发意外的程序行为
2. **坐标验证：** 确保 VLM 模型识别的坐标准确无误
3. **执行过程：** 获得授权后，按既定方案执行，中途无需再次确认

## 使用流程

### 标准工作流（四步法）

> **注意**：所有工具文件与 SKILL.md 位于同一目录下。

1. **粗定位**：全屏截图，VLM 识别目标大致位置
   ```bash
   python grid_full.py
   ```

2. **精定位**：区域截图，VLM 获取精确坐标
   ```bash
   python grid_region.py cx,cy
   ```
   
   参数说明：
   - `cx,cy`：中心点坐标，工具会自动截取以该点为中心、屏幕 1/5 大小的矩形区域

3. **执行操作**：在精确坐标执行鼠标点击
   ```bash
   python click_tool.py x y
   ```

4. **验证结果**：操作后全屏截图，验证操作是否成功
   ```bash
   python grid_full.py
   ```

## 配置说明

### 配置文件 (grid_tool_config.json)

配置文件存储默认输出路径：

```json
{
  "default_output_path": "C:\\Users\\MLTZ\\Desktop\\程序\\temp_ai"
}
```

**设置默认输出路径（完整截图工具）：**
```bash
python grid_full.py --set-default-output "C:\path\to\output\folder"
```

**设置默认输出路径（区域截图工具）：**
```bash
python grid_region.py 0,0 --set-default-output "C:\path\to\output\folder"
```



## 注意事项

1. **Windows 专用**：截图功能使用 Windows API，仅支持 Windows 系统
2. **权限要求**：可能需要管理员权限才能执行某些操作
3. **DPI 感知**：工具会自动设置 DPI 感知以获取正确的屏幕分辨率
4. **字体支持**：网格标注会自动尝试系统中文字体
5. **输出管理**：定期清理生成的截图文件

## 紧急情况处理

如果执行操作后出现意外情况：

1. **立即停止**：停止任何正在执行的操作
2. **用户通知**：立即告知用户发生的情况
3. **系统检查**：检查系统状态是否正常
4. **回滚操作**：执行必要的回滚步骤
5. **记录问题**：记录问题详情，便于后续分析

## 工具文件列表

- `grid_common.py` - 公共模块（配置、图像处理核心函数）
- `grid_full.py` - 完整截图工具
- `grid_region.py` - 区域截图工具
- `click_tool.py` - 坐标点击工具
- `grid_tool_config.json` - 配置文件
- `SKILL.md` - 技能说明文档

---

⚠️ **再次强调：** 本技能仅在用户明确要求且取得同意后使用，任务开始前必须评估风险并获得授权，执行过程中无需再次确认。