# AnClicker

**Repository Path**: code-tailor/AnClicker

## Basic Information

- **Project Name**: AnClicker
- **Description**: Windows 自动化工作台：表格与流程图双编辑、可拖拽指令、深浅主题和长循环缓存保护。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# An Clicker

An Clicker 是一款基于 PySide6 的 Windows、macOS、Linux 桌面自动化工具，由 Clicker 项目扩展而来。启动入口为 `main.py`，主窗口控制器位于 `Start_Win.py`。

项目同步发布于 [Gitee](https://gitee.com/YiZhiYanYi/AnClicker) 与 [GitHub](https://github.com/714248411/AnClicker)；应用内“反馈及建议2”直接打开 Gitee 仓库的 [Issues](https://gitee.com/YiZhiYanYi/AnClicker/issues)。

## 当前架构

### 流程图复刻与运行语义

流程图按“先插入节点、再自由连线”的方式工作。节点可从指令栏拖入，也可在画布空白处右键创建；左侧五分之一区域用于拉入前置线，右侧五分之一区域用于拉出后置线。节点支持多选、框选、移动、调整大小、备注、双击配置和保存为模板，画布支持平移、30%–250% 缩放及适应视图。

连线角色会随数据库保存：条件判断使用“是/否”，循环和条件循环使用“循环体/完成”。循环体可以回连到循环节点；运行时不再按表格位置猜测分支，而是逐条沿已保存连线执行。流程完成后，表格和多功能视图会立即联动刷新，多功能内容中同时生成可核对的流程连线说明。

主窗口采用从左到右层次清晰的三栏布局，并提供五个互相联动的工作视图：

- 左侧为可搜索、可拖拽的指令树，内容完全由 `instructions.registry` 生成。
- 指令栏在“表格”和“流程图”中显示，可从指令栏拖拽添加，并可从工具栏移到左侧/右侧或折叠。
- 表格页采用上下布局：上方维护指令，下方持续显示运行日志；中间分隔条可拖动调整高度。
- 右侧为统一的“控制与操作”面板，包含循环设置、运行、暂停/恢复和结束任务。
- 五个视图依次为“主界面、表格、流程图、多功能、导航”；原初级视图的功能入口集中到最后的“导航”页，不再保留预览视图。
- “流程图”支持先拖拽或右键插入未连接指令，再自由连线；节点左侧五分之一区域拉入线，右侧五分之一区域拉出线，右键节点可删除全部、前置或后置流程连接。
- 流程允许分支、汇合以及由循环节点控制的回连。所有节点都从开始可达且最终通向结束后，系统按稳定顺序生成表格和多功能内容。
- 新增“循环、条件判断、条件循环”控制节点；循环框直接显示次数，条件节点使用菱形，上方输出为“是”、下方输出为“否”，箭头尺寸也已加大。
- 顶部工具栏可切换默认深色与浅色主题，主题采用灰阶和蓝紫强调色、圆角控件，并自动保存选择；五个视图可使用 `Ctrl+1` 至 `Ctrl+5` 打开。

正式流程从“开始”沿持久化连线运行到“结束”。节点连线由 `graph_repository.py` 事务性保存；普通连线进入下一步，条件节点只进入“是”或“否”分支，循环节点在“循环体”和“完成”之间切换。只有包含循环或条件循环节点的结构化环路才允许保存和运行。

```text
instructions/               # 35 条独立指令及唯一注册表
├─ registry.py              # InstructionSpec 清单和惰性加载入口
├─ models.py                # InstructionDraft、CommandRecord、ExecutionContext
├─ base.py                  # 参数编辑器与执行器统一接口
└─ <分类>/<指令名>/
   ├─ <指令名>.ui
   ├─ <指令名>_ui.py
   └─ <指令名>.py          # 独立参数窗口类和执行类
node_editor/                # 可嵌入节点画布与左侧指令树
graph_repository.py         # 命令、节点、连线和 Excel 协议
old_ins/                    # 旧导航窗口和单体指令代码，只读参考归档
```

`old_ins/` 不属于运行时模块，也不会进入打包流程。活动代码不得从该目录导入任何对象。

## 添加或维护指令

1. 在 `instructions/<分类>/<指令名>/` 中维护该指令自己的 `.ui`、生成的 `_ui.py`、参数编辑器和执行器。
2. 参数窗口通过 `InstructionDraft` 加载、校验并返回 JSON 可序列化参数，不直接拼接 SQL。
3. 执行器统一接收 `ExecutionContext + CommandRecord`，不得使用 `eval()` 读取参数。
4. 在 `instructions/registry.py` 的唯一清单中登记 `InstructionSpec`。主窗口指令树、编辑器加载、执行映射和 PyInstaller hidden imports 会自动使用此注册信息。
5. 修改 `.ui` 后使用项目虚拟环境重新生成对应 Python 文件，例如：

   ```powershell
   .\.venv\Scripts\pyside6-uic.exe instructions\键鼠\图像点击\图像点击.ui -o instructions\键鼠\图像点击\图像点击_ui.py
   ```

## 数据目录

可迁移数据统一保存在程序同级的 `data` 文件夹：

```text
data/
├─ 命令集.db     # 设置、变量、资源记录，以及命令和节点图
├─ images/       # 截图和应用自有图片
├─ exports/      # 默认导出目录
├─ logs/         # 操作日志
└─ temp/         # 可随时清理的临时文件
```

迁移或备份时复制整个 `data` 文件夹即可。`flat`、`Window`、`instructions` 和图标目录是程序静态资源。用户添加的外部资源目录与外部文件仍保留原路径引用。

Excel 导入导出采用节点协议，工作表固定为“命令、节点、连线、设置”。导入会先完整验证 JSON、指令类型、节点引用和分支拓扑，验证成功后才事务性替换数据；旧表格格式不再兼容。

## 开发与运行

优先使用项目虚拟环境：

```powershell
.\.venv\Scripts\python.exe main.py
```

依赖清单见 `requirements.txt` 和 `pyproject.toml`。生成主窗口 UI：

```powershell
.\.venv\Scripts\pyside6-uic.exe Window\mainwindow.ui -o Window\mainwindow_ui.py
```

PyInstaller 打包说明见 `packaging/打包文件说明.md`。

## 跨平台发布

- Windows：保留便携式 `data` 目录、系统提示音和全局快捷键。
- macOS：用户数据写入 `~/Library/Application Support/AnClicker`；全局快捷键不可用时自动使用界面按钮。键鼠自动化需在系统设置中授权辅助功能与屏幕录制。
- Linux：用户数据遵循 `$XDG_DATA_HOME/AnClicker`（默认 `~/.local/share/AnClicker`）；X11 下启用全局快捷键，Wayland 或无全局后端时自动使用界面按钮。
- 设置 `ANCLICKER_DATA_DIR` 可在三个平台显式指定数据目录。

当前完整版本为 **v1.1.5**，新增旧版 Excel 单分支指令转换，并整合识别精度、重复次数等数字输入框裁切修复、小化运行控制台、旧版图像点击布局、黑灰蓝深色主题、变量管理及键鼠录制修复。主题图标左侧的“小化”按钮只显示控制与操作及可伸缩运行日志；窗口与字体可缩小，退出后恢复完整界面，小化时暂时禁用运行隐藏窗口。主题选择自动记忆。完整解压下载包后即可运行，无需先安装旧版或应用补丁。首次运行会自动创建数据目录、数据库和默认配置；Windows 程序目录无写权限时自动使用用户数据目录。

旧版数据请通过“文件 → 导入”选择原 `.xlsx`，确认转换后自动备份当前指令，并在原文件旁另存“原文件名-新版.xlsx”，后续保存使用新版副本。支持已适配的十列/十一列单分支指令表，不会执行参数表达式。多个非空旧分支、跳转、未知指令或参数暂不强行转换，会提示具体原因并保留原数据。旧 `.db` 不属于本次 Excel 转换范围，不要直接覆盖新版数据库。

### 键鼠录制（v1.1.1 完善）

在“导航”右侧打开“录制”（Ctrl+6），点击开始并等待倒计时，操作结束后按 Esc、F8 或点击停止按钮。取消“F8 停止录制”可录制 F8 本身；Esc 始终用于停止，不写入结果。默认停止后自动把录制内容追加到表格、流程图与多功能，可取消自动写入，先查看预览再手动写入。录制结果与普通指令一起保存到任务工作簿，不覆盖已有内容。

可记录键盘按下/松开、组合键、功能键、小键盘、媒体键，以及鼠标移动、点击、双击、侧键、拖拽和双向滚轮。Windows 原始键码区分左右修饰键及小键盘回车，保留精细滚轮增量。鼠标移动每 10ms 采样，单次最多 20000 个事件；按键、点击及滚轮不降采样，回放时间仍受系统负载影响。

请勿录制密码等敏感输入。macOS 需开启辅助功能及输入监控权限；Linux 全局录制目前需 X11。原始键码需在对应系统回放；硬件 Fn、Ctrl+Alt+Del、安全桌面及被驱动截获的操作无法保证录制/回放，输入法候选结果也取决于回放时状态。

### 变量管理

导航 → 变量，或按 Ctrl+Shift+V，可自定义新增、编辑、删除全局变量和普通变量。全局变量保存运行结果；普通变量在本次任务内共享，下次运行恢复初始值。获取时间等指令可选择变量并打开“设置变量”。旧变量自动保留为全局变量，升级前请备份 data。

条件判断菱形：顶部拖线为“否”，右侧拖线为“是”，左侧为前置输入。上/左/右各四分之一区域可拖线，角部重叠按对角线平分，边界只触发一个方向。

执行规则：无连线按拖拽添加先后运行；有连线先执行连线流程，然后按添加先后补执行所有未运行命令（包括条件未选中的分支）。循环体仍按循环次数重复，普通汇合节点不重复补执行。

推送 `v*` 标签会触发 `.github/workflows/release.yml`，在 Windows、Linux、macOS Intel 和 Apple Silicon 原生运行器执行测试、PyInstaller 构建及实际程序首次/再次启动检查，生成四个完整软件 ZIP 并上传至 GitHub Release。发布测试同时验证窗口中的版本号与源码一致。

## 贡献者

- YanYi
- FasterThanLight
- 邮箱：714248411@qq.com
- 邮箱：federalsadler@sohu.com
- QQ：714248411
- QQ：2309636438
- QQ 群 1：84284936（[加入群聊](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=XCOQZMwDVB3y-vIz4LXdMITq-7sqGP3A&authKey=6FPrdTF0o6JIfJoc58deZ1cEWvUURazs%2FDh%2BJOz1aJI2DS%2BMFr3jRIai2%2F7bbvwN&noverify=0&group_code=84284936)）
- QQ 群 2：308994839（[加入群聊](https://qm.qq.com/q/3ih3PE16Mg)）