chore: archive tools/ui_inspector snapshot before migration removal.
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>
This commit is contained in:
@@ -1,14 +1,34 @@
|
||||
# OpenClaw UI Inspector（桌面试验版 v0.8.1）
|
||||
# OpenClaw UI Inspector（UI Automation Recorder v0.16.0）
|
||||
|
||||
> **有焦点的窗口 = 采集目标**（与大小无关）。
|
||||
> 企微暖树：**只调用** `jiangchang_desktop_wake.ensure_ui_ready`（与技能同路径），不复制注入逻辑。
|
||||
> 主窗 → profile `wecom`；搜索浮层 `SearchResultWindow2` → profile `wecom_search`（需 kit≥1.2.6）。
|
||||
默认窗口采用窄长控制台布局：停靠到鼠标所在显示器右侧，顶部预留目标应用标题栏安全区；也可在界面中一键切换到左侧。
|
||||
|
||||
> **定位**：以人工操作为主线的开发期录制器，产出可交给 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
|
||||
# 建议使用已安装 jiangchang-platform-kit>=1.2.5 的 Python（与宿主共享 venv 一致）
|
||||
python tools/ui_inspector/run.py --scene demo
|
||||
```
|
||||
|
||||
@@ -16,34 +36,154 @@ python tools/ui_inspector/run.py --scene demo
|
||||
|
||||
```powershell
|
||||
pip install -r tools/ui_inspector/requirements.txt
|
||||
# 企微自动暖树（强烈建议）
|
||||
pip install "jiangchang-platform-kit>=1.2.5" # 或指向你们 Gitea/本地 index
|
||||
pip install "jiangchang-platform-kit>=1.2.11"
|
||||
```
|
||||
|
||||
## 规则
|
||||
## 录制流程
|
||||
|
||||
1. 焦点在谁就采谁（排除 Inspector 自身 hwnd）
|
||||
2. **自动拾取默认勾选**；点「开始流程」后先 **5 秒倒数**，请在此期间点击目标窗
|
||||
3. Inspector **保持置顶**便于看进度；置顶 ≠ 焦点，不因此改采本面板
|
||||
4. **不强制最大化**目标窗，保持操作者当时的大小/位置（仅最小化时会还原）
|
||||
5. 不会因为窗口小 / FindAll 少而改采别的软件
|
||||
6. **企微自动暖树（无感）**：识别到 `WeWorkWindow` 时，在准备/拾取前静默调用
|
||||
`ensure_ui_ready("wecom")`；已暖则快速返回。结果写入每步 `meta.json` → `dump_stats.kit_wake`
|
||||
主界面固定使用自动动作录制，只保留 **开始 / 暂停（继续）/ 结束**。Recorder 立即记录 Action，完整证据由独立后台队列异步合并采集。Inspector 自身窗口上的点击和输入不会写入目标 Action Flow。
|
||||
|
||||
## 空壳说明
|
||||
“运行状态与拾取结果”会对浏览器和桌面统一采用单步骤覆盖式显示；新动作替换上一动作，同一动作的异步证据返回后在原位置更新定位器、唯一性或失败原因。迟到的旧动作证据不会覆盖更新的步骤，完整历史始终保存在 `action_flow.json`、`actions/` 与 `element_catalog.json` 中。
|
||||
|
||||
- **已装 kit**：冷企微应被 n2-wake 暖到 `findall` 较大、`provider_cold=false`。若仍冷，看状态栏 `kit_wake: FAILED …`。
|
||||
- **未装 kit**：行为与旧版相同，可能 `findall≈2`、`provider_cold=true`；状态栏会提示未安装 platform-kit。
|
||||
引导、手动检查点和 Legacy 间隔 dump 仅作为底层兼容与开发诊断能力保留，不进入普通用户流程；旧偏好会自动迁移回自动录制。
|
||||
|
||||
## 验收建议（企微）
|
||||
## 运行时稳定性
|
||||
|
||||
1. 打开并登录桌面企业微信
|
||||
2. 启动 Inspector →「开始流程」→ 倒数内点到企微主窗
|
||||
3. 看详情区 / 第一步 `meta.json`：`kit_wake.warm=true`，`findall` 通常 ≫ 80
|
||||
4. 再搜联系人、开会话，确认 `groupbuddyname` 的 Value 能采到
|
||||
- Tk 主线程只处理界面；导航、Dump、截图、动作落盘均在后台执行。
|
||||
- 后台结果通过 UI 消息队列回传，后台线程不读取 Tk Variable 或 Widget。
|
||||
- 原始事件先追加到 `journal/raw_events.jsonl`，再进入语义 Action FIFO。
|
||||
- Action 热路径不执行完整页面 dump；慢速证据在独立队列按页面合并采集。
|
||||
- 异步证据标记为 `coalesced_eventual`，不会伪装成事件时刻的精确 after state。
|
||||
- Playwright 命令均有超时；导航失败不会被伪装成“已就绪”。
|
||||
- 浏览器使用 context 级事件桥并保留轮询回退，整页跳转前的 click 不随旧 document 丢失。
|
||||
|
||||
## 冒烟（不弹 GUI）
|
||||
## 拾取通道
|
||||
|
||||
- **浏览器**：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。
|
||||
|
||||
Reference in New Issue
Block a user