xlsx

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 计算出的总额。当输入变化时，工作表必须能够重新计算。
• 严格遵循用户的规格说明。 精确的工作表名称、精确的列标题，以及用户明确给出的公式。无论多么优雅，改动计算逻辑的重新设计都是失败的。
• 在读者可见之处记录每个假设和硬编码数值——可以是单元格批注，也可以是表格末尾的相邻单元格。若存在真实来源，需引用（Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]）；若数值来自用户，需明确说明。
• 为他人填写而创建的工作簿需要一段简短的说明，指明应编辑哪些单元格，并附上一行符合实际的示例数据，展示预期格式。切勿在你被要求编辑的文件中添加此类示例行。
• 编辑现有文件：严格匹配其约定。 这些约定优先于本文中的所有指南。先找出其指定的输入单元格——独特的字体颜色、填充或底纹会标示它们——仅在这些单元格中写入，并保持所有现有公式不变。

重新计算（只要文件包含公式就必须执行）

openpyxl 会将公式以字符串形式写入，且不包含缓存值。在重新计算之前，任何读取缓存值的程序（如 pandas、load_workbook(data_only=True) 以及大多数预览工具）读到的每个公式单元格都是 None。

python scripts/recalc.py output.xlsx [timeout_seconds]   # default 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 会在这些函数名前加上前缀存储（其界面中隐藏了该前缀）：_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 自动配置）