企业官网建设流程全解析

• 人工智能
• AI 技能
• AI 评测

导读

本文以开源仓库 GitHub_Trending/skills3/skills 中的 xlsx Skill 文档 为核心，系统讲解面向 .xlsx/.xlsm/.xltx/.csv/.tsv 文件的程序化创建、读取、编辑与分析全流程。你将掌握：如何在不同任务下选择正确的工具链（openpyxl / pandas / markitdown）、如何用 recalc.py 强制重算并排查公式错误、哪些 Excel 公式能在自动化工作流中安全存活、以及财务模型工作簿的配色与数字格式规范——全部附带仓库源码级依据，可直接在真实工作流中复制执行。

Skill 定位：什么任务该用它，什么任务不该用

xlsx 是仓库skills/xlsx/目录下的一个 Agent Skill，其触发条件写在其描述元数据（见 SKILL.md 的 frontmatter）中：

• 主输入或主输出是电子表格：打开、读取、编辑、修复已有.xlsx、.xlsm、.xltx、.csv、.tsv文件（如加列、计算公式、格式化、制图、清洗脏数据）；
• 从零创建电子表格：从其他数据源生成新表格；
• 表格格式互转：在.xlsx/.csv/.tsv之间转换；
• 清洗杂乱表格数据：畸形行、错位表头、垃圾数据整理成规范表格；
• 触发信号：用户以文件名或路径引用表格文件（哪怕随口说"下载文件夹里那个 xlsx"）并要求对其做点什么。

同时明确不触发的场景：主交付物是 Word 文档、HTML 报告、独立 Python 脚本、数据库管线或 Google Sheets API 集成——即使其中涉及表格数据。理解触发边界有助于把该 Skill 用在刀刃上，避免把表格工具误用于非表格交付物。

任务-工具选型矩阵

原文档用一张表给出了四类任务的工具取向，这是整份指南的骨架：

环境前提：openpyxl、pandas、markitdown均已预装，不要先执行pip install，直接写脚本 import 即可。只有当 import 失败（或markitdown命令缺失）时，才pip install对应包。

依赖清单见 SKILL.md 的 Dependencies 一节：openpyxl、pandas、markitdown（pip，预装）以及 LibreOffice（soffice，通过 scripts/office/soffice.py 自动适配沙箱环境）。

环境适配：soffice.py 如何让 LibreOffice 在沙箱中跑起来

重算依赖 LibreOffice，而沙箱化 VM 中AF_UNIXsocket 常被禁止。仓库中的 soffice.py 在运行时探测该限制并做两层兜底：

1. 运行时探测：_needs_shim()尝试创建AF_UNIXsocket，失败即认为需要 shim；
2. LD_PRELOAD shim：_ensure_shim()动态编译一个 C shim（lo_socket_shim.so），把被禁止的socket(AF_UNIX)调用回退到socketpair()，并用管道模拟listen/accept的阻塞语义，使 LibreOffice 的无头转换流程得以完成；
3. 环境变量：get_soffice_env()固定设置SAL_USE_VCLPLUGIN=svp（虚拟显示插件），并注入LD_PRELOAD；
4. 用户配置隔离：run_soffice()在参数缺少-env:UserInstallation时自动为每次调用创建临时 profile，避免非 root 沙箱无法引导默认配置而报User installation could not be completed。

这意味着：在任何环境运行recalc.py前无需手动配置 LibreOffice，脚本会自行完成沙箱适配——前提是系统里确实安装了soffice（缺失时脚本返回soffice not found on PATH错误）。

每份输出的硬性要求

原文档列出了无论创建还是编辑都必须满足的产出规范，逐条执行可保证交付物专业且可被再次编辑：

1. 全篇专业字体：除非用户另有要求，统一使用 Arial、Times New Roman；
2. 零公式错误：recalc.py报告errors_found时绝不能交付。若怀疑错误是先于你存在的，用data_only=True加载原始文件并查看该单元格来证明——你自己引入的错误和继承的错误看起来一模一样；
3. 用公式，不要硬编码结果：写sheet['B10'] = '=SUM(B2:B9)'，而不是 Python 算好的总数。工作表必须在输入变化时能自动重算；
4. 严格遵循用户规格：精确的表名、精确的列头、用户指定的公式一字不差。一个"计算了别的东西"的精美重设计即使再优雅也是失败；
5. 文档化每个假设与硬编码数字：写在读者看得见的地方——单元格批注，或表格末尾的相邻单元格。有真实来源就引用（如Source: Company 10-K, FY2024, Page 45, Revenue Note）；数字来自用户就直说；
6. 为他人填写的空白工作簿：需要一段简短图例说明该编辑哪些单元格，并附一行符合预期格式的真实示例数据行；但绝不可给"被要求编辑的文件"添加这样的行；
7. 编辑已有文件：完全匹配其既有约定——它们优先于本文所有指南。先找到其指定输入单元格（通常用不同的字体颜色、填充或底纹标记），只写那里，并让所有既有公式原封不动。

