# ui-autoflow

**Repository Path**: staok/ui-autoflow

## Basic Information

- **Project Name**: ui-autoflow
- **Description**: 可视化 UI 自动化编排工具。录制键鼠、执行脚本、条件判断、循环、延时，按 block 编排并运行。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ui-autoflow

[English](README_EN.md) | 中文

可视化 UI 自动化编排工具。录制键鼠、执行脚本、条件判断、循环、延时，按 block 编排并运行。

| Demo 英文                                 | Demo 中文                                             | 逻辑嵌套                            |
| ----------------------------------------- | ----------------------------------------------------- | ----------------------------------- |
| <img src="assets/demo.png" alt="demo"  /> | <img src="assets/demo_zh-cn.png" alt="demo_zh-cn"  /> | <img src="assets/1.png" alt="1"  /> |



*p.s AI (Opus 4.8 High) 生成的工具，迭代多轮已经成版，有问题欢迎 Issue 或 PR。*

*p.ss 目前只支持 Win。*

## 功能

- **键鼠录制/回放**：默认全局热键 ctrl+shift+f11 开始/停止、ctrl+shift+f12 暂停（可在设置中重设为其它组合键），录制存为 JSON。软件启动后热键即生效，播放执行期间暂停录制热键监听
- **命令行脚本**：执行任意命令行，约定 stdout 返回 `true`/`false`
- **宏回放**：选择已录制的 JSON 文件回放；未指定文件或文件不存在时停止整个流程
- **延时**：单位 ms/s/min/h/d，数值 1–999，支持暂停/停止
- **条件判断（if 语义）**：依据上一脚本输出，单执行体。仅可在"执行脚本"block 后添加
- **循环（while 语义）**：脚本检查（返回 false 退出）或固定次数，单执行体可嵌套
- **项目管理**：创建/保存/加载工程（名称限制 120 字节）；启动时不打开任何工程，画布提示"请新建或打开工程"；新建名称与已有工程重名时自动加序号避免覆盖
- **未保存提示**：有未保存改动时标题的工程名后显示 `*`；此时新建/打开/关闭会提示是否放弃改动
- **运行控制**：开始/停止/暂停，运行时高亮当前 block，画布只读不可编辑
- **播放热键**：默认 ctrl+shift+f1 播放/停止工程、ctrl+shift+f2 暂停/继续播放（全局，可在设置中重设）
- **block 编号**：每个 block 按流程顺序编号，画布与日志均带 `#序号`，便于对照跟踪
- **日志**：保存日志到文件（`logs/LOG_*.txt`）、清空日志
- **录制浮窗**：录制开始/暂停/停止时置顶提示，数秒后自动隐藏；固定宽度、文字过长自动换行，可拖动
- **画布平移**：在画布空白处按住鼠标左键拖动可平移视图
- **帮助**：右上角 `?` 按钮弹出帮助窗口，简要说明操作流程与当前快捷键
- **设置面板**：自定义存放路径（工程/录制/日志）、四个热键（录制/播放，支持组合键）、回放倍速、语言、皮肤
- **多语言**：中文 / English 切换（重启生效）；画布上的 block 名称随语言本地化，与 `+` 菜单一致
- **多皮肤**：Light / Dark / Ocean / Sunset（默认 Dark），在设置面板切换，即时生效并记忆；窗口标题栏与所有弹窗随皮肤上色（Windows 深色标题栏）

## 环境要求

- Python 3.10+
- Windows / macOS / Linux（Windows 实测）
- 依赖：`pynput`

## 从源码启动

安装

```bash
cd ui-autoflow
pip install -r requirements.txt
```

启动

```bash
python src/run.py
```

## 打包 Windows 可执行文件

一键打包（双击 `build.bat`，或运行 `python build.py`）：

```bash
python build.py
```

基于 PyInstaller 生成单文件程序；中间产物放在项目内的 `build/`，最后仅把可执行文件复制到 `release/ui-autoflow.exe`，**不会清空 `release/` 目录**——exe 运行时在其所在目录生成的 `projects`/`recordings`/`logs`/`settings.json` 都会保留。未安装 PyInstaller 时脚本会自动安装。

## 使用流程

### 1. 创建工程

点击「新建」→ 输入工程名（最多 120 字节）→ 确定。工程保存为 `projects/<名称>.uiaf.json`。若名称与已有工程重名，会自动追加 ` (序号)` 并提示，避免覆盖。启动软件时默认不打开任何工程，需先新建或打开。

### 2. 编排流程

画布默认有一个「开始」节点，其下有 `+` 号。点击 `+` 选择添加 block：

| Block（`+` 菜单项） | 说明                                                           |
| ------------------- | -------------------------------------------------------------- |
| 宏回放              | 选择已录制的 json 文件回放                                     |
| 执行脚本            | 输入命令行，stdout 约定`true`/`false`                          |
| 条件                | 仅在「执行脚本」后可选；选择 is_true/is_false，体内添加子块     |
| 循环                | 脚本检查模式（返回 false 退出）或次数模式，体内添加子块         |
| 延时                | 数值 + 单位（ms/s/min/h/d）                                     |

