office-excel git:20260720.5237f6cA

Immutable. This exact content is served forever at /api/v1/blob/6f87ea2c45bf5ed6.

---
name: office-excel
description: Excel 电子表格读写与编辑最佳实践 — 用 xlsx_read/xlsx_write/xlsx_edit 处理 .xlsx 时遵守的公式、数字格式与可维护性纪律
triggers: [xlsx, excel, 表格, 电子表格, 工作表, 单元格, spreadsheet, workbook, sheet]
---

# Office Excel（.xlsx 读写纪律）

> 改编自 anthropics/skills xlsx（Apache 2.0）。

用本插件（`xlsx_read` / `xlsx_write` / `xlsx_edit`）交付 Excel 文件时，遵守以下纪律。

## 1. 能用公式绝不硬编码计算值

- 汇总、合计、比率一律写公式（`{ formula: 'SUM(B2:B10)' }`），不要把算好的结果写死。
- 交付的表格必须保持**动态可重算**：用户改了源数据，合计列应自动更新。写死的数字会在源数据变更后悄悄变成错误答案。
- 公式在 `xlsx_read` 中以 `=SUM(...)` 原文显示，交付前读回自查一遍公式是否正确。

## 2. 零公式错误纪律

`#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` 一个都不允许出现在交付物里。常见成因与预防：

- **行列从 1 开始**：`A1` 是第一个单元格，不存在第 0 行/第 0 列。越界引用直接 `#REF!`。
- **跨 sheet 引用**用 `Sheet1!A1` 语法；sheet 名含空格或特殊字符时用单引号 `'My Sheet'!A1`。
- **除零检查**：除法公式先确认分母列无空值/零值，必要时 `IF(B2=0, 0, A2/B2)`。
- **类型一致**：文本列与数字列混算得 `#VALUE!`；写入时不要把数字写成带引号的字符串。
- **函数名拼写**：`#NAME?` 几乎都是函数名拼错或用了不存在的函数。

## 3. 数字格式约定（用 number_formats 设置）

- 货币：`$#,##0`（或 `¥#,##0`）
- 百分比：`0.0%`
- 倍数：`0.0x`
- 负数用括号表示：`#,##0;(#,##0)`
- **年份作为文本**写入（如 `'2024`），防止被加千分位显示成 `2,024`

## 4. 假设参数放独立单元格

- 增长率、折扣率、汇率等假设值单独放一个单元格，公式引用它：`=B5*(1+$B$6)`，而不是 `=B5*1.05`。
- 用 `$B$6` 绝对引用锁定假设单元格，下拉填充时不会漂移。
- 这样用户改假设即可全表重算，不用改任何公式。

## 5. 修改已有模板时沿用其既有约定

- 用 `xlsx_read` 先看清原文件的表头、格式、公式风格，再动手。
- 严格沿用模板自己的数字格式、列宽、命名习惯——**不把自己的风格强加进去**。
- 只改该改的单元格（`xlsx_edit` 的 `update_cells` / `append_rows`），不要整体重写文件。