skill-template/tools/ui_inspector

OpenClaw UI Inspector（UI Automation Recorder v0.16.0）

默认窗口采用窄长控制台布局：停靠到鼠标所在显示器右侧，顶部预留目标应用标题栏安全区；也可在界面中一键切换到左侧。

定位：以人工操作为主线的开发期录制器，产出可交给 AI 编程工具的 Action Flow + Element Catalog。 不是：每 2 秒无条件 dump 页面的流水线（该行为仅保留为 Legacy 模式）。

核心模型

人工操作
  → Raw Event Journal（先落事实，不阻塞）
  → Action Reducer（去重、输入事务、pointerdown/click 合并）
  → Target Resolver（距离 + 面积 + 语义）
  → ActionRecord + Element Catalog
  → 异步合并式 Observation / State / Screenshot

概念	作用
Action	流程主线（click / fill / press_key / checkpoint …）
State	动作前后上下文与证据（tree/index/screenshot）
Element Catalog	开发期与运行期共用的元素资产
Locator	结构化属性 + 编译后的 expression；须验证匹配数
原始 dump	诊断证据；不再把每次 heartbeat 登记为流程步骤
Raw Event Journal	可重算的原始事实；Reducer 出错时无需重走人工流程

启动

cd D:\OpenClaw\client-commons\skill-template
python tools/ui_inspector/run.py --scene demo

依赖：

pip install -r tools/ui_inspector/requirements.txt
pip install "jiangchang-platform-kit>=1.2.11"

录制流程

主界面固定使用自动动作录制，只保留 开始 / 暂停（继续）/ 结束。Recorder 立即记录 Action，完整证据由独立后台队列异步合并采集。Inspector 自身窗口上的点击和输入不会写入目标 Action Flow。

“运行状态与拾取结果”会对浏览器和桌面统一采用单步骤覆盖式显示；新动作替换上一动作，同一动作的异步证据返回后在原位置更新定位器、唯一性或失败原因。迟到的旧动作证据不会覆盖更新的步骤，完整历史始终保存在 action_flow.json、actions/ 与 element_catalog.json 中。

引导、手动检查点和 Legacy 间隔 dump 仅作为底层兼容与开发诊断能力保留，不进入普通用户流程；旧偏好会自动迁移回自动录制。

运行时稳定性

• Tk 主线程只处理界面；导航、Dump、截图、动作落盘均在后台执行。
• 后台结果通过 UI 消息队列回传，后台线程不读取 Tk Variable 或 Widget。
• 原始事件先追加到 journal/raw_events.jsonl，再进入语义 Action FIFO。
• Action 热路径不执行完整页面 dump；慢速证据在独立队列按页面合并采集。
• 异步证据标记为 coalesced_eventual，不会伪装成事件时刻的精确 after state。
• Playwright 命令均有超时；导航失败不会被伪装成“已就绪”。
• 浏览器使用 context 级事件桥并保留轮询回退，整页跳转前的 click 不随旧 document 丢失。

拾取通道

• 浏览器：Inspector 自管 Playwright；起始 URL 可选；Browser Recorder（捕获阶段监听，不 preventDefault）
  • 动作后的 Dump / 截图绑定事件来源 page_id；手动检查点才按当前可见标签页回退，不再固定 pages[0]
  • 列表页新开详情标签后，切到详情再 dump/录制即可；关闭详情回到列表同理
  • Recorder 会在所有已打开标签上安装监听并汇总事件
  • 输入框、contenteditable、SVG/图标点击会沿 composedPath 提升到真实可操作目标；原始命中节点仍保留作诊断证据
  • 语义定位不足时生成完整 CSS 路径，并在事件来源页面实时验证唯一性后才进入 Locator Catalog
  • 链接保留 href，可编辑区生成稳定祖先作用域选择器；事件时刻的唯一性计数随快照保存，避免跳转后误判
  • press_key 保留原始事件、Page/Document 身份和目标元素引用，不再依赖前一步推断焦点
  • 页面跳转采用短暂因果重排，确保触发跳转的 click 先于 navigation；新标签同时保留 opener page_id
  • 同时监听 pointerdown 与 click：正常 click 会去重；页面提前卸载时 pointerdown 作为保底 Action
  • 通用目标评分限制祖先距离与面积，不会把小图标提升成整页容器
  • 目标解析联合考虑语义、几何、事件时刻唯一性和定位器稳定性；SVG/path 仅作命中证据，优先选择唯一的可点击包装节点
  • 输入事务与 Element Catalog 共用稳定元素身份，焦点/校验/悬停 class 变化不会拆分一次连续输入
  • 输入事务使用浏览器源时间并保存全部 raw_event_ids，支持从原始日志审计和重算
  • 完整 Dump / Screenshot 由后台 Evidence Coordinator 合并执行；手动检查点仍保留稳定采集
