Release v1.0.61: desktop RPA Name/Value and activate fixes

development/DEVELOPMENT.md

@@ -158,7 +158,7 @@ scripts/
    ```
    上述 import 来自宿主共享 runtime 安装的 `jiangchang-platform-kit`，不是技能目录副本。
 4. **单测/CI 须 mock 离线可过**；业务 `.env` 默认 `real_rpa`，须真实跑通。**不得只 mock 通就交活**；须 release 到匠厂宿主验收（见 §15，含用户体验）。多账号或矩阵能力还须按 `ACCOUNT_MANAGER.md` 覆盖至少两个账号、租约冲突、关闭重开保持登录和异常释放，不能以单账号一两次成功代替规模验证。
-5. **Windows 桌面**：技术路线已由 `add-friend-wecom` 验证。先读 `examples/real_desktop_rpa/README.md`，复用窗口唯一性、UIA作用域、probe、dry-run/assisted 和失败留证范式；目标软件 selector 必须重新拾取，禁止照抄企业微信控件名。
+5. **Windows 桌面**：技术路线已由 `add-friend-wecom` 全链路验证。先读 `examples/real_desktop_rpa/README.md` 与 `development/RPA_DESKTOP.md`（含 Name/Value、最大化激活、同名叶子父容器），复用窗口唯一性、UIA 作用域、probe、dry-run/assisted 和失败留证范式；目标软件 selector 必须重新拾取，禁止照抄企业微信控件名。
 6. **手机**：先按 `RPA_MOBILE.md` 完成设备、context、element map 和验收设计。当前 `examples/mobile_rpa/` 只是完成规格，尚无真实成功案例；不得把骨架宣传为已跑通实现。
 
 **技术路线红线：**正常界面或获得授权的官方 API 无法完成闭环时，停止并向负责人说明；禁止 AI 或开发者擅自改用破解、反编译、逆向、私有协议、Hook / 注入、验证码破解、设备指纹伪造、自动换号或无限重试。

development/RPA_DESKTOP.md

@@ -15,14 +15,16 @@
 
 ## 1. 已验证基线
 
-真实成功来源：`D:\OpenClaw\client-marketing\add-friend-wecom`。
+真实成功来源：`D:\OpenClaw\client-marketing\add-friend-wecom`（含通讯录 → 新的客户 → 添加 → 搜索 → 发送全链路）。
 
 该案例验证了：
 
 - 通过进程/窗口类名/标题找到企业微信顶层窗口。
-- 从 HWND 获取 UIA 根控件。
-- 在父窗口和弹窗范围内按 UIA 属性定位。
-- 真实激活窗口、点击、逐字输入和轮询状态。
+- 主窗激活后**最大化**，避免侧栏折叠导致控件不可见或坐标漂移。
+- 从 HWND 获取 UIA 根控件；在**子业务 pane**（如「企业微信-通讯录」）内缩小作用域。
+- 区分 UIA `Name` 与 `Value`：可见中文常在 Value / 子 Label，不在 Name。
+- 通用叶子名（`item` / `status_layout` / `wbtn_container`）必须绑业务父容器，并用文案校验。
+- 真实点击后校验后置状态（标题、专用容器、子窗口）。
 - 处理独立弹窗与嵌套弹窗。
 - 提供 `probe-ui` 诊断和 `dry-run / assisted / auto` 三档。
 
@@ -34,31 +36,37 @@ example 只提炼通用模式；企业微信名称、窗口类、控件名、列
 
 操作步骤：
 
-1. 启动目标软件，登录并手工进入准确页面。
+1. 启动目标软件，登录并手工进入准确页面；需要完整侧栏时先**最大化**。
 2. 记录目标进程名、PID、主窗口标题和 Window Class。
 3. 用检查器点选目标元素，记录：
    - AutomationId
-   - Name
-   - ControlType
-   - ClassName
-   - FrameworkId
-   - IsEnabled / IsOffscreen
-   - BoundingRectangle
-   - 父容器链
+   - **Name**（内部 id，可能是 `org_op_new` / `status_layout`）
+   - **Value**（可见中文文案常在这里，如「通讯录」「新的客户」）
+   - ControlType / ClassName / FrameworkId
+   - IsEnabled / IsOffscreen / BoundingRectangle
+   - 父容器链（含业务子窗/pane 标题）
 4. 保存截图和原始 UIA 树/拾取器导出文件。
 5. 从长路径中找出稳定窗口、业务父容器和叶子属性。
-6. 删除仅反映当前布局的深层 index；确需 index 时写明业务依据。
-7. 写入 element map。
-8. 运行 `probe-ui`，验证关键窗口和元素。
+6. 删除仅反映当前布局的深层 index；确需 index 时写明业务依据，且优先用文案定位。
+7. 写入 element map（Name 与 Value 分开登记）。
+8. 运行 `probe-ui`（建议先激活并最大化），验证关键窗口和元素。
 9. 关闭重开软件、切换一次页面后再次验证。
 
+### Name / Value（易错）
+
+- 影刀/检查器里的**选择器显示名**（如「新的客户」）≠ 控件 UIA `Name`。
+- 许多国产客户端：`Name` 是内部 id，**界面中文在 `Value` 或子控件 Value**。
+- 拾取时两者都记；定位时勿把业务中文当成 `Name=` 去搜。
+
 ### 从拾取结果提炼定位器
 
 影刀等工具可能导出很长的 UIA 路径。不要整条照抄：
 
 ```text
