spreadsheet

用途

Spreadsheet 技能适用于涉及电子表格（.xlsx、.csv、.tsv）的创建、编辑、分析或格式化任务。具体使用场景包括：

构建带公式、格式和结构化布局的新工作簿。
读取或分析表格数据（筛选、聚合、透视、计算指标）。
在不破坏公式或引用的前提下修改现有工作簿。
用图表/表格和合理格式可视化数据。

注意：系统指令和用户指令始终优先于本技能说明。

主要能力

使用 openpyxl 创建/编辑 .xlsx 文件并保留格式。
使用 pandas 进行分析和 CSV/TSV 工作流，再将结果写回 .xlsx 或 .csv。
如需图表，优先使用 openpyxl.chart 生成原生 Excel 图表。
支持公式编写、引用来源、格式与配色规范，以及财务和投行模型布局要求。

使用方式

工作流程：

确认文件类型和目标（创建、编辑、分析、可视化）。
用 openpyxl 编辑 .xlsx，用 pandas 做分析和 CSV/TSV 工作流。
如果布局重要，渲染以进行视觉检查（见下方渲染与视觉检查）。
验证公式和引用；注意 openpyxl 不会计算公式。
保存输出并清理中间文件。

临时与输出约定：

中间文件放在 tmp/spreadsheets/，完成后删除。
在本仓库工作时，最终产物写入 output/spreadsheet/。
保持文件名稳定且具描述性。

渲染与视觉检查：

如果可用 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

可选（图表较多或 PDF 审查工作流）：

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/。

公式要求

派生值使用公式而非硬编码结果。
公式保持简单易读；复杂逻辑使用辅助单元格。
除非必要，避免使用 INDIRECT 和 OFFSET 等易变函数。
优先使用单元格引用而非魔法数字（例如 =H6*(1+$B$3) 而非 =H6*1.04）。
通过验证和检查防范错误（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）。
openpyxl 不会计算公式；保留公式原样，并说明结果将在 Excel/Sheets 中计算。

引用要求

在电子表格内使用纯文本 URL 引用来源。
对于财务模型，在单元格批注中引用输入来源。
对于来自网络的表格数据，包含一个带 URL 的 Source 列。

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

尽可能在修改前渲染并检查提供的电子表格。
精确保留现有格式和样式。
新填充的、此前为空的单元格要匹配样式。

格式要求（新建或无样式电子表格）

使用合适的数字和日期格式（日期用日期格式，货币带符号，百分比精度合理）。
使用干净的视觉布局：表头与数据区分，间距一致，列宽可读。
避免每个单元格都加边框；用留白和选择性边框来组织区块。
确保文本不会溢出到相邻单元格。

配色约定（如无样式指引）

蓝色：用户输入
黑色：公式/派生值
绿色：链接/导入值
灰色：静态常量
橙色：审查/注意
浅红色：错误/标记
紫色：控制/逻辑
青色：可视化锚点（关键 KPI 或图表驱动项）

财务专用要求

零格式化为“-”。
负数用红色并加括号。
表头始终标明单位（例如“Revenue ($mm)”）。
所有原始输入在单元格批注中引用来源。

投行布局

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

合计应直接对上方区域求和。
隐藏网格线；在合计上方跨相关列使用水平边框。
区块标题应为合并单元格，深色填充、白色文字。
数值数据的列标签右对齐；行标签左对齐。
子指标在父级行项目下缩进。

适用场景

构建带公式和格式的新工作簿。
分析表格数据并输出指标或透视结果。
修改现有工作簿且需保留公式和格式。
制作图表和可视化。
财务建模和投行风格模型布局。

限制

openpyxl 不会计算公式，结果需在 Excel/Sheets 中计算。
渲染与视觉检查依赖 LibreOffice 和 Poppler，若不可用需用户本地检查。
依赖需手动安装（openpyxl、pandas，可选 matplotlib）。
系统指令和用户指令始终优先。