skill-template/development/RPA_ELEMENT_LOCATING.md

RPA 元素定位与拾取总标准

本文定义浏览器、Windows 桌面和手机三端共用的“元素工程”标准。开始写任何界面操作代码前必须先完成元素拾取、元素清单和定位验证。分端实操分别见 RPA_BROWSER.md、RPA_DESKTOP.md、RPA_MOBILE.md。

目录

1. 核心术语
2. 强制工作流
3. 元素清单
4. 定位器质量规则
5. 动作闭环
6. 降级决策树
7. 失败留证
8. AI 编程约束
9. 交付门禁

1. 核心术语

术语	定义
拾取	使用检查器在真实界面上点选元素，读取 DOM、UIA 或移动控件树属性
定位器	根据稳定属性在运行时重新找到元素的规则
作用域	页面、iframe、窗口、弹窗、父容器、列表行或 WebView 等查找边界
锚点	与目标元素存在稳定业务关系的父级、标题、标签或同一行元素
后置状态	动作完成后必须出现或消失的真实业务状态
降级	主定位器不可用时，改用已验证的备用定位器或图像方案
界面快照	失败现场的截图和 DOM/UIA/XML 控件树

2. 强制工作流

按以下顺序开发，不得跳过拾取直接猜 selector：

1. 在真实目标版本上手工走通业务流程，记录每一步的前置状态和成功表现。
2. 使用对应端检查器拾取元素，保存截图和原始 DOM/UIA/XML。
3. 识别正确作用域：页面/iframe、进程/窗口、Native/WebView、弹窗或列表行。
4. 为每个关键元素填写元素清单。
5. 按分端优先级生成候选定位器。
6. 验证候选定位器在目标作用域中匹配数量符合预期，关键动作默认必须恰好为 1。
7. 验证元素可见、启用、未离屏且边界矩形有效。
8. 执行动作，并等待真实后置状态。
9. 重启目标程序或会话后再次验证；动态列表还要更换数据验证。
10. 记录已验证的软件版本、页面状态、系统缩放/设备信息和日期。

未完成第 2～6 步时，代码只能保留明确的 TODO: NEED_REAL_UI_INSPECTION，不得写“看起来可能正确”的 selector。

开发期推荐使用独立仓 jiangchang-ui-recorder（本机常见路径 D:\OpenClaw\client-jiangchang\jiangchang-ui-recorder，python run.py）：以 Raw Event Journal → Action → Element Catalog → 异步 Observation 录制，优先把 action_flow.json 与 element_catalog.json 交给 AI 编程工具；原始事件可重新归并，tree/index 作为诊断证据。默认不再让完整页面 dump 阻塞动作采集。本模板仓内的 tools/ui_inspector 已移除，勿再从 skill-template 启动。

3. 元素清单

每个关键输入、按钮、列表、弹窗、成功状态和错误状态都必须登记。推荐 YAML：

logical_name: submit_button
purpose: 提交当前业务单据
surface: browser                 # browser | windows | android | ios
screen: 订单确认
scope:
  kind: dialog
  locator: role=dialog,name=订单确认
primary_locator:
  strategy: role
  value: button,name=确认提交
fallback_locators: []
expected_count: 1
ready_condition:
  visible: true
  enabled: true
postcondition:
  description: 出现订单号且状态为已提交
failure_evidence:
  - screenshot
  - ui_tree
verified_target_version: "待填写"
verified_at: "YYYY-MM-DD"

要求：

• logical_name 使用业务语义，不使用 button1、element2。
• scope 不得省略；全页面、全桌面或全设备盲搜不作为默认生产方案。
• fallback_locators 只能填写人工验证过的定位器。
• 不可逆动作必须同时登记确认前状态和提交后状态。
• selector 变化时更新 verified_target_version 和验证日期。

4. 定位器质量规则

4.1 必须满足

• 关键动作定位器在目标作用域中唯一。
• 定位器依赖业务语义、可访问性属性或稳定接口标识。
• 每次页面/窗口/列表刷新后重新定位，不长期缓存元素句柄。
• 同一元素的主定位器和 fallback 使用不同的稳定证据，不是同一脆弱路径的轻微改写。
• 多结果是合法业务场景时，先定位业务容器/行，再在容器内定位按钮。

