企业官网建设流程全解析

• GUI 自动化
• 浏览器控制
• 工作流自动化

导读

本篇是 TagUI 官方文档 docs/advanced.rst（Advanced Concepts）的完整实战化解读，面向已能编写基础 flow 的开发者与 RPA 工程师。你将系统掌握六大进阶能力：用-report选项把每次运行结果沉淀为可审计的 CSV 报告与 HTML 日志；用"本地—工作流—全局"三层策略从容处理自动化中的各类异常；用 Datatable 与对象仓库实现"一次编写、多行数据批量执行"和"数据与流程解耦"；通过子流（subflow）模块化拆解大型工作流；以及 turbo 加速、OCR 视觉自动化、Python 深度集成、调试日志与云端运行等高级技巧。文中所有结论均对照当前仓库源码给出依据，可直接落地到你的真实业务中。

保存运行结果：-report选项与运行审计

基本用法

TagUI 默认只在终端输出运行日志（文本形式）。如果需要把每次运行的完整结果留存下来，用于审计、复盘或集中管理，可以在运行 flow 时追加-report（简写-r）选项：

tagui my_flow.tag -report

加上该选项后，TagUI 会做两件事：

1. 生成一份 HTML 格式的日志（由文本 log 转换而来），便于在浏览器中分享查看；
2. 将每次运行的摘要追加写入tagui/src/tagui_report.csv，一行对应一次运行。

CSV 报告中的字段

tagui_report.csv中每次运行会记录一行，包含以下信息：

源码级实现依据

上述行为在仓库中均有对应实现：

• 选项解析位于启动脚本 src/tagui：脚本逐一检查命令行参数-report/-r，命中后将其从参数列表中移除，并置环境变量tagui_html_report=true；Windows 版对应逻辑在 src/tagui.cmd 中。
• 报告生成器是 src/tagui_report.php：它从my_flow.log中提取START - automation started -、FINISH - automation finished -时间戳以及ERROR -错误信息，写入tagui_report.csv（表头为"#","WORKFLOW","START TIME","TIME TAKEN","ERROR STATUS","LOG FILE","USER ID"）；同时把文本 log 转成带样式的 HTML 文件，并用正则清除 ANSI 颜色码，错误状态显示为红色、开始/结束信息分别用蓝/绿色标注。若运行出错且自动截图已生成（my_flow_error.png），HTML 日志还会内嵌该错误截图（见 src/tagui_report.php）。
• 用户身份由 src/tagui 在运行结束时通过tagui_user_id="$(id -gn)\\$(id -un)"取得，并调用php -q tagui_report.php "$1" "$tagui_user_id"完成写入。

需要注意的是，-report生成的 CSV 路径固定为tagui/src/tagui_report.csv，且每次生成的 HTML 日志会以_序号.html的形式保留多份副本，避免被下一次运行覆盖（见 src/tagui_report.php），非常适合作为集中审计的原始数据源。

处理异常与错误：三种由浅入深的策略

当自动化执行"不按剧本走"时，TagUI 提供三层异常处理机制，按粒度从细到粗排列。

第一层：本地错误处理（Local Error Handling）

在 flow 内部用if条件针对特定场景做精细判断，属于"细粒度"异常处理。例如：判断某个 UI 元素是否缺失，缺失则执行备选步骤。一个工作流中可以穿插多个这样的局部检查，从而对每个风险点单独兜底。

// 示例：元素不存在时走备选路径 if not present('submit_button') echo submit button missing, trying alternative click alternative_submit

第二层：工作流错误处理（Workflow Error Handling）

利用 shell 的退出码语义，把多个 flow 串成"出错则补救、成功则善后"的链路：

Windows（命令提示符）示例：

call tagui flow.tag || tagui error.tag call tagui flow.tag && tagui success.tag

macOS / Linux（终端）示例：

tagui flow.tag || tagui error.tag tagui flow.tag && tagui success.tag

其语义为：||右侧的error.tag仅在flow.tag运行出错时执行；&&右侧的success.tag仅在flow.tag成功时执行。TagUI 在检测到期望的 UI 元素缺失（此时会自动截图保存）或遇到其他未知错误时，会主动抛出错误并让进程以非零状态退出，从而触发||分支。

