ARTICLE · 1090736
xlwings 技能包:Excel 自动化全场景工作流
xlwings 技能包：Excel 自动化全场景工作流
技能包系列 · Excel
这是六个仓库里体量最大的一个：xlwings 开发技能的开源发布——使用 Python（xlwings）开发 Excel 应用的全生命周期技能。SKILL.md 的 description 一段就把能力面铺开了：场景 A（Python 脚本与 MCP 两种方式自动化操作 Excel）、场景 B（Web/服务化方案——xlwings Server / Lite / Office.js）、场景 C（VBA 宏与 VBA 加载项，含 UDF）、场景 D（源码学习与二次开发）；场景 C 提供 13 步完整工作流，含 12 个质量门禁、便携运行时分发、白标 xlam 构建。本公众号此前的「公告快手」系列（32 篇 xlwings 插件开发），用的正是这套技能体系。
图 1 三大场景与上游合规（依据官方 SKILL.md）
零基础名词速查
这一篇的几个关键词，先用大白话说清：
xlwings
大白话解释｜让 Python 直接读写 Excel 的库——Python 里一行代码，Excel 里就变了
UDF（自定义函数）
大白话解释｜把 Python 函数变成 Excel 公式：单元格里输入 =ANN_COUNT(...) 就能算
RunPython
大白话解释｜Excel 里的按钮点一下 → 启动 Python 跑一段代码的桥
白标 xlam
大白话解释｜换上自己名字的 Excel 加载项——别人打开 Excel 就能看到你的功能按钮
便携运行时
大白话解释｜把 Python 本体和依赖一起打包带走，用户机器没装 Python 也能跑
一、场景路由：三维判定与决策树
SKILL.md 按「需求路由 → 场景执行 → 质量门禁 → 交付分发」组织。第 2 章给出三维判定模型（2.1）与场景路由决策树（2.2）：按需求特征在四个场景间路由。场景 C 专指桌面 VBA 通道——覆盖 VBA 宏、RunPython 桥接、UDF 自定义函数（桌面 UDF）、Ribbon 自定义、UserForm 窗体、桌面面板（pywebview+FastHTML）、白标 xlam 加载项、便携运行时分发；Web/Office.js 加载项不属本场景，归场景 B。
二、需求澄清：12 条必问问题
场景 C 的 6.5.1 列了 12 条必问问题，把需求澄清做成了清单——这几问值得所有做需求的人抄走：
1
必问问题｜你现在是手工怎么做这件事的？
2
必问问题｜最费时间的是哪一步？
3
必问问题｜你期望最终看到什么结果？
4
必问问题｜点按钮运行（RunPython 宏），还是输入公式后自动计算（UDF）？
5
必问问题｜如果原始数据变了，你希望结果自动跟着变吗？
6
必问问题｜你的 Python 代码需要用到哪些第三方库？（pandas、numpy、requests 等）
7
必问问题｜是改原表、生成新表、弹提示，还是放一个长期复用的入口？
8
必问问题｜只给一个固定文件用，还是很多文件都要用？
9
必问问题｜是你自己用，还是别人也要用？
10
必问问题｜如果别人也要用，他们的电脑上有没有 Python 环境？
11
必问问题｜希望怎么触发：打开文件自动跑、点按钮，还是写公式？
12
必问问题｜能不能给我样例表、截图、列名说明？
配套的必要截图要求同样具体：带行号列标、尽量带公式栏、带工作表名称、框出当前处理区域、报错带完整错误弹窗、交互问题带按钮位置。确认清单六项全过（用途/输入格式/输出格式/用户群体/触发方式/MVP 清单）才进入下一步；零基础用户沟通规范：不解释技术细节，用比喻说明（「我会给你做一个 Excel 里的按钮」），只问业务问题。
三、13 步工作流与 12 个门禁
6.5.1 需求澄清与形态判定 → 6.5.2 环境准备 → 6.5.3 项目初始化与设计
→ 6.5.4 Python 代码构建 → 6.5.5 VBA 代码构建与引擎激活 → 6.5.6 Ribbon 构建
→ 6.5.7 UDF 开发与导入 → 6.5.8 插件配置与重命名 → 6.5.9 单元测试与静态检查
→ 6.5.10 部署与交付物整备 → 6.5.11 安装 → 6.5.12 安装后集成验证 → 6.5.13 分发
13 步工作流（官方 SKILL.md 原文）
A
名称｜构建完整性
脚本｜gate_a_build_integrity.py
执行时机｜每次构建后
B
名称｜配置与分发
脚本｜gate_b_config_and_dist.py
执行时机｜配置后
C/D
名称｜加载项注册
脚本｜verify_addin_registered.ps1
执行时机｜安装后
E
名称｜交付前最终验证
脚本｜gate_e_final_delivery.py
执行时机｜交付前
F
名称｜RunPython 链路
脚本｜gate_f_runpython_chain.py
执行时机｜安装后
G
名称｜引擎注入
脚本｜gate_g_engine_injected.py
执行时机｜引擎激活后
H
名称｜语法检查
脚本｜gate_h_syntax_check.py
执行时机｜每次改 .py 后
I
名称｜路径计算
脚本｜gate_i_path_calculation.py
执行时机｜ZIP 分发时
J
名称｜端到端运行时
脚本｜gate_j_e2e_runtime.py
执行时机｜交付前
K
名称｜配置表重复键
脚本｜gate_k_config_duplicate.py
执行时机｜配置后
L
名称｜真实 Excel 启动
脚本｜gate_l_real_excel_launch.py
执行时机｜安装后
0 级错误阻断进入下一步。另有一个容易被忽略的细节：验证本地源码注入时不能看 xw.__version__——源码里该常量是构建期占位符（xlwings/xlwings/__init__.py 第 8 行写死为 0.0.0），官方给的正确验证方式是打印 xlwings.__file__ 看路径是否落在技能根目录内。
四、场景 A：自动化主线与文档资产
场景 A 的主线工作流：连接 Excel → 对象导航 → 读取数据 → 写入数据 → 格式化样式 → 图表/图片/形状/表格 → 清理收尾。连接层覆盖 Book 打开/创建、with xw.App() 生命周期管理、多实例用 xw.apps.keys() 取 PID 精确指定、OneDrive/SharePoint 云盘连接；导航层覆盖正向与反向导航（rng.sheet.book.app）与 Range 三种选择方式；读取用 .options() 控制转换器、大数据 chunksize 分块。
这个技能最厚实的资产是官方文档转档：xlwings/docs/api/ 下按对象逐篇收录——app/book/sheet/range、font/border/note/page_setup/autofilter/conditional_format/data_validation、chart 系列、shape/picture、table/name、pivot_table 系列、top_level_functions/udf_decorators、PRO 的 reports——写任何 Excel 自动化代码前先查对应篇目，这就是 HARD-GATE 理念的落地。MCP 自动化（场景 A 的协议封装通道）也在场景 A 内覆盖。
五、上游合规：快照跟踪机制
技能按 Agent Skills 规范以虚拟树结构发布（skills/xlwings/ 为一个完整技能）。处理第三方资源的方式：examples/（11 个官方/第三方示例仓库）、MCP-Server/（4 个 xlwings MCP 服务器实现）、xlwings/（官方源码包）、xlwings-server/、xlwings-lite/ 五个目录均为本地副本占位——不随本仓库分发，以 README 占位并链接官方来源（github.com/xlwings/xlwings、xlwings.org、server.xlwings.org 等）。跟踪机制：manifest.json 记录每个上游的 ref + pinned_sha，SYNCLOG.md 记录同步历史，配合 scripts/sync_upstream.py 使用——上游漂移可追踪、可复现、可审计。许可边界清晰：仓库内的技能文档与脚本为自有许可；引用的第三方版权归各自所有者。
六、官方链接
🔗 https://github.com/kuailexiaozixin/xlwings｜技能仓库
🔗 https://github.com/xlwings/xlwings｜xlwings 官方源码（上游）
🔗 https://www.xlwings.org/｜xlwings 官网
🔗 https://github.com/xlwings/xlwings-server｜xlwings Server（上游）
🔗 https://github.com/xlwings/xlwings-lite｜xlwings Lite（上游）
素材来源：github.com/kuailexiaozixin/xlwings 官方 README 与 skills/xlwings/SKILL.md（已存档核对）