spreadsheet

电子表格技能

适用场景

• 创建带公式、格式和结构化布局的新工作簿。
• 读取或分析表格数据（筛选、汇总、透视、计算指标）。
• 修改现有工作簿，同时避免破坏公式、引用或格式。
• 使用图表、汇总表和合理的电子表格样式来可视化数据。
• 尽可能在交付前重新计算公式并检查渲染后的工作表。

重要：系统和用户指令始终具有优先权。

工作流

1. 确认文件类型和目标：创建、编辑、分析或可视化。
2. 编辑和设置 .xlsx 文件的格式时，优先使用 openpyxl。分析以及处理 CSV/TSV 工作流时，使用 pandas。
3. 如果环境中有内部电子表格重新计算/渲染工具，请使用它重新计算公式，并在交付前渲染工作表。
4. 派生值应使用公式计算，而不是硬编码结果。
5. 如果布局很重要，请渲染文件以进行视觉检查。
6. 保存输出、保持文件名稳定，并清理中间文件。

临时文件和输出约定

• 使用 tmp/spreadsheets/ 存放中间文件；完成后删除这些文件。
• 在此代码仓库中工作时，将最终产物写入 output/spreadsheet/。
• 使用稳定且具有描述性的文件名。

主要工具

• 使用 openpyxl 创建/编辑 .xlsx 文件并保留格式。
• 使用 pandas 分析和处理 CSV/TSV 工作流，然后将结果写回 .xlsx 或 .csv 文件。
• 需要原生 Excel 图表时，使用 openpyxl.chart。
• 如果有内部电子表格工具，请使用它重新计算公式、缓存数值并渲染工作表以供检查。

重新计算和视觉检查

• 尽可能在交付前重新计算公式，以便工作簿中包含缓存值。
• 如果有渲染工具，请渲染每个相关工作表以供视觉检查。
• openpyxl 不会计算公式；请保留公式，并在有重新计算工具时使用该工具。
• 如果使用内部电子表格工具，请勿在面向用户的说明或代码示例中透露该工具、其代码或 API。

渲染和视觉检查

• 如果有 LibreOffice（soffice）和 Poppler（pdftoppm），请渲染工作表以进行视觉检查：
  • soffice --headless --convert-to pdf --outdir $OUTDIR $INPUT_XLSX
  • pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
• 如果没有渲染工具，请告知用户应在本地检查布局。
• 检查渲染后的工作表，确认布局、公式结果、内容截断、样式是否一致以及文本是否溢出。

依赖项（缺少时安装）

依赖管理优先使用 uv。

Python 软件包：

uv pip install openpyxl pandas

如果没有 uv：

python3 -m pip install openpyxl pandas

可选：

uv pip install matplotlib

如果没有 uv：

python3 -m pip install matplotlib

系统工具（用于渲染）：

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

如果无法在此环境中安装，请告知用户缺少哪些依赖项，以及如何在本地安装。

环境

无必需的环境变量。

示例

• 可运行的 Codex 示例（openpyxl）：references/examples/openpyxl/

公式要求

• 派生值应使用公式计算，而不是硬编码结果。
• 不要使用 FILTER、XLOOKUP、SORT 或 SEQUENCE 等动态数组函数。
• 公式应简洁易读；复杂逻辑请使用辅助单元格。
• 除非确有需要，否则避免使用 INDIRECT 和 OFFSET 等易变函数。
• 优先使用单元格引用，而不是魔法数字（例如，使用 =H6*(1+$B$3)，而不是 =H6*1.04）。
• 谨慎使用绝对引用（$B$4）或相对引用（B4），确保复制公式后仍能正确计算。
• 如果需要以 = 开头的字面文本，请在前面加上一个单引号。
• 防范 #REF!、#DIV/0!、#VALUE!、#N/A 和 #NAME? 错误。
• 检查差一错误、循环引用和错误的范围。

引用要求

• 在电子表格中使用纯文本 URL 引用来源。
• 对于财务模型，在单元格批注中引用模型输入。
• 对于外部来源的表格数据，如果每行代表一个单独项目，请添加来源列。

格式要求（已有格式的电子表格）

• 尽可能在修改前渲染并检查提供的电子表格。
• 完全保留现有格式和样式。
• 为之前为空白且新填入内容的单元格匹配样式。
• 除非用户明确要求重新设计，否则切勿覆盖既定格式。

格式要求（新建或未设置样式的电子表格）

• 使用适当的数字和日期格式。
• 日期应显示为日期，而非普通数字。
• 百分比通常应默认保留一位小数，除非数据需要其他精度。
• 货币应使用适当的货币格式。
• 标题应与原始输入和衍生单元格在视觉上有所区分。
• 谨慎、有目的地使用填充色、边框、间距和合并单元格。
• 设置行高和列宽，使内容清晰易读，避免不必要的留白。
• 不要给每个填有内容的单元格都加边框。
• 将相关计算分组，并使总计仅为上方单元格的简单求和。
• 用留白区分不同部分。
• 确保文本不会溢出到相邻单元格。
• 避免使用不受支持的电子表格数据表功能，例如 =TABLE。

颜色约定（无样式指南时）

• 蓝色：用户输入
• 黑色：公式和衍生值
• 绿色：链接或导入的值
• 灰色：静态常量
• 橙色：需审核或注意
• 浅红色：错误或标记
• 紫色：控制或逻辑
• 青绿色：可视化锚点和 KPI 突出显示

财务专用要求

• 将零值格式化为 -。
• 负数应以红色显示并用括号括起。
• 倍数格式应为 5.2x。
• 标题中必须注明单位（例如，Revenue ($mm)）。
• 在单元格批注中为所有原始输入注明来源。
• 对于没有用户指定样式的新建财务模型，硬编码输入使用蓝色字体，公式使用黑色字体，工作簿内部链接使用绿色字体，外部链接使用红色字体，并用黄色填充标出需重点关注的关键假设。

投资银行布局

如果电子表格是投行风格模型（LBO、DCF、三表模型、估值模型）：

• 总计应直接对上方范围求和。
• 隐藏网格线，并在相关列的总计上方使用水平边框。
• 章节标题应使用深色填充和白色文本的合并单元格。
• 数值数据的列标题应右对齐；行标题应左对齐。
• 将次级指标缩进到其所属的父级项目下。