excel-spreadsheets

Excel 电子表格

适用场景

工具	适用场景
create_excel_spreadsheet	用户要求创建/生成新的电子表格
modify_excel_spreadsheet	用户要求编辑/更新现有电子表格
list_my_excel_spreadsheets	用户询问有哪些可用的电子表格
read_excel_spreadsheet	用户希望下载或读取电子表格内容
preview_excel_sheets	编辑时检查工作表的实际外观

工作流

1. 修改前：调用 preview_excel_sheets 检查当前布局。
2. 创建/修改后：调用 preview_excel_sheets 进行验证。
3. 按顺序运行工具（切勿并行），以防止文件竞争情况。

专业格式

• 字体：除非现有模板另有指定，否则所有单元格均使用 Arial。
• 负数：使用括号格式 (1,234)，而不是减号 -1,234。
• 货币：使用 $#,##0 格式。在标题中注明单位（例如，“收入（$mm）”）。
• 百分比：使用 0.0%（保留一位小数）。
• 年份：设置为文本格式（"2024"，而不是 "2,024"）。
• 零值：使用自定义数字格式显示为 "-"。

# Example: professional number formatting
from openpyxl.styles import numbers
ws['B2'].number_format = '$#,##0'          # Currency
ws['C2'].number_format = '0.0%'            # Percentage
ws['D2'].number_format = '#,##0;(#,##0)'   # Negative in parentheses
ws['E2'].number_format = '@'               # Year as text
ws['F2'].number_format = '#,##0;(#,##0);"-"'  # Zeros as dash

财务模型颜色编码

构建财务模型时，请应用以下惯例：

颜色	Hex	用途
蓝色文本	0000FF	硬编码输入值和假设
黑色文本	000000	所有公式和计算
绿色文本	008000	从其他工作表提取数据的链接
黄色背景	FFFF00	需要关注的关键假设

from openpyxl.styles import Font, PatternFill
ws['B2'].font = Font(name='Arial', color='0000FF')       # Blue: input
ws['B3'].font = Font(name='Arial', color='000000')       # Black: formula
ws['B4'].font = Font(name='Arial', color='008000')       # Green: cross-sheet link
ws['B5'].fill = PatternFill('solid', fgColor='FFFF00')   # Yellow bg: key assumption

图片

from openpyxl.drawing.image import Image
ws.add_image(Image('file.png'), 'E1')

代码规则

• 工作簿已预先初始化为 wb = Workbook()，活动工作表为 ws = wb.active（创建时），或已作为 wb 加载（修改时）。不要包含 Workbook() 或 wb.save()。
• 可用库：openpyxl、matplotlib、pandas、numpy（seaborn 不可用）
• 始终使用 Excel 公式，绝不要对计算值进行硬编码。
  • 错误：ws['B10'] = total
  • 正确：ws['B10'] = '=SUM(B2:B9)'
• 将假设放在单独的单元格中，并在公式中引用它们（例如，使用 =B5*(1+$B$6)，而不是 =B5*1.05）。
• 避免循环引用。
• 文件名：只能包含字母、数字和连字符。

---

工具参考

create_excel_spreadsheet

使用 openpyxl 代码创建新的 Excel 电子表格。

参数	类型	必填	描述
python_code	str	是	使用 openpyxl 的 Python 代码（参见上文的代码规则）
spreadsheet_name	str	是	不含扩展名的文件名（只能包含字母、数字和连字符）

工具输入示例：

{
  "python_code": "ws.title = 'Sales'\nws['A1'] = 'Quarter'\nws['B1'] = 'Revenue'\nfor i, (q, r) in enumerate(zip(['Q1','Q2','Q3','Q4'], [100,150,130,180]), start=2):\n    ws[f'A{i}'] = q\n    ws[f'B{i}'] = r",
  "spreadsheet_name": "quarterly-sales"
}

警告：参数是 spreadsheet_name，不是 filename 或 name。

modify_excel_spreadsheet

修改现有电子表格，并使用新名称保存。

参数	类型	必填	描述
source_name	str	是	现有电子表格名称（不含 .xlsx）
output_name	str	是	新的输出名称（必须与源名称不同）
python_code	str	是	用于修改电子表格的 Python 代码

工具输入示例：

{
  "source_name": "quarterly-sales",
  "output_name": "quarterly-sales-v2",
  "python_code": "ws = wb.active\nws['B6'] = '=SUM(B2:B5)'"
}

list_my_excel_spreadsheets

列出工作区中的所有电子表格。无需参数。

read_excel_spreadsheet

获取指定电子表格以供下载。

参数	类型	必填
spreadsheet_name	str	是

preview_excel_sheets

获取工作表截图，以便在编辑前进行目视检查。

参数	类型	必填	描述
spreadsheet_name	str	是	不含扩展名的电子表格名称
sheet_names	list[str]	是	要预览的工作表名称（空列表 [] 表示所有工作表）

UI 指南（来自 tools-config）

必须按顺序执行： 依次运行修改工具，切勿并行运行（以避免 S3 文件读写时发生竞态条件）。

使用场景：

• create_excel_spreadsheet：用户要求创建/生成新的 Excel 电子表格
• modify_excel_spreadsheet：用户要求编辑/修改/更新现有电子表格
• list_my_excel_spreadsheets：用户询问有哪些电子表格可用
• read_excel_spreadsheet：用户想要下载或读取电子表格内容
• preview_excel_sheets：编辑时检查工作表的实际外观

修改前： 始终先使用 preview_excel_sheets 查看当前布局。

重要 — 使用公式，而非硬编码数值：

• 始终使用 Excel 公式。切勿在 Python 中计算后将结果硬编码。
• 错误：ws['B10'] = total。正确：ws['B10'] = '=SUM(B2:B9)'
• 将假设值放在单独的单元格中，并在公式中引用这些单元格（例如，=B5*(1+$B$6)，而非 =B5*1.05）
• 保存后，公式会通过 LibreOffice 自动重新计算。
• 避免循环引用。

专业格式：

• 字体：除非现有模板另有规定，否则所有单元格均使用 Arial
• 负数：使用括号格式 (1,234)，而非带负号的 -1,234
• 货币：$#,##0 格式；在标题中注明单位（“Revenue ($mm)”）
• 百分比：0.0%（保留一位小数）
• 年份：设为文本格式（“2024”，而非“2,024”）
• 零值：使用自定义数字格式显示为“-”

财务模型颜色编码（适用时）：

• 蓝色文本 (0,0,255)：硬编码输入值和假设值
• 黑色文本 (0,0,0)：所有公式和计算
• 绿色文本 (0,128,0)：从其他工作表引用的数据
• 黄色背景 (255,255,0)：需要关注的关键假设值

文件名： 仅使用字母、数字和连字符（例如，“Q4-sales.xlsx”）

可用库： openpyxl、matplotlib、pandas、numpy（不提供 seaborn）

图像： from openpyxl.drawing.image import Image; ws.add_image(Image('file.png'), 'E1')

质量检查： 创建后始终使用 preview_excel_sheets 检查外观。