Metadata-Version: 2.5
Name: imgclickflow
Version: 0.1.0
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 | 环境变量 `IMGCLICKFLOW_HOME` | 多环境隔离与测试 |
| 2 | 当前目录已存在 `templates/` | 兼容「脚本与模板放一起」的老用法 |
| 3 | `%LOCALAPPDATA%\ImgClickFlow` | 默认位置 |

数据**绝不写进 site-packages** —— 那里升级即清空、多用户互相污染、
系统级安装下还可能没有写权限。

固定数据目录：

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

## 命令行

```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）。可商用、可与闭源代码一起分发；
但**修改本项目文件本身**时，需公开该文件的改动。
