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，其.value是只读的。 .xlsm会丢失其宏，除非你向load_workbook传递keep_vba=True。- 包含空格的工作表名称必须在跨表引用中加引号：
='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 为沙盒环境自动配置）