第三层：全局错误处理（Global Error Handling）

通过配置 TagUI，使每一次运行结束后都执行统一的特殊处理——例如把-report产生的数据和文件同步到指定文件夹或 API 端点，用于集中的错误/成功判定，典型场景是把所有自动化运行记录汇总到中央存储做审计。该策略作用于所有 TagUI flow，粒度最粗但覆盖面最全。

实战组合建议

• 关键业务节点用本地处理做精细校验；
• 流程整体成败用工作流处理做分流（配合 docs/advanced.rst 中-report的 HTML 日志留存证据）；
• 团队级审计需求用全局处理统一收口。

Datatable：用 CSV 驱动批量自动化

Datatable 本质上是 CSV 文件，用于让同一个 flow 以不同输入反复运行多次，是"参数化批量执行"的核心机制。

Datatable 的形态

一个名为trade_data.csv的 Datatable 示例：

# trade,username,password,pair,size,direction 1,Trade USDSGD,test_account,12345678,USDSGD,10000,BUY 2,Trade USDSGD,test_account,12345678,USDJPY,1000,SELL 3,Trade EURUSD,test_account,12345678,EURUSD,100000,BUY

第一行是表头（列名），后续每行是一组输入数据。注意第一列可以是行号，也可以是普通业务字段。

运行方式

tagui my_flow.tag trade_data.csv

TagUI 会对 Datatable 中除表头外的每一行数据，把my_flow.tag完整运行一遍。在 flow 内部，trade、username、password、pair、size、direction等列名可以直接当作变量使用（如同本地对象仓库中的变量），其值自动取自当前运行对应的那一行。

用iteration变量区分轮次

当需要区分"第几轮运行"时，使用内置变量iteration：

echo current iteration: `iteration` if iteration equals to 1 // go to login URL and do the login steps www.xero.com // do rest of the steps for every iteration

典型用途是"第一轮先登录，之后每轮复用会话"，避免每行数据都重复登录。

仓库中的真实示例

• 示例 flow flows/samples/6_datatables.tag 展示了完整用法：它把form_data.csv中每一行的firstname/lastname依次填入表单并点击提交。运行方式为tagui 6_datatables.tag form_data.csv，配套数据文件是 flows/samples/form_data.csv。
• 解析器 src/tagui_parse.php 通过环境变量custom_csv_file读取 Datatable，逐行用fgetcsv解析；随后在 src/tagui_parse.php 把每一列的列名清洗为合法变量名（空格转下划线、剔除非法字符、数字开头自动加下划线前缀），再以var 列名 = '值'注入生成的 JavaScript 脚本；具体取哪一列由环境变量tagui_data_set决定（src/tagui_parse.php）。

提示：若同时使用 Datatable 与本地/全局对象仓库，解析器会对行数不足的列做补位处理（src/tagui_parse.php），确保变量都能取到值。

对象仓库（Object Repository）：数据与流程解耦

对象仓库是可选的 CSV 文件，用来存放 flow 中使用的变量（含登录信息等个人数据）。它帮助你：把"私人数据"从 flow 中剥离出来，并在多个 flow 之间共享公共信息，一处修改、处处生效。

本地仓库与全局仓库

本地仓库的优先级高于全局仓库：同名对象以本地定义为准。

仓库文件格式

object,definition email,user-email-textbox create account,btn btn--green btn-xl signup-btn

第一列为对象名，第二列为定义（可以是元素标识、XPath、图片文件名等）。flow 中的对象名会被直接替换为定义后再执行。

例如，假设user-email-textbox是某个网页文本输入框的标识符，那么在 flow 中可以这样使用：

type `email` as my_email@email.com

仓库中的真实示例

仓库自带的 flows/samples/tagui_local.csv 展示了丰富用法：除普通对象（email→quick_email、password→quick_pass）外，还支持把 XPath 存为对象（facebook_link→//*[@id="profile_full"]//a），甚至可以把一整条步骤存为对象（click link→click `facebook_link`），实现步骤级复用。

解析器 src/tagui_parse.php 的加载逻辑印证了优先级规则：先尝试加载tagui_local.csv（路径为 flow 所在目录），再加载tagui_global.csv，两者按顺序合并进同一变量表，后加载的同名条目不会覆盖先加载的本地条目，从而保证本地优先。

