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 链接]）；当数字来自用户时，请直接说明。 - 你创建的供他人填写的工作簿需要包含一个简短的图例，说明哪些单元格需要编辑，并提供一个示例行，其中包含显示预期格式的真实值。绝不要在你被要求编辑的文件中添加这样的行。
- 编辑现有文件：严格遵循其约定。 它们覆盖这里的每一条指南。首先找到其指定的输入单元格 — 通过独特的字体颜色、填充或底纹标记 — 只在那里写入，并保持所有现有公式不变。
重新计算（当文件包含公式时必须执行）
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。- 包含空格的表名必须在跨表引用中引用：
='假设输入'!$B$5。如果不引用，则求值为#VALUE!。
金融模型
除非用户另有说明，或现有文件已采用其他方式。
颜色： 蓝色文本 (0,0,255) 用于硬编码输入和场景杠杆 · 黑色用于公式 · 绿色 (0,128,0) 用于链接到其他工作表 · 红色 (255,0,0) 用于链接到其他文件 · 黄色填充 (255,255,0) 用于关键假设和用户应填写的单元格。
数字： 货币 $#,##0，并在标题中命名单位（收入 ($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 为沙盒环境自动配置）