强制重算机制：recalc.py 深度解析

为什么必须重算

openpyxl 把公式写成字符串，不附带任何缓存值。在重算之前，任何读取缓存值的消费者——pandas、load_workbook(data_only=True)、大多数预览器——读到的公式单元格都是None。因此只要文件含公式，重算是强制步骤。

用法与退出码

python scripts/recalc.py output.xlsx [timeout_seconds] # 默认 30 秒

LibreOffice 计算全部公式后，文件原地重写，脚本输出 JSON：

• status：success或errors_found；
• total_formulas：文件中的公式总数；
• total_errors：错误单元格总数；
• error_summary：按错误类型分组，每种类型列出最多 100 个单元格位置；locations_truncated表示被截断的数量——判断总量要以total_errors为准，而不是看列表长度。

修复它点名的单元格后再次运行。关键退出码语义（源码见 recalc.py 的 main()）：

• JSON 含error键（而非status）说明什么都没重算，此时脚本以非零码退出；
• errors_found反而以0退出——所以绝不能把"命令退出码为 0"当成"工作簿干净"。只有error分支sys.exit(1)，errors_found分支同样走 0 退出。

扫描的错误类型

recalc.py 的_recalc_with_profile()用load_workbook(data_only=True)读回重算结果，逐单元格匹配以下 7 种 Excel 错误字符串：

#VALUE! #DIV/0! #REF! #NAME? #NULL! #NUM! #N/A

命中即记录sheet!coordinate位置并入error_summary；随后再以data_only=False打开统计total_formulas（以=开头的字符串单元格计数）。

绿色重算 ≠ 正确的重算

重算通过只能证明公式"能求值"，不能证明公式"算对了"。范围差一行、引用了错误的行，都会产出一份无错但数字错误的工作簿。原文档给出的对策：先写好 2～3 个公式，验证它们拉到了你预期的数值，再铺开整个网格。

外部链接保护：recalc.py 的拒绝逻辑

工作簿若链接到另一个文件，用 openpyxl 重新保存会丢失这些链接。这类公式形如='[1]Returns Analysis'!$B$2——其中的[1]是工作簿外部引用列表的索引，指向磁盘上的另一个文件，不是本工作簿的 sheet。那个文件很少存在，所以该单元格的缓存值是唯一的数据来源；openpyxl 保存时剥离缓存值，LibreOffice 随后真实解析引用、失败、写入#NAME?并永久删除所有外部链接。

为此 recalc() 内置了保护：通过external_links_at_risk()（recalc.py 源码）检查xl/externalLinks/部件、命名区域与公式中的外部引用，若发现reaches_out且缓存值为None的单元格，拒绝重算并返回error与external_link_cells列表——提示你先从原始文件复制这些单元格的值再保存，或传--force接受链接丢失的风险。--force由命令行参数解析（recalc.py main()）透传。提示中还指出：图表与条件格式也可能持有外部引用，因此该列表可能不完整。

超时与沙箱细节

timeout_seconds默认 30 秒，脚本实际执行时取max(5, 剩余时间)（源码）；Linux 上用系统timeout包装 soffice，macOS 上有gtimeout才用（源码）。超时或 soffice 返回非零、或文件未被重写（_stamp前后一致）都会返回带error的 JSON。每次重算使用独立的临时 profile 目录安装一个 StarBasic 宏（RecalculateAndSave，见 recalc.py 的宏定义），宏执行calculateAll()→store()→close(True)，实现无头重算。

公式选型：哪些公式能活着通过校验

LibreOffice 实现的函数比 Excel 少，任何它无法求值的函数都会变成写进交付文件的字面量#NAME?。选型规则：

• 优先 Excel-2007 时代的函数：SUMIFS、INDEX、MATCH、IFERROR、SUMPRODUCT——无需任何前缀；