-原始：主窗口 → 多层布局 → 列表 → item[2] → status_layout
-提炼：进程/窗口 → 通讯录列表父容器 → 业务文案或稳定叶子属性
+原始：主窗口 → 通讯录 pane → wlist_view → item[2] → status_layout
+      → … → main_chattext（Value=新的客户）
+提炼：通讯录 pane → wlist_view → 行内 main_chattext.Value=新的客户 → 点击该行 status_layout
+禁止：全树第一个 Name=status_layout（常为「群聊」等其它行）
 ```
 
 长路径用于排障和理解结构；生产定位器使用最短、唯一、可解释的稳定组合。
@@ -67,25 +75,28 @@ example 只提炼通用模式；企业微信名称、窗口类、控件名、列
 
 从高到低：
 
-1. `Process/PID + WindowClass + WindowTitle`
+1. `Process/PID + WindowClass + WindowTitle`（及稳定业务子 pane）
 2. 目标窗口内 `AutomationId + ControlType`
-3. 稳定 `Name + ControlType`
+3. 稳定内部 `Name + ControlType`（如 `org_op_new`、`searchedit`）
 4. 业务父容器 + 稳定子元素属性
-5. 可见业务文案 + 相对关系
+5. **可见业务文案（优先读 Value / 子 Label）+ 相对关系**
 6. `ClassName/FrameworkId` 辅助组合
-7. 有业务依据的 index
+7. 有业务依据的 index（仅兜底；须写清父容器与序号含义，禁止「过滤后的列表 [2]」与「父节点 child index=2」混用）
 8. UIA 元素实时 BoundingRectangle 派生坐标
 9. 局部截图模板/OCR
 10. 写死绝对坐标：禁止作为生产方案
 
 顶层窗口或关键按钮出现多个候选时，返回 `ERROR:ELEMENT_AMBIGUOUS`，不得默认使用第一个。
 
+同名叶子（如多处 `wbtn_container`）必须限制在业务父容器内（如 `search_external`），并可用子文案（如 Value=`添加`）校验；禁止点搜索旁通用「+」。
+
 ## 4. 窗口与控件规则
 
 ### 窗口
 
 - 校验窗口属于预期进程和当前用户会话。
-- 主窗口、搜索窗、确认窗分别建立作用域。
+- 主窗口、**应用内业务子 pane**、搜索窗、确认窗分别建立作用域。
+- 进入依赖完整侧栏/工具栏的页面时：**激活后最大化**；`activate` **禁止**对已最大化窗口无条件调用 `SW_RESTORE`（会还原成普通窗，导致折叠与坐标漂移）。仅最小化时才 Restore。
 - 应用可能重建窗口；页面切换后重新取 HWND 和 UIA root。
 - 自动化进程与目标进程权限级别必须兼容；不要为了绕过权限注入目标进程。
 - 多开场景必须由账号、PID或明确窗口信息选择，歧义时停止。
@@ -102,11 +113,13 @@ example 只提炼通用模式；企业微信名称、窗口类、控件名、列
 
 ### 点击
 
-1. 激活目标窗口。
+1. 激活目标窗口（主窗按需最大化；子对话框不要误 Maximize）。
 2. 重新定位元素。
 3. 检查边界矩形。
 4. 使用 UIA Click/Invoke 或正常鼠标点击。
-5. 等待后置窗口/控件/业务状态。
+5. 等待后置窗口/控件/业务状态（如标题文案、专用容器、子窗口 Class）。
+
+关键导航建议日志：`locate`（策略/文案）→ `click` → `verify`（后置）。这与 [`LOGGING.md`](LOGGING.md)「不必每个 Click 一行」不冲突：要求的是**关键跳转可观测**，不是像素级刷屏。
 
 UIA 点击失败时可以用该元素刚读取的 BoundingRectangle 中心点降级，但必须记录降级、确认窗口前台并验证后置状态；不得静默改点写死坐标。
 
@@ -133,10 +146,11 @@ UIA 点击失败时可以用该元素刚读取的 BoundingRectangle 中心点降
 先检查：
 
 1. 权限级别和 Windows 会话是否一致。
-2. 是否选错进程或子窗口。
+2. 是否选错进程或子窗口；主窗是否未最大化导致侧栏未实例化。
 3. 控件是否离屏或尚未实例化。
 4. 应用是否为 Electron（可评估 Playwright）。
 5. 是否为自绘、游戏引擎、远程桌面或安全控件。
+6. 空树/树抖动时：最大化主窗；用 Inspect/影刀附着一次后再 probe（远程桌面工具可能干扰无障碍树）。
 
 只有控件树确认不可用时才使用图像：
 
@@ -153,11 +167,15 @@ U盾、人脸、动态口令和安全键盘交给人工，不用 OCR、Hook 或
 桌面 `health` / `probe-ui` 至少输出：
 
 - UIA 依赖是否可用。
-- 目标进程和主窗口是否存在。
+- 目标进程和主窗口是否存在；是否已最大化（若业务需要）。
 - 关键窗口/控件是否各唯一匹配。
 - 当前窗口标题、Class、PID。
 - DPI/缩放诊断。
 
+example 里的最小 `probe`（只探主窗+个别入口）**不等于**生产 probe 完整度；业务技能应对关键跳转节点分别探测或做深探。
+
+手开 PowerShell 跑 `stats` / `health` / dump 时，必须显式对齐宿主的 `CLAW_USER_ID` / 数据根，否则会读到默认用户空库，误判熔断/冷却。
+
 定位失败保存：
 
 - 目标窗口和全屏截图。

development/RPA_ELEMENT_LOCATING.md

@@ -155,7 +155,7 @@ verified_at: "YYYY-MM-DD"
 
 1. 先阅读本总标准和对应分端手册。
 2. 先输出业务步骤表和元素清单，再生成代码。
-3. 只使用真实拾取得到的属性；缺少属性时明确停止并索要界面快照。
+3. 只使用真实拾取得到的属性；缺少属性时明确停止并索要界面快照。桌面端须同时记录 **Name 与 Value**（可见中文常在 Value；见 [`RPA_DESKTOP.md`](RPA_DESKTOP.md) §2）。
 4. 把目标系统 selector 集中到 element map/selector catalog，不散落在业务流程中。
 5. 为每个动作实现前置状态、定位、动作和后置状态。
 6. 把诊断探针、界面树导出和失败截图作为实现的一部分。