在 flow 内运行子流：模块化你的 RPA

面对复杂场景，可以把一个大型工作流拆分为多个子流（subflow）文件，甚至让子流再调用子流，实现多层模块化。常见动机包括：子流在多处复用、把特定步骤序列独立成文件便于组织、以及把 Python / JavaScript 代码与函数放入独立子流（配合py begin/py finish代码块）。

基本调用

tagui login_crm.tag

子流也可以存放在子文件夹中：

// Windows 示例 tagui CRM\login.tag // Mac / Linux 示例 tagui CRM/login.tag

父子流之间的变量传递

父 flow 中定义的变量在子 flow 中可直接访问，反之亦然：

// 此时 username 和 password 变量在 login.tag 中可用 username = 'jennifer'; password = '12345678'; tagui login.tag // 也可以分行定义变量 username = 'jennifer' password = '12345678' tagui login.tag // 在 login.tag 中定义并回传变量给父 flow 使用 echo `login_result`

注意：子 flow 中通过echo `变量名`输出（并配合反引号包裹）即可把值暴露给父 flow。

用变量驱动"多段子流"设计

可以把多个步骤序列合并进同一个子流，由父 flow 设置action变量决定执行哪一段：

// crm_steps.tag if action equals to 'login' do some steps do some more steps else if action equals to 'report' do some steps do some more steps else if action equals to 'logout' do some steps do some more steps else echo ERROR - action undefined

父 flow 中只需action = 'login'再调用tagui crm_steps.tag，即可按需执行对应分支。这是把"多个入口"收敛进"一个子流"的推荐模式。

底层机制

子流调用（tagui步骤）在解析阶段由 src/tagui_parse.php 的expand_intent()函数展开：先把原始 flow 展开为.raw中间文件，再对展开后的内容做后续解析，最终生成可执行的 JavaScript。这也是下方"调试日志"中.raw文件的来源。

Turbo 模式：10 倍速运行（谨慎使用）

用法

tagui flow.tag -turbo # 或简写 tagui flow.tag -t

启动脚本 src/tagui 会在参数列表任意位置识别-turbo/-t，并设置环境变量tagui_turbo_mode=true；解析器在 src/tagui_parse.php 依据该变量跳过正常速度所需的延迟（如两次迭代之间重启浏览器等），从而实现约 10 倍的执行速度。

必须知道的代价

大多数网站和桌面应用并不是为"超人速度"设计的。如果自动化运行速度超过它们设计与测试的上限，很可能出现：字段和数据没有正确填写、预期校验未触发、表单提交缺数据、甚至账号被封锁等。而且问题可能随机出现——在同一台电脑上正常、在另一台 CPU 速度不同的电脑上却失败。因此官方明确不推荐在生产环境默认使用 turbo 模式：省下的是廉价的机器时间，赔上的可能是昂贵的人工排查时间。

适用场景（务必先充分测试）

• 从应用/网页中做数据采集；
• 在能可靠承受超高速输入的 Web 应用上做数据录入；
• 聊天机器人作为后端为用户执行 RPA；
• 快速原型验证；
• RPA 竞赛、黑客松等场景。

官方建议：在使用前针对你的具体用例做充分测试，确认无副作用后再启用。

视觉自动化技巧：using ocr与图像定位

用 OCR 按"屏幕上的文字"交互

很多步骤支持在末尾追加using ocr（或大写using OCR），指示 TagUI 借助 OCR（光学字符识别）在屏幕上按文字定位 UI 元素。支持的步骤包括：click、rclick、dclick、hover、type、select、read、snap、exist()、present()。

click Submit using ocr if exist('Special Offer using ocr') click Add To Cart using OCR // select 步骤的多种组合用法 select Dress Color using OCR as Dark Blue using OCR select dress_color.png as Bright Pink using ocr select Dress Color using OCR as dark_black.png select dress_color.png as bright_white.png

从源码看，OCR 模式的识别位于 src/tagui.sikuli/tagui.py：当定位符（locator）以'using ocr'结尾时，TagUI 会剥离该后缀并改用 OCR 文本匹配方式在屏幕（或截图）中寻找目标。

透明背景技巧

