Metadata-Version: 2.5
Name: imgclickflow
Version: 0.1.1
Summary: 基于图像识别的 Windows 桌面自动化助手：截图即模板，一次编写随处运行
Project-URL: Homepage, https://github.com/honggescripts/ImgClickFlow
Project-URL: Repository, https://github.com/honggescripts/ImgClickFlow
Project-URL: Issues, https://github.com/honggescripts/ImgClickFlow/issues
Project-URL: Changelog, https://github.com/honggescripts/ImgClickFlow/blob/main/CHANGELOG.md
Author: yushihong
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: automation,gui-automation,image-recognition,opencv,rpa,template-matching,windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: numpy>=1.20
Requires-Dist: opencv-python>=4.5
Requires-Dist: pillow>=8.0
Requires-Dist: pywin32>=300; sys_platform == 'win32'
Description-Content-Type: text/markdown

# ImgClickFlow

基于图像识别的 **Windows 桌面自动化助手**。截图即模板，一行代码点按钮。

面向**没有 API、没有网页、只有图形界面**的老式 Windows 客户端：内网 ERP、
财务/政务系统、医院 HIS 等。全部计算在本机完成，**不联网、不上传任何数据**。

```python
import imgclickflow

imgclickflow.auto.click("保存")
```

## 安装

```bash
pip install imgclickflow
```

- **仅支持 Windows**（依赖 Win32 API 完成屏幕捕获与窗口操作）
- 需要 Python 3.9 及以上
- 依赖：`numpy` / `opencv-python` / `Pillow` / `pywin32`

## 快速上手

**1. 采集按钮模板** —— 把要点的按钮截成 PNG：

```bash
imgclickflow capture 保存
```

该命令会全屏截图并提示你用画图工具裁剪到只剩按钮，保存到数据目录的
`templates/保存.png`。

> ⚠️ 模板**必须是 PNG**。JPG 的有损压缩会让像素产生偏移，导致匹配失败。

**2. 写流程脚本** `my_flow.py`：

```python
import imgclickflow

imgclickflow.auto.click("登录")
imgclickflow.auto.write("用户名")
imgclickflow.auto.press("tab")
imgclickflow.auto.write("密码")
imgclickflow.auto.click("确定")
```

**3. 运行**：

```bash
imgclickflow run my_flow.py
```

## 数据目录

模板、日志、截图、报告都放在**数据目录**下，解析优先级：

| 顺序 | 来源 | 说明 |
|---|---|---|
| 1 | 显式设定 `init(data_dir=...)` | 代码里指定，优先级最高 |
| 2 | 环境变量 `IMGCLICKFLOW_HOME` | 多环境隔离与测试 |
| 3 | **调用方脚本所在目录** | 默认 —— 模板与录像就落在你的脚本旁边 |
| 4 | 当前目录已存在 `templates/` | 交互式会话（REPL / `python -c`）兜底 |
| 5 | `%LOCALAPPDATA%\ImgClickFlow` | 无调用方脚本时的兜底位置 |

也就是说，脚本放在 `D:\work\amazon\测试.py`，那么 `templates/`、`logs/`、
`screenshots_author/`、`error_snapshots/` 都出现在 `D:\work\amazon\` 下，
**与你在哪个目录执行脚本无关**。

第 3 级取的是**调用方**脚本的路径（`__main__.__file__` / `sys.argv[0]`），
不是本库自身的；并且会排除 site-packages 与标准库目录。
数据**绝不写进 site-packages** —— 那里升级即清空、多用户互相污染、
系统级安装下还可能没有写权限。

固定数据目录：

```python
import imgclickflow
imgclickflow.init(data_dir=r"D:\my_flows")
```

## 模板图库（多目录查找）

模板按**有序路径列表**查找，先命中先用。默认只有一个目录（脚本同级 `templates/`）：

```python
import imgclickflow

imgclickflow.set_template_dir(r"D:\项目图库")                    # 只用一个图库
imgclickflow.set_template_dirs([r"D:\项目图库", r"D:\公共图库"])   # 分层：先项目、后公共
imgclickflow.add_template_dir(r"D:\公共图库")                     # 追加一个兜底图库
imgclickflow.clear_template_dirs()                              # 恢复默认

imgclickflow.get_template_dirs()                               # 查看当前搜索路径
```

单次调用指定图库，**不影响全局设置**：

```python
imgclickflow.auto.click("保存", template_dir=r"D:\另一个图库")
imgclickflow.auto.click(r"D:\图库\btn")        # 绝对路径，带不带 .png 都行
```

找不到图片时抛 `TemplateNotFound`（继承 `FileNotFoundError`，旧代码的
`except FileNotFoundError` 依然有效），错误信息里会**列出所有搜索过的目录**，
并带 `name` 与 `searched` 两个属性便于程序化处理。

## 命令行

```bash
imgclickflow doctor           # 环境诊断：分辨率、DPI、依赖、模板搜索路径
imgclickflow capture <名称>    # 采集一个按钮模板
imgclickflow run <脚本>        # 运行流程脚本
imgclickflow help             # 完整使用手册
imgclickflow --version
```

也支持 `python -m imgclickflow`。

## 常用 API

| 方法 | 作用 |
|---|---|
| `click(名称)` / `dclick` / `rclick` | 单击 / 双击 / 右键 |
| `write(文本)` | 输入文本 |
| `press(键)` / `hotkey(*键)` | 按键 / 组合键 |
| `wait(名称, timeout=)` | 等待元素出现 |
| `if_see(名称)` / `else_do()` / `endif()` | 条件分支 |
| `for_data(列表)` / `end_for()` | 循环 |
| `find_all(名称)` | 返回全部坐标（批量） |
| `snap(备注)` | 保存当前屏幕截图 |
| `cron("17:30", 函数)` | 定时执行 |

链式编排：

```python
imgclickflow.auto.do() \
    .click("查询") \
    .wait("结果列表") \
    .click("导出") \
    .run()
```

## 环境诊断

```bash
imgclickflow doctor
```

会打印物理/逻辑分辨率、DPI 缩放系数、依赖状态、模板搜索路径与模板健康情况。
**换到新机器后建议先跑一次**，确认模板与缩放是否仍然匹配。

## 已知限制

- **仅 Windows**，非 Windows 平台 `import` 会直接报错说明原因。
- **仅支持主显示器**：程序不抓取副屏内容，多屏环境下请把目标窗口放在主屏。
- **界面改版后模板会失效**：主题换色、控件位移、缩放比例变化都需要重新采集模板。
- 需要程序自身具备 DPI 感知能力；若被其他已设置 DPI 感知的宿主进程加载，
  缩放补偿可能不生效。

## 许可

MPL-2.0（Mozilla Public License 2.0）。可商用、可与闭源代码一起分发；
但**修改本项目文件本身**时，需公开该文件的改动。
