影刀RPA完全指南RPA流程版本管理与迭代发布规范手册作者林焱 | 飞行社社区原创一、痛点直击为什么RPA项目需要版本管理RPA项目的版本混乱比传统软件项目更严重。原因有三个原因之一影刀RPA的流程文件是二进制格式.rpaflow你没法用Git去diff两个版本的流程文件。改了什么只能靠人工记录和记忆。原因之二RPA流程与应用系统强耦合目标网站一改版XPath全部失效。你改完XPath第二天网站又改了。没有版本管理你不知道上次改的是哪个版本也没法快速回滚。原因之三多人协作时容易互相覆盖你改了流程A同事也改了流程A他先发布你的改动就没了。我之前带一个3人RPA团队最严重的一次一个流程被两人同时改上线后发现有问题但不知道上一个可用版本是哪个只好重新开发浪费了整整3天。后来建立了一套RPA版本管理规范基于文件命名规范 变更记录 飞书文档自动化。现在3人同时改不同的流程不会互相覆盖出问题10分钟内回滚到上一个可用版本。二、版本号规范2.1 版本号格式主版本.次版本.修订号遵循语义化版本2.0.0规范示例v2.3.1 主版本Major 2 → 做了不兼容的修改如更换了目标系统 次版本Minor 3 → 做了向下兼容的功能性新增如增加了一个新的数据源 修订号Patch 1 → 做了向下兼容的问题修正如修复了一个bug版本号变更规则表变更类型版本号变化示例说明修复bug不改变功能修订号1v1.2.3 → v1.2.4最小变更新增功能向下兼容次版本1修订号归零v1.2.3 → v1.3.0中等变更大版本重构不兼容旧版主版本1次版本和修订号归零v1.2.3 → v2.0.0最大变更2.2 文件命名规范每个RPA流程文件必须按以下格式命名{流程名称}_v{主版本}.{次版本}.{修订号}_{日期}_{负责人缩写}.rpaflow 示例 order_sync_v1.2.3_20240615_linyan.rpaflow  inventory_check_v2.0.0_20240601_linyan.rpaflow在影刀中的实现方式影刀RPA的流程文件.rpaflow存储在项目的flows/目录下。建立以下目录结构flows/ ├── order_sync/ │ ├── order_sync_v1.0.0_20240101_linyan.rpaflow # 归档版本 │ ├── order_sync_v1.1.0_20240315_linyan.rpaflow # 归档版本 │ ├── order_sync_v1.2.0_20240601_linyan.rpaflow # 归档版本 │ └── order_sync_dev.rpaflow # 当前开发版本会被定期归档 ├── inventory_check/ │ └── ... └── logistics_tracker/ └── ...归档时机每次发布到生产环境后立即归档当前版本重大bug修复后归档每周五下午定期归档当前开发版本三、变更记录Change Log规范每个流程目录中必须有一个CHANGELOG.md文件。拼多多店群自动化上架方案3.1 CHANGELOG.md模板# 变更记录 - order_sync订单同步流程 ## [Unreleased]未发布 ### 新增 - 待发布的新功能写在这里 ### 修复 - 待发布的bug修复写在这里 ### 变更 - 待发布的不兼容变更写在这里 --- ## [v1.2.3] - 2024-06-15 ### 修复 - 修复了拼多多订单下载超时未正确处理的问题林焱 - 修复了字段映射表中缺失买家备注字段导致流程报错的问题林焱 ### 变更 - 调整了飞书写入的批处理大小为100条/批之前是500条避免API限流 --- ## [v1.2.2] - 2024-05-20 ### 新增 - 增加了淘宝订单下载失败时的自动重试机制最多重试3次 ### 修复 - 修复了日期格式标准化时某些日期解析失败的问题 --- ## [v1.0.0] - 2024-01-01 ### 新增 - 初始版本支持淘宝、拼多多订单自动同步 - 支持字段映射和格式标准化 - 支持写入飞书多维表格3.2 变更记录的自动化更新手动维护CHANGELOG.md容易忘记。可以用影刀RPA在每次发布时自动更新。# # 影刀Python指令自动更新CHANGELOG.md# 在每次发布流程时调用# importreimportosfromdatetimeimportdatetimedefupdate_changelog(flow_name,new_version,changes,author林焱): 自动更新CHANGELOG.md 参数 flow_name: 流程名称如 order_sync new_version: 新版本号如 v1.2.4 changes: 变更内容字典格式 { 新增: [功能A, 功能B], 修复: [bugA, bugB], 删除: [功能C], } author: 作者名 changelog_filefC:/RPA_Flows/{flow_name}/CHANGELOG.md# 读取现有变更记录ifos.path.exists(changelog_file):withopen(changelog_file,r,encodingutf-8)asf:contentf.read()else:contentf# 变更记录 -{flow_name}\n\n## [Unreleased]\n\n### 新增\n- 待发布的新功能写在这里\n# 构造新版本的变更记录todaydatetime.now().strftime(%Y-%m-%d)new_entryf\n\n## [{new_version}] -{today}\nforsection,itemsinchanges.items():ifitems:new_entryf\n###{section}\nforiteminitems:new_entryf-{item}{author}\n# 将新版本插入到 [Unreleased] 之后patternr(## \[Unreleased\].*?)\n\n(## \[v\d)replacementf\\1\n{new_entry}\n\\2new_contentre.sub(pattern,replacement,content,count1)# 如果正则没匹配上文件格式不对简单追加到开头ifnew_contentcontent:# 在 ## [Unreleased] 之后插入linescontent.split(\n)insert_idxNonefori,lineinenumerate(lines):if[Unreleased]inline:# 找到下一个 ## 之前插入forjinrange(i1,len(lines)):iflines[j].startswith(## [):insert_idxjbreakbreakifinsert_idxisnotNone:lines.insert(insert_idx,new_entry.strip())new_content\n.join(lines)# 写回文件withopen(changelog_file,w,encodingutf-8)asf:f.write(new_content)print(f✅ CHANGELOG.md 已更新{new_version})returnTrue# # 在影刀RPA发布流程中的使用方式# ## 步骤1准备本次发布的变更内容#changes{新增:[增加了抖音小店订单自动同步功能,增加了数据校验失败时的自动告警,],修复:[修复了拼多多CSV文件GBK编码解析失败的问题,修复了飞书写入时偶尔超时的问题,],变更:[调整了字段映射表的格式新增transform_rule列,],删除:[],}# 步骤2更新CHANGELOGupdate_changelog(flow_nameorder_sync,new_versionv1.3.0,changeschanges,author林焱)# 步骤3归档当前流程文件importshutil srcC:/RPA_Flows/order_sync/order_sync_dev.rpaflowdstfC:/RPA_Flows/order_sync/order_sync_v1.3.0_{datetime.now().strftime(%Y%m%d)}_linyan.rpaflowshutil.copy2(src,dst)print(f✅ 版本已归档{dst})四、回滚机制4.1 为什么需要回滚场景描述回滚需求发布后发现严重bug新版本在生产环境跑不通立即回滚到上一个稳定版本网站改版导致XPath失效修好的版本还没验证完回滚到使用旧版XPath的版本配置参数改错了新版本的配置文件有错误回滚配置文件流程文件可以不变4.2 回滚操作手册# RPA流程回滚操作手册 ## 回滚场景1流程文件需要回滚 ### 操作步骤 1. **找到上一个稳定版本** 打开 flows/{流程名称}/ 目录找到最近一个稳定版本的 .rpaflow 文件 命名格式{流程名称}_v{版本号}_{日期}_{负责人}.rpaflow 示例上一个稳定版本是 order_sync_v1.2.2_20240520_linyan.rpaflow 2. **恢复流程文件** 将归档的流程文件复制为开发版本 bash copy order_sync_v1.2.2_20240520_linyan.rpaflow order_sync_dev.rpaflow检查配置文件如果配置文件也有变更需要同时回滚配置文件配置文件的版本管理见回滚场景2在影刀中重新加载流程用影刀RPA打开恢复后的order_sync_dev.rpaflow更新CHANGELOG.md在[Unreleased]章节中记录回滚操作### 回滚 - 2024-06-20因v1.2.3存在严重bug回滚到v1.2.2回滚场景2配置文件需要回滚配置文件如field_mapping.xlsx、task_registry.xlsx使用Git进行版本管理。操作步骤查看配置文件的Git历史cdC:/RPA_Configgitlog--onelinefield_mapping.xlsx找到上一个正确的版本记录要回滚到的commit_hash回滚配置文件gitcheckoutcommit_hashfield_mapping.xlsx验证配置文件用Excel打开回滚后的配置文件确认内容正确提交回滚操作gitcommit-am回滚 field_mapping.xlsx 到 commit_hash回滚场景3飞书多维表格数据需要回滚如果RPA流程写入飞书多维表格的数据有误需要从备份恢复。操作步骤找到最近的数据备份备份文件在C:/RPA_Output/backup/YYYY-MM-DD.xlsx手动在飞书多维表格中删除错误数据飞书多维表格目前不支持API批量删除需要手动操作重新导入备份数据使用影刀RPA的飞书多维表格批量写入指令从备份文件重新写入### 4.3 回滚自动化脚本 python # # 影刀Python指令自动回滚到指定版本 # import os import shutil import glob from datetime import datetime def rolbak_flow(flow_name, target_versionNone): 自动回滚流程到指定版本 参数 flow_name: 流程名称 target_version: 目标版本号如 v1.2.2 如果为None则自动回滚到上一个版本 flow_dir fC:/RPA_Flows/{flow_name}/ if not os.path.exists(flow_dir): print(f❌ 流程目录不存在{flow_dir}) return False # 查找所有归档的版本文件 pattern os.path.join(flow_dir, f{flow_name}_v*_*.rpaflow) archived_files glob.glob(pattern) if not archived_files: print(f❌ 没有找到归档版本{flow_dir}) return False # 按版本号排序提取文件名中的版本号按语义化版本排序 def extract_version(filename): basename os.path.basename(filename) # 匹配 v1.2.3 格式 match re.search(r_v(\d)\.(\d)\.(\d)_, basename) if match: return (int(match.group(1)), int(match.group(2)), int(match.group(3))) return (0, 0, 0) archived_files.sort(keyextract_version, reverseTrue) # 确定回滚目标 if target_version: target_file None for f in archived_files: if f_{target_version}_ in f: target_file f break if not target_file: print(f❌ 找不到目标版本{target_version}) return False else: # 自动回滚到上一个版本当前版本的前一个 if len(archived_files) 2: print(f❌ 没有上一个版本可以回滚) return False # archived_files[0] 是当前版本[1] 是上一个版本 target_file archived_files[1] # 执行回滚 dev_file os.path.join(flow_dir, f{flow_name}_dev.rpaflow) try: shutil.copy2(target_file, dev_file) print(f✅ 回滚成功) print(f 从{os.path.basename(target_file)}) print(f 到{dev_file}) return True except Exception as e: print(f❌ 回滚失败{str(e)}) return False # # 在影刀RPA中的使用方式 # # # 场景生产环境发现v1.2.3有严重bug需要回滚到v1.2.2 # success rolbak_flow(order_sync, target_versionv1.2.2) if success: # 更新CHANGELOG update_changelog( flow_nameorder_sync, new_versionv1.2.3-rollback, # 特殊版本号表示回滚 changes{ 回滚: [因v1.2.3存在严重bug回滚到v1.2.2], }, author林焱 ) print(请重新加载流程文件并发布到生产环境) else: print(回滚失败请手动处理)五、多版本并行开发当多人同时开发不同的功能时需要分支策略。5.1 分支目录结构flows/order_sync/ ├── order_sync_dev.rpaflow # 主干开发版本 ├── order_sync_feature_xxx.rpaflow # 功能分支开发完成后合并回dev ├── order_sync_hotfix_yyy.rpaflow # 紧急修复分支 └── archived/ # 归档目录 ├── v1.0.0/ ├── v1.1.0/ └── v1.2.0/5.2 功能分支开发流程# 功能分支开发流程 ## 场景需要新增抖音小店订单同步功能 1. **从当前dev版本创建功能分支** bash cd C:/RPA_Flows/order_sync/ copy order_sync_dev.rpaflow order_sync_feature_douyin.rpaflow在功能分支上开发用影刀RPA打开order_sync_feature_douyin.rpaflow进行开发开发完成后合并回dev版本注意由于.rpaflow是二进制文件无法自动合并。需要手动操作a. 用影刀RPA打开order_sync_dev.rpaflow主干b. 手动将功能分支中的新增指令/子流程复制到主干c. 测试主干版本确认功能正常d. 删除功能分支文件归档新版本见第三节变更记录建议对于复杂的RPA流程建议将流程拆分为多个子流程主干流程只负责调用子流程子流程每个功能模块一个子流程文件这样多人可以同时开发不同的子流程不会冲突。--- ## 六、与飞书文档联动的版本文档自动化 ### 6.1 架构设计RPA流程发布↓[影刀RPA Python指令]↓调用飞书开放平台API↓自动更新飞书文档中的版本记录章节### 6.2 实现代码 python # # 影刀Python指令自动更新飞书文档中的版本记录 # 每次发布流程时自动将版本信息同步到飞书文档 # import requests import json from datetime import datetime class FeishuDocVersionSync: 飞书文档版本同步器 def __init__(self, app_id, app_secret, document_token): 初始化 app_id: 飞书自建应用的App ID app_secret: 飞书自建应用的App Secret document_token: 飞书文档的Token在文档URL中 self.app_id app_id self.app_secret app_secret self.document_token document_token self.access_token None def _get_tenant_token(self): 获取 tenant_access_token url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal resp requests.post(url, json{ app_id: self.app_id, app_secret: self.app_secret }, timeout10).json() if resp.get(code) 0: self.access_token resp[tenant_access_token] return self.access_token else: raise Exception(f获取token失败{resp.get(msg)}) def append_version_record(self, flow_name, version, changes, author林焱): 在飞书文档末尾追加版本记录 参数 flow_name: 流程名称 version: 版本号如 v1.3.0 changes: 变更内容字典同 update_changelog 的格式 author: 作者 if not self.access_token: self._get_tenant_token() # 构造要追加的Markdown内容 today datetime.now().strftime(%Y-%m-%d) content f\n\n## {flow_name} - {version} ({today})\n\n for section, items in changes.items(): if items: content f### {section}\n for item in items: content f- {item}{author}\n # 调用飞书文档API追加内容 url fhttps://open.feishu.cn/open-apis/docx/v1/documents/{self.document_token}/blocks/{self.document_token}/children headers { Authorization: fBearer {self.access_token}, Content-Type: application/json } # 飞书文档API需要特殊的block格式 # 这里简化直接更新整个文档需要先读取再写入 # 读取当前文档内容 get_url fhttps://open.feishu.cn/open-apis/docx/v1/documents/{self.document_token} get_resp requests.get(get_url, headersheaders, timeout10).json() if get_resp.get(code) 0: # 获取文档的block_id root_block_id get_resp[data][document][root_block_id] # 在文档末尾追加新内容 # 实际实现需要构造符合飞书文档API的block结构 # 这里提供一个简化版本实际使用时建议参考飞书文档API文档 print(f✅ 版本记录已同步到飞书文档) print(f 文档地址https://feishu.cn/docs/{self.document_token}) return True else: print(f❌ 同步失败{get_resp.get(msg)}) return False # # 在影刀RPA发布流程中的完整使用方式 # # # 以下代码应该放在发布流程的最后一步 # # 1. 更新本地CHANGELOG update_changelog( flow_nameorder_sync, new_versionv1.3.0, changeschanges, author林焱 ) # 2. 归档流程文件 import shutil src C:/RPA_Flows/order_sync/order_sync_dev.rpaflow dst fC:/RPA_Flows/order_sync/archived/v1.3.0/order_sync_v1.3.0_{datetime.now().strftime(%Y%m%d)}_linyan.rpaflow os.makedirs(os.path.dirname(dst), exist_okTrue) shutil.copy2(src, dst) # 3. 同步到飞书文档 syncer FeishuDocVersionSync( app_idyour_app_id, app_secretyour_app_secret, document_tokenyour_document_token # 在飞书文档URL中可以看到 ) syncer.append_version_record( flow_nameorder_sync, versionv1.3.0, changeschanges, author林焱 ) print(✅ 发布完成版本记录已同步到飞书文档)七、完整发布流程设计7.1 发布检查清单# RPA流程发布检查清单 ## 发布前检查必做 - [ ] 流程在开发环境完整跑通至少3次 - [ ] 变更记录CHANGELOG.md已更新 - [ ] 版本号已按规范升级 - [ ] 配置文件已检查路径、参数都正确 - [ ] 流程文件已另存为带版本号的文件名 - [ ] 飞书文档中的版本记录已同步 ## 发布操作 1. [ ] 将流程文件.rpaflow复制到生产环境目录 2. [ ] 将配置文件.json / .xlsx复制到生产环境目录 3. [ ] 在生产环境手动运行一次确认正常 4. [ ] 更新生产环境的定时任务如果需要 5. [ ] 通知相关人已发布完成 ## 发布后验证 - [ ] 定时任务正常触发 - [ ] 第一次自动运行成功 - [ ] 输出结果正确 - [ ] 通知正常发送 ## 回滚准备 - [ ] 上一个稳定版本的流程文件已找到 - [ ] 上一个稳定版本的配置文件已找到 - [ ] 回滚步骤已确认7.2 发布通知模板defsend_release_notification(flow_name,version,changes,feishu_webhook_url):发送发布通知到飞书群# 构造通知内容contentf【RPA流程发布通知】 流程名称{flow_name}新版本{version}发布时间{datetime.now().strftime(%Y-%m-%d %H:%M:%S)}发布人林焱 --- 变更内容 --- forsection,itemsinchanges.items():ifitems:contentf\n【{section}】\nforiteminitems:contentf •{item}\ncontent\n已发布到生产环境请关注运行状态。# 发送到飞书群Webhook方式payload{msg_type:text,content:{text:content}}resprequests.post(feishu_webhook_url,jsonpayload,timeout10)ifresp.json().get(code)0:print(f✅ 发布通知已发送到飞书群)returnTrueelse:print(f❌ 通知发送失败{resp.json().get(msg)})returnFalse八、常见问题速查Q1.rpaflow文件用Git管理时无法diff怎么办现象把.rpaflow文件提交到Git但git diff显示的都是乱码二进制文件。解决方式不要把.rpaflow文件放到Git只对配置和文档做Git版本管理对.rpaflow文件使用文件命名规范 归档目录见本文第二节如果需要比较两个版本的流程差异可以用影刀RPA分别打开两个版本截图对比或者从流程中导出为文字描述影刀有导出流程说明功能Q2多人同时改一个流程冲突了怎么办现象两个人同时基于order_sync_dev.rpaflow修改后提交的人把前一个的修改覆盖了。解决方式建立流程锁机制谁在改就在C:/RPA_Flows/locks/order_sync.lock创建一个锁文件写上自己的名字和时间。另一个人看到锁文件就知道有人在改。拆分为子流程将大流程拆分为多个子流程每个人负责不同的子流程。使用功能分支见本文第五节。Q3不知道当前生产环境正在跑哪个版本怎么办现象生产环境的流程文件没有版本标识不知道当前跑的是v1.2.2还是v1.2.3。解决方式在流程的开头添加一个Python指令输出当前版本号# 在流程开头添加VERSIONv1.2.3# 每次发布时手动更新这行print(f流程版本{VERSION})或者在生产环境的流程文件命名中带版本号生产环境目录 C:/RPA_Production/order_sync_v1.2.3.rpaflow 影刀定时任务中配置的是这个带版本号的文件名 [video(video-mKAk2sXb-1785092134671)(type-csdn)(url-https://live.csdn.net/v/embed/524993)(image-https://v-blog.csdnimg.cn/asset/a547123d88ad712dccba346c9217e237/cover/Cover0.jpg)(title-TEMU店群如何管理运营)]Q4CHANGELOG.md 太长了不好维护怎么办现象CHANGELOG.md写了1年多已经有5000行了打开很慢。解决方式按年份拆分CHANGELOG-2024.md、CHANGELOG-2025.md只保留最近10个版本的详细记录更早的版本只保留版本号和日期# 历史版本简略 - v1.0.0 (2024-01-01)初始版本 - v1.1.0 (2024-03-15)增加拼多多支持 -  - v1.2.0 (2024-06-01)增加抖音小店支持 详细记录见 CHANGELOG-2024.mdQ5版本回滚后发现回滚的版本也有问题怎么办现象生产环境v1.2.3有bug回滚到v1.2.2但发现v1.2.2也有另一个bug。解决方式立即回滚到更早的版本如v1.2.1或者在v1.2.2的基础上做热修复基于v1.2.2创建order_sync_hotfix.rpaflow只修复那个bug不做任何其他改动测试通过后发布为v1.2.4修订号1同时记录在CHANGELOG中记录这次热修复Q6飞书文档API调用失败版本同步不成功怎么办现象调用飞书文档API时返回错误版本记录没有同步。解决方式检查access_token是否过期2小时过期需要重新获取检查文档权限确保自建应用有这个文档的编辑权限降级方案如果API一直失败改用手动复制粘贴每次发布后手动把CHANGELOG中的新版本记录复制到飞书文档虽然有手动操作但至少保证了版本记录的完整性Q7配置文件如field_mapping.xlsx的版本如何与流程文件版本对应现象流程文件是v1.2.3但不知道当时用的配置文件是哪个版本。解决方式在配置文件中增加版本标识在field_mapping.xlsx的第一个Sheet中增加一行配置版本对应流程版本最后更新时间更新人v1.2.3v1.2.32024-06-15林焱配置文件也做版本归档config/ ├── field_mapping.xlsx # 当前使用 ├── field_mapping_v1.2.2.xlsx # 归档 └── field_mapping_v1.2.3.xlsx # 归档九、推荐资源资源名称类型地址/说明语义化版本2.0.0规范semver.org/lang/zh-CN/Git官方文档文档git-scm.com/doc飞书开放平台-文档API文档open.feishu.cn/document/server-docs/docs/docs/docs-overview影刀RPA官方文档-流程管理文档影刀学院搜索流程管理《持续交付》书籍ISBN: 9787115355953十、内容标签影刀RPA版本管理变更记录回滚机制多版本并行飞书文档迭代发布RPA规范团队协作项目管理作者林焱 | 飞行社社区原创转载请注明出处