如果把某个 UI 元素的.png图片背景用图像编辑器处理为 100% 透明，TagUI 就能无视元素实际背景、稳定地命中目标（常用于背景会变化的页面元素）。

反向技巧：清空前景做动态 OCR

反过来，也可以把某个锚点元素（如一个边框/框架）附近的前景内容移除，让空出来的区域用于read步骤 OCR 读取不断变化的内容——例如固定一个截图框，持续读取其中动态变化的数字。

在 flow 中编写 Python

TagUI 的py步骤可以在 flow 中直接执行 Python 代码（底层通过命令行调用python，因此需要单独安装 Python并确保python在 PATH 中）。Python 的print()输出（stdout）会被捕获并存入 TagUI 变量py_result。

单行py步骤

py a=1 py b=2 py c=a+b py print(c) echo `py_result`

py begin/py finish代码块

py begin a=1 b=2 c=a+b print(c) py finish echo `py_result`

py begin/py finish包裹的整段代码会被整体送入 Python 执行，适合较长的代码段。解析器 src/tagui_parse.php 通过跟踪py begin/py finish标记来识别代码块边界，并且支持在if/ 循环中以缩进方式嵌套py begin块（见 src/tagui_parse.php 的缩进追踪逻辑）。

把 TagUI 变量传入 Python：py_step()

使用辅助函数py_step()可以拼接动态变量传入 Python：

phone = 1234567 py_step('phone = ' + phone) py print(phone) echo `py_result` name = 'Donald' py_step('name = "' + name + '"') py print(name) echo `py_result`

注意字符串变量需要手动加引号包裹。v4/v5 版本发布说明（src/media/v5.0_release.md）还指出：如果 Python 输出的是 JSON 数据，TagUI 会自动生成py_json对象，便于直接访问 JSON 元素；否则py_json为 null。

复杂数据传递：用 JSON 桥梁

当需要传递和返回多个变量时，推荐用 JavaScript 与 Python 两端的 JSON 库，把多个变量编码为 JSON 字符串互相传递：TagUI 侧（JavaScript 步骤）构造 JSON →py_step()传入 Python → Python 处理后再print()输出 JSON → TagUI 通过py_json解析回变量。这是官方建议的"多变量进出 Python"的标准做法。

创建日志文件进行深度调试

当需要进阶排错时，可以在tagui/src/目录下创建一个名为tagui_logging的空文件，之后每次运行 flow 都会额外生成三个调试文件（以my_flow为例）：

这三个文件分别对应执行日志、最终产物、解析中间态，恰好覆盖了"发生了什么、执行了什么、展开成什么"三个排查维度：若步骤结果异常查.log；若想确认某一步被翻译成怎样的 JS 逻辑查.js；若怀疑子流展开或语言翻译出错则查.raw。其中.js与.raw的生成路径可见于解析器 src/tagui_parse.php 与 src/tagui_parse.php。

在云端运行 TagUI

对于希望把自动化放到云上的使用者，TagUI 提供多条路径：

• 浏览器 / 手机云端运行：借助免费的 Google Cloud 环境，可在浏览器标签页中运行 TagUI，最多支持在浏览器不同标签页并发运行 5 个会话。
• Docker 化运行：官方维护的openiap/nodered-taguiDocker 镜像（使用edgetag 获取最新版本）可供在任意云厂商上部署，获得更强的控制力；同时也有对应的 Dockerfile 可自行构建。
• Node-RED 云端（OpenFlow）：可在免费的 Node-RED 实例（OpenFlow 平台）上运行，Docker 镜像、Dockerfile 与 OpenFlow 云服务由作者 Allan Zimmermann 维护与赞助。

这些云端方案适合需要"无人值守 + 可伸缩"的 RPA 场景，例如定时批量任务或对外提供自动化服务；在团队落地时，可进一步结合前文的-report审计与全局错误处理，构建"云端执行 + 集中审计"的完整体系。

进阶能力速查表

以上全部内容均以 docs/advanced.rst 为骨架，并结合 src/tagui、src/tagui_report.php、src/tagui_parse.php、src/tagui_config.txt 等仓库源码与 flows/samples 下的真实示例验证，可放心作为你在生产环境设计 TagUI 高级自动化方案的参考依据。

• GUI 自动化
• 浏览器控制
• 工作流自动化