# XLSX

> 当电子表格是主要输入或交付物时必须使用本技能。适用于打开、读取、清洗、修复、编辑或创建 .xlsx、.xlsm、.xltx、.csv、.tsv，包括中文销售台账、预算表、排期表、数据清洗、补公式、格式化、图表和模板更新。用户只说“下载目录里那个表”“把脏 CSV 整成 Excel”也应触发。若主要产物是 Word、HTML、独立 Python 脚本、数据库流水线或 Google Sheets API，则不要触发。

- Skill: `marcelleon/xlsx` (Agent Skill, multi-file: 53 files)
- Install (CLI): `npx skillmds@latest add marcelleon/xlsx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcelleon/xlsx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: Proprietary. LICENSE.txt has complete terms
- Author: MarcelLeon (https://skillmd.com/u/marcelleon)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/marcelleon/xlsx

---


# XLSX 创建、编辑与分析

| 任务 | 推荐工具 |
| --- | --- |
| 公式、样式、结构 | `openpyxl` |
| 批量数据读写 | `pandas` |
| 快速浏览内容 | `markitdown file.xlsx` |
| 同时读取公式和值 | 分别用默认模式和 `data_only=True` 加载 |

`openpyxl`、`pandas`、`markitdown` 通常已预装。先直接使用，只有导入失败时才安装。脚本路径均相对于本 Skill 目录。

## 中文场景 few-shot

**输入：**“下载目录里的销售台账.xlsx 帮我补毛利率、按区域汇总，再做一张趋势图。”

**执行：**先识别原表字段、输入单元格和既有样式；用公式生成毛利率，用汇总表和原生图表呈现趋势；回算后检查公式错误和关键数字。

**输入：**“把这份错位的 CSV 整成下周继续填报的运营模板。”

**执行：**用 pandas 纠正表头和脏行，输出中文列名清晰的 `.xlsx`；添加“可编辑区域”说明和一行真实格式示例，但不在已有业务表中擅自插入示例数据。

## 每个交付物都要满足

- 用户或既有模板的字段名、sheet 名、格式和公式约定优先。
- 新建中文表格时选用目标环境可用的专业中文字体；已有表格必须继承原字体。
- 公式必须写入 Excel，不把 Python 计算结果硬编码成静态值。
- 所有假设和硬编码数字应在可见位置说明来源；用户提供的数据明确标注“来源：用户提供”。
- 用户要继续填写的空模板需要短图例和一行格式示例；编辑已有文件时不要擅自添加。
- 交付前 `recalc.py` 必须达到零公式错误。

## 通用工作流

1. 快速浏览所有 sheet、表头、合并单元格、公式和输入样式。
2. 明确哪些是输入、公式、跨表引用和外部链接。
3. 先写 2–3 个代表性公式并核对引用，再批量填充。
4. 保存后执行回算。
5. 检查公式正确性、格式、图表范围和中文显示。

## 公式回算

`openpyxl` 只写公式字符串，不产生缓存值。含公式文件必须运行：

```bash
python scripts/recalc.py output.xlsx
```

脚本会原地改写工作簿，并输出 JSON：

- `status: success`：公式已回算且没有已识别错误。
- `status: errors_found`：进程仍可能退出 0，必须读取 `total_errors` 和 `error_summary`。
- 出现 `error` 字段而不是 `status`：没有完成回算。

绿色回算只证明公式能求值，不证明业务引用正确。抽查至少 2–3 个关键公式的行列和边界。

## 公式兼容性

优先使用 `SUMIFS`、`INDEX`、`MATCH`、`IFERROR`、`SUMPRODUCT` 等兼容函数。

以下函数需要 `_xlfn.` 前缀：`TEXTJOIN`、`CONCAT`、`IFS`、`SWITCH`、`MAXIFS`、`MINIFS`。

不要使用当前校验链无法可靠回算的动态数组函数：

- `XLOOKUP`
- `XMATCH`
- `SORT`
- `FILTER`
- `UNIQUE`
- `SEQUENCE`

查找使用 `INDEX`/`MATCH`，排序、筛选和去重在 Python 中完成后再写入单元格。

## openpyxl 高风险点

- 同时拿公式和值需要加载两次；一次加载无法兼得。
- `data_only=True` 的工作簿不能保存，否则公式会被静态值替换。
- 刚由 openpyxl 写出的公式，用 `data_only=True` 读取通常是 `None`；先回算。
- 合并单元格只能写左上角锚点。
- `.xlsm` 必须使用 `keep_vba=True`，否则宏会丢失。
- 含空格的 sheet 名在公式中必须加单引号，如 `='参数 输入'!$B$5`。
- 修改现有文件时先识别其输入颜色/填充，只写指定区域，不覆盖原公式。

### 外部链接

公式如 `='[1]Returns Analysis'!$B$2` 指向外部文件。openpyxl 保存后可能丢失原缓存值，LibreOffice 无法解析时会写入 `#NAME?` 并删除链接。

遇到外部链接时：

1. 在修改前读取并保存原缓存值。
2. 不要直接覆盖原文件。
3. 明确说明外部依赖是否可用。
4. 只有用户接受链接丢失风险时才使用 `recalc.py --force`。

## 财务模型默认约定

既有模板或用户要求优先；否则：

- 蓝字：硬编码输入和情景变量。
- 黑字：公式。
- 绿字：同工作簿跨表引用。
- 红字：外部文件引用。
- 黄底：关键假设或待填写单元格。
- 百分比存为小数，`0.15` 显示为 `15.0%`。
- 负数用括号，零显示为 `-`，倍数显示 `0.0x`。
- 每个假设放在独立单元格并由公式引用，不把 `1.05` 写死在公式里。

## 最终验收

```bash
python scripts/recalc.py output.xlsx
```

随后检查：

- `total_errors == 0`
- 关键公式引用正确
- sheet 名、列名、日期和数值格式符合用户要求
- 图表数据范围和图例正确
- 中文字符、列宽、冻结窗格、筛选和打印区域可用

## 依赖

`openpyxl` · `pandas` · `markitdown` · LibreOffice