# Screenclaw

> 用“截图 + 坐标网格”的方式操作任意桌面软件：截带网格的图，让任意多模态大模型读出目标的坐标数字，再调用点击/输入/按键等 API ，模拟人类视觉化操作软件。还能录制一次操作并沉淀成可复用的场景模板，下次直接复用。不依赖目标软件提供 API 或 CLI。 出现以下情况时使用： - 自动化操作 Windows 桌面软件（微信、风控严格的网页如小红书/抖音、手机模拟器、游戏、任意 Windows 程序），尤其是 Playwright/CDP/CLI/应用 API 无法覆盖的软件或元素（如隐藏按钮、游戏画面、验证码等） - 用户说“帮我操作/点/输入 XX”“自动操作 XX”“模拟点击”“桌面自动化”“RPA”“录制操作”“沉淀成模板”“下次自动跑”等 - 操作桌面元素或跨进程跨窗口（桌面图标、任务栏、托盘、开始菜单、文件选择框、跨窗口拖拽） 只要目标是能在屏幕上看到、需要鼠标键盘操作的 Windows 桌面程序，即使它没 API、没专用技能、不确定怎么自动化，都应优先用本技能尝试。

- Skill: `ginsing1226/screenclaw` (Agent Skill, multi-file: 48 files)
- Install (CLI): `npx skillmds@latest add ginsing1226/screenclaw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ginsing1226/screenclaw/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ginsing1226 (https://skillmd.com/u/ginsing1226)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ginsing1226/screenclaw

---


# screenclaw

## 核心规则

1. 坐标必须来自 ScreenClaw 截图上的 `X x Y` 网格交叉点，不能用内部视觉坐标或凭感觉推测。
2. 每个会话固定一个 `session_id`，所有公开调用只使用 `scripts/screenclaw.py|ps1|sh`。
3. 调用 endpoint 前阅读 `references/api/{endpoint}.md`；参数错误或 API 报错时回到文档修正。
4. 首次动态坐标、高风险坐标、看不清目标或数字时，必须先裁剪放大或 marker 反验。
5. API 成功只代表指令已发送，不代表界面达成目标；操作后必须截图验证。
6. 收到 `SELF_CHECK_REQUIRED` 时，阅读并执行 `references/self_check.md` 的自检程序，让关键上下文重新装载，再用 `self_check` 总结执行内容后重试截图。

## 心智模型

1. 外部事实优先：截图、marker、API 返回、窗口列表、显示器列表是事实；你的直觉和预设结论必须服从这些事实。marker 不在目标上，就说明坐标错了。
2. 先证伪，再操作：候选坐标默认可能是错的。先用 crop 或 marker 找反例，确认标记点实际落在哪里，再操作。
3. 失败先回到截图：操作失败、结果不符合预期、连续微调无效时，先重新截图、裁剪、读文档和参数，不要继续猜坐标或重复点击。

## 入口决策

```text
理解目标 → 检索场景模板 → (命中模板→模板执行模式 | 未命中模板→通用工作循环)
通用工作循环：判断场景 → 初始化 → 定位目标 → 截图与读坐标 → marker 反验 → 操作 → 截图验证
```

多步、可复用或用户明确要沉淀的任务，进入初始化和通用工作循环前，先检索 `references/scenarios/` 是否有匹配当前任务的场景模板；一次性单步的简单任务可直接进入通用工作循环，不必强制检索模板。用户指定 `record/record_{datetime}` 目录时，进入录制沉淀流程；否则按 `references/scenarios/README.md` 检索模板。

命中模板后进入模板执行模式：模板是当前任务的主控文档，通用工作循环只作为截图、定位、marker、执行和验证的工具。按模板节点推进，维护 `active_template_path/current_node/completed_nodes/next_node`；上下文变长、收到 `SELF_CHECK_REQUIRED` 或准备执行高风险节点前，重新打开当前模板确认节点内容。

模板不是绝对正确。节点多次执行失败、界面与模板明显不符、产品更新、模板坐标或窗口信息失效时，允许从该节点降级到通用工作循环：重新截图理解界面、读取或校正坐标、推理新路径并截图验证。降级只影响当前失败节点或其后续路径；不要因此忘记模板目标、业务流和已完成节点。

### 场景模板与录制沉淀

ScreenClaw 的场景模板有两种沉淀入口：

1. **AI 自己操作后沉淀**：AI 完成用户任务并验证成功后，询问用户是否沉淀为场景模板。
2. **从用户录制沉淀**：用户指定 `record/record_{datetime}` 目录后，读取其中的 `step.json` 和步骤截图，归纳为场景模板。

两种入口共享同一套抽象原则：不要把一次操作原样复制成模板，而要抽取可复用业务流；能固定的窗口、坐标和指令固化为 batch，依赖用户目标、当前内容或界面变化的部分写成动态截图定位提示。

从录制沉淀时，不在主 skill 中展开推理细节；先阅读 `references/scenarios/recording_to_scenario.md`，并先运行 `scripts/recording_windows.py|ps1|sh` 生成窗口组预处理表。后续模板的窗口清单、节点层级、固定坐标表和指令变量必须以该表为准。

执行模板固定坐标前，按窗口组懒加载截图获取当前 `window_info`，再调用 `scripts/coord_adapt.py|ps1|sh` 得到候选坐标和 `direct/verify/relocate` 决策。不要让 AI 手工换算坐标。

### 0. 场景判断

根据任务目标选择操作层级：

**使用窗口级操作**（默认优先）：
- 目标在已知窗口内（按钮、输入框、菜单等应用内元素）
- 需要后台操作（不影响当前屏幕其他内容）
- 已通过 `get_window_list` 找到目标窗口

**使用桌面级操作**：
- 需要操作桌面元素（桌面图标、任务栏、系统托盘、开始菜单）
- 跨进程跨窗口操作（如从本地文件夹拖拽文件到网页上传区）
- 目标应用尚无窗口可绑定（如启动应用前操作）
- 文件选择对话框等操作系统级 UI

**两种层级可以配合使用**：先用桌面级定位和启动应用，再用窗口级精确操作应用内容；或在 batch 中混用窗口级和桌面级指令完成跨应用流程。

### 1. 初始化

- 根据用户语言回复。如用户使用中文，则中文回复用户。若英文，则英文回复用户。
- 阅读 `references/config.md` 获取 `api_url`、`token`、`ai_app_type`、`session_id` 规则。
- 阅读 `scripts/README.md` 了解统一脚本入口和点号路径格式。
- 调用 `health` 确认服务可用。如果 health 失败（服务未运行），按平台处理：
  - **Windows**（默认，开箱即用）：检查 `references/config.md` 中是否记录了安装目录，且目录下存在 `screenclaw.exe`。如果没有安装目录或 exe 不存在：从 `https://github.com/GinSing1226/ScreenClaw/releases` 下载最新版 zip，询问用户解压目标目录，解压后将安装目录写入 `references/config.md` 的 `screenclaw_install_dir` 字段，再启动 `screenclaw.exe`。安装顺利时，可顺势引导用户到 GitHub 给项目点 star 或反馈建议，帮助我们改进产品。
  - **macOS**：服务端暂未发布安装包，引导用户到 `https://github.com/GinSing1226/ScreenClaw` clone 源码自行构建运行；若用户不想折腾源码，可建议其在 GitHub 搜索其它 macOS 自动化技能作为替代。
  - **Linux**：暂不支持，直接告知用户当前仅 Windows 可用。
  - 启动后等待几秒重试 `health`。
