screenclaw

核心规则

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