xlsx

Excel 工作簿

你已经熟悉 openpyxl 和 pandas。这项技能补充了代码中看不到的内容：一个重新计算步骤，用于报告工作簿中实际存在的问题，以及 openpyxl 和 LibreOffice 会悄悄破坏文件的行为。

运行脚本

<skill> 是包含此文件的目录。请从用户的工作目录使用绝对路径运行捆绑脚本，这样脚本中的相对文件路径才能正常工作：

uv run <skill>/scripts/recalc.py model.xlsx

运行你编写的 Python 代码时，须声明其依赖项，可以使用 uv run --with openpyxl script.py，也可以使用 PEP 723 标头。重新计算需要 LibreOffice（soffice）。

选择工具

• openpyxl 用于你要交付的任何工作簿：公式、格式、图表、数据验证、批注。它会保留所加载文件中的图表、图片、批注、数据验证和条件格式。但它会丢弃无法建模的内容，例如形状、文本框、切片器和表单控件，因此编辑包含这些内容的工作簿前要先检查。
• pandas 用于分析和批量读取。它的写入器只保留值，因此绝不要用它编辑他人还会继续使用的工作簿。
• 对于 .xlsm，请使用 load_workbook(path, keep_vba=True) 加载，否则保存时宏会丢失。

使用公式，而非值

所有派生内容都应以公式的形式写入工作表，这样输入发生变化时，工作簿仍能保持正确。只有无法用电子表格公式表示的内容，才在 Python 中计算，然后将其作为带标签的输入写入。

ws["B10"] = "=SUM(B2:B9)"          # not ws["B10"] = df["Sales"].sum()
ws["C5"] = "=(C4-C2)/C2"           # growth, from the cells it depends on
ws["D3"] = "=B3*(1+$B$1)"          # assumptions live in their own cells

检查输出

openpyxl 写入公式时不会写入计算值，因此文件在重新计算之前还不能算完成。每次保存中涉及公式的修改后，都要运行此步骤，并在交付前修复报告的问题：

uv run <skill>/scripts/recalc.py model.xlsx

它会在 LibreOffice 中重新计算，将计算值写回文件，并输出 JSON。没有问题时退出状态为 0；存在问题时为 1；无法运行时为 2。

字段	含义和修复方法
errors	按类型列出的错误值，例如 {"#DIV/0!": {"count": 3, "locations": ["Model!C7", …]}}，每种类型最多列出 50 个位置。请修复这些单元格中的公式。
missing_prefix	新函数的写入方式缺少文件格式要求的前缀（见下文）。文件不会被修改，每个条目都会在 fix 中附带修正后的公式。
circular_references	相互依赖的单元格组。LibreOffice 会将它们显示为 #VALUE!，因此请先修复循环引用。
uncalculated	LibreOffice 未能计算出值的公式。通常是 LibreOffice 尚未实现的函数。工作簿可能仍能在 Excel 中正常使用，但请告知用户。

链接到其他工作簿时，脚本会停止，因为重新计算会覆盖链接值。只有在用户接受的情况下才传入 --force。

容易悄无声息地出错的问题

• 函数前缀。 Excel 2007 之后新增的函数都带有前缀。请写成 =_xlfn.XLOOKUP(…)、=_xlfn.TEXTJOIN(…)、=_xlfn.IFS(…)、=_xlfn._xlws.FILTER(…) 和 =_xlfn._xlws.SORT(…)。否则，Excel 和 LibreOffice 都会显示 #NAME?。recalc 会在这些问题造成损害之前将其捕获。低于 24.8 版的 LibreOffice（soffice --version）不支持 XLOOKUP、XMATCH、FILTER、SORT、SORTBY、UNIQUE、SEQUENCE 和 LET，因此即使带有前缀，recalc 仍会将其标记出来；工作簿在 Excel 中仍能正常计算，因此应告知用户，而不是重写公式。
• 插入或删除行和列。 insert_rows、delete_rows、insert_cols 和 delete_cols 会移动单元格，但不会改写引用这些单元格的公式。在某行上方插入一行后，=SUM(B1:B4) 仍会是 =SUM(B1:B4)。请自行重写受影响的公式，或调整工作表布局，避免需要插入行或列。
• data_only=True 会读取缓存值。以这种方式打开工作簿后保存，会将每个公式永久替换为其上次计算的值。
• 动态数组。 openpyxl 无法写入溢出公式。FILTER、SORT、UNIQUE 和 SEQUENCE 会落在单个单元格中，Excel 会为其添加 @ 前缀。优先使用每个单元格返回一个值的公式。
• 索引。 行和列的索引从 1 开始。请使用 get_column_letter 和 column_index_from_string；列 Z 之后切勿手动数列字母。

图表

对于需要放在工作簿中的图表，请使用 openpyxl 原生图表（openpyxl.chart），这样图表会与单元格保持链接。只有在图表需要放到其他位置时，才渲染 matplotlib 图像。

现有工作簿和模板

修改文件之前，请先检查文件，并准确沿用其字体、填充、数字格式、列宽和布局。文件自身的规范优先于以下所有内容。

财务模型

除非用户或模板另有说明：

• 按用途设置字体颜色： 硬编码输入使用蓝色 0000FF，公式使用黑色，指向其他工作表的链接使用绿色 008000，指向其他文件的链接使用红色 FF0000。关键假设使用黄色 FFFF00 填充。
• 数字格式：
  • 货币：$#,##0;($#,##0);-，并在标题中注明单位，例如“Revenue ($mm)”。
  • 百分比：0.0%。
  • 倍数：0.0x。
  • 负数：用括号表示。
  • 年份：以文本形式填写，确保“2026”不会变成“2,026”。
• 结构： 每个假设都应放在单独的、带标签的单元格中，并通过引用使用，切勿直接输入公式。每个预测期都使用与前一期相同的公式。
• 来源： 每个硬编码数字都应在单元格批注或相邻单元格中注明来源，例如“Source: Company 10-K, FY2025, p. 45”。