XLSX 创建、编辑和分析
| 任务 | 方法 |
|---|---|
| 创建或编辑（含公式/格式） | openpyxl — 参见下面的注意事项 |
| 批量数据导入或导出 | pandas（read_excel、to_excel） |
| 快速查看工作表 | markitdown file.xlsx — 每个工作表以 ## SheetName 形式显示；也支持 .xlsm。不含单元格坐标，因此不要据此计划编辑 |
| 读取模型（公式和值） | 两次 load_workbook 调用 — 参见注意事项 |
openpyxl、pandas和markitdown已预装 — 请勿先运行pip install；直接编写脚本并导入。仅当导入失败（或markitdown命令缺失）时，运行pip install安装缺失的包。
以下脚本路径相对于本技能目录。
每个输出的要求
- 专业字体（Arial、Times New Roman）贯穿全文，除非用户另有要求。
- 零公式错误。 绝不要输出
recalc.py报告errors_found的文件。如果你认为错误在你之前就已存在，请证明：用data_only=True加载原文件并查看该单元格。你引入的错误看起来与继承的错误完全相同。 - 使用公式，绝不使用硬编码结果。 写入
sheet['B10'] = '=SUM(B2:B9)'，而不是 Python 计算的总和。工作表必须在输入变化时重新计算。 - 严格遵循用户的规格说明。 确切的选项卡名称、确切的列标题以及他们明确说明的公式。任何计算其他内容的重新设计都是失败的，无论多么优雅。
- 记录每个假设和硬编码数字，放在读者能看到的地方 — 单元格批注，或表格末尾的相邻单元格。有真实来源时引用来源（
来源：公司 10-K，2024 财年，第 45 页，收入附注，[SEC EDGAR URL]）；当数字来自用户时，直接说明。 - 你创建的、供他人填写的工作簿需要包含一个简短的图例，说明哪些单元格需要编辑，并包含一行示例行，显示预期的格式并包含真实值。绝不要将这样的示例行添加到被要求编辑的文件中。
- 编辑现有文件时：完全遵循其约定。 它们覆盖这里的每一条指南。首先找到其指定的输入单元格 — 通常以不同的字体颜色、填充或阴影标记 — 仅在这些单元格中写入，并保持所有现有公式不变。
重新计算（只要文件包含公式就必须执行）
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，而不是列表的长度）。修复它命名的内容并再次运行。JSON 包含 error 键而非 status 键表示没有进行任何重新计算，只有这种情况会退出并返回非零状态 — errors_found 退出状态为 0，所以绝不要将干净的退出视为工作簿干净。
一次成功的重新计算证明你的公式可求值，而不是它们是正确的。 一个差一错误的范围或引用错误行的公式会生成一个干净、无错误但数字错误的数据。在构建整个网格之前，先编写 2-3 个公式并检查它们是否按预期拉取数值。
一个链接到其他文件的工作簿如果使用 openpyxl 重新保存然后重新计算，就会丢失这些链接。这样的公式读起来像 ='[1]Returns Analysis'!$B$2 — 其中 [1] 是工作簿外部引用列表中的索引，命名的是磁盘上的一个单独文件，而不是一个工作表。该文件在这里很少存在，因此该单元格的缓存值是唯一保存其数据的东西。openpyxl 在保存时会剥离该值；然后 LibreOffice 必须真正解析该引用，失败，写入 #NAME?，并删除所有链接。recalc.py 在这种状态下拒绝运行 — 在覆盖保存之前，将那些单元格的值从原始文件中复制出来（--force 会覆盖并接受数据丢失）。
选择能通过验证的公式
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 无法在任何前缀下评估它们。较新的版本可以评估它们，但它们会溢出数组函数，而用 openpyxl 写入的文件没有溢出元数据，因此只有该范围的左上角单元格会获得一个值 — 而recalc.py会在截断的结果上报告total_errors: 0。对于查找，使用INDEX/MATCH；在写入单元格之前，在 Python 中完成排序、筛选和去重。 - 一个 LibreOffice 无法解析的公式会被小写写回 — 这是在
#NAME?旁边的快速判断标志。
openpyxl 注意事项
- 读取模型需要两次加载。
data_only=True返回缓存值，但公式消失；默认值返回公式字符串，但没有值。一次调用无法同时提供两者。 - 如果保存，
data_only=True具有破坏性。 该工作簿不再包含任何公式，因此保存会将每个公式永久替换为字面量。 - 对刚刚由 openpyxl 写入的文件使用
data_only=True会全部返回None— 先运行recalc.py。（结果为""的公式也会读回为None。） - 合并单元格：只写入左上角的锚点。 区域中的每个其他单元格都是只读的
MergedCell。 - 除非向
load_workbook传递keep_vba=True，否则.xlsm会丢失其宏。 - 包含空格的工作表名称在跨工作表引用中必须加引号：
='Assumptions Inputs'!$B$5。不加引号会求值为#VALUE!。
财务模型
除非用户另有说明，或现有文件已经采用了其他方式。
颜色： 蓝色文本（0,0,255）用于硬编码输入和情景杠杆 · 黑色用于公式 · 绿色（0,128,0）用于指向其他工作表的链接 · 红色（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） · 每个预测期间的公式保持一致，因为行中间单独编辑的单元格是最常见的无声错误 · 保护可能为零的分母。
依赖项
openpyxl、pandas、markitdown（pip，已预装 — 仅当导入失败或命令缺失时安装） · LibreOffice（soffice，通过 scripts/office/soffice.py 自动配置适用于沙箱环境）