ARTICLE · 1065907
MiniRPA 完整版程序开发说明文档
版本：v1.0
适用平台：Windows 10 / 11
文档定位：面向开发人员与集成人员的技术说明
---
1. 产品概述
MiniRPA 是一套面向 Windows 桌面环境的自动化流程开发工具，用于构建、调试和发布 RPA（Robotic Process Automation）流程。支持的自动化领域包括：
· 网页自动化（浏览器操作、数据抓取）
· 桌面自动化（鼠标、键盘、窗口、UI 控件、图像识别）
· Office 自动化（Excel / WPS 读写）
· 文件与数据处理（文本、CSV、INI、JSON、PDF、数据表）
· 网络与协议（HTTP、邮件、IMAP、FTP/SFTP、IE 浏览器）
用户通过可视化界面组合命令生成 Python 代码，实时运行与调试，可打包为独立 EXE 分发。
---
2. 运行环境
项 要求
操作系统 Windows 10 / 11（64 位）
Python 3.10 及以上
浏览器 Chromium（内置）/ Chrome / Edge / Firefox / WebKit
Office Microsoft Excel 2016+ 或 WPS 表格（可选）
IE IE 11（仅在 IE 自动化时需要）
---
3. 功能模块
3.1 主界面
· 三栏布局：命令树（左） / 代码编辑器 + 运行日志（中） / 属性面板（右）
· 顶部工具栏：文件、运行、定时、批量、发布、抓取器、AI 助手、UDF 设计、系统设置
· 属性面板：参数可视化配置，支持分组、动作切换、文件选择、元素选择
3.2 命令库
内置命令覆盖 30 个分类、450+ 条命令，主要分类：
组 分类
基本 基本命令、流程控制、日志
鼠标键盘 鼠标、键盘
界面操作 窗口、图像、界面元素
软件自动化 网页自动化、IE 浏览器、Excel
数据处理 字符串、数组、时间、数学、JSON、集合、数据表
文件处理 文件、INI、CSV、PDF
系统操作 系统、应用、对话框、剪贴板
网络 网络、邮件、IMAP、FTP
3.3 抓取器
工具 用途
元素抓取器 抓取网页元素，生成元素库条目
数据抓取向导 引导式抓取列表型 / 表格型数据
UI 抓取器 抓取桌面控件（pywinauto/UIA）
抓取器支持两种运行模式：
· CDP 模式：连接已运行的 Chrome / Edge（浏览器进程独立保留）
· Playwright 模式：由工具启动内置浏览器
3.4 AI 助手
支持两种后端：
· DeepSeek 云 API：填写 API Key 即可用
· Ollama 本地：本地模型（默认 qwen2.5:7b）
功能：UiBot 代码转换、自然语言转 Python 代码、流式输出、可自定义 System Prompt。
3.5 UDF 表单设计器
可视化拖拽生成自定义对话框（JSON 配置），支持 8 种控件：
input / password / textarea / select / checkbox / radio / file / time
流程中调用 udf_dialog() 弹出表单，返回 {字段名: 值} 字典。
3.6 辅助功能
功能 说明
代码自动补全 输入时弹出建议，支持对象方法 / 关键字 / 内置变量
代码片段库 保存常用代码片段，双击插入
录制器 监听鼠标键盘，生成 desktop.xxx 代码
定时调度 间隔模式 / 每日模式
批量运行 顺序执行多个流程文件
变量面板 运行后回显变量值
历史面板 每次运行的耗时 / 结果
---
4. 命令 JSON 结构
命令以 JSON 文件定义，字段如下：
字段 类型 说明
key string 命令唯一标识（必填）
category string 所属分类
order int 分类内排序值
usage string 用法说明
syntax string 语法示例
notes string 注意事项
comment string 代码行尾注释
template string 代码生成模板
nested bool 是否包裹选中代码
body_indent int nested 命令的 body 缩进空格数（默认 4）
actions dict 动作定义（可选）
params list 参数列表
参数结构
字段 说明
group 必选 / 可选
name 参数名（对应模板 {name}）
label 界面显示标签
type text / number / bool / combo / action / element / file
kind var 表示变量引用（不加引号）
default 默认值
options combo / action 的候选项 [[label, value], ...]
min / max 数字范围
placeholder 输入提示
file_filter / file_mode file 类型的过滤器与模式
---
5. 用户侧 API 约定
流程代码运行时，以下对象自动注入：
对象 用途
browser 浏览器会话管理（Playwright）
desktop 桌面自动化（鼠标 / 键盘 / 窗口 / UI 元素 / 图像）
excel Excel / WPS 读写
api HTTP 请求
mail SMTP 邮件发送
imap IMAP 邮件接收
ftp FTP / SFTP
ie IE 浏览器 COM
log 日志输出
logger 日志对象（info / warn / error）
flow 子流程调用
udf_dialog 自定义表单
常见调用示例
```python
# 网页
hWeb = browser.open("chromium", url="https://example.com")
browser.click_element(hWeb, "#submit")
browser.input_element(hWeb, "#kw", "python", clear=True)
text = browser.text(hWeb, "标题")
data = browser.scrape(hWeb, "热搜榜", max_pages=5)
rows = browser.scrape_table(hWeb, {"tag": "TABLE", "idx": 0})
# 桌面
desktop.click(100, 200)
desktop.input("hello")
wnd = desktop.window_find("*记事本*")
desktop.window_activate(wnd, topmost="on")
desktop.ui_input(target, "hello")
# Excel
wb = excel.open("@RE\"data.xlsx\"", visible=False)
excel.set_cell(wb, "Sheet1", "A1", "hello")
excel.write_range(wb, "Sheet1", "B1", [[1, 2], [3, 4]])
wb.close(save_changes=True)
# HTTP
resp = api.get("https://api.example.com/data", timeout=30)
api.download("https://example.com/file.zip", "D:/data/file.zip")
```
---
6. 路径约定
写法 展开为
@RE"config.json" <项目根>/RE/config.json
@RE"sub/a.xlsx" <项目根>/RE/sub/a.xlsx
@"D:/temp/a.txt" D:/temp/a.txt
所有路径类参数（file / excel / csv / pdf / image）均支持该简写。
---
7. 项目目录结构
```
MiniRPA/
├─ main.py 主入口
├─ requirements.txt 依赖清单
├─ editor/ 编辑器层
│ ├─ main_window/ 主窗口（组合）
│ ├─ commands/ 命令库
│ ├─ ai_*.py AI 助手
│ ├─ udf_designer.py UDF 表单设计器
│ ├─ publish.py EXE 打包
│ └─ ...
├─ engine/ 运行时引擎
│ ├─ runner.py 流程执行器
│ ├─ browser/ 浏览器自动化
│ ├─ excel/ Excel 引擎（前后台）
│ ├─ desktop.py 桌面自动化
│ ├─ ie_com.py IE 自动化
│ └─ ...
├─ tools/
│ ├─ picker/ 网页抓取器
│ └─ ui_picker/ 桌面 UI 抓取器
├─ docs/ 文档
├─ flows/ 流程文件（.json）
├─ elements/ 网页元素库
├─ elements_ui/ 桌面元素库
├─ RE/ 运行时数据目录
└─ dist/ 发布输出
```
---
8. 打包发布
通过编辑器工具栏「发布」按钮或 editor/publish.py 打包为独立 EXE。
特性 说明
输出方式 单文件 EXE（PyInstaller onefile）
控制台 默认隐藏，错误以 Windows 弹窗提示
依赖裁剪 自动排除 tkinter / Qt 等无关模块
Qt 按需 仅当流程使用 udf_dialog 时打包 PySide6
运行目录 EXE 首次运行自动创建 RE/ 和 flows/
路径重定向 流程内的 D:/.../RE/xxx 自动替换为 EXE 同级 RE/xxx
---
9. 快捷键
快捷键 功能
Ctrl+N 新建流程
Ctrl+O 打开流程
Ctrl+S 保存
Ctrl+Shift+S 另存为
F5 运行全部代码
F6 运行选中区域
Shift+F5 停止
Ctrl+B 发布 EXE
Ctrl+Shift+P 打开抓取器
Ctrl+Shift+A AI 助手
Ctrl+Shift+R 批量运行
Ctrl+L 清空日志
Tab / Shift+Tab 缩进 / 反缩进（对齐到 4 空格位）
---
10. 运行模式
10.1 流程文件
· 格式：JSON
· 结构：{"code": "<Python 代码>"}
· 存储位置：flows/ 目录
· 双击关联：通过「安装右键菜单.bat」注册
10.2 Excel 引擎
模式 参数 特点
后台 visible=False 基于 openpyxl，不启动 Excel 进程
前台 visible=True 基于 COM，支持 Excel / WPS
bind_active() 可绑定已打开的 Excel / WPS 实例。
10.3 浏览器会话
模式 特点
CDP 连接外部 Chrome / Edge，浏览器进程独立
Playwright 由工具启动内置浏览器，进程随工具关闭
---
11. 技术约束
· 单流程单线程：每个流程独立执行，不共享变量
· 同步执行：命令按顺序执行，无异步
· 文件格式：流程与元素库均为 UTF-8 JSON
· 路径编码：支持中文路径，内部统一正斜杠 /
· 变量作用域：流程内全局，子流程独立上下文
---
12. 术语表
术语 说明
流程 一个可执行的 .json 文件
命令 可视化配置的参数模板，生成 Python 代码
元素 网页或桌面的一个控件定义
元素库 元素的集合，供命令复用
UDF 用户自定义表单
抓取器 用于提取元素特征的辅助工具
嵌套命令 会包裹选中代码的命令（如 if / for）
会话 一个浏览器窗口或标签页的连接对象
---
期待后续