影刀RPA 流程注释与文档规范让流程可读可维护作者林焱什么情况用你三个月前写的影刀RPA流程现在打开一看——满屏幕的指令块完全想不起来每一步在干什么同事接手你的流程看了半天不知道某个子流程是干嘛的流程出了bug但没人能看懂逻辑只能从头重写流程注释和文档是解决这些问题的根本手段。写代码不写注释等于给未来的自己挖坑。影刀RPA虽然是非代码的可视化工具但同样需要注释和文档规范。本文讲清楚影刀RPA中怎么给流程加注释、怎么写子流程说明、怎么做流程文档让流程可读可维护。怎么做一、影刀RPA的注释能力影刀RPA提供了三种注释方式方式位置用途指令备注每个指令的备注栏说明该指令做什么流程说明流程编辑区的说明文本说明整个流程或某段逻辑Python注释Python代码块内代码级注释二、指令备注的规范每个关键指令都应该加备注备注内容遵循为什么优于做什么的原则店群矩阵自动化突破运营极限❌ 差的备注 【打开网页】备注打开网页 【点击】备注点击按钮 【设置变量】备注设置变量 ✅ 好的备注 【打开网页】备注打开后台管理系统首页需先确保VPN已连接 【点击】备注点击导出按钮触发数据下载。此按钮有2秒延迟才响应 【设置变量】备注设置重试次数上限来自配置文件config.json的retry字段备注规范一句话说明这个指令的目的不是描述动作本身如果有特殊注意事项加在后面如果是临时方案或待优化标注TODO:或FIXME:三、流程说明的使用在流程编辑区的空白处可以添加说明文本块 流程说明 流程名称电商商品数据采集 功能采集某电商平台指定类目的商品信息包括名称、价格、销量、评分 创建日期2026-07-01 最后更新2026-07-01 作者林焱 输入参数 - category_url: 类目页面URL - max_pages: 最大采集页数默认10 输出 - result.xlsx: 采集结果文件 - log.txt: 运行日志 注意事项 1. 需要先登录账号Cookie保存在cookies.json 2. 每页采集间隔3-5秒随机延时 3. 如果遇到验证码暂停流程等待人工处理 四、子流程的文档规范每个子流程都应该有清晰的输入输出说明子流程名称scrape_product_detail 功能说明采集单个商品详情页的完整信息 输入参数 - product_url (str): 商品详情页URL - timeout (int): 页面加载超时时间默认30秒 输出参数 - product_data (dict): 商品数据字典 - name: 商品名称 - price: 价格float - stock: 库存int - images: 图片URL列表 - specs: 规格参数字典 - status (str): 采集状态 success/fail - error_msg (str): 失败时的错误信息 调用示例 主流程中传入product_url获取product_data和status 如果statusfail记录error_msg并跳过该商品五、Python代码块的注释规范# # 功能从网页文本中提取价格数值# 输入raw_text (str) - 网页采集的原始文本如128.50或1,234元# 输出price (float) - 提取的价格数值如128.50或1234.0# 异常如果无法提取数字返回0.0# defextract_price(raw_text):importre# 去除所有非数字字符保留小数点和负号# 注意\xa0是不间断空格网页中常见cleanedre.sub(r[^\d.\-],,raw_text.replace(\xa0,))ifnotcleanedorcleaned-:return0.0try:returnfloat(cleaned)exceptValueError:return0.0# # 功能批量处理商品列表补充价格字段# 输入products (list[dict]) - 商品字典列表# 输出list[dict] - 补充了price_float字段的商品列表# defenrich_prices(products):result[]forproductinproducts:# 复制原始数据不修改原列表itemproduct.copy()# 提取价格raw_priceitem.get(price_text,)item[price_float]extract_price(raw_price)# 如果提取失败标记异常ifitem[price_float]0.0andraw_price:item[price_warning]f价格提取失败{raw_price}result.append(item)returnresult六、流程文档模板每个完整流程项目应包含一份文档可以用Markdown文件存放在流程同目录# 流程文档电商商品数据采集 ## 基本信息 - 流程名称电商商品数据采集 - 版本v1.2 - 创建日期2026-07-01 - 最后更新2026-07-01 - 作者林焱 ## 功能描述 采集某电商平台指定类目的商品信息包括商品名称、价格、销量、评分、图片等 导出为Excel文件并发送邮件通知。 ## 运行环境 - 影刀RPA版本5.x - 浏览器Chrome需安装对应版本驱动 - Python依赖requests, openpyxl, pandas - 配置文件config.json需放在流程同目录 ## 输入参数 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | category_url | str | 是 | - | 类目页面URL | | max_pages | int | 否 | 10 | 最大采集页数 | | output_dir | str | 否 | ./output | 输出目录 | ## 输出 | 文件 | 说明 | |------|------| | result_YYYYMMDD.xlsx | 采集结果 | | log_YYYYMMDD.txt | 运行日志 | | error_YYYYMMDD.txt | 错误记录 | ## 流程结构 1. 初始化读取配置、创建目录、初始化日志 2. 登录加载Cookie、验证登录态 3. 采集循环翻页采集每页商品列表 4. 详情对每个商品采集详情页 5. 导出数据清洗、写入Excel 6. 通知发送邮件通知 ## 子流程清单 | 子流程 | 功能 | 输入 | 输出 | |--------|------|------|------| | init_env | 初始化环境 | config_path | config_dict | | check_login | 检查登录状态 | cookie_file | is_login(bool) | | scrape_list | 采集列表页 | url, page | items_list | | scrape_detail | 采集详情页 | url | product_dict | | export_excel | 导出Excel | data, path | filepath | | send_email | 发送通知 | to, subject, body | success(bool) | ## 常见问题 1. Cookie过期重新登录网站导出新Cookie 2. 验证码出现流程暂停手动处理 3. 网络超时自动重试3次仍失败则跳过 ## 变更记录 | 日期 | 版本 | 变更内容 | |------|------|----------| | 2026-07-01 | v1.0 | 初始版本 | | 2026-07-01 | v1.1 | 增加重试机制 | | 2026-07-01 | v1.2 | 增加邮件通知功能 |七、命名规范好的命名本身就是最好的注释❌ 差的命名 变量名a, b, c, data1, data2, temp, x 子流程名流程1, 子流程A, 处理 ✅ 好的命名 变量名product_list, current_page, retry_count, error_log 子流程名scrape_product_list, parse_detail_page, export_to_excel 文件名电商采集_20260701.xlsx, config_prod.json命名规范变量名用英文小写下划线product_list子流程名用动词开头scrape_xxx,parse_xxx,export_xxx常量用全大写MAX_RETRY 3布尔变量用is/has/can开头is_login,has_next_page八、版本管理习惯在流程说明中维护版本记录 v1.0 (2026-07-01) - 初始版本实现基本采集功能 v1.1 (2026-07-01) - 增加重试机制修复翻页bug v1.2 (2026-07-01) - 增加邮件通知优化日志格式 TODO: - [ ] 增加多线程采集 - [ ] 支持代理IP切换 - [ ] 增加数据去重功能有什么坑坑1注释和代码不一致现象备注写着点击搜索按钮但实际指令点的是筛选按钮。代码改了注释没改。temu店群自动化报活动案例原因修改流程时只改了指令没改备注是最常见的维护问题。解决每次修改指令后同步检查备注是否需要更新。养成改代码即改注释的习惯。如果备注和代码不一致比没有备注更危险——会误导排查者。坑2备注写太多反而看不清流程现象每个指令都加了大段备注流程编辑区密密麻麻全是文字反而看不清指令结构。原因把所有信息都塞进备注没有区分关键信息和显而易见的信息。解决备注只写关键信息——为什么这么做、有什么注意事项。显而易见的操作如设置变量count0不需要备注。一个子流程的入口处加一段总结性说明比每行都加备注更有用。坑3子流程没有输入输出说明现象打开一个子流程不知道需要传什么参数、会返回什么只能通读全部逻辑才知道。解决每个子流程的第一行加一个说明指令【输出调试信息】或说明文本写清楚输入参数和输出参数。即使影刀有子流程的参数定义界面文字说明也更直观。坑4流程文档放在本机不共享现象流程文档写在本地电脑上换电脑或同事接手时找不到文档。解决把文档和流程放在一起——如果流程在影刀云端文档也放在流程的说明中。如果是本地流程文档放在流程同目录下。重要的配置和注意事项直接写在流程的说明文本块里不依赖外部文件。坑5临时方案没有标注现象流程里有个临时的处理方式当时想以后再改结果忘了半年后还在用。解决临时方案必须标注TODO:或FIXME:前缀在备注中写明原因和计划备注FIXME: 临时使用固定URL待接口开发完成后改为动态获取。计划v1.3版本修复。 这样每次打开流程都能看到待办事项不会被遗忘。