feat: add three-surface RPA locator standards and examples

examples/real_desktop_rpa/README.md

@@ -0,0 +1,135 @@
+# Real Windows Desktop RPA Example
+
+这是从已跑通业务技能 `D:\OpenClaw\client-marketing\add-friend-wecom` 提炼的 Windows UIA 参考案例。它用于教技术人员和 AI 编程工具如何从真实拾取结果得到稳定定位器，并完成窗口、控件、动作、等待和诊断闭环。
+
+## 状态
+
+- **技术路线已真实验证**：Windows UIA + Python `uiautomation`
+- **来源业务已真实跑通**：企业微信添加客户
+- **本目录默认安全模式**：只提供 probe、dry-run、assisted 范式，不默认发送真实邀请
+- **不是完整 skill 仓库**：按 Copy map 选择性复制
+
+## 先读
+
+1. [`../../development/RPA_ELEMENT_LOCATING.md`](../../development/RPA_ELEMENT_LOCATING.md)
+2. [`../../development/RPA_DESKTOP.md`](../../development/RPA_DESKTOP.md)
+3. 本 README 的“原始拾取到生产定位器”
+
+## 成功案例验证了什么
+
+```text
+枚举目标顶层窗口
+→ 按进程/窗口类/标题确认作用域
+→ 从 HWND 获取 UIA root
+→ 在父容器中定位元素
+→ 激活窗口并真实点击/输入
+→ 等待子窗口或业务结果
+→ 处理独立/嵌套弹窗
+→ probe-ui 诊断
+```
+
+来源案例还提供 `dry-run / assisted / auto` 三档、频率控制和业务记忆。本 example 只提炼 UIA 元素工程；账号、风控和数据库仍由具体业务技能实现。
+
+## 目录结构
+
+```text
+real_desktop_rpa/
+  README.md
+  assets/
+    element-map.sample.yaml
+    selector-capture.sample.xml
+  scripts/
+    service/
+      desktop_session.py
+      uia_locator.py
+      wecom_reference_flow.py
+    util/
+      selectors.py
+  tests/
+    test_selector_contract.py
+```
+
+## 原始拾取到生产定位器
+
+来源案例的影刀 `selectorsV2` 导出通常包含：
+
+```text
+Window(class=SearchExternalsWnd,title=添加客户)
+  → 多层 Layout/index
+  → search_layout
+  → searchedit
+```
+
+正确提炼方式：
+
+1. 保留稳定顶层窗口：进程、Window Class、标题。
+2. 保留最小业务父容器：如 `search_layout`。
+3. 使用叶子元素稳定属性：如 `Name=searchedit`。
+4. 删除只反映当前布局的深层 `index`。
+5. 验证父容器内候选数量为 `1`。
+6. 重启应用后再次验证。
+
+不要把完整 XML 路径或 `item[0]` 原样变成生产定位器。
+
+## Element map
+
+本目录的 [`assets/element-map.sample.yaml`](assets/element-map.sample.yaml) 只展示来源案例的元素登记方法。复制后必须重新拾取目标软件并全部替换。
+
+关键规则：
+
+- 窗口不唯一时失败，不取 `hwnds[0]`。
+- 控件不唯一时失败，不取第一个匹配。
+- `item`、`status_layout`、`wbtn_container` 等通用 Name 必须放进稳定父容器。
+- 行顺序不是身份；用业务文案或稳定属性选择结果行。
+- 只有主定位成功、窗口前台且矩形有效时，才允许从 UIA BoundingRectangle 降级坐标点击。
+
+## 三种实施模式
+
+| 模式 | 行为 | 用途 |
+|---|---|---|
+| `probe` | 只检查依赖、窗口和关键控件 | 安装、自检、版本变更排障 |
+| `dry-run` | 导航并填写，提交前停止 | 开发和验收默认 |
+| `assisted` | 填写后等待用户人工确认 | 不可逆动作或现场联调 |
+
+业务技能若增加 `auto`，必须实现明确确认策略、频率限制、业务后置状态和 `RESULT_UNCONFIRMED`。
+
+## Copy map
+
+| 来源 | 目标 | 说明 |
+|---|---|---|
+| `scripts/service/desktop_session.py` | `scripts/service/desktop_session.py` | 顶层窗口枚举、唯一性、激活 |
+| `scripts/service/uia_locator.py` | `scripts/service/uia_locator.py` | 作用域内唯一定位、点击、输入 |
+| `scripts/util/selectors.py` | `scripts/util/<platform>_selectors.py` | element spec；必须全部替换 |
+| `scripts/service/wecom_reference_flow.py` | `scripts/service/<business>_flow.py` | 只复制流程分层，不复制企微 selector |
+| `assets/element-map.sample.yaml` | `assets/<platform>-element-map.yaml` | 真实拾取后填写 |
+| `tests/test_selector_contract.py` | `tests/test_selector_contract.py` | 定位器契约测试思路 |
+
+## 必须补齐的业务能力
+
+- 目标应用安装/版本 doctor
+- 真实业务元素清单
+- 失败截图、UIA树和顶层窗口快照
+- Activity/RpaVideoSession 步骤
+- 不可逆动作确认
+- 业务成功/失败/结果不明确状态
+- 频率限制、幂等和断点续跑
+- 真实集成测试（默认不进 CI）
+
+## 禁止照抄
+
+- `WXWork`、`WeWorkWindow`、`SearchExternalsWnd`
+- `org_op_new`、`searchedit`、`wbtn_container`
+- 企业微信列表第 0/1 行含义
+- 来源案例的本机路径、账号和业务数据
+- 任何未经目标软件真实拾取验证的 fallback
+
+## 验收
+
+- `probe` 能明确报告依赖、窗口和关键元素
+- 每个关键元素在目标作用域内唯一
+- 关闭重开软件后仍能定位
+- 多窗口时不会误选
+- UI变化时停止并保存截图/UIA树
+- dry-run 不执行不可逆提交
+- assisted 清楚提示用户确认
+- 提交后仅在业务后置状态成立时报告成功