1. 快速入门

启动程序

双击 KeyMouseMate.exe 即可启动。

首次运行时，若 Windows 弹出安全警告，请点击「仍要运行」或「更多信息 → 仍要运行」。

第一个方案（5 步完成）

1. 新建方案：菜单「方案 → 新建方案」，输入名称，保存。
2. 新建节点：右侧「节点库」→「新建」，输入名称。
3. 添加动作：弹出节点编辑器 →「添加动作」，选择「左键单击」，设置坐标，保存。
4. 添加步骤：在主界面「方案步骤」面板 →「添加步骤」，选择刚创建的节点。
5. 运行：点击「▶ 运行」按钮或按 Ctrl+Shift+S。

2. 三层模型

程序以三层结构组织自动化任务：

公共模板与私有实例

动作与节点都有两种形态，界面上用徽标区分：

快照（自包含）：公共实例在关联模板的同时，会把自己所用模板的全部字段副本一并存入方案文件。因此方案文件本身即完整可运行——单个 .json 直接分享给别人即可，接收方无需预先拥有相同的动作库 / 节点库。

• 保存 / 改名模板 → 所有引用它的节点与方案快照自动刷新。
• 删除模板 → 引用处自动降级为私有副本，方案仍可运行。
• 编辑公共实例 → 每次都弹二次确认：修改模板＝全局生效（所有引用处一起变）、仅改这一份＝转为私有（只影响当前方案）、取消＝不改（默认聚焦取消，防误触）。
• 新建默认私有：新增的动作 / 节点默认是私有实例；需要复用时点「转为公共」，填名称与分类后写入库，重名须改名。
• 导入分享的方案：命中本地同 ID 的模板则保持公共并刷新快照，未命中的自动降级为私有副本，导入后即可直接运行。

3. 界面布局

• 状态栏：左侧显示版权，右侧红色坐标实时跟随鼠标。
• 日志区：可上下拖动分割条调整高度。
• 折叠：点击「◁ 显示方案」/「▷ 显示节点」可折叠对应侧栏，节省空间。

3.5 典型场景示例

示例一：自动登录网页

场景：打开浏览器，自动填写用户名密码并登录。

方案「自动登录」：
  步骤1「打开网站」(1轮)
    节点「登录-打开网页」
      ├─ action: open_website → https://example.com/login
      └─ action: wait → 3s（等页面加载）

  步骤2「输入凭证并登录」(1轮)
    节点「登录-填表单」
      ├─ action: ocr_check → 关键词"用户名", 区域追踪
      ├─ action: tab_click → 点击用户名输入框
      ├─ action: input_text → 用户名文本（可用 {变量.用户名}）
      ├─ action: tab_click → 点击密码输入框
      ├─ action: input_text → 从密码库取密文
      └─ action: left_click → 坐标点击[登录]按钮

示例二：批量表单提交 + 弹窗处理

场景：批量处理 100 条数据，每条提交后可能弹出确认或错误框。

方案「批量提交」：
  步骤1「循环提交」(100轮)
    节点「提交操作」
      ├─ action: wait → 0.5s
      ├─ action: ocr_check → 关键词"提交按钮", 点击
      ├─ action: wait → 1s
      └─ action: goto → 回到本节点第1步（loop_count控制总轮数）

  监控规则1「错误弹窗处理」：
    关键词：错误,报错,异常,数据不规范
    处理器：节点「处理-报错弹窗」（点击[确定]后返回）

  监控规则2「确认弹窗」：
    关键词：确认,确定,是否继续
    处理器：节点「处理-确认弹窗」（点击[确定]后返回）

示例三：定时巡检报表

场景：工作日每天上午9点自动运行巡检脚本。

方案「每日巡检」：
  步骤1「启动巡检」(1轮)
    节点「启动程序」
      └─ action: open_file → D:\scripts\inspection.py

  步骤2「等待结果」(1轮)
    节点「等待完成」
      └─ action: wait_text → 区域识别"完成"或"error"，超时300s

  监控规则「意外弹窗」：
    关键词：异常,崩溃,退出
    处理器：节点「处理-异常」（发送通知）

