---
name: easy-flow
description: Easy Flow CLI(autoflow):监控文件夹,图片自动压缩/转格式/按规则归档。任务即目录(task.toml+script.lua),支持批量执行、处理历史查询、配置体检与旧版迁移。安装桌面版(≥0.5.0)后任意终端直接调用,无需其他依赖。
---

# Easy Flow CLI(autoflow)

跨平台文件自动化工具:监控指定文件夹,新图片落盘并稳定后自动处理——WebP/AVIF 有损压缩(可设目标体积)、格式转换、按 EXIF 拍摄日期/相机/尺寸等规则归档。**安装桌面版后,任意终端直接使用 `autoflow` 命令**,单文件 exe、无需其他依赖。

## 安装

下载并安装桌面版安装包(**v0.5.0 及以上**含 CLI,per-machine 装 `C:\Program Files\Easy Flow`,官网 https://pinnadash.com/easyflow.html 直链下载):

- CLI `autoflow.exe` 随安装包落安装目录并加入系统 PATH(新开的终端立即可用)
- 卸载时自动移除

数据全部存本机(Windows `%APPDATA%\auto_flow\`,任务目录 + SQLite 历史 + 滚动日志),无任何网络请求(AI 生成脚本功能除外,其密钥由用户自行配置)。GUI 与 CLI 共用同一份数据,引擎单实例互斥:GUI 与 `autoflow watch` 同一时刻只能运行一个监控。

## 命令清单

### task — 任务管理(任务即目录:`<数据目录>/tasks/<任务名>/`)

```powershell
# 新建任务:生成任务目录(task.toml + 默认脚本 + AI_PROMPT.md)
autoflow task create pics --watch D:/pics --output D:/pics_out

# 列出任务(含脚本状态);--json 输出机器可读数组
autoflow task list --json

# 编译级校验脚本(报错含行号);启用/停用/删除任务
autoflow task validate pics
autoflow task disable pics
autoflow task enable pics
autoflow task remove pics
```

### watch — 常驻监控(前台,Ctrl-C 退出;`--detach` 后台常驻)

```powershell
autoflow watch
```

### run — 对已有文件批量执行一次(不监控)

```powershell
autoflow run --all            # 全部启用任务
autoflow run --task pics      # 只跑某个任务
autoflow run D:/some/dir     # 对指定目录跑默认任务
```

### history — 查询处理历史(SQLite)

```powershell
autoflow history --limit 20              # 最近 20 条
autoflow history --task pics --json     # 按任务过滤,机器可读
```

### logs / doctor / status / migrate

```powershell
autoflow logs --lines 50                # 查看运行日志(<数据目录>/auto_flow.log 末尾)
autoflow doctor                         # 配置/任务/脚本/路径全量体检,输出问题清单
autoflow status                         # 引擎与任务状态(key=value 行)
autoflow migrate                        # v0.2 表单任务一键迁移为目录任务(幂等)
```

## 机器可读输出(AI/脚本调用约定)

全局 `--json`:`autoflow task list --json`、`autoflow history --json` 等输出纯 JSON(stdout 不带任何表格或提示行),字段自描述、直接解析即可。

## 脚本模型(给 AI 的关键约定)

每个任务是一个目录:`task.toml`(监控/输出目录与开关)+ `script.lua`(处理逻辑)+ `AI_PROMPT.md`(自包含 API 文档)。**把整个任务目录交给任何 AI 工具,描述需求即可让它写/改 `script.lua`**:

- 脚本运行在沙箱:没有文件 IO、不能联网、不能执行外部命令;只能调用 `autoflow.probe()`(尺寸/EXIF/日期)并返回"操作表"(convert/save),落盘全部由引擎执行
- 绝不删除原图:成功原图归档到监控目录 `_originals/`,失败隔离到 `_autoflow_failed/`
- 改完用 `autoflow task validate <任务名>` 自查,再用 `autoflow run --task <任务名>` 试跑