xlsx

输出要求

所有 Excel 文件

零公式错误

• 交付的每个 Excel 模型都 MUST 不含任何公式错误（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）

保留现有模板（更新模板时）

• 修改文件时，应仔细研究并 EXACTLY 匹配现有格式、样式和惯例
• 如果文件已有成熟的格式模式，切勿强行套用标准化格式
• 现有模板惯例始终优先于本指南

财务模型

对于财务模型、DCF 和估值，请阅读 references/financial-model-standards.md，了解颜色编码、数字格式、公式构建规则和文档要求。

XLSX 创建、编辑和分析

概述

用户可能会要求你创建、编辑或分析 .xlsx 文件的内容。针对不同任务，你可以使用不同的工具和工作流。

重要要求

公式重新计算必须使用 LibreOffice：你可以假设已安装 LibreOffice，以便使用 recalc.py 脚本重新计算公式值。该脚本会在首次运行时自动配置 LibreOffice。

数据读取与分析

使用 pandas 进行数据分析

进行数据分析、可视化和基本操作时，请使用 pandas，它能提供强大的数据处理功能：

import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyse
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)

关键：使用公式，而非硬编码值

**始终使用 Excel 公式，而不是在 Python 中计算数值后再将其硬编码。**这样可以确保电子表格保持动态并可更新。

错误做法 - 将计算结果硬编码

# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5

正确做法 - 使用 Excel 公式

# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'

这适用于所有计算——总计、百分比、比率、差值等。源数据变更后，电子表格应能够重新计算。

常见工作流

1. 选择工具：数据使用 pandas，公式/格式使用 openpyxl
2. 创建/加载：创建新工作簿或加载现有文件
3. 修改：添加/编辑数据、公式和格式
4. 保存：写入文件
5. 重新计算公式（使用公式时为必需步骤）：使用 recalc.py 脚本

   python recalc.py output.xlsx
   

6. 验证并修复所有错误：
   • 脚本会返回包含错误详情的 JSON
   • 如果 status 为 errors_found，请检查 error_summary 中的具体错误类型和位置
   • 修复已发现的错误，然后再次重新计算
   • 常见错误及修复方法：
     • #REF!：单元格引用无效
     • #DIV/0!：除数为零
     • #VALUE!：公式中的数据类型错误
     • #NAME?：无法识别的公式名称

如需详细代码示例（创建/编辑文件），请阅读 references/openpyxl-patterns.md。

重新计算公式

openpyxl 创建或修改的 Excel 文件会将公式保存为字符串，而不包含计算结果。请使用提供的 recalc.py 脚本重新计算：

python recalc.py <excel_file> [timeout_seconds]

示例：

python recalc.py output.xlsx 30

该脚本：

• 首次运行时自动设置 LibreOffice 宏
• 重新计算所有工作表中的全部公式
• 扫描所有单元格，查找 Excel 错误（#REF!、#DIV/0! 等）
• 返回包含详细错误位置和数量的 JSON
• 可在 Linux 和 macOS 上运行

如需查看公式验证清单以及如何解读 recalc.py 的输出，请阅读 references/formula-verification.md。

代码风格指南

重要：生成用于 Excel 操作的 Python 代码时：

• 编写精简简洁的 Python 代码，不添加不必要的注释
• 避免使用冗长的变量名和冗余操作
• 避免不必要的 print 语句

对于 Excel 文件本身：

• 为包含复杂公式或重要假设的单元格添加注释
• 记录硬编码值的数据来源
• 为关键计算和模型部分添加说明

参考资料

• references/financial-model-standards.md - 财务模型的颜色编码、数字格式、公式构建规则和文档要求
• references/openpyxl-patterns.md - 文件创建和编辑的代码示例、库选择指南、openpyxl 和 pandas 使用技巧
• references/formula-verification.md - 验证清单、常见陷阱、recalc.py 输出解读