定时调度：
  Cron：0 0 9 * * 1-5 *（工作日 9:00:00）
  关联方案：每日巡检

4. 动作类型全解

4.1 鼠标类

4.2 输入类

4.3 等待类

4.4 OCR 类

匹配模式：

• 任意（OR）：命中任一关键词即成功
• 全部（AND）：所有关键词都出现才成功

4.5 流程控制类

4.6 系统类

4.7 新增动作详解与典型场景

下面对近期新增的 13 种动作（动作总数已达 33 种）展开说明主要用法与应用场景，参数速查见上文 4.1～4.6 各表。

组合示例：自动取数流水线——一条流程串起多个新动作：

5. 执行次数

所有动作类型均支持执行次数（loop_count），默认 1 次。

设置位置

• 节点编辑器 → 编辑动作 → "执行次数" 字段
• 动作管理器（全局库）→ 编辑 → "执行次数" 字段
• 动作列表表格中均有"执行次数"列，支持右键「列设置」隐藏或调整宽度

行为

• 动作执行 N 次后，继续下一个动作。
• 每次执行之间自动等待"后置等待"时间。
• 例：动作 A 执行次数=2，动作 B 执行次数=1 → 顺序为 A→A→B。

6. 条件分支与工作流

6.1 步骤级条件

每个步骤可设置执行条件，决定该步骤是否运行：

条件不满足时的处理：

• 跳过：执行下一个步骤（默认）
• 跳转到步骤 #N：跳到指定步骤
• 终止方案：方案停止，状态显示"已完成"

6.2 动作出错处理

6.3 动作级跳转（节点内）

OCR识别 和 跳转 动作支持节点内跳转：

• 命中→跳转：OCR 命中后跳到节点内第 N 个动作
• 未命中→跳转：OCR 未命中后跳到第 N 个动作
• 可组合形成节点内循环（如：跳转回第 1 个动作）

7. 变量与表达式

7.1 内置变量

7.2 表达式语法

表达式用于步骤执行条件，不使用 eval，安全受限：

运算符：== != > < >= <= contains matches startswith endswith and or not

matches 支持正则：右侧用 re: 前缀

{ocr.last} matches 're:错误代码:\s*\d+'

7.3 示例

{变量.已登录} == true
{ocr.last} contains '成功'
{轮次} > 3 and {变量.停止} != true
{ocr.last} matches 're:订单号:\s*\w+'

7.4 模板替换

在「输入文本」「按键」「打开文件」「设置变量」的值中可写 {变量名}，执行时自动替换；未知变量原样保留，不报错。

8. OCR 识别

8.1 双引擎

auto 模式：优先 RapidOCR，失败时自动回退到 PaddleOCR。

8.2 OCR 设置

菜单「工具 → OCR 设置」：

• 引擎切换：RapidOCR / PaddleOCR / auto
• 置信度阈值：低于此值的识别行被过滤（0.0~1.0，默认 0.5）
• 调试日志：运行时输出每次 OCR 识别结果预览，方便排查识别问题
• 区域测试：选择区域 → 点击"测试识别"，查看识别文本和置信度

8.3 小区域放大

自动检测：识别区域过小时（< 200px 宽或高），自动放大 1.5~2 倍再识别，提高小文字识别率。

9. 监控规则（弹窗处理）

9.1 工作原理

监控规则在后台线程运行，与主流程完全独立：

9.2 创建监控规则

菜单「工具 → 监控规则」→ 新建：

9.3 典型场景：批量提交 + 弹窗处理

9.4 调试技巧

1. 打开「OCR 调试日志」，日志中出现 🔍 [规则名] OCR: ... 查看识别内容
2. 在节点中添加 ocr_check 动作，将识别全文存入变量并截图到桌面，确认区域是否正确
3. 若触发过于频繁，增大 冷却时间

