xlsx

用途

该技能适用于任何以电子表格文件为主要输入或输出的任务，包括打开、读取、编辑或修复现有的 .xlsx 文件，以及创建新的 Excel 工作簿和进行分析。

主要能力

• 使用 pandas 读取与分析数据，支持读取首个工作表、以字典形式读取全部工作表，并支持预览、列信息查看与统计描述。
• 使用 pandas 导出数据到 Excel。
• 使用 openpyxl 创建新工作簿，添加数据、公式、字体、填充、对齐与列宽设置。
• 使用 openpyxl 加载并编辑现有文件，保留公式与格式，可跨工作表操作、修改单元格、插入行、删除列、新增工作表。
• 通过 scripts/recalc.py 脚本对公式进行重算并扫描全部单元格中的 Excel 错误。

输出要求

适用于所有 Excel 文件的要求包括：使用统一、专业的字体（如 Arial、Times New Roman），除非用户另有指示；每个 Excel 模型交付时必须零公式错误（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）；在更新模板时，必须研究并完全匹配现有格式、样式与约定，不得对已有既定模式的文件夹硬套标准化格式，现有模板约定始终优先于本指南。

财务模型的颜色编码标准（除非用户或现有模板另有说明）：蓝色文字（RGB: 0,0,255）用于硬编码输入及用户会为情景调整的数字；黑色文字（RGB: 0,0,0）用于所有公式与计算；绿色文字（RGB: 0,128,0）用于同一工作簿内引用其他工作表的链接；红色文字（RGB: 255,0,0）用于指向其他文件的外部链接；黄色背景（RGB: 255,255,0）用于需要关注的关键假设或需要更新的单元格。

数字格式标准

年份格式化为文本字符串（如 "2024" 而非 "2,024"）；货币使用 $#,##0 格式，并始终在表头注明单位（如 "Revenue ($mm)"）；使用数字格式让所有零显示为 "-"，包括百分比（如 "$#,##0;($#,##0);-"）；百分比默认使用 0.0% 格式（一位小数）；倍数使用 0.0x 格式（估值倍数 EV/EBITDA、P/E）；负数使用括号 (123) 而非负号 -123。

公式构建规则

所有假设（增长率、利润率、倍数等）应放在单独的假设单元格中，公式中使用单元格引用而非硬编码值，例如使用 =B5*(1+$B$6) 而非 =B5*1.05。公式错误预防要求：验证所有单元格引用正确；检查区域是否存在差一错误；确保所有预测期间的公式一致；用边界情况（零值、负数）测试；确认没有意外的循环引用。硬编码值需附文档说明，格式为 "Source: [系统/文档], [日期], [具体引用], [URL 如适用]"，示例包括 "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"、"Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity" 等。

使用方式

• 关键原则：使用公式而非硬编码值。应始终用 Excel 公式而非 Python 计算结果并硬编码，以保证表格保持动态可更新。正确做法如 sheet['B10'] = '=SUM(B2:B9)'、sheet['C5'] = '=(C4-C2)/C2'、sheet['D20'] = '=AVERAGE(D2:D19)'；错误做法如在 Python 中计算总和、增长率、平均值后直接写入结果。此原则适用于所有计算，包括总计、百分比、比率、差额等，表格应能在源数据变化时重新计算。
• 常见工作流：选择工具（数据用 pandas，公式/格式化用 openpyxl）；创建或加载工作簿；修改数据、公式与格式；保存到文件；若使用公式则必须用 scripts/recalc.py 重算，命令为 python scripts/recalc.py output.xlsx；随后根据脚本返回的 JSON 检查并修复错误，若 status 为 errors_found，则查看 error_summary 中的错误类型与位置，修复后再次重算。常见需修复的错误包括 #REF!（无效单元格引用）、#DIV/0!（除零）、#VALUE!（公式中数据类型错误）、#NAME?（无法识别的公式名称）。
• 公式重算：由 openpyxl 创建或修改的 Excel 文件中的公式仅以字符串形式存在，没有计算值，需使用 scripts/recalc.py 重算。命令为 python scripts/recalc.py <excel_file> [timeout_seconds]，例如 python scripts/recalc.py output.xlsx 30。脚本在首次运行时自动设置 LibreOffice 宏，重算所有工作表中的全部公式，扫描所有单元格中的 Excel 错误（#REF!、#DIV/0! 等），返回带有详细错误位置与数量的 JSON，适用于 Linux 与 macOS。
• 公式验证清单：测试 2-3 个样本引用，确认取值正确后再构建完整模型；确认 Excel 列映射正确（如第 64 列是 BL 而非 BK）；注意 Excel 行从 1 开始计数（DataFrame 第 5 行对应 Excel 第 6 行）。常见陷阱包括：用 pd.notna() 检查空值；FY 数据常在 50 列之后；搜索所有匹配项而非仅第一个；使用除法前检查分母；验证所有单元格引用指向预期单元格；跨工作表引用使用正确格式（Sheet1!A1）。公式测试策略为：先在 2-3 个单元格上小范围测试；检查公式引用的所有单元格是否存在；测试零、负数与极大值等边界情况。
• scripts/recalc.py 输出解读：返回 JSON 包含 status（success 或 errors_found）、total_errors（错误总数）、total_formulas（文件中的公式数量）与 error_summary（仅在发现错误时出现，含各错误类型及其数量与位置）。

最佳实践

库选择上，pandas 最适合数据分析、批量操作与简单数据导出；openpyxl 最适合复杂格式化、公式与 Excel 专有功能。使用 openpyxl 时，单元格索引从 1 开始（row=1, column=1 指 A1）；可用 data_only=True 读取计算值，但需注意若以此方式打开并保存，公式会被值替换并永久丢失；大文件可用 read_only=True 读取或 write_only=True 写入；公式会被保留但不会被求值，需用 scripts/recalc.py 更新值。使用 pandas 时，可指定数据类型避免推断问题（如 pd.read_excel('file.xlsx', dtype={'id': str})）；大文件可只读取特定列（usecols=['A','C','E']）；正确处理日期（parse_dates=['date_column']）。

代码风格

生成 Excel 操作的 Python 代码时应编写最小、简洁的代码，不加多余注释，避免冗长变量名与冗余操作，避免不必要的 print 语句。对 Excel 文件本身，应为含复杂公式或重要假设的单元格添加注释，为硬编码值记录数据来源，并为关键计算与模型分节添加说明。

适用场景与限制

适用场景包括读取与分析电子表格数据、创建与编辑 Excel 文件、构建需要动态公式的财务模型、以及修复现有表格中的公式错误。限制方面：公式重算依赖 LibreOffice 环境；openpyxl 创建的公式不会自动求值，必须使用 scripts/recalc.py；以 data_only=True 打开并保存会永久丢失公式。具体价格、版本要求与其他平台支持情况暂未提供。