\r \r

screenclaw\r

\r

核心规则\r

\r

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

心智模型\r

\r

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

入口决策\r

\r

理解目标 → 检索场景模板 → (命中模板→模板执行模式 | 未命中模板→通用工作循环)\r
通用工作循环：判断场景 → 初始化 → 定位目标 → 截图与读坐标 → marker 反验 → 操作 → 截图验证\r
```\r
\r
任何普通视觉操作任务，进入初始化和通用工作循环前，必须先检索 `references/scenarios/` 是否有匹配当前任务的场景模板。用户指定 `record/record_{datetime}` 目录时，进入录制沉淀流程；否则按 `references/scenarios/README.md` 检索模板。\r
\r
命中模板后进入模板执行模式：模板是当前任务的主控文档，通用工作循环只作为截图、定位、marker、执行和验证的工具。按模板节点推进，维护 `active_template_path/current_node/completed_nodes/next_node`；上下文变长、收到 `SELF_CHECK_REQUIRED` 或准备执行高风险节点前，重新打开当前模板确认节点内容。\r
\r
模板不是绝对正确。节点多次执行失败、界面与模板明显不符、产品更新、模板坐标或窗口信息失效时，允许从该节点降级到通用工作循环：重新截图理解界面、读取或校正坐标、推理新路径并截图验证。降级只影响当前失败节点或其后续路径；不要因此忘记模板目标、业务流和已完成节点。\r
\r
### 场景模板与录制沉淀\r
\r
ScreenClaw 的场景模板有两种沉淀入口：\r
\r
1. **AI 自己操作后沉淀**：AI 完成用户任务并验证成功后，询问用户是否沉淀为场景模板。\r
2. **从用户录制沉淀**：用户指定 `record/record_{datetime}` 目录后，读取其中的 `step.json` 和步骤截图，归纳为场景模板。\r
\r
两种入口共享同一套抽象原则：不要把一次操作原样复制成模板，而要抽取可复用业务流；能固定的窗口、坐标和指令固化为 batch，依赖用户目标、当前内容或界面变化的部分写成动态截图定位提示。\r
\r
从录制沉淀时，不在主 skill 中展开推理细节；先阅读 `references/scenarios/recording_to_scenario.md`，并先运行 `scripts/recording_windows.py|ps1|sh` 生成窗口组预处理表。后续模板的窗口清单、节点层级、固定坐标表和指令变量必须以该表为准。\r
\r
执行模板固定坐标前，按窗口组懒加载截图获取当前 `window_info`，再调用 `scripts/coord_adapt.py|ps1|sh` 得到候选坐标和 `direct/verify/relocate` 决策。不要让 AI 手工换算坐标。\r
\r
### 0. 场景判断\r
\r
根据任务目标选择操作层级：\r
\r
**使用窗口级操作**（默认优先）：\r
- 目标在已知窗口内（按钮、输入框、菜单等应用内元素）\r
- 需要后台操作（不影响当前屏幕其他内容）\r
- 已通过 `get_window_list` 找到目标窗口\r
\r
**使用桌面级操作**：\r
- 需要操作桌面元素（桌面图标、任务栏、系统托盘、开始菜单）\r
- 跨进程跨窗口操作（如从本地文件夹拖拽文件到网页上传区）\r
- 目标应用尚无窗口可绑定（如启动应用前操作）\r
- 文件选择对话框等操作系统级 UI\r
\r
**两种层级可以配合使用**：先用桌面级定位和启动应用，再用窗口级精确操作应用内容；或在 batch 中混用窗口级和桌面级指令完成跨应用流程。\r
\r
### 1. 初始化\r
\r
- 根据用户语言回复。\r
- 阅读 `references/config.md` 获取 `api_url`、`token`、`ai_app_type`、`session_id` 规则。\r
- 阅读 `scripts/README.md` 了解统一脚本入口和点号路径格式。\r
- 调用 `health` 确认服务可用。如果 health 失败（服务未运行）：\r
  - 检查 `references/config.md` 中是否记录了安装目录，且目录下存在 `screenclaw.exe`。\r
  - 如果没有安装目录或 exe 不存在：从 `https://github.com/GinSing1226/ScreenClaw/releases` 下载最新版 zip，询问用户解压目标目录，解压后将安装目录写入 `references/config.md` 的 `screenclaw_install_dir` 字段。\r
  - 启动安装目录下的 `screenclaw.exe`，等待几秒后重试 `health`。\r
