Screenclaw

通过 screenclaw 获取带坐标网格的截图，读出图上的坐标数字，再调用点击、输入、按键等 API 控制软件，模拟人类视觉交互。 当符合以下场景时使用此技能： - 需要视觉操作软件 - 用户目标需要通过截图理解界面、读取元素坐标或验证 UI 状态 - Playwright、CLI、应用专用 API 无法覆盖，例如隐藏按钮、游戏、验证码、任意普通桌面软件 - 用户要求自动操作一个没有专用技能的软件 - 需要操作桌面元素、跨进程跨窗口操作（桌面图标、任务栏、文件上传等）

核心规则

1. 坐标必须来自 ScreenClaw 截图上的 XxY 网格交叉点，不能用内部视觉坐标或凭感觉推测。
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. 失败先回到截图：操作失败、结果不符合预期、连续微调无效时，先重新截图、裁剪、读文档和参数，不要继续猜坐标或重复点击。

入口决策

理解目标 → 检索场景模板 → (命中模板→模板执行模式 | 未命中模板→通用工作循环)
通用工作循环：判断场景 → 初始化 → 定位目标 → 截图与读坐标 → 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 失败（服务未运行）：
  • 检查 references/config.md 中是否记录了安装目录，且目录下存在 screenclaw.exe。
  • 如果没有安装目录或 exe 不存在：从 https://github.com/GinSing1226/ScreenClaw/releases 下载最新版 zip，询问用户解压目标目录，解压后将安装目录写入 references/config.md 的 screenclaw_install_dir 字段。
  • 启动安装目录下的 screenclaw.exe，等待几秒后重试 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 时必须更新当前计划或下一步动作。

坐标概念

截图上的坐标格式为 XxY，例如 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

脚本降级

降级路径：

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 生成录制窗口组预处理表