4.2 默认禁止

• 用 .first、.nth(0)、hwnds[0]、instance=0 消除本应解决的歧义。
• 长绝对 XPath、深层 DOM/UIA 路径和大量 index。
• 哈希 class、随机生成 id、易变化坐标作为唯一依据。
• 扫描所有输入框后按宽度、位置“猜”目标。
• 捕获所有异常后继续尝试随机 selector 或随机坐标。
• UI结构变化后自动生成新 selector 并继续执行不可逆动作。

确有稳定业务顺序时可以使用 index，但必须在元素清单中写明锚点、顺序依据、匹配总数和版本验证结果。

5. 动作闭环

每一个动作实现为一个小状态机：

确认前置状态
→ 获取正确作用域
→ 重新定位元素
→ 校验唯一/可见/可用
→ 激活并执行真实输入
→ 等待后置状态
→ 记录成功证据

• 缓冲等待只用于改善稳定性，不能替代后置状态。
• 点击后状态不明确时先查询业务状态，禁止再次点击。
• 付款、发送、删除、审批、发布等动作如果无法确认结果，返回 ERROR:RESULT_UNCONFIRMED。
• 列表滚动、页面切换、窗口重建和移动端 Activity 切换后重新获取元素。

6. 降级决策树

找不到元素时依次检查：

1. 目标应用、页面或设备是否正确启动并处于预期账号。
2. 是否选错页面、iframe、进程、窗口、弹窗、Native/WebView 上下文。
3. 元素是否尚未加载、被遮挡、禁用、离屏或在虚拟列表未实例化区域。
4. 是否因管理员权限、远程会话、设备授权或驱动版本无法读取控件树。
5. 主定位器属性是否变化；对比保存的界面快照。
6. 是否可以用已验证的父容器、业务文案或相对锚点定位。
7. 控件是否为 Canvas、自绘、远程桌面或未暴露可访问性树。
8. 最后才评估局部图像/OCR/坐标方案。

任何一级确认“界面结构变化”时，截图、导出控件树并停止；不得在生产任务中让 AI 临时猜新定位器。

7. 失败留证

定位失败至少保存：

• 当前屏幕/窗口截图。
• 当前 DOM、UIA 或移动端 XML。
• 页面 URL、进程/PID/窗口标题或设备 serial、包名、Activity、context。
• 逻辑元素名、作用域、主定位器和已尝试 fallback。
• 每个候选匹配数量、可见/启用/离屏状态和边界矩形。
• 目标应用版本、浏览器版本或设备系统版本。
• 失败阶段、错误码、时间和 batch_id。

敏感输入、Cookie、token、手机号和客户数据必须脱敏。

8. AI 编程约束

向 AI 编程工具提供本模板时，必须要求它：

1. 先阅读本总标准和对应分端手册。
2. 先输出业务步骤表和元素清单，再生成代码。
3. 只使用真实拾取得到的属性；缺少属性时明确停止并索要界面快照。桌面端须同时记录 Name 与 Value（可见中文常在 Value；见 RPA_DESKTOP.md §2）。
4. 把目标系统 selector 集中到 element map/selector catalog，不散落在业务流程中。
5. 为每个动作实现前置状态、定位、动作和后置状态。
6. 把诊断探针、界面树导出和失败截图作为实现的一部分。
7. 不把 mock 通过、命令未报错或弹窗关闭当成真实业务成功。
8. 不擅自切换到 Hook、注入、私有协议、验证码破解或其他禁止路线。

9. 交付门禁

• 关键元素均有元素清单和真实拾取证据
• 每个不可逆动作默认唯一定位
• 重启会话后定位仍然有效
• 动态数据或列表顺序变化后不会误点
• 每个动作有真实后置状态
• UI结构变化会停止并留证
• fallback 均已人工验证
• 截图和控件树不泄露敏感数据
• 真实主路径至少完整跑通一次
• example 状态明确区分“已验证成功”和“规范骨架”