---
name: "spreadsheet"
description: "当任务涉及创建、编辑、分析或格式化电子表格（`.xlsx`、`.csv`、`.tsv`）时使用，具有公式感知的工作流程、缓存重新计算和视觉审查。"
---

# 电子表格技能

## 何时使用
- 创建具有公式、格式和结构化布局的新工作簿。
- 读取或分析表格数据（过滤、聚合、透视、计算指标）。
- 修改现有工作簿而不破坏公式、引用或格式。
- 使用图表、汇总表和合理的电子表格样式可视化数据。
- 在可能的情况下，在交付之前重新计算公式并审查渲染的工作表。

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

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

## 临时和输出约定
- 使用 `tmp/spreadsheets/` 作为中间文件；完成后删除它们。
- 在此仓库中工作时，将最终工件写入 `output/spreadsheet/`。
- 保持文件名稳定和描述性。

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

## 重新计算和视觉审查
- 尽可能在交付前重新计算公式，以便工作簿中存在缓存值。
- 当有可用的渲染工具时，渲染每个相关的工作表以进行视觉审查。
- `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)`）。
- 在单元格注释中引用所有原始输入的来源。
- 对于没有用户指定样式的新财务模型，对硬编码输入使用蓝色文本，对公式使用黑色，对内部工作簿链接使用绿色，对外部链接使用红色，对需要注意的关键假设使用黄色填充。

## 投资银行布局
如果电子表格是 IB 风格的模型（LBO、DCF、三张报表、估值）：
- 总计应直接对上方的范围求和。
- 隐藏网格线并在相关列上方使用水平边框。
- 部分标题应为带有深色填充和白色文本的合并单元格。
- 数值数据的列标签应右对齐；行标签应左对齐。
- 在其父行项下缩进子指标。