• 六个 2007 之后的函数可用，但必须带_xlfn.前缀：openpyxl 把你的公式原样写进 XML，而 Excel 存储 2007 后函数名时带前缀（UI 隐藏了它）：

  _xlfn.TEXTJOIN _xlfn.CONCAT _xlfn.IFS _xlfn.SWITCH _xlfn.MAXIFS _xlfn.MINIFS

  裸写任何一个都会得到#NAME?；

• 绝不要用XLOOKUP、XMATCH、SORT、FILTER、UNIQUE、SEQUENCE：当前运行时的 LibreOffice 在任何前缀下都无法求值它们。更新的构建可以，但它们属于溢出（spilling）数组函数，而 openpyxl 写出的文件没有溢出元数据，结果只有区域左上角单元格拿到值——recalc.py会在截断结果上报total_errors: 0。查找请用INDEX/MATCH；排序、过滤、去重请在 Python 中完成后再写入单元格；

• 一个小提示：LibreOffice 无法解析的公式会被改写成小写回写——这是#NAME?旁边最快速的排查信号。

openpyxl 陷阱全解

原文档给出六条高频坑，每一条都值得写进 checklist：

1. 读取模型需要两次加载：data_only=True得到缓存值但公式没了；默认模式得到公式字符串但没有值。一次加载不可能同时拿到两者；
2. data_only=True是破坏性的——如果保存：那个工作簿已经没有公式，保存会用字面量永久替换每一个公式；
3. 对 openpyxl 刚写出的文件用data_only=True读取，处处是None——先跑recalc.py。（结果为""的公式也读作None）；
4. 合并单元格：只写左上角锚点。区域内其他单元格都是只读的MergedCell；
5. .xlsm会丢失宏：除非向load_workbook传keep_vba=True；
6. 含空格的 sheet 名在跨 sheet 引用中必须加引号：='Assumptions Inputs'!$B$5。不加引号会求值为#VALUE!。

财务模型工作簿规范

除非用户另有指示，或已有文件就是这么做的，否则按以下约定执行：

配色：

• 蓝色文本(0,0,255)——硬编码输入与情景杠杆（scenario levers）；
• 黑色——公式；
• 绿色(0,128,0)——跨 sheet 链接；
• 红色(255,0,0)——跨文件链接；
• 黄色填充(255,255,0)——关键假设及用户需要填写的单元格。

数字格式：

• 货币$#,##0，表头标注单位（Revenue ($mm)）；
• 零显示为-（含百分比）：$#,##0;($#,##0);-；
• 负数用括号；
• 百分比0.0%，存储为小数（0.15渲染为15.0%；存15会渲染成1500.0%）；
• 估值倍数0.0x；
• 年份用文本（"2024"，绝不能是2,024）。

结构：

• 每个假设独占一个带标签的单元格，被使用它的公式引用：=B5*(1+$B$6)，绝不写=B5*1.05；
• 公式在所有预测期间保持一致——行中间孤立的被编辑单元格是最常见的静默错误来源；
• 为可能为零的分母设置守卫。

xlsx 家族的校验辅助

仓库在 scripts/office/validate.py 中提供了 Office 文档 XML 校验工具（支持.docx/.pptx/.xlsx及模板），但其中对 xlsx 家族有一个明确设计：不做 XSD schema 校验——validate.py的case "xlsx"分支直接打印说明并建议"公式错误检查请改用 scripts/recalc.py"（源码见 validate.py）。也就是说，xlsx 工作流的质量闸门就是本文的强制重算机制，而不是 XML 模式校验。相关支撑还体现在 helpers/init.py 的OOXML_FAMILY映射（.xlsx/.xltx归入 xlsx 家族）与安全解压逻辑中。

依赖清单与许可

• 运行依赖：openpyxl、pandas、markitdown（pip 预装，仅当 import 失败或命令缺失时才安装）、LibreOfficesoffice（沙箱环境由 soffice.py 自动适配）。
• 许可：本 Skill 为专有许可，完整条款见 skills/xlsx/LICENSE.txt。

结语

从任务选型、产出规范、强制重算、公式存活策略到 openpyxl 陷阱与财务模型约定，xlsx Skill 把"用代码生成可信 Excel"这件事收敛成了一套可复现的工程流程。核心闭环是：openpyxl 写公式 → recalc.py 用 LibreOffice 重算并扫描 7 类错误 → 依据 error_summary 修复 → 确认 status 为 success——同时牢记绿色重算只证明求值成功，数字正确性仍要靠先写 2～3 个公式抽查来保证。

• 人工智能
• AI 技能
• AI 评测