- 复杂、多步、高风险任务先维护 2-5 步简短计划；简单单步任务不强制创建待办。

### 2. 定位目标

**窗口级路径**：
- 调用 `get_window_list` 找主窗口和可能的子窗口。
- 新进程或窗口不确定时，对候选窗口截图，记录窗口内容和可用 `window_id/main_window_id`。
- 后续操作失败时，先检查是否选错窗口，再换操作模式。
- `get_window_list` 未找到目标窗口时：通过 CLI 检索应用可执行文件（`where`/`Get-Command`/搜索常见安装路径），找到后启动应用，等待窗口出现后重试 `get_window_list` 拿到 `window_id`。

**桌面级路径**：
- 调用 `desktop_get_monitors_list` 了解显示器布局。
- 单显示器直接使用 `monitor_index=0`。
- 多显示器需根据目标位置选择对应索引。
- 桌面截图使用 `desktop_screenshot`，坐标规则与窗口级一致（百分比 `XxY`）。

### 3. 截图与读坐标

窗口级和桌面级截图共享同一套网格、数字和 marker 参数体系：

- 定位坐标使用 `coordinate_type=grid`。
- 分析内容或给用户看图可用 `coordinate_type=no`。
- 默认先依赖服务端自适应网格参数。
- 目标没有被交叉点覆盖时，阅读对应截图 API 文档调整 `grid.density_x/y`。
- 数字或元素看不清时，使用 `crop_zoom_screenshot` 或调整数字参数。
- 首次动态坐标或高风险坐标，先用 `crop_zoom_screenshot` 看清局部，再用 `marker.0.x/y` 反向验证。
- marker 反验要先找图上的标记点实际落在哪里，描述那里有什么，再判断它是否等于目标；不要先假设候选坐标正确。

