# OpenClaw UI Inspector（UI Automation Recorder v0.16.0）

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

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

## 核心模型

```text
人工操作
  → 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 出错时无需重走人工流程 |

## 启动

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

依赖：

```powershell
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`，质量检查会明确告警。
- **手机**：未实现，不得宣称已支持

## 输出目录（双写兼容）

```text
_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**。

## 冒烟与单测

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

## 目录结构

```text
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。