131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# autodemo-win (示教式自动化原型)
|
||
|
||
MIT Licensed Python 3.10+ 原型，覆盖录制→事件/多模态存储→LLM 归纳 DSL→UI 自动化执行的端到端流程，面向 Windows 10/11。
|
||
|
||
## 功能概览
|
||
- 录制层：pynput 捕获鼠标 click（不记录 move）、键盘文本缓冲（800ms 无输入自动 flush 为 text_input）、窗口焦点变更；UIA hit-test/前台窗口信息；浅层控件树摘要（深度<=3）。
|
||
- 多模态采集：ffmpeg(优先)/mss+opencv 录屏 video.mp4，关键事件截图 frames/，鼠标附近与命中控件裁剪 frames_crops/，UIA selector+树快照 ui_snapshots/。
|
||
- 数据层：统一 pydantic schema，events.jsonl 每条含高精度 ts、视频偏移、窗口/鼠标/UIA/帧路径等；manifest.json 记录分辨率、fps、起止时间、目录。
|
||
- 归纳层：LLM 抽象 `LLMClient`，支持文本-only（默认 `DummyLLM`）与多模态（配置 `OPENAI_API_KEY` 时附带关键帧 base64）两种模式，输出严格符合 `dsl_schema.json` 的 DSL。
|
||
- DSL：YAML/JSON，支持 `steps/params/assertions/retry_policy/waits` 与 `if/else`、`for_each`。
|
||
- 执行层：基于 `uiautomation`，支持 click/type/set_value/assert_exists/wait_for，等待重试，dry-run 打印动作，窗口标题白名单保护。
|
||
- CLI：`record` / `infer` / `run` 三个子命令；pytest 覆盖最小校验。
|
||
|
||
## 目录结构
|
||
```
|
||
requirements.txt
|
||
autodemo/
|
||
__init__.py
|
||
__main__.py
|
||
schema.py
|
||
screen_recorder.py
|
||
recorder.py
|
||
llm.py
|
||
dsl.py
|
||
executor.py
|
||
cli.py
|
||
tests/
|
||
test_schema.py
|
||
test_dummy_llm.py
|
||
test_executor_dry.py
|
||
```
|
||
|
||
## 安装
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 快速使用
|
||
1) 录制演示（按 F9 结束）：
|
||
```bash
|
||
python -m autodemo record --out sessions --hotkey F9 --fps 12 --screen 0
|
||
```
|
||
会生成 `sessions/<session_id>/`：
|
||
- `manifest.json`：分辨率、fps、起止时间、各子目录。
|
||
- `video.mp4`：全程录屏。
|
||
- `events.jsonl`：逐行事件（ts/event_type/window/mouse/text/uia/frame_paths/ui_snapshot/video_time_offset_ms）。
|
||
- `frames/`：关键事件截图。
|
||
- `frames_crops/`：鼠标周边与命中控件区域裁剪（若可得）。
|
||
- `ui_snapshots/`：UIA selector 与浅层控件树快照。
|
||
|
||
2) 归纳 DSL（文本-only 或多模态；多模态需设置 `OPENAI_API_KEY` 环境变量，默认 `OPENAI_BASE_URL=https://api.wgetai.com/v1`、`model=gpt-5.1-high`）：
|
||
```bash
|
||
# 示例：对现有录制目录直接归纳
|
||
python -m autodemo.infer --session-dir sessions\4693c5e5-6a29-4edc-9ca4-d0ef88e00e0a --out dsl.json --model gpt-5.1-high --timeout 300
|
||
```
|
||
可选参数：
|
||
- `--api-key` / `OPENAI_API_KEY`：多模态时的 LLM Key
|
||
- `--base-url` / `OPENAI_BASE_URL`：代理/中转地址（默认 https://api.wgetai.com/v1）
|
||
- `--model`：模型名（默认 gpt-5.1-high）
|
||
|
||
3) 执行 DSL（白名单标题保护，建议 dry-run 先验证）：
|
||
```bash
|
||
python -m autodemo run --dsl dsl.json --allow-title "新标签页 - Google Chrome" --dry-run
|
||
```
|
||
去掉 `--dry-run` 即真实执行。
|
||
执行时日志与快照：
|
||
- 执行器会将每一步的结果写入 `artifacts/executor_log.jsonl`，包含时间、动作、目标、尝试次数、成功/失败、错误等。
|
||
- 成功/失败都会保存截图到 `artifacts/screenshots/`，并保存 UIA 树摘要到 `artifacts/ui_trees/`，便于排查。
|
||
可选视觉校验（模板匹配）：
|
||
- 在 DSL step 中添加 `expected_screen`，例如：
|
||
```yaml
|
||
steps:
|
||
- action: click
|
||
target: {Name: "确定", ControlType: "Button"}
|
||
expected_screen:
|
||
template_path: templates/ok_button.png
|
||
threshold: 0.8
|
||
```
|
||
执行器会在 UIA 定位后先做模板匹配，未通过则按重试策略重试或报错。
|
||
|
||
### 参数覆盖示例
|
||
```bash
|
||
python -m autodemo run --dsl flow.yaml --allow-title "记事本|Notepad" --params "{\"text\": \"hello\"}"
|
||
```
|
||
|
||
## DSL 字段示例（YAML）
|
||
```yaml
|
||
params:
|
||
text: "示例参数"
|
||
steps:
|
||
- action: click
|
||
target: {AutomationId: "15", ControlType: "Edit"}
|
||
- action: type
|
||
target: {AutomationId: "15"}
|
||
text: "{{text}}"
|
||
- if_condition: need_confirm
|
||
steps:
|
||
- action: click
|
||
target: {Name: "确定"}
|
||
else_steps:
|
||
- action: click
|
||
target: {Name: "取消"}
|
||
- for_each: items
|
||
steps:
|
||
- action: type
|
||
target: {ClassName: "Edit"}
|
||
text: "{{item}}"
|
||
assertions:
|
||
- "输入框非空"
|
||
retry_policy: {max_attempts: 2, interval: 1.0}
|
||
waits: {appear: 5.0, disappear: 5.0}
|
||
```
|
||
|
||
## 测试
|
||
```bash
|
||
pytest -q
|
||
```
|
||
|
||
## 组件说明
|
||
- `recorder.py`：pynput 事件采集 + UIA hit-test/树快照 + mss/ffmpeg 录屏 + 关键帧截图裁剪 + events/manifest 持久化。
|
||
- `screen_recorder.py`：录屏封装，优先 ffmpeg(gdigrab)，降级 mss+opencv。
|
||
- `llm.py`：`LLMClient` 接口与 `DummyLLM` 简单规则生成；`render_prompt` 可用于接入真实 LLM。
|
||
- `dsl.py`：DSL YAML 存取。
|
||
- `executor.py`：uiautomation 执行器，含等待、重试、dry-run、安全白名单。
|
||
- `cli.py`：命令行入口，子命令 `record`/`infer`/`run`。
|
||
|
||
## 已知限制
|
||
- 录制依赖全局 hook（pynput），需管理员权限时请自行处理。
|
||
- DummyLLM 仅作示范，真实归纳需接入外部 LLM。
|
||
- 执行器查找控件基于浅层条件匹配，复杂 UI 需扩展匹配策略或增强控件路径。
|