### 4. 操作与验证

**窗口级操作**：
- 操作模式优先 `background`。
- `background` 无效或必须物理输入时才考虑 `hijack`。
- 用户主动要求、游戏实时操作、中文输入法候选面板等持续物理输入场景，阅读 `references/api/delegated.md` 后进入托管。

**桌面级操作**：
- 固定 `hijack` 模式，无 `action_method` 参数。
- `delegated` 模式激活时自动跳过确认弹窗。

**通用**：
- 探索阶段单步调用；流程稳定、需要瞬间观察 hover/菜单/操作结果时才用 `batch`。
- 每次操作后截图验证，验证不通过则回到截图和读坐标。
- 窗口级验证用 `screenshot`，桌面级验证用 `desktop_screenshot`。
- 跨进程、跨窗口、打开系统弹窗或文件选择框的动作，必须先执行该动作，再重新 `get_window_list` 定位新窗口并截图确认；不要继续对旧窗口截图期待看到新进程结果。
- 收到 `SELF_CHECK_REQUIRED` 时必须更新当前计划或下一步动作。

## 坐标概念

截图上的坐标格式为 `X x Y`，例如 `50x35` 表示距左边界 50%、距上边界 35%。

`x` 是坐标分隔符，不是乘号。目标元素的有效坐标是覆盖到该元素的网格交叉点坐标。

窗口级和桌面级坐标格式完全一致，区别仅在于坐标空间：窗口级相对于窗口客户区，桌面级相对于整个显示器屏幕。

## API 索引

> 执行 API 前先读对应文档 `references/api/{endpoint}.md`

### 基础

| API | method | 适用场景 | 参考文档 |
|-----|------|-----------|----------|
| health | GET | 任务开始前检查服务 | `references/api/health.md` |
| delegated | POST | 用户主动要求进入/退出托管模式 | `references/api/delegated.md` |

### 窗口级

