ee2a4d9e22
All checks were successful
技能自动化发布 / release (push) Successful in 15s
基于 skill-template 脚手架开发，包含： - 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额） - 请假核算引擎（扣薪计算、审批层级判定、年假抵扣） - CLI 入口（import-employees / calculate-leave / render-html） - HTML 审批与扣薪报告生成 - 示例数据与完整测试套件（295 tests passed）
179 lines
8.1 KiB
Markdown
179 lines
8.1 KiB
Markdown
# RPA 元素定位与拾取总标准
|
||
|
||
> 本文定义浏览器、Windows 桌面和手机三端共用的“元素工程”标准。开始写任何界面操作代码前必须先完成元素拾取、元素清单和定位验证。分端实操分别见 [`RPA_BROWSER.md`](RPA_BROWSER.md)、[`RPA_DESKTOP.md`](RPA_DESKTOP.md)、[`RPA_MOBILE.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](https://git.jc2009.com/client-jiangchang/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：
|
||
|
||
```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. 动作闭环
|
||
|
||
每一个动作实现为一个小状态机：
|
||
|
||
```text
|
||
确认前置状态
|
||
→ 获取正确作用域
|
||
→ 重新定位元素
|
||
→ 校验唯一/可见/可用
|
||
→ 激活并执行真实输入
|
||
→ 等待后置状态
|
||
→ 记录成功证据
|
||
```
|
||
|
||
- 缓冲等待只用于改善稳定性，不能替代后置状态。
|
||
- 点击后状态不明确时先查询业务状态，禁止再次点击。
|
||
- 付款、发送、删除、审批、发布等动作如果无法确认结果，返回 `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`](RPA_DESKTOP.md) §2）。
|
||
4. 把目标系统 selector 集中到 element map/selector catalog，不散落在业务流程中。
|
||
5. 为每个动作实现前置状态、定位、动作和后置状态。
|
||
6. 把诊断探针、界面树导出和失败截图作为实现的一部分。
|
||
7. 不把 mock 通过、命令未报错或弹窗关闭当成真实业务成功。
|
||
8. 不擅自切换到 Hook、注入、私有协议、验证码破解或其他禁止路线。
|
||
|
||
## 9. 交付门禁
|
||
|
||
- [ ] 关键元素均有元素清单和真实拾取证据
|
||
- [ ] 每个不可逆动作默认唯一定位
|
||
- [ ] 重启会话后定位仍然有效
|
||
- [ ] 动态数据或列表顺序变化后不会误点
|
||
- [ ] 每个动作有真实后置状态
|
||
- [ ] UI结构变化会停止并留证
|
||
- [ ] fallback 均已人工验证
|
||
- [ ] 截图和控件树不泄露敏感数据
|
||
- [ ] 真实主路径至少完整跑通一次
|
||
- [ ] example 状态明确区分“已验证成功”和“规范骨架”
|