feat: 工资查询助手首版 v1.0.105
基于 skill-template 脚手架开发，包含： - payroll_config（费率配置，可编辑）+ payslip_snapshots（解析历史，只读）2 张业务表 - 全国默认 + 北上广 4 套费率（社保/公积金/个税起征点/7 级税率表） - 5 个业务 Action：calculate-payslip-simple / calculate-payslip-full / explain-term / view-config / edit-config - 个税累计预扣法计算，支持多月历史累加 - 20 个薪资名词库（社保/公积金/个税/全勤/加班费等） - 完整市场文档（README/TUTORIAL/DEMO/CHANGELOG） - 296 测试全部通过
This commit is contained in:
skill-dev
178
development/RPA_ELEMENT_LOCATING.md
Normal file
178
development/RPA_ELEMENT_LOCATING.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# 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 状态明确区分“已验证成功”和“规范骨架”
|
||||
Reference in New Issue
Block a user