spreadsheet-operations
影刀 RPA 运行时 Excel/CSV 处理规范;不规定 Agent 直接操作表格文件的工具。
apexcheng · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add apexcheng/yingdao-xbot-ai-agent --skill spreadsheet-operationsAbout this skill
name: spreadsheet-operations description: 影刀 RPA 运行时 Excel/CSV 处理规范;不规定 Agent 直接操作表格文件的工具。
表格操作(影刀 WPS)
本 Skill 只约束交付的影刀 RPA 运行时表格处理代码。Agent 直接检查、修改、计算或保存表格文件(包括项目模板和运行产物)时,按自身执行环境的适用规则选择工具,不受本 Skill 的 xbot.excel / WPS 要求限制。API 参数和返回值查 xbot.excel 正式文档;业务模块命名与函数边界见 编程风格。不重复加载其它表格操作规范。
新开发的 Excel / CSV 处理代码默认采用 xbot.excel / WPS;维护已有项目时遵循该项目已确认的技术方案,不因局部修改而自动替换,确需变更先说明影响并取得确认。下列 WPS 操作规则适用于采用 WPS 的流程。
测试时,用户明确指定专用测试工作簿就直接使用,不强制复制;若要求保留 WPS 打开且不保存,则按要求跳过测试收尾的保存与关闭。生产运行仍遵守下述规则。
打开与使用工作簿
-
本轮程序第一次打开 WPS 前,直接调用
xbot.excel.kill_excel_process("wps", True)结束残留进程;不判断其他 WPS 文件是否正在编辑。本轮已经打开目标工作簿后,不在打开源文件前再次结束 WPS。 -
采用 WPS 的业务流程使用
xbot.excel.open()的 WPS 驱动打开 Excel / CSV。 -
统一使用
workbook = xbot.excel.open(file_name=str(target), kind="wps", visible=True, update_links=False);不使用visible=False。 -
每次打开工作簿后,立即激活并最大化:
workbook.workbook.Activate() workbook.workbook.Application.WindowState = -4137 -
根据任务选择读取和写入接口;批量搬运数据可使用
get_range()读取、整理后用set_range()写入。已有二维数据直接写入,不创建临时工作簿中转。 覆盖旧数据时只清空当前业务约定的数据区域,不整表clear()影响公式和格式。写入原始数据后确实要立即使用公式计算结果时,按实际 WPS 计算结果处理,不能用 Python 模拟计算代替。 写入 RAW 时,表头和字段值中以=开头的业务文本,按 WPS 批量写入文本保护 处理;真正需要执行的公式不得转义。 -
对已确认由工作簿公式完成业务计算的项目,RPA 负责模拟操作和搬运 RAW / 事实数据。除用户明确要求外,不自行增加源文件与目标 Sheet 的表头一致性校验,不判断数据是否符合业务预期,不因空文件或只有表头拒绝覆盖,也不复刻、重算或核对工作簿公式。 按约定区域读取、清理和写入;空结果同样按约定清理旧 RAW,保留明确要求的标识字段文本保护。取得下载路径后直接按业务流程读取,不额外验证文件存在性。 操作所需的任务绑定、状态等待和下载等待仍正常执行,技术异常如实抛出,不将读取失败当成空数据。
-
多个步骤需要同一工作簿时复用已打开的对象,避免无必要重复打开;函数的输入与返回值按实际职责确定。
多 Sheet 更新与收尾
- 主流程直接写明下载、打开、写入、计算、保存和关闭的先后顺序。目标工作簿一轮只打开一次,各业务模块接收该对象。
- 每个 Sheet 的完整更新流程最多尝试 2 次(首次执行 + 失败后重试 1 次),包括下载、读取和写入,不仅重试下载;不把整轮保存和通知纳入该重试。A Sheet 最终失败时记录错误,继续更新独立的 C Sheet;存在前置依赖的 Sheet 按当前业务确认的依赖关系及失败策略处理。各 Sheet 处理完后统一
workbook.save()一次,不在每个 Sheet 更新后保存。 - 下载函数按实际流程返回文件路径、已打开的工作簿或所需数据;避免无必要重复下载或打开。
- 完成本轮处理后,先保存目标工作簿,再统一关闭全部 WPS 表格,不额外维护逐工作簿关闭清单。异常时按原业务异常处理未保存内容;清理失败不能覆盖原来的业务异常。
- 按已确认的项目架构和实际职责组织下载、更新和计算代码;多个业务确实复用相同且完整的技术操作时才提取公共函数。
不为了潜在需求新增跨轮下载缓存、重复状态源、补跑开关、历史兼容和复杂恢复分支。