- 复杂、多步、高风险任务先维护 2-5 步简短计划；简单单步任务不强制创建待办。\r
\r
### 2. 定位目标\r
\r
**窗口级路径**：\r
- 调用 `get_window_list` 找主窗口和可能的子窗口。\r
- 新进程或窗口不确定时，对候选窗口截图，记录窗口内容和可用 `window_id/main_window_id`。\r
- 后续操作失败时，先检查是否选错窗口，再换操作模式。\r
- `get_window_list` 未找到目标窗口时：通过 CLI 检索应用可执行文件（`where`/`Get-Command`/搜索常见安装路径），找到后启动应用，等待窗口出现后重试 `get_window_list` 拿到 `window_id`。\r
\r
**桌面级路径**：\r
- 调用 `desktop_get_monitors_list` 了解显示器布局。\r
- 单显示器直接使用 `monitor_index=0`。\r
- 多显示器需根据目标位置选择对应索引。\r
- 桌面截图使用 `desktop_screenshot`，坐标规则与窗口级一致（百分比 `XxY`）。\r
\r
### 3. 截图与读坐标\r
\r
窗口级和桌面级截图共享同一套网格、数字和 marker 参数体系：\r
\r
- 定位坐标使用 `coordinate_type=grid`。\r
- 分析内容或给用户看图可用 `coordinate_type=no`。\r
- 默认先依赖服务端自适应网格参数。\r
- 目标没有被交叉点覆盖时，阅读对应截图 API 文档调整 `grid.density_x/y`。\r
- 数字或元素看不清时，使用 `crop_zoom_screenshot` 或调整数字参数。\r
- 首次动态坐标或高风险坐标，先用 `crop_zoom_screenshot` 看清局部，再用 `marker.0.x/y` 反向验证。\r
- marker 反验要先找图上的标记点实际落在哪里，描述那里有什么，再判断它是否等于目标；不要先假设候选坐标正确。\r
\r
### 4. 操作与验证\r
\r
**窗口级操作**：\r
- 操作模式优先 `background`。\r
- `background` 无效或必须物理输入时才考虑 `hijack`。\r
- 用户主动要求、游戏实时操作、中文输入法候选面板等持续物理输入场景，阅读 `references/api/delegated.md` 后进入托管。\r
\r
**桌面级操作**：\r
- 固定 `hijack` 模式，无 `action_method` 参数。\r
- `delegated` 模式激活时自动跳过确认弹窗。\r
\r
**通用**：\r
- 探索阶段单步调用；流程稳定、需要瞬间观察 hover/菜单/操作结果时才用 `batch`。\r
- 每次操作后截图验证，验证不通过则回到截图和读坐标。\r
- 窗口级验证用 `screenshot`，桌面级验证用 `desktop_screenshot`。\r
- 跨进程、跨窗口、打开系统弹窗或文件选择框的动作，必须先执行该动作，再重新 `get_window_list` 定位新窗口并截图确认；不要继续对旧窗口截图期待看到新进程结果。\r
- 收到 `SELF_CHECK_REQUIRED` 时必须更新当前计划或下一步动作。\r
\r
## 坐标概念\r
\r
截图上的坐标格式为 `XxY`，例如 `50x35` 表示距左边界 50%、距上边界 35%。\r
\r
`x` 是坐标分隔符，不是乘号。目标元素的有效坐标是覆盖到该元素的网格交叉点坐标。\r
\r
窗口级和桌面级坐标格式完全一致，区别仅在于坐标空间：窗口级相对于窗口客户区，桌面级相对于整个显示器屏幕。\r
\r
## API 索引\r
\r
> 执行 API 前先读对应文档 `references/api/{endpoint}.md`\r
\r
### 基础\r
\r
| API | method | 适用场景 | 参考文档 |\r
|-----|------|-----------|----------|\r
| health | GET | 任务开始前检查服务 | `references/api/health.md` |\r
| delegated | POST | 用户主动要求进入/退出托管模式 | `references/api/delegated.md` |\r
\r
### 窗口级\r
\r
| API | method | 适用场景 | 参考文档 |\r
|-----|------|-----------|----------|\r
| get_window_list | POST | 找出需要被控制的目标窗口 | `references/api/get_window_list.md` |\r
| screenshot | POST | 带网格可定位坐标。不带网格可分析界面、留存记录。带标记点可预览坐标位置 | `references/api/screenshot.md` |\r
| crop_zoom_screenshot | POST | 裁剪任意截图并放大，看清细节（如坐标数字） | `references/api/crop_zoom_screenshot.md` |\r
| scroll_screenshot | POST | 滚动长截图，记录长页面、长内容，整体理解目标窗口 | `references/api/scroll_screenshot.md` |\r
| click | POST | 单击，触发按钮/进入页面 | `references/api/click.md` |\r
| long_press | POST | 长按，触发某些功能 | `references/api/long_press.md` |\r
| swipe | POST | 触摸式滑动，上下左右移动页面 | `references/api/swipe.md` |\r
| drag | POST | 拖拽元素，按住鼠标并移动 | `references/api/drag.md` |\r
| scroll | POST | 鼠标滚轮滚动，上下移动页面 | `references/api/scroll.md` |\r
| right_click | POST | 右键，打开上下文菜单 | `references/api/right_click.md` |\r
| hover | POST | 触发悬停效果，配合截图获取hover效果 | `references/api/hover.md` |\r
| mouse_move | POST | 鼠标移动，游戏视角控制，仅hijack/托管 | `references/api/mouse_move.md` |\r
| input_text | POST | 输入文本。带坐标会先单击再输入。不带坐标直接输入 | `references/api/input_text.md` |\r
| press_key | POST | 按键/组合键。多个按键空格分割。带坐标会先单击再按键。不带坐标直接按键 | `references/api/press_key.md` |\r
| wait | POST | 等待UI动画/页面加载 | `references/api/wait.md` |\r
\r
### 桌面级\r
\r
| API | method | 适用场景 | 参考文档 |\r
|-----|------|-----------|----------|\r
| desktop_get_monitors_list | GET | 枚举显示器，获取索引和分辨率 | `references/api/desktop_get_monitors_list.md` |\r
| desktop_screenshot | POST | 桌面截图，带网格可定位坐标。不带网格可分析界面、留存记录。带标记点可预览坐标位置 | `references/api/desktop_screenshot.md` |\r
| desktop_click | POST | 桌面单击，触发按钮/进入页面 | `references/api/desktop_click.md` |\r
| desktop_double_click | POST | 桌面双击 | `references/api/desktop_double_click.md` |\r
| desktop_right_click | POST | 桌面右键 | `references/api/desktop_right_click.md` |\r
| desktop_drag | POST | 桌面拖拽，支持跨屏 | `references/api/desktop_drag.md` |\r
| desktop_scroll | POST | 桌面滚轮滚动 | `references/api/desktop_scroll.md` |\r
| desktop_input_text | POST | 桌面文本输入，带坐标会先单击再输入。不带坐标直接输入 | `references/api/desktop_input_text.md` |\r
| desktop_press_key | POST | 桌面按键/组合键，多个按键空格分割。带坐标会先单击再按键。不带坐标直接按键 | `references/api/desktop_press_key.md` |\r
| desktop_hover | POST | 桌面悬浮，触发悬停/hover效果 | `references/api/desktop_hover.md` |\r
\r
### 组合\r
\r
| API | method | 适用场景 | 参考文档 |\r
|-----|------|-----------|----------|\r
| batch | POST | 组合指令，支持混用窗口级和桌面级 | `references/api/batch.md` |\r
\r
## 脚本降级\r
\r
降级路径：\r
\r
```text\r
scripts/screenclaw.py -> scripts/screenclaw.ps1 -> scripts/screenclaw.sh -> curl\r
```\r
\r
降级前先判断原因：\r
\r
| 错误类型 | 处理方式 |\r
|----------|----------|\r
| 参数错误 | 修正参数，重跑同一脚本，不降级 |\r
| API 业务错误 | 阅读对应 API 文档和服务端 message，不降级 |\r
| Python 不存在等环境错误 | 降级到 PowerShell 或 shell |\r
\r
## 参考文档\r
\r
- `references/config.md` - 连接配置、`ai_app_type`、`session_id`\r
- `scripts/README.md` - 统一脚本入口和点号路径格式\r
- `references/self_check.md` - 长时程自检重载清单\r
- `references/api/*.md` - 各 API 参数和排错\r
- `references/scenarios/` - 场景模板和应用知识\r
- `references/scenarios/recording_to_scenario.md` - 从用户录制产物沉淀场景模板\r
- `scripts/coord_adapt.py|ps1|sh` - 模板固定坐标迁移与复用决策\r
- `scripts/recording_windows.py|ps1|sh` - 从 `step.json` 生成录制窗口组预处理表\r