Excel 创建、编辑与分析

概述

用户可能要求创建、编辑或分析 .xlsx 文件。根据任务类型选择合适的工具和工作流。

重要: 本项目已内置 create_document、read_document、edit_document 工具支持 Excel 操作。优先使用这些内置工具，以下 pandas/openpyxl 指南用于复杂场景。

使用内置工具（推荐）

创建 Excel 文件

<create_document>
<type>excel</type>
<file_path>/path/to/output.xlsx</file_path>
<document_data>{"sheets":[{"name":"Sheet1","data":[["姓名","年龄","城市"],["张三",28,"北京"],["李四",32,"上海"]],"column_widths":[20,10,15],"formulas":[{"cell":"D2","formula":"=B2+1"}]}]}</document_data>
</create_document>

注意: type 必须是 "excel"（不是 "xlsx"）。

读取 Excel 文件

<read_document>
<uri>/path/to/file.xlsx</uri>
</read_document>

编辑现有 Excel 文件

<edit_document>
<uri>/path/to/file.xlsx</uri>
<content>新内容追加到文件</content>
</edit_document>

转换为其他格式

<document_convert>
<input_file>/path/to/file.xlsx</input_file>
<output_path>/path/to/file.pdf</output_path>
<format>pdf</format>
</document_convert>

输出标准

所有 Excel 文件

专业字体: 使用一致的专业字体（Arial、Times New Roman），除非用户另有指定
零公式错误: 交付的 Excel 必须零公式错误（#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?）
保留现有模板: 修改文件时严格匹配现有格式、样式和惯例

财务模型色彩规范

颜色	用途
蓝色文字 (0,0,255)	硬编码输入、场景分析变量
黑色文字 (0,0,0)	所有公式和计算
绿色文字 (0,128,0)	同工作簿跨工作表引用
红色文字 (255,0,0)	外部文件链接
黄色背景 (255,255,0)	需关注的关键假设

数字格式规范

年份: 格式为文本（"2024" 非 "2,024"）
货币: 使用 $#,##0，标题必须标明单位（"收入 ($万)"）
零值: 格式化为 "-"
百分比: 默认 0.0%（一位小数）
倍数: 格式为 0.0x（EV/EBITDA, P/E）
负数: 使用括号 (123) 而非 -123

关键原则：使用公式而非硬编码

始终使用 Excel 公式，不要在 Python 中计算后硬编码结果。

# ❌ 错误 - 硬编码计算值
total = df['Sales'].sum()
sheet['B10'] = total  # 硬编码 5000

# ✅ 正确 - 使用 Excel 公式
sheet['B10'] = '=SUM(B2:B9)'

工作流

数据分析（pandas）

import pandas as pd

df = pd.read_excel('file.xlsx')              # 默认第一个工作表
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # 所有表

df.head()       # 预览
df.info()       # 列信息
df.describe()   # 统计摘要

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

创建新文件（openpyxl）

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

sheet['A1'] = '标题'
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')
sheet.column_dimensions['A'].width = 20

# 使用公式
sheet['B10'] = '=SUM(B2:B9)'

wb.save('output.xlsx')

编辑现有文件

from openpyxl import load_workbook

wb = load_workbook('existing.xlsx')
sheet = wb.active  # 或 wb['SheetName']

sheet['A1'] = '新值'
sheet.insert_rows(2)
sheet.delete_cols(3)

wb.save('modified.xlsx')

公式验证清单

必检项

抽样验证 2-3 个引用的正确性
列映射确认（列64 = BL，非 BK）
行偏移：Excel 行从1开始（DataFrame 行5 = Excel 行6）

常见陷阱

NaN 处理：用 pd.notna() 检查空值
除零错误：公式中 / 前检查分母
引用错误：验证所有单元格引用指向正确位置
跨表引用：使用正确格式 Sheet1!A1

库选择指南

库	适用场景
pandas	数据分析、批量操作、简单数据导出
openpyxl	复杂格式、公式、Excel 特有功能

openpyxl 注意事项

单元格索引从1开始
data_only=True 读取计算值（保存后公式会丢失！）
大文件使用 read_only=True 或 write_only=True
公式保留但不求值，需要外部工具重新计算

pandas 注意事项

指定数据类型避免推断问题：dtype={'id': str}
大文件读取特定列：usecols=['A', 'C', 'E']
正确处理日期：parse_dates=['date_column']