• 桌面：UIA；Windows Recorder 使用进程外 WH_MOUSE_LL / WH_KEYBOARD_LL 事件监听，点击后由独立线程执行 ControlFromPoint。Hook 不注入目标进程；GetAsyncKeyState 仅作为 Hook 无法安装时的降级路径。
  • 输入使用焦点控件 Value/Text 变化聚合为一次 fill，不保存中文输入法的拼音按键；混合 DPI 应用会在键盘阶段重新探测正确坐标空间。
  • 已注册的桌面适配器会在宣布“录制就绪”前完成必要的 Accessibility warm；企业微信首次启动可能多等十几秒，但不会再让首个输入事务与后台暖树竞争。
  • 输入法候选/组合窗口只作为临时系统 UI 忽略，不会替换业务输入框；编辑器内的 Backspace/Delete 合并进最终 fill。
  • Enter、Tab 等功能键优先继承刚才的文本编辑器目标，不再退化为整个根窗口。
  • 鼠标按下时会枚举光标下可见顶层窗口，处理 owner window 吞掉浮窗命中的应用；后置树再把搜索/列表大容器提升到坐标命中的具体行。
  • 超过 5 秒的延迟证据不能用动态消息摘要/预览改写旧点击；坐标不可靠且只有一个可见结果行时，才使用唯一结果行作为保守回退。
  • 原始键盘活动只写入不含内容的事务标记；若发生输入但没有生成 fill/type，质量检查会明确告警。
• 手机：未实现，不得宣称已支持

输出目录（双写兼容）

_captures/<ts>_<flow>/
  flow.json              # v1 schema；可选 v2 指针字段
  SUMMARY.md
  action_flow.json       # v2
  element_catalog.json   # v2
  pages.json             # Page / Document 记录
  journal/raw_events.jsonl
  diagnostics/metrics.json
  diagnostics/validation.json
  diagnostics/replay_report.json  # 静态、非破坏性的回放就绪预检
  steps/NN_xxx/          # v1：meta/tree/index/locatable/screen/SUMMARY
  states/<id>/           # v2：证据
  observations/<id>/     # v2：每次真实采集证据（不去重）
  actions/<id>.json
  elements/<id>.json

旧读取方只认 flow.json + steps/ 仍可工作。flow.json 中的 v2 字段可忽略。

Schema 名

• openclaw.ui_inspector.state.v1
• openclaw.ui_inspector.observation.v1
• openclaw.ui_inspector.action.v1
• openclaw.ui_inspector.element.v1
• openclaw.ui_inspector.element_catalog.v1
• openclaw.ui_inspector.action_flow.v1
• openclaw.ui_inspector.flow.v1（原有）

交给 AI 编程工具

优先提供：

1. action_flow.json — 动作序列、目标和证据关联；异步证据不冒充精确 after state
2. element_catalog.json — logical_name、结构化 locator 候选、唯一性结果
3. 需要排障时再附对应 states/<id>/ 或旧 steps/ 下的 tree/locatable/screen

不要只丢一堆无动作语义的定时 dump。

diagnostics.capture_validator 会报告缺失的生产级定位器、目标元素引用、原始事件关联、根窗口按键目标、列表大容器点击及丢失的输入事务，避免“动作录到了”被误判为“可以稳定生成代码”。

当前能力边界

能力	状态
click	已实现（browser + windows）
fill/type 聚合	已实现
press_key（Enter/Tab/Esc 等）	已实现
checkpoint	已实现
navigation	部分（URL 变化观察）
其余动作类型	Schema 预留，capability=schema_only
手机录制	未实现
截图像素级脱敏	未实现（敏感页在 meta 标记 may_contain_sensitive_data）

敏感信息

• 密码框 / token / cookie / 手机号 / 邮箱等会脱敏，不写入 action_flow / catalog 明文。
• 截图无法可靠脱敏时标记风险；可用配置关闭敏感页截图保存。
• 禁止在测试或产物中使用真实客户数据。

WeCom Adapter

企业微信专用规则在 adapters/wecom.py：

• WeWorkWindow → profile wecom
• SearchResultWindow2 → profile wecom_search
• Warm cache key = profile + hwnd，主窗 warm 不会假装搜索浮层已暖
• Recorder 捕获点击目标前不执行全量 warm；warm 属于 dump/checkpoint/live 验证路径

Legacy 间隔模式

Legacy 能力仅供底层兼容与开发排障，不在标准界面暴露。 默认动作驱动模式下，heartbeat 只做输入聚合刷新，相同 fingerprint 不新增 State，不产生 Action。

冒烟与单测

python tools/ui_inspector/smoke_check.py
python -m pytest tools/ui_inspector/tests -q

目录结构

ui_inspector/
  core/                  # 三端共用模型、管线、策略
  surfaces/              # browser / windows / future mobile
  evidence/              # 异步证据协调
  locators/              # Locator Catalog 与稳定性
  storage/               # 新旧采集格式读写
  diagnostics/           # 指标与通用质量检查
  compatibility/         # v1/legacy 兼容入口
  ui/                    # 新 UI facade；app.py 暂保留为 Tk 兼容入口
  adapters/              # 可选产品增强，不参与核心正确性
  tests/                 # unit / contract / integration / e2e

models/、recorder/、drivers/ 等旧路径暂时保留为兼容实现；新入口已从 surfaces/、core/ 和 storage/ 访问，后续可按模块逐步内收而不破坏现有技能。

暖树：ensure_ui_ready（kit≥1.2.6）；整页 dump：kit≥1.2.11。