10. 定时调度（Cron）

10.1 创建调度

菜单「工具 → 定时调度」→ 新建：

调度包含：Cron 表达式（7 字段：秒 分 时 日 月 周 年）、启动延迟、关联方案、调度名称。

10.2 Cron 表达式速查

10.3 高级语法

10.4 运行状态

• 调度器在后台精确等待下次触发时刻（非轮询），到达时自动运行关联方案。
• 托盘图标和日志显示调度状态。
• 主窗口关闭后调度继续运行（托盘模式下）。

11. 热键

11.1 默认热键

11.2 修改热键

菜单「工具 → 热键设置」→ 选择功能 → 点击"录制" → 按下新的组合键 → 保存。

11.3 追踪热键详解

Ctrl+Shift+C 是三阶段追踪：

1. 第一次按下：开始追踪左上角（按钮文字显示"追踪左上角"）
2. 第二次按下：切换到追踪右下角（按钮文字显示"追踪右下角"）
3. 第三次按下：锁定当前坐标（按钮文字显示"已锁定"）

适用于：动作编辑坐标、步骤 OCR 条件区域、监控规则区域、OCR 设置测试区域。

Ctrl+Shift+X 仅用于拖动动作的终点追踪。

12. 密码管理

菜单「工具 → 密码管理」：

• 添加：输入名称和明文密码 → 加密存储到 userdata/passwords.db
• 编辑/删除：右键管理已有条目
• 在动作中使用：输入文本动作 → 点击"密码库…" → 选择条目

执行时程序自动：①从数据库取出明文 ②粘贴到目标位置 ③清空剪贴板（防止泄露）④日志中显示 *****（打码，不显示实际密码）。

13. 坐标追踪

13.1 追踪区域（Ctrl+Shift+C）

适用于所有需要坐标的位置：动作的左上角/右下角、步骤 OCR 条件区域、监控规则区域、OCR 设置测试区域。

1. 在坐标输入框中点击"追踪区域"按钮（或按 Ctrl+Shift+C）
2. 移动鼠标到目标左上角，再次按 Ctrl+Shift+C 锁定左上角
3. 移动鼠标到目标右下角，再次按 Ctrl+Shift+C 锁定右下角
4. 按钮文字实时显示当前阶段（追踪左上角 / 追踪右下角 / 已锁定）

13.2 追踪终点（Ctrl+Shift+X）

用于拖动动作的终点：移动鼠标到目标位置，按 Ctrl+Shift+X 锁定，起点不受影响。

13.3 独立追踪

两个按钮独立追踪，可同时追踪起点和终点而不互相干扰。

14. 数据管理：新建 / 复制 / 重命名 / 删除

14.1 新建

14.2 复制规则

14.3 重命名

• 节点重命名：自动同步所有引用该节点的方案中的步骤（按 ID 与名称双匹配）。
• 动作重命名：旧文件自动删除，新名称文件写入。

14.4 删除

• 被引用的节点/动作/方案删除时会列出受影响对象并要求确认。
• 方案删除后不影响节点和动作文件。

14.5 列设置

所有表格（动作列表、节点列表、方案列表）均支持右键 →「列设置… 」：勾选显示/隐藏列，拖拽调整列宽，设置自动保存。

14.6 右键菜单操作

除列设置外，各表格还根据上下文提供操作菜单：

部分菜单项可能需要先选中对应行才可用（显示为灰色）。

15. 效果叠加（执行回显）

菜单「设置 → 效果设置」：运行方案时在主窗口上方叠加半透明视觉效果，由执行引擎触发，用于调试和观察执行状态：

可独立开关每种效果，调整颜色（Hex 颜色值）和透明度。

16. 实时可视化（键鼠可视化）

由独立工具 KeyMouseViz 有机融合而来的内置模块（rpa/viz.py），随主程序启动常驻、随主程序退出关闭，无需管理员权限，支持高 DPI / 多显示器。

16.1 功能概览