点击 block 可编辑或删除。条件/循环 的执行体内通过 `+` 添加嵌套子块。

### 3. 录制键鼠

按 **ctrl+shift+f11** 开始/停止录制，**ctrl+shift+f12** 暂停/恢复（热键可在设置中重设）。

- 暂停时间不计入回放时间轴
- 录制文件存为 `recordings/REC_YYYYmmdd_HHMMSS.json`
- 录制浮窗在状态切换时提示，数秒后自动隐藏，可拖动到任意位置

### 4. 运行

点击「开始」或按 **ctrl+shift+f1** 按编排顺序执行：

- **暂停 / ctrl+shift+f2**：当前 block 执行完后暂停（延时可在中途暂停）
- **停止 / 再按 ctrl+shift+f1**：当前 block 执行完后停止整个流程
- 播放热键为全局热键，可在设置中重设
- 运行时画布只读，不可编辑

运行时画布高亮当前执行的 block；日志与画布均以 `#序号` 标注每个 block，便于对照。

### 5. 日志

日志面板在底部，显示执行进度。点击「保存日志」保存到 `logs/LOG_YYYYmmdd_HHMMSS.txt`，点击「清空日志」清空。

### 6. 设置

点击「设置」打开设置面板：

- **存放路径**：工程 / 录制 / 日志目录，留空则默认为程序（源码或可执行文件）根目录
- **热键**：录制开始/停止、录制暂停/继续、播放/停止工程、暂停/继续播放；支持组合键（如 `f11`、`ctrl+f11`、`ctrl+shift+f1`）；热键中的修饰键/功能键不会被录入宏
- **回放倍速**：宏回放速度（0.1–10x）
- **语言**：中文 / English（切换后重启生效）
- **皮肤**：Light / Dark / Ocean / Sunset（默认 Dark）

设置保存到程序根目录的 `settings.json`。路径、热键、倍速、皮肤即时生效。

## 脚本返回值约定

脚本 block 与循环/判断的检查脚本，通过 stdout 返回值：

- stdout 去除首尾空白后为 `true`（不区分大小写）→ 真
- 为 `false` → 假
- 其它内容 → 视为无明确布尔值（判断块按假处理）

示例（Windows cmd）：

p.s 也可以自己写脚本（做一些事情、一些检查），就非常灵活了。

```bat
echo true
```

## 条件判断语义（if）

仅可在「执行脚本」block 之后添加（主线或条件/循环的执行体内均可）。配置 is_true/is_false：

- is_true：上一脚本返回 `true` → 执行体内子块；否则跳过
- is_false：上一脚本返回 `false` → 执行体内子块；否则跳过

等价 `if (条件) { 执行体 }`。执行体跑完后继续判断块后面的主线逻辑。

## 循环语义（while）

两种退出模式：

- **脚本检查**：每轮循环开始前执行检查命令，返回 `false` 退出，`true` 继续执行循环体。等价 `while(检查返回true) { 循环体 }`。
- **次数**：执行指定次数后退出。

循环体可嵌套任意 block。循环结束后继续循环块后面的主线逻辑。

## 目录结构

```
ui-autoflow/
├── build.py            打包脚本（生成单文件可执行程序）
├── build.bat           一键打包（双击运行 build.py）
├── src/                源代码
│   ├── run.py          启动入口 / 打包入口
│   ├── models.py       数据模型
│   ├── settings.py     设置读写（路径/热键/倍速/语言）
│   ├── i18n.py         多语言
│   ├── skins.py        皮肤（颜色主题）
│   ├── project_store.py 工程序列化
│   ├── recorder.py     键鼠录制（可配置组合热键，待机监听）
│   ├── player.py       键鼠回放（支持倍速）
│   ├── script_runner.py 脚本执行
│   ├── orchestrator.py  执行引擎
│   └── gui/            GUI 模块
│       ├── app.py          主窗口
│       ├── canvas.py       可视化画布（可拖动平移）
│       ├── block_dialogs.py block 编辑对话框
│       ├── settings_dialog.py 设置面板
│       ├── help_dialog.py    帮助窗口
│       ├── recorder_overlay.py 录制浮窗（可拖动）
│       ├── runner_panel.py 工具栏
│       └── project_manager.py 工程管理
├── test/               测试脚本
├── projects/           工程文件（.uiaf.json）
├── recordings/         录制文件（REC_*.json）
└── logs/               日志文件（LOG_*.txt）
```



## 待办

- T1 block 拖拽重排序
- T2 支持 Mac（包括从源码启动，包括一键生成打包生成可执行文件的脚本）



## 其它类似开源工具

有的功能比较单调。

* [github.com/taojy123/KeymouseGo](https://github.com/taojy123/KeymouseGo)
* .etc