chendelian
633ecff4e2
Keep the last in-template copy on main so history can restore it; product continues in jiangchang-ui-recorder. Co-authored-by: Cursor <cursoragent@cursor.com>
190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# 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。
|