默认全部关闭，随程序启动常驻待命，按需开启。

16.2 开启方式（四处入口，状态实时同步）

1. 菜单：设置 → ☑「启用浮动工具栏」/「设置可视化…」
2. 托盘：托盘图标右键 →「可视化」子菜单（6 项开关 + 浮动工具栏）
3. 浮动工具栏：点击图标开关对应功能
4. 热键：见 11.2 可视化热键

任意一处切换，其余三处勾选状态即时同步。

16.3 浮动工具栏

屏幕悬浮工具条（默认屏幕右下角，可拖动），提供 6 个功能按钮：定位/高亮、点击效果、键盘、坐标、聚光灯、放大镜。图标为内置线条绘制；若 config/floatbar/*.svg 存在则优先使用 SVG。图标颜色可在可视化设置中分别调整。

16.4 设置可视化对话框

菜单「设置 → 设置可视化…」或热键 Ctrl+Shift+F1 打开：

16.5 与「效果叠加」的区别

两者相互独立、可同时使用。

17. 托盘与关闭行为

17.1 托盘图标

启动后系统托盘出现程序图标，右键菜单：

• 显示主窗口：恢复主窗口
• 暂停 / 恢复：与主界面按钮等效
• 停止执行：停止当前方案
• 可视化：子菜单（鼠标高亮 / 点击效果 / 按键显示 / 鼠标坐标 / 聚光灯 / 放大镜 / 浮动工具栏，勾选状态与菜单、浮栏实时同步）
• 关闭行为设置…：修改关闭窗口时的行为
• 彻底退出：直接退出程序（可视化模块一并停止）

17.2 关闭行为

点击窗口 X 按钮时，可配置行为（首次询问，可勾选"记住选择"）：

18. 迁移旧方案

菜单「方案 → 迁移旧方案」：

扫描旧版 schemes/ 目录，自动转换：

• 主任务 → 节点「主流程-方案名
• 弹窗规则 → 监控规则 + 处理节点「弹窗处理-方案名-规则名
• 子动作、点击坐标、密码引用全部保留
• 旧版"总轮次" → 步骤循环次数

幂等：已存在的同名内容自动跳过，可重复执行。

19. 常见问题

19.1 首次运行安全警告

Windows SmartScreen 可能提示"未知发布者"，点击「更多信息 → 仍要运行」即可。

19.2 OCR 识别中文差

进入「工具 → OCR 设置」，将引擎切换为RapidOCR（默认引擎，中文效果最佳）。

19.3 坐标不准确

可能是 DPI 缩放导致。请右键 KeyMouseMate.exe → 属性 → 兼容性 → 更改高 DPI 设置 → 勾选「替代高 DPI 缩放行为」，由应用程序控制。

19.4 修改后不生效

关闭程序，重新打开即可。若涉及共享节点，注意其他方案引用该节点时也会同步更新。

19.5 打包后样式与原版不同

这是正常现象，程序已内置 Fusion 样式，确保在任何 Windows 环境下外观一致。

20. 目录结构与数据布局

程序目录分为两大块：程序设置（config/）与使用数据（userdata/）。打包后均位于 EXE 同级；源码模式下为项目根目录：

20.1 旧版自动迁移

首次启动检测到旧布局时自动迁移，无需手动操作（旧文件保留 .bak 备份）：

• userdata/config/config.json → config/config.json
• userdata/config/passwords.db → userdata/passwords.db
• userdata/floatbar/ → config/floatbar/
• config.json 中的 plan_order / node_order / default_plan → userdata/data.json

20.2 备份与迁移

• 完整备份：同时复制 config/ 与 userdata/ 两个文件夹。
• 只备数据：复制 userdata/（方案/节点/动作/密码/排序全部在内）。

20.3 二维码

「帮助 → 关于」的二维码图片按顺序查找：config/qrcode.png → EXE 同目录 → 程序目录。将图片命名为 qrcode.png 放入 config/ 即可显示。