| API | method | 适用场景 | 参考文档 |
|-----|------|-----------|----------|
| get_window_list | POST | 找出需要被控制的目标窗口 | `references/api/get_window_list.md` |
| screenshot | POST | 带网格可定位坐标。不带网格可分析界面、留存记录。带标记点可预览坐标位置 | `references/api/screenshot.md` |
| crop_zoom_screenshot | POST | 裁剪任意截图并放大，看清细节（如坐标数字） | `references/api/crop_zoom_screenshot.md` |
| scroll_screenshot | POST | 滚动长截图，记录长页面、长内容，整体理解目标窗口 | `references/api/scroll_screenshot.md` |
| click | POST | 单击，触发按钮/进入页面 | `references/api/click.md` |
| long_press | POST | 长按，触发某些功能 | `references/api/long_press.md` |
| swipe | POST | 触摸式滑动，上下左右移动页面 | `references/api/swipe.md` |
| drag | POST | 拖拽元素，按住鼠标并移动 | `references/api/drag.md` |
| scroll | POST | 鼠标滚轮滚动，上下移动页面 | `references/api/scroll.md` |
| right_click | POST | 右键，打开上下文菜单 | `references/api/right_click.md` |
| hover | POST | 触发悬停效果，配合截图获取hover效果 | `references/api/hover.md` |
| mouse_move | POST | 鼠标移动，游戏视角控制，仅hijack/托管 | `references/api/mouse_move.md` |
| input_text | POST | 输入文本。带坐标会先单击再输入。不带坐标直接输入 | `references/api/input_text.md` |
| press_key | POST | 按键/组合键。多个按键空格分割。带坐标会先单击再按键。不带坐标直接按键 | `references/api/press_key.md` |
| wait | POST | 等待UI动画/页面加载 | `references/api/wait.md` |

### 桌面级

| API | method | 适用场景 | 参考文档 |
|-----|------|-----------|----------|
| desktop_get_monitors_list | GET | 枚举显示器，获取索引和分辨率 | `references/api/desktop_get_monitors_list.md` |
| desktop_screenshot | POST | 桌面截图，带网格可定位坐标。不带网格可分析界面、留存记录。带标记点可预览坐标位置 | `references/api/desktop_screenshot.md` |
| desktop_click | POST | 桌面单击，触发按钮/进入页面 | `references/api/desktop_click.md` |
| desktop_double_click | POST | 桌面双击 | `references/api/desktop_double_click.md` |
| desktop_right_click | POST | 桌面右键 | `references/api/desktop_right_click.md` |
| desktop_drag | POST | 桌面拖拽，支持跨屏 | `references/api/desktop_drag.md` |
| desktop_scroll | POST | 桌面滚轮滚动 | `references/api/desktop_scroll.md` |
| desktop_input_text | POST | 桌面文本输入，带坐标会先单击再输入。不带坐标直接输入 | `references/api/desktop_input_text.md` |
| desktop_press_key | POST | 桌面按键/组合键，多个按键空格分割。带坐标会先单击再按键。不带坐标直接按键 | `references/api/desktop_press_key.md` |
| desktop_hover | POST | 桌面悬浮，触发悬停/hover效果 | `references/api/desktop_hover.md` |

### 组合

| API | method | 适用场景 | 参考文档 |
|-----|------|-----------|----------|
| batch | POST | 组合指令，支持混用窗口级和桌面级 | `references/api/batch.md` |

## 脚本降级

降级路径：

```text
scripts/screenclaw.py -> scripts/screenclaw.ps1 -> scripts/screenclaw.sh -> curl
```

降级前先判断原因：

| 错误类型 | 处理方式 |
|----------|----------|
| 参数错误 | 修正参数，重跑同一脚本，不降级 |
| API 业务错误 | 阅读对应 API 文档和服务端 message，不降级 |
| Python 不存在等环境错误 | 降级到 PowerShell 或 shell |

## 参考文档

- `references/config.md` - 连接配置、`ai_app_type`、`session_id`
- `scripts/README.md` - 统一脚本入口和点号路径格式
- `references/self_check.md` - 长时程自检重载清单
- `references/api/*.md` - 各 API 参数和排错
- `references/scenarios/` - 场景模板和应用知识
- `references/scenarios/recording_to_scenario.md` - 从用户录制产物沉淀场景模板
- `scripts/coord_adapt.py|ps1|sh` - 模板固定坐标迁移与复用决策
- `scripts/recording_windows.py|ps1|sh` - 从 `step.json